Label annotation element definition (sarpy.annotation.label)

This module provides structures for performing data labelling on a background image

class sarpy.annotation.label.LabelSchema(version: str | None = '1.0', labels: Dict[str, str] | None = None, version_date: str | None = None, classification: str = 'UNCLASSIFIED', subtypes: Dict[str, List[str]] | None = None, confidence_values: List[str | int] | None = None, permitted_geometries: List[str] | None = None)

Bases: object

The basic structure for an annotation/labelling schema.

The label names may certainly be modified in place through use of the labels property, without worry for causing errors. This is discouraged, because having two schemas with same version number/ids and differing names can likely lead to confusion.

Any modification of label ids of sub-id structure should be performed by using the set_labels_and_subtypes() method, or difficult to diagnose runtime errors will likely be introduced.

property version: str

The version of the schema.

Return type:

str

property version_date: str

The date for this schema version - this should be a viable datetime format, but this is unenforced.

Return type:

str

property classification: str

The classification for the contents of this schema.

Type:

str

property suggested_next_id: int | None

If all ids are integer type, this returns max_id+1. Otherwise, this yields None.

Type:

None|int

property labels: Dict[str, str]

label_name}`.

Return type:

Dict[str, str]

Type:

The complete label dictionary of the form `{label_id

property subtypes: Dict[str, List[str]]

<subids list>}`.

Return type:

Dict[str, List[str]]

Type:

The complete dictionary of subtypes of the form `{parent_id

property parent_types: Dict[str, List[str]]

<set of parent ids>}`. It is canonically defined that an id is a parent of itself. The order of the parent_ids list is ascending order of parentage, i.e. [<self>, <parent>, <parent of parent>, …].

Return type:

Dict[str, List[str]]

Type:

The dictionary of parent types of the form `{child_id

property confidence_values: List[str | int]

The list of confidence values.

Returns:

Each element should be a json type (most likely use cases are str or int).

Return type:

List

property permitted_geometries: List[str] | None

The collection of permitted geometry types. None corresponds to all. Entries should be one of {‘point’, ‘line’, ‘polygon’}.

Return type:

None|List[str]

get_id_from_name(the_name: str) → str | None

Determine the id from the given name. Get None if this fails.

Parameters:

the_name (str) –

Return type:

None|str

get_parent(the_id: str) → str

Get the parent id for the given element id. The empty string is returned for elements with no parent.

Parameters:

the_id (str) –

Return type:

str

set_labels_and_subtypes(labels: Dict[str, str], subtypes: Dict[str, List[str]]) → None

Set the labels and subtypes. Note that subtypes may be modified in place.

Parameters:

  • labels (None|dict) –

  • subtypes (None|dict) –

Return type:

None

add_entry(the_id: str, the_name: str, the_parent: str = '') → None

Adds a new entry. Note that leading or trailing blanks will be trimmed from all input values.

Parameters:

  • the_id (str) – The id for the label.

  • the_name (str) – The name for the label.

  • the_parent (str) – The parent id, where blank denotes no parent.

Return type:

None

change_entry(the_id: str, the_name: str, the_parent: str) → bool

Modify the values for a schema element.

Parameters:

  • the_id (str) –

  • the_name (str) –

  • the_parent (str) –

Returns:

True if anything was actually changed. False otherwise.

Return type:

bool

delete_entry(the_id: str, recursive: bool = False) → None

Deletes the entry from the schema.

If the given element has children and recursive=False, a ValueError will be raised. If the given element has children and recursive=True, then all children will be deleted.

Parameters:

  • the_id (str) –

  • recursive (bool) –

reorder_child_element(the_id: str, spaces: int = 1) → bool

Move the one space (forward or backward) in the list of children for the current parent. This is explicitly changes no actual parent/child relationships, and only changes the child list ORDERING.

Parameters:

  • the_id (str) –

  • spaces (int) – How many spaces to shift the entry.

Returns:

True of something actually changed, False otherwise.

Return type:

bool

classmethod from_file(file_name: str)

Read schema from a file.

Parameters:

file_name (str) –

Return type:

LabelSchema

classmethod from_dict(input_dict: Dict)

Construct from a dictionary.

Parameters:

input_dict (dict) –

Return type:

LabelSchema

to_dict() → Dict

Serialize to a dictionary representation.

Return type:

dict

to_file(file_name: str) → None

Write to a (json) file.

Parameters:

file_name (str) –

Return type:

None

is_valid_confidence(value: List) → bool

Is the given value a valid confidence (i.e. is in confidence_values)? Note that None is always considered valid here.

Parameters:

value –

Return type:

bool

is_valid_geometry(value: List) → bool

Is the given geometry type allowed (i.e. is in permitted_geometries)? Note that None is always considered valid here.

Parameters:

value (str|Geometry) –

Return type:

bool

class sarpy.annotation.label.LabelMetadata(label_id: str | None = None, user_id: str | None = None, comment: str | None = None, confidence: None | int | str = None, timestamp: None | int | float = None)

Bases: Jsonable

Basic annotation metadata building block - everything but the geometry object

classmethod from_dict(the_json: Dict)

Deserialize from json.

Parameters:

the_json (Dict) –

to_dict(parent_dict: Dict | None = None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

replicate()

Make a replica of the item, where uid has not been copied.

copy()

Make a deep copy of the item.

property type

The type identifier.

Return type:

str

class sarpy.annotation.label.LabelMetadataList(elements: None | List[LabelMetadata] | Dict = None)

Bases: Jsonable

The collection of LabelMetadata elements.

property elements: List[LabelMetadata] | None

The LabelMetadata elements.

Return type:

None|List[LabelMetadata]

insert_new_element(element: LabelMetadata) → None

Inserts an element at the head of the elements list.

Parameters:

element (LabelMetadata) –

Return type:

None

classmethod from_dict(the_json: dict) → LabelMetadataList

Deserialize from json.

Parameters:

the_json (Dict) –

to_dict(parent_dict: Dict | None = None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

replicate() → LabelMetadataList

Make a replica of the item, where uid has not been copied.

get_label_id() → str | None

Gets the current label id.

Return type:

None|str

copy()

Make a deep copy of the item.

property type

The type identifier.

Return type:

str

class sarpy.annotation.label.LabelProperties(name=None, description=None, directory=None, geometry_properties=None, parameters=None)

Bases: AnnotationProperties

property parameters

The parameters

Type:

LabelMetadataList

get_label_id()

Gets the current label id.

Return type:

None|str

add_geometry_property(entry)

Add a geometry property to the list.

Warning

Care should be taken that this list stay in sync with the parent geometry.

Parameters:

entry (Dict|GeometryProperties) – The geometry properties instance of serialized version of it.

copy()

Make a deep copy of the item.

property description

The description

Type:

Optional[str]

property directory

The directory - for basic display and/or subdivision purposes

Type:

Optional[str]

classmethod from_dict(the_json)

Deserialize from json.

Parameters:

the_json (Dict) –

Return type:

AnnotationProperties

property geometry_properties: List[GeometryProperties]

The geometry properties.

Type:

List[GeometryProperties]

get_geometry_property(item)

Fetches the appropriate geometry property.

Parameters:

item (int|str) – The geometry properties uid or integer index.

Return type:

GeometryProperties

Raises:

KeyError –

get_geometry_property_and_index(item)

Fetches the appropriate geometry property and its integer index.

Parameters:

item (int|str) – The geometry properties uid or integer index.

Return type:

(GeometryProperties, int)

Raises:

KeyError –

property name

The name

Type:

Optional[str]

replicate()

Make a replica of the item, where uid has not been copied.

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

property type

The type identifier.

Return type:

str

class sarpy.annotation.label.LabelFeature(uid=None, geometry=None, properties=None)

Bases: AnnotationFeature

A specific extension of the Feature class which has the properties attribute populated with LabelProperties instance.

property properties

The properties.

Return type:

None|LabelProperties

add_annotation_metadata(value)

Adds the new label to the series of labeling efforts.

Parameters:

value (LabelMetadata) –

get_label_id()

Gets the label id.

Return type:

None|str

add_geometry_element(geometry, properties=None)

Adds the given geometry to the feature geometry (collection).

Parameters:
add_to_kml(doc, coord_transform, parent=None)

Add this feature to the kml document. Note that coordinates or transformed coordinates are assumed to be WGS-84 coordinates in longitude, latitude order. Currently only the first two (i.e. longitude and latitude) are used in this export.

Parameters:

  • doc (sarpy.io.kml.Document) –

  • coord_transform (None|callable) – If callable, the the transform will be applied to the coordinates before adding to the document.

  • parent (None|minidom.Element) – The parent node.

Return type:

None

copy()

Make a deep copy of the item.

classmethod from_dict(the_json)

Deserialize from json.

Parameters:

the_json (Dict) –

property geometry

The geometry object.

Return type:

GeometryObject|GeometryCollection

property geometry_count

The number of base geometry elements

Type:

int

get_geometry_and_geometry_properties(item)

Gets the geometry and geometry properties object for the given index/uid.

Parameters:

item (int|str) – The geometry properties uid or integer index.

Return type:

(Point|Line|Polygon, GeometryProperties)

Raises:

KeyError –

get_geometry_element(item)

Gets the basic geometry object at the given index.

Parameters:

item (int|str) – The integer index or associated geometry properties uid.

Return type:

Point|Line|Polygon

Raises:

ValueError|KeyError –

get_geometry_name(item)

Gets the name, or a reasonable default, for the geometry.

Parameters:

item (int|str) –

Return type:

str

get_geometry_property(item)

Gets the geometry properties object for the given index/uid.

Parameters:

item (int|str) – The geometry properties uid or integer index.

Return type:

GeometryProperties

Raises:

KeyError –

get_geometry_property_and_index(item)

Gets the geometry properties object and integer index for the given index/uid.

Parameters:

item (int|str) – The geometry properties uid or integer index.

Return type:

(GeometryProperties, int)

Raises:

KeyError –

get_name()

Gets a useful name.

Return type:

str

remove_geometry_element(item)

Remove the geometry element at the given index

Parameters:

item (int|str) –

replicate()

Make a replica of the item, where uid has not been copied.

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

property type

The type identifier.

Return type:

str

property uid

The feature unique identifier.

Return type:

str

class sarpy.annotation.label.LabelCollection(features=None)

Bases: AnnotationCollection

A specific extension of the FeatureCollection class which has the features are LabelFeature instances.

property features

The features list.

Return type:

List[LabelFeature]

add_feature(feature)

Add an annotation.

Parameters:

feature (LabelFeature) –

copy()

Make a deep copy of the item.

export_to_kml(file_name, coord_transform=None, **params)

Export to a kml document. Note that underlying geometry coordinates or transformed coordinates are assumed in longitude, latitude order. Currently only the first two (i.e. longitude and latitude) are used in this export.

Parameters:

  • file_name (str|zipfile.ZipFile|file like) –

  • coord_transform (None|callable) – The coordinate transform function.

  • params (dict) –

Return type:

None

classmethod from_dict(the_json)

Deserialize from json.

Parameters:

the_json (Dict) –

get_integer_index(feature_id)

Gets the integer index for the given feature id.

Parameters:

feature_id (str) –

Return type:

int

replicate()

Make a replica of the item, where uid has not been copied.

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict

property type

The type identifier.

Return type:

str

class sarpy.annotation.label.FileLabelCollection(label_schema, version=None, annotations=None, image_file_name=None, image_id=None, core_name=None)

Bases: FileAnnotationCollection

An collection of annotation elements associated with a given single image element file.

property label_schema

The label schema.

Return type:

LabelSchema

copy()

Make a deep copy of the item.

property core_name

The image core name, if appropriate.

Return type:

None|str

delete_annotation(annotation_id)

Deletes the annotation associated with the given id.

Parameters:

annotation_id (str) –

property image_file_name

The image file name, if appropriate.

Return type:

None|str

property image_id

The image id, if appropriate.

Return type:

None|str

replicate()

Make a replica of the item, where uid has not been copied.

property type

The type identifier.

Return type:

str

property version

The version

Type:

str

property annotations

The annotations.

Return type:

LabelCollection

add_annotation(annotation, validate_confidence=True, validate_geometry=True)

Add an annotation, with a check for valid values in confidence and geometry type.

Parameters:

  • annotation (LabelFeature) – The prospective annotation.

  • validate_confidence (bool) – Should we check that all confidence values follow the schema?

  • validate_geometry (bool) – Should we check that all geometries are of allowed type?

Return type:

None

is_annotation_valid(annotation)

Is the given annotation valid according to the schema?

Parameters:

annotation (LabelFeature) –

Return type:

bool

classmethod from_file(file_name)

Read from (json) file.

Parameters:

file_name (str) –

Return type:

FileLabelCollection

classmethod from_dict(the_dict)

Define from a dictionary representation.

Parameters:

the_dict (dict) –

Return type:

FileLabelCollection

to_dict(parent_dict=None)

Serialize to json.

Parameters:

parent_dict (None|Dict) –

Return type:

Dict