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.SimpleURIImageProvider object>)[source]
property images

project images

Return type

Sequence[QuPathProjectImageEntry]

add_image(image_id, image_type=None, *, allow_duplicates=False)[source]

add an image to the project

Parameters
  • image_id (Any) – 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

QuPathProjectImageEntry

is_readable()[source]

verify if images are reachable

Return type

Dict[Hashable, bool]

update_image_paths(**rebase_kwargs)[source]

update image path uris if image files moved

property uri

the uri identifying the project location

Return type

str

property path_classes

return path_classes stored in the project

Return type

Tuple[QuPathPathClass, …]

property path

the path to the project root

Return type

Path

save()[source]

flush changes in the project to disk

(writes path_classes and project data)

Return type

None

property name

project name

Return type

str

property timestamp_creation

system time at creation in milliseconds

Return type

int

property timestamp_modification

system time at modification in milliseconds

Return type

int

property version

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

the name of the class

Return type

str

property id

the unique identifier string of the class

Return type

str

property parent

the parent path class of this path class

Return type

Optional[QuPathPathClass]

property origin

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

return the path color

Return type

Optional[QuPathColor]

property is_valid

check if the path class is valid

Return type

bool

property is_derived_class

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

the unique image entry id

Return type

str

property entry_path

path to the image directory

Return type

Path

property image_name

the image entry name

Return type

str

property image_type

image type

Return type

QuPathImageType

property description

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

downsample levels provided by the image

Notes

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

property metadata

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

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, *, _image_ref=None)[source]
property is_empty

a hierarchy is empty if it only contains the root object

Return type

bool

property root

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

all annotations provided as a flattened set-like proxy

Return type

_PathObjectSetProxy[QuPathPathAnnotationObject]

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

convenience method for adding annotations

Return type

QuPathPathAnnotationObject

property detections

all detections provided as a flattened set-like proxy

Return type

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

load annotations into this hierarchy from a geojson list

returns True if new objects were added, False otherwise.

Return type

bool

QuPathPathObjects

Annotations and detections are encapsulated via QuPathPathAnnotationObjects.

class paquo.pathobjects._PathROIObject(java_object)[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

~PathROIObjectType

classmethod from_geojson(geojson)[source]

create a new Path Object from geojson

Return type

~PathROIObjectType

to_geojson()[source]

convert the annotation object to geojson

Return type

dict

property path_class

the annotation path class

Return type

Optional[QuPathPathClass]

property path_class_probability

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

lock state of the annotation

Return type

bool

property is_editable

can the annotation be edited in the qupath UI

Return type

bool

property level

the annotation’s level

Return type

int

property name

an optional name for the annotation

Return type

Optional[str]

property parent

the annotation object’s parent annotation object

Return type

Optional[~PathROIObjectType]

property roi

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

Bases: paquo.pathobjects._PathROIObject

description

an optional description for the annotation

Return type

Optional[str]

class paquo.pathobjects.QuPathPathDetectionObject(java_object)[source]

Bases: paquo.pathobjects._PathROIObject

class paquo.pathobjects.QuPathPathTileObject(java_object)[source]

Bases: paquo.pathobjects.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! 💖