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