Annotations

class hs.annotations.AnnotationFile

A file containing multiple annotations and their property definitions.

annotations

List of annotations in the file.

property_desc

Definitions of properties used by the annotations.

class hs.annotations.Annotation

A single annotation on an image.

An annotation consists of a title, a unique identifier, a geometric descriptor, and a set of properties.

color

descriptor

The geometric shape and position of the annotation.

image_path

properties

Additional properties associated with the annotation.

title

The title or name of the annotation.

uuid

A unique identifier for the annotation.

class hs.annotations.PropertyValue

Possible values for an annotation property.

class Float(_0)

class String(_0)

class hs.annotations.Descriptor

Geometric descriptor of an annotation.

class Ellipse(cx, cy, a, b, angle, max_dist)

a

angle

b

cx

cy

max_dist

class Polygon(points, width, height, x, y)

height

points

width

x

y

class Rect(x, y, width, height)

height

width

x

y

mask()

Returns a binary mask as a numpy array.

The mask is a 2D boolean array where True indicates a pixel inside the annotation.

height

The height of the bounding box.

width

The width of the bounding box.

x

The x-coordinate of the top-left corner of the bounding box.

y

The y-coordinate of the top-left corner of the bounding box.

class hs.annotations.Property

Description of a property type.

class FloatValue

class Label(labels, colors)

colors

labels

hs.annotations.open(path)

Loads an AnnotationFile from a JSON file.

Args:

path (str): Path to the JSON file.

Returns:

AnnotationFile: The loaded annotations.

hs.annotations.write(file, path)

Writes an AnnotationFile to a JSON file.

Args:

file (AnnotationFile): The AnnotationFile to save. path (str): Path to the output JSON file.

Drawing utility functions

hs.annotations.plot_image_with_annotations(image: Any, annotations: AnnotationFile | Iterable[Annotation], *, ax=None, label: bool = False, color_property: str | None = None, show_axes: bool = False, image_kwargs: dict[str, Any] | None = None, annotation_kwargs: dict[str, Any] | None = None)

Plot an image and draw annotations on top.

Parameters:

• image (Any) – Array-like image accepted by imshow.

• annotations (AnnotationFile | Iterable[Annotation]) – AnnotationFile or iterable of Annotation objects.

• ax (default: None) – Optional Matplotlib axes. A new figure and axes are created when omitted.

• label (bool, default: False) – Whether to draw annotation titles.

• color_property (str | None, default: None) – Optional property name to use for annotation colors. If None, the annotation colors are used instead.

• show_axes (bool, default: False) – Whether to leave axes visible.

• image_kwargs (dict[str, Any] | None, default: None) – Optional keyword arguments passed to draw_image.

• annotation_kwargs (dict[str, Any] | None, default: None) – Optional keyword arguments passed to draw_annotations.

Returns:

A tuple (fig, ax, patches).

hs.annotations.draw_annotations(ax, annotations: Iterable[Annotation], *, label: bool = False, colors: list[str] | None, **patch_kwargs: Any) → list[Any]

Draw multiple annotations on an existing Matplotlib axes.

Parameters:

• ax – Matplotlib axes to draw on.

• annotations (Iterable[Annotation]) – AnnotationFile or iterable of Annotation objects.

• label (bool, default: False) – Whether to draw annotation titles.

• colors (list[str] | None) – List of colors to draw with. If None, the annotation colors are used instead.

• patch_kwargs (Any) – Keyword arguments passed to draw_annotation.

Returns:

A list of created Matplotlib patches.

Return type:

list[Any]

hs.annotations.draw_annotations_file(ax, file: AnnotationFile, *, label: bool = False, color_property: str | None = None, **patch_kwargs: Any)

Parameters:

• file (AnnotationFile)

• label (bool)

• color_property (str | None)

• patch_kwargs (Any)

hs.annotations.draw_annotation(ax, annotation: Annotation, *, label: bool | str = False, color: str | None = None, **patch_kwargs: Any)

Draw one annotation on an existing Matplotlib axis.

Parameters:

• ax – Matplotlib axes to draw on.

• annotation (Annotation) – Annotation to draw.

• label (bool | str, default: False) – If true, use the annotation title as label. If a string, use it directly. Defaults to no label.

• color (str | None, default: None) – Optional patch edge color.

• patch_kwargs (Any) – Keyword arguments passed to draw_descriptor.

Returns:

The created Matplotlib patch.

hs.annotations.draw_descriptor(ax, descriptor: Descriptor, *, label: str | None = None, label_kwargs: dict[str, Any] | None = None, **patch_kwargs: Any)

Draw a descriptor on an existing Matplotlib axes.

Parameters:

• ax – Matplotlib axes to draw on.

• descriptor (Descriptor) – Descriptor to draw.

• label (str | None, default: None) – Optional label to place near the descriptor center.

• label_kwargs (dict[str, Any] | None, default: None) – Optional keyword arguments passed to ax.text.

• patch_kwargs (Any) – Keyword arguments passed to descriptor_patch.

Returns:

The created Matplotlib patch.

hs.annotations.descriptor_patch(descriptor: Descriptor, *, edgecolor: str = 'tab:red', facecolor: str = 'none', linewidth: float = 1.5, alpha: float | None = None, **kwargs: Any)

Create a Matplotlib patch for a descriptor.

Parameters:

• descriptor (Descriptor) – Descriptor to draw.

• edgecolor (str, default: 'tab:red') – Patch edge color.

• facecolor (str, default: 'none') – Patch fill color. Defaults to no fill.

• linewidth (float, default: 1.5) – Patch line width.

• alpha (float | None, default: None) – Optional patch alpha.

• kwargs (Any) – Additional keyword arguments passed to the patch constructor.

Returns:

A Matplotlib patch matching the descriptor geometry.

hs.annotations.draw_image(ax, image: Any, *, show_axes: bool = False, **imshow_kwargs: Any)

Draw an image array on an existing Matplotlib axis.

Parameters:

• ax – Matplotlib axes to draw on.

• image (Any) – Array-like image accepted by imshow.

• show_axes (bool, default: False) – Whether to leave axes visible. Defaults to false.

• imshow_kwargs (Any) – Keyword arguments passed to ax.imshow.

Returns:

The Matplotlib image artist.