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>)[source]
property images: Sequence[QuPathProjectImageEntry]

project images

Return type

Sequence[QuPathProjectImageEntry]

add_image(image_id: SimpleFileImageId, image_type: Optional[QuPathImageType] = None, *, allow_duplicates: bool = False, return_list: Literal[True]) List[QuPathProjectImageEntry][source]
add_image(image_id: SimpleFileImageId, image_type: Optional[QuPathImageType] = None, *, allow_duplicates: bool = False, return_list: Literal[False] = False) Union[QuPathProjectImageEntry, List[QuPathProjectImageEntry]]

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()[source]

verify if images are reachable

Return type

Dict[str, bool]

update_image_paths(*, try_relative=False, **rebase_kwargs)[source]

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)[source]

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

Return type

str

property path_classes: Tuple[QuPathPathClass, ...]

return path_classes stored in the project

Return type

Tuple[QuPathPathClass, ...]

property path: Path

the path to the project root

Return type

Path

save(images=True)[source]

flush changes in the project to disk

(writes path_classes and project data)

Return type

None

property name: str

project name

Return type

str

property timestamp_creation: int

system time at creation in milliseconds

Return type

int

property timestamp_modification: int

system time at modification in milliseconds

Return type

int

property version: Optional[str]

the project version. should be identical to the qupath version

Return type

Optional[str]

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)[source]
classmethod from_java(path_class)[source]

initialize a QuPathPathClass from its corresponding java PathClass

Return type

QuPathPathClass

property name: str

the name of the class

Return type

str

property id: str

the unique identifier string of the class

Return type

str

property parent: Optional[QuPathPathClass]

the parent path class of this path class

Return type

Optional[QuPathPathClass]

property origin: QuPathPathClass

the toplevel parent of this path class

Return type

QuPathPathClass

is_derived_from(parent_class)[source]

is this class derived from the parent_class

is_ancestor_of(child_class)[source]

is this class an ancestor of the child_class

property color: Optional[QuPathColor]

return the path color

Return type

Optional[QuPathColor]

property is_valid: bool

check if the path class is valid

Return type

bool

property is_derived_class: bool

check if the class is a derived path class

Return type

bool

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)[source]
property entry_id: str

the unique image entry id

Return type

str

property entry_path: Path

path to the image directory

Return type

Path

property image_name: str

the image entry name

Return type

str

property image_type: QuPathImageType

image type

Return type

QuPathImageType

property description: str

free text describing the image

Return type

str

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

Return type

_ProjectImageEntryMetadata

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()[source]

check if the image file is readable

Return type

bool

is_changed()[source]

check if image_data is changed

Raises

IOError – if image_data can’t be read

Return type

bool

save()[source]

save image entry

class paquo.images.QuPathImageType(value)[source]

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)[source]
property is_empty: bool

a hierarchy is empty if it only contains the root object

Return type

bool

no_autoflush()[source]

prevent updates to the hierarchy to trigger an internal update event

flush(invalidate_proxy_cache=False)[source]

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.

Return type

QuPathPathAnnotationObject

property annotations: PathObjectProxy[QuPathPathAnnotationObject]

all annotations provided as a flattened set-like proxy

Return type

PathObjectProxy[QuPathPathAnnotationObject]

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

convenience method for adding annotations

Return type

QuPathPathAnnotationObject

property detections: PathObjectProxy[QuPathPathDetectionObject]

all detections provided as a flattened set-like proxy

Return type

PathObjectProxy[QuPathPathDetectionObject]

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

convenience method for adding tile detections

Notes

these will be added to self.detections

Return type

QuPathPathTileObject

to_geojson()[source]

return all annotations as a list of geojson features

Return type

list

load_geojson(geojson, *, raise_on_skip=False, fix_invalid=False)[source]

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)[source]

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)[source]

internal base class for PathObjects

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

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)[source]

create a new Path Object from geojson

Return type

TypeVar(PathROIObjectType, bound= _PathROIObject)

to_geojson()[source]

convert the annotation object to geojson

Return type

dict

property path_class: Optional[QuPathPathClass]

the annotation path class

Return type

Optional[QuPathPathClass]

property path_class_probability: float

the annotation path class probability

Return type

float

update_path_class(pc, probability=nan)[source]

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

Return type

None

property locked: bool

lock state of the annotation

Return type

bool

property is_editable: bool

can the annotation be edited in the qupath UI

Return type

bool

property level: int

the annotation’s level

Return type

int

property name: Optional[str]

an optional name for the annotation

Return type

Optional[str]

property parent: Optional[PathROIObjectType]

the annotation object’s parent annotation object

Return type

Optional[TypeVar(PathROIObjectType, bound= _PathROIObject)]

property roi: BaseGeometry

the roi as a shapely shape

Return type

BaseGeometry

update_roi(geometry)[source]

update the roi of the annotation

Return type

None

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

Bases: _PathROIObject

description

an optional description for the annotation

Return type

Optional[str]

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

Bases: _PathROIObject

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

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)[source]

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()[source]

tests if a QuPathColor is valid

(there are currently no validation checks performed on __init__)

Return type

bool

to_rgb()[source]

convert to 3 * uint8 rgb tuple

Return type

Tuple[int, int, int]

to_rgba()[source]

convert to 4 * uint8 rgba tuple

Return type

Tuple[int, int, int, int]

to_mpl_rgba()[source]

convert to 4 * float rgba tuple (mpl compatible)

Return type

Tuple[float, float, float, float]

to_hex()[source]

convert to hex color. loses alpha.

Return type

str

classmethod from_hex(hex_color)[source]

convert from hex_color

Return type

QuPathColor

to_java_rgb()[source]

“convert to the java rgb integer representation used by qupath

Return type

_JClass[]

classmethod from_java_rgb(java_rgb)[source]

convert from java but ignore the alpha value in java_rgb

Return type

QuPathColor

to_java_rgba()[source]

“convert to the java argb integer representation used by qupath

Return type

_JClass[]

classmethod from_java_rgba(java_rgba)[source]

converts a java integer color into a QuPathColor instance

Return type

QuPathColor

classmethod from_any(value)[source]

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! 💖