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

<table><thead><tr><th width="179">Parameter</th><th width="134">Type</th><th width="115">Attributes</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>int</td><td>read-only</td><td>The ID of the neural network.</td></tr><tr><td>name</td><td>string</td><td></td><td>A short name for your network.</td></tr><tr><td>description</td><td>string</td><td></td><td>A longer description of your network.</td></tr><tr><td>update_date</td><td>string</td><td>read-only</td><td>Date time (ISO 8601 format) of the last update of the network.</td></tr><tr><td>metadata</td><td>object</td><td></td><td>A JSON field containing any kind of information that you may find interesting to store.</td></tr><tr><td>framework</td><td>string</td><td>immutable</td><td><p>A string describing which framework to use for your network. Possible values are: </p><ul><li><code>tensorflow-1.x</code>: support Tensorflow models up to version 2.9</li></ul></td></tr><tr><td>preprocessing</td><td><a href="/pages/-LZKqIf1mY6IjiPAv9Mg#pre-processing-object">object</a></td><td>immutable</td><td>A pre-processing object to describe how input data should be pre-processed.</td></tr><tr><td>postprocessings</td><td>array(<a href="#post-processing-object">object</a>)</td><td>immutable</td><td>An array of post-processing object to list output tensors.</td></tr><tr><td>task_id</td><td>int</td><td>read-only</td><td>ID of the task containing the deployment status of the network.</td></tr></tbody></table>

{% hint style="danger" %}
Once the network has been created, you cannot modify the `preprocessing` field anymore.
{% endhint %}

### Pre-processing object

This object describes how data should be preprocessed for each input of the network.

<table><thead><tr><th width="174.33333333333331">Parameter</th><th width="141">Type</th><th>Description</th></tr></thead><tbody><tr><td>inputs</td><td>array(<a href="#input-pre-processing">object</a>)</td><td>A list of Input Preprocessing Object. The order matters as input data will be fed in the same order at inference time.</td></tr><tr><td>batched_output</td><td>bool</td><td><em>[deprecated]</em> Set this value to <code>True</code></td></tr></tbody></table>

### **Input pre-processing**

<table><thead><tr><th width="174.33333333333331">Parameter</th><th width="143">Type</th><th>Description</th></tr></thead><tbody><tr><td>tensor_name</td><td>string</td><td>The name of the input tensor that this input will feed.</td></tr><tr><td>image</td><td><a href="/pages/-LZKqIf1mY6IjiPAv9Mg#image-pre-processing">object</a></td><td>An Image Preprocessing Object. Currently, the only supported input type.</td></tr></tbody></table>

### **Image pre-processing**

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

### Post-processing object

This object maps output tensors to a specific function in order to interpret them thanks to [recognition versions](/deepomatic-api-v0.7/recognition-version.md).

{% hint style="info" %}
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).
{% endhint %}

<table><thead><tr><th width="177.33333333333331">Attribute</th><th width="129">Type</th><th>Description</th></tr></thead><tbody><tr><td>tensors_output</td><td><a href="#standard-post-processing">object</a></td><td>A simple ordered list of tensor names.</td></tr><tr><td>standard_output</td><td><a href="#standard-post-processing-deprecated">object</a></td><td><em>[deprecated]</em> A post-processing specific to detection.</td></tr></tbody></table>

#### Default post-processing

<table><thead><tr><th width="181">Attribute</th><th width="126.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>tensors</td><td>array(string)</td><td>A simple ordered list of tensor names.</td></tr></tbody></table>

#### Standard post-processing (deprecated)

<table><thead><tr><th width="184">Attribute</th><th width="125.33333333333331">Type</th><th>Description</th></tr></thead><tbody><tr><td>boxes_tensor</td><td>string</td><td>The name of the output tensor containing the boxes. It must be of size <code>N x 4</code>where <code>N</code> is the number of detected regions and the 4 columns correspond to <code>xmin</code>, <code>ymin</code>, <code>xmax</code> and <code>ymax</code>coordinates of the bounding boxes, <code>xmin</code>and <code>ymin</code> being the coordinates of the upper-left corner.</td></tr><tr><td>scores_tensor</td><td>string</td><td>The name of the output tensor containing the scores for each label and box. It must be of size <code>N x K</code> where <code>K</code>is the number of labels in the recognition specification.</td></tr></tbody></table>

## Create a network

### Definition

Creates a new custom network after you have trained a model of your own on your infrastructure.

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))

client.Network.create(...)
```

{% endtab %}
{% endtabs %}

### Arguments

<table><thead><tr><th width="192">Parameter</th><th width="92">Type</th><th width="96" align="center">Default</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td align="center"></td><td>A short name for your network.</td></tr><tr><td>description</td><td>string</td><td align="center"></td><td>A longer description of your network.</td></tr><tr><td>metadata</td><td>object</td><td align="center">{}</td><td>A JSON field containing any kind of information that you may find interesting to store.</td></tr><tr><td>framework</td><td>string</td><td align="center"></td><td><p>A string describing which framework to use for your network. Possible values are:</p><ul><li><code>tensorflow-1.x</code>: Tensorflow: currently version 2.9</li></ul></td></tr><tr><td>preprocessing</td><td><a href="/pages/-LZKqIf1mY6IjiPAv9Mg#pre-processing-object">object</a></td><td align="center"></td><td>A preprocessing object to describe how input data should be pre-processed.</td></tr><tr><td><em>&#x3C;additionnal-files></em></td><td>file</td><td align="center"></td><td>Extra files for network graph and weights, as well as mean files needed by the preprocessing. See below.</td></tr></tbody></table>

{% hint style="danger" %}
Once the network has been created, you cannot modify the `preprocessing` field anymore.
{% endhint %}

### Code sample

{% tabs %}
{% tab title="cURL" %}

```bash
# 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
```

{% endtab %}

{% tab title="Python" %}

```python
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))
```

{% endtab %}
{% endtabs %}

### 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](/deepomatic-api-v0.7/neural-networks.md#pre-processing-object) as long it has one of the supported extensions, see the [documentation](/deepomatic-api-v0.7/neural-networks.md#network-object).

{% hint style="success" %}
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.
{% endhint %}

#### Saving mean files

In order to save numpy tensor means to files before sending them to the API, please proceed like this:

{% code title="Python" %}

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

{% endcode %}

### Response

A [neural network object](/deepomatic-api-v0.7/neural-networks.md#network-object), example response:

{% code title="JSON" %}

```javascript
{
    "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
    }
}
```

{% endcode %}

## List networks

### Code sample

Lists all public and private networks:

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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)
```

{% endtab %}
{% endtabs %}

### Response

A paginated list of responses.

<table><thead><tr><th width="146.33333333333331">Parameter</th><th width="139">Type</th><th>Description</th></tr></thead><tbody><tr><td>count</td><td>int</td><td>The total number of results.</td></tr><tr><td>next</td><td>string</td><td>The URL to the next page.</td></tr><tr><td>previous</td><td>string</td><td>The URL to the previous page.</td></tr><tr><td>results</td><td>array(<a href="/pages/-LZKqIf1mY6IjiPAv9Mg#network-object">object</a>)</td><td>A list of your neural networks objects</td></tr></tbody></table>

Example response

{% code title="JSON" %}

```javascript
{
    "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
            }
        }
    ]
}
```

{% endcode %}

## Retrieve a network

### Definition

Retrieve a neural network by ID:

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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})
```

{% endtab %}
{% endtabs %}

### Arguments

<table><thead><tr><th width="147">Parameter</th><th width="88">Type</th><th width="96">Default</th><th>Description</th></tr></thead><tbody><tr><td>network_id</td><td>int</td><td></td><td>The ID of the neural network to get.</td></tr></tbody></table>

### Code sample

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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)
```

{% endtab %}
{% endtabs %}

### Response

A [neural networks object](/deepomatic-api-v0.7/neural-networks.md#network-object).

{% code title="JSON" %}

```javascript
{
    "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
    }
}
```

{% endcode %}

## 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 `metadata`arguments. Other values are immutable.

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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(...)
```

{% endtab %}
{% endtabs %}

### Arguments

<table><thead><tr><th width="136">Parameter</th><th width="104">Type</th><th width="116">Attributes</th><th>Description</th></tr></thead><tbody><tr><td>name</td><td>string</td><td>optionnal</td><td>A short name for your network.</td></tr><tr><td>description</td><td>string</td><td>optionnal</td><td>A longer description of your network.</td></tr><tr><td>metadata</td><td>object</td><td>optionnal</td><td>A JSON field containing any kind of information that you may find interesting to store.</td></tr></tbody></table>

### Code sample

{% tabs %}
{% tab title="cURL" %}

```bash
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
```

{% endtab %}

{% tab title="Python" %}

```python
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"
)
```

{% endtab %}
{% endtabs %}

### Response

A [neural networks object](/deepomatic-api-v0.7/neural-networks.md#network-object).

## Delete a network

### Definition

Permanently deletes a network. This cannot be undone.

{% tabs %}
{% tab title="cURL" %}

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

{% endtab %}

{% tab title="Python" %}

```python
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()
```

{% endtab %}
{% endtabs %}

{% hint style="danger" %}
Attached resources such as **recognition versions** will also be suppressed.
{% endhint %}

### Arguments

<table><thead><tr><th width="134">Parameter</th><th width="113">Type</th><th width="99">Default</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>int</td><td></td><td>The Neural Network ID to delete.</td></tr></tbody></table>

### Code sample

{% tabs %}
{% tab title="cURL" %}

```bash
curl https://api.deepomatic.com/v0.7/networks/42 \
-H "X-API-KEY: ${DEEPOMATIC_API_KEY}" \
-X DELETE
```

{% endtab %}

{% tab title="Python" %}

```python
import os
from deepomatic.api.client import Client
client = Client(api_key=os.getenv('DEEPOMATIC_API_KEY'))

network = client.Network.retrieve(42)
network.delete()
```

{% endtab %}
{% endtabs %}

### Response

Return 204 (no content).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.deepomatic.com/deepomatic-api-v0.7/neural-networks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.