AnnotationStore¶

tiatoolbox . annotation . storage . AnnotationStore

class AnnotationStore[source]¶

Annotation store abstract base class.

Methods

`append`	Insert a new annotation, returning the key.
`append_many`	Bulk append of annotations.
`bquery`	Query the store for annotation bounding boxes.
`clear`	Remove all annotations from the store.
`commit`	Commit any in-memory changes to disk.
`deserialise_geometry`	Deserialise a geometry from a string or bytes.
`dump`	Serialise a copy of the whole store to a file-like object.
`dumps`	Serialise and return a copy of store as a string or bytes.
`features`	Return annotations as a list of geoJSON features.
`from_dataframe`
`from_geojson`
`from_ndjson`	Load annotations from NDJSON.
`iquery`	Query the store for annotation keys.
`keys`	Return an iterable (usually generator) of all keys in the store.
`open`	Load a store object from a path or file-like object.
`patch`	Patch an annotation at given key.
`patch_many`	Bulk patch of annotations.
`query`	Query the store for annotations.
`remove`	Remove annotation from the store with its unique key.
`remove_many`	Bulk removal of annotations by keys.
`serialise_geometry`	Serialise a geometry to a string or bytes.
`setdefault`	Return the value of the annotation with the given key.
`to_dataframe`
`to_geodict`	Return annotations as a dictionary in geoJSON format.
`to_geojson`	Serialise the store to geoJSON.
`to_ndjson`	Serialise to New Line Delimited JSON.
`values`	Return an iterable of all annotation in the store.

append(annotation, key=None)[source]¶

Insert a new annotation, returning the key.

Parameters

annotation (Annotation) – The shapely annotation to insert.
key (str) – Optional. The unique key used to identify the annotation in the store. If not given a new UUID4 will be generated and returned instead.

Returns

The unique key of the newly inserted annotation.

Return type

str

append_many(annotations, keys=None)[source]¶

Bulk append of annotations.

This may be more performant than repeated calls to append.

Parameters

annotations (iter(Annotation)) – An iterable of annotations.
keys (iter(str)) – An iterable of unique keys associated with each geometry being inserted. If None, a new UUID4 is generated for each geometry.

Returns

A list of unique keys for the inserted geometries.

Return type

list(str)

bquery(geometry=None, where=None)[source]¶

Query the store for annotation bounding boxes.

Acts similarly to AnnotationStore.query except it checks for intersection between sotred and query geometry bounding boxes. This may be faster than a regular query in some cases, e.g. for SQliteStore with a alrge number of annotations.

Note that this method only checks for bounding box intersection and therefore may give a different result to using AnnotationStore.query with a box polygon and the “intersects” geometry predicate. Also note that geometry predicates are not supported for this method.

Parameters

geometry (Geometry or Iterable) – Geometry to use when querying. This can be a bounds (iterable of length 4) or a Shapely geometry (e.g. Polygon). If a geometry is provided, the bounds of the geometry will be used for the query. Full geometry intersection is not used for the query method.
where (str or bytes or Callable) – A statement which should evaluate to a boolean value. Only annotations for which this predicate is true will be returned. Defaults to None (assume always true). This may be a string, callable, or pickled function as bytes. Callables are called to filter each result returned the from annotation store backend in python before being returned to the user. A pickle object is, where possible, hooked into the backend as a user defined function to filter results during the backend query. Strings are expected to be in a domain specific language and are converted to SQL on a best-effort basis. For supported operators of the DSL see tiatoolbox.annotation.dsl. E.g. a simple python expression props[“class”] == 42 will be converted to a valid SQLite predicate when using SQLiteStore and inserted into the SQL query. This should be faster than filtering in python after or during the query. Additionally, the same string can be used across different backends (e.g. the previous example predicate string is valid for both DictionaryStore `and a `SQliteStore). On the other hand it has many more limitations. It is important to note that untrusted user input should never be accepted to this argument as arbitrary code can be run via pickle or the parsing of the string statement.
Returns –

list:
A list of bounding boxes for each Annotation.
_BP (..) –

https://shapely.readthedocs.io/en/stable/

manual.html#binary-predicates
BP (__) –

Return type

Dict[str, Tuple[float, float, float, float]]

clear()[source]¶

Remove all annotations from the store.

This is a naive implementation, it simply iterates over all annotations and removes them. Faster implementations may be possible in specific cases and may be implemented by subclasses.

Return type: None

abstract commit()[source]¶

Commit any in-memory changes to disk.

Return type: None

static deserialise_geometry(data)[source]¶

Deserialise a geometry from a string or bytes.

This default implementation will deserialise bytes as well-known binary (WKB) and strings as well-known text (WKT). This can be overridden to deserialise other formats such as geoJSON etc.

Parameters: data (bytes or str) – The serialised representation of a Shapely geometry.
Returns: The deserialised Shapely geometry.
Return type: Geometry

abstract dump(fp)[source]¶

Serialise a copy of the whole store to a file-like object.

Parameters: fp (Path or str or IO) – A file path or file handle object for output to disk.
Return type: None

abstract dumps()[source]¶

Serialise and return a copy of store as a string or bytes.

Returns: The serialised store.
Return type: str or bytes

features()[source]¶

Return annotations as a list of geoJSON features.

Returns: List of features as dictionaries.
Return type: list

classmethod from_ndjson(fp)[source]¶

Load annotations from NDJSON.

Expects each line to be a JSON object with the following format: ```json {

“key”: “…”, “geometry”: {

“type”: “…”, “coordinates”: […]

}, “properties”: {

“…”: “…”

}

That is a geoJSON object with an additional key field. If this key field is missing, then a new UUID4 key will be generated for this annotation.

Parameters: fp (IO) – A file-like object supporting .read.
Returns: The loaded annotations.
Return type: AnnotationStore

iquery(geometry, where=None, geometry_predicate='intersects')[source]¶

Query the store for annotation keys.

Acts the same as AnnotationStore.query except returns keys instead of annotations.

Parameters

geometry (Geometry or Iterable) – Geometry to use when querying. This can be a bounds (iterable of length 4) or a Shapely geometry (e.g. Polygon).
where (str or bytes or Callable) – A statement which should evaluate to a boolean value. Only annotations for which this predicate is true will be returned. Defaults to None (assume always true). This may be a string, callable, or pickled function as bytes. Callables are called to filter each result returned the from annotation store backend in python before being returned to the user. A pickle object is, where possible, hooked into the backend as a user defined function to filter results during the backend query. Strings are expected to be in a domain specific language and are converted to SQL on a best-effort basis. For supported operators of the DSL see tiatoolbox.annotation.dsl. E.g. a simple python expression props[“class”] == 42 will be converted to a valid SQLite predicate when using SQLiteStore and inserted into the SQL query. This should be faster than filtering in python after or during the query. Additionally, the same string can be used across different backends (e.g. the previous example predicate string is valid for both DictionaryStore `and a `SQliteStore). On the other hand it has many more limitations. It is important to note that untrusted user input should never be accepted to this argument as arbitrary code can be run via pickle or the parsing of the string statement.
geometry_predicate (str) – A string which define which binary geometry predicate to use when comparing the query geometry and a geometry in the store. Only annotations for which this binary predicate is true will be returned. Defaults to intersects. For more information see the `shapely documentation on binary predicates`__.
Returns –

list:
A list of keys for each Annotation.
_BP (..) –

https://shapely.readthedocs.io/en/stable/

manual.html#binary-predicates
BP (__) –

Return type

List[int]

keys()[source]¶

Return an iterable (usually generator) of all keys in the store.

Returns: An iterable of keys.
Return type: Iterable[str]

abstract classmethod open(fp)[source]¶

Load a store object from a path or file-like object.

Parameters: fp (Path or str or IO) – The file path or file handle.
Returns: An instance of an annotation store.
Return type: AnnotationStoreABC

patch(key, geometry=None, properties=None)[source]¶

Patch an annotation at given key.

Partial update of an annotation. Providing only a geometry will update the geometry and leave properties unchanged. Providing a properties dictionary applies a patch operation to the properties. Only updating the properties which are given and leaving the rest unchanged. To completely replace an annotation use __setitem__.

Parameters

key (str) – The key of the annotation to update.
geometry (Geometry) – The new geometry. If None, the geometry is not updated.
properties (dict) – A dictionary of properties to patch and their new values. If None, the existing properties are not altered.

Return type

None

patch_many(keys, geometries=None, properties_iter=None)[source]¶

Bulk patch of annotations.

This may be more efficient than calling patch repeatedly in a loop.

Parameters

geometries (iter(Geometry)) – An iterable of geometries to update.
properties_iter (iter(dict)) – An iterable of properties to update.
keys (iter(str)) – An iterable of keys for each annotation to be updated.

Return type

None

query(geometry=None, where=None, geometry_predicate='intersects')[source]¶

Query the store for annotations.

Parameters

geometry (Geometry or Iterable) – Geometry to use when querying. This can be a bounds (iterable of length 4) or a Shapely geometry (e.g. Polygon).
where (str or bytes or Callable) – A statement which should evaluate to a boolean value. Only annotations for which this predicate is true will be returned. Defaults to None (assume always true). This may be a string, callable, or pickled function as bytes. Callables are called to filter each result returned the from annotation store backend in python before being returned to the user. A pickle object is, where possible, hooked into the backend as a user defined function to filter results during the backend query. Strings are expected to be in a domain specific language and are converted to SQL on a best-effort basis. For supported operators of the DSL see tiatoolbox.annotation.dsl. E.g. a simple python expression props[“class”] == 42 will be converted to a valid SQLite predicate when using SQLiteStore and inserted into the SQL query. This should be faster than filtering in python after or during the query. Additionally, the same string can be used across different backends (e.g. the previous example predicate string is valid for both DictionaryStore `and a `SQliteStore). On the other hand it has many more limitations. It is important to note that untrusted user input should never be accepted to this argument as arbitrary code can be run via pickle or the parsing of the string statement.
geometry_predicate (str) – A string defining which binary geometry predicate to use when comparing the query geometry and a geometry in the store. Only annotations for which this binary predicate is true will be returned. Defaults to intersects. For more information see the `shapely documentation on binary predicates`__.
Returns –

list:
A list of Annotation objects.
_BP (..) –

https://shapely.readthedocs.io/en/stable/

manual.html#binary-predicates
BP (__) –

Return type

Dict[str, tiatoolbox.annotation.storage.Annotation]

remove(key)[source]¶

Remove annotation from the store with its unique key.

Parameters: key (str) – The key of the annotation to be removed.
Return type: None

remove_many(keys)[source]¶

Bulk removal of annotations by keys.

Parameters: keys (iter(str)) – An iterable of keys for the annotation to be removed.
Return type: None

static serialise_geometry(geometry)[source]¶

Serialise a geometry to a string or bytes.

This defaults to well-known text (WKT) but may be overridden to any other format which a Shapely geometry could be serialised to e.g. well-known binary (WKB) or geoJSON etc.

Parameters: geometry (Geometry) – The Shapely geometry to be serialised.
Returns: The serialised geometry.
Return type: bytes or str

setdefault(key, default=None)[source]¶

Return the value of the annotation with the given key.

If the key does not exist, insert the default value and return it.

Parameters

key (str) – The key of the annotation to be fetched.
default (Annotation) – The value to return if the key is not found.

Returns

The annotation or default if the key is not found.

Return type

Annotation

to_geodict()[source]¶

Return annotations as a dictionary in geoJSON format.

Returns: Dictionary of annotations in geoJSON format.
Return type: dict

to_geojson(fp=None)[source]¶

Serialise the store to geoJSON.

For more information on the geoJSON format see: - https://geojson.org/ - https://tools.ietf.org/html/rfc7946

Parameters: fp (IO) – A file-like object supporting .read. Defaults to None which returns geoJSON as a string.
Returns: None if writing to file or the geoJSON string if fp is None.
Return type: Optional[str]

to_ndjson(fp=None)[source]¶

Serialise to New Line Delimited JSON.

Each line contains a JSON object with the following format: ```json {

“key”: “…”, “geometry”: {

“type”: “…”, “coordinates”: […]

}, “properties”: {

“…”: “…”

}

That is a geoJSON object with an additional key field.

For more information on the NDJSON format see: - ndjson Specification: http://ndjson.org - JSON Lines Documentation: https://jsonlines.org - Streaming JSON: https://w.wiki/4Qan - GeoJSON RFC: https://tools.ietf.org/html/rfc7946 - JSON RFC: https://tools.ietf.org/html/rfc7159

Parameters: fp (IO) – A file-like object supporting .read. Defaults to None which returns geoJSON as a string.
Returns: None if writing to file or the geoJSON string if`fp` is None.
Return type: Optional[str]

values()[source]¶

Return an iterable of all annotation in the store.

Returns: An iterable of annotations.
Return type: Iterable[Annotation]

AnnotationStore¶

TIA Toolbox

Navigation

Related Topics