Collections API¶

Helios Collections API.

Methods are meant to represent the core functionality in the developer documentation. Some may have additional functionality for convenience.

class helios.collections_api.Collections(session=None)[source]¶

The Collections API allows users to group and organize individual image frames.

Collections are intended to be short-lived resources and will be accessible for 90 days from the time the collection was created. After that time period has expired, the collection and all associated imagery will be removed from the system.

add_image(assets, collection_id)[source]¶

Add images to a collection from Helios assets.

assets dictionary templates:

# Asset examples that can be included in the `assets` input list.
data = {'camera_id': ''}
data = {'camera_id': '', 'time': ''}
data = {'observation_id': ''}
data = {'collection_id': '', 'image': ''}

Usage example:

import helios

coll_inst = helios.client('collections')
camera_id = '...'
times = [...] # List of image times.
destination_id = '...'
data = [{'camera_id': camera_id, 'time': x} for x in times]
results, failures = coll_inst.add_image(data, destination_id)

Parameters:

assets (dict or list of dicts) – Data containing any of these payloads (camera_id), (camera_id, time), (observation_id), (collection_id, image). E.g. data = [{‘camera_id’: ‘cam_01’, time: ‘2017-01-01T00:00:000Z’}]
collection_id (str) – Collection ID.

Returns:

A tuple containing:

succeeded (list of Record):: Successful API call records.
failed (list of Record):: Failed API call records.

Return type:

tuple

copy(collection_id, new_name)[source]¶

Copy a collection and its contents to a new collection.

Parameters:	collection_id (str) – Collection ID. new_name (str) – New collection name.
Returns:	New collection ID.
Return type:	str

create(name, description, tags=None)[source]¶

Create a new collection.

Parameters:	name (str) – Display name for the collection. description (str) – Description for the collection. tags (str or list of strs, optional) – Optional comma-delimited keyword tags to be added to the collection.
Returns:	New collection ID.
Return type:	str

destroy(collection_id)[source]¶

Delete an empty collection.

If the collection is not empty, delete will fail. Use the empty method to remove all imagery before calling this method.

Parameters:	collection_id (str) – Collection to delete.
Returns:	{ok: true}
Return type:	dict

empty(collection_id)[source]¶

Bulk remove (up to 1000) images from a collection.

Parameters:	collection_id (str) – Collection to empty.
Returns:	{ok: true, total: 1000}
Return type:	dict

images(collection_id, camera=None, old_flag=False)[source]¶

Get all image names in a given collection.

When using the optional camera input parameter only images from that camera will be returned.

Parameters:	collection_id (str) – Collection ID. camera (str, optional) – Camera ID to be found. old_flag (bool, optional) – Flag for finding old format image names. When True images that do not contain md5 hashes at the start of their name will be found.
Returns:	Image names.
Return type:	list of strs

index(**kwargs)[source]¶

Get collections matching the provided spatial, text, or metadata filters.

The maximum skip value is 4000. If this is reached, truncated results will be returned. You will need to refine your query to avoid this.

Parameters:	**kwargs – Any keyword arguments found in the collections_index_documentation.
Returns:	A tuple containing: feature_collection (`CollectionsFeatureCollection`): Collections feature collection. failed (list of `Record`): Failed API call records.
Return type:	tuple

remove_image(names, collection_id)[source]¶

Remove images from a collection.

Parameters:

names (str or list of strs) – List of image names to be removed.
collection_id (str) – Collection ID to remove images from.

Returns:

A tuple containing:

succeeded (list of Record):: Successful API call records.
failed (list of Record):: Failed API call records.

Return type:

tuple

show(collection_id, limit=200, marker=None)[source]¶

Get the attributes and image list for collections.

The results will also contain image names available in the collection. These are limited to a maximum of 200 per query.

Parameters:	collection_id (str) – Collection ID. limit (int, optional) – Number of image names to be returned with each response. Defaults to 200. Max value of 200 is allowed. marker (str, optional) – Pagination marker. If the marker is an exact match to an existing image, the next image after the marker will be the first image returned. Therefore, for normal linked list pagination, specify the last image name from the current response as the marker value in the next request. Partial file names may be specified, in which case the first matching result will be the first image returned.
Returns:	A single collection feature.
Return type:	`CollectionsFeature`

show_image(image_names, collection_id, out_dir=None, return_image_data=False)[source]¶

Get images from a collection.

Parameters:

image_names (str or list of strs) – Image names.
collection_id (str) – Collection ID to add images into.
out_dir (optional, str) – Directory to write images to. Defaults to None.
return_image_data (optional, bool) – If True images will be available as PIL images in the returned ImageRecords. Defaults to False.

Returns:

A tuple containing:

images (list of ImageRecord):: All received images.
failed (ImageRecord):: Failed API calls.

Return type:

tuple

update(collections_id, name=None, description=None, tags=None)[source]¶

Update a collection.

Parameters:	collections_id (str) – Collection ID. name (str, optional) – Name to be changed to. description (str, optional) – Description to be changed to. tags (str or list of strs, optional) – Optional comma-delimited keyword tags to be changed to.
Returns:	Json response.
Return type:	dict

class helios.collections_api.CollectionsFeature(feature)[source]¶

Individual Collection JSON result.

bucket¶

‘bucket’ value for the result.

Type:	str

created_at¶

‘city’ value for the result.

Type:	str

description¶

‘created_at’ value for the result.

Type:	str

id¶

‘_id’ value for the result.

Type:	str

images¶

‘images’ value for the result.

Type:	list of strs

json¶

Raw JSON result.

Type:	dict

name¶

‘name’ value for the result.

Type:	str

tags¶

‘tags’ value for the result.

Type:	list of strs

updated_at¶

‘updated_at’ value for the result.

Type:	str

user_id¶

‘user_id’ value for the result.

Type:	str

class helios.collections_api.CollectionsFeatureCollection(features)[source]¶

Collection of features obtained via the Collections API.

Convenience properties are available to extract values from every feature.

features¶

All features returned from a query.

Type:	list of `CollectionsFeature`

bucket¶: ‘bucket’ values for every result.

created_at¶: ‘city’ values for every result.

description¶: ‘created_at’ values for every result.

id¶: ‘_id’ values for every result.

json¶: Raw ‘json’ for every feature.

name¶: ‘name’ values for every result.

tags¶: ‘tags’ values for every result.

updated_at¶: ‘updated_at’ values for every result.

user_id¶: ‘user_id’ values for every result.