GstAnalytics.ModelInfo¶

Fields¶

None

Methods¶

class	`load` (model_filename)
	`find_tensor_name` (dir, index, in_tensor_name, data_type, dims)
	`free` ()
	`get_dims_order` (tensor_name)
	`get_group_id` ()
	`get_id` (tensor_name)
	`get_input_scales_offsets` (tensor_name, input_mins, input_maxs)
	`get_quark_group_id` ()
	`get_quark_id` (tensor_name)
	`get_target_ranges` (tensor_name)
	`get_version` ()

Details¶

class GstAnalytics.ModelInfo¶

The GstAnalytics.ModelInfo is an object storing artifical neural network model metadata describing the input and output tensors. These information’s are required by inference elements.

New in version 1.28.

classmethod load(model_filename)¶

Parameters:: model_filename (str) – Path to the model file (e.g., “model.onnx”, “model.tflite”)
Returns:: A new GstAnalytics.ModelInfo instance, or None if the modelinfo file could not be found or loaded.
Return type:: GstAnalytics.ModelInfo or None

Load a modelinfo file associated with the given model file.

This function attempts to load a .modelinfo file in the following order:

{model_filename}.modelinfo

{model_filename_without_extension}.modelinfo

The modelinfo file contains metadata for the model’s input and output tensors, including normalization ranges, dimension ordering, tensor IDs, etc.

The loaded modelinfo must be freed with GstAnalytics.ModelInfo.free() when no longer needed.

New in version 1.28.

find_tensor_name(dir, index, in_tensor_name, data_type, dims)¶

Parameters:

dir (GstAnalytics.ModelInfoTensorDirection) – The tensor direction (input or output)
index (int) – The tensor index within the specified direction
in_tensor_name (str or None) – An optional tensor name hint to check first
data_type (GstAnalytics.TensorDataType) – The tensor data type to match
dims ([int]) – The dimension sizes. Use -1 for dynamic dimensions.

Returns:

The tensor name if found, or None otherwise. The caller must free this with GLib.free() when done.

Return type:

str or None

Find the name of a tensor in the modelinfo that matches the given criteria.

The function performs the following checks in order:

If in_tensor_name is provided and exists in modelinfo, validate it matches

Search by index for the specified direction and validate

Search by dimensions and data type

New in version 1.28.

free()¶

Free a modelinfo object allocated by GstAnalytics.ModelInfo.load().

This function should be called when the modelinfo is no longer needed to release the associated resources.

New in version 1.28.

get_dims_order(tensor_name)¶

Parameters:: tensor_name (str) – The name of the tensor
Returns:: The dimension order as GstAnalytics.TensorDimOrder
Return type:: GstAnalytics.TensorDimOrder

Retrieve the dimension ordering for a given tensor.

The dimension ordering specifies how multi-dimensional tensor data is laid out in memory:

Row-major (C/NumPy style): Last dimension changes fastest in memory
Column-major (Fortran style): First dimension changes fastest in memory

If not specified in the modelinfo, defaults to row-major.

New in version 1.28.

get_group_id()¶

Returns:: The group ID string, or None if not found. The caller must free this with GLib.free() when done.
Return type:: str or None

Get the group ID that groups related tensors together (e.g., all outputs from the same model).

The group ID is stored in the modelinfo section and is global for all tensors in the model.

New in version 1.28.

get_id(tensor_name)¶

Parameters:: tensor_name (str) – The name of the tensor
Returns:: The tensor ID string, or None if not found. The caller must free this with GLib.free() when done.
Return type:: str or None

Get the tensor ID from the modelinfo for the specified tensor name.

The tensor ID is ideally registered in the Tensor ID Registry.

New in version 1.28.

get_input_scales_offsets(tensor_name, input_mins, input_maxs)¶

Parameters:

tensor_name (str) – The name of the tensor
input_mins ([float]) – The minimum values of the actual input data for each channel
input_maxs ([float]) – The maximum values of the actual input data for each channel

Returns:

True on success, False on error, if ranges field is not found, or if num_input_ranges doesn’t match the number of target ranges in the modelinfo

output_scales:: The scale values for normalization
output_offsets:: The offset values for normalization

Return type:

(bool, output_scales: [float], output_offsets: [float])

Calculate normalization scales and offsets to transform input data to the target range.

This function calculates transformation parameters to convert from the actual input data range [input_min, input_max] to the target range expected by the model [target_min, target_max]: normalized_value[i] = input[i] * output_scale[i] + output_offset[i]

The target ranges are read from the modelinfo ranges field: Semicolon-separated list of comma-separated pairs (min,max) for per-channel target ranges (e.g., “0.0,255.0;-1.0,1.0;0.0,1.0” for RGB channels with different target ranges).

Common input ranges:

[0.0, 255.0]: 8-bit unsigned (uint8)
[-128.0, 127.0]: 8-bit signed (int8)
[0.0, 65535.0]: 16-bit unsigned (uint16)
[-32768.0, 32767.0]: 16-bit signed (int16)
[0.0, 1.0]: Normalized float
[-1.0, 1.0]: Normalized signed float

The number of input ranges (num_input_ranges) must equal the number of target ranges in the modelinfo. The function will return False if they don’t match.

The caller must free output_scales and output_offsets with GLib.free() when done.

New in version 1.28.

get_quark_group_id()¶

Returns:: The GQuark of the group ID, or 0 if not found
Return type:: int

Get the group ID as a GQuark for efficient string comparison and storage.

Using GQuark is more efficient than string comparison when you need to compare multiple group IDs.

New in version 1.28.

get_quark_id(tensor_name)¶

Parameters:: tensor_name (str) – The name of the tensor
Returns:: The GQuark of the tensor ID, or 0 if not found
Return type:: int

Get the tensor ID as a GQuark for efficient string comparison and storage.

Using GQuark is more efficient than string comparison when you need to compare multiple IDs.

New in version 1.28.

get_target_ranges(tensor_name)¶

Parameters:

tensor_name (str) – The name of the tensor

Returns:

True if range information was found and valid, False otherwise

mins:: The minimum values for each target range
maxs:: The maximum values for each target range

Return type:

(bool, mins: [float], maxs: [float])

Retrieve all target ranges (min/max pairs) expected by the model for a given tensor.

This function retrieves all target ranges from the ranges field in the modelinfo. Each range represents the expected input range for a channel or dimension that the model requires.

The function reads from the ranges field: Semicolon-separated list of comma-separated pairs (min,max) for per-channel target ranges (e.g., “0.0,1.0;-1.0,1.0;0.0,1.0” for RGB channels with different normalization targets).

The caller must free mins and maxs with GLib.free() when done.

New in version 1.28.

get_version()¶

Returns:: The version string (e.g., “1.0”). The caller must free this with GLib.free() when done. Defaults to “1.0” if not specified.
Return type:: str

Retrieve the version string of the modelinfo file format.

The version is in the format “Major.Minor” and is stored in the [modelinfo] section of the modelinfo file.

New in version 1.28.