qubalab.images package

qubalab.images.aicsimageio_server module

qubalab.images.icc_profile_server module

class qubalab.images.icc_profile_server.IccProfileServer(base_server: ImageServer, icc_profile: bytes | ImageCmsProfile | CmsProfile | ImageCmsTransform | None = None, **kwargs)

Bases: WrappedImageServer

Wrap an ImageServer and apply an ICC Profile to the pixels, if possible.

If no ICC Profile is provided, an attempt is made to read the profile from the image using PIL. This isn’t guaranteed to succeed. To find out if it was successful, test whether self.icc_transform is not None.

See http://www.andrewjanowczyk.com/application-of-icc-profiles-to-digital-pathology-images/ for a blog post describing where this may be useful, and providing further code.

Closing this server will close the wrapped server. The metadata of this server is equivalent to the metadata of the wrapped server.

Parameters:

  • base_server – the server to wrap

  • icc_profile – the ICC profile to apply to the wrapped image server. If omitted, an attempt is made to read the profile from the image. If not successful, a warning will be logged.

  • resize_method – the resampling method to use when resizing the image for downsampling. Bicubic by default

property icc_transform: ImageCmsTransform

Get the transform used to apply the ICC profile.

If this is None, then the server simply returns the original pixels unchanged.

qubalab.images.image_server module

class qubalab.images.image_server.ImageServer(resize_method: Resampling = Resampling.BICUBIC)

Bases: ABC

An abtract class to read pixels and metadata of an image.

An image server must be closed (see the close() function) once no longer used.

Parameters:

resize_method – the resampling method to use when resizing the image for downsampling. Bicubic by default

abstract close()

Close this image server.

This should be called whenever this server is not used anymore.

level_to_dask(level: int = 0, chunk_width: int = 1024, chunk_height: int = 1024) → Array

Return a dask array representing a single resolution of the image.

Pixels of the returned array can be accessed with the following order: (t, c, z, y, x). There may be less dimensions for simple images: for example, an image with a single timepoint and a single z-slice will return an array of dimensions (c, y, x). However, there will always be dimensions x and y, even if they have a size of 1.

Subclasses of ImageServer may override this function if they can provide a faster implementation.

Parameters:

  • level – the pyramid level (0 is full resolution). Must be less than the number of resolutions of the image

  • chunk_width – the image will be read chunk by chunk. This parameter specifies the size of the chunks on the x-axis

  • chunk_height – the size of the chunks on the y-axis

Returns:

a dask array containing all pixels of the provided level

Raises:

ValueError – when level is not valid

property metadata: ImageMetadata

The image metadata.

read_region(downsample: float = 1.0, region: Region2D | tuple[int, ...] | None = None, x: int = 0, y: int = 0, width: int = -1, height: int = -1, z: int = 0, t: int = 0) → ndarray

Read pixels from any arbitrary image region, at any resolution determined by the downsample.

This method can be called in one of two ways: passing a region (as a Region2D object or a tuple of integers), or passing x, y, width, height, z and t parameters separately. The latter can be more convenient and readable when calling interactively, without the need to create a region object. If a region is passed, the other parameters (except for the downsample) are ignored.

Important: coordinates and width/height values are given in the coordinate space of the full-resolution image, and the downsample is applied before reading the region. This means that, except when the downsample is 1.0, the width and height of the returned image will usually be different from the width and height passed as parameters.

Parameters:

  • downsample – the downsample to use

  • region – a Region2D object or a tuple of integers (x, y, width, height, z, t)

  • x – the x coordinate of the region to read

  • y – the y coordinate of the region to read

  • width – the width of the region to read

  • height – the height of the region to read

  • z – the z index of the region to read

  • t – the t index of the region to read

Returns:

a 3-dimensional numpy array containing the requested pixels from the 2D region. The [c, y, x] index of the returned array returns the channel of index c of the pixel located at coordinates [x, y] on the image

Raises:

ValueError – when the region to read is not specified

to_dask(downsample: float | Iterable[float] | None = None) → Array | tuple[Array, ...]

Convert this image to one or more dask arrays, at any arbitary downsample factor.

It turns out that requesting at an arbitrary downsample level is very slow - currently, all pixels are requested upon first compute (even for a small region), and then resized. Prefer using ImageServer.level_to_dask() instead.

Parameters:

downsample – the downsample factor to use, or a list of downsample factors to use. If None, all available resolutions will be used

Returns:

a dask array or tuple of dask arrays, depending upon whether one or more downsample factors are required

qubalab.images.labeled_server module

class qubalab.images.labeled_server.LabeledImageServer(base_image_metadata: ImageMetadata, features: Iterable[ImageFeature], label_map: dict[Classification, int] | None = None, downsample: float | None = None, multichannel: bool = False, resize_method=Resampling.NEAREST, **kwargs)

Bases: ImageServer

An ImageServer where pixel values are labels corresponding to image features (such as annotations) present on an image.

The returned image will have one timepoint and one z-stack. The size of the remaining dimensions depend on the metadata provided when creating the server — usually, the same as the ImageServer that the labeled image corresponds to.

The image will only have one resolution level; the downsample for this level may be greater than or less than 1, and consequently region requests and downsamples should be considered relative to the metadata provided at server creation, not relative to the downsampled (or upsampled) LabeledImageServer coordinates.

Parameters:

  • base_image_metadata – the metadata of the image containing the image features

  • features – the image features to draw

  • label_map – a dictionary mapping a classification to a label. The value of pixels where an image feature with a certain classification is present will be taken from this dictionnary. If not provided, each feature will be assigned a unique integer. All labels must be greater than 0

  • downsample – the downsample to apply to the image. Can be omitted to use the full resolution image

  • multichannel – if False, the image returned by this server will have a single channel where pixel values will be unsigned integers representing a label (see the label_map parameter). If True, the number of channels will be equal to the highest label value + 1, and the pixel located at (c, y, x) is a boolean indicating if an annotation with label c is present on the pixel located at (x, y)

  • resize_method – the resampling method to use when resizing the image for downsampling. Nearest neighbour by default for labeled images.

Raises:

ValueError – when a label in label_map is less than or equal to 0

close()

Close this image server.

This should be called whenever this server is not used anymore.

qubalab.images.openslide_server module

class qubalab.images.openslide_server.OpenSlideServer(path: str, strip_alpha=True, single_channel=False, limit_bounds=True, **kwargs)

Bases: ImageServer

An image server that relies on OpenSlide (https://openslide.org/) to read RGB images.

This server may only be able to detect the full resolution of a pyramidal image.

OpenSlide provides some properties to define a rectangle bounding the non-empty region of the slide (see https://openslide.org/api/python/#standard-properties). If such properties are found, only this rectangle will be read (but note that this behaviour was not properly tested).

Parameters:

  • path – the local path to the image to open

  • strip_alpha – whether to strip the alpha channel from the image

  • single_channel – whether to keep only the first channel of the image

  • limit_bounds – whether to only consider a rectangle bounding the non-empty region of the slide, if such rectangle is defined in the properties of the image

  • resize_method – the resampling method to use when resizing the image for downsampling. Bicubic by default

close()

Close this image server.

This should be called whenever this server is not used anymore.

qubalab.images.qupath_server module

class qubalab.images.qupath_server.QuPathServer(gateway: JavaGateway | None = None, qupath_server: JavaObject | None = None, pixel_access: str = 'base_64', **kwargs)

Bases: ImageServer

An ImageServer that communicates with a QuPath ImageServer through a Gateway.

Closing this server won’t close the underlying QuPath ImageServer.

Parameters:

  • gateway – the gateway between Python and QuPath. If not specified, the default gateway is used

  • qupath_server – a Java object representing the QuPath ImageServer. If not specified, the currently opened in QuPath ImageServer is used

  • pixel_access – how to send pixel values from QuPath to Python. Can be ‘base_64’ to convert pixels to base 64 encoded text, ‘bytes’ to to convert pixels to bytes, or ‘temp_files’ to use temporary files

  • resize_method – the resampling method to use when resizing the image for downsampling. Bicubic by default

Raises:

ValueError – when pixel_access has an unexpected value

close()

Close this image server.

This should be called whenever this server is not used anymore.

qubalab.images.region_2d module

class qubalab.images.region_2d.Region2D(x: int = 0, y: int = 0, width: int = -1, height: int = -1, z: int = 0, t: int = 0)

Bases: object

Simple data class to represent the bounding box for a region in 2D.

Parameters:

  • x – the top left x-coordinate of the bounding box

  • y – the top left y-coordinate of the bounding box

  • width – the width of the bounding box

  • height – the height of the bounding box

  • z – the z-slice index of the bounding box

  • t – the time point index of the bounding box

downsample_region(downsample: float) → Region2D

Downsample the bounding box of this region on the x and y axis.

This can be used to convert coordinates from (for example) the full image resolution to a different pyramidal level.

Parameters:

downsample – the downsample to apply to this region

Returns:

a Region2D downsampled by the provided factor

Raises:

ValueError – when downsample is 0

property geometry: Geometry

A shapely geometry describing the x/y coordinates of the region.

height: int = -1
scale_region(scale_factor: float) → Region2D

Scale the bounding box of this region on the x and y axis.

Parameters:

scale_factor – the scale factor to apply to this region

Returns:

a Region2D scaled by the provided factor

Raises:

ValueError – when scale_factor is 0

t: int = 0
width: int = -1
x: int = 0
y: int = 0
z: int = 0

qubalab.images.utils module

qubalab.images.utils.base64_to_image(data: str, is_rgb: bool, shape: ImageShape | None = None) → ndarray

Read the provided string with the Base64 format and convert it to a numpy array representing an image.

Parameters:

  • uri – a text with the Base64 format. This must represent a 2-dimensionnal or 3-dimensionnal (with a channel axis) image

  • is_rgb – whether the expected image should have the RGB format

  • shape – the shape of the image to open. This will be used to reorder axes. Can be None to not reorder axes

Returns:

a numpy array representing the input image. If shape is defined, this function will try to set its dimensions to (c, y, x), but this may not always be the case if two dimensions have the same number of elements

qubalab.images.utils.bytes_to_image(uri: {<class 'bytes'>, <class 'str'>}, is_rgb: bool, shape: ~qubalab.images.metadata.image_shape.ImageShape | None = None) → ndarray

Read the provided bytes (or URI pointing to a binary file) and convert them to a numpy array representing an image.

Parameters:

  • uri – an URI pointing to a binary file, or an array of bytes. This must represent a 2-dimensionnal or 3-dimensionnal (with a channel axis) image

  • is_rgb – whether the expected image should have the RGB format

  • shape – the shape of the image to open. This will be used to reorder axes. Can be None to not reorder axes

Returns:

a numpy array representing the input image. If shape is defined, this function will try to set its dimensions to (c, y, x), but this may not always be the case if two dimensions have the same number of elements

qubalab.images.wrapped_image_server module

class qubalab.images.wrapped_image_server.WrappedImageServer(base_server: ImageServer, **kwargs)

Bases: ImageServer

Abstract class for an ImageServer that wraps another ImageServer, e.g. to transform the image in some way.

Closing this server will close the wrapped server. The metadata of this server is equivalent to the metadata of the wrapped server.

Parameters:

  • base_server – the server to wrap

  • resize_method – the resampling method to use when resizing the image for downsampling. Bicubic by default

property base_server: ImageServer

Get the wrapped server.

close()

Close this image server.

This should be called whenever this server is not used anymore.

Subpackages