Model Module
Last updated
Was this helpful?
Last updated
Was this helpful?
Bases: ABC
Model class. Handles whole inference lifecycle for a single model: input data preprocessing, inference, and postprocessing.
Note
You never construct model objects yourself – instead you call method to create instances for you.
degirum.model.Model.custom_postprocessor
property writable
Custom postprocessor class. When not None, the object of this class is returned as inference result. Such custom postprocessor classes must be inherited from class.
degirum.model.Model.device_type
property writable
The type of the device to be used for model inference in a format <runtime>/<device>
Setter accepts either a string which specifies single device in a format <runtime>/<device>
or it can be a list of such strings. In this case the first supported device type
from the list will be selected.
Getter returns currently selected device type.
degirum.model.Model.devices_available
abstractmethod property
The list of inference device indices which can be used for model inference.
degirum.model.Model.devices_selected
property writable
The list of inference device indices selected for model inference.
degirum.model.Model.eager_batch_size
property writable
The size of the batch (number of consecutive frames before this model is switched to another model during batch predict) to be used by device scheduler when inferencing this model.
degirum.model.Model.frame_queue_depth
property writable
The depth of the model prediction queue. When the queue size reaches this value, the next prediction call will block until there will be space in the queue.
degirum.model.Model.image_backend
property writable
Graphical library (backend) to use for graphical tasks – one of 'pil', 'opencv', 'auto'
'auto' means try OpenCV first, if not installed, try PIL.
degirum.model.Model.inference_timeout_s
property writable
The maximum time in seconds to wait for inference result from the model.
degirum.model.Model.input_crop_percentage
property writable
Percentage of image to crop around. Valid range: [0..1].
degirum.model.Model.input_image_format
property writable
Defines the image format for model inputs of image type – one of 'JPEG' or 'RAW'.
degirum.model.Model.input_letterbox_fill_color
property writable
3-element RGB tuple.
degirum.model.Model.input_numpy_colorspace
property writable
Input image colorspace – one of 'RGB', 'BGR', or 'auto'.
This parameter is used only to identify colorspace for NumPy arrays.
'auto' translates to 'BGR' for opencv backend, and to 'RGB' for pil backend.
degirum.model.Model.input_pad_method
property writable
Input image pad method – one of 'stretch', 'letterbox', 'crop-first', or 'crop-last'.
In case of 'stretch', the input image will be resized to the model input size without preserving aspect ratio.
In case of 'letterbox', the input image will be resized to the model input size preserving aspect ratio.
In case of 'crop-first', the input image will be cropped to input_crop_percentage around the center and then resized.
In the case of 'crop-last', if the model's input dimensions are square, the image is resized with its smaller side matching the model dimension, preserving the aspect ratio. If the dimensions are rectangular, the image is resized and stretched to fit the model's input dimensions. After resizing, the image is cropped to the model's input dimensions and aspect ratio based on the 'input_crop_percentage' property.
degirum.model.Model.input_resize_method
property writable
Input image resize method – one of 'nearest', 'bilinear', 'area', 'bicubic', or 'lanczos'.
degirum.model.Model.input_shape
property writable
Input tensor shapes. List of tensor shapes per input.
Each element of that list is another list containing tensor dimensions, slowest dimension first:
if InputShape model parameter is specified, its value is used.
otherwise, all defined InputN/H/W/C model parameters are used as [InputN, InputH, InputW, InputC] list.
degirum.model.Model.label_dictionary
abstractmethod property
Get model class label dictionary.
Each dictionary element is key-value pair, where the key is the class ID and the value is the class label string.
degirum.model.Model.measure_time
property writable
Flag to enable measuring and collecting inference time statistics.
degirum.model.Model.model_info
property
Return model information object to provide read-only access to model parameters.
New deep copy is created each time.
degirum.model.Model.non_blocking_batch_predict
property writable
Flag to control the behavior of the generator object returned by predict_batch() method.
When the flag is set to True, the generator accepts None from the inference input data
iterator object (passed as data parameter): If None is returned, the model predict step is skipped for
this iteration. Also, when no inference results are available in the result queue at this iteration,
the generator yields None result.
When the flag is set to False (default value), the generator does not allow None to be returned from
the inference input data iterator object: If None is returned, an exception is raised.
Also, when no inference results are available in the result queue at this iteration,
the generator continues to the next iteration of the input data iterator.
Setting this flag to True allows using predict_batch() generator in a non-blocking manner, assuming
the design of input data iterator object is also non-blocking, i.e., returning None when no data is
available instead of waiting for the data. Every next element request from the generator will not block
the execution waiting for either input data or inference results, returning None when no results are
available.
degirum.model.Model.output_class_set
property writable
Labels filter: list of class labels/category IDs to be included in inference results.
Note
degirum.model.Model.output_confidence_threshold
property writable
Confidence threshold used in inference result post-processing.
Valid range: [0..1].
Only objects with scores higher than this threshold are reported.
Note
degirum.model.Model.output_max_classes_per_detection
property writable
Max Detections Per Class number used in inference result post-processing, and specifies the maximum number of highest probability classes per anchor to be processed during the non-max suppression process for fast algorithm.
Applicable only for detection models.
degirum.model.Model.output_max_detections
property writable
Max Detection number used in inference result post-processing, and specifies the total maximum objects of number to be detected.
Applicable only for detection models.
degirum.model.Model.output_max_detections_per_class
property writable
Max Detections Per Class number used in inference result post-processing, and specifies the maximum number of objects to keep during per class non-max suppression process for regular algorithm.
Applicable only for detection models.
degirum.model.Model.output_nms_threshold
property writable
Non-Max Suppression (NMS) threshold used in inference result post-processing.
Valid range: [0..1].
Applicable only for models which utilize NMS algorithm.
degirum.model.Model.output_pose_threshold
property writable
Pose detection threshold used in inference result post-processing.
Valid range: [0..1].
Applicable only for pose detection models.
degirum.model.Model.output_postprocess_type
property writable
Inference result post-processing type.
You may set it to 'None' to bypass post-processing.
degirum.model.Model.output_top_k
property writable
The number of classes with highest scores to report for classification models.
degirum.model.Model.output_use_regular_nms
property writable
Use Regular NMS value used in inference result post-processing and specifies the algorithm to use for detection postprocessing.
If value is True, regular Non-Max suppression algorithm is used – NMS is calculated for each class
separately and after that all results are merged.
If value is False, fast Non-Max suppression algorithm is used – NMS is calculated for all classes
simultaneously.
degirum.model.Model.overlay_alpha
property writable
Alpha-blend weight for inference results drawing on overlay image.
float number in range [0..1].
degirum.model.Model.overlay_blur
property writable
Overlay blur option.
None for no blur, "all" to blur all objects, a class label or list of class
labels to blur specific objects.
degirum.model.Model.overlay_color
property writable
Color for inference results drawing on overlay image.
3-element RGB tuple or list of 3-element RGB tuples.
The overlay_color property is used to define the color to draw overlay details. In the case of a single RGB tuple,
the corresponding color is used to draw all the overlay data: points, boxes, labels, segments, etc.
In the case of a list of RGB tuples the behavior depends on the model type:
For classification models different colors from the list are used to draw labels of different classes.
For detection models different colors are used to draw labels and boxes of different classes.
For pose detection models different colors are used to draw keypoints of different persons.
For segmentation models different colors are used to highlight segments of different classes.
If the list size is less than the number of classes of the model, then overlay_color values are used cyclically,
for example, for three-element list it will be overlay_color[0], then overlay_color[1], overlay_color[2],
and again overlay_color[0].
degirum.model.Model.overlay_font_scale
property writable
Font scale for inference results drawing on overlay image.
float positive number.
degirum.model.Model.overlay_line_width
property writable
Line width for inference results drawing on overlay image.
degirum.model.Model.overlay_show_labels
property writable
Flag to enable/disable drawing class labels on overlay image.
degirum.model.Model.overlay_show_probabilities
property writable
Flag to enable/disable drawing class probabilities on overlay image.
degirum.model.Model.save_model_image
property writable
Flag to enable/disable saving of model input image in inference results.
Model input image is the image converted to AI model input specifications as raw binary array.
degirum.model.Model.supported_device_types
property
The list of supported device types in format <runtime>/<device> for this model.
degirum.model.Model.__call__(data)
Perform whole inference lifecycle: input data preprocessing, inference and postprocessing.
degirum.model.Model.__enter__()
Context manager enter handler.
degirum.model.Model.__exit__(exc_type, exc_val, exc_tb)
Context manager exit handler.
degirum.model.Model.__init__(model_name, model_params, supported_device_types)
Constructor.
Note
degirum.model.Model.predict(data)
Perform whole inference lifecycle: input data preprocessing, inference, and postprocessing.
Parameters:
data
any
Inference input data. Input data type depends on the model.
If the model expects image data, then the input data is either:
Input image path string.
NumPy 3D array of pixels in a form HWC.
where color dimension is native to selected graphical backend (RGB for 'pil' and BGR for 'opencv' backend)
PIL.Image object (only for 'pil' backend).
If the model expects audio data, then the input data is NumPy 1D array with audio data samples.
If the model expects raw tensor data, then the input data is NumPy multidimensional array with shape matching model input.
In case of multi-input model a list of elements of the supported data type is expected.
required
Returns:
Inference result object, which allows you to access inference results as a dictionary or as an overlay image if it is supported by the model. For your convenience, all image coordinates in case of detection models are converted from model coordinates to original image coordinates.
degirum.model.Model.predict_batch(data)
Perform whole inference lifecycle for all objects in given iterator object (for example, list).
Parameters:
data
iterator
Inference input data iterator object such as list or generator function.
Each element returned by this iterator can be one of the following:
A single input data object, in case of single-input model.
A list of input data objects, in case of multi-input model.
A tuple containing a pair of input data object or a list of input data objects as a first element
and frame info object as a second element of the tuple.
The input data object type depends on the model.
If the model expects image data, then the input data object is either:
Input image path string.
NumPy 3D array of pixels in a form HWC, where color dimension is native to selected graphical backend
(RGB for 'pil' and BGR for 'opencv' backend).
PIL.Image object (only for 'pil' backend).
If the model expects audio data, then the input data object is NumPy 1D array with audio data samples.
If the model expects raw tensor data, then the input data object is NumPy multidimensional array with shape matching model input.
The frame info object is passed to the inference result object unchanged and can be accessed via info
property of the inference result object.
required
Returns:
Example
degirum.model.Model.predict_dir(path, *, recursive=False, extensions=['.jpg', '.jpeg', '.png', '.bmp'])
Perform whole inference lifecycle for all files from specified directory matching given file extensions.
Supports only single-input models.
Parameters:
path
str
Directory name containing files to be processed.
required
recursive
bool
True to recursively walk through all subdirectories in a directory. Default is False.
False
extensions
list[str]
Single string or list of strings containing file extension(s) to process.
['.jpg', '.jpeg', '.png', '.bmp']
Returns:
Example
degirum.model.Model.reset_time_stats()
Reset inference time statistics.
degirum.model.Model.time_stats()
Query inference time statistics.
Returns:
dict
Dictionary containing time statistic objects.
A key in that dictionary is a string description of a particular inference step.
Supported device types can be obtained by property.
Image fill color in case of 'letterbox' padding (see
property for details).
The voids will be filled with solid color specified by input_letterbox_fill_color property.
In all cases property specifies the algorithm for resizing.
Call to query accumulated inference time statistics.
You can use property to obtain a list of model classes.
For classification models if parameter is set to non-zero value, then it supersedes this threshold -- highest score classes are always reported.
When set to 0, then report all classes with scores greater than .
See for more details.
The default value of overlay_color is a single RBG tuple of yellow color for all model types except segmentation models.
For segmentation models it is the list of RGB tuples with the list size equal to the number of model classes.
You can use property to obtain a list of model classes.
Each color is automatically assigned to look pretty and different from other colors in the list.
See for more details.
See for more details.
See for more details.
See for more details.
Same as .
You never construct model objects yourself – instead you call method to create instances for you.
Such iterator object should return the same object types which regular method accepts.
Iterator[]
Generator object which iterates over inference result objects. This allows you directly using the
result of in for loops.
Iterator[]
Generator object to iterate over inference result objects. This allows you directly using the
result of in for loops.
method will return empty dictionary after this call.
Each statistic object keeps min, max, and average values in milliseconds, accumulated over all inferences performed on this model since the model creation of last call of statistic reset method .
Time statistics are accumulated only when property is set to True.