pathology-image-features 0.2.0__py3-none-any.whl

pathology_image_features/ann_io/README.md

@@ -0,0 +1,51 @@
+# *pathology-image-features* I/O module
+
+This module contains methods for input and output of various annotation types.
+
+Supported datatypes include:
+
+- *large-image*
+    - Extensions: .json
+    - Schema: https://girder.github.io/large_image/annotations.html
+    - Functions:
+      - Read: `read_histomics`
+      - Convert: `histomics_to_geojson`, `histomics_to_aperio`
+      - Write: `write_histomics`
+
+- *GeoJSON*
+    - Extensions: .json, .geojson
+    - Schema: https://geojson.org/
+    - Functions:
+      - Read: `read_geojson`
+      - Convert: `geojson_to_histomics`, `geojson_to_aperio`
+      - Write: `write_geojson` 
+
+- *Aperio ImageScope*
+    - Extensions: .xml
+    - Schema: (None provided)
+    - Functions:
+      - Read: `read_aperio`
+      - Convert: `aperio_to_geojson`, `aperio_to_histomics`
+      - Write: `write_aperio` 
+
+- *Parquet*
+    - Extensions: .csv
+    - Schema: (see GeoJSON)
+    - Functions:
+      - Read: (In Progress)
+      - Convert: (In Progress)
+      - Write: (In Progress)
+
+- *Image annotation types*: (see below)
+    - Extensions: .jpg, .png, .tiff, .ome.tiff, ...
+    - Schema: (see below)
+    - Functions: 
+      - Read: (In Progress)
+      - Convert: (In Progress)
+      - Write: (In Progress)
+
+Image annotation types
+- "label-mask"
+    - 2D mask with a single "class" where each unique index above zero corresponds to one "object"
+- "one-hot"
+    - ND mask where each channel is a "class" and each unique index above zero corresponds to one "object" for that "class"

pathology_image_features/ann_io/__init__.py

@@ -0,0 +1,33 @@
+from .convert import (
+    aperio_to_geojson,
+    aperio_to_histomics,
+    geojson_to_aperio,
+    geojson_to_histomics,
+    histomics_to_aperio,
+    histomics_to_geojson,
+)
+from .read import (
+    read_aperio,
+    read_geojson,
+    read_histomics,
+)
+from .write import (
+    write_aperio,
+    write_geojson,
+    write_histomics,
+)
+
+__all__ = [
+    "aperio_to_geojson",
+    "aperio_to_histomics",
+    "geojson_to_aperio",
+    "geojson_to_histomics",
+    "histomics_to_aperio",
+    "histomics_to_geojson",
+    "read_aperio",
+    "read_geojson",
+    "read_histomics",
+    "write_aperio",
+    "write_geojson",
+    "write_histomics",
+]

pathology_image_features/ann_io/convert.py

@@ -0,0 +1,340 @@
+"""
+
+Functions for converting from one annotation format to another
+
+Steps:
+    - Convert to GeoJSON (if not already GeoJSON)
+    - Convert GeoJSON to desired format
+
+"""
+
+import json
+import os
+
+import pandas as pd
+from lxml import etree as ET
+from typing_extensions import Union
+
+from ..utils.general import unique_id
+
+
+def histomics_to_geojson(anns: Union[list[dict], dict]) -> Union[list[dict], dict]:
+    """Converting Histomics/large-image formatted annotations to GeoJSON
+
+    :param anns: One or more Histomics/large-image formatted annotations
+    :type anns: Union[list,dict]
+    :return: Same annotations but in GeoJSON format
+    :rtype: Union[list,dict]
+    """
+
+    if type(anns) is dict:
+        anns = [anns]
+
+    geojson_anns = []
+    for ann in anns:
+        ann_id = ann.get("_id", unique_id())
+
+        geojson_ann = {
+            "type": "FeatureCollection",
+            "properties": {"name": ann["annotation"].get("name", ""), "_id": ann_id},
+            "features": [],
+        }
+
+        for el_idx, el in enumerate(ann["annotation"].get("elements", [])):
+            if el.get("type") == "polyline":
+                coords = [el["points"]]
+            elif el.get("type") == "rectangle":
+                coords = [
+                    [
+                        [
+                            el["center"][0] - (el["width"] / 2),
+                            el["center"][1] - (el["height"] / 2),
+                        ],
+                        [
+                            el["center"][0] + (el["width"] / 2),
+                            el["center"][1] - (el["height"] / 2),
+                        ],
+                        [
+                            el["center"][0] + (el["width"] / 2),
+                            el["center"][1] + (el["height"] / 2),
+                        ],
+                        [
+                            el["center"][0] - (el["width"] / 2),
+                            el["center"][1] + (el["height"] / 2),
+                        ],
+                        [
+                            el["center"][0] - (el["width"] / 2),
+                            el["center"][1] + (el["height"] / 2),
+                        ],
+                    ]
+                ]
+            else:
+                print(f"element type: {el.get('type')} is not implemented")
+
+            # Checking if there are holes
+            holes_list = el.get("holes", [])
+
+            props_dict = {
+                "name": ann["annotation"].get("name", ""),
+                "_id": unique_id(),
+                "_index": el_idx,
+            }
+
+            if "user" in el:
+                props_dict = el["user"] | props_dict
+
+            geojson_ann["features"].append(
+                {
+                    "type": "Feature",
+                    "geometry": {
+                        "type": "Polygon",
+                        "coordinates": coords
+                        if len(holes_list) == 0
+                        else coords + holes_list,
+                    },
+                    "properties": props_dict,
+                }
+            )
+
+        geojson_anns.append(geojson_ann)
+
+    if len(anns) == 1:
+        geojson_anns = geojson_anns[0]
+
+    return geojson_anns
+
+
+def aperio_to_geojson(xml_tree) -> Union[list, dict]:
+    """Converting Aperio ImageScope formatted annotations to GeoJSON
+
+    :param xml_tree: An XML E-Tree that is the output of read_aperio
+    :type xml_tree: None
+    :return: A list of GeoJSON FeatureCollections for each Annotation
+    :rtype: Union[list,dict]
+    """
+
+    layers_in_xml = xml_tree.findall("Annotation")
+    geojson_anns = []
+    for ann_idx in range(0, len(layers_in_xml)):
+        layer_name = (
+            f"Layer {ann_idx + 1}",
+        )  # TODO: Get the XML layer's "Label" property here
+
+        geojson_ann = {
+            "type": "FeatureCollection",
+            "features": [],
+            "properties": {"name": layer_name, "_id": unique_id()},
+        }
+
+        layer_regions = xml_tree.findall(
+            f'Annotation[@Id="{ann_idx + 1}"]/Regions/Region'
+        )
+        # Iterating through Regions
+        for r_idx, r in enumerate(layer_regions):
+            vertices = r.findall("./Vertices/Vertex")
+            coords = []
+            for vert in vertices:
+                coords.append(
+                    [int(float(vert.attrib["X"])), int(float(vert.attrib["Y"]))]
+                )
+
+            geojson_ann["features"].append(
+                {
+                    "type": "Feature",
+                    "geometry": {"type": "Polygon", "coordinates": [coords]},
+                    "properties": {
+                        "name": layer_name,
+                        "_id": unique_id(),
+                        "_index": r_idx,
+                    },
+                }
+            )
+
+        geojson_anns.append(geojson_ann)
+
+    if len(geojson_anns) == 1:
+        geojson_anns = geojson_anns[0]
+
+    return geojson_anns
+
+
+def geojson_to_histomics(anns: Union[list, dict]) -> Union[list, dict]:
+    """Converting GeoJSON formatted annotations to Histomics/large-image
+
+    :param anns: One or more GeoJSON formatted annotations
+    :type anns: Union[list,dict]
+    :return: List or single Histomics formatted annotation
+    :rtype: Union[list,dict]
+    """
+
+    if type(anns) is dict:
+        anns = [anns]
+
+    histomics_anns = []
+    for g in anns:
+        g_name = g.get("properties", {}).get("name", "")
+
+        histomics_ann = {
+            "annotation": {
+                "name": g_name,
+                "elements": [
+                    {
+                        "type": "polyline",
+                        "user": f.get("properties", {}),
+                        "closed": True,
+                        "points": [
+                            list(i) + [0] if type(i) is tuple else i + [0]
+                            for i in f["geometry"]["coordinates"][0]
+                        ],
+                        "holes": [
+                            list(i) + [0] if type(i) is tuple else i + [0]
+                            for i in f["geometry"]["coordinates"][1]
+                        ]
+                        if len(f["geometry"]["coordinates"]) == 2
+                        else [],
+                    }
+                    if all([len(i) == 2 for i in f["geometry"]["coordinates"][0]])
+                    else {
+                        "type": "polyline",
+                        "user": f.get("properties", {}),
+                        "closed": True,
+                        "points": [
+                            list(i) if type(i) is tuple else i
+                            for i in f["geometry"]["coordinates"][0]
+                        ],
+                        "holes": [
+                            list(i) if type(i) is tuple else i
+                            for i in f["geometry"]["coordinates"][1]
+                        ]
+                        if len(f["geometry"]["coordinates"]) == 2
+                        else [],
+                    }
+                    for f in g["features"]
+                ],
+            }
+        }
+        histomics_anns.append(histomics_ann)
+
+    if len(histomics_anns) == 1:
+        histomics_anns = histomics_anns[0]
+
+    return histomics_anns
+
+
+def geojson_to_aperio(anns: Union[list, dict]) -> ET._ElementTree:
+    """Converting GeoJSON formatted annotations to Aperio ImageScope format
+
+    :param anns: One or more GeoJSON annotations
+    :type anns: Union[list,dict]
+    """
+    output_xml = ET.Element("Annotations")
+
+    if type(anns) is dict:
+        anns = [anns]
+
+    for a_idx, a in enumerate(anns):
+        a_layer = ET.SubElement(
+            output_xml,
+            "Annotation",
+            attrib={
+                "Type": "4",
+                "Visible": "1",
+                "ReadOnly": "0",
+                "Incremental": "0",
+                "LineColorReadOnly": "0",
+                "Id": "1",
+                "NameReadOnly": "0",
+                "LayerName": a.get("properties", {}).get("name", f"Layer {a_idx + 1}"),
+            },
+        )
+
+        a_regions = ET.SubElement(a_layer, "Regions")
+
+        for g_idx, g in enumerate(a.get("features", [])):
+            region = ET.SubElement(
+                a_regions,
+                "Region",
+                attrib={
+                    "NegativeROA": "0",
+                    "ImageFocus": "-1",
+                    "DisplayId": str(g_idx + 1),
+                    "InputRegionId": "0",
+                    "Analyze": "0",
+                    "Type": "0",
+                    "Id": str(g_idx + 1),
+                },
+            )
+
+            vertices = ET.SubElement(region, "Vertices")
+
+            for vert in g["geometry"]["coordinates"]:
+                if len(vert) == 2:
+                    ET.SubElement(
+                        vertices,
+                        "Vertex",
+                        attrib={"X": str(vert[0]), "Y": str(vert[1]), "Z": "0"},
+                    )
+                elif len(vert) == 3:
+                    ET.SubElement(
+                        vertices,
+                        "Vertex",
+                        attrib={
+                            "X": str(vert[0]),
+                            "Y": str(vert[1]),
+                            "Z": str(vert[2]),
+                        },
+                    )
+
+            if len(g["geometry"]["coordinates"][0]) == 2:
+                ET.SubElement(
+                    vertices,
+                    "Vertex",
+                    attrib={
+                        "X": str(g["geometry"]["coordinates"][0][0]),
+                        "Y": str(g["geometry"]["coordinates"][0][1]),
+                        "Z": "0",
+                    },
+                )
+            elif len(g["geometry"]["coordinates"][0]) == 3:
+                ET.SubElement(
+                    vertices,
+                    "Vertex",
+                    attrib={
+                        "X": str(g["geometry"]["coordinates"][0][0]),
+                        "Y": str(g["geometry"]["coordinates"][0][1]),
+                        "Z": str(g["geometry"]["coordinates"][0][2]),
+                    },
+                )
+
+    output_xml_tree = output_xml.getroottree()
+
+    return output_xml_tree
+
+
+# These are the "lazy" implementations of converters
+def aperio_to_histomics(xml_tree: ET._ElementTree) -> Union[list, dict]:
+    """Converting Aperio ImageScope formatted annotations to Histomics
+
+    :param xml_tree: XML ETree object containing annotations
+    :type xml_tree: _type_
+    :return: One or more Histomics formatted annotation layers
+    :rtype: Union[list,dict]
+    """
+
+    geojson_anns = aperio_to_geojson(xml_tree)
+    histomics_anns = geojson_to_histomics(geojson_anns)
+
+    return histomics_anns
+
+
+def histomics_to_aperio(anns: Union[list, dict]) -> ET._ElementTree:
+    """Converting Histomics/large-image formatted annotations to Aperio ImageScope
+
+    :param anns: One or more annotations in Histomics/large-image format
+    :type anns: Union[list,dict]
+    """
+
+    geojson_anns = histomics_to_geojson(anns)
+    aperio_anns = geojson_to_aperio(geojson_anns)
+
+    return aperio_anns

pathology_image_features/ann_io/read.py

@@ -0,0 +1,123 @@
+"""
+
+Functions for reading different annotation types
+
+"""
+
+import functools
+import json
+import os
+
+import pandas as pd
+from lxml import etree as ET
+from numpy.random.mtrand import f
+from typing_extensions import Union
+
+
+def check_path(func):
+    """Decorator function for checking if input file paths in a function exist
+
+    :param func: Function which takes a filepath as input
+    :type func: None
+    """
+
+    @functools.wraps(func)
+    def reader(path):
+        assert os.path.exists(path), f"File: {path} not found!"
+
+        return func(path)
+
+    return reader
+
+
+def check_ext(allowed_exts: Union[list, None] = None):
+    """Decorator function for checking if input file has correct extensions for a given reader.
+
+    :param allowed_exts: List of allowed file extensions, defaults to None
+    :type allowed_exts: Union[list,None], optional
+    """
+
+    def wrapper(func):
+        @functools.wraps(func)
+        def reader(path):
+            if allowed_exts is not None:
+                assert path.split(".")[-1] in allowed_exts, (
+                    f"File: {path} has incorrect extension ({path.split('.')[-1]}). Allowed extensions for this reader are: {allowed_exts}"
+                )
+            else:
+                pass
+            return func(path)
+
+        return reader
+
+    return wrapper
+
+
+@check_ext(["json"])
+@check_path
+def read_histomics(ann_path: str) -> Union[list, dict]:
+    """Read annotations in Histomics/large-image format
+
+    For more details on this schema, see: https://girder.github.io/large_image/annotations.html
+
+    :param ann_path: Path to annotations file (.json extension)
+    :type ann_path: str
+    :return: Read annotations in original format
+    :rtype: Union[list,dict]
+    """
+
+    with open(ann_path, "r") as f:
+        read_anns = json.load(f)
+        f.close()
+
+    return read_anns
+
+
+@check_ext(["json", "geojson"])
+@check_path
+def read_geojson(ann_path: str) -> Union[list, dict]:
+    """Read annotations in GeoJSON format
+
+    For more details on this schema, see: https://geojson.org/
+
+    :param ann_path: Path to annotation file
+    :type ann_path: str
+    :return: Read annotations in original format
+    :rtype: Union[list,dict]
+    """
+
+    with open(ann_path, "r") as f:
+        read_anns = json.load(f)
+        f.close()
+
+    return read_anns
+
+
+@check_ext(["xml"])
+@check_path
+def read_aperio(ann_path: str) -> ET._ElementTree:
+    """Read annotations in Aperio ImageScope format
+
+    :param ann_path: Path to annotation file
+    :type ann_path: str
+    :return: Read annotations in original format
+    :rtype: Union[list,dict]
+    """
+
+    read_anns = ET.parse(ann_path)
+
+    return read_anns
+
+
+# TODO: Same as with read_aperio, "Original format" for Parquet annotations could be different from list/dict
+@check_path
+@check_ext(["csv", "parquet"])
+def read_parquet(ann_path: str) -> Union[list, dict]:
+    """Read annotations in Parquet format
+
+    :param ann_path: Path to annotation file
+    :type ann_path: str
+    :return: Read annotations in original format
+    :rtype: Union[list,dict]
+    """
+    raise NotImplementedError

pathology_image_features/ann_io/write.py

@@ -0,0 +1,108 @@
+"""
+
+Functions for writing different annotation types
+
+"""
+
+import functools
+import json
+import os
+
+import pandas as pd
+from lxml import etree as ET
+from typing_extensions import Union
+
+
+def check_path(func):
+    """Decorator function for checking if output path exists.
+
+    :param func: Function which takes a filepath as input argument for writing a file to
+    :type func: None
+    """
+
+    @functools.wraps(func)
+    def writer(anns, path):
+        assert os.path.isdir(f"{os.sep}".join(path.split(os.sep)[:-1])), (
+            f"Folder: {f'{os.sep}'.join(path.split(os.sep)[:-1])} not found!"
+        )
+
+        return func(anns, path)
+
+    return writer
+
+
+def check_ext(allowed_exts: Union[list, None] = None):
+    """Decorator function for checking if output file path has correct file extension
+
+    :param allowed_exts: List of allowed file extensions, defaults to None
+    :type allowed_exts: Union[list,None], optional
+    """
+
+    def wrapper(func):
+        @functools.wraps(func)
+        def writer(anns, path):
+            if allowed_exts is not None:
+                assert path.split(".")[-1] in allowed_exts, (
+                    f"Output file: {path.split(os.sep)[-1]} has incorrect extension ({path.split('.')[-1]}), Allowed extensions for this writer are: {allowed_exts}"
+                )
+            else:
+                pass
+
+            return func(anns, path)
+
+        return writer
+
+    return wrapper
+
+
+@check_ext(["json"])
+@check_path
+def write_histomics(anns: Union[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
+
+    :param anns: One or more Histomics-formatted annotations
+    :type anns: Union[list,dict]
+    :param output_path: File path to save annotations to
+    :type output_path: str
+    """
+
+    with open(output_path, "w") as f:
+        json.dump(anns, f)
+        f.close()
+
+
+@check_ext(["json", "geojson"])
+@check_path
+def write_geojson(anns: Union[list, dict], output_path: str):
+    """Write annotations to GeoJSON format
+
+    for more details on this schema, see: https://geojson.org
+
+    :param anns: One or more GeoJSON-formatted annotations
+    :type anns: Union[list,dict]
+    :param output_path: File path to save annotations to
+    :type output_path: str
+    """
+
+    with open(output_path, "w") as f:
+        json.dump(anns, f)
+        f.close()
+
+
+@check_ext(["xml"])
+@check_path
+def write_aperio(anns: ET._ElementTree, output_path: str):
+    """Write annotations to Aperio ImageScope format
+
+    :param anns: Annotations in Aperio (XML) format
+    :type anns: ET._ElementTree
+    :param output_path: File path to save annotations to
+    :type output_path: str
+    """
+
+    xml_string = ET.tostring(anns, encoding="unicode", pretty_print=True)
+    with open(output_path, "w") as f:
+        f.write(xml_string)
+        f.close()