PySDK Retired Versions

Version 0.6.0 (03/28/2023)

IMPORTANT: This release has changes in PySDK API

New Features and Modifications

The function degirum.connect_model_zoo is deprecated and replaced with new function degirum.connect, which has more convenient interface.

The degirum.connect_model_zoo function is still available in 0.6.0 release for backward compatibility but it is not recommended to use in new development.
New function degirum.connect is introduced to simplify establishing model zoo connections. This is the main PySDK entry point: you start your work with PySDK by calling this function.

The following use cases are supported: - You want to perform cloud inferences and take models from some cloud model zoo. - You want to perform inferences on some AI server and take models from some cloud model zoo. - You want to perform inferences on some AI server and take models from its local model zoo. - You want to perform inferences on local AI hardware and take models from some cloud model zoo. - You want to perform inferences on local AI hardware and use particular model from your local drive.

Parameters:
- inference_host_address: inference engine designator; it defines which inference engine to use.
  
  For AI Server-based inference it can be either the hostname or IP address of the AI Server host, optionally followed by the port number in the form :port.
  
  For DeGirum Cloud Platform-based inference it is the string "@cloud" or degirum.CLOUD constant.
  
  For local inference it is the string "@local" or degirum.LOCAL constant.
- zoo_url: model zoo URL string which defines the model zoo to operate with.
  
  For a cloud model zoo, it is specified in the following format: <cloud server prefix>[/<zoo suffix>]. The <cloud server prefix> part is the cloud platform root URL, typically https://cs.degirum.com. The optional <zoo suffix> part is the cloud zoo URL suffix in the form <organization>/<model zoo name>. You can confirm zoo URL suffix by visiting your cloud user account and opening the model zoo management page. If <zoo suffix> is not specified, then DeGirum public model zoo degirum/public is used.
  
  For AI Server-based inferences, you may omit both zoo_url and token parameters. In this case locally-deployed model zoo of the AI Server will be used.
  
  For local AI hardware inferences, if you want to use particular AI model from your local drive, then you specify zoo_url parameter equal to the path to that model's .json configuration file. The token parameter is not needed in this case.
- token: cloud API access token used to access the cloud zoo. To obtain this token you need to open a user account on DeGirum cloud platform. Please login to your account and go to the token generation page to generate an API access token.
The function returns an instance of Model Zoo manager object configured to work with AI inference host and model zoo of your choice.
InputNormEn and InputNormCoeff model parameters (properties of ModelParams class) are substituted with InputScaleEn and InputScaleCoeff respectively. This renaming is done to better reflect the semantic of these parameters: the input data is scaled with InputScaleCoeff coefficient, when InputScaleEn is set; then per-channel normalization is applied if InputNormMean and InputNormStd parameters are not empty, and these two actions are independent from one another. The previous names of these parameters InputNormEn and InputNormCoeff made confusion with per-channel normalization parameters InputNormMean and InputNormStd, which are independent from the input scaling.

Old parameters InputNormEn and InputNormCoeff are deprecated but remain for backward compatibility.
The diagnostics of incorrect input image formats has been improved in case when a numpy array with incorrect shape is supplied for the inference.
The default public cloud model zoo URL suffix is changed from degirum_com/public to degirum/public.

Bug Fixes

When PySDK inference methods are called concurrently from multiple threads the Python application may crash intermittently.

Version 0.5.2 (03/13/2023)

New Features and Modifications

Hand palm detection models are initially supported in PySDK. Such models detect multiple palm key-points such as fingers. To process palm detection results the HandDetection post-processor is added to the PySDK.

Each detected hand palm is represented by the following JSON object:

JSON Field Name	Description	Data Type
"score"	Probability of detected hand	floating point
"handedness"	Probability of right hand	floating point
"landmarks"	hand description landmarks	array of landmark JSON objects (see next table)

The following is the structure of hand description landmark JSON object:

JSON Field Name	Description	Data Type
"label"	Classified object class label	string
"category_id"	Classified object class index	integer
"landmark"	landmark point	three-element JSON array [x, y, z]
"world_landmark"	metric world landmark point	three-element JSON array [x, y, z]
"connect"	list of adjacent landmarks indices	JSON array of integers

Two new properties are added to the degirum.model.Model class:
- eager_batch_size: it specifies the size of the batch to be used by the AI Server device scheduler when performing the inference of this model. The batch is the number of consecutive frames before this model is switched to another model during batch predict. This property accepts integer values in the range [1..80] range. The default value is 8.
- frame_queue_depth: it specifies the depth of the model prediction queue. When the queue size reaches this value, the next prediction call will block until there will be a free space in the queue. This property accepts integer values in the range [1..160] range. The default value is 80 for cloud inferences and 8 for other cases.
Using these two properties you may fine tune the inference latency and throughput.

In order to reduce the inference latency you reduce the frame_queue_depth. The downside of reduced frame_queue_depth is the increased probability of empty model prediction queue, which degrades the inference throughput.

If you simultaneously perform the inference of multiple models on the same AI Server, then to further reduce the inference latency you reduce the eager_batch_size. This causes AI Server scheduler to switch between different models more frequently. However, this degrades the inference throughput, since the model switching takes extra time.

If you want to maximize the throughput for one particular model at the expense of other models, you increase the eager_batch_size value for that particular model. This causes AI Server scheduler to postpone switching to another model(s) until the number of frames equal to eager_batch_size value are processed by this model.

Bug Fixes

When two (or more) AI Server clients simultaneously request the same model from the AI Server, and that model is already in the local cache, the first client takes it from the cache, while the second client always downloads it from the cloud.
The validation of PySDK preprocessor-related model properties is broken in ver. 0.5.1. For example the input_pad_method property has the following set of possible values: "stretch", "letterbox", "crop-first", "crop-last". But it was possible to assign arbitrary string value to this property and get unexpected errors during inference.
When a cloud model is loaded for inference on an AI Server and then this model is updated in the cloud zoo, then on the next inference request it is updated in the AI Server local cache (which is correct), but it is not updated in the AI accelerator cache and the outdated model is used for the inference.
Image colors get inverted when running inference on OpenCV image of exact model size. Steps to reproduce:
1. Use the model with RGB input colorspace.
2. Read the image by OpenCV so it will be in BGR colorspace.
3. Resize this image to the model input size.
4. Perform the inference
5. Show the overlay result: it will be with inverted colors

Version 0.5.1 (02/13/2023)

IMPORTANT: This release has new features in PySDK API

New Features and Modifications

PySDK packages for Python 3.10 and 3.11 are now available for the following platforms:
- Ubuntu Linux 20.04 LTS x86-64
- Ubuntu Linux 20.04 LTS ARM AArch64
- Windows 10/11 x86-64
The image cropping feature is implemented.

Two new choices are added for degirum.model.Model.input_pad_method property: "crop-first" and "crop-last".

New property, degirum.model.Model.input_crop_percentage, is added to specify the percentage of image dimensions to crop around when "input_pad_method" is set to "crop-first" or "crop-last".

When you select the "crop-first" method, the image is first cropped to match the AI model input tensor aspect ratio with respect to the degirum.model.Model.input_crop_percentage and then resized to match the AI model input tensor dimensions.

For example: an input image with dimensions 640x480 going into a model with input tensor dimensions 224x224 with crop percentage of 0.875 will first be center cropped to 420x420 and then resized to 224x224.

When you select "crop-last" method, if the AI model input tensor dimensions are equal, the image is resized with its smaller side equal to model dimension with respect to degirum.model.Model.input_crop_percentage. If the AI model input tensor dimensions are not equal (rectangle) the image is resized with stretching to the input tensor dimensions with respect to degirum.model.Model.input_crop_percentage. The image is then cropped to fit the AI model input tensor dimensions and aspect ratio.

For example: an input image with dimensions 640x480 going into a model with input tensor dimensions 224x224 with crop percentage of 0.875 will first be resized to 341x256 and then center cropped to 224x224, alternatively an input image with dimensions 640x480 and a model with input tensor dimensions 280x224 will be resized to 320x256 (not preserving image aspect ratio) and then center cropped to 280x224.
InputFmt and ModelFmt parameters of ModelInfo class are deprecated and superseded by InputTensorLayout parameter. In case when some older models do not define InputTensorLayout parameter, the software falls back to deprecated parameters in the following order: InputTensorLayout --> InputFmt --> ModelFmt.
Checksum model JSON file parameter is now mandatory. Attempt to load a model without Checksum parameter now produces a runtime error.
Logging functionality is implemented for PySDK methods and functions. When enabled, each call to every PySDK method or function is logged to the provided Python-style log handler. The logging.INFO logging level is used.

The following example shows how to install a log handler of your choice and set a logging level:
```
import logging

dglogger = logging.getLogger("degirum") # query 'degirum' logger
handler = logging.StreamHandler() # instantiate console printing handler 
# you can use whatever handler you see fit, for example FileHandler or SocketHandler
dglogger.addHandler(handler) # add the handler to the logger
dglogger.setLevel(logging.INFO) # set the logging level
```
If you just want to enable PySDK logging to a console, you may use the degirum.enable_default_logger helper function. Essentially, it performs the code listed just above.

Bug Fixes

In case of cloud inferences, frequent re-connections to the cloud server happen in case of slow Internet connection. This leads to slow performance of the cloud inference. The error was caused by websocket-client third-party library. Now PySDK requirements for websocket-client library are bumped to version 1.5.1, which has necessary fix.
AI Server error handling is improved in case of sudden AI server disconnections. In previous versions the client software may hang in case of sudden AI server disconnection.
AI Server error handling is improved in case of model loading failures such as request to load a model without checksum or when loading a model from a cloud zoo fails. In previous versions the client software may hang in case of model loading failures.

Version 0.5.0 (01/03/2023)

IMPORTANT: This release has changes in PySDK API

IMPORTANT: This release implements incompatible changes in AI Server protocol. If you work in client-server configuration and you upgraded the client-side PySDK, then you also need to upgrade the AI server software to version 0.5.0 and vice versa.

New Features and Modifications

Access to cloud model zoos hosted on DeGirum Cloud Platform is supported in PySDK. Now you may use PySDK to download and request inferences of AI models hosted in the cloud.

The new version of PySDK supports the following use cases: - cloud inference of a model in a cloud zoo; - AI server inference of a model in a cloud zoo; - AI server inference of a model in a local zoo; - local inference of a model in a cloud zoo; - local inference of a model in a local zoo.

The particular use case is selected based on the URL string which you pass to degirum.connect_model_zoo function as the first argument. Please refer to the PySDK documentation for the detailed description of degirum.connect_model_zoo function arguments. Here we provide just short summary:

Inference Type	Model Zoo Type	URL to Use
Cloud inference	Cloud zoo	`"dgcps://cs.degirum.com[/<zoo URL>]"`
AI server inference	Cloud zoo	`("<hostname>", "https://cs.degirum.com[/<zoo URL>]")`
AI server inference	Local zoo	`"<hostname>"`
Local inference	Cloud zoo	`"https://cs.degirum.com[/<zoo URL>]"`
Local inference	Local file	`"/path/to/model.json"`
Local inference	DeGirum Public cloud zoo	`""`

Note: GitHub-hosted cloud model zoos are no longer supported.

Please refer to the PySDK documentation for the detailed description of the cloud zoo operations.

The following new attributes are added to the ModelParams class (as returned by degirum.model.Model.model_info method):

Attribute Name	Description	Possible Values
Pre-Processing-Related Attributes
`InputResizeMethod`	Interpolation algorithm used for image resizing during model training	List of the following strings: `"nearest"`, `"bilinear"`, `"area"`, `"bicubic"`, `"lanczos"`
`InputPadMethod`	How input image is padded when resized during model training	List of the following strings: `"stretch"`, `"letterbox"`
`ImageBackend`	Graphical package used for image processing during model training	List of the following strings: `"pil"`, `"opencv"`

These attributes may be specified in the model configuration JSON file to indicate how the training image set was pre-processed during model training.

The values of these attributes are used as default values for corresponding degirum.model.Model properties: degirum.model.Model.resize_method, degirum.model.Model.pad_method, and degirum.model.Model.image_backend respectively.

The AvailableDeviceMask attribute is deleted from the ModelParams class (as returned by degirum.model.Model.model_info method).
Cloud inference connection and disconnection time is reduced by one second each. Now a single Model.predict() call takes less than one second, while in previous releases it took more than two seconds.
All working/temporary files, which PySDK may create during operation are moved into DeGirum-specific application data directory:
- For Linux it is $HOME/.local/share/DeGirum
- For Windows it is %APPDATA%\DeGirum
- For MacOS it is $HOME/Library/Application Support/DeGirum

Bug Fixes

Semantic segmentation models do not work with cloud inference.
degirum sys-info command incorrectly reports that Intel Myriad device is present in the system, when it is not.

Version 0.4.1 (11/16/2022)

New Features and Modifications

Semantic segmentation models are now supported by PySDK.

For segmentation models the overlay image accessible by InferenceResults.image_overlay property shows all detected segments, highlighted by some color (see more details for color assignments just below).
The Model.overlay_color property now can also be specified as a list of 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].

The default value of overlay_color 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 Model.label_dictionary property to obtain a list of model classes. Each color is automatically assigned to look pretty and different from other colors in the list.
More detailed error information is now reported in the case of cloud server inference failures. This information now includes details reported by the inference stack instead of generic HTTP errors.
PCI device information is now reported by degirum sys-info command for Orca accelerator cards. This information is listed in Device Description entry and includes PCI bus index and device index on that bus.

Version 0.4.0 (09/19/2022)

IMPORTANT: This release has changes in PySDK API

IMPORTANT: This release implements backward-compatible extensions in AI Server protocol. If you work in client-server configuration and you upgraded the client-side PySDK, then you also need to upgrade the AI server software to version 0.4.0.

New Features and Modifications

PySDK command-line interface (CLI) has been implemented. Using PySDK CLI you can:

download AI models from the model zoo repo;
start and stop AI server;
command AI server to rescan local model zoo;
obtain system information dump either from local or remote AI system;
manage AI server tracing facility.

The PySDK CLI is implemented as the degirum executable console script. As a part of PySDK installation it is installed into the system path. This console script extends PySDK functionality through the mechanism of entry points.

The PySDK CLI supports the following commands:

Command	Description
`download-zoo`	Command to download AI models from the model zoo GitHub repo
`server`	Command to control the operation of AI server
`sys-info`	Command to obtain system information dump
`trace`	Command to manage AI server tracing facility

You invoke the console script passing the command from the table above as its first argument followed by command-specific parameters described in the following sections.

Please refer to the PySDK documentation for the detailed description of all CLI commands and their parameters.

The possibility to pass arbitrary frame information objects along with the frame data is implemented for the Model.predict_batch() method. Recall that the Model.predict_batch() method accepts an iterator object which returns the frame data, one frame at a time. Now this iterator object may also return tuples, where the first element of such tuple is traditional frame data and the second element is an object which contains frame information of your choice. When the inference of a frame is complete, the frame information object is stored in the corresponding inference result object: you can access it using the info property of the inference result object. The frame information object can be of any type you want.

This feature is very handy when you need to associate inference results with particular frame attributes. For example, you have labeled data set with ground truth data for each frame, and you need to access this ground truth data in the same place where you have the inference results. The following code demonstrates how to do it:
```
# connect to model zoo and load model as usual

# define iterator function to iterate over frames
def source():
    frame_data = ... # here should be the code to obtain frame data
    ground_truth = ... # here should be the code to obtain ground truth
    yield (frame_data, ground_truth) # return a tuple of frame data and frame info

# perform batch prediction
for result in model.predict_batch(source()):
    print(result.results) # here is your inference result
    print(result.info) # here is your ground truth data for that result
```

Version 0.3.5 (08/31/2022)

New Features and Modifications

Support for floating-point models has been added to the audio pre-processor.
PySDK OpenCV image preprocessor is optimized to improve timing performance.
PySDK documentation and docstrings are updated: missing information has been added, some sections were rewritten for better clarity.

Version 0.3.4 (08/15/2022)

New Features and Modifications

C++ SDK documentation has been updated to reflect recent changes.

Bug Fixes

An attempt to load non-existent model using AI client-server API causes client application crash.
Object detection models may give slightly different bounding box results based on which OS is used to run the inference.

Version 0.3.3 (08/10/2022)

Bug Fixes

ML inference performed on DeGirum Cloud Platform may hang intermittently; more often when running long batch predicts on slow Internet connections.
MSVC compiler warnings are fixed for C++ SDK.

Version 0.3.2 (08/03/2022)

New Features and Modifications

Retries are implemented in PySDK when attempting to connect to DeGirum Cloud Platform servers. This improves robustness in case of poor Internet connection.

When working with DeGirum Cloud Platform, the Model object reconnects to the cloud server at the beginning of each predict() and predict_batch() method call and disconnects at the end. This behavior is implemented to avoid keeping open connections to the cloud server for indefinite time. On the other hand it greatly decreases performance of single-frame or small-batch inferences. In order to improve single-frame performance the Model class now implements context manager interface. On __enter__() it connects to the cloud server and keeps connection open until __exit__() is called. The following code snippet demonstrates this approach:

 import degirum as dg

 zoo = dg.connect_model_zoo("dgcps://cs.degirum.com") # connect to cloud server
 model = zoo.load_model(zoo.list_models()[0]) # load a model
 with model: # key point: use model object as context manager in `with` statement
     # at this point connection to the server server is open 
     # and will be open for all consecutive inferences within `with` statement
     res1 = model.predict("https://degirum.github.io/images/samples/TwoCats.jpg")
     res2 = model.predict("https://degirum.github.io/images/samples/Car.jpg")
     # and so on...
 # and only at this point connection will be closed

When performing long batch prediction using Model.predict_batch() method, the last portion of pipelined inference results was delivered at once. The previous implementation worked the following way: once the last frame is sent for prediction it just waited for completion of all posted frames and only then starts yielding results. This created a long delay before the last portion of results is delivered. The new implementation continues keeping track of ready results and continues delivering them in a timely manner even after the last frame is sent for prediction. This guarantees smooth delivery of results without any time gaps.

Bug Fixes

ML inference performed on DeGirum Cloud Platform may hang intermittently.
ML inference performed on DeGirum Cloud Platform may intermittently raise the following exceptions:
"DegirumException: Connection to cloud server unexpectedly closed"
"DegirumException: Unable to open connection to cloud server cs.degirum.com: Operation aborted."
"TimeoutError: [WinError 10060] A connection attempt failed because the connected party did not properly respond after a period of time, or established connection failed because connected host has failed to respond"
"DegirumException: Unable to access server cs.degirum.com: HTTPSConnectionPool(host='cs.degirum.com', port=443): Read timed out. (read timeout=5)"

They appear more often in case of poor Internet connection.

Rendering of overlay image fails for object detection models when Model.measure_time is set to True, and no objects are detected.

Version 0.3.1 (07/20/2022)

IMPORTANT: This release has critical bug fixes. It is strongly recommended to upgrade your PySDK from version 0.3.0 to version 0.3.1.

Critical Bug Fixes

DeGirum Cloud Platform communication protocol has critical flaw. When an open connection to the cloud server gets interrupted for whatever reason, the client starts sending a stream of reconnection requests flooding the cloud server. When multiple clients start exhibiting such behavior, the cloud server may become not responsive.
When connection to the cloud server gets interrupted during inference, the client script may hang with infinite timeout. Now the following error message will be raised in case of connection failures: "Connection to cloud server unexpectedly closed".
When performing batch inference on the cloud server, the following error may occur intermittently: "Result frame numbers mismatch: expected <N>, processed <M>"", where N and M are some integers numbers.

Other Bug Fixes

When image URL provide for inference is redirection URL (not direct URL to an image file), then PySDK does not follow redirection, and downloads redirection HTML instead. This problem affects, for example, all images from Wikipedia.
Changing parameter(s) of one cloud model object affects all newly created model objects. This bug is similar to the bug fixed in the release 0.2.1 (see below), but affects only cloud models supported in release 0.3.0.
Zoo accessor list_model() method does not support filtering for OpenVINO runtime and Intel Myriad device.
An attempt to send graphical data to audio pre-processor causes not very informative error message. Now the error message says: "Input data format passed for the audio model input #0 is not supported: expected 1-D numpy tensor containing audio waveform of 15600 samples"

New Features and Modifications

Set input image type to "JPEG" when the cloud server model is used to reduce network traffic and improve performance. For all other models "RAW" input image type is set by default to reduce computation load on both client and server to avoid JPEG encoding and decoding.
The following packages are added to the list of PySDK requirements:
- opencv-python
- python-dotenv
- pyaudio (only for Windows platform)
To avoid compatibility problems minimum versions are now provided for all PySDK requirements.

Version 0.3.0 (07/14/2022)

IMPORTANT: This release has changes in PySDK API

IMPORTANT: This release has changes in AI Server protocol, which make it incompatible with previous PySDK versions. If you work in client-server configuration you need to simultaneously upgrade both client and AI server software to version 0.3.0.

New Features and Modifications

The DeGirum Cloud Platform is initially supported in PySDK.

DeGirum Cloud Platform solves the Edge AI development problem by providing the toolchain to design, run, and evaluate ML models across different hardware platforms in the cloud: - no hardware to buy, - no drivers to install, - no worries on software dependencies, - no getting locked to one particular hardware.

DeGirum Cloud Platform includes the following components: - DeGirum Cloud Device Farm accesible through Cloud Application Server and PySDK - DeGirum DeGirum Cloud Portal Management site, cs.degirum.com

The DeGirum Cloud Farm is a set of computing nodes with various AI hardware accelerators installed in those nodes, including: - DeGirum Orca - Google Edge TPU - Intel® Movidius™ Myriad™ VPU

The farm nodes are hosted by DeGirum.

The DeGirum Cloud Application Server provides web API to perform AI inference on the Cloud Farm devices. Starting from ver. 0.3.0 PySDK supports Application Server web API and provides the same level of functionality transparently to the end user: you may run exactly the same code on the Cloud Platform as it was designed for traditional use cases such as local inference or AI server inference.

The DeGirum Cloud Portal Management site provides GUI to manage web API tokens, which are required to access Cloud Application Server through PySDK.

Please visit DeGirum Developers Center for the quick start guide on how to use PySDK with DeGirum Cloud Platform.
Intel® OpenVINO™ runtime is initially supported by DeGirum software stack. It opens possibilities to run OpenVINO™ models in PySDK. For models compiled for Intel® Movidius™ Myriad™ VPU you need to install that VPU on your system which runs DeGirum AI server. Models for OpenVINO™ runtime have openvino suffix in the model name. Models compiled for Myriad™ VPU have myriad suffix in the model name, for example: mobilenet_v2_imagenet--224x224_float_openvino_myriad_1.
AI Server protocol has been updated to revision 2. If you work in client-server configuration you need to simultaneously upgrade both client and AI server software to version 0.3.0. Otherwise you may get the following error message when you try to connect to older AI server with newer 0.3.0 client: Protocol version '2' is out of supported version range [1, 1]. Please upgrade your client software to the most recent version. Or vice versa: Protocol version '1' is out of supported version range [2, 2]. Please upgrade your client software to the most recent version.

When inference time collection is enabled (degirum.model.Model.measure_time property is assigned to True), then additional statistic items are reported for DeGirum Orca AI accelerator hardware:

Key	Description
`DeviceInferenceDuration_ms`	Duration of AI inference computations on AI accelerator IC excluding data transfers
`DeviceTemperature_C`	Internal temperature of AI accelerator IC in C
`DeviceFrequency_MHz`	Working frequency of AI accelerator IC in MHz

Bug Fixes

When Python installation which is used to run PySDK has PIL library version less than 9.1.0, then following error happened when you try to use PIL graphical backend: AttributeError: module 'PIL.Image' has no attribute 'Resampling'. Now PySDK requirements include correct PIL library version of 9.1.0 and above.

Version 0.2.1 (06/23/2022)

IMPORTANT: This release has critical bug fixes.

New Features and Modifications

License plate OCR detection model returned empty result when no license plates detected. Now it returns single result with empty label and zero score.

Critical Bug Fixes

When multiple concurrent AI inferences of YOLOv5-based detection models are running on a single instance of AI server, incorrect inference results may be reported intermittently.

Changing parameter(s) of one model object affects all newly created model objects. For example, consider the following code:

import degirum as dg

zoo = dg.connect_model_zoo()
name = zoo.list_models()[0]

m1 = zoo.load_model(name)
m1.output_postprocess_type = 'None' # change some parameter

m2 = zoo.load_model(name) # create another model object of the same model

assert m2.output_postprocess_type != 'None'
# this assertion fails

Setting output_postprocess_type for the first model affects output_postprocess_type of all models created after that.

Other Bug Fixes

An attempt to read the degirum.model.Model.label_dictionary property of a model, which does not have the label dictionary, leads to runtime exception 'NoneType' object has no attribute 'items'.
An attempt to run inference on a model after assigning non-existing device index to degirum.model.Model.devices_selected property causes AI server crash.

Version 0.2.0 (05/23/2022)

IMPORTANT: This release has changes in PySDK API.

New Features and Modifications

PySDK for macOS 12 / x86-64 / Python 3.9 and macOS 12 / AArch64 / Python 3.9 is officially supported.
PySDK for Ubuntu 20.04 / AArch64 / Python 3.9 is officially supported.

Multi-input models are initially supported.

As a result, all properties of ModelInfo class prefixed with Input prefix changed their type from scalar values to lists. The list size of each such property is equal to the number of model inputs.

The following new properties are added to the ModelInfo class:

Property Name	Description	Possible Values
`InputN`	Input frame dimension size	`1` Other sizes to be supported
`InputH`	Input height dimension size	Integer number
`InputW`	Input width dimension size	Integer number
`InputC`	Input color dimension size	Integer number
`InputQuantEn`	Enable input frame quantization flag (set for quantized models)	Boolean value
`InputQuantOffset`	Quantization offset for input image quantization	List of float values
`InputQuantScale`	Quantization scale for input image quantization	List of float values

The following propertied of the ModelInfo class become deprecated, since they are superseded by complementary per-input properties, listed in the table above.

Property Name	Description	Possible Values
`ModelInputN`	Model frame dimension size	`1` Other sizes to be supported
`ModelInputH`	Model height dimension size	Integer number
`ModelInputW`	Model width dimension size	Integer number
`ModelInputC`	Model color dimension size	Integer number
`ModelQuantEn`	Enable input frame quantization flag (set for quantized models)	Boolean value
`InputImgQuantOffset`	Quantization offset for input image quantization	Float value
`InputImgQuantScale`	Quantization scale for input image quantization	Float value

Audio classification models are initially supported.

For audio models, ModelInfo.InputType property returns Audio input type value.

As a result, the following new properties are added to the ModelInfo class:

Property Name	Description	Possible Values
`InputWaveformSize`	Input waveform size in samples for audio input types	List of positive integer values
`InputSamplingRate`	Input waveform sampling rate in Hz for audio input types	List of positive float values

When dealing with model inputs of audio type (InputType is equal to "Audio"), PySDK does not perform any conversions of the input data: it expects numpy 1-D array with audio waveform samples of proper size and with proper sampling rate. The waveform size should be equal to InputWaveformSize model info property. The waveform sampling rate should be equal to InputSamplingRate model info property. And finally the data element type should be equal to the data type specified by the InputRawDataType model info property.

Non-blocking mode of batch predict is implemented. You turn on this mode by assigning True to new degirum.model.Model.non_blocking_batch_predict property. When non-blocking mode is enabled, the generator object returned by predict_batch() method accepts None from the input iterable object. This allows you to design non-blocking frame data source iterators: when no data is available, such iterator just yields None without waiting for the next frame. If None is returned from the input iterator, the model predict step is simply skipped for this iteration. Also in non-blocking mode when no inference results are available in the result queue at some iteration, the generator yields None result. This allows to continue execution of the code which operates with another model. In order to operate in non-blocking mode you need to modify your code the following way:
- Modify frame data source iterator to return None if no frame is available yet, instead of waiting for the next frame.
- Modify inference loop body to deal with None results by simply skipping them.
Inference device selection is supported. To get the information about available devices you query degirum.model.Model.devices_available property of your model object. It returns the list of zero-based device indices of all available devices of the type this model is designed for. In certain cases you may want to limit the model inference to particular subset of available devices. To do so you need to assign degirum.model.Model.devices_selected property of your model object to contain the list of device indices you want your model to run on.
degirum.model.Model.input_numpy_colorspace property default value is set to RGB for all graphical backends.

Bug Fixes

degirum.zoo_manager.ZooManager.list_models method ignores pruned parameter.
Any run-time error which happens during JPEG image decoding causes quiet process termination.
Any change to degirum.model.Model.output_pose_threshold property is ignored in case when AI server models are used (it works OK when cloud or local models are used).
License Plate OCR model returns result with empty label and score value equal to 1 in case of no results.

Version 0.1.0 (04/19/2022)

IMPORTANT: This release has critical bug fixes.

IMPORTANT: This release has changes in PySDK API.

New Features and Modifications

Python version 3.9 is supported.
The model filtering is introduced for cloud model zoo connections. Now the list of models available for local inference include only models supported by your local hardware configuration. For example, if the local host does not have DeGirum Orca AI accelerator hardware installed, all AI models designed for Orca AI accelerator will not be listed.
Communication protocol version compatibility check is introduced for DeGirum AI server. Now if you try to connect new PySDK client software to older version of DeGirum AI server you will get an error: "AI server: Protocol version 'xx' is out of supported version range [yy,zz]. Please upgrade your client software to the most recent version.".
Access to the model label dictionary is introduced. New method degirum.model.Model.label_dictionary is added to access the model label dictionary. It returns a dictionary where each element is a key-value pair, where the key is the class ID number and the value is the class label string.
New property degirum.model.Model.output_pose_threshold is added. Use this property to control aggregated pose confidence threshold for pose detection models (as opposed to the individual body parts confidence threshold specified by degirum.model.Model.output_confidence_threshold).
New non-positional arguments are added to degirum.server.download_models method. Using these new arguments you may download only specific models from the clound model zoo. The set of new arguments repeats the arguments of degirum.zoo_manager.ZooManager.list_models method:
- model_family: model family name filter. When you pass a string, it will be used as search substring in the model name. For example, "yolo", "mobilenet". You may also pass re.Pattern object: in this case it will do regular expression pattern search.
- device: target inference device - string or list of strings of device names. Possible names: "orca", "cpu", "edgetpu"
- precision: model calculation precision - string or list of strings of model precision labels. Possible labels: "quant", "float"
- pruned: model density - string or list of strings of model density labels. Possible labels: "dense", "pruned"
- runtime: runtime agent type - string or list of strings of runtime agent types: Possible types: "n2x", "tflite"

PySDK inference timing collection API is introduced. It includes the following new features:

degirum.model.Model.measure_time property. Set it to True to enable inference timing collection. Default value is False. When inference timing collection is enabled, the durations of individual steps for each frame prediction are accumulated in internal statistic accumulators.
degirum.model.Model.reset_time_stats method. Call it to reset internal statistic accumulators.

degirum.model.Model.time_stats method. When measure_time property is set to True, the time_stats method returns a dictionary with time statistic objects. Each time statistic object accumulates time statistics for particular inference step over all frame predictions happened since the timing collection was enabled or reset. The statistics includes minimum, maximum, average, and count. Inference steps correspond to dictionary keys. The following dictionary keys are supported:

Key	Description
`"FrameTotalDuration_ms"`	Frame total inference duration
`"PythonPreprocessDuration_ms"`	Duration of Python pre-processing step
`"CorePreprocessDuration_ms"`	Duration of low-level pre-processing step
`"CoreInferenceDuration_ms"`	Duration of actual AI inference step
`"CoreLoadResultDuration_ms"`	Duration of data movement step
`"CorePostprocessDuration_ms"`	Duration of low-level post-processing step

degirum.zoo_manager.ZooManager.rescan_zoo() method is removed from PySDK API.

Critical Bug Fixes

When a model is renamed or removed from a cloud zoo an attempt to connect to such model zoo by calling degirum.connect_model_zoo() produces non-recoverable error KeyError.
Establishing connection to DeGirum AI server specified by host name (as opposed to IP address) takes 2 sec. on Windows OS.

Version 0.0.1 (03/24/2022)

IMPORTANT: This is the first official alpha release of DeGirum PySDK.