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

immutable

A pre-processing object to describe how input data should be pre-processed.

postprocessings

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

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

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

A simple ordered list of tensor names.

standard_output

[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.

POST https://api.deepomatic.com/v0.7/networks

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 2.9

preprocessing

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

# 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

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:

# 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}"

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

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:

# 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}

Arguments

Parameter
Type
Default
Description

network_id

int

The ID of the neural network to get.

Code sample

# 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}"

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.

PATCH https://api.deepomatic.com/v0.7/networks/{NETWORK_ID}

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 https://api.deepomatic.com/v0.7/networks/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-d '{"name": "new name", "description":"new description"}' \
-X PATCH

Response

A neural networks object.

Delete a network

Definition

Permanently deletes a network. This cannot be undone.

DELETE https://api.deepomatic.com/v0.7/networks/{NETWORK_ID}

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 https://api.deepomatic.com/v0.7/networks/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-X DELETE

Response

Return 204 (no content).

Last updated