Deepomatic API v0.7
Search…
⌃K

Recognition Version

Version object

Definition

A recognition version implements a specification: this is the link between a specification and a neural network.
Attribute
Type
Attributes
Description
id
int
read-only
The ID of the recognition version.
spec_id
int
immutable
The ID of the parent recognition specification.
network_id
int
immutable
The ID of the neural network which will cary on the computation.
post_processings
object
immutable
The post-processing object that defines some network specific adjustments like the output tensor, some thresholds, etc. The length of this array must exactly match the length of the outputs field of the parent specification and the i-th post-processing will be matched to the i-th output.
spec_name
string
read-only
The name of the recognition specification corresponding to spec_id. This is convenient for display purposes.
network_name
string
read-only
The name of the neural network corresponding to network_id. This is convenient for display purposes.
update_date
string
read-only
Date time (ISO 8601 format) of the creation specification version.

Post-processing

The fields of this object are mutually exclusive: you must specify exactly one of them.
Attribute
Type
Description
classification
object
A post-processing of type classification for an output of type labels.
detection
object
A post-processing of type detection for an output of type labels.

Classification post-processing

Attribute
Type
Description
output_tensor
string
The name of the network tensor that holds the classification scores.
thresholds
array(float)
A list of threshold for each label of the recognition specification. The label will be considered present if its score is greater than the threshold. The length of this array must exactly match the length of the labels field of the parent labels specification and the i-th threshold will be matched to the i-th label.

Detection post-processing

You must specify exactly one of the anchored_output, direct_output or yolo_output fields. When we specify an expected tensor size in the description of those fields, we omit the first dimension of the tensor (i.e. the batch size).
Attribute
Type
Description
anchored_output
object
(optional) Some neural networks output some anchor bounding boxes together with the offsets to apply to those anchors to get the final bounding boxes. Use this if this is the case of your network. This object must have the following fields:
  • scores_tensor: the name of the output tensor containing the scores for each label and box. It must be of size N x (L + 1)where N is the number of region proposals and L is the number of labels in the recognition specification. The background score must be the additional first column of the tensor.
  • anchors_tensor: the name of the output tensor containing the anchors. It must be of size N x 5where the 1st column is the region proposal score, the 2nd and 3rd columns are the x and ycoordinates of the upper-left corner and the 4th and 5th columns are its width and height.
  • offsets_tensor: the name of the output tensor containing the offsets for each classe (including background) and anchor. It must be of size N * (L + 1) * 4 where the first 4 columns correspond to the background label and column order is the same as above: x, y, width, height.
direct_output
object
(optional) Some neural networks directly output the final bounding boxes. Use this if this is the case of your network. This object must have the following fields:
  • scores_tensor: the name of the output tensor containing the scores for each label and box. It must be of size N x 1 where Nis the number of region proposals in the recognition specification.
  • classes_tensor: the name of the output tensor containing the classes for each label and box. It must be of size N x 1 where Nis the number of region proposals in the recognition specification. Be careful, it will contain the ids of the classes mapped in the specification, not the row number of the corresponding label.
  • boxes_tensor: the name of the output tensor containing the boxes. It must be of size N x 4where the 4 columns correspond to ymin, xmin, ymax and xmaxcoordinates of the bounding boxes, xminand ymin being the coordinates of the upper-left corner.
yolo_output
object
(optional) Yolo typically outputs, in the same tensor, both (i) the class scores and (ii) the offsets regarding to some predefined anchors. Use this if you are deploying a Yolo network. This object must have the following fields:
  • anchors: an array of X and Y dimensions for the anchors as found in the .meta file generated at training time. It must be of length B * 2 where B is the number of boxes per anchor. It starts with the X dimension (width) of the first box, then its Y dimension (height), then the width of the second box, etc...
  • output_tensor: the name of the output tensor containing both the scores for each label and the offset comparing to anchor boxes. It must be of size H x W x (B * (5 + L))where H and W can be any number (those are the final tensor height and width), B is the same as for the anchors field and L is the number of labels.
thresholds
array(float)
A list of threshold for each label of the recognition specification. The label will be considered present if its score is greater than the threshold. The length of this array must exactly match the length of the labels field of the parent labels specification and the i-th threshold will be matched to the i-th label.
nms_threshold
float
The Jaccard index threshold that will be applied to NMS to decide if two boxes of the same label represent the same object.
normalize_wrt_tensor
string
(optional) If your neural network outputs coordinates which are not normalised, use this field to specify a tensor that would hold the input image size (image height must be the first element of the tensor, image width the second element). Can be left blank if not used.

Definition

Creates a new recognition version.
cURL
POST https://api.deepomatic.com/v0.7/recognition/versions

Arguments

Parameter
Type
Default
Description
spec_id
int
The ID of the parent recognition specification.
network_id
int
The ID of the neural network which will cary on the computation.
post_processings
object
The post-processing object that defines some network specific adjustments like the output tensor, some thresholds, etc. The length of this array must exactly match the length of the outputs field of the parent specification and the i-th post-processing will be matched to the i-th output.

Code sample

cURL
Python
curl https://api.deepomatic.com/v0.7/recognition/versions \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-d '{
"spec_id": 42,
"network_id": 123,
"post_processings": [{"classification": {"output_tensor": "inception_v3/logits/predictions", "thresholds": [0.025, 0.025]}}]
}' \
-H "Content-Type: application/json"
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
client.RecognitionVersion.create(
spec_id=42,
network_id=123,
post_processings=[{
"classification": {
"output_tensor": "inception_v3/logits/predictions",
"thresholds": [
0.5,
0.5
]
}
}]
)

Response

JSON
{
"id": 1,
"spec_id": 42,
"spec_name": "hot-dog VS not hot-dog classifier",
"network_id": 123,
"network_name": "hot-dog VS not hot-dog classifier",
"update_date": "2018-03-09T18:30:43.404610Z",
"post_processings": [{
"classification": {
"output_tensor": "inception_v3/logits/predictions",
"thresholds": [
0.5,
0.5
]
}
}]
}

List versions

Definition

Get the list of existing recognition versions.
cURL
Python
# To access all your versions, use:
GET https://api.deepomatic.com/v0.7/recognition/versions
# To access versions attached to a given recognition spec, use:
GET https://api.deepomatic.com/v0.7/recognition/specs/{SPEC_ID}/versions
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
# To access all your versions, use:
client.RecognitionVersion.list()
# To access versions attached to a given recognition spec, use:
client.RecognitionSpec.retrieve({SPEC_ID}).versions()

Code sample

cURL
Python
# To access all your versions:
curl https://api.deepomatic.com/v0.7/recognition/versions \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
# To access versions attached to a given recognition spec, use:
curl https://api.deepomatic.com/v0.7/recognition/specs/42/versions \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
# To access all your versions, use:
for version in client.RecognitionVersion.list():
print(version)
# To access versions attached to a given recognition spec, use:
for version in client.RecognitionSpec.retrieve(42).versions():
print(version)

Response

A paginated list of responses.
Attribute
Type
Description
count
int
The total number of results.
next
string
The URL to the next page.
previous
string
The URL to the previous page.
results
array(object)
A list of your recognition version objects. Please note that the post_processings field is not present.
JSON
{
"count": 2,
"next": null,
"previous": null,
"results": [
{
"id": 1,
"spec_id": 42,
"spec_name": "hot-dog VS not hot-dog classifier",
"network_id": 123,
"network_name": "hot-dog VS not hot-dog classifier",
"update_date": "2018-03-09T18:30:43.404610Z"
},
...
]
}

Retrieve a version

Definition

Retrieve a recognition version by ID.
cURL
GET https://api.deepomatic.com/v0.7/recognition/versions/{VERSION_ID}

Arguments

Parameter
Type
Default
Description
version_id
int
The ID of the version to retrieve.

Code sample

cURL
Python
curl https://api.deepomatic.com/v0.7/recognition/versions/1 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
client.RecognitionVersion.retrieve(1)

Response

Delete a version

Definition

Permanently deletes a recognition version.
cURL
DELETE https://api.deepomatic.com/v0.7/recognition/versions/{VERSION_ID}
This cannot be undone.

Arguments

Parameter
Type
Default
Description
version_id
int
The ID of the version to delete.

Code sample

cURL
Python
curl https://api.deepomatic.com/v0.7/recognition/versions/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-X DELETE
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
version = client.RecognitionVersion.retrieve(42)
version.delete()

Response

Return 204 (no content).

Version inference

Definition

Run inference on this specification version. This endpoint returns a task ID. Please refer to the Specification Inference to have a comprehensive list of the inference request arguments and response.
cURL
POST https://api.deepomatic.com/v0.7/recognition/versions/{VERSION_ID}/inference

Code sample

cURL
Python
curl https://api.deepomatic.com/v0.7/recognition/versions/1/inference \
-X POST
-H "Content-Type: application/json" \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-d '{"inputs": [{"image": {"source": "https://static.deepomatic.com/resources/demos/api-clients/dog2.jpg"}}]}'
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
version = client.RecognitionVersion.retrieve(1)
url = "https://static.deepomatic.com/resources/demos/api-clients/dog2.jpg"
version.inference(inputs=[deepomatic.ImageInput(url)])

Response

A task JSON.
JSON
{
"task_id": "123"
}