AnnotationStore¶
- class AnnotationStore[source]¶
Annotation store abstract base class.
Methods
Insert a new annotation, returning the key.
Bulk append of annotations.
Remove all annotations from the store.
Commit any in-memory changes to disk.
Create an SQLite expression index based on the provided predicate.
Deserialise a geometry from a string or bytes.
Serialise a copy of the whole store to a file-like object.
Serialise and return a copy of store as a string or bytes.
Return annotations as a list of geoJSON features.
from_dataframefrom_geojsonLoad annotations from NDJSON.
Query the store for annotation keys.
Return an iterable (usually generator) of all keys in the store.
Load a store object from a path or file-like object.
Patch an annotation at given key.
Bulk patch of annotations.
Query the store for annotations.
Remove annotation from the store with its unique key.
Bulk removal of annotations by keys.
Serialise a geometry to a string or bytes.
Return the value of the annotation with the given key.
to_dataframeReturn annotations as a dictionary in geoJSON format.
Serialise the store to geoJSON.
Serialise to New Line Delimited JSON.
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
- 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
- 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
- create_index(name, where)[source]¶
Create an SQLite expression index based on the provided predicate.
Note that an expression index will only be used if the query expression (in the WHERE clause) exactly matches the expression used when creating the index (excluding minor inconsequential changes such as whitespace).
SQLite expression indexes require SQLite version 3.9.0 or higher.
- 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.
- 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
- features()[source]¶
Return annotations as a list of geoJSON features.
- Returns
List of features as dictionaries.
- Return type
- 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
- 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 (Union[Tuple[numbers.Number, numbers.Number, numbers.Number, numbers.Number], shapely.geometry.point.Point, shapely.geometry.polygon.Polygon, shapely.geometry.linestring.LineString]) – Geometry to use when querying. This can be a bounds or a Shapely geometry (e.g. Polygon).
value. (A statement which should evaluate to a boolean) – Only annotations for which this predicate is true will be returned. Defaults to None (assume always true). 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 2-tuples containing: - geometry: The annotation Shapely geometry object. - properties: The properties JSON as a dictionary.
_BP (..) –
manual.html#binary-predicatesBP (__) –
where (Optional[Union[str, bytes, Callable[[Dict[str, Any]], bool]]]) –
- Return type
- keys()[source]¶
Return an iterable (usually generator) of all keys in the store.
- Returns
An iterable of keys.
- Return type
iter
- 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__.
- 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.
- query(geometry, where=None, geometry_predicate='intersects')[source]¶
Query the store for annotations.
- Parameters
geometry (QueryGeometry) – Geometry to use when querying. This can be a bounds 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). 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 2-tuples containing: - geometry: The annotation Shapely geometry object. - properties: The properties JSON as a dictionary.
_BP (..) –
manual.html#binary-predicatesBP (__) –
- Return type
- 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.
- 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
- to_geodict()[source]¶
Return annotations as a dictionary in geoJSON format.
- Returns
Dictionary of annotations in geoJSON format.
- Return type
- 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.
- Return type
None or 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.
- Return type
None or str