Interpreter (tflite-native 2.4.1 API)

java.lang.Object
- org.tensorflow.lite.Interpreter

All Implemented Interfaces:

java.lang.AutoCloseable
```
public final class Interpreter
extends java.lang.Object
implements java.lang.AutoCloseable
```
Driver class to drive model inference with TensorFlow Lite.
A Interpreter encapsulates a pre-trained TensorFlow Lite model, in which operations are executed for model inference.
For example, if a model takes only one input and returns only one output:
```
 try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
   interpreter.run(input, output);
 }
 
```
If a model takes multiple inputs or outputs:
```
 Object[] inputs = {input0, input1, ...};
 Map<Integer, Object> map_of_indices_to_outputs = new HashMap<>();
 FloatBuffer ith_output = FloatBuffer.allocateDirect(3 * 2 * 4);  // Float tensor, shape 3x2x4.
 ith_output.order(ByteOrder.nativeOrder());
 map_of_indices_to_outputs.put(i, ith_output);
 try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
   interpreter.runForMultipleInputsOutputs(inputs, map_of_indices_to_outputs);
 }
 
```
If a model takes or produces string tensors:
```
 String[] input = {"foo", "bar"};  // Input tensor shape is [2].
 String[] output = new String[3][2];  // Output tensor shape is [3, 2].
 try (Interpreter interpreter = new Interpreter(file_of_a_tensorflowlite_model)) {
   interpreter.runForMultipleInputsOutputs(input, output);
 }
 
```
Orders of inputs and outputs are determined when converting TensorFlow model to TensorFlowLite model with Toco, as are the default shapes of the inputs.
When inputs are provided as (multi-dimensional) arrays, the corresponding input tensor(s) will be implicitly resized according to that array's shape. When inputs are provided as Buffer types, no implicit resizing is done; the caller must ensure that the Buffer byte size either matches that of the corresponding tensor, or that they first resize the tensor via resizeInput(int, int[]). Tensor shape and type information can be obtained via the Tensor class, available via getInputTensor(int) and getOutputTensor(int).
WARNING:Instances of a Interpreter is not thread-safe. A Interpreter owns resources that must be explicitly freed by invoking close()
The TFLite library is built against NDK API 19. It may work for Android API levels below 19, but is not guaranteed.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Interpreter.Options
An options class for controlling runtime interpreter behavior.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Interpreter.Options` An options class for controlling runtime interpreter behavior.

Constructor Summary

Constructors
Constructor and Description
`Interpreter(java.nio.ByteBuffer byteBuffer)` Initializes a `Interpreter` with a `ByteBuffer` of a model file.
`Interpreter(java.nio.ByteBuffer byteBuffer, int numThreads)` Deprecated. Prefer using the `Interpreter(ByteBuffer,Options)` constructor. This method will be removed in a future release.
`Interpreter(java.nio.ByteBuffer byteBuffer, Interpreter.Options options)` Initializes a `Interpreter` with a `ByteBuffer` of a model file and a set of custom `Interpreter.Options`.
`Interpreter(java.io.File modelFile)` Initializes a `Interpreter`
`Interpreter(java.io.File modelFile, int numThreads)` Deprecated. Prefer using the `Interpreter(File,Options)` constructor. This method will be removed in a future release.
`Interpreter(java.io.File modelFile, Interpreter.Options options)` Initializes a `Interpreter` and specifies the number of threads used for inference.
`Interpreter(java.nio.MappedByteBuffer mappedByteBuffer)` Deprecated. Prefer using the `Interpreter(ByteBuffer,Options)` constructor. This method will be removed in a future release.

Method Summary

All Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method and Description
`void`	`allocateTensors()` Expicitly updates allocations for all tensors, if necessary.
`void`	`close()` Release resources associated with the `Interpreter`.
`protected void`	`finalize()`
`int`	`getInputIndex(java.lang.String opName)` Gets index of an input given the op name of the input.
`Tensor`	`getInputTensor(int inputIndex)` Gets the Tensor associated with the provdied input index.
`int`	`getInputTensorCount()` Gets the number of input tensors.
`java.lang.Long`	`getLastNativeInferenceDurationNanoseconds()` Returns native inference timing.
`int`	`getOutputIndex(java.lang.String opName)` Gets index of an output given the op name of the output.
`Tensor`	`getOutputTensor(int outputIndex)` Gets the Tensor associated with the provdied output index.
`int`	`getOutputTensorCount()` Gets the number of output Tensors.
`void`	`modifyGraphWithDelegate(Delegate delegate)` Deprecated. Prefer using `Interpreter.Options.addDelegate(org.tensorflow.lite.Delegate)` to provide delegates at creation time. This method will be removed in a future release.
`void`	`resetVariableTensors()` Advanced: Resets all variable tensors to the default value.
`void`	`resizeInput(int idx, int[] dims)` Resizes idx-th input of the native model to the given dims.
`void`	`resizeInput(int idx, int[] dims, boolean strict)` Resizes idx-th input of the native model to the given dims.
`void`	`run(java.lang.Object input)` Runs model inference if the model takes only one input, and provides only one output.
`void`	`runForMultipleInputsOutputs(java.lang.Object[] inputs)` Runs model inference if the model takes multiple inputs, or returns multiple outputs.
`void`	`setCancelled(boolean cancelled)` Advanced: Interrupts inference in the middle of a call to `run(java.lang.Object)`.
`void`	`setNumThreads(int numThreads)` Deprecated. Prefer using `Interpreter.Options.setNumThreads(int)` directly for controlling thread multi-threading. This method will be removed in a future release.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Constructor Detail
  - Interpreter
```
public Interpreter(java.io.File modelFile)
```
    Initializes a Interpreter
    
    Parameters:
    
    modelFile - a File of a pre-trained TF Lite model.
    
    Throws:
    
    java.lang.IllegalArgumentException - if modelFile does not encode a valid TensorFlow Lite model.
  - Interpreter
```
@Deprecated
public Interpreter(java.io.File modelFile,
                               int numThreads)
```
    Deprecated. Prefer using the Interpreter(File,Options) constructor. This method will be removed in a future release.
    
    Initializes a Interpreter and specifies the number of threads used for inference.
    
    Parameters:
    
    modelFile - a file of a pre-trained TF Lite model
    
    numThreads - number of threads to use for inference
  - Interpreter
```
public Interpreter(java.io.File modelFile,
                   Interpreter.Options options)
```
    Initializes a Interpreter and specifies the number of threads used for inference.
    
    Parameters:
    
    modelFile - a file of a pre-trained TF Lite model
    
    options - a set of options for customizing interpreter behavior
    
    Throws:
    
    java.lang.IllegalArgumentException - if modelFile does not encode a valid TensorFlow Lite model.
  - Interpreter
```
public Interpreter(java.nio.ByteBuffer byteBuffer)
```
    Initializes a Interpreter with a ByteBuffer of a model file.
    The ByteBuffer should not be modified after the construction of a Interpreter. The ByteBuffer can be either a MappedByteBuffer that memory-maps a model file, or a direct ByteBuffer of nativeOrder() that contains the bytes content of a model.
    
    Throws:
    
    java.lang.IllegalArgumentException - if byteBuffer is not a MappedByteBuffer nor a direct ByteBuffer of nativeOrder.
  - Interpreter
```
@Deprecated
public Interpreter(java.nio.ByteBuffer byteBuffer,
                               int numThreads)
```
    Deprecated. Prefer using the Interpreter(ByteBuffer,Options) constructor. This method will be removed in a future release.
    
    Initializes a Interpreter with a ByteBuffer of a model file and specifies the number of threads used for inference.
    The ByteBuffer should not be modified after the construction of a Interpreter. The ByteBuffer can be either a MappedByteBuffer that memory-maps a model file, or a direct ByteBuffer of nativeOrder() that contains the bytes content of a model.
  - Interpreter
```
@Deprecated
public Interpreter(java.nio.MappedByteBuffer mappedByteBuffer)
```
    Deprecated. Prefer using the Interpreter(ByteBuffer,Options) constructor. This method will be removed in a future release.
    
    Initializes a Interpreter with a MappedByteBuffer to the model file.
    The MappedByteBuffer should remain unchanged after the construction of a Interpreter.
  - Interpreter
```
public Interpreter(java.nio.ByteBuffer byteBuffer,
                   Interpreter.Options options)
```
    Initializes a Interpreter with a ByteBuffer of a model file and a set of custom Interpreter.Options.
    The ByteBuffer should not be modified after the construction of a Interpreter. The ByteBuffer can be either a MappedByteBuffer that memory-maps a model file, or a direct ByteBuffer of nativeOrder() that contains the bytes content of a model.
    
    Throws:
    
    java.lang.IllegalArgumentException - if byteBuffer is not a MappedByteBuffer nor a direct ByteBuffer of nativeOrder.
- Method Detail
  - run
```
public void run(java.lang.Object input)
```
    Runs model inference if the model takes only one input, and provides only one output.
    Warning: The API is more efficient if a Buffer (preferably direct, but not required) is used as the input/output data type. Please consider using Buffer to feed and fetch primitive data for better performance. The following concrete Buffer types are supported:
    - ByteBuffer - compatible with any underlying primitive Tensor type.
    - FloatBuffer - compatible with float Tensors.
    - IntBuffer - compatible with int32 Tensors.
    - LongBuffer - compatible with int64 Tensors.
    Note that boolean types are only supported as arrays, not Buffers, or as scalar inputs.
    Parameters:
    
    input - an array or multidimensional array, or a Buffer of primitive types including int, float, long, and byte. Buffer is the preferred way to pass large input data for primitive types, whereas string types require using the (multi-dimensional) array input path. When a Buffer is used, its content should remain unchanged until model inference is done, and the caller must ensure that the Buffer is at the appropriate read position. A null value is allowed only if the caller is using a Delegate that allows buffer handle interop, and such a buffer has been bound to the input Tensor.
    
    Throws:
    
    java.lang.IllegalArgumentException - if input or output is null or empty, or if error occurs when running the inference.
    
    java.lang.IllegalArgumentException - (EXPERIMENTAL, subject to change) if the inference is interrupted by setCancelled(true).
  - runForMultipleInputsOutputs
```
public void runForMultipleInputsOutputs(java.lang.Object[] inputs)
```
    Runs model inference if the model takes multiple inputs, or returns multiple outputs.
    Warning: The API is more efficient if Buffers (preferably direct, but not required) are used as the input/output data types. Please consider using Buffer to feed and fetch primitive data for better performance. The following concrete Buffer types are supported:
    - ByteBuffer - compatible with any underlying primitive Tensor type.
    - FloatBuffer - compatible with float Tensors.
    - IntBuffer - compatible with int32 Tensors.
    - LongBuffer - compatible with int64 Tensors.
    Note that boolean types are only supported as arrays, not Buffers, or as scalar inputs.
    Note: null values for invididual elements of inputs and outputs is allowed only if the caller is using a Delegate that allows buffer handle interop, and such a buffer has been bound to the corresponding input or output Tensor(s).
    Parameters:
    
    inputs - an array of input data. The inputs should be in the same order as inputs of the model. Each input can be an array or multidimensional array, or a Buffer of primitive types including int, float, long, and byte. Buffer is the preferred way to pass large input data, whereas string types require using the (multi-dimensional) array input path. When Buffer is used, its content should remain unchanged until model inference is done, and the caller must ensure that the Buffer is at the appropriate read position.
    
    Throws:
    
    java.lang.IllegalArgumentException - if inputs or outputs is null or empty, or if error occurs when running the inference.
  - allocateTensors
```
public void allocateTensors()
```
    Expicitly updates allocations for all tensors, if necessary.
    This will propagate shapes and memory allocations for all dependent tensors using the input tensor shape(s) as given.
    Note: This call is *purely optional*. Tensor allocation will occur automatically during execution if any input tensors have been resized. This call is most useful in determining the shapes for any output tensors before executing the graph, e.g.,
```
 interpreter.resizeInput(0, new int[]{1, 4, 4, 3}));
 interpreter.allocateTensors();
 FloatBuffer input = FloatBuffer.allocate(interpreter.getInputTensor(0),numElements());
 // Populate inputs...
 FloatBuffer output = FloatBuffer.allocate(interpreter.getOutputTensor(0).numElements());
 interpreter.run(input, output)
 // Process outputs...
 
```
    Throws:
    
    java.lang.IllegalStateException - if the graph's tensors could not be successfully allocated.
  - resizeInput
```
public void resizeInput(int idx,
                        int[] dims)
```
    Resizes idx-th input of the native model to the given dims.
    
    Throws:
    
    java.lang.IllegalArgumentException - if idx is negtive or is not smaller than the number of model inputs; or if error occurs when resizing the idx-th input.
  - resizeInput
```
public void resizeInput(int idx,
                        int[] dims,
                        boolean strict)
```
    Resizes idx-th input of the native model to the given dims.
    When `strict` is True, only unknown dimensions can be resized. Unknown dimensions are indicated as `-1` in the array returned by `Tensor.shapeSignature()`.
    
    Throws:
    
    java.lang.IllegalArgumentException - if idx is negtive or is not smaller than the number of model inputs; or if error occurs when resizing the idx-th input. Additionally, the error occurs when attempting to resize a tensor with fixed dimensions when `struct` is True.
  - getInputTensorCount
```
public int getInputTensorCount()
```
    Gets the number of input tensors.
  - getInputIndex
```
public int getInputIndex(java.lang.String opName)
```
    Gets index of an input given the op name of the input.
    
    Throws:
    
    java.lang.IllegalArgumentException - if opName does not match any input in the model used to initialize the Interpreter.
  - getInputTensor
```
public Tensor getInputTensor(int inputIndex)
```
    Gets the Tensor associated with the provdied input index.
    
    Throws:
    
    java.lang.IllegalArgumentException - if inputIndex is negtive or is not smaller than the number of model inputs.
  - getOutputTensorCount
```
public int getOutputTensorCount()
```
    Gets the number of output Tensors.
  - getOutputIndex
```
public int getOutputIndex(java.lang.String opName)
```
    Gets index of an output given the op name of the output.
    
    Throws:
    
    java.lang.IllegalArgumentException - if opName does not match any output in the model used to initialize the Interpreter.
  - getOutputTensor
```
public Tensor getOutputTensor(int outputIndex)
```
    Gets the Tensor associated with the provdied output index.
    Note: Output tensor details (e.g., shape) may not be fully populated until after inference is executed. If you need updated details *before* running inference (e.g., after resizing an input tensor, which may invalidate output tensor shapes), use allocateTensors() to explicitly trigger allocation and shape propagation. Note that, for graphs with output shapes that are dependent on input *values*, the output shape may not be fully determined until running inference.
    
    Throws:
    
    java.lang.IllegalArgumentException - if outputIndex is negtive or is not smaller than the number of model outputs.
  - getLastNativeInferenceDurationNanoseconds
```
public java.lang.Long getLastNativeInferenceDurationNanoseconds()
```
    Returns native inference timing.
    
    Throws:
    
    java.lang.IllegalArgumentException - if the model is not initialized by the Interpreter.
  - setNumThreads
```
@Deprecated
public void setNumThreads(int numThreads)
```
    Deprecated. Prefer using Interpreter.Options.setNumThreads(int) directly for controlling thread multi-threading. This method will be removed in a future release.
    
    Sets the number of threads to be used for ops that support multi-threading.
  - modifyGraphWithDelegate
```
@Deprecated
public void modifyGraphWithDelegate(Delegate delegate)
```
    Deprecated. Prefer using Interpreter.Options.addDelegate(org.tensorflow.lite.Delegate) to provide delegates at creation time. This method will be removed in a future release.
    
    Advanced: Modifies the graph with the provided Delegate.
    
    Throws:
    
    java.lang.IllegalArgumentException - if error occurs when modifying graph with delegate.
  - resetVariableTensors
```
public void resetVariableTensors()
```
    Advanced: Resets all variable tensors to the default value.
    If a variable tensor doesn't have an associated buffer, it will be reset to zero.
    WARNING: This is an experimental API and subject to change.
  - setCancelled
```
public void setCancelled(boolean cancelled)
```
    Advanced: Interrupts inference in the middle of a call to run(java.lang.Object).
    A cancellation flag will be set to true when this function gets called. The interpreter will check the flag between Op invocations, and if it's true, the interpreter will stop execution. The interpreter will remain a cancelled state until explicitly "uncancelled" by setCancelled(false).
    WARNING: This is an experimental API and subject to change.
    
    Parameters:
    
    cancelled - true to cancel inference in a best-effort way; false to resume.
    
    Throws:
    
    java.lang.IllegalStateException - if the interpreter is not initialized with the cancellable option, which is by default off.
  - close
```
public void close()
```
    Release resources associated with the Interpreter.
    
    Specified by:
    
    close in interface java.lang.AutoCloseable
  - finalize
```
protected void finalize()
                 throws java.lang.Throwable
```
    Overrides:
    
    finalize in class java.lang.Object
    
    Throws:
    
    java.lang.Throwable

Class Interpreter

Nested Class Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

Interpreter

Interpreter

Interpreter

Interpreter

Interpreter

Interpreter

Interpreter

Method Detail

run

runForMultipleInputsOutputs

allocateTensors

resizeInput

resizeInput

getInputTensorCount

getInputIndex

getInputTensor

getOutputTensorCount

getOutputIndex

getOutputTensor

getLastNativeInferenceDurationNanoseconds

setNumThreads

modifyGraphWithDelegate

resetVariableTensors

setCancelled

close

finalize