Annotations I/O

Reading Annotations

Functions for reading different annotation types

pathology_image_features.ann_io.read.check_ext(allowed_exts: list | None = None)

Decorator function for checking if input file has correct extensions for a given reader.

Parameters:

allowed_exts (Union[list,None], optional) – List of allowed file extensions, defaults to None

pathology_image_features.ann_io.read.check_path(func)

Decorator function for checking if input file paths in a function exist

Parameters:

func (None) – Function which takes a filepath as input

pathology_image_features.ann_io.read.read_aperio(ann_path: str) → _ElementTree

Read annotations in Aperio ImageScope format

Parameters:

ann_path (str) – Path to annotation file

Returns:

Read annotations in original format

Return type:

Union[list,dict]

pathology_image_features.ann_io.read.read_geojson(ann_path: str) → list | dict

Read annotations in GeoJSON format

For more details on this schema, see: https://geojson.org/

Parameters:

ann_path (str) – Path to annotation file

Returns:

Read annotations in original format

Return type:

Union[list,dict]

pathology_image_features.ann_io.read.read_histomics(ann_path: str) → list | dict

Read annotations in Histomics/large-image format

For more details on this schema, see: https://girder.github.io/large_image/annotations.html

Parameters:

ann_path (str) – Path to annotations file (.json extension)

Returns:

Read annotations in original format

Return type:

Union[list,dict]

pathology_image_features.ann_io.read.read_parquet(ann_path: str) → list | dict

Read annotations in Parquet format

Parameters:

ann_path (str) – Path to annotation file

Returns:

Read annotations in original format

Return type:

Union[list,dict]

Converting Annotations

Functions for converting from one annotation format to another

Steps:

• Convert to GeoJSON (if not already GeoJSON)

• Convert GeoJSON to desired format

pathology_image_features.ann_io.convert.aperio_to_geojson(xml_tree) → list | dict

Converting Aperio ImageScope formatted annotations to GeoJSON

Parameters:

xml_tree (None) – An XML E-Tree that is the output of read_aperio

Returns:

A list of GeoJSON FeatureCollections for each Annotation

Return type:

Union[list,dict]

pathology_image_features.ann_io.convert.aperio_to_histomics(xml_tree: _ElementTree) → list | dict

Converting Aperio ImageScope formatted annotations to Histomics

Parameters:

xml_tree (_type_) – XML ETree object containing annotations

Returns:

One or more Histomics formatted annotation layers

Return type:

Union[list,dict]

pathology_image_features.ann_io.convert.geojson_to_aperio(anns: list | dict) → _ElementTree

Converting GeoJSON formatted annotations to Aperio ImageScope format

Parameters:

anns (Union[list,dict]) – One or more GeoJSON annotations

pathology_image_features.ann_io.convert.geojson_to_histomics(anns: list | dict) → list | dict

Converting GeoJSON formatted annotations to Histomics/large-image

Parameters:

anns (Union[list,dict]) – One or more GeoJSON formatted annotations

Returns:

List or single Histomics formatted annotation

Return type:

Union[list,dict]

pathology_image_features.ann_io.convert.histomics_to_aperio(anns: list | dict) → _ElementTree

Converting Histomics/large-image formatted annotations to Aperio ImageScope

Parameters:

anns (Union[list,dict]) – One or more annotations in Histomics/large-image format

pathology_image_features.ann_io.convert.histomics_to_geojson(anns: list | dict) → list | dict

Converting Histomics/large-image formatted annotations to GeoJSON

Parameters:

anns (Union[list,dict]) – One or more Histomics/large-image formatted annotations

Returns:

Same annotations but in GeoJSON format

Return type:

Union[list,dict]

Writing Annotations

Functions for writing different annotation types

pathology_image_features.ann_io.write.check_ext(allowed_exts: list | None = None)

Decorator function for checking if output file path has correct file extension

Parameters:

allowed_exts (Union[list,None], optional) – List of allowed file extensions, defaults to None

pathology_image_features.ann_io.write.check_path(func)

Decorator function for checking if output path exists.

Parameters:

func (None) – Function which takes a filepath as input argument for writing a file to

pathology_image_features.ann_io.write.write_aperio(anns: _ElementTree, output_path: str)

Write annotations to Aperio ImageScope format

Parameters:

• anns (ET._ElementTree) – Annotations in Aperio (XML) format

• output_path (str) – File path to save annotations to

pathology_image_features.ann_io.write.write_geojson(anns: list | dict, output_path: str)

Write annotations to GeoJSON format

for more details on this schema, see: https://geojson.org

Parameters:

• anns (Union[list,dict]) – One or more GeoJSON-formatted annotations

• output_path (str) – File path to save annotations to

pathology_image_features.ann_io.write.write_histomics(anns: list | dict, output_path: str)

Write annotations to Histomics/large-image format

For more details on this schema, see: https://girder.github.io/large_image/annotations.html

Parameters:

• anns (Union[list,dict]) – One or more Histomics-formatted annotations

• output_path (str) – File path to save annotations to