Paquo API

QuPathProjects

Paquo’s most used class is the QuPathProject. Through it you’re accessing images, annotation, metadata and everything that QuPath has to offer (😅 let us know if something’s missing!)

class paquo.projects.QuPathProject(path, mode='r', *, image_provider=<paquo.images.ImageProvider object>)

property images: Sequence[QuPathProjectImageEntry]

project images

add_image(image_id, image_type=None, *, allow_duplicates=False, return_list=False)

add an image to the project

Parameters:

• image_id (Union[str, Path]) – image_id pointing to the image file (with default image_provider: filename)

• image_type (Optional[QuPathImageType]) – provide an image type for the image. If not provided the user will be prompted before opening the image in QuPath.

• allow_duplicates (bool) – check if file has already been added to the project.

Return type:

Union[QuPathProjectImageEntry, List[QuPathProjectImageEntry]]

is_readable()

verify if images are reachable

Return type:

Dict[str, bool]

update_image_paths(*, try_relative=False, **rebase_kwargs)

update image path uris if image files moved

Parameters:

• try_relative (bool) – if try_relative is True, update_image_paths tries to use relative paths to resolve missing image entries. This is useful in case you move the the project together with its images directory, or in case you remount at a different location.

• **rebase_kwargs – keyword arguments are handed over to the image provider instance. The default image provider is a paquo.images.ImageProvider which uses the uri2uri keyword argument. (A mapping from old URI to new URI: Mapping[str, str])

Return type:

None

remove_image(image_entry)

Delete an image from the QuPath project.

Parameters:

image_entry (Union[QuPathProjectImageEntry, int]) – the image entry to be removed

Return type:

None

property uri: str

the uri identifying the project location

property path_classes: Tuple[QuPathPathClass, ...]

return path_classes stored in the project

property path: Path

the path to the project root

save(images=True)

flush changes in the project to disk

(writes path_classes and project data)

Return type:

None

property name: str

project name

property timestamp_creation: int

system time at creation in milliseconds

property timestamp_modification: int

system time at modification in milliseconds

property version: str | None

the project version. should be identical to the qupath version

QuPathPathClasses

Classes are used to group your annotation into (you’ve guessed it) classes. QuPathPathClasses can have names, a color and they can be children of other classes. If you want to create a new QuPathPathClass just instantiate it by providing a name and an optional color and optional parent class.

class paquo.classes.QuPathPathClass(name, color=None, parent=None, **_kwargs)

classmethod from_java(path_class)

initialize a QuPathPathClass from its corresponding java PathClass

Return type:

QuPathPathClass

property name: str

the name of the class

property id: str

the unique identifier string of the class

property parent: QuPathPathClass | None

the parent path class of this path class

property origin: QuPathPathClass

the toplevel parent of this path class

is_derived_from(parent_class)

is this class derived from the parent_class

is_ancestor_of(child_class)

is this class an ancestor of the child_class

property color: QuPathColor | None

return the path color

property is_valid: bool

check if the path class is valid

property is_derived_class: bool

check if the class is a derived path class

QuPathProjectImageEntries

Images in paquo cannot exist on their own and are always bound to a QuPathProject. You access them via QuPathProject.images() or you make a new one from a file via QuPathProject.add_image(). Images let you set a description, provide you with interfaces for metadata and properties and give you access to the various QuPath annotation and detections objects through the QuPathPathObjectHierarchy.

class paquo.images.QuPathProjectImageEntry(entry, *, _project_ref=None)

property entry_id: str

the unique image entry id

property entry_path: Path

path to the image directory

property image_name: str

the image entry name

property image_type: QuPathImageType

image type

property description: str

free text describing the image

property width

image width in pixels

property height

image height in pixels

property num_channels

number of channels in the image

property num_z_slices

number of z_slices in the image

property num_timepoints

number of time points in the image

property downsample_levels: List[Dict[str, float]]

downsample levels provided by the image

Notes

The available downsample levels can differ dependent on which image backend is used by QuPath

property metadata: _ProjectImageEntryMetadata

the metadata stored on the image as dict-like proxy

property properties

the properties stored in the image data as a dict-like proxy

property hierarchy: QuPathPathObjectHierarchy

the image entry hierarchy. it contains all annotations

property uri

the image entry uri

is_readable()

check if the image file is readable

Return type:

bool

is_changed()

check if image_data is changed

Raises:

IOError – if image_data can’t be read

Return type:

bool

save()

save image entry

class paquo.images.QuPathImageType(value)

Enum representing image types

BRIGHTFIELD_H_DAB = 'Brightfield (H-DAB)'

BRIGHTFIELD_H_E = 'Brightfield (H&E)'

BRIGHTFIELD_OTHER = 'Brightfield (other)'

FLUORESCENCE = 'Fluorescence'

OTHER = 'Other'

UNSET = 'Not set'

Note

There’s an additional paquo.images.ImageProvider class which will be introduced when paquo settles on its implementation. See Paquo Issue #13.

QuPathPathObjectHierarchy

The hierarchy is accessed via QuPathProjectImageEntry.hierarchy. It contains proxy objects that allow you to access annotations and detections, as well as importing and exporting them to geojson.

class paquo.hierarchy.QuPathPathObjectHierarchy(hierarchy=None, *, readonly=False, image_name='N/A', autoflush=True)

property is_empty: bool

a hierarchy is empty if it only contains the root object

no_autoflush()

prevent updates to the hierarchy to trigger an internal update event

flush(invalidate_proxy_cache=False)

flush changes to the hierarchy

property root: QuPathPathAnnotationObject

the hierarchy root node

This object has no roi and cannot be assigned another class. All other objects are descendants of this object if they are attached to this hierarchy.

property annotations: PathObjectProxy[QuPathPathAnnotationObject]

all annotations provided as a flattened set-like proxy

add_annotation(roi, path_class=None, measurements=None, *, path_class_probability=nan)

convenience method for adding annotations

Return type:

QuPathPathAnnotationObject

property detections: PathObjectProxy[QuPathPathDetectionObject]

all detections provided as a flattened set-like proxy

add_tile(roi, path_class=None, measurements=None, *, path_class_probability=nan)

convenience method for adding tile detections

Return type:

QuPathPathTileObject

Notes

these will be added to self.detections

to_geojson()

return all annotations as a list of geojson features

Return type:

list

load_geojson(geojson, *, raise_on_skip=False, fix_invalid=False)

load annotations into this hierarchy from a geojson list

returns True if new objects were added, False otherwise.

Return type:

bool

to_ome_xml(prefix='paquo', fill_alpha=0.0)

return all annotations in ome xml format

Return type:

str

QuPathPathObjects

Annotations and detections are encapsulated via QuPathPathAnnotationObjects.

class paquo.pathobjects._PathROIObject(java_object, *, update_callback=None)

internal base class for PathObjects

classmethod from_shapely(roi, path_class=None, measurements=None, *, path_class_probability=nan)

create a Path Object from a shapely shape

Parameters:

• roi (BaseGeometry) – a shapely shape as the region of interest of the annotation

• path_class (Optional[QuPathPathClass]) – a paquo QuPathPathClass to mark the annotation type

• measurements (Optional[dict]) – dict holding static measurements for annotation object

• path_class_probability (float) – keyword only argument defining the probability of the class (default NaN)

Return type:

TypeVar(PathROIObjectType, bound= _PathROIObject)

classmethod from_geojson(geojson)

create a new Path Object from geojson

Return type:

TypeVar(PathROIObjectType, bound= _PathROIObject)

to_geojson()

convert the annotation object to geojson

Return type:

dict

property path_class: QuPathPathClass | None

the annotation path class

property path_class_probability: float

the annotation path class probability

update_path_class(pc, probability=nan)

updating the class or probability has to be done via this method

Return type:

None

property locked: bool

lock state of the annotation

property is_editable: bool

can the annotation be edited in the qupath UI

property level: int

the annotation’s level

property name: str | None

an optional name for the annotation

property parent: PathROIObjectType | None

the annotation object’s parent annotation object

property roi: BaseGeometry

the roi as a shapely shape

update_roi(geometry)

update the roi of the annotation

Return type:

None

class paquo.pathobjects.QuPathPathAnnotationObject(java_object, *, update_callback=None)

Bases: _PathROIObject

description

an optional description for the annotation

class paquo.pathobjects.QuPathPathDetectionObject(java_object, *, update_callback=None)

Bases: _PathROIObject

class paquo.pathobjects.QuPathPathTileObject(java_object, *, update_callback=None)

Bases: QuPathPathDetectionObject

QuPathColor

Colors in QuPath are represented as non-human-friendly integers. QuPathColor provides a nicer interface to allow more intuitive color handling.

class paquo.colors.QuPathColor(red: int, green: int, blue: int, alpha: int = 255)

color representation in paquo

>>> c = QuPathColor(128, 128, 160, alpha=240)

red: int

Alias for field number 0

green: int

Alias for field number 1

blue: int

Alias for field number 2

alpha: int

Alias for field number 3

is_valid()

tests if a QuPathColor is valid

(there are currently no validation checks performed on __init__)

Return type:

bool

to_rgb()

convert to 3 * uint8 rgb tuple

Return type:

Tuple[int, int, int]

to_rgba()

convert to 4 * uint8 rgba tuple

Return type:

Tuple[int, int, int, int]

to_mpl_rgba()

convert to 4 * float rgba tuple (mpl compatible)

Return type:

Tuple[float, float, float, float]

to_hex()

convert to hex color. loses alpha.

Return type:

str

classmethod from_hex(hex_color)

convert from hex_color

Return type:

QuPathColor

to_java_rgb()

“convert to the java rgb integer representation used by qupath

Return type:

_JClass[]

classmethod from_java_rgb(java_rgb)

convert from java but ignore the alpha value in java_rgb

Return type:

QuPathColor

to_java_rgba()

“convert to the java argb integer representation used by qupath

Return type:

_JClass[]

classmethod from_java_rgba(java_rgba)

converts a java integer color into a QuPathColor instance

Return type:

QuPathColor

classmethod from_any(value)

try creating a QuPathColor from all supported types

Return type:

QuPathColor

And more…

If anything is not documented and you would love to know more about it, open an issue and let us know! We’re happy to provide more documentation and clear things up! 💖