MLSingleShot API

The Machine Learning Single Shot API provides functionality for inference with use of neural network models. Single Shot API is useful for a simple usage scenario of neural network models. It allows invoking a neural network model with a single instance of input data for the model directly. It is useful if you have the input data pre-processed with the application itself and there are no complex interactions between neural network models, data processors, or data stream paths.

Remark: In order to access files, a proper privilege has to be defined additionally:

Since: 6.5

Table of Contents

Summary of Interfaces and Methods

Interface Method
MachineLearningSingle
SingleShot openModel (Path modelPath, optional TensorsInfo? inTensorsInfo, optional TensorsInfo? outTensorsInfo, optional NNFWType fwType, optional HWType hwType, optional boolean isDynamicMode)
void openModelAsync (Path modelPath, OpenModelSuccessCallback successCallback, optional ErrorCallback? errorCallback, optional TensorsInfo? inTensorsInfo, optional TensorsInfo? outTensorsInfo, optional NNFWType fwType, optional HWType hwType, optional boolean isDynamicMode)
SingleShot
TensorsData invoke (TensorsData inTensorsData)
void invokeAsync (TensorsData inTensorsData, InvokeAsyncSuccessCallback successCallback, optional ErrorCallback? errorCallback)
DOMString getValue (DOMString name)
void setValue (DOMString name, DOMString value)
void setTimeout (unsigned long timeout)
void close ()
OpenModelSuccessCallback
void onsuccess (SingleShot singleShot)
InvokeAsyncSuccessCallback
void onsuccess (TensorsData tensorsData)

1. Interfaces

1.1. MachineLearningSingle

The Machine Learning single interface that provides access to the Single Shot API. 
  [NoInterfaceObject] interface MachineLearningSingle {
    SingleShot openModel(Path modelPath, optional TensorsInfo? inTensorsInfo, optional TensorsInfo? outTensorsInfo,
                         optional NNFWType fwType = "ANY", optional HWType hwType = "ANY", optional boolean isDynamicMode = false)
                         raises(WebAPIException);
    void openModelAsync(Path modelPath, OpenModelSuccessCallback successCallback, optional ErrorCallback? errorCallback,
                        optional TensorsInfo? inTensorsInfo, optional TensorsInfo? outTensorsInfo, optional NNFWType fwType = "ANY", optional HWType hwType = "ANY", optional boolean isDynamicMode = false) raises(WebAPIException);
  };

Since: 6.5

Methods

openModel
Opens file, loads the neural network model and configures runtime environment with Neural Network Framework and HW information. Use SingleShot::close() method to close the opened model. 
SingleShot openModel(Path modelPath, optional TensorsInfo? inTensorsInfo, optional TensorsInfo? outTensorsInfo,
                     optional NNFWType fwType = "ANY", optional HWType hwType = "ANY", optional boolean isDynamicMode = false);

Since: 6.5

Remark: For bigger models use MachineLearningSingle::openModelAsync() method, which will not block application UI.

Parameters:

  • modelPath: Path to a model. Check Filesystem API for more information about valid path in Tizen.
  • inTensorsInfo [optional] [nullable]: Input TensorsInfo object. This parameter can change model's input if the model supports flexible input.
  • outTensorsInfo [optional] [nullable]: Output TensorsInfo object for inference result. This parameter can change model's output if the model supports flexible output.
  • fwType [optional] [default value = "ANY"]: Type of Neural Network Framework.
  • hwType [optional] [default value = "ANY"]: Type of hardware resources to be used for NNFWs.
  • isDynamicMode [optional] [default value = false]: Support Dynamic Mode. Setting this to true enables changing the information of model's input tensors. Not all of the models or frameworks support changing this information.

Return value:

    SingleShot: SingleShot object which holds Machine Learning model.

Exceptions:

  • WebAPIException

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type NotFoundError, if the file with model is not found.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to access the storage. For more information, see Storage privileges.

    • with error type AbortError, if any other error occurs.

Code example:

var model;
try
{
  model = tizen.ml.single.openModel(
      "documents/mobilenet_v1_1.0_224_quant.tflite", null, null, "TENSORFLOW_LITE", "ANY");
  console.log("Model opened successfully");
}
catch (e)
{
  console.log("Error while opening model: " + e.message);
}

/* Do inference here */

model.close();

Output example:

Model opened successfully
openModelAsync
Opens file asynchronously, loads the neural network model and configures runtime environment with Neural Network Framework and HW information. Use SingleShot::close() method to close opened model. 
void openModelAsync(Path modelPath, OpenModelSuccessCallback successCallback, optional ErrorCallback? errorCallback,
                    optional TensorsInfo? inTensorsInfo, optional TensorsInfo? outTensorsInfo, optional NNFWType fwType = "ANY", optional HWType hwType = "ANY", optional boolean isDynamicMode = false);

Since: 6.5

The ErrorCallback method is launched with these error types:

  • InvalidValuesError - if any of the input parameters contains an invalid value.
  • NotFoundError - if the file with model is not found.
  • NotSupportedError - if the feature is not supported.
  • AbortError - if any other error occurs.

Parameters:

  • modelPath: Path to a model. Check Filesystem API for more information about valid path in Tizen.
  • successCallback: The method to call when the model opens successfully.
  • errorCallback [optional] [nullable]: The method to call when an error occurs.
  • inTensorsInfo [optional] [nullable]: Input TensorsInfo object. This parameter can change model's input if the model supports flexible input.
  • outTensorsInfo [optional] [nullable]: Output TensorsInfo object for inference result. This parameter can change model's output if the model supports flexible output.
  • fwType [optional] [default value = "ANY"]: Type of Neural Network Framework.
  • hwType [optional] [default value = "ANY"]: Type of hardware resources to be used for NNFWs.
  • isDynamicMode [optional] [default value = false]: Support Dynamic Mode. Setting this to true enables changing the information of model's input tensors. Not all of the models or frameworks support changing this information.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type SecurityError, if the application does not have the privilege to access the storage. For more information, see Storage privileges.

    • with error type AbortError, if any other error occurs.

Code example:

function errorCallback(error)
{
  console.log("Error while opening model: " + error.message);
}

function successCallback(model)
{
  console.log("Model opened successfully");

  /* Do inference here */

  model.close();
}
tizen.ml.single.openModelAsync("documents/mobilenet_v1_1.0_224_quant.tflite", successCallback,
    errorCallback, null, null, "TENSORFLOW_LITE", "ANY");

Output example:

Model opened successfully

1.2. SingleShot

The interface provides method for making inferences from input data. 
  [NoInterfaceObject] interface SingleShot {
    attribute TensorsInfo input raises(WebAPIException);
    readonly attribute TensorsInfo output raises(WebAPIException);
    TensorsData invoke(TensorsData inTensorsData) raises(WebAPIException);
    void invokeAsync(TensorsData inTensorsData, InvokeAsyncSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                     raises(WebAPIException);
    DOMString getValue(DOMString name) raises(WebAPIException);
    void setValue(DOMString name, DOMString value) raises(WebAPIException);
    void setTimeout(unsigned long timeout) raises(WebAPIException);
    void close() raises(WebAPIException);
  };

Since: 6.5

Attributes

  • TensorsInfo input
    The information (tensor dimension, type, name and so on) of required input data for the given model.

    Since: 6.5

    Remark: input returns a clone of TensorsInfo object which needs to be disposed when no longer needed.

    Exceptions:

    • WebAPIException

      • with error type TypeMismatchError, if the set value is not compatible with TensorsInfo object.

      • with error type AbortError, if any other error occurs.

    Code example:

    model = tizen.ml.single.openModel("documents/add.tflite");
var input = model.input;
input.setDimensions(0, [5]);
model.input = input;
input.dispose();
  • readonly TensorsInfo output
    The information (tensor dimension, type, name and so on) of output data for the given model.

    Since: 6.5

    Remark: output returns a clone of TensorsInfo object which needs to be disposed when no longer needed.

    Exceptions:

    • WebAPIException

      • with error type AbortError, if any error occurs.

Methods

invoke
Invokes the model with the given input data. 
TensorsData invoke(TensorsData inTensorsData);

Since: 6.5

Remark: For inferences taking more time, it is recommended to use SingleShot::invokeAsync() method, which will not block application UI.

Parameters:

  • inTensorsData: The input data.

Return value:

    TensorsData: TensorsData instance which contains the inferred result.

Exceptions:

  • WebAPIException

    • with error type TimeoutError, if the operation timed out. Timeout can be set with SingleShot::setTimeout() method.

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type NotSupportedError, if this feature is not supported.

    • with error type AbortError, if any other error occurs.

Code example:

model = tizen.ml.single.openModel("documents/mobilenet_v1_1.0_224_quant.tflite");
var tensorsInfo = new tizen.ml.TensorsInfo();
tensorsInfo.addTensorInfo("tensor", "UINT8", [3, 224, 224]);
var tensorsData = tensorsInfo.getTensorsData();

var tensorsDataOut = model.invoke(tensorsData);
console.log(tensorsDataOut.getTensorRawData(0));

/* Always call dispose() on no longer needed objects */
tensorsDataOut.dispose();
tensorsData.dispose();
tensorsInfo.dispose();
model.close();

Output example:

TensorRawData {data: Uint8Array(1001), size: 1001, shape: Array(4)}
invokeAsync
Invokes the model asynchronously with the given input data without blocking application UI. 
void invokeAsync(TensorsData inTensorsData, InvokeAsyncSuccessCallback successCallback, optional ErrorCallback? errorCallback);

Since: 6.5

The ErrorCallback method is launched with these error types:

  • TimeoutError - if the operation is timed out. Timeout can be set with SingleShot::setTimeout() method.
  • NotSupportedError - if the feature is not supported.
  • AbortError - if any other error occurs.

Remark: TensorsData object provided by successCallback needs to be disposed when no longer needed.

Parameters:

  • inTensorsData: The input data.
  • successCallback: The method to call when the inference is finished successfully.
  • errorCallback [optional] [nullable]: The method to call when an error occurs.

Exceptions:

  • WebAPIException

    • with error type TypeMismatchError, if any input parameter is not compatible with the expected type for that parameter.

    • with error type AbortError, if any other error occurs.

Code example:

model = tizen.ml.single.openModel("documents/mobilenet_v1_1.0_224_quant.tflite");
var tensorsInfo = new tizen.ml.TensorsInfo();
tensorsInfo.addTensorInfo("tensor", "UINT8", [3, 224, 224]);
var tensorsData = tensorsInfo.getTensorsData();

function errorCallback(error)
{
  console.log("Error during invokeAsync: " + error.message);
}

function successCallback(tensorsDataOut)
{
  console.log("Inference finished successfully");

  /* process tensorsDataOut here */
  console.log(tensorsDataOut.getTensorRawData(0));

  /* Always call dispose() on no longer needed objects */
  tensorsDataOut.dispose();
  tensorsData.dispose();
  tensorsInfo.dispose();
  model.close();
}

model.invokeAsync(tensorsData, successCallback, errorCallback);

Output example:

Inference finished successfully
TensorRawData {data: Uint8Array(1001), size: 1001, shape: Array(4)}
getValue
Gets the property value for the given model. 
DOMString getValue(DOMString name);

Since: 6.5

Parameters:

  • name: The property name.

Return value:

    DOMString: The property value.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported, or given property is not available.

    • with error type AbortError, if any other error occurs.

Code example:

var model = tizen.ml.single.openModel("documents/mobilenet_v1_1.0_224_quant.tflite");
var key = "input";
console.log("Value for " + key + ": " + model.getValue(key));
model.close();

Output example:

Value for input: 3:224:224:1
setValue
Sets the property value for the given model. A model/framework may support changing the model information, such as tensor dimension and data layout. If model does not support changing the information, this method will raise an exception. 
void setValue(DOMString name, DOMString value);

Since: 6.5

Parameters:

  • name: The property name.
  • value: The property value.

Exceptions:

  • WebAPIException

    • with error type InvalidValuesError, if any of the input parameters contain an invalid value.

    • with error type NotSupportedError, if this feature is not supported, or given property is not available.

    • with error type AbortError, if any other error occurs.

Code example:

var model = tizen.ml.single.openModel("documents/mobilenet_v1_1.0_224_quant.tflite");
var key = "input";
console.log("Value for " + key + ": " + model.getValue(key));
model.setValue(key, "3:224:224:7");
console.log("Value for " + key + " after update: " + model.getValue(key));
model.close();

Output example:

Value for input: 3:224:224:1
Value for input after update: 3:224:224:7
setTimeout
Sets the maximum amount of time to wait for an output from SingleShot::invoke() method, in milliseconds. 
void setTimeout(unsigned long timeout);

Since: 6.5

Parameters:

  • timeout: The time to wait for an output.

Exceptions:

  • WebAPIException

    • with error type NotSupportedError, if this feature is not supported, or given property is not available.

    • with error type AbortError, if any other error occurs.

Code example:

var model = tizen.ml.single.openModel("documents/mobilenet_v1_1.0_224_quant.tflite");

/* 1 ms is used only for testing, to show TimeoutError */
/* Use more reasonable value in real life applications */
model.setTimeout(1);

var tensorsInfo = new tizen.ml.TensorsInfo();
tensorsInfo.addTensorInfo("tensor", "UINT8", [3, 224, 224]);
var tensorsData = tensorsInfo.getTensorsData();
try
{
  var tensorsDataOut = model.invoke(tensorsData);

  /* Always call dispose() on no longer needed objects */
  tensorsDataOut.dispose();
}
catch (e)
{
  console.log("Error: " + e.message);
}

/* Always call dispose() on no longer needed objects */
tensorsData.dispose();
tensorsInfo.dispose();
model.close();

Output example:

Error: Failed to invoke: timeout
close
Closes the model and releases memory. 
void close();

Since: 6.5

Remark: Calling methods on closed model will trigger AbortError.

Exceptions:

  • WebAPIException

    • with error type AbortError, if any error occurs.

Code example:

var model = tizen.ml.single.openModel(
    "documents/mobilenet_v1_1.0_224_quant.tflite", null, null, "TENSORFLOW_LITE", "ANY");
model.close();
try
{
  console.log(model.input);
}
catch (e)
{
  console.log("Error: " + e.message);
}

Output example:

Error: SingleShot object was closed and using it is no longer possible.

1.3. OpenModelSuccessCallback

The OpenModelSuccessCallback interface provides a SuccessCallback for the MachineLearningSingle::openModelAsync() method. 
  [Callback=FunctionOnly, NoInterfaceObject] interface OpenModelSuccessCallback {
    void onsuccess(SingleShot singleShot);
  };

Since: 6.5

Methods

onsuccess
Called when the model file is opened successfully. 
void onsuccess(SingleShot singleShot);

Since: 6.5

Parameters:

1.4. InvokeAsyncSuccessCallback

The InvokeAsyncSuccessCallback interface provides a SuccessCallback for the SingleShot::invokeAsync() method. 
  [Callback=FunctionOnly, NoInterfaceObject] interface InvokeAsyncSuccessCallback {
    void onsuccess(TensorsData tensorsData);
  };

Since: 6.5

Methods

onsuccess
Called when the inference was finished successfully. 
void onsuccess(TensorsData tensorsData);

Since: 6.5

Parameters:

2. Related Feature

Method tizen.systeminfo.getCapability() can be used in application runtime to check whether this API is supported.

To guarantee that the ML application runs on a device with the ML feature, declare the following feature requirements in the config file:

  • http://tizen.org/feature/machine_learning

    • To guarantee that the ML application runs on a device with the ML Inference feature, declare the following feature requirements in the config file:

  • http://tizen.org/feature/machine_learning.inference

    • For more information, see Application Filtering.

    3. Full WebIDL

    module MLSingleShot {
  [NoInterfaceObject] interface MachineLearningSingle {
    SingleShot openModel(Path modelPath, optional TensorsInfo? inTensorsInfo, optional TensorsInfo? outTensorsInfo,
                         optional NNFWType fwType = "ANY", optional HWType hwType = "ANY", optional boolean isDynamicMode = false)
                         raises(WebAPIException);
    void openModelAsync(Path modelPath, OpenModelSuccessCallback successCallback, optional ErrorCallback? errorCallback,
                        optional TensorsInfo? inTensorsInfo, optional TensorsInfo? outTensorsInfo, optional NNFWType fwType = "ANY", optional HWType hwType = "ANY", optional boolean isDynamicMode = false) raises(WebAPIException);
  };
  [NoInterfaceObject] interface SingleShot {
    attribute TensorsInfo input raises(WebAPIException);
    readonly attribute TensorsInfo output raises(WebAPIException);
    TensorsData invoke(TensorsData inTensorsData) raises(WebAPIException);
    void invokeAsync(TensorsData inTensorsData, InvokeAsyncSuccessCallback successCallback, optional ErrorCallback? errorCallback)
                     raises(WebAPIException);
    DOMString getValue(DOMString name) raises(WebAPIException);
    void setValue(DOMString name, DOMString value) raises(WebAPIException);
    void setTimeout(unsigned long timeout) raises(WebAPIException);
    void close() raises(WebAPIException);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface OpenModelSuccessCallback {
    void onsuccess(SingleShot singleShot);
  };
  [Callback=FunctionOnly, NoInterfaceObject] interface InvokeAsyncSuccessCallback {
    void onsuccess(TensorsData tensorsData);
  };
};
    Except as noted, this content - excluding the Code Examples - is licensed under Creative Commons Attribution 3.0 and all of the Code Examples contained herein are licensed under BSD-3-Clause.
    For details, see the Content License.