def get_annotations(self, **options):
"""Get annotations. Requires processing=false. Note: you need to provide at least one of the three ids to query"""
(endpoint, method) = self.endpoints["get_annotations"]
detector_id = options.get("detectorId")
label_ids = options.get("labelIds")
image_id = options.get("imageId")
if not detector_id and not label_ids and not image_id:
raise error.InvalidQueryError(
message=
"Missing required parameter: detectorId, labelIds or imageId")
try:
headers = {"Authorization": self.token.authorization_header()}
params = {
"detectorId": detector_id,
"labelIds": label_ids,
"imageId": image_id,
}
return requests.request(method, endpoint, **{
"headers": headers,
"params": params
})
except Exception as e:
raise error.APIConnectionError(message=e)
def get_video_results(self, videoId, **options):
"""
Get the current classifications for a given video ID
videoId: a unique id for the classified video
threshold: the cutoff for confidence level in the detection at each timestamp
format: 'csv' or 'json' for the response format
"""
(endpoint, method) = self.endpoints["get_video_results"]
if options.get("format") == "csv" and self.json_format:
print(
"cannot return csv format when json_format True is specified upon API object initialization"
)
print("requesting JSON format...")
format = "json"
endpoint = endpoint.replace(":key", videoId)
try:
headers = {"Authorization": self.token.authorization_header()}
params = {
"videoId": videoId,
}
params.update(options)
return requests.request(
method, endpoint, **{"headers": headers, "params": params}
)
except Exception as e:
raise error.APIConnectionError(message=e)
def get_video_results(self, video_id, threshold=1, response_format='json'):
"""
Get the current classifications for a given video ID
video_id: a unique id for the classified video
threshold: the cutoff for confidence level in the detection at each timestamp
response_format: 'csv' or 'json' for the response format
"""
(endpoint, method) = self.endpoints['get_video_results']
if response_format == 'csv' and self.json_format:
print(
'cannot return csv format when json_format True is specified upon API object initialization'
)
print('requesting JSON format...')
response_format = 'json'
endpoint = endpoint.replace(':key', video_id)
try:
headers = {'Authorization': self.token.authorization_header()}
params = {
'videoId': video_id,
'threshold': threshold,
'format': response_format
}
return requests.request(method, endpoint, **{
'headers': headers,
'params': params
})
except Exception as e:
raise error.APIConnectionError(message=e)
def create_detector(self, zip_file, name, detector_type):
"""
Create a new detector with the contents of the zip file
detector_type: general, facial_recognition, or facial_characteristics
name: the detector's display name
zip_file: a zip file containing the images to be used in the detector creation
the root folder should contain only directories which will become the labels for detection
each of these directories should contain only images corresponding to that label.
However, there is an exception if you want to add negative examples to a label.
In that case, put the negative images for the label in a folder called "negative" inside the corresponding label.
To include bounding boxes, include one file called bbox.csv in the top level directory.
Each line of this file should be formatted as follows:
0.25, 0.3, 0.75, 0.8, cat, positive, image.jpg
0.25, 0.4, 0.55, 0.7, dog, positive, picture.jpg
0.0, 0.1, 0.2, 0.3, cat, negative, raccoon.jpg
Column definitions:
top left X coordinate, top left Y coordinate, bottom right X coordinate, bottom right Y coordinate, label, positive or negative example, file name
Max 300 MB zip file upload
structure example:
cat/
garfield.jpg
nermal.png
dog/
odie.TIFF
negative/
lobo.jpg
bbox.csv
"""
MAX_LOCAL_ZIP_SIZE = 300 * 1024 * 1024
(endpoint, method) = self.endpoints['create_detector']
try:
headers = {'Authorization': self.token.authorization_header()}
data = {'name': name, 'detector_type': detector_type}
with self.filereader.get_file(zip_file) as file_to_upload:
files = {'file': file_to_upload}
file_size = os.fstat(file_to_upload.fileno()).st_size
if file_size > MAX_LOCAL_ZIP_SIZE:
raise error.InvalidQueryError(
message=
'File %s is larger than the limit of %d megabytes' %
(file_to_upload.name,
self.bytes_to_mb(MAX_LOCAL_ZIP_SIZE)))
return requests.request(
method, endpoint, **{
'headers': headers,
'files': files,
'data': data
})
except Exception as e:
raise error.APIConnectionError(message=e)
def retrieve_token(self, options={}):
"""
Generates an OAuth token. The API client will intelligently refresh the Access Token for you
However, if you would like to manually expire an existing token and create a new token,
call this method manually and pass in 'expire_token': True in the options argument.
In addition, you would have to refresh manually if another client has expired your access token.
You can pass the 'request_from_server': True option to make a request
to the server for the access token without invalidating it. This is useful if you are running
multiple clients with the same token so they don't endlessly refresh each others' tokens
"""
(endpoint, method) = self.endpoints['token']
if not options.get('expire_token') and not options.get(
'request_from_server'):
if self.token and not self.token.expired():
return self.token
try:
query_data = {
'grant_type': self.grant_type,
'client_id': self.client_id,
'client_secret': self.client_secret
}
if options.get('expire_token'):
query_data['refresh'] = 'true'
response = requests.request(method, endpoint, data=query_data)
except Exception as e:
raise error.APIConnectionError(message=e)
self.check_errors(response, error.AuthorizationError)
self.save_token(response)
def create_label_with_images(self, detectorId, name, imageFiles, **options):
"""Create a label. Requires processing=false. Creates label asynchronously (turn processing to true)"""
(endpoint, method) = self.endpoints["create_label_with_images"]
endpoint = endpoint.replace(":key", detectorId)
try:
headers = {"Authorization": self.token.authorization_header()}
data = {
"name": name,
"destination": options.get("destination"),
}
if options.get("bboxes"):
data["bboxes"] = json.dumps(options.get("bboxes"))
if not isinstance(imageFiles, list):
imageFiles = [imageFiles]
return batch_file_request(imageFiles, method, endpoint, headers, data,
"imageFiles")
except IOError as e:
raise e
except error.InvalidQueryError as e:
raise e
except Exception as e:
raise error.APIConnectionError(message=e)
def classify_video(self, detector_id, video_url=None, video_file=None):
"""
Classify a video from a url with a detector
detector_id: a unique id for the detector
video_url: internet URL for the video to classify
"""
MAX_LOCAL_VIDEO_SIZE = 300 * 1024 * 1024
(endpoint, method) = self.endpoints['classify_video']
if not video_url and not video_file:
raise error.InvalidQueryError(
message='Missing required parameter: video_url or video_file')
if video_url and video_file:
raise error.InvalidQueryError(
message=
'Cannot classify a URL and local file in the same request')
if isinstance(video_file, list):
raise error.InvalidQueryError(
message='Only one video can be uploaded at a time')
endpoint = endpoint.replace(':key', detector_id)
try:
headers = {'Authorization': self.token.authorization_header()}
data = {'detector_id': detector_id}
if video_url:
data['url'] = video_url
return requests.request(method, endpoint, **{
'headers': headers,
'data': data
})
elif video_file:
with self.filereader.get_file(video_file) as file_to_upload:
files = {'file': file_to_upload}
file_size = os.fstat(file_to_upload.fileno()).st_size
if file_size > MAX_LOCAL_VIDEO_SIZE:
raise error.InvalidQueryError(
message=
'File %s is larger than the limit of %d megabytes'
% (file_to_upload.name,
self.bytes_to_mb(MAX_LOCAL_VIDEO_SIZE)))
return requests.request(
method, endpoint, **{
'headers': headers,
'files': files,
'data': data
})
except error.InvalidQueryError as e:
raise e
except Exception as e:
raise error.APIConnectionError(message=e)
def list_detectors(self):
"""Lists the available detectors"""
(endpoint, method) = self.endpoints["list_detectors"]
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def classify_video(self, detectorId, url=None, file=None, **options):
"""
Classify a video from a url with a detector
detectorId: a unique id for the detector
url: internet URL for the video to classify
"""
MAX_LOCAL_VIDEO_SIZE = 300 * 1024 * 1024
(endpoint, method) = self.endpoints["classify_video"]
if not url and not file:
raise error.InvalidQueryError(message="Missing required parameter: url or file")
if url and file:
raise error.InvalidQueryError(
message="Cannot classify a URL and local file in the same request"
)
if isinstance(file, list):
raise error.InvalidQueryError(
message="Only one video can be uploaded at a time"
)
endpoint = endpoint.replace(":key", detectorId)
try:
headers = {"Authorization": self.token.authorization_header()}
data = {"detectorId": detectorId}
data.update(options)
if url:
data["url"] = url
return requests.request(
method, endpoint, **{"headers": headers, "data": data}
)
elif file:
with self.filereader.get_file(file) as file_to_upload:
files = {"file": file_to_upload}
file_size = os.fstat(file_to_upload.fileno()).st_size
if file_size > MAX_LOCAL_VIDEO_SIZE:
raise error.InvalidQueryError(
message="File %s is larger than the limit of %d megabytes"
% (file_to_upload.name, self.bytes_to_mb(MAX_LOCAL_VIDEO_SIZE))
)
return requests.request(
method,
endpoint,
**{"headers": headers, "files": files, "data": data},
)
except error.InvalidQueryError as e:
raise e
except Exception as e:
raise error.APIConnectionError(message=e)
def kill_monitoring(self, monitoringId):
(endpoint, method) = self.endpoints["kill_monitoring"]
endpoint = endpoint.replace(":key", monitoringId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def import_detector(self, name, **options):
"""
Note: certain combination of parameters can be supplied: file_detector, file_proto + file_label (+ file_label_ind), or file_proto + labels (+ label_inds). Parentheses part can be optionally supplied for object detection.
"""
(endpoint, method) = self.endpoints["import_detector"]
data = {
"name": name,
}
def get_data_info():
data["inputTensor"] = (options.get("inputTensor"), )
data["outputTensor"] = (options.get("outputTensor"), )
data["detectorType"] = (options.get("detectorType"), )
if options.get("fileDetector"):
file_paths = {"fileDetector": options.get("fileDetector")}
elif options.get("fileProto") and options.get("fileLabel"):
file_paths = {
"fileProto": options.get("fileProto"),
"fileLabel": options.get("fileLabel"),
"fileLabelInd": options.get("fileLabelInd"),
}
get_data_info()
elif options.get("fileProto") and options.get("labels"):
file_paths = {
"fileProto": options.get("fileProto"),
}
data["labels"] = options.get("labels")
data["labelInds"] = options.get("labelInds")
get_data_info()
else:
raise error.InvalidQueryError(message="Invalid parameter combination")
file_objs = {}
for file_keyword, file_path in file_paths.items():
file_obj = self.filereader.get_file(file_path)
file_objs[file_keyword] = file_obj
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(
method, endpoint, **{
"headers": headers,
"files": file_objs,
"data": data
})
except IOError as e:
raise e
except error.InvalidQueryError as e:
raise e
except Exception as e:
raise error.APIConnectionError(message=e)
finally:
for file_keyword, file_obj in file_objs.items():
if isinstance(file_obj, io.IOBase):
file_obj.close()
def delete_stream(self, streamId):
(endpoint, method) = self.endpoints["delete_stream"]
endpoint = endpoint.replace(":key", streamId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def account_info(self):
"""Get user account and credits information"""
(endpoint, method) = self.endpoints['account_info']
try:
headers = {'Authorization': self.token.authorization_header()}
return requests.request(method, endpoint, **{'headers': headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def get_collection(self, collectionId):
"""Get information about a specific collection"""
(endpoint, method) = self.endpoints["get_collection"]
endpoint = endpoint.replace(":key", collectionId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def delete_collection_index(self, taskId):
"""Deletes a completed collection mananger task"""
(endpoint, method) = self.endpoints["delete_collection_index"]
endpoint = endpoint.replace(":key", taskId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def get_collection_task(self, taskId):
"""Creates a new collection from a web or S3 url"""
(endpoint, method) = self.endpoints["get_collection_task"]
endpoint = endpoint.replace(":key", taskId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def get_label_images(self, detectorId, labelId):
(endpoint, method) = self.endpoints["get_label_images"]
endpoint = endpoint.replace(":detectorId", detectorId)
endpoint = endpoint.replace(":labelId", labelId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def delete_collection(self, collectionId):
"""Deletes a collection with no active indexing tasks"""
(endpoint, method) = self.endpoints["delete_collection"]
endpoint = endpoint.replace(":key", collectionId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def delete_label(self, detectorId, labelId):
"""Delete a label. Requires processing=false"""
(endpoint, method) = self.endpoints["delete_label"]
endpoint = endpoint.replace(":detectorId", detectorId)
endpoint = endpoint.replace(":labelId", labelId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def detector_info(self, detector_id):
"""Get information about detector"""
(endpoint, method) = self.endpoints['detector_info']
endpoint = endpoint.replace(':key', detector_id)
try:
headers = {'Authorization': self.token.authorization_header()}
return requests.request(method, endpoint, **{'headers': headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def list_detectors(self, **query):
"""Lists the available detectors"""
(endpoint, method) = self.endpoints['detectors']
try:
headers = {'Authorization': self.token.authorization_header()}
params = {x: str(query[x]).lower() for x in query}
return requests.request(method, endpoint, **{
'headers': headers,
'params': params
})
except Exception as e:
raise error.APIConnectionError(message=e)
def register_stream(self, stream_url, stream_name):
(endpoint, method) = self.endpoints['register_stream']
try:
headers = {'Authorization': self.token.authorization_header()}
data = {'name': stream_name, 'url': stream_url}
return requests.request(method, endpoint, **{
'headers': headers,
'data': data
})
except Exception as e:
raise error.APIConnectionError(message=e)
def delete_feedback(self, feedbackId, detectorId):
"""Delete previously given feedback"""
(endpoint, method) = self.endpoints["delete_feedback"]
endpoint = endpoint.replace(":detector_id", detectorId)
endpoint = endpoint.replace(":feedback_id", feedbackId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except error.InvalidQueryError as e:
raise e
except Exception as e:
raise error.APIConnectionError(message=e)
def search_monitorings(self, **options):
(endpoint, method) = self.endpoints["search_monitorings"]
try:
headers = {"Authorization": self.token.authorization_header()}
params = {}
params.update(options)
return requests.request(method, endpoint, **{
"headers": headers,
"params": params
})
except Exception as e:
raise error.APIConnectionError(message=e)
def create_stream(self, url, name, **options):
(endpoint, method) = self.endpoints["create_stream"]
try:
headers = {"Authorization": self.token.authorization_header()}
data = {"name": name, "url": url}
data.update(options)
return requests.request(method, endpoint, **{
"headers": headers,
"data": data
})
except Exception as e:
raise error.APIConnectionError(message=e)
def update_collection_index(self, taskId, updateIndex):
"""Update a collection index"""
(endpoint, method) = self.endpoints["update_collection_index"]
endpoint = endpoint.replace(":key", taskId)
try:
headers = {"Authorization": self.token.authorization_header()}
data = {"updateIndex": "true" if updateIndex else "false"}
return requests.request(method, endpoint, **{
"headers": headers,
"data": data
})
except Exception as e:
raise error.APIConnectionError(message=e)
def create_collection_index(self, collectionId, detectorId, fileTypes):
"""Create an index on a collection with a detector"""
(endpoint, method) = self.endpoints["create_collection_index"]
endpoint = endpoint.replace(":key", collectionId)
try:
headers = {"Authorization": self.token.authorization_header()}
data = {"detectorId": detectorId, "fileTypes": fileTypes}
return requests.request(method, endpoint, **{
"headers": headers,
"data": data
})
except Exception as e:
raise error.APIConnectionError(message=e)
def delete_detector(self, detectorId):
"""
Requires processing=false.
Note: Users can only delete pending detectors; once finalized, the only way to delete is via the Web UI.
"""
(endpoint, method) = self.endpoints["delete_detector"]
endpoint = endpoint.replace(":key", detectorId)
try:
headers = {"Authorization": self.token.authorization_header()}
return requests.request(method, endpoint, **{"headers": headers})
except Exception as e:
raise error.APIConnectionError(message=e)
def search_detectors(self, **query):
"""Lists the available detectors"""
(endpoint, method) = self.endpoints["detectors"]
try:
headers = {"Authorization": self.token.authorization_header()}
params = {x: str(query[x]).lower() for x in query}
params["published"] = "true" if query.get("published") else "false"
return requests.request(method, endpoint, **{
"headers": headers,
"params": params
})
except Exception as e:
raise error.APIConnectionError(message=e)
def kill_collection_index(self, taskId, includeCollectionInfo):
"""Kills an active collection indexing task"""
(endpoint, method) = self.endpoints["kill_collection_index"]
endpoint = endpoint.replace(":key", taskId)
try:
headers = {"Authorization": self.token.authorization_header()}
data = {
"includeCollectionInfo": "true" if includeCollectionInfo else ""
}
return requests.request(method, endpoint, **{
"headers": headers,
"data": data
})
except Exception as e:
raise error.APIConnectionError(message=e)