Neural Networks

Network object
A neural network object describes how input data should be preprocessed to be able to perform a simple inference and get raw output features from any layer.
Parameter
Type
Attributes
Description
id
int
read-only
The ID of the neural network.
name
string
​
A short name for your network.
description
string
​
A longer description of your network.
update_date
string
read-only
Date time (ISO 8601 format) of the last update of the network.
metadata
object
​
A JSON field containing any kind of information that you may find interesting to store.
framework
string
immutable
A string describing which framework to use for your network. Possible values are: 
tensorflow-1.x: support Tensorflow models up to version 2.9
preprocessing
​object​
immutable
A pre-processing object to describe how input data should be pre-processed.
postprocessings
array(object)
immutable
An array of post-processing object to list output tensors.
task_id
int
read-only
ID of the task containing the deployment status of the network.
Once the network has been created, you cannot modify the preprocessing field anymore.
Pre-processing object
This object describes how data should be preprocessed for each input of the network.
Parameter
Type
Description
inputs
array(object)
A list of Input Preprocessing Object. The order matters as input data will be fed in the same order at inference time.
batched_output
bool
[deprecated] Set this value to True
Input pre-processing
Parameter
Type
Description
tensor_name
string
The name of the input tensor that this input will feed.
image
​object​
An Image Preprocessing Object. Currently, the only supported input type.
Image pre-processing
Parameter
Type
Description
dimension_order
string
A value describing the order of the dimensions in a batch N = batch_size, C = Channel, H = Height, W = Width Possible values are:
NCHW
NCWH
NHWC
NWHC
resize_type
string
​
Possible values are:
SQUASH: image is resized to fit network input, losing aspect ratio.
CROP: image is resized so that the smallest side fits the network input, the rest is cropped.
FILL: image is resized so that the largest side fits the network input, the rest is filled with white.
NETWORK: image is resized so that its largest side fits target_size (see below) and the network is reshaped accordingly.
target_size
string
​
Target size of the input image. It might have multiple formats. In the following W, H and N denote integer numbers, W (and H) being used specifically for width (and height), respectively:
WxH: image is resized so that width and height fit the specified sizes.
N: image is resized so that the largest side of the input image matches the specified number of pixels.
color_channels
string
Might be RGB, BGR or L (for gray levels).
pixel_scaling
float
Pixel values will be normalized between 0 and pixel_scaling before mean subtraction.
Post-processing object
This object maps output tensors to a specific function in order to interpret them thanks to recognition versions.
You must specify exactly one of the tensors_output or standard_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
tensors_output
​object​
A simple ordered list of tensor names.
standard_output
​object​
[deprecated] A post-processing specific to detection.
Default post-processing
Attribute
Type
Description
tensors
array(string)
A simple ordered list of tensor names.
Standard post-processing (deprecated)
Attribute
Type
Description
boxes_tensor
string
The name of the output tensor containing the boxes. It must be of size N x 4where N is the number of detected regions and the 4 columns correspond to xmin, ymin, xmax and ymaxcoordinates of the bounding boxes, xminand ymin being the coordinates of the upper-left corner.
scores_tensor
string
The name of the output tensor containing the scores for each label and box. It must be of size N x K where Kis the number of labels in the recognition specification.
Create a network
Definition
Creates a new custom network after you have trained a model of your own on your infrastructure.
cURL
Python
POST https://api.deepomatic.com/v0.7/networks
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
client.Network.create(...)
Arguments
Parameter
Type
Default
Description
name
string
​
A short name for your network.
description
string
​
A longer description of your network.
metadata
object
{}
A JSON field containing any kind of information that you may find interesting to store.
framework
string
​
A string describing which framework to use for your network. Possible values are:
tensorflow-1.x: Tensorflow: currently version 1.15
preprocessing
​object​
​
A preprocessing object to describe how input data should be pre-processed.
<additionnal-files>
file
​
Extra files for network graph and weights, as well as mean files needed by the preprocessing. See below.
Once the network has been created, you cannot modify the preprocessing field anymore.
Code sample
cURL
Python
# We download the Caffe a GoogleNet pre-trained network
curl -o /tmp/deploy.prototxt https://raw.githubusercontent.com/BVLC/caffe/master/models/bvlc_googlenet/deploy.prototxt
curl -o /tmp/snapshot.caffemodel http://dl.caffe.berkeleyvision.org/bvlc_googlenet.caffemodel
curl -o /tmp/caffe_ilsvrc12.tar.gz http://dl.caffe.berkeleyvision.org/caffe_ilsvrc12.tar.gz
tar -zxvf /tmp/caffe_ilsvrc12.tar.gz -C /tmp
​
# Now proceed to upload
curl https://api.deepomatic.com/v0.7/networks \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-F name='my new network' \
-F description='trained with more images' \
-F metadata='{"author": "me", "project": "Go to mars"}' \
-F framework='nv-caffe-0.x-mod' \
-F preprocessing='{"inputs": [{"tensor_name": "data","image": {"dimension_order":"NCHW", "target_size":"224x224", "resize_type":"SQUASH", "mean_file": "mean_file_1.binaryproto", "color_channels": "BGR", "pixel_scaling": 255.0, "data_type": "FLOAT32"}}], "batched_output": true}' \
-F deploy.prototxt=@/tmp/deploy.prototxt \
-F snapshot.caffemodel=@/tmp/snapshot.caffemodel \
-F mean_file_1.binaryproto=@/tmp/imagenet_mean.binaryproto
import os
import sys
import tempfile
import shutil
import hashlib
import requests
import zipfile
​
from deepomatic.api.client import Client
​
if sys.version_info >= (3, 0):
    from urllib.request import urlretrieve
else:
    from urllib import urlretrieve
​
# Initialize the client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
# Helper function to download demo resources for the Caffe pre-trained networks
def download_file(url):
    _, ext = os.path.splitext(url)
    filename = os.path.join(tempfile.gettempdir(),
                            hashlib.sha1(url.encode()).hexdigest() + ext)
    print("Downloading {} to {}".format(url, filename))
    if os.path.exists(filename):  # avoid redownloading
        return filename
    r = requests.get(url, stream=True)
    r.raise_for_status()
    with open(filename, 'wb') as f:
        r.raw.decode_content = True
        shutil.copyfileobj(r.raw, f)
    return filename
​
​
# We download the Tensorflow Inception v3 pre-trained network
extract_dir = tempfile.gettempdir()
net_zip = download_file('https://s3-eu-west-1.amazonaws.com/deepo-public/run-demo-networks/imagenet-inception-v3/network.zip')
preproc_zip = download_file('https://s3-eu-west-1.amazonaws.com/deepo-public/run-demo-networks/imagenet-inception-v3/preprocessing.zip')
​
model_file_name = 'saved_model.pb'
variables_file_name = 'variables.index'
variables_data_file_name = 'variables.data-00000-of-00001'
mean_file_name = 'mean.proto.bin'
​
model_file = os.path.join(extract_dir, model_file_name)
mean_file = os.path.join(extract_dir, mean_file_name)
variables_file = os.path.join(extract_dir + '/variables/', variables_file_name)
variables_data_file = os.path.join(extract_dir + '/variables/', variables_data_file_name)
​
print("Extracting archive...")
if not os.path.exists(model_file):
    with zipfile.ZipFile(net_zip) as f:
        f.extractall(extract_dir)
if not os.path.exists(mean_file):
    with zipfile.ZipFile(preproc_zip) as f:
        f.extractall(extract_dir)
​
"""
Here, we specify the network preprocessing. Please refer to the documentation to see what each
field is used for.
"""
preprocessing = {
    "inputs": [
        {
            "tensor_name": "map/TensorArrayStack/TensorArrayGatherV3:0",
            "image": {
                "dimension_order": "NHWC",
                "target_size": "299x299",
                "resize_type": "CROP",
                "mean_file": mean_file_name,
                "color_channels": "BGR",
                "pixel_scaling": 2.0,
                "data_type": "FLOAT32"
            }
        }
    ],
    "batched_output": True
}
​
"""
We now register the three files needed by our network
"""
files = {
    model_file_name: open(model_file, 'rb'),
    variables_file_name: open(variables_file, 'rb'),
    variables_data_file_name: open(variables_data_file, 'rb'),
    mean_file_name: open(mean_file, 'rb')
}
​
"""
We now upload our new network via the 'client.Network().create(...)' network.
Please refere to the documentation for a description of each parameter.
"""
print("Uploading model to API...")
network = client.Network.create(name="My first network",
                                framework='tensorflow-1.x',
                                preprocessing=preprocessing,
                                files=files)
network_id = network['id']
print("Network ID = {}".format(network_id))
Network files
You will need to provide several additional files to create the network.
TensorFlow files
You need to specify at least one of those files for the tensorflow-1.x framework:
saved_model.pb: the file that specifies the the network architecture.
saved_model.pbtxt: same as above but serialised in it text format.
If the saved model does not embed the variables weights, you will need to specify additional files:
variables.data-00000-of-00001: the file that specifies variables' weights. It is usually located in a variables directory. Numbers can change but must respect those of your original file.
variables.index: the index of variables. It is usually located in a variables directory.
Pre-processing files
You might also include any additional file as required by you various input types, for exemple any mean file named as you like and whose name is referred by the mean_file parameter field of a pre-processing object as long it has one of the supported extensions, see the documentation.
Please refer to the Saving mean files code sample bellow to find out how to save you mean files before sending them to the API.
Saving mean files
In order to save numpy tensor means to files before sending them to the API, please proceed like this:
Python
import numpy as np
​
# example mean file when `dimension_order == "HWC"` and H = 1, W = 1 and C = 3
# typically, your mean image as been compute on the training images and you already
# have this tensor available.
example_mean_file = np.ones((1, 1, 3))
​
# Save this mean to 'mean.npy'
with open('mean.npy', 'wb') as f:
    np.save(f, mean, allow_pickle=False)
​
# You can now use `"mean_file": "mean.npy"` in the preprocessing JSON
# {
#   ...
#   "mean_file": "mean.npy"
#   ...
# }
Response
A neural network object, example response:
JSON
{
    "id": 42,
    "name": "My first network",
    "description": "A neural network trained on some data",
    "task_id": 123,
    "update_date": "2018-02-16T16:37:25.148189Z",
    "metadata": {
        "any": "value"
    },
    "preprocessing": {
        "inputs": [
            {
                "tensor_name": "data",
                "image": {
                    "dimension_order": "NCHW",
                    "target_size": "224x224",
                    "resize_type": "SQUASH",
                    "mean_file": "mean.proto.bin",
                    "color_channels": "BGR",
                    "pixel_scaling": 255.0,
                    "data_type": "FLOAT32"
                }
            }
        ],
        "batched_output": true
    }
}
List networks
Code sample
Lists all public and private networks:
cURL
Python
# For public networks:
curl https://api.deepomatic.com/v0.7/networks/public \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
​
# For private networks:
curl https://api.deepomatic.com/v0.7/networks \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
# For public networks:
for network in client.Network.list(public=True):
    print(network)
​
# For private networks:
for network in client.Network.list():
    print(network)
Response
A paginated list of responses.
Parameter
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 neural networks objects
Example response
JSON
{
    "count": 1,
    "next": null,
    "previous": null,
    "results": [
        {
            "id": 1,
            "name": "Alexnet",
            "description": "Alexnet",
            "task_id": "123",
            "update_date": "2018-02-16T13:45:36.078955Z",
            "metadata": {},
            "preprocessing": {
                "inputs": [
                    {
                        "tensor_name": "data",
                        "image": {
                            "dimension_order": "NCHW",
                            "target_size": "224x224",
                            "resize_type": "SQUASH",
                            "mean_file": "data_mean.proto.bin",
                            "color_channels": "BGR",
                            "pixel_scaling": 255.0,
                            "data_type": "FLOAT32"
                        }
                    }
                ],
                "batched_output": true
            }
        }
    ]
}
Retrieve a network
Definition
Retrieve a neural network by ID:
cURL
Python
# To retrieve a public network, use:
GET https://api.deepomatic.com/v0.7/networks/public/{NETWORK_ID}
​
# To retrieve your own network, use:
GET https://api.deepomatic.com/v0.7/networks/{NETWORK_ID}
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
# {NETWORK_ID} may be a string for a public
# network or an integer for your own network.
client.Network.retrieve({NETWORK_ID})
Arguments
Parameter
Type
Default
Description
network_id
int
​
The ID of the neural network to get.
Code sample
cURL
Python
# For a public network:
curl https://api.deepomatic.com/v0.7/networks/public/imagenet-inception-v1 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
​
# For a private network:
curl https://api.deepomatic.com/v0.7/networks/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}"
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
# For a public network:
client.Network.retrieve("imagenet-inception-v1")
​
# For a private network:
client.Network.retrieve(42)
Response
A neural networks object.
JSON
{
    "id": 1,
    "name": "Alexnet",
    "description": "Alexnet",
    "task_id": "123",
    "update_date": "2018-02-16T13:45:36.078955Z",
    "metadata": {},
    "preprocessing": {
        "inputs": [
            {
                "tensor_name": "data",
                "image": {
                    "dimension_order": "NCHW",
                    "target_size": "224x224",
                    "resize_type": "SQUASH",
                    "mean_file": "data_mean.proto.bin",
                    "color_channels": "BGR",
                    "pixel_scaling": 255.0,
                    "data_type": "FLOAT32"
                }
            }
        ],
        "batched_output": true
    }
}
Edit a network
Definition
Updates the specified network by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
This request accepts only the name and metadataarguments. Other values are immutable.
cURL
Python
PATCH https://api.deepomatic.com/v0.7/networks/{NETWORK_ID}
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
network = client.Network.retrieve({NETWORK_ID})
network.update(...)
Arguments
Parameter
Type
Attributes
Description
name
string
optionnal
A short name for your network.
description
string
optionnal
A longer description of your network.
metadata
object
optionnal
A JSON field containing any kind of information that you may find interesting to store.
Code sample
cURL
Python
curl https://api.deepomatic.com/v0.7/networks/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-d '{"name": "new name", "description":"new description"}' \
-X PATCH
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
network = client.Network.retrieve(42)
network.update(
    name="new name",
    description="new description"
)
Response
A neural networks object.
Delete a network
Definition
Permanently deletes a network. This cannot be undone.
cURL
Python
DELETE https://api.deepomatic.com/v0.7/networks/{NETWORK_ID}
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))
​
network = client.Network.retrieve({NETWORK_ID})
network.delete()
Attached resources such as recognition versions will also be suppressed.
Arguments
Parameter
Type
Default
Description
id
int
​
The Neural Network ID to delete.
Code sample
cURL
Python
curl https://api.deepomatic.com/v0.7/networks/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'))
​
network = client.Network.retrieve(42)
network.delete()
Response
Return 204 (no content).

Parameter	Type	Attributes	Description
id	int	read-only	The ID of the neural network.
name	string		A short name for your network.
description	string		A longer description of your network.
update_date	string	read-only	Date time (ISO 8601 format) of the last update of the network.
metadata	object		A JSON field containing any kind of information that you may find interesting to store.
framework	string	immutable	A string describing which framework to use for your network. Possible values are: `tensorflow-1.x`: support Tensorflow models up to version 2.9
preprocessing	object	immutable	A pre-processing object to describe how input data should be pre-processed.
postprocessings	array(object)	immutable	An array of post-processing object to list output tensors.
task_id	int	read-only	ID of the task containing the deployment status of the network.

Parameter	Type	Description
inputs	array(object)	A list of Input Preprocessing Object. The order matters as input data will be fed in the same order at inference time.
batched_output	bool	[deprecated] Set this value to `True`

Parameter	Type	Description
tensor_name	string	The name of the input tensor that this input will feed.
image	object	An Image Preprocessing Object. Currently, the only supported input type.

Parameter	Type	Description
dimension_order	string	A value describing the order of the dimensions in a batch N = batch_size, C = Channel, H = Height, W = Width Possible values are: `NCHW` `NCWH` `NHWC` `NWHC`
resize_type	string	Possible values are: `SQUASH`: image is resized to fit network input, losing aspect ratio. `CROP`: image is resized so that the smallest side fits the network input, the rest is cropped. `FILL`: image is resized so that the largest side fits the network input, the rest is filled with white. `NETWORK`: image is resized so that its largest side fits target_size (see below) and the network is reshaped accordingly.
target_size	string	Target size of the input image. It might have multiple formats. In the following `W`, `H` and `N` denote integer numbers, `W` (and `H`) being used specifically for width (and height), respectively: `WxH`: image is resized so that width and height fit the specified sizes. `N`: image is resized so that the largest side of the input image matches the specified number of pixels.
color_channels	string	Might be `RGB`, `BGR` or `L` (for gray levels).
pixel_scaling	float	Pixel values will be normalized between 0 and `pixel_scaling` before mean subtraction.

Attribute	Type	Description
tensors_output	object	A simple ordered list of tensor names.
standard_output	object	[deprecated] A post-processing specific to detection.

Attribute	Type	Description
tensors	array(string)	A simple ordered list of tensor names.

Attribute	Type	Description
boxes_tensor	string	The name of the output tensor containing the boxes. It must be of size `N x 4`where `N` is the number of detected regions and the 4 columns correspond to `xmin`, `ymin`, `xmax` and `ymax`coordinates of the bounding boxes, `xmin`and `ymin` being the coordinates of the upper-left corner.
scores_tensor	string	The name of the output tensor containing the scores for each label and box. It must be of size `N x K` where `K`is the number of labels in the recognition specification.

Parameter	Type	Default	Description
name	string		A short name for your network.
description	string		A longer description of your network.
metadata	object	{}	A JSON field containing any kind of information that you may find interesting to store.
framework	string		A string describing which framework to use for your network. Possible values are: `tensorflow-1.x`: Tensorflow: currently version 1.15
preprocessing	object		A preprocessing object to describe how input data should be pre-processed.
<additionnal-files>	file		Extra files for network graph and weights, as well as mean files needed by the preprocessing. See below.

Parameter	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 neural networks objects

Parameter	Type	Default	Description
network_id	int		The ID of the neural network to get.

Parameter	Type	Attributes	Description
name	string	optionnal	A short name for your network.
description	string	optionnal	A longer description of your network.
metadata	object	optionnal	A JSON field containing any kind of information that you may find interesting to store.

Parameter	Type	Default	Description
id	int		The Neural Network ID to delete.

Quick Start

Recognition Specification

Last modified 8d ago