TIOModel

@protocol TIOModel <NSObject>

An Obj-C wrapper around lower level, usually C++ model implementations. This is the primary API provided by the TensorIO framework.

A TIOModel is built from a bundle folder that contains the underlying model, a json description of the model’s input and output layers, and any additional assets required by the model, for example, output labels.

A conforming TIOModel begins by parsing a json description of the model’s input and output layers, producing a TIOLayerInterface for each layer. Each layer is fully described by a conforming TIOLayerDescription, which describes the data the layer expects or produces, for example, whether it is quantized, any transformations that should be applied to it, and the number of bytes the layer expects.

To perform inference with the underlying model, call runOn: with a conforming TIOData object. TIOData objects simply know how to copy bytes to and receive bytes from a model’s input and output layers. Internally, this method matches TIOData objects with their corresponding layers and ensures that bytes are copied to the right place. The runOn: method then returns a conforming TIOData object, which is the result of performing inference with the model. Objects that conform to the TIOData protocol include NSNumber, NSArray, NSData, NSDictionary, and TIOPixelBuffer, which wraps a CVPixelBuffer for computer vision models.

For more information about a model’s interface, refer to the TIOLayerInterface and TIOLayerDescription classes. For more information about the kinds of Objective-C data a TIOModel can work with, refer to the TIOData protocol and its conforming classes. For more information about the JSON file which describes a model, see TIOModelBundleJSONSchema.h

Note that, currently, only TensorFlow Lite (TFLite) models are supported.

@warning Models are not thread safe. Models may be used on separate threads, so that you can perform inference off the main thread, but you should not use the same model from multiple threads.

  • The TIOModelBundle object from which this model was instantiated.

    Declaration

    Objective-C

    @property (readonly, atomic) TIOModelBundle *_Nonnull bundle;

    Swift

    var bundle: TIOModelBundle { get }
  • Options associated with this model.

    Declaration

    Objective-C

    @property (readonly, atomic) TIOModelOptions *_Nonnull options;

    Swift

    var options: TIOModelOptions { get }
  • A string uniquely identifying this model, taken from the model bundle.

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *_Nonnull identifier;

    Swift

    var identifier: String { get }
  • Human readable name of the model, taken from the model bundle.

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *_Nonnull name;

    Swift

    var name: String { get }
  • Additional information about the model, taken from the model bundle.

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *_Nonnull details;

    Swift

    var details: String { get }
  • The model’s authors, taken from the model bundle.

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *_Nonnull author;

    Swift

    var author: String { get }
  • The model’s license, taken from the model bundle.

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *_Nonnull license;

    Swift

    var license: String { get }
  • A boolean value indicating if this is a placeholder bundle.

    A placeholder bundle has no underlying model and instantiates a TIOModel that does nothing. Placeholders bundles are used to collect labeled data for models that haven’t been trained yet.

    Declaration

    Objective-C

    @property (readonly, atomic) BOOL placeholder;

    Swift

    var placeholder: Bool { get }
  • A boolean value indicating if the model is quantized or not.

    Quantized models have 8 bit uint8_t interfaces while unquantized modesl have 32 bit, float_t interfaces.

    Declaration

    Objective-C

    @property (readonly, atomic) BOOL quantized;

    Swift

    var quantized: Bool { get }
  • A string indicating the kind of model this is, e.g. image.classification.imagenet

    Declaration

    Objective-C

    @property (readonly, atomic) NSString *_Nonnull type;

    Swift

    var type: String { get }
  • A boolean value indicating whether the model has been loaded or not. Conforming classes may want to wrap the underlying models such that they can be aggressively loaded and unloaded from memory, as some models contain hundreds of megabytes of paramters.

    Declaration

    Objective-C

    @property (readonly, atomic) BOOL loaded;

    Swift

    var loaded: Bool { get }
  • Returns descriptions of the model’s inputs indexed to the order they appear in model.json.

    Declaration

    Objective-C

    @property (readonly, atomic) NSArray<TIOLayerInterface *> *_Nonnull inputs;

    Swift

    var inputs: [TIOLayerInterface] { get }
  • Returns descriptions of the model’s outputs indexed to the order they appear in model.json.

    Declaration

    Objective-C

    @property (readonly, atomic) NSArray<TIOLayerInterface *> *_Nonnull outputs;

    Swift

    var outputs: [TIOLayerInterface] { get }
  • The designated initializer for conforming classes.

    You should not need to call this method directly. Instead, acquire an instance of a TIOModelBundle associated with this model by way of the model’s identifier. Then the TIOModelBundle class calls this initWithBundle: factory initialization method, which conforming classes may override to support custom initialization.

    Declaration

    Objective-C

    - (nullable instancetype)initWithBundle:(nonnull TIOModelBundle *)bundle;

    Swift

    init?(bundle: TIOModelBundle)

    Parameters

    bundle

    TIOModelBundle containing information about the model and its path

    Return Value

    instancetype An instance of the conforming class, may be nil.

  • Convenience method for initializing a model directly from bundle at some path

    Declaration

    Objective-C

    + (nullable instancetype)modelWithBundleAtPath:(nonnull NSString *)path;

    Swift

    static func withBundleAtPath(_ path: String) -> Self?

    Parameters

    path

    The path to the model bundle folder

    Return Value

    instancetype An instance of the model, or nil.

  • Loads a model into memory.

    A model should load itself prior to running on any input, but consumers of the model may want more control over when a model is loaded in order to avoid placing parameters into memory before they are needed.

    Conforming classes should override this method to perform custom loading and set loaded=YES.

    Declaration

    Objective-C

    - (BOOL)load:(NSError *_Nullable *_Nullable)error;

    Swift

    func load() throws

    Parameters

    error

    Set to one of the errors in TIOTFLiteErrors.h for TFLiteModels, or one of your own error.

    Return Value

    BOOL YES if the model is successfully loaded, NO otherwise.

  • Unloads a model from memory

    A model will unload its resources automatically when it is deallocated, but the unload function may do this as well in order to provide finer grained control to consumers.

    Conforming classes should override this method to perform custom unloading and set loaded=NO.

    Declaration

    Objective-C

    - (void)unload;

    Swift

    func unload()
  • Performs inference on the provided input and returns the results. The primary interface to a conforming class.

    Declaration

    Objective-C

    - (nonnull id<TIOData>)runOn:(nonnull id<TIOData>)input;

    Parameters

    input

    Any class conforming to TIOData that you want to run inference on

    Return Value

    TIOData The results of performing inference

  • Returns a description of the model’s input at a given index

    Model inputs and outputs are organized by index and name. In the model.json file that describes the interface to a model, an array of named inputs includes information such as the type of data the input expects, its volume, and any transformations that will be applied to it.

    This information is encapsulated in a TIOLayerDescription, which is used to prepare inputs provided to the runOn: method prior to performing inference. See TIOModelBundleJSONSchema.h for more information about this json file.

    Declaration

    Objective-C

    - (nonnull id<TIOLayerDescription>)descriptionOfInputAtIndex:(NSUInteger)index;
  • Returns a description of the model’s input for a given name

    Model inputs and outputs are organized by index and name. In the model.json file that describes the interface to a model, an array of named inputs includes information such as the type of data the input expects, its volume, and any transformations that will be applied to it.

    This information is encapsulated in a TIOLayerDescription, which is used to prepare inputs provided to the runOn: method prior to performing inference. See TIOModelBundleJSONSchema.h for more information about this json file.

    Declaration

    Objective-C

    - (nonnull id<TIOLayerDescription>)descriptionOfInputWithName:
        (nonnull NSString *)name;
  • Returns a description of the model’s output at a given index

    Model inputs and outputs are organized by index and name. In the model.json file that describes the interface to a model, an array of named inputs includes information such as the type of data the input expects, its volume, and any transformations that will be applied to it.

    This information is encapsulated in a TIOLayerDescription, which is used to prepare the results of performing inference and returned from the runOn: method. See TIOModelBundleJSONSchema.h for more information about this json file.

    Declaration

    Objective-C

    - (nonnull id<TIOLayerDescription>)descriptionOfOutputAtIndex:(NSUInteger)index;
  • Returns a description of the model’s output for a given name

    Model inputs and outputs are organized by index and name. In the model.json file that describes the interface to a model, an array of named inputs includes information such as the type of data the input expects, its volume, and any transformations that will be applied to it.

    This information is encapsulated in a TIOLayerDescription, which is used to prepare the results of performing inference and returned from the runOn: method. See TIOModelBundleJSONSchema.h for more information about this json file.

    Declaration

    Objective-C

    - (nonnull id<TIOLayerDescription>)descriptionOfOutputWithName:
        (nonnull NSString *)name;