sticky_pi_api package
Subpackages
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, skip_on_error=False)[source]
Bases:
BaseAPISpec
,ABC
Abstract class that defines the methods of the client (common between remote and client).
- Parameters
- 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
- 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
andImages
).
- property local_dir
- class sticky_pi_api.client.LocalClient(local_dir, n_threads=8, *args, **kwargs)[source]
Bases:
LocalAPI
,BaseClient
Abstract class that defines the methods of the client (common between remote and client).
- class sticky_pi_api.client.RemoteAPIConnector(host, username, password, protocol='https', port=443)[source]
Bases:
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
- Return type
- Returns
A list of dictionaries with one element for each deleted image.
- delete_project_columns(info, client_info=None)[source]
Delete a column from a project series. Requires admin rights for this project
- Parameters
- Return type
- Returns
the name of the columns that were indeed deleted
- delete_project_series(info, client_info=None)[source]
Delete project series by ID
- Parameters
- Return type
- Returns
a list representing the deleted series.
- delete_projects(info, client_info=None)[source]
Get a list of API monitoring projects. Either all projects (Default), or filter users by field if
info
is specified. In the latter case, the union of all matched users is returned. Only projects for which the user has read permission are returned. Admins users automatically have admin access to all projects.- Parameters
- Return type
- Returns
a list representing the deleted projects.
- delete_tiled_tuboids(info, client_info=None)[source]
Delete a set of tiled tuboids series, defined by their parent device, start a datetime.
- Parameters
- Return type
- Returns
A list of dictionaries with one element for each deleted image.
- delete_users(info, client_info=None)[source]
Delete 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
- Return type
- Returns
A list of users that were deleted, as represented in the underlying database, minus the cryptographic information
- 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 withdevice="%"
.what (
str
) – The nature of the objects to retrieve. One of {'metadata'
,'image'
,'thumbnail'
,'thumbnail-mini'
}
- Return type
- 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. thewhat
) argument. In the case ofwhat='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
- 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. thewhat
) argument. In the case ofwhat='metadata'
,url=''
(i.e. no url is generated).
- get_images_to_annotate(info, what='metadata', client_info=None)[source]
Retrieves images to annotate by the UID. Will reserve these images for 60min.
- 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:
'algo_name'
,'algo_version'
,``’device’, ``'start_datetime'
and'end_datetime'
.device
is interpreted to the MySQL like operator. For instance,one can match all devices withdevice="%"
. This can be used to subset the images to annotatewhat (
str
) – The nature of the objects to retrieve. One of {'metadata'
,'image'
,'thumbnail'
,'thumbnail-mini'
}
- Return type
- 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. thewhat
) argument. In the case ofwhat='metadata'
,url=''
(i.e. no url is generated).
- get_project_permissions(info=None, client_info=None)[source]
Get the permissions for a given project, filtered by the same fields as
get_projects
, i.e. {'name'
,``’description’``, … }. levels are 1,2,3 for read, read/write and read/write/admin :type info:Optional
[List
[Dict
[str
,Any
]]] :param info: A dictionary acting as a filter, using an SQL like-type match.For instance
{'name': '%'}
return all projects.
- get_projects(info=None, client_info=None)[source]
Get a list of API monitoring projects. Either all projects (Default), or filter users by field if
info
is specified. In the latter case, the union of all matched users is returned. Only projects for which the user has read permission are returned. Admins users automatically have admin access to all projects.- Parameters
- Return type
- Returns
A list of projects as represented in the underlying database, as one dictionary
- 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 withdevice="%"
.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 resultsclient_info (
Optional
[Dict
[str
,Any
]]) – optional information about the client/user contains key'username'
- Return type
- 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
- Return type
- 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 ofwhat='metadata'
, the fieldjson=''
. 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
- 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 ofwhat='metadata'
, the fieldjson=''
. 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
- Return type
- 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
- Return type
- Returns
the field corresponding to the labels that were submitted
- put_project_columns(info, client_info=None)[source]
- Add or update a column to a project series table. If
'old_column_name'
is defined, then this call will rename the old column. Requires write permission for this project
- Parameters
- Return type
- Returns
A list of columns that were added {‘column_name’`,
'column_SQL_type'
}
- Add or update a column to a project series table. If
- put_project_permissions(info, client_info=None)[source]
Add permissions to a given project by a dict of proprieties.
- Parameters
- Return type
- Returns
A list of dictionaries describing the project permisions that were created
- put_project_series(info, client_info=None)[source]
Add series to a project. series are defined st least with
'device'
,'start_datetime'
,'end_datetime'
. In addition, each series may contain values for project series columns, which are nullable. Series can also be updated if the explicit'id'
is provided.- Parameters
info (
List
[Dict
[str
,Any
]]) – A list of dictionary each dictionary has, at least, the fields {'project_id'
,'device'
,
'start_datetime'
,'end_datetime'
} :type client_info:Optional
[Dict
[str
,Any
]] :param client_info: optional information about the client/user contains key'username'
:rtype:List
[Dict
[str
,Any
]] :return: A list of dictionaries describing the series added, as represented in the underlying database.
- put_projects(info, client_info=None)[source]
Add a list of projects defined by a dict of proprieties.
- Parameters
- Return type
- Returns
A list of dictionaries describing the projects that were created
- 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
- 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
- class sticky_pi_api.client.RemoteClient(local_dir, host, username, password, protocol='https', port=443, n_threads=8, skip_on_error=False)[source]
Bases:
RemoteAPIConnector
,BaseClient
Abstract class that defines the methods of the client (common between remote and client).
sticky_pi_api.configuration module
- class sticky_pi_api.configuration.LocalAPIConf(env_file=None, **kwargs)[source]
Bases:
BaseAPIConf
- class sticky_pi_api.configuration.RemoteAPIConf(env_file=None, **kwargs)[source]
Bases:
BaseAPIConf
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:
BaseAPISpec
,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
- Return type
- Returns
A list of dictionaries with one element for each deleted image.
- delete_project_columns(info, client_info=None)[source]
Delete a column from a project series. Requires admin rights for this project
- Parameters
- Return type
- Returns
the name of the columns that were indeed deleted
- delete_project_series(info, client_info=None)[source]
Delete project series by ID
- Parameters
- Return type
- Returns
a list representing the deleted series.
- delete_projects(info, client_info=None)[source]
Get a list of API monitoring projects. Either all projects (Default), or filter users by field if
info
is specified. In the latter case, the union of all matched users is returned. Only projects for which the user has read permission are returned. Admins users automatically have admin access to all projects.- Parameters
- Return type
- Returns
a list representing the deleted projects.
- delete_tiled_tuboids(info, client_info=None)[source]
Delete a set of tiled tuboids series, defined by their parent device, start a datetime.
- Parameters
- Return type
- Returns
A list of dictionaries with one element for each deleted image.
- delete_users(info, client_info=None)[source]
Delete 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
- Return type
- Returns
A list of users that were deleted, as represented in the underlying database, minus the cryptographic information
- get_image_series(info, what='metadata', client_info=None, filter_by_intent=False)[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 withdevice="%"
.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. thewhat
) argument. In the case ofwhat='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. thewhat
) argument. In the case ofwhat='metadata'
,url=''
(i.e. no url is generated).
- get_images_to_annotate(info, what='metadata', client_info=None)[source]
Retrieves images to annotate by the UID. Will reserve these images for 60min.
- 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:'algo_name'
,'algo_version'
,``’device’, ``'start_datetime'
and'end_datetime'
.device
is interpreted to the MySQL like operator. For instance,one can match all devices withdevice="%"
. This can be used to subset the images to annotatewhat (
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. thewhat
) argument. In the case ofwhat='metadata'
,url=''
(i.e. no url is generated).
- get_project_permissions(info=None, client_info=None)[source]
Get the permissions for a given project, filtered by the same fields as
get_projects
, i.e. {'name'
,``’description’``, … }. levels are 1,2,3 for read, read/write and read/write/admin :type info:Optional
[List
[Dict
[str
,str
]]] :param info: A dictionary acting as a filter, using an SQL like-type match.For instance
{'name': '%'}
return all projects.
- get_projects(info=None, client_info=None)[source]
Get a list of API monitoring projects. Either all projects (Default), or filter users by field if
info
is specified. In the latter case, the union of all matched users is returned. Only projects for which the user has read permission are returned. Admins users automatically have admin access to all projects.- Parameters
- Return type
- Returns
A list of projects as represented in the underlying database, as one dictionary
- 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 withdevice="%"
.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 resultsclient_info (
Optional
[Dict
[str
,Any
]]) – optional information about the client/user contains key'username'
- Return type
- 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
- 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 ofwhat='metadata'
, the fieldjson=''
. 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 ofwhat='metadata'
, the fieldjson=''
. 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
- Return type
- 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
- Return type
- Returns
the field corresponding to the labels that were submitted
- put_project_columns(info, client_info=None)[source]
- Add or update a column to a project series table. If
'old_column_name'
is defined, then this call will rename the old column. Requires write permission for this project
- Parameters
- Return type
- Returns
A list of columns that were added {‘column_name’`,
'column_SQL_type'
}
- Add or update a column to a project series table. If
- put_project_permissions(info, client_info=None)[source]
Add permissions to a given project by a dict of proprieties.
- Parameters
- Return type
- Returns
A list of dictionaries describing the project permisions that were created
- put_project_series(info, client_info=None)[source]
Add series to a project. series are defined st least with
'device'
,'start_datetime'
,'end_datetime'
. In addition, each series may contain values for project series columns, which are nullable. Series can also be updated if the explicit'id'
is provided.- Parameters
info (
List
[Dict
[str
,Any
]]) – A list of dictionary each dictionary has, at least, the fields {'project_id'
,'device'
,
'start_datetime'
,'end_datetime'
} :type client_info:Optional
[Dict
[str
,Any
]] :param client_info: optional information about the client/user contains key'username'
:rtype:List
[Dict
[str
,Any
]] :return: A list of dictionaries describing the series added, as represented in the underlying database.
- put_projects(info, client_info=None)[source]
Add a list of projects defined by a dict of proprieties.
- Parameters
- Return type
- Returns
A list of dictionaries describing the projects that were created
- 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
- class sticky_pi_api.specifications.BaseAPISpec[source]
Bases:
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
- Returns
A list of dictionaries with one element for each deleted image.
- abstract delete_project_columns(info, client_info=None)[source]
Delete a column from a project series. Requires admin rights for this project
- Parameters
- Return type
- Returns
the name of the columns that were indeed deleted
- abstract delete_project_series(info, client_info=None)[source]
Delete project series by ID
- Parameters
- Return type
- Returns
a list representing the deleted series.
- abstract delete_projects(info, client_info=None)[source]
Get a list of API monitoring projects. Either all projects (Default), or filter users by field if
info
is specified. In the latter case, the union of all matched users is returned. Only projects for which the user has read permission are returned. Admins users automatically have admin access to all projects.- Parameters
- Return type
- Returns
a list representing the deleted projects.
- 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
- Return type
- Returns
A list of dictionaries with one element for each deleted image.
- abstract delete_users(info, client_info=None)[source]
Delete 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
- Return type
- Returns
A list of users that were deleted, as represented in the underlying database, minus the cryptographic information
- 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 withdevice="%"
.what (
str
) – The nature of the objects to retrieve. One of {'metadata'
,'image'
,'thumbnail'
,'thumbnail-mini'
}
- Return type
- 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. thewhat
) argument. In the case ofwhat='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
- 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. thewhat
) argument. In the case ofwhat='metadata'
,url=''
(i.e. no url is generated).
- abstract get_images_to_annotate(info, what='metadata', client_info=None)[source]
Retrieves images to annotate by the UID. Will reserve these images for 60min.
- 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:
'algo_name'
,'algo_version'
,``’device’, ``'start_datetime'
and'end_datetime'
.device
is interpreted to the MySQL like operator. For instance,one can match all devices withdevice="%"
. This can be used to subset the images to annotatewhat (
str
) – The nature of the objects to retrieve. One of {'metadata'
,'image'
,'thumbnail'
,'thumbnail-mini'
}
- Return type
- 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. thewhat
) argument. In the case ofwhat='metadata'
,url=''
(i.e. no url is generated).
- abstract get_project_permissions(info=None, client_info=None)[source]
Get the permissions for a given project, filtered by the same fields as
get_projects
, i.e. {'name'
,``’description’``, … }. levels are 1,2,3 for read, read/write and read/write/admin :type info:Optional
[List
[Dict
[str
,str
]]] :param info: A dictionary acting as a filter, using an SQL like-type match.For instance
{'name': '%'}
return all projects.
- abstract get_projects(info=None, client_info=None)[source]
Get a list of API monitoring projects. Either all projects (Default), or filter users by field if
info
is specified. In the latter case, the union of all matched users is returned. Only projects for which the user has read permission are returned. Admins users automatically have admin access to all projects.- Parameters
- Return type
- Returns
A list of projects as represented in the underlying database, as one dictionary
- 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 withdevice="%"
.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 resultsclient_info (
Optional
[Dict
[str
,Any
]]) – optional information about the client/user contains key'username'
- Return type
- 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.
- abstract get_uid_annotations(info, what='metadata', client_info=None)[source]
Retrieves annotations for a given set of images.
- Parameters
- Return type
- 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 ofwhat='metadata'
, the fieldjson=''
. 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
- 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 ofwhat='metadata'
, the fieldjson=''
. 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
- Return type
- 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
- Return type
- Returns
the field corresponding to the labels that were submitted
- abstract put_project_columns(info, client_info=None)[source]
- Add or update a column to a project series table. If
'old_column_name'
is defined, then this call will rename the old column. Requires write permission for this project
- Parameters
- Return type
- Returns
A list of columns that were added {‘column_name’`,
'column_SQL_type'
}
- Add or update a column to a project series table. If
- abstract put_project_permissions(info, client_info=None)[source]
Add permissions to a given project by a dict of proprieties.
- Parameters
- Return type
- Returns
A list of dictionaries describing the project permisions that were created
- abstract put_project_series(info, client_info=None)[source]
Add series to a project. series are defined st least with
'device'
,'start_datetime'
,'end_datetime'
. In addition, each series may contain values for project series columns, which are nullable. Series can also be updated if the explicit'id'
is provided.- Parameters
info (
List
[Dict
[str
,Any
]]) – A list of dictionary each dictionary has, at least, the fields {'project_id'
,'device'
,
'start_datetime'
,'end_datetime'
} :type client_info:Optional
[Dict
[str
,Any
]] :param client_info: optional information about the client/user contains key'username'
:rtype:List
[Dict
[str
,Any
]] :return: A list of dictionaries describing the series added, as represented in the underlying database.
- abstract put_projects(info, client_info=None)[source]
Add a list of projects defined by a dict of proprieties.
- Parameters
- Return type
- Returns
A list of dictionaries describing the projects that were created
- 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
- 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
- class sticky_pi_api.specifications.LocalAPI(api_conf, *args, **kwargs)[source]
Bases:
BaseAPI
sticky_pi_api.storage module
- class sticky_pi_api.storage.BaseStorage(api_conf, *args, **kwargs)[source]
Bases:
ABC
- abstract delete_image_files(image)[source]
Delete the files corresponding to an image. :type image:
Images
:param image: an image object- Return type
- abstract delete_tiled_tuboid_files(tuboid)[source]
Delete the files corresponding to a tiled tuboid :param image: an image object
- Return type
- abstract get_ml_bundle_file_list(bundle_name, what='all')[source]
List and describes the files present in a ML bundle.
- Parameters
- Return type
- Returns
A list of dict containing the fields
key
andurl
of the files to be downloaded, which can be used to download the files
- get_ml_bundle_upload_links(bundle_name, info)[source]
Request a list of upload links to put files in a given ML bundle
- Parameters
- Return type
- Returns
A list like
info
with the extra keyurl
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.
- class sticky_pi_api.storage.DiskStorage(api_conf, *args, **kwargs)[source]
Bases:
BaseStorage
- delete_image_files(image)[source]
Delete the files corresponding to an image. :type image:
Images
:param image: an image object- Return type
- delete_tiled_tuboid_files(tuboid)[source]
Delete the files corresponding to a tiled tuboid :param image: an image object
- Return type
- get_ml_bundle_file_list(bundle_name, what='all')[source]
List and describes the files present in a ML bundle.
- Parameters
- Return type
- Returns
A list of dict containing the fields
key
andurl
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.
- class sticky_pi_api.storage.S3Storage(api_conf, *args, **kwargs)[source]
Bases:
BaseStorage
- delete_image_files(image)[source]
Delete the files corresponding to an image. :type image:
Images
:param image: an image object- Return type
- delete_tiled_tuboid_files(tuboid)[source]
Delete the files corresponding to a tiled tuboid :param image: an image object
- Return type
- get_ml_bundle_file_list(bundle_name, what='all')[source]
List and describes the files present in a ML bundle.
- Parameters
- Return type
- Returns
A list of dict containing the fields
key
andurl
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.
sticky_pi_api.types module
sticky_pi_api.utils module
Module contents
this is the __init__ of sticky_pi_api