# Model JSON Structure

<figure><picture><source srcset="https://2601997817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FadsCjYOHkzN6JzhjwIb1%2Fuploads%2Fgit-blob-ce5ee4e3e3b31f248e7294be9477ce09f023c2e5%2Fpysdk--json-components-overview-white-stroke.svg?alt=media" media="(prefers-color-scheme: dark)"><img src="https://2601997817-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FadsCjYOHkzN6JzhjwIb1%2Fuploads%2Fgit-blob-b391d72d49bce9afa1079eb0a19b35429c24bdff%2Fpysdk--json-components-overview-black-stroke.svg?alt=media" alt="JSON Configuration File Parameters"></picture><figcaption><p>JSON Configuration File Parameters</p></figcaption></figure>

## JSON Overview

All models in model zoos are paired with JSON configuration files that describe the model type, its intended function, the runtime environment it is compiled for, and its preprocessing and postprocessing settings.

These parameters fall into five sections:

* [General](#general-parameters): Basic information to identify the model.
* [DEVICE](#target-device-parameters): Environment the model expects.
* [MODEL\_PARAMETERS](#model-parameters): Settings for how the model operates.
* [PRE\_PROCESS](#preprocessing-parameters): Preprocessing settings for model inputs.
* [POST\_PROCESS](#postprocessing-parameters): Postprocessing settings for model outputs.

{% hint style="warning" %}
Incorrectly setting these parameters may decrease precision and performance.
{% endhint %}

### Example JSON Configuration

Here is a sample JSON configuration. Include or omit parameters as your model requires:

{% code overflow="wrap" %}

```json
{
  "ConfigVersion": <config_version_number>,
  "Checksum": "<checksum>",
  "DEVICE": [
    {
      "DeviceType": "<device_type>",
      "RuntimeAgent": "<runtime_agent>",
      "SupportedDeviceTypes": "<supported_device_types>"
    }
  ],
  "PRE_PROCESS": [
    {
      "InputN": <input_N>,
      "InputH": <input_H>,
      "InputW": <input_W>,
      "InputC": <input_C>,
      "InputQuantEn": <boolean_for_quant_enabled>
    }
  ],
  "MODEL_PARAMETERS": [
    {
      "ModelPath": "<path_to_model>"
    }
  ],
  "POST_PROCESS": [
    {
      "OutputPostprocessType": "<postprocess_type>",
      "OutputNumClasses": <number_of_output_classes>,
      "LabelsPath": "<path_to_labels_json>"
    }
  ]
}
```

{% endcode %}

***

## General Parameters

General parameters at the top of the JSON file specify its version and the model binary's checksum.

<table><thead><tr><th width="262">Parameter</th><th>Type</th><th>Mandatory</th></tr></thead><tbody><tr><td>ConfigVersion</td><td>int</td><td>yes</td></tr><tr><td>Checksum</td><td>string</td><td>yes</td></tr></tbody></table>

* **ConfigVersion**\
  The version of the JSON configuration file. The current JSON config version is 11. It is verified against the minimum compatible and current framework software versions. If the version is not within the acceptable range, a version-check runtime exception is generated during model loading. At this moment, PySDK is backwards-compatible with ConfigVersions introduced in prior PySDK releases.
  * Version 11 was introduced in PySDK 0.17.0.
  * Version 10 was introduced in PySDK 0.14.3.
  * Version 9 was introduced in PySDK 0.12.0.
* **Checksum**\
  The checksum of the model binary file.

***

## Device Parameters

**Section name in JSON:** `DEVICE`

This section includes three parameters: **DeviceType**, **RuntimeAgent**, and **SupportedDeviceTypes**. Refer to the [Supported Hardware](https://docs.degirum.com/pysdk/installation#supported-hardware) section for details on device compatibility.

<table><thead><tr><th width="255">Parameter</th><th>Type</th><th>Mandatory</th></tr></thead><tbody><tr><td>DeviceType</td><td>string</td><td>yes</td></tr><tr><td>RuntimeAgent</td><td>string</td><td>yes</td></tr><tr><td>SupportedDeviceTypes</td><td>string</td><td>yes</td></tr></tbody></table>

* **DeviceType**\
  The type of device on which the model will run.
* **RuntimeAgent**\
  The runtime agent responsible for executing the model.
* **SupportedDeviceTypes**\
  Lists the device types that are supported by the model. Refer to the Supported Hardware documentation for details on device compatibility.
* **FrameQueueDepth**\
  Maximum size of client frame queue. Needs to be set to 20 for Axelera models with double\_buffer=true.

***

## Model Parameters

**Section name in JSON:** `MODEL_PARAMETERS`

These parameters control how the model operates.

<table><thead><tr><th width="256">Parameter</th><th>Type</th><th>Mandatory</th><th>Models</th></tr></thead><tbody><tr><td>ModelPath</td><td>string</td><td>yes</td><td>All</td></tr></tbody></table>

* **ModelPath**\
  The path to a model file.

***

## Preprocessing Parameters

**Section name in JSON:** `PRE_PROCESS`

These parameters control settings used to prepare and transform input data before it is fed into the model, ensuring proper formatting and normalization. This section may contain multiple elements (one per input tensor in multi-input networks).

### Input Configuration

Fundamental properties of the input data, including its type, dimensions, and layout.

<table><thead><tr><th width="258">Parameter</th><th>Type</th><th>Mandatory</th><th>Default</th><th>Input Type</th></tr></thead><tbody><tr><td>InputN</td><td>int</td><td>yes</td><td>(none)</td><td>All</td></tr><tr><td>InputH</td><td>int</td><td>yes</td><td>(none)</td><td>All</td></tr><tr><td>InputW</td><td>int</td><td>yes</td><td>(none)</td><td>All</td></tr><tr><td>InputC</td><td>int</td><td>yes</td><td>(none)</td><td>All</td></tr><tr><td>InputType</td><td>string</td><td>No</td><td>"Image"</td><td>All</td></tr><tr><td>InputShape</td><td>int array</td><td>No</td><td>(none)</td><td>All</td></tr><tr><td>InputRawDataType</td><td>string</td><td>No</td><td>"DG_UINT8"</td><td>All</td></tr><tr><td>InputTensorLayout</td><td>string</td><td>No</td><td>"NHWC"</td><td>Image</td></tr></tbody></table>

* **InputN**\
  The batch size for the input data tensor.
* **InputH**\
  The height of the input data tensor.
* **InputW**\
  The width of the input data tensor.
* **InputC**\
  The number of channels in the input data tensor.
* **InputType**\
  The model input type. The dimension order is defined by **InputTensorLayout**. This can be set to:
  * `Image`
  * `Tensor`
* **InputShape**\
  The shape of the input data tensor in the format`[<N>, <H>, <W>, <C>]`. You may specify the shape with this parameter or with the InputN, InputH, InputW, and InputC parameters.
* **InputRawDataType**\
  The data type of raw binary tensor elements (how the preprocessor treats client data). This is a runtime parameter that can be changed on the fly. This can be set to:
  * `DG_UINT8` (unsigned 8-bit integer)
  * `DG_FLT` (32-bit floating point),
  * `DG_INT16` (signed 16-bit integer).
* **InputTensorLayout**\
  The dimensional layout of the raw binary tensor for inputs of raw image type and raw tensor type. This can be set to:
  * `auto`
  * `NHWC`
  * `NCHW`

***

### Image Format & Manipulation

Governs the image input format, color space, resizing, padding, cropping, and slicing operations. These parameters are needed only when **InputType** is `Image`.

<table><thead><tr><th width="255">Parameter</th><th>Type</th><th>Mandatory</th><th>Default</th></tr></thead><tbody><tr><td>ImageBackend</td><td>string</td><td>No</td><td>"auto"</td></tr><tr><td>InputResizeMethod</td><td>string</td><td>No</td><td>"bilinear"</td></tr><tr><td>InputPadMethod</td><td>string</td><td>No</td><td>"letterbox"</td></tr><tr><td>InputCropPercentage</td><td>double</td><td>No</td><td>1.0</td></tr><tr><td>InputImgFmt</td><td>string</td><td>No</td><td>"JPEG"</td></tr><tr><td>InputColorSpace</td><td>string</td><td>No</td><td>"RGB"</td></tr></tbody></table>

* **ImageBackend**\
  The Python package used for image processing. When this is set to `auto`, the OpenCV backend will be tried first. This can be set to:
  * `auto`
  * `pil`
  * `opencv`
* **InputResizeMethod**\
  The interpolation algorithm used for image resizing. This can be set to:
  * `nearest`
  * `bilinear`
  * `area`
  * `bicubic`
  * `lanczos`
* **InputPadMethod**\
  Specifies how the input image is padded or cropped during resizing. This can be set to:
  * `stretch`
  * `letterbox`
  * `crop-first`
  * `crop-last`
* **InputCropPercentage**\
  The crop percentage when **InputPadMethod** is set to `crop-first` or `crop-last`.
* **InputImgFmt**\
  The image format for image inputs. Data type is defined by **InputRawDataType**. This can be set to:
  * `JPEG`
  * `RAW`
* **InputColorSpace**\
  The color space required for image inputs. This can be set to `RGB` or `BGR`. If **InputImgFmt** is `JPEG`, the preprocessor automatically handles color conversion; if `RAW`, the raw tensor must be arranged accordingly.

***

### Normalization

Defines how input data is normalized, including scale factors and per-channel adjustments, to ensure consistency across inputs.

<table><thead><tr><th width="254">Parameter</th><th>Type</th><th>Mandatory</th><th>Default</th><th>Models</th></tr></thead><tbody><tr><td>InputScaleEn</td><td>bool</td><td>No</td><td>false</td><td>Image</td></tr><tr><td>InputScaleCoeff</td><td>double</td><td>No</td><td>1./255.</td><td>Image</td></tr><tr><td>InputNormMean</td><td>float array</td><td>No</td><td>[]</td><td>Image</td></tr><tr><td>InputNormStd</td><td>float array</td><td>No</td><td>[]</td><td>Image</td></tr></tbody></table>

* **InputScaleEn**\
  Specifies whether global data normalization is applied.
* **InputScaleCoeff**\
  The scale factor used for global data normalization when **InputScaleEn** is `true`.
* **InputNormMean**\
  The mean values for per-channel normalization of image inputs (e.g., `[0.485, 0.456, 0.406]`).
* **InputNormStd**\
  The standard deviation values for per-channel normalization of image inputs (e.g., `[0.229, 0.224, 0.225]`).

***

### Quantization

Settings for converting input data into quantized formats to optimize processing efficiency and model performance.

<table><thead><tr><th width="255">Parameter</th><th>Type</th><th>Mandatory</th><th>Default</th><th>Models</th></tr></thead><tbody><tr><td>InputQuantEn</td><td>bool</td><td>No</td><td>false</td><td>All</td></tr><tr><td>InputQuantOffset</td><td>float</td><td>No</td><td>0</td><td>All</td></tr><tr><td>InputQuantScale</td><td>float</td><td>No</td><td>1</td><td>All</td></tr></tbody></table>

* **InputQuantEn**\
  Enables input quantization for image and raw tensor types, determining whether the model input is treated as `uint8` or `float32`.
* **InputQuantOffset**\
  The quantization zero offset for image and raw tensor inputs.
* **InputQuantScale**\
  The quantization scale. When quantization is enabled, data is scaled before quantization using the provided formula.

***

## Postprocessing Parameters

**Section name in JSON:** `POST_PROCESS`

These parameters transform model outputs into final, interpretable results.

### General Behavior

General settings for the output postprocessing algorithm and how output tensors are managed.

<table><thead><tr><th width="265">Parameter</th><th>Type</th><th>Mandatory</th><th>Default</th></tr></thead><tbody><tr><td>PythonFile</td><td>string</td><td>No</td><td>(none)</td></tr><tr><td>LabelsPath</td><td>string</td><td>No</td><td>""</td></tr><tr><td>OutputPostprocessType</td><td>string</td><td>No</td><td><code>None</code></td></tr></tbody></table>

* **OutputPostprocessType**\
  The type of output postprocessing algorithm. This can be set to:
  * `Classification`
  * `Detection`
  * `DetectionDamoYolo`
  * `DetectionYolo`
  * `DetectionYoloPlates`
  * `DetectionYoloV8`
  * `DetectionYoloV8OBB`
  * `DetectionYoloHailo`
  * `FaceDetection`
  * `HandDetection`
  * `PoseDetection`
  * `PoseDetectionYoloV8`
  * `Segmentation`
  * `SegmentationYoloV8`
  * `Dequantization`
  * `Null`
  * `None`
* **PythonFile**\
  The name of a Python file that contains server-side postprocessing code.
* **LabelsPath**\
  The path to a label dictionary file.
* **OutputPostprocessType**\
  The type of output post-processing algorithm.

***

### Thresholds & Alignment

Thresholds and alignment adjustments used during postprocessing to filter and refine model outputs.

<table><thead><tr><th width="265">Parameter</th><th>Type</th><th>Mandatory</th><th>Default</th></tr></thead><tbody><tr><td>OutputConfThreshold</td><td>double</td><td>No</td><td>0.3</td></tr><tr><td>OutputNMSThreshold</td><td>double</td><td>No</td><td>0.6</td></tr><tr><td>OutputClassIDAdjustment</td><td>int</td><td>No</td><td>0</td></tr></tbody></table>

* **OutputConfThreshold**\
  The confidence threshold below which results are filtered out.
* **OutputNMSThreshold**\
  The threshold for the Non-Max Suppression (NMS) algorithm.
* **OutputClassIDAdjustment**\
  The adjustment for the index of the first non-background class.

***

### Classification-Specific

Parameters tailored for classification tasks, such as enabling softmax and selecting the number of top classes.

<table><thead><tr><th width="265">Parameter</th><th>Type</th><th>Mandatory</th><th>Default</th></tr></thead><tbody><tr><td>OutputSoftmaxEn</td><td>bool</td><td>No</td><td>false</td></tr><tr><td>OutputTopK</td><td>size_t</td><td>No</td><td>0</td></tr></tbody></table>

* **OutputSoftmaxEn**\
  Specifies whether softmax is enabled during post-processing.
* **OutputTopK**\
  The number of classes to include in the classification result. If set to zero, all classes above **OutputConfThreshold** are reported.

***

### Detection-Specific

Parameters tailored for object detection, including detection limits, scaling coefficients, and non-max suppression parameters.

<table><thead><tr><th width="265">Parameter</th><th>Type</th><th>Mandatory</th><th>Default</th></tr></thead><tbody><tr><td>XScale</td><td>double</td><td>conditional</td><td>1</td></tr><tr><td>YScale</td><td>double</td><td>conditional</td><td>1</td></tr><tr><td>HScale</td><td>double</td><td>conditional</td><td>1</td></tr><tr><td>WScale</td><td>double</td><td>conditional</td><td>1</td></tr><tr><td>OutputNumClasses</td><td>int</td><td>No</td><td>20</td></tr><tr><td>MaxDetectionsPerClass</td><td>int</td><td>No</td><td>100</td></tr><tr><td>MaxClassesPerDetection</td><td>int</td><td>No</td><td>1</td></tr><tr><td>UseRegularNMS</td><td>bool</td><td>No</td><td>true</td></tr><tr><td>MaxDetections</td><td>int</td><td>No</td><td>100</td></tr><tr><td>PoseThreshold</td><td>double</td><td>No</td><td>0.8</td></tr><tr><td>NMSRadius</td><td>double</td><td>No</td><td>10</td></tr><tr><td>Stride</td><td>int</td><td>No</td><td>16</td></tr></tbody></table>

* **XScale**\
  The X scale coefficient used to convert box center coordinates to an anchor-based coordinate system.
* **YScale**\
  The Y scale coefficient used to convert box center coordinates to an anchor-based coordinate system.
* **HScale**\
  The height scale coefficient used to convert box size coordinates to an anchor-based coordinate system.
* **WScale**\
  The width scale coefficient used to convert box size coordinates to an anchor-based coordinate system.
* **OutputNumClasses**\
  The number of output classes for detection models.
* **MaxDetectionsPerClass**\
  The maximum number of object detection results to report per class.
* **MaxClassesPerDetection**\
  The maximum number of classes to report for each detection.
* **UseRegularNMS**\
  Specifies whether to use a regular (non-batched) NMS algorithm for object detection.
* **MaxDetections**\
  The maximum number of object detection results to report.
* **PoseThreshold**\
  The pose score threshold below which low-confidence poses are filtered out.
* **NMSRadius**\
  The NMS radius for pose detection—a keypoint candidate is rejected if it lies within this pixel range of a previously detected instance.
* **Stride**\
  The stride scale coefficient used for pose detection.