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 TFLTensor; 20 21 NS_ASSUME_NONNULL_BEGIN 22 23 /** 24 * @enum TFLInterpreterErrorCode 25 * This enum specifies various error codes related to `TFLInterpreter`. 26 */ 27 typedef NS_ENUM(NSUInteger, TFLInterpreterErrorCode) { 28 /** Provided tensor index is invalid. */ 29 TFLInterpreterErrorCodeInvalidTensorIndex, 30 31 /** Input data has invalid byte size. */ 32 TFLInterpreterErrorCodeInvalidInputByteSize, 33 34 /** Provided shape is invalid. It must be a non-empty array of positive unsigned integers. */ 35 TFLInterpreterErrorCodeInvalidShape, 36 37 /** Provided model cannot be loaded. */ 38 TFLInterpreterErrorCodeFailedToLoadModel, 39 40 /** Failed to create `TFLInterpreter`. */ 41 TFLInterpreterErrorCodeFailedToCreateInterpreter, 42 43 /** Failed to invoke `TFLInterpreter`. */ 44 TFLInterpreterErrorCodeFailedToInvoke, 45 46 /** Failed to retrieve a tensor. */ 47 TFLInterpreterErrorCodeFailedToGetTensor, 48 49 /** Invalid tensor. */ 50 TFLInterpreterErrorCodeInvalidTensor, 51 52 /** Failed to resize an input tensor. */ 53 TFLInterpreterErrorCodeFailedToResizeInputTensor, 54 55 /** Failed to copy data into an input tensor. */ 56 TFLInterpreterErrorCodeFailedToCopyDataToInputTensor, 57 58 /** Copying data into an output tensor not allowed. */ 59 TFLInterpreterErrorCodeCopyDataToOutputTensorNotAllowed, 60 61 /** Failed to get data from a tensor. */ 62 TFLInterpreterErrorCodeFailedToGetDataFromTensor, 63 64 /** Failed to allocate memory for tensors. */ 65 TFLInterpreterErrorCodeFailedToAllocateTensors, 66 67 /** Operation not allowed without allocating memory for tensors first. */ 68 TFLInterpreterErrorCodeAllocateTensorsRequired, 69 70 /** Operation not allowed without invoking the interpreter first. */ 71 TFLInterpreterErrorCodeInvokeInterpreterRequired, 72 }; 73 74 /** 75 * A TensorFlow Lite model interpreter. 76 * 77 * Note: Interpreter instances are *not* thread-safe. 78 */ 79 @interface TFLInterpreter : NSObject 80 81 /** The total number of input tensors. 0 if the interpreter creation failed. */ 82 @property(nonatomic, readonly) NSUInteger inputTensorCount; 83 84 /** The total number of output tensors. 0 if the interpreter creation failed. */ 85 @property(nonatomic, readonly) NSUInteger outputTensorCount; 86 87 /** Unavailable. */ 88 - (instancetype)init NS_UNAVAILABLE; 89 90 /** 91 * Initializes a new TensorFlow Lite interpreter instance with the given model file path and the 92 * default interpreter options. 93 * 94 * @param modelPath An absolute path to a TensorFlow Lite model file stored locally on the device. 95 * @param error An optional error parameter populated when there is an error in initializing the 96 * interpreter. 97 * 98 * @return A new instance of `TFLInterpreter` with the given model and the default interpreter 99 * options. `nil` if there is an error in initializing the interpreter. 100 */ 101 - (nullable instancetype)initWithModelPath:(NSString *)modelPath error:(NSError **)error; 102 103 /** 104 * Initializes a new TensorFlow Lite interpreter instance with the given model file path and 105 * options. 106 * 107 * @param modelPath An absolute path to a TensorFlow Lite model file stored locally on the device. 108 * @param options Options to use for configuring the TensorFlow Lite interpreter. 109 * @param error An optional error parameter populated when there is an error in initializing the 110 * interpreter. 111 * 112 * @return A new instance of `TFLInterpreter` with the given model and options. `nil` if there is an 113 * error in initializing the interpreter. 114 */ 115 - (nullable instancetype)initWithModelPath:(NSString *)modelPath 116 options:(TFLInterpreterOptions *)options 117 error:(NSError **)error; 118 119 /** 120 * Initializes a new TensorFlow Lite interpreter instance with the given model file path, options 121 * and delegates. 122 * 123 * @param modelPath An absolute path to a TensorFlow Lite model file stored locally on the device. 124 * @param options Options to use for configuring the TensorFlow Lite interpreter. 125 * @param delegates Delegates to use with the TensorFlow Lite interpreter. When the array is empty, 126 * no delegate will be applied. 127 * @param error An optional error parameter populated when there is an error in initializing the 128 * interpreter. 129 * 130 * @return A new instance of `TFLInterpreter` with the given model and options. `nil` if there is an 131 * error in initializing the interpreter. 132 */ 133 - (nullable instancetype)initWithModelPath:(NSString *)modelPath 134 options:(TFLInterpreterOptions *)options 135 delegates:(NSArray<TFLDelegate *> *)delegates 136 error:(NSError **)error NS_DESIGNATED_INITIALIZER; 137 138 /** 139 * Invokes the interpreter to run inference. 140 * 141 * @param error An optional error parameter populated when there is an error in invoking the 142 * interpreter. 143 * 144 * @return Whether the invocation is successful. Returns NO if an error occurred. 145 */ 146 - (BOOL)invokeWithError:(NSError **)error; 147 148 /** 149 * Returns the input tensor at the given index. 150 * 151 * @param index The index of an input tensor. 152 * @param error An optional error parameter populated when there is an error in looking up the input 153 * tensor. 154 * 155 * @return The input tensor at the given index. `nil` if there is an error. See the `TFLTensor` 156 * class documentation for more details on the life expectancy between the returned tensor and 157 * this interpreter. 158 */ 159 - (nullable TFLTensor *)inputTensorAtIndex:(NSUInteger)index error:(NSError **)error; 160 161 /** 162 * Returns the output tensor at the given index. 163 * 164 * @param index The index of an output tensor. 165 * @param error An optional error parameter populated when there is an error in looking up the 166 * output tensor. 167 * 168 * @return The output tensor at the given index. `nil` if there is an error. See the `TFLTensor` 169 * class documentation for more details on the life expectancy between the returned tensor and 170 * this interpreter. 171 */ 172 - (nullable TFLTensor *)outputTensorAtIndex:(NSUInteger)index error:(NSError **)error; 173 174 /** 175 * Resizes the input tensor at the given index to the specified shape (an array of positive unsigned 176 * integers). 177 * 178 * @param index The index of an input tensor. 179 * @param shape Shape that the given input tensor should be resized to. It should be an array of 180 * positive unsigned integer(s) containing the size of each dimension. 181 * @param error An optional error parameter populated when there is an error in resizing the input 182 * tensor. 183 * 184 * @return Whether the input tensor was resized successfully. Returns NO if an error occurred. 185 */ 186 - (BOOL)resizeInputTensorAtIndex:(NSUInteger)index 187 toShape:(NSArray<NSNumber *> *)shape 188 error:(NSError **)error; 189 190 /** 191 * Allocates memory for tensors. 192 * 193 * @param error An optional error parameter populated when there is an error in allocating memory. 194 * 195 * @return Whether memory allocation is successful. Returns NO if an error occurred. 196 */ 197 - (BOOL)allocateTensorsWithError:(NSError **)error; 198 199 @end 200 201 NS_ASSUME_NONNULL_END 202