qubalab.objects package

qubalab.objects.classification module

class qubalab.objects.classification.Classification(name: str, color: tuple[int, int, int] | None = None)

Bases: object

Simple class to store the name and color of a classification.

Parameters:

  • name – the name of the classification

  • color – the RGB color (each component between 0 and 255) of the classification. Can be None to use a random color

property color: tuple[int, int, int]

The color of the classification.

static get_cached_classification(name: str, color: tuple[int, int, int] | None = None) → Classification

Return a classification by looking at an internal cache.

If no classification with the provided name is present in the cache, a new classification is created and the cache is updated.

This is useful if you want to avoid creating multiple classifications with the same name and use only one instead.

Parameters:

  • name – the name of the classification (can be None)

  • color – the RGB color (each component between 0 and 255) of the classification. Can be None to use a random color. This is only used if the cache doesn’t already contain a classification with the provided name

Returns:

a classification with the provided name, but not always with the provided color if a classification with the same name already existed in the cache. If the provided name is None, None is also returned

property name: str

The name of the classification.

qubalab.objects.draw module

qubalab.objects.draw.draw_geometry(image_size: tuple[int, int], drawing_context: Draw, geometry: Geometry, value: int)

Draw the provided Shapely geometry with the provided drawing context using the provided value.

Parameters:

  • image_size – the size of the image to draw on

  • drawing_context – the drawing context to use

  • geometry – the geometry to draw

  • value – the value to use when drawing

qubalab.objects.geojson module

qubalab.objects.geojson.geojson_features_from_string(json_string: str, **kwargs) → Iterable[Feature] | Feature

Read features from a GeoJSON string.

If the string encodes a feature collection, the features themselves will be extracted.

NaNs values are allowed. However, converting a returned feature with a NaN value to a string will throw an exception.

Parameters:

  • json_string – a string representing a GeoJSON

  • kwargs – additional parameters to pass to the geojson loader

Returns:

a single or a collection of features representing the provided string

qubalab.objects.geometry module

class qubalab.objects.geometry.ImagePlane(z: int = 0, t: int = 0)

Bases: dict

An additional property of a geometry containing z and t indices.

Parameters:

  • z – the z-stack of the geometry

  • t – the time point of the geometry

qubalab.objects.geometry.add_plane_to_geometry(geometry: Geometry | Feature, z: int | None = None, t: int | None = None, preferred_geometry_key: str | None = None) → Geometry

Create a GeoJSON Geometry object with an additional ‘plane’ property containing z and t indices.

If indices are unspecified, they will be taken from the geometry’s ‘plane’ property, if present, or else z or t attributes otherwise. If z and t values cannot be found in either of these locations, defaults (z=0 and t=0) will be used instead.

The ‘plane’ property is immutable.

Parameters:

  • geometry – a GeoJSON feature or geometry. It must not be a FeatureCollection

  • z – the z-stack index this geometry should have

  • t – the timepoint this geometry should have

  • preferred_geometry_key – if the provided geometry is a feature, and this feature has a ‘extra_geometries’ property, then this parameter can be used as a key to retrieve the geometry to consider from the ‘extra_geometries’ dictionnary

Returns:

a GeoJSON Geometry containing an additional ‘plane’ property containing z and t indices

Raises:

ValueError – when the provided geometry is a FeatureCollection

qubalab.objects.image_feature module

class qubalab.objects.image_feature.ImageFeature(geometry: Geometry, classification: Classification | dict | None = None, name: str | None = None, measurements: dict[str, float] | None = None, object_type: ObjectType = ObjectType.ANNOTATION, color: tuple[int, int, int] | None = None, extra_geometries: dict[str, Geometry] | None = None, id: str | int | UUID | None = None, extra_properties: dict[str, Any] | None = None)

Bases: Feature

GeoJSON Feature with additional properties for image objects.

The added properties are:

  • A classification (defined by a name and a color).

  • A name.

  • A list of measurements.

  • A type of QuPath object (e.g. detection, annotation).

  • A color.

  • Additional geometries.

  • And any other property.

Except from the geometry and id parameters, all parameters of this constructor will be added to the list of properties of this feature (if provided).

Parameters:

  • geometry – the geometry of the feature

  • classification – the classification of this feature, or a dictionnary with the ‘name’ and ‘color’ properties defining respectively a string and a 3-long int tuple with values between 0 and 255

  • name – the name of this feature

  • measurements – a dictionnary containing measurements. Measurements with NaN values will not be added

  • object_type – the type of QuPath object this feature represents

  • color – the color of this feature

  • extra_geometries – a dictionnary containing additional geometries that represent this feature

  • id – the ID of the feature. If not provided, an UUID will be generated

  • extra_properties – a dictionnary of additional properties to add

property classification: Classification

The classification of this feature (or None if not defined).

property color: tuple[int, int, int]

The color of this feature (or None if not defined).

classmethod create_from_feature(feature: Feature) → ImageFeature

Create an ImageFeature from a GeoJSON feature.

The ImageFeature properties will be searched in the provided feature and in the properties of the provided feature.

Parameters:

feature – the feature to convert to an ImageFeature

Returns:

an ImageFeature corresponding to the provided feature

classmethod create_from_label_image(input_image: ndarray, object_type: ObjectType = ObjectType.ANNOTATION, connectivity: int = 4, scale: float = 1.0, include_labels=False, classification_names: str | dict[int, str] | None = None) → list[ImageFeature]

Create a list of ImageFeatures from a binary or labeled image.

The created geometries will be polygons, even when representing points or line.

Parameters:

  • input_image – a 2-dimensionnal binary (with a boolean type) or labeled (with a uint8 type) image containing the features to create. If a binary image is given, all True pixel values will be considered as potential features. If a labeled image is given, all pixel values greater than 0 will be considered as potential features

  • object_type – the type of object to create

  • connectivity – the pixel connectivity for grouping pixels into features (4 or 8)

  • scale – a scale value to apply to the shapes

  • include_labels – whether to include a ‘Label’ measurement in the created features

  • classification_names – if str, the name of the classification to apply to all features. if dict, a dictionnary mapping a label to a classification name

Returns:

a list of image features representing polygons present in the input image

property is_annotation: bool

Wether the QuPath object type (e.g. detection, annotation) represented by this feature is an annotation.

property is_cell: bool

Wether the QuPath object type (e.g. detection, annotation) represented by this feature is a cell.

property is_detection: bool

Wether the QuPath object type (e.g. detection, annotation) represented by this feature is a detection, cell, or tile.

property is_tile: bool

Wether the QuPath object type (e.g. detection, annotation) represented by this feature is a tile.

property measurements: dict[str, float]

The measurements of this feature.

property name: str

The name of this feature (or None if not defined).

property nucleus_geometry: Geometry

The nucleus geometry of this feature (or None if not defined). It can be defined when passed as an extra_geometry with the ‘nucleus’ key when creating an ImageFeature, by defining the ‘nucleus_geometry’ property of an ImageFeature, or when passed as a ‘nucleusGeometry’ property when creating an ImageFeature from a GeoJSON feature.

property object_type: ObjectType

The QuPath object type (e.g. detection, annotation) this feature represents or None if the object type doesn’t exist or is not recognised.

qubalab.objects.object_type module

class qubalab.objects.object_type.ObjectType(value)

Bases: Enum

Represent an object in QuPath.

ANNOTATION = 2
CELL = 5
DETECTION = 3
ROOT = 1
TILE = 4
TMA_CORE = 6