scistag.imagestag.image.Image¶

class Image(source=None, framework=None, pixel_format=None, size=None, bg_color=None, **params)[source]¶

Bases: ImageBase

SciStag’s default class for storing image data in all common pixel formats.

The data is internally either stored using the PILLOW image library’s Image class or as a classical numpy array, depending on how it was initialized. If not specified otherwise it will always the PILLOW representation as this is very well suited to visualize the data or modify it using the Canvas class.

If you want to access the data directly you can at all times call the to_pil or get_pixels function.

Usage example:

"""
Simple demo which loads an image from the web using WebStag, loads it via
ImageStag and displays it in a TKInter window.
"""

import tkinter
from PIL import ImageTk

from scistag.imagestag import Image
from scistag.tests import TestConstants
from scistag.webstag import web_fetch


def main():
    root = tkinter.Tk()
    # fetch data from web
    url = TestConstants.STAG_URL
    print(f"Loading image from {url}...")
    image_data = web_fetch(url)
    # create an image
    image = Image(image_data)
    # display it
    img = ImageTk.PhotoImage(image.to_pil())
    panel = tkinter.Label(root, image=img)
    panel.pack(side="bottom", fill="both", expand="yes")
    # run the main loop
    root.mainloop()


if __name__ == "__main__":
    main()

Parameters

source (ImageSourceTypes | None) –
The image source. Either a file name, a http URL, numpy array or one of the supported low level types. Note that the pixel source you refer, e.g. a PIl image or a numpy array might be referenced directly and modified by this object.

Files from the web are cached by default if not disabled otherwise via cache=False using WebStag’s default caching duration and size.
framework (ImsFramework) – The framework to be used if the file is loaded from disk
pixel_format (PixelFormat | None) – The pixel format - if the data was passed as np.array. RGB by default.
size (Size2DTypes | None) – The size of the new image (if no source ia passed)
bg_color (Color | None) – The background color of the new image
params – Source protocol dependent, additional loading parameters

Raises a ValueError if the image could not be loaded

Methods

`bgr_to_rgb`	Converts BGR to RGB or the otherwise round
`compute_rescaled_size_from_max_size`	Computes the new size of an image after rescaling with a given maximum width and/or height and a given original size.
`convert`	Converts the image's format
`convert_to_pil`	Converts the image to use the RAW framework which is faster if you excessively access the pixel data frequently.
`convert_to_raw`	Converts the image to use the RAW framework which is faster if you excessively access the pixel data frequently.
`copy`	Creates a copy of this image.
`cropped`	Crops a region of the image and returns it
`detect_format`	Detects the format
`encode`	Compresses the image and returns the compressed file's data as bytes object.
`from_cv2`	Creates an image from a "classic" bgr, bgra or grayscale OpenCV source.
`get_band_names`	Returns the names of the single color bands
`get_handle`	Returns the low level data handle, for example a numpy array or a PIL handle.
`get_hash`	Returns an image uniquely identifying it
`get_pixels`	Returns the image's pixel data as `np.ndarray`.
`get_pixels_bgr`	Returns the pixels and ensures they are either bgr or bgra
`get_pixels_gray`	Returns the pixels and ensures they are gray scale
`get_pixels_rgb`	Returns the pixels and ensures they are either rgb or rgba
`get_raw_data`	Returns the image's raw pixel data as flattened byte array
`get_size`	Returns the image's size in pixels
`get_size_as_size`	Returns the image's size
`is_bgr`	Returns if the current format is bgr or bgra
`is_transparent`	Returns if the image is transparent, either alpha transparent or color keyed.
`normalize_to_bgr`	Guarantees that the output will be in the BGR or BGRA format
`normalize_to_gray`	Guarantees that the output will be grayscale
`normalize_to_rgb`	Guarantees that the output will be in the RGB or RGBA format
`resize`	Resizes the image to given resolution (modifying this image directly)
`resized`	Returns an image resized to given resolution
`resized_ext`	Returns a resized variant of the image with many configuration possibilities.
`save`	Saves the image to disk
`split`	Returns the single bands as single channels.
`to_ascii`	Converts the image to ASCII, e.g.
`to_canvas`	Converts the image to a canvas (if possible)
`to_cv2`	Converts the pixel data from the current format to it's counter type in OpenCV
`to_ipython`	Converts the image to it's IPython representation, e.g. to allow
`to_jpeg`	Encodes the image as jpeg.
`to_pil`	Converts the image to a PIL image object
`to_png`	Encodes the image as png.

Attributes

`__array_interface__`	Conversion to numpy representation
`__dict__`
`__doc__`
`__module__`
`__weakref__`	list of weak references to the object (if defined)
`size`	Returns the image's size in pixels
`width`	The image's width in pixels
`height`	The image's height in pixels
`framework`	The framework being used.
`_pil_handle`	The PILLOW handle (if available)
`_pixel_data`	The pixel data (if available) as numpy array
`pixel_format`	The base format (rgb, rbga, bgr etc.)

__setattr__(key, value)[source]¶: Implement setattr(self, name, value).

_init_as_cv2(source)[source]¶

Initializes the image from a numpy array and assuming OpenCV’s BGR / BGRA color channel order

Parameters: source (ndarray) – The data source

_init_as_pil(source)[source]¶

Initializes the image as PIL image

Parameters: source – The data source

classmethod _pixel_data_from_source(source)¶

Loads an arbitrary source and returns it as pixel data

Parameters: source (str | np.ndarray | bytes | PIL.Image.Image) – The data source. A filename, a http url, numpy array or a PIL image
Return type: np.ndarray
Returns: The pixel data

classmethod _prepare_data_source(framework, source, pixel_format, **params)[source]¶

Prepares and if necessary converts the data source to a supported format

Parameters

framework (ImsFramework) – The framework being used
source (Union[str, ndarray, bytes, Image, type]) – The source, a byte steam, a filename or a http URL
params – Source protocol dependent, additional loading parameters

Returns

The prepared source data

_repr_png_()[source]¶

PNG representation for Jupyter

Return type: bytes
Returns: The PNG data

static bgr_to_rgb(pixel_data)¶

Converts BGR to RGB or the otherwise round

Parameters: pixel_data (ndarray) – The input pixel data
Return type: ndarray
Returns: The output pixel data

compute_rescaled_size_from_max_size(max_size, org_size)[source]¶

Computes the new size of an image after rescaling with a given maximum width and/or height and a given original size.

Parameters

max_size – The maximum size or a tuple containing the maximum width, height or both
org_size (Size2D) – The original size

Return type

tuple[int, int]

Returns

The effective size in pixels

convert(target_format, bg_fill=None)[source]¶

Converts the image’s format

Parameters

target_format (PixelFormat | str) – The target format
bg_fill (Union['Color', None]) – For alpha-transparent images only: The color of the background of the new non-transparent image.

Return type

Image

Returns

Self

convert_to_pil()[source]¶

Converts the image to use the RAW framework which is faster if you excessively access the pixel data frequently.

Return type: Image

convert_to_raw()[source]¶

Converts the image to use the RAW framework which is faster if you excessively access the pixel data frequently.

Return type: Image

copy()[source]¶

Creates a copy of this image.

By default a PILLOW based image will be created

Return type: Image
Returns: A copy of this image

cropped(box)[source]¶

Crops a region of the image and returns it

Parameters: box (Union[Bounding2D, tuple[int, int, int, int], tuple[float, float, float, float], tuple[Union[Pos2D, tuple[float, float]], Union[Pos2D, tuple[float, float]]], tuple[Union[Pos2D, tuple[float, float]], Union[tuple[float, float], Size2D]]]) – The box in the form x, y, x2, y2
Return type: Image
Returns: The image of the defined subregion

classmethod detect_format(pixels, is_cv2=False)¶

Detects the format

Parameters

pixels (ndarray) – The pixels
is_cv2 – Defines if the source was OpenCV

Returns

The pixel format. See PixelFormat

encode(filetype='png', quality=90, background_color=None)[source]¶

Compresses the image and returns the compressed file’s data as bytes object.

Parameters

filetype (str | tuple[str, int]) –
The output file type. Valid types are “png”, “jpg”/”jpeg”, “bmp” and “gif”.

You can also pass the filetype and quality as a str, int tuple such as(“jpg”, 60).
quality (int) – The image quality between (0 = worst quality) and (95 = best quality). >95 = minimal loss
background_color (Color | None) – The background color to store an RGBA image as RGB image.

Return type

bytes | None

Returns

The bytes object if no error occurred, otherwise None

classmethod from_cv2(pixel_data)¶

Creates an image from a “classic” bgr, bgra or grayscale OpenCV source.

For more advanced type please use the standard constructor.

Parameters: pixel_data (ndarray) – The pixel data
Return type: Image
Returns: The image instance

get_band_names()[source]¶

Returns the names of the single color bands

Return type: list[str]
Returns: The name of the bands

get_handle()[source]¶

Returns the low level data handle, for example a numpy array or a PIL handle.

Do not use this to modify the data and be aware of the the type could change dynamically. Use method:~get_pixels or :method:`~to_pil` if you need a guaranteed type.

Return type: np.ndarray | PIL.Image.Image
Returns: The handle

get_hash()[source]¶

Returns an image uniquely identifying it

Return type: str
Returns: The image’s hash

get_pixels(desired_format=None)[source]¶

Returns the image’s pixel data as np.ndarray.

Note that manipulating the data will has no effect to the image if the internal representation is not a numpy array.

Parameters: desired_format (PixelFormat | None) – The desired output pixel format, e.g. see PixelFormat. By default the own format
Return type: np.ndarray
Returns: The numpy array containing the pixels

get_pixels_bgr()[source]¶

Returns the pixels and ensures they are either bgr or bgra

Return type: ndarray

get_pixels_gray()[source]¶

Returns the pixels and ensures they are gray scale

Return type: ndarray

get_pixels_rgb()[source]¶

Returns the pixels and ensures they are either rgb or rgba

Return type: ndarray

get_raw_data()[source]¶

Returns the image’s raw pixel data as flattened byte array

Return type: bytes
Returns: The image’s pixel data

get_size()[source]¶

Returns the image’s size in pixels

Return type: tuple[int, int]
Returns: The size as tuple (width, height)

get_size_as_size()[source]¶

Returns the image’s size

Return type: Size2D
Returns: The size

is_bgr()[source]¶

Returns if the current format is bgr or bgra

Return type: bool
Returns: True if the image currently in bgr or bgra format

is_transparent()[source]¶

Returns if the image is transparent, either alpha transparent or color keyed.

Return type: bool
Returns: True if the image is transparent

classmethod normalize_to_bgr(pixels, input_format=PixelFormat.RGB, keep_gray=False)¶

Guarantees that the output will be in the BGR or BGRA format

Parameters

pixels (ndarray) – The pixel data
input_format (PixelFormat) – The input format representation, e.g. see PixelFormat
keep_gray – Defines if single channel formats shall be kept intact. False by default.

Return type

ndarray

Returns

The BGR image as numpy array. If keep_gray was set and the input was single channeled the original.

classmethod normalize_to_gray(pixels, input_format=PixelFormat.RGB)¶

Guarantees that the output will be grayscale

Parameters

pixels (ndarray) – The pixel data np.ndarray
input_format (PixelFormat) – The input format representation, e.g. see PixelFormat

Return type

ndarray

Returns

The grayscale image as np.ndarray

classmethod normalize_to_rgb(pixels, input_format=<enum 'PixelFormat'>, keep_gray=False)¶

Guarantees that the output will be in the RGB or RGBA format

Parameters

pixels (ndarray) – The pixel data as np.ndarray
input_format (PixelFormat) – The input format representation, e.g. see PixelFormat
keep_gray – Defines if single channel formats shall be kept intact. False by default.

Return type

ndarray

Returns

The RGB image as numpy array. If keep_gray was set and the input was single channeled the original.

resize(size, interpolation=InterpolationMethod.LANCZOS)[source]¶

Resizes the image to given resolution (modifying this image directly)

Parameters

size (Union[tuple[float, float], Size2D]) – The new size
interpolation (InterpolationMethod) – The interpolation method.

resized(size, interpolation=InterpolationMethod.LANCZOS)[source]¶

Returns an image resized to given resolution

Parameters

size (Union[tuple[float, float], Size2D]) – The new size
interpolation (InterpolationMethod) – The interpolation method.

Return type

Image

resized_ext(size=None, max_size=None, keep_aspect=False, target_aspect=None, fill_area=False, factor=None, interpolation=InterpolationMethod.LANCZOS, background_color=Color(r=0.0, g=0.0, b=0.0, a=1.0, _rgba=(0.0, 0.0, 0.0, 1.0), _int_rgba=(0, 0, 0, 255)))[source]¶

Returns a resized variant of the image with many configuration possibilities.

Parameters

size (Size2DTypes | None) – The target size as tuple (in pixels) (optional)
max_size (Size2DTypes | tuple[int | None, int | None] | None) – The maximum width and/or height to which the image shall be scaled while keeping the aspect_ration intact. You can pass a maximum width, a maximum height or both.
keep_aspect (bool) – Defines if the aspect ratio shall be kept. if set to true the image will be zoomed or shrunk equally on both axis so it fits the target size. False by default.
target_aspect (float | None) –
If defined the image will be forced into given aspect ratio by adding “black bars” (or the color you defined in “background_color”). Common values are for example 4/3, 16/9 or 21/9.

Note that this does NOT change the aspect ratio of the real image itself. If you want to change this just call this function with the desired “size” parameter.

It will always preserve the size of the axis to which no black bares are added, so e.g. converting an image from 4:3 to 16:9 resulting in black bars on left and right side the original height will be kept.

Converting an image from 16:9 to 4:3 on the other hand where black bars are added on top and bottom the width will be kept. Overrides “size”.
fill_area (bool) –
Defines if the whole area shall be filled with the original image.

False by default. Only evaluated if keep_aspect is True as well as otherwise a simple definition of “size” would anyway do the job.
factor (float | tuple[float, float] | None) –
Scales the image by given factor. Overwrites size.

Can be combined with target_aspect. None by default. Overrides “size”.
interpolation (InterpolationMethod) – The interpolation method.
background_color – The color which shall be used to fill the empty area, e.g. when a certain aspect ratio is enforced.

Return type

Image

save(target, **params)[source]¶

Saves the image to disk

Parameters

target (str) – The storage target such as a filename
quality (int) – The image quality between (0 = worst quality) and (95 = best quality). >95 = minimal loss
params – See encode()

Returns

True on success

split()[source]¶

Returns the single bands as single channels.

In difference to get_pixels() the data is reshaped to channel x height x width so each channel can be handled separately.

Single band channels (such as gray) also guarantee a three dimensional shape. (1 x Height x Width)

Return type: list[ndarray]
Returns: The single channels.

to_ascii(max_width=80, **params)[source]¶

Converts the image to ASCII, e.g. to add a coarse preview to a log file… or just 4 fun ;-).

Parameters: max_width – The maximum count of characters per row
Return type: str
Returns: The ASCII image as string

to_canvas()[source]¶

Converts the image to a canvas (if possible)

Return type: Canvas
Returns: The canvas handle

to_cv2()[source]¶

Converts the pixel data from the current format to it’s counter type in OpenCV

Return type: ndarray
Returns: The OpenCV numpy data

to_ipython(filetype='png', quality=90, **params)[source]¶

Converts the image to it’s IPython representation, e.g. to allow: faster visualization via using JPG.

Parameters

filetype – The file type such as “png” or “jpeg”
quality (int) – The compression level
params – Advanced encoding params. See encode()

Return type

Any

Returns

The IPython.display.Image

to_jpeg(quality=90, **params)[source]¶

Encodes the image as jpeg.

Parameters

quality (int) – The compression grade.
params – Advanced encoding params. See encode()

Return type

bytes | None

Returns

The image as bytes object

to_pil()[source]¶

Converts the image to a PIL image object

Return type: Image
Returns: The PIL image

to_png(quality=90, **params)[source]¶

Encodes the image as png.

Parameters

quality (int) – The compression grade (no impact on quality).
params – Advanced encoding params. See encode()

Return type

bytes | None

Returns

The image as bytes object

_pil_handle: PIL.Image.Image | None¶: The PILLOW handle (if available)

_pixel_data: np.ndarray | None¶: The pixel data (if available) as numpy array

framework¶: The framework being used. ImsFramework.PIL by default.

height¶: The image’s height in pixels

pixel_format: PixelFormat¶: The base format (rgb, rbga, bgr etc.)

property size: tuple[int, int]¶

Returns the image’s size in pixels

Return type: tuple[int, int]
Returns: The size as tuple (width, height)

width¶: The image’s width in pixels