Welcome to pyhaloxml’s documentation!

HaloXML

A package for parsing .annotations files from Halo.

It can load .annotation files and store them as .geojson. The geojson will be QuPath compatible.

Examples

Converting an annotations file to geojson:

>>> from pyhaloxml import HaloXML
>>> hx = HaloXML()
>>> hx.load(r'c:\test.annotations')
>>> hx.matchnegative()
>>> hx.to_geojson(r'c:\test.geojson')

Using the contextmanager to do the same thing:

>>> from pyhaloxml import HaloXMLFile
>>> with HaloXML(r'c:\test.annotations') as hx:
>>>     hx.matchnegative()
>>>     hx.to_geojson(r'c:\test.geojson')

class pyhaloxml.HaloXML.HaloXML

HaloXML Class to import the xml files that are outputted by Halo.

This class can contain also be used to combine multiple annotation files. It would accumulate all layers and regions to a single annotation file.

Attributes:

tree_ElementTree: with the raw xml data
layerslist[Layer]: list with the layers that are present in this dataset
validbool: is the dataset valid
loglogger

as_geojson() → FeatureCollection

Return the annotations as geojson.FeatureCollection.

Returns:

FeatureCollection: A GeoJSON FeatureCollection containing the information of the .annotations file.

as_raw() → bytes

Return the bytes that can be written to a .annotations file.

Returns:

bytes: Bytes represention of the data in this HaloXML.

load(pth: str | PathLike[Any]) → None

Load .annotations file from a path.

Parameters:

pthstr | os.PathLike[Any]: Path to the .annotations file to load.

loadstream(fp: BinaryIO) → None

Load the annotation from a BinaryIO stream.

Parameters:

fpBinaryIO: Pointer to a BinaryIO.

matchnegative() → None: Match the negative regions in all layers to their positive region.

save(pth: str | PathLike[Any]) → None

Save the data as .annotation file.

Parameters:

pthstr | os.PathLike[Any]: Path to the .annotations file to save.

to_geojson(pth: str | PathLike[Any]) → None

Save regions as geojson. This file can be loaded in QuPath.

Parameters:

pthstr | os.PathLike[Any]: Path to the .GeoJSON file to save.

class pyhaloxml.HaloXML.HaloXMLFile(pth: str | PathLike[Any], mode: str = 'r')

Context manager for handeling .annotation files.

Parameters:

pthstr | os.PathLike[Any]: Path to the .annotations file.
modestr: ‘r’ = read (default). ‘w’ = write.

Region

Region.py.

class pyhaloxml.Region.Region(region: _Element)

Halo region.

Can contian negative Regions with the same layer. Has a variable called region that contains the original element from the pyhaloxml.

Parameters:

region_Element: Lxml element with the region information.

Attributes:

region_Element: Raw xml data of the region
holeslist[Region]: Holes in this region
commentslist[Comment]: Comments to the region
vertices: list[tuple[float, float]]: vertices that make up the region
type: RegionType: type of region
isnegativebool: is the region negative
hasendcapsbool: does it have endcaps
loglogger

add_hole(hole: Region) → None

Add a hole to this Region.

Parameters:

holeRegion: The hole to add.

as_geojson() → Polygon | LineString | Point

Return the region as a geojson object depending on the type of region.

Returns:

geojson.Polygon | geojson.LineString | geojson.Point: The region as geojson object in the region.

getpointinregion() → tuple[float, float]

Return a point in the region or on the region.

It can be the edge of the region or on the line of a linestring or the point of a point annotation.

Returns:

tuple[float, float]: The point in the region.

Layer

Layer.py.

class pyhaloxml.Layer.Layer

Halo annotations are grouped in layers.

These layers are the first buildingblock of a halo annotation. They have properties like color and name and contain the regions.

Attributes:

linecolorColor: Color of the lines in this layer
namestr: Name of the layer
visiblebool: If the layer is visible
regions: list[Region]: a list of Regions
loglogger

addregion(region: Region) → None

Add a region to this layer.

Parameters:

regionRegion: Region to be added.

as_geojson(matchnegative: bool = True) → List[Feature]

A geojson representation of all regions in this layer.

Parameters:

matchnegativebool: True (default) - First matches negative regions before converting to GeoJSON. False - Will not match negative regions, but will raise a warning if negative regions are found.

Returns:

List[gs.Feature]: A list with geojson Feature objects for each Region.

contains_negative() → bool

Are there any negative regions in the layer.

Returns:

bool: Returns true if the layer contains any negative regions that are not matched to positive regions.