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 @interface TFLInterpreter : NSObject 78 79 /** The total number of input tensors. 0 if the interpreter creation failed. */ 80 @property(nonatomic, readonly) NSUInteger inputTensorCount; 81 82 /** The total number of output tensors. 0 if the interpreter creation failed. */ 83 @property(nonatomic, readonly) NSUInteger outputTensorCount; 84 85 /** Unavailable. */ 86 - (instancetype)init NS_UNAVAILABLE; 87 88 /** 89 * Initializes a new TensorFlow Lite interpreter instance with the given model file path and the 90 * default interpreter options. 91 * 92 * @param modelPath An absolute path to a TensorFlow Lite model file stored locally on the device. 93 * @param error An optional error parameter populated when there is an error in initializing the 94 * interpreter. 95 * 96 * @return A new instance of `TFLInterpreter` with the given model and the default interpreter 97 * options. `nil` if there is an error in initializing the interpreter. 98 */ 99 - (nullable instancetype)initWithModelPath:(NSString *)modelPath error:(NSError **)error; 100 101 /** 102 * Initializes a new TensorFlow Lite interpreter instance with the given model file path and 103 * options. 104 * 105 * @param modelPath An absolute path to a TensorFlow Lite model file stored locally on the device. 106 * @param options Options to use for configuring the TensorFlow Lite interpreter. 107 * @param error An optional error parameter populated when there is an error in initializing the 108 * interpreter. 109 * 110 * @return A new instance of `TFLInterpreter` with the given model and options. `nil` if there is an 111 * error in initializing the interpreter. 112 */ 113 - (nullable instancetype)initWithModelPath:(NSString *)modelPath 114 options:(TFLInterpreterOptions *)options 115 error:(NSError **)error; 116 117 /** 118 * Initializes a new TensorFlow Lite interpreter instance with the given model file path, options 119 * and delegates. 120 * 121 * @param modelPath An absolute path to a TensorFlow Lite model file stored locally on the device. 122 * @param options Options to use for configuring the TensorFlow Lite interpreter. 123 * @param delegates Delegates to use with the TensorFlow Lite interpreter. When the array is empty, 124 * no delegate will be applied. 125 * @param error An optional error parameter populated when there is an error in initializing the 126 * interpreter. 127 * 128 * @return A new instance of `TFLInterpreter` with the given model and options. `nil` if there is an 129 * error in initializing the interpreter. 130 */ 131 - (nullable instancetype)initWithModelPath:(NSString *)modelPath 132 options:(TFLInterpreterOptions *)options 133 delegates:(NSArray<TFLDelegate *> *)delegates 134 error:(NSError **)error NS_DESIGNATED_INITIALIZER; 135 136 /** 137 * Invokes the interpreter to run inference. 138 * 139 * @param error An optional error parameter populated when there is an error in invoking the 140 * interpreter. 141 * 142 * @return Whether the invocation is successful. Returns NO if an error occurred. 143 */ 144 - (BOOL)invokeWithError:(NSError **)error; 145 146 /** 147 * Returns the input tensor at the given index. 148 * 149 * @param index The index of an input tensor. 150 * @param error An optional error parameter populated when there is an error in looking up the input 151 * tensor. 152 * 153 * @return The input tensor at the given index. `nil` if there is an error. See the `TFLTensor` 154 * class documentation for more details on the life expectancy between the returned tensor and 155 * this interpreter. 156 */ 157 - (nullable TFLTensor *)inputTensorAtIndex:(NSUInteger)index error:(NSError **)error; 158 159 /** 160 * Returns the output tensor at the given index. 161 * 162 * @param index The index of an output tensor. 163 * @param error An optional error parameter populated when there is an error in looking up the 164 * output tensor. 165 * 166 * @return The output tensor at the given index. `nil` if there is an error. See the `TFLTensor` 167 * class documentation for more details on the life expectancy between the returned tensor and 168 * this interpreter. 169 */ 170 - (nullable TFLTensor *)outputTensorAtIndex:(NSUInteger)index error:(NSError **)error; 171 172 /** 173 * Resizes the input tensor at the given index to the specified shape (an array of positive unsigned 174 * integers). 175 * 176 * @param index The index of an input tensor. 177 * @param shape Shape that the given input tensor should be resized to. It should be an array of 178 * positive unsigned integer(s) containing the size of each dimension. 179 * @param error An optional error parameter populated when there is an error in resizing the input 180 * tensor. 181 * 182 * @return Whether the input tensor was resized successfully. Returns NO if an error occurred. 183 */ 184 - (BOOL)resizeInputTensorAtIndex:(NSUInteger)index 185 toShape:(NSArray<NSNumber *> *)shape 186 error:(NSError **)error; 187 188 /** 189 * Allocates memory for tensors. 190 * 191 * @param error An optional error parameter populated when there is an error in allocating memory. 192 * 193 * @return Whether memory allocation is successful. Returns NO if an error occurred. 194 */ 195 - (BOOL)allocateTensorsWithError:(NSError **)error; 196 197 @end 198 199 NS_ASSUME_NONNULL_END 200