sticky_pi_api package

Submodules

sticky_pi_api.client module

Main module of the client. Implements classes to interact with the API.

class sticky_pi_api.client.BaseClient(local_dir, n_threads=8)[source]

Bases: sticky_pi_api.specifications.BaseAPISpec, abc.ABC

Abstract class that defines the methods of the client (common between remote and client).

Parameters
  • local_dir (str) – The path to a client directory that acts as a client storage

  • n_threads (int) – The number of parallel threads to use to compute statistics on the image (md5 and such)

delete_cache()[source]
get_images_with_uid_annotations_series(info, what_image='metadata', what_annotation='metadata')[source]

Retrieves images alongside their annotations (if available) for images from a given device and within a given datetime range.

Parameters
  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'

  • what_image (str) – The nature of the image objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail_mini'}

  • what_annotation (str) – The nature of the object to retrieve. One of {'metadata', 'data'}.

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database tables (see UIDAnnotations and Images).

get_ml_bundle_dir(bundle_name, bundle_dir, what)[source]
Return type

List[Dict[str, Union[float, str]]]

get_tiled_tuboid_series_itc_labels(info, what='metadata')[source]
Return type

List[Dict[str, Union[float, int, str]]]

property local_dir
put_images(files)[source]

Incrementally upload a list of client files

Parameters

files (List[str]) – the paths to the client files

Return type

List[Dict[str, Union[float, int, str]]]

Returns

the data of the uploaded files, as represented in by API

put_ml_bundle_dir(bundle_name, bundle_dir, what='all')[source]
Return type

List[Dict[str, Union[float, str]]]

put_tiled_tuboids(tuboid_directories, series_info)[source]
class sticky_pi_api.client.Cache(path)[source]

Bases: dict

add(function, results)[source]
delete()[source]
get_cached(function, hash)[source]
class sticky_pi_api.client.LocalClient(local_dir, n_threads=8, *args, **kwargs)[source]

Bases: sticky_pi_api.specifications.LocalAPI, sticky_pi_api.client.BaseClient

Abstract class that defines the methods of the client (common between remote and client).

Parameters
  • local_dir (str) – The path to a client directory that acts as a client storage

  • n_threads (int) – The number of parallel threads to use to compute statistics on the image (md5 and such)

class sticky_pi_api.client.RemoteAPIConnector(host, username, password, protocol='https', port=443)[source]

Bases: sticky_pi_api.specifications.BaseAPISpec

delete_images(info, client_info=None)[source]

#fixme. this is false. it now takes a set of images as returned by get_images Delete a set of images, defined by their parent device and the datetime of the picture.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

delete_tiled_tuboids(info, client_info=None)[source]

Delete a set of tiled tuboids series, defined by their parent device, start a datetime.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device', 'start_datetime' and 'end_datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

get_image_series(info, what='metadata', client_info=None)[source]

Retrieves image sequences (i.e. series). A series contains all images from a given device within a datetime range.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".

  • what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

get_images(info, what='metadata', client_info=None)[source]

Retrieves information about a given set of images, defined by their parent device and the datetime of the picture. If an image is not available, no data is returned for this image.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'

  • what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

get_tiled_tuboid_series(info, what='metadata', client_info=None)[source]

Retrieves tiled tuboids – i.e. stitched annotations into a tile, where the assumption is one tuboid per instance. A series contains all tuboids fully contained within a range

Parameters
  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".

  • what (str) – The nature of the objects to retrieve, either 'data' or 'metadata'. 'metadata' will not add the extra three fields mapping the files to the results

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus the fields 'metadata', 'tuboid' and 'context' fields, which have a url to fetch the relevant file.

get_token(client_info=None)[source]

A authentication token for a user. injection in this function.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

str

Returns

a dictionary with the keys 'token' and 'expiration', an ascii formatted token, and expiration timestamp, respectively

get_uid_annotations(info, what='metadata', client_info=None)[source]

Retrieves annotations for a given set of images.

Parameters
  • info (List[Dict[str, str]]) – A list of dict with keys: 'device' and 'datetime'

  • what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

get_uid_annotations_series(info, what='metadata', client_info=None)[source]

Retrieves annotations for a given set of images.

Parameters
  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator.

  • what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

get_users(info=None, client_info=None)[source]

Get a list of API users. Either all users (Default), or filter users by field if info is specified. In the latter case, the union of all matched users is returned.

Parameters
  • info (Optional[List[Dict[str, str]]]) – A dictionary acting as a filter, using an SQL like-type match. For instance {'username': '%'} return all users.

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of users as represented in the underlying database, as one dictionary [per user, with the keys being database column names. Note that the crypo/sensitive fields are not returned (e.g. password_hash)

put_itc_labels(info, client_info=None)[source]

Stores labels for a given set of tiled tuboid

Parameters
  • info (List[Dict[str, Union[str, int]]]) – A list of dict with keys: 'tuboid_id', 'label', 'pattern', 'algo_version'``and ``'algo_name' (see ITCLabels).

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

the field corresponding to the labels that were submitted

put_uid_annotations(info, client_info=None)[source]
Parameters
  • info (List[Dict[str, Union[List, Dict[str, Any]]]]) –

    A list of dictionaries corresponding to annotations (one list element per image). The annotations are formatted as a dictionaries with two keys: 'annotations' and 'metadata'.

    • 'metadata' must have the fields:
      • 'algo_name': the name of the algorithm used to find the object (e.g. 'sticky-pi-universal-insect-detector')

      • 'algo_version': The version of the algorithm as timestamp-md5 (e.g. '1598113346-ad2cd78dfaca12821046dfb8994724d5')

      • 'device': The device that took the annotated image (e.g. '5c173ff2')

      • 'datetime': The datetime at which the image was taken (e.g. '2020-06-20_21-33-24')

      • 'md5': The md5 of the image that was analysed (e.g. '9e6e908d9c29d332b511f8d5121857f8')

    • 'annotations' is a list where each element represent an object. It has the fields:
      • 'contour': a 3d array encoding the position of the vertices (as convention in OpenCV)

      • 'name': the name/type of the object (e.g. 'insect')

      • 'fill_colour' and 'stroke_colour': the colours of the contour (if it is to be drawn – e.g. '#0000ff')

      • 'value': an optional integer further describing the contour (e.g. 1)

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

The metadata of the uploaded annotations (i.e. a list od dicts. each field of the dict naming a column in the database). This corresponds to the annotation data as represented in UIDAnnotations

put_users(info, client_info=None)[source]

Add a list of users defined by a dict of proprieties.

Parameters
  • info (List[Dict[str, Any]]) – A list of dictionary each dictionary has the fields {'username', 'password'}, and optionally: {'email', 'is_admin'},

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of dictionaries describing the users that were created

exception sticky_pi_api.client.RemoteAPIException[source]

Bases: Exception

class sticky_pi_api.client.RemoteClient(local_dir, host, username, password, protocol='https', port=443, n_threads=8)[source]

Bases: sticky_pi_api.client.RemoteAPIConnector, sticky_pi_api.client.BaseClient

Abstract class that defines the methods of the client (common between remote and client).

Parameters
  • local_dir (str) – The path to a client directory that acts as a client storage

  • n_threads (int) – The number of parallel threads to use to compute statistics on the image (md5 and such)

sticky_pi_api.configuration module

class sticky_pi_api.configuration.BaseAPIConf(env_file=None, **kwargs)[source]

Bases: dict

class sticky_pi_api.configuration.LocalAPIConf(env_file=None, **kwargs)[source]

Bases: sticky_pi_api.configuration.BaseAPIConf

class sticky_pi_api.configuration.RemoteAPIConf(env_file=None, **kwargs)[source]

Bases: sticky_pi_api.configuration.BaseAPIConf

class sticky_pi_api.configuration.RequiredConfVar[source]

Bases: object

sticky_pi_api.image_parser module

class sticky_pi_api.image_parser.ImageParser(file)[source]

Bases: dict

A class derived from dict that contains image metadata in its fields. It parses data from an input JPEG image file taken by a Sticky Pi and retrieves its metadata from filename an exif fields. In addition, it computes md5 sum and generate thumbnails for the input image. :param file: path to file or file like object

property file_blob
property filename
property thumbnail
property thumbnail_mini

sticky_pi_api.specifications module

class sticky_pi_api.specifications.BaseAPI(api_conf, *args, **kwargs)[source]

Bases: sticky_pi_api.specifications.BaseAPISpec, abc.ABC

delete_images(info, client_info=None)[source]

#fixme. this is false. it now takes a set of images as returned by get_images Delete a set of images, defined by their parent device and the datetime of the picture.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

delete_tiled_tuboids(info, client_info=None)[source]

Delete a set of tiled tuboids series, defined by their parent device, start a datetime.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device', 'start_datetime' and 'end_datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

get_image_series(info, what='metadata', client_info=None)[source]

Retrieves image sequences (i.e. series). A series contains all images from a given device within a datetime range.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".

  • what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

get_images(info, what='metadata', client_info=None)[source]

Retrieves information about a given set of images, defined by their parent device and the datetime of the picture. If an image is not available, no data is returned for this image.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'

  • what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

get_tiled_tuboid_series(info, what='metadata', client_info=None)[source]

Retrieves tiled tuboids – i.e. stitched annotations into a tile, where the assumption is one tuboid per instance. A series contains all tuboids fully contained within a range

Parameters
  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".

  • what (str) – The nature of the objects to retrieve, either 'data' or 'metadata'. 'metadata' will not add the extra three fields mapping the files to the results

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus the fields 'metadata', 'tuboid' and 'context' fields, which have a url to fetch the relevant file.

get_uid_annotations(info, what='metadata', client_info=None)[source]

Retrieves annotations for a given set of images.

Parameters
  • info (List[Dict[str, Union[float, int, str]]]) – A list of dict with keys: 'device' and 'datetime'

  • what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

get_uid_annotations_series(info, what='metadata', client_info=None)[source]

Retrieves annotations for a given set of images.

Parameters
  • info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator.

  • what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

get_users(info=None, client_info=None)[source]

Get a list of API users. Either all users (Default), or filter users by field if info is specified. In the latter case, the union of all matched users is returned.

Parameters
  • info (Optional[List[Dict[str, str]]]) – A dictionary acting as a filter, using an SQL like-type match. For instance {'username': '%'} return all users.

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of users as represented in the underlying database, as one dictionary [per user, with the keys being database column names. Note that the crypo/sensitive fields are not returned (e.g. password_hash)

put_itc_labels(info, client_info=None)[source]

Stores labels for a given set of tiled tuboid

Parameters
  • info (List[Dict[str, Union[str, int]]]) – A list of dict with keys: 'tuboid_id', 'label', 'pattern', 'algo_version'``and ``'algo_name' (see ITCLabels).

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

the field corresponding to the labels that were submitted

put_uid_annotations(info, client_info=None)[source]
Parameters
  • info (List[Dict[str, Union[List, Dict[str, Any]]]]) –

    A list of dictionaries corresponding to annotations (one list element per image). The annotations are formatted as a dictionaries with two keys: 'annotations' and 'metadata'.

    • 'metadata' must have the fields:
      • 'algo_name': the name of the algorithm used to find the object (e.g. 'sticky-pi-universal-insect-detector')

      • 'algo_version': The version of the algorithm as timestamp-md5 (e.g. '1598113346-ad2cd78dfaca12821046dfb8994724d5')

      • 'device': The device that took the annotated image (e.g. '5c173ff2')

      • 'datetime': The datetime at which the image was taken (e.g. '2020-06-20_21-33-24')

      • 'md5': The md5 of the image that was analysed (e.g. '9e6e908d9c29d332b511f8d5121857f8')

    • 'annotations' is a list where each element represent an object. It has the fields:
      • 'contour': a 3d array encoding the position of the vertices (as convention in OpenCV)

      • 'name': the name/type of the object (e.g. 'insect')

      • 'fill_colour' and 'stroke_colour': the colours of the contour (if it is to be drawn – e.g. '#0000ff')

      • 'value': an optional integer further describing the contour (e.g. 1)

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Returns

The metadata of the uploaded annotations (i.e. a list od dicts. each field of the dict naming a column in the database). This corresponds to the annotation data as represented in UIDAnnotations

put_users(info, client_info=None)[source]

Add a list of users defined by a dict of proprieties.

Parameters
  • info (List[Dict[str, Any]]) – A list of dictionary each dictionary has the fields {'username', 'password'}, and optionally: {'email', 'is_admin'},

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of dictionaries describing the users that were created

verify_password(username_or_token, password)[source]
class sticky_pi_api.specifications.BaseAPISpec[source]

Bases: abc.ABC

abstract delete_images(info, client_info=None)[source]

#fixme. this is false. it now takes a set of images as returned by get_images Delete a set of images, defined by their parent device and the datetime of the picture.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, Union[float, int, str]]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'

Returns

A list of dictionaries with one element for each deleted image.

abstract delete_tiled_tuboids(info, client_info=None)[source]

Delete a set of tiled tuboids series, defined by their parent device, start a datetime.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device', 'start_datetime' and 'end_datetime'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each deleted image.

abstract get_image_series(info, what='metadata', client_info=None)[source]

Retrieves image sequences (i.e. series). A series contains all images from a given device within a datetime range.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".

  • what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

abstract get_images(info, what='metadata', client_info=None)[source]

Retrieves information about a given set of images, defined by their parent device and the datetime of the picture. If an image is not available, no data is returned for this image.

Parameters
  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, keys: 'device' and 'datetime'

  • what (str) – The nature of the objects to retrieve. One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus a 'url' fields to retrieve the actual object requested (i.e. the what) argument. In the case of what='metadata', url='' (i.e. no url is generated).

abstract get_tiled_tuboid_series(info, what='metadata', client_info=None)[source]

Retrieves tiled tuboids – i.e. stitched annotations into a tile, where the assumption is one tuboid per instance. A series contains all tuboids fully contained within a range

Parameters
  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator. For instance,one can match all devices with device="%".

  • what (str) – The nature of the objects to retrieve, either 'data' or 'metadata'. 'metadata' will not add the extra three fields mapping the files to the results

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database plus the fields 'metadata', 'tuboid' and 'context' fields, which have a url to fetch the relevant file.

abstract get_token(client_info=None)[source]

A authentication token for a user. injection in this function.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

Dict[str, Union[str, int]]

Returns

a dictionary with the keys 'token' and 'expiration', an ascii formatted token, and expiration timestamp, respectively

abstract get_uid_annotations(info, what='metadata', client_info=None)[source]

Retrieves annotations for a given set of images.

Parameters
  • info (List[Dict[str, str]]) – A list of dict with keys: 'device' and 'datetime'

  • what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

abstract get_uid_annotations_series(info, what='metadata', client_info=None)[source]

Retrieves annotations for a given set of images.

Parameters
  • info (List[Dict[str, str]]) – A list of dicts. each dicts has, at least, the keys: 'device', 'start_datetime' and 'end_datetime'. device is interpreted to the MySQL like operator.

  • what (str) – The nature of the object to retrieve. One of {'metadata', 'json'}.

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

A list of dictionaries with one element for each queried value. Each dictionary contains the fields present in the underlying database table (see UIDAnnotations). In the case of what='metadata', the field json=''. Otherwise, it contains a json string with the actual annotation data.

abstract get_users(info=None, client_info=None)[source]

Get a list of API users. Either all users (Default), or filter users by field if info is specified. In the latter case, the union of all matched users is returned.

Parameters
  • info (Optional[List[Dict[str, str]]]) – A dictionary acting as a filter, using an SQL like-type match. For instance {'username': '%'} return all users.

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of users as represented in the underlying database, as one dictionary [per user, with the keys being database column names. Note that the crypo/sensitive fields are not returned (e.g. password_hash)

abstract put_itc_labels(info, client_info=None)[source]

Stores labels for a given set of tiled tuboid

Parameters
  • info (List[Dict[str, Union[str, int]]]) – A list of dict with keys: 'tuboid_id', 'label', 'pattern', 'algo_version'``and ``'algo_name' (see ITCLabels).

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

the field corresponding to the labels that were submitted

abstract put_uid_annotations(info, client_info=None)[source]
Parameters
  • info (List[Dict[str, Union[List, Dict[str, Any]]]]) –

    A list of dictionaries corresponding to annotations (one list element per image). The annotations are formatted as a dictionaries with two keys: 'annotations' and 'metadata'.

    • 'metadata' must have the fields:
      • 'algo_name': the name of the algorithm used to find the object (e.g. 'sticky-pi-universal-insect-detector')

      • 'algo_version': The version of the algorithm as timestamp-md5 (e.g. '1598113346-ad2cd78dfaca12821046dfb8994724d5')

      • 'device': The device that took the annotated image (e.g. '5c173ff2')

      • 'datetime': The datetime at which the image was taken (e.g. '2020-06-20_21-33-24')

      • 'md5': The md5 of the image that was analysed (e.g. '9e6e908d9c29d332b511f8d5121857f8')

    • 'annotations' is a list where each element represent an object. It has the fields:
      • 'contour': a 3d array encoding the position of the vertices (as convention in OpenCV)

      • 'name': the name/type of the object (e.g. 'insect')

      • 'fill_colour' and 'stroke_colour': the colours of the contour (if it is to be drawn – e.g. '#0000ff')

      • 'value': an optional integer further describing the contour (e.g. 1)

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Union[float, int, str]]]

Returns

The metadata of the uploaded annotations (i.e. a list od dicts. each field of the dict naming a column in the database). This corresponds to the annotation data as represented in UIDAnnotations

abstract put_users(info, client_info=None)[source]

Add a list of users defined by a dict of proprieties.

Parameters
  • info (List[Dict[str, Any]]) – A list of dictionary each dictionary has the fields {'username', 'password'}, and optionally: {'email', 'is_admin'},

  • client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

List[Dict[str, Any]]

Returns

A list of dictionaries describing the users that were created

class sticky_pi_api.specifications.LocalAPI(api_conf, *args, **kwargs)[source]

Bases: sticky_pi_api.specifications.BaseAPI

get_token(client_info=None)[source]

A authentication token for a user. injection in this function.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Returns

a dictionary with the keys 'token' and 'expiration', an ascii formatted token, and expiration timestamp, respectively

class sticky_pi_api.specifications.RemoteAPI(api_conf, *args, **kwargs)[source]

Bases: sticky_pi_api.specifications.BaseAPI

get_token(client_info=None)[source]

A authentication token for a user. injection in this function.

Parameters

client_info (Optional[Dict[str, Any]]) – optional information about the client/user contains key 'username'

Return type

Dict[str, Union[str, int]]

Returns

a dictionary with the keys 'token' and 'expiration', an ascii formatted token, and expiration timestamp, respectively

put_images(files, client_info=None)[source]
sticky_pi_api.specifications.set_sqlite_pragma(dbapi_connection, connection_record)[source]

sticky_pi_api.storage module

class sticky_pi_api.storage.BaseStorage(api_conf, *args, **kwargs)[source]

Bases: abc.ABC

abstract delete_image_files(image)[source]

Delete the files corresponding to an image. :type image: Images :param image: an image object

Return type

None

abstract delete_tiled_tuboid_files(tuboid)[source]

Delete the files corresponding to a tiled tuboid :param image: an image object

Return type

None

abstract get_ml_bundle_file_list(bundle_name, what='all')[source]

List and describes the files present in a ML bundle.

Parameters
  • bundle_name (str) – the name of the machine learning bundle to fetch the files from

  • what (str) – One of {'all', 'data',``’model’`` }, to return all files, only the training data(training), or only the model (inference), respectively.

Return type

List[Dict[str, Union[float, str]]]

Returns

A list of dict containing the fields key and url of the files to be downloaded, which can be used to download the files

Request a list of upload links to put files in a given ML bundle

Parameters
  • bundle_name (str) –

  • info (List[Dict[str, Union[float, str]]]) – A list of dict containing the fields key, md5 mtime describing the upload candidates.

Return type

List[Dict[str, Union[float, str]]]

Returns

A list like info with the extra key url pointing to a destination where the file can be copied/posted. The list contains only files that did not exist on remote – hence can be empty.

abstract get_url_for_image(image, what='metadata')[source]

Retrieves the URL to the file corresponding to an image in the database.

Parameters
  • image (Images) – an image object

  • what (str) – One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

str

Returns

a url/path as a string. For what='metadata', an empty string is returned. for consistency

abstract get_urls_for_tiled_tuboids(data)[source]
Return type

Dict[str, str]

classmethod local_bundle_files_info(bundle_dir, what='all', ignored_dir_names=('.cache'))[source]
abstract store_image_files(image)[source]

Saves the files corresponding to a an image. Those are generally the original JPEG plus thumbnail and thumbnail-mini

Parameters

image (Images) – an image object

Return type

None

abstract store_tiled_tuboid(data)[source]
Return type

None

class sticky_pi_api.storage.DiskStorage(api_conf, *args, **kwargs)[source]

Bases: sticky_pi_api.storage.BaseStorage

delete_image_files(image)[source]

Delete the files corresponding to an image. :type image: Images :param image: an image object

Return type

None

delete_tiled_tuboid_files(tuboid)[source]

Delete the files corresponding to a tiled tuboid :param image: an image object

Return type

None

get_ml_bundle_file_list(bundle_name, what='all')[source]

List and describes the files present in a ML bundle.

Parameters
  • bundle_name (str) – the name of the machine learning bundle to fetch the files from

  • what (str) – One of {'all', 'data',``’model’`` }, to return all files, only the training data(training), or only the model (inference), respectively.

Return type

List[Dict[str, Union[float, str]]]

Returns

A list of dict containing the fields key and url of the files to be downloaded, which can be used to download the files

get_url_for_image(image, what='metadata')[source]

Retrieves the URL to the file corresponding to an image in the database.

Parameters
  • image (Images) – an image object

  • what (str) – One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

str

Returns

a url/path as a string. For what='metadata', an empty string is returned. for consistency

get_urls_for_tiled_tuboids(data)[source]
Return type

Dict[str, str]

store_image_files(image)[source]

Saves the files corresponding to a an image. Those are generally the original JPEG plus thumbnail and thumbnail-mini

Parameters

image (Images) – an image object

Return type

None

store_tiled_tuboid(data)[source]
Return type

None

class sticky_pi_api.storage.S3Storage(api_conf, *args, **kwargs)[source]

Bases: sticky_pi_api.storage.BaseStorage

delete_image_files(image)[source]

Delete the files corresponding to an image. :type image: Images :param image: an image object

Return type

None

delete_tiled_tuboid_files(tuboid)[source]

Delete the files corresponding to a tiled tuboid :param image: an image object

Return type

None

get_ml_bundle_file_list(bundle_name, what='all')[source]

List and describes the files present in a ML bundle.

Parameters
  • bundle_name (str) – the name of the machine learning bundle to fetch the files from

  • what (str) – One of {'all', 'data',``’model’`` }, to return all files, only the training data(training), or only the model (inference), respectively.

Return type

List[Dict[str, Union[float, str]]]

Returns

A list of dict containing the fields key and url of the files to be downloaded, which can be used to download the files

get_url_for_image(image, what='metadata')[source]

Retrieves the URL to the file corresponding to an image in the database.

Parameters
  • image (Images) – an image object

  • what (str) – One of {'metadata', 'image', 'thumbnail', 'thumbnail-mini'}

Return type

str

Returns

a url/path as a string. For what='metadata', an empty string is returned. for consistency

get_urls_for_tiled_tuboids(data)[source]
Return type

Dict[str, str]

store_image_files(image)[source]

Saves the files corresponding to a an image. Those are generally the original JPEG plus thumbnail and thumbnail-mini

Parameters

image (Images) – an image object

Return type

None

store_tiled_tuboid(data)[source]
Return type

None

sticky_pi_api.types module

sticky_pi_api.utils module

class sticky_pi_api.utils.URLOrFileOpen(file_or_url, mode)[source]

Bases: object

sticky_pi_api.utils.chunker(seq, size)[source]

Breaks an interable into a list of smaller chunks of size size (or less for the last chunk)

Parameters
  • seq – an iterable

  • size (int) – the size of the chunk

Returns

sticky_pi_api.utils.datetime_to_string(dt)[source]
sticky_pi_api.utils.json_inputs_to_python(func)[source]
sticky_pi_api.utils.json_io_converter(o)[source]
sticky_pi_api.utils.json_out_parser(o)[source]
sticky_pi_api.utils.md5(file, chunk_size=32768)[source]
sticky_pi_api.utils.multipart_etag(file, chunk_size)[source]
sticky_pi_api.utils.python_inputs_to_json(func)[source]
sticky_pi_api.utils.string_to_datetime(string)[source]

Module contents

this is the __init__ of sticky_pi_api