xref: /aosp_15_r20/external/tensorflow/tensorflow/lite/objc/apis/TFLInterpreter.h (revision b6fb3261f9314811a0f4371741dbb8839866f948)
1 // Copyright 2018 Google Inc. All rights reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at:
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14 
15 #import <Foundation/Foundation.h>
16 
17 @class TFLDelegate;
18 @class TFLInterpreterOptions;
19 @class TFLSignatureRunner;
20 @class TFLTensor;
21 
22 NS_ASSUME_NONNULL_BEGIN
23 
24 /**
25  * @enum TFLInterpreterErrorCode
26  * This enum specifies various error codes related to `TFLInterpreter`.
27  */
28 typedef NS_ENUM(NSUInteger, TFLInterpreterErrorCode) {
29   /** Provided tensor index is invalid. */
30   TFLInterpreterErrorCodeInvalidTensorIndex,
31 
32   /** Input data has invalid byte size. */
33   TFLInterpreterErrorCodeInvalidInputByteSize,
34 
35   /** Provided shape is invalid. It must be a non-empty array of positive unsigned integers. */
36   TFLInterpreterErrorCodeInvalidShape,
37 
38   /** Provided model cannot be loaded. */
39   TFLInterpreterErrorCodeFailedToLoadModel,
40 
41   /** Failed to create `TFLInterpreter`. */
42   TFLInterpreterErrorCodeFailedToCreateInterpreter,
43 
44   /** Failed to invoke `TFLInterpreter`. */
45   TFLInterpreterErrorCodeFailedToInvoke,
46 
47   /** Failed to retrieve a tensor. */
48   TFLInterpreterErrorCodeFailedToGetTensor,
49 
50   /** Invalid tensor. */
51   TFLInterpreterErrorCodeInvalidTensor,
52 
53   /** Failed to resize an input tensor. */
54   TFLInterpreterErrorCodeFailedToResizeInputTensor,
55 
56   /** Failed to copy data into an input tensor. */
57   TFLInterpreterErrorCodeFailedToCopyDataToInputTensor,
58 
59   /** Copying data into an output tensor not allowed. */
60   TFLInterpreterErrorCodeCopyDataToOutputTensorNotAllowed,
61 
62   /** Failed to get data from a tensor. */
63   TFLInterpreterErrorCodeFailedToGetDataFromTensor,
64 
65   /** Failed to allocate memory for tensors. */
66   TFLInterpreterErrorCodeFailedToAllocateTensors,
67 
68   /** Operation not allowed without allocating memory for tensors first. */
69   TFLInterpreterErrorCodeAllocateTensorsRequired,
70 
71   /** Operation not allowed without invoking the interpreter first. */
72   TFLInterpreterErrorCodeInvokeInterpreterRequired,
73 };
74 
75 /**
76  * A TensorFlow Lite model interpreter.
77  *
78  * Note: Interpreter instances are *not* thread-safe.
79  */
80 @interface TFLInterpreter : NSObject
81 
82 /** The total number of input tensors. 0 if the interpreter creation failed. */
83 @property(nonatomic, readonly) NSUInteger inputTensorCount;
84 
85 /** The total number of output tensors. 0 if the interpreter creation failed. */
86 @property(nonatomic, readonly) NSUInteger outputTensorCount;
87 
88 /** An ordered list of the SignatureDef exported method names available in the model. */
89 @property(nonatomic, readonly) NSArray<NSString *> *signatureKeys;
90 
91 /** Unavailable. */
92 - (instancetype)init NS_UNAVAILABLE;
93 + (instancetype)new NS_UNAVAILABLE;
94 
95 /**
96  * Initializes a new TensorFlow Lite interpreter instance with the given model file path and the
97  * default interpreter options.
98  *
99  * @param modelPath An absolute path to a TensorFlow Lite model file stored locally on the device.
100  * @param error An optional error parameter populated when there is an error in initializing the
101  *     interpreter.
102  *
103  * @return A new instance of `TFLInterpreter` with the given model and the default interpreter
104  *     options. `nil` if there is an error in initializing the interpreter.
105  */
106 - (nullable instancetype)initWithModelPath:(NSString *)modelPath error:(NSError **)error;
107 
108 /**
109  * Initializes a new TensorFlow Lite interpreter instance with the given model file path and
110  * options.
111  *
112  * @param modelPath An absolute path to a TensorFlow Lite model file stored locally on the device.
113  * @param options Options to use for configuring the TensorFlow Lite interpreter.
114  * @param error An optional error parameter populated when there is an error in initializing the
115  *     interpreter.
116  *
117  * @return A new instance of `TFLInterpreter` with the given model and options. `nil` if there is an
118  *     error in initializing the interpreter.
119  */
120 - (nullable instancetype)initWithModelPath:(NSString *)modelPath
121                                    options:(TFLInterpreterOptions *)options
122                                      error:(NSError **)error;
123 
124 /**
125  * Initializes a new TensorFlow Lite interpreter instance with the given model file path, options
126  * and delegates.
127  *
128  * @param modelPath An absolute path to a TensorFlow Lite model file stored locally on the device.
129  * @param options Options to use for configuring the TensorFlow Lite interpreter.
130  * @param delegates Delegates to use with the TensorFlow Lite interpreter. When the array is empty,
131  *     no delegate will be applied.
132  * @param error An optional error parameter populated when there is an error in initializing the
133  *     interpreter.
134  *
135  * @return A new instance of `TFLInterpreter` with the given model and options. `nil` if there is an
136  *     error in initializing the interpreter.
137  */
138 - (nullable instancetype)initWithModelPath:(NSString *)modelPath
139                                    options:(TFLInterpreterOptions *)options
140                                  delegates:(NSArray<TFLDelegate *> *)delegates
141                                      error:(NSError **)error NS_DESIGNATED_INITIALIZER;
142 
143 /**
144  * Invokes the interpreter to run inference.
145  *
146  * @param error An optional error parameter populated when there is an error in invoking the
147  *     interpreter.
148  *
149  * @return Whether the invocation is successful. Returns NO if an error occurred.
150  */
151 - (BOOL)invokeWithError:(NSError **)error;
152 
153 /**
154  * Returns the input tensor at the given index.
155  *
156  * @param index The index of an input tensor.
157  * @param error An optional error parameter populated when there is an error in looking up the input
158  *     tensor.
159  *
160  * @return The input tensor at the given index. `nil` if there is an error. See the `TFLTensor`
161  *     class documentation for more details on the life expectancy between the returned tensor and
162  *     this interpreter.
163  */
164 - (nullable TFLTensor *)inputTensorAtIndex:(NSUInteger)index error:(NSError **)error;
165 
166 /**
167  * Returns the output tensor at the given index.
168  *
169  * @param index The index of an output tensor.
170  * @param error An optional error parameter populated when there is an error in looking up the
171  *     output tensor.
172  *
173  * @return The output tensor at the given index. `nil` if there is an error. See the `TFLTensor`
174  *     class documentation for more details on the life expectancy between the returned tensor and
175  *     this interpreter.
176  */
177 - (nullable TFLTensor *)outputTensorAtIndex:(NSUInteger)index error:(NSError **)error;
178 
179 /**
180  * Resizes the input tensor at the given index to the specified shape (an array of positive unsigned
181  * integers).
182  *
183  * @param index The index of an input tensor.
184  * @param shape Shape that the given input tensor should be resized to. It should be an array of
185  *     positive unsigned integer(s) containing the size of each dimension.
186  * @param error An optional error parameter populated when there is an error in resizing the input
187  *     tensor.
188  *
189  * @return Whether the input tensor was resized successfully. Returns NO if an error occurred.
190  */
191 - (BOOL)resizeInputTensorAtIndex:(NSUInteger)index
192                          toShape:(NSArray<NSNumber *> *)shape
193                            error:(NSError **)error;
194 
195 /**
196  * Allocates memory for tensors.
197  *
198  * @param error An optional error parameter populated when there is an error in allocating memory.
199  *
200  * @return Whether memory allocation is successful. Returns NO if an error occurred.
201  */
202 - (BOOL)allocateTensorsWithError:(NSError **)error;
203 
204 /**
205  * Returns a new signature runner instance for the signature with the given key in the model.
206  *
207  * @param key The signature key.
208  * @param error An optional error parameter populated when there is an error creating the signature
209  * runner.
210  *
211  * @return A new signature runner instance for the signature with given key.
212  */
213 - (nullable TFLSignatureRunner *)signatureRunnerWithKey:(NSString *)key error:(NSError **)error;
214 
215 @end
216 
217 NS_ASSUME_NONNULL_END
218