Struct MLModel

#[repr(C)]
pub struct MLModel { /* private fields */ }

Available on crate feature MLModel only.

MLModel

Construct a model and evaluate on a specific set of input features. Inputs and outputs are accessed via the MLFeatureProvider protocol. Returns a model or nil if there is an error.

See also Apple’s documentation

Implementations

impl MLModel

pub unsafe fn modelDescription(&self) -> Retained<MLModelDescription>

Available on crate feature MLModelDescription only.

A model holds a description of its required inputs and expected outputs.

pub unsafe fn configuration(&self) -> Retained<MLModelConfiguration>

Available on crate feature MLModelConfiguration only.

The load-time parameters used to instantiate this MLModel object.

pub unsafe fn modelWithContentsOfURL_error( url: &NSURL, ) -> Result<Retained<Self>, Retained<NSError>>

Construct a model with a default MLModelConfiguration object

pub unsafe fn modelWithContentsOfURL_configuration_error( url: &NSURL, configuration: &MLModelConfiguration, ) -> Result<Retained<Self>, Retained<NSError>>

Available on crate feature MLModelConfiguration only.

Construct a model given the location of its on-disk representation. Returns nil on error.

pub unsafe fn loadContentsOfURL_configuration_completionHandler( url: &NSURL, configuration: &MLModelConfiguration, handler: &DynBlock<dyn Fn(*mut MLModel, *mut NSError)>, )

Available on crate features MLModelConfiguration and block2 only.

Construct a model asynchronously given the location of its on-disk representation and configuration.

Model loading may take time when the model content is not immediately available (e.g. encrypted model). Use this factory method especially when the caller is on the main thread.

Parameter url: the location of its on-disk representation (.mlmodelc directory).

Parameter configuration: The model configuration

Parameter handler: When the model load completes successfully or unsuccessfully, the completion handler is invoked with a valid MLModel instance or NSError object.

pub unsafe fn predictionFromFeatures_error( &self, input: &ProtocolObject<dyn MLFeatureProvider>, ) -> Result<Retained<ProtocolObject<dyn MLFeatureProvider>>, Retained<NSError>>

Available on crate feature MLFeatureProvider only.

Run a prediction on a model synchronously.

This is a convenience overload method of prediction(from:options:) that uses the default prediction options.

• Parameters
• input: The input features to make a prediction from.
• error: The output parameter to be filled with error information on failure.
• Returns: The output features from the prediction.

pub unsafe fn predictionFromFeatures_options_error( &self, input: &ProtocolObject<dyn MLFeatureProvider>, options: &MLPredictionOptions, ) -> Result<Retained<ProtocolObject<dyn MLFeatureProvider>>, Retained<NSError>>

Available on crate features MLFeatureProvider and MLPredictionOptions only.

Run a prediction on a model synchronously

• Parameters
• input: The input features to make a prediction from.
• options: Prediction options to modify how the prediction is run.
• error: The output parameter to be filled with error information on failure.
• Returns: The output features from the prediction.

pub unsafe fn predictionFromFeatures_completionHandler( &self, input: &ProtocolObject<dyn MLFeatureProvider>, completion_handler: &DynBlock<dyn Fn(*mut ProtocolObject<dyn MLFeatureProvider>, *mut NSError)>, )

Available on crate features MLFeatureProvider and block2 only.

Run a prediction on a model asynchronously.

This is a convenience overload method of prediction(from:options:) async that uses the default prediction options.

• Parameters
• input: The input features to make a prediction from.
• completionHandler: A block that will be invoked once the prediction has completed successfully or unsuccessfully. On success, it is invoked with a valid model output. On failure, it is invoked with a nil output and NSError

pub unsafe fn predictionFromFeatures_options_completionHandler( &self, input: &ProtocolObject<dyn MLFeatureProvider>, options: &MLPredictionOptions, completion_handler: &DynBlock<dyn Fn(*mut ProtocolObject<dyn MLFeatureProvider>, *mut NSError)>, )

Available on crate features MLFeatureProvider and MLPredictionOptions and block2 only.

Run a prediction on a model asynchronously.

• Parameters
• input: The input features to make a prediction from.
• options: Prediction options to modify how the prediction is run.
• completionHandler: A block that will be invoked once the prediction has completed successfully or unsuccessfully. On success, it is invoked with a valid model output. On failure, it is invoked with a nil output and NSError

pub unsafe fn predictionsFromBatch_error( &self, input_batch: &ProtocolObject<dyn MLBatchProvider>, ) -> Result<Retained<ProtocolObject<dyn MLBatchProvider>>, Retained<NSError>>

Available on crate feature MLBatchProvider only.

Batch prediction without explicit options

pub unsafe fn predictionsFromBatch_options_error( &self, input_batch: &ProtocolObject<dyn MLBatchProvider>, options: &MLPredictionOptions, ) -> Result<Retained<ProtocolObject<dyn MLBatchProvider>>, Retained<NSError>>

Available on crate features MLBatchProvider and MLPredictionOptions only.

Batch prediction with explicit options

pub unsafe fn parameterValueForKey_error( &self, key: &MLParameterKey, ) -> Result<Retained<AnyObject>, Retained<NSError>>

Available on crate features MLKey and MLParameterKey only.

Provides value for the given parameter. Returns nil on error.

pub unsafe fn loadModelAsset_configuration_completionHandler( asset: &MLModelAsset, configuration: &MLModelConfiguration, handler: &DynBlock<dyn Fn(*mut MLModel, *mut NSError)>, )

Available on crate features MLModelAsset and MLModelConfiguration and block2 only.

Construct a model asynchronously from a compiled model asset.

Parameter asset: Compiled model asset derived from in-memory or on-disk Core ML model

Parameter configuration: Model configuration that hold options for loading a model

Parameter handler: When the model load completes successfully or unsuccessfully, the completion handler is invoked with a valid MLModel instance or NSError object.

impl MLModel

Methods declared on superclass NSObject.

pub unsafe fn init(this: Allocated<Self>) -> Retained<Self>

pub unsafe fn new() -> Retained<Self>

impl MLModel

MLComputeDevice. MLModel (MLComputeDevice)

Class with utilties for getting the available compute devices.

pub unsafe fn availableComputeDevices() -> Retained<NSArray<ProtocolObject<dyn MLComputeDeviceProtocol>>>

Available on crate features MLModel_MLComputeDevice and MLComputeDeviceProtocol only.

The list of available compute devices for CoreML.

Use the method to get the list of compute devices that MLModel’s prediction can use.

Some compute devices on the hardware are exclusive to the domain ML frameworks such as Vision and SoundAnalysis and not available to CoreML. See also MLComputeDevice.allComputeDevices.

impl MLModel

MLModelCompilation. MLModel (MLModelCompilation)

Class with utilties for performing .mlmodel compilation

pub unsafe fn compileModelAtURL_error( model_url: &NSURL, ) -> Result<Retained<NSURL>, Retained<NSError>>

👎Deprecated: Use the asynchronous interface compileModelAtURL:completionHandler:error: instead.

Available on crate feature MLModel_MLModelCompilation only.

Compile a .mlmodel for this device

Parameter modelURL: URL file path to .mlmodel file you wish to compile

Parameter error: Any errors are surfaced here

Returns: a URL to the compiled .mlmodelc directory if successful The model is compiled to a temporary location on disk You must move the compiled model to a permanent location if you wish to keep it

The returned model can be loaded using:

 [MLModel modelWithContentsOfURL:error:]

pub unsafe fn compileModelAtURL_completionHandler( model_url: &NSURL, handler: &DynBlock<dyn Fn(*mut NSURL, *mut NSError)>, )

Available on crate features MLModel_MLModelCompilation and block2 only.

Compile a .mlmodel or .mlpackage for this device. Perform the compilation asynchronously.

Parameter modelURL: URL file path to .mlmodel file you wish to compile

Parameter handler: When the model compilation completes successfully the completion handler is invoked with a valid URL to the compiled .mlmodelc directory. On failure, signified by nil compiledModelURL, the NSError object is populated.

The model is compiled to a temporary location in the file system. You must move the compiled model to a permanent location if you wish to keep it. Then the model can be loaded using the returned URL:

 [MLModel modelWithContentsOfURL:error:]

impl MLModel

MLState.

pub unsafe fn newState(&self) -> Retained<MLState>

Available on crate features MLModel_MLState and MLState only.

Creates a new state object.

Core ML framework will allocate the state buffers declared in the model.

The allocated state buffers are initialized to zeros. To initialize with different values, use .withMultiArray(for:) to get the mutable MLMultiArray-view to the state buffer.

It returns an empty state when the model is stateless. One can use the empty state with stateful prediction functions such as prediction(from:using:) and those predictions will be stateless. This simplifies the call site which may or may not use a stateful model.

// Create state that contains two state buffers: s1 and s2.
// Then, initialize s1 to 1.0 and s2 to 2.0.
let state = model.newState()
state.withMultiArray(for: "s1") { stateMultiArray in
stateMultiArray[0] = 1.0
}
state.withMultiArray(for: "s2") { stateMultiArray in
stateMultiArray[0] = 2.0
}

pub unsafe fn predictionFromFeatures_usingState_error( &self, input_features: &ProtocolObject<dyn MLFeatureProvider>, state: &MLState, ) -> Result<Retained<ProtocolObject<dyn MLFeatureProvider>>, Retained<NSError>>

Available on crate features MLModel_MLState and MLFeatureProvider and MLState only.

Run a stateful prediction synchronously.

Use this method to run predictions on a stateful model.

let state = model.newState()
let prediction = try model.prediction(from: inputFeatures, using: state)

• Parameters:
• inputFeatures: The input features as declared in the model description.
• state: The state object created by newState() method.
• error: The output parameter to receive an error information on failure.

pub unsafe fn predictionFromFeatures_usingState_options_error( &self, input_features: &ProtocolObject<dyn MLFeatureProvider>, state: &MLState, options: &MLPredictionOptions, ) -> Result<Retained<ProtocolObject<dyn MLFeatureProvider>>, Retained<NSError>>

Available on crate features MLModel_MLState and MLFeatureProvider and MLPredictionOptions and MLState only.

Run a stateful prediction synchronously with options.

Use this method to run predictions on a stateful model.

let state = model.newState()
let prediction = try model.prediction(from: inputFeatures, using: state, options: predictionOptions)

• Parameters:
• inputFeatures: The input features as declared in the model description.
• state: The state object created by newState() method.
• options: The prediction options.
• error: The output parameter to receive an error information on failure.

pub unsafe fn predictionFromFeatures_usingState_options_completionHandler( &self, input_features: &ProtocolObject<dyn MLFeatureProvider>, state: &MLState, options: &MLPredictionOptions, completion_handler: &DynBlock<dyn Fn(*mut ProtocolObject<dyn MLFeatureProvider>, *mut NSError)>, )

Available on crate features MLModel_MLState and MLFeatureProvider and MLPredictionOptions and MLState and block2 only.

Run a stateful prediction asynchronously.

Use this method to run predictions on a stateful model.

Do not request a prediction while another prediction that shares the same state is in-flight, otherwise the behavior is undefined.

let state = model.newState()
let prediction = try await model.prediction(from: inputFeatures, using: state)

• Parameters
• input: The input features to make a prediction from.
• state: The state object created by newState() method.
• options: Prediction options to modify how the prediction is run.
• completionHandler: A block that will be invoked once the prediction has completed successfully or unsuccessfully. On success, it is invoked with a valid model output. On failure, it is invoked with a nil output and NSError

Methods from Deref<Target = NSObject>

pub fn doesNotRecognizeSelector(&self, sel: Sel) -> !

Handle messages the object doesn’t recognize.

See Apple’s documentation for details.

Methods from Deref<Target = AnyObject>

pub fn class(&self) -> &'static AnyClass

Dynamically find the class of this object.

Panics

May panic if the object is invalid (which may be the case for objects returned from unavailable init/new methods).

Example

Check that an instance of NSObject has the precise class NSObject.

use objc2::ClassType;
use objc2::runtime::NSObject;

let obj = NSObject::new();
assert_eq!(obj.class(), NSObject::class());

pub unsafe fn get_ivar<T>(&self, name: &str) -> &T

where T: Encode,

👎Deprecated: this is difficult to use correctly, use Ivar::load instead.

Use Ivar::load instead.

Safety

The object must have an instance variable with the given name, and it must be of type T.

See Ivar::load_ptr for details surrounding this.

pub fn downcast_ref<T>(&self) -> Option<&T>

where T: DowncastTarget,

Attempt to downcast the object to a class of type T.

This is the reference-variant. Use Retained::downcast if you want to convert a retained object to another type.

Mutable classes

Some classes have immutable and mutable variants, such as NSString and NSMutableString.

When some Objective-C API signature says it gives you an immutable class, it generally expects you to not mutate that, even though it may technically be mutable “under the hood”.

So using this method to convert a NSString to a NSMutableString, while not unsound, is generally frowned upon unless you created the string yourself, or the API explicitly documents the string to be mutable.

See Apple’s documentation on mutability and on isKindOfClass: for more details.

Generic classes

Objective-C generics are called “lightweight generics”, and that’s because they aren’t exposed in the runtime. This makes it impossible to safely downcast to generic collections, so this is disallowed by this method.

You can, however, safely downcast to generic collections where all the type-parameters are AnyObject.

Panics

This works internally by calling isKindOfClass:. That means that the object must have the instance method of that name, and an exception will be thrown (if CoreFoundation is linked) or the process will abort if that is not the case. In the vast majority of cases, you don’t need to worry about this, since both root objects NSObject and NSProxy implement this method.

Examples

Cast an NSString back and forth from NSObject.

use objc2::rc::Retained;
use objc2_foundation::{NSObject, NSString};

let obj: Retained<NSObject> = NSString::new().into_super();
let string = obj.downcast_ref::<NSString>().unwrap();
// Or with `downcast`, if we do not need the object afterwards
let string = obj.downcast::<NSString>().unwrap();

Try (and fail) to cast an NSObject to an NSString.

use objc2_foundation::{NSObject, NSString};

let obj = NSObject::new();
assert!(obj.downcast_ref::<NSString>().is_none());

Try to cast to an array of strings.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);
// This is invalid and doesn't type check.
let arr = arr.downcast_ref::<NSArray<NSString>>();

This fails to compile, since it would require enumerating over the array to ensure that each element is of the desired type, which is a performance pitfall.

Downcast when processing each element instead.

use objc2_foundation::{NSArray, NSObject, NSString};

let arr = NSArray::from_retained_slice(&[NSObject::new()]);

for elem in arr {
    if let Some(data) = elem.downcast_ref::<NSString>() {
        // handle `data`
    }
}

Trait Implementations

impl AsRef<AnyObject> for MLModel

fn as_ref(&self) -> &AnyObject

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<MLModel> for MLModel

fn as_ref(&self) -> &Self

Converts this type into a shared reference of the (usually inferred) input type.

impl AsRef<NSObject> for MLModel

fn as_ref(&self) -> &NSObject

Converts this type into a shared reference of the (usually inferred) input type.

impl Borrow<AnyObject> for MLModel

fn borrow(&self) -> &AnyObject

Immutably borrows from an owned value.

impl Borrow<NSObject> for MLModel

fn borrow(&self) -> &NSObject

Immutably borrows from an owned value.

impl ClassType for MLModel

const NAME: &'static str = "MLModel"

The name of the Objective-C class that this type represents.

type Super = NSObject

The superclass of this class.

type ThreadKind = <<MLModel as ClassType>::Super as ClassType>::ThreadKind

Whether the type can be used from any thread, or from only the main thread.

fn class() -> &'static AnyClass

Get a reference to the Objective-C class that this type represents.

fn as_super(&self) -> &Self::Super

Get an immutable reference to the superclass.

impl Debug for MLModel

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Deref for MLModel

type Target = NSObject

The resulting type after dereferencing.

fn deref(&self) -> &Self::Target

Dereferences the value.

impl Hash for MLModel

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Message for MLModel

fn retain(&self) -> Retained<Self>

where Self: Sized,

Increment the reference count of the receiver.

impl NSObjectProtocol for MLModel

fn isEqual(&self, other: Option<&AnyObject>) -> bool

where Self: Sized + Message,

Check whether the object is equal to an arbitrary other object.

fn hash(&self) -> usize

where Self: Sized + Message,

An integer that can be used as a table address in a hash table structure.

fn isKindOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of the class, or one of its subclasses.

fn is_kind_of<T>(&self) -> bool

where T: ClassType, Self: Sized + Message,

👎Deprecated: use isKindOfClass directly, or cast your objects with AnyObject::downcast_ref

Check if the object is an instance of the class type, or one of its subclasses.

fn isMemberOfClass(&self, cls: &AnyClass) -> bool

where Self: Sized + Message,

Check if the object is an instance of a specific class, without checking subclasses.

fn respondsToSelector(&self, aSelector: Sel) -> bool

where Self: Sized + Message,

Check whether the object implements or inherits a method with the given selector.

fn conformsToProtocol(&self, aProtocol: &AnyProtocol) -> bool

where Self: Sized + Message,

Check whether the object conforms to a given protocol.

fn description(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object.

fn debugDescription(&self) -> Retained<NSObject>

where Self: Sized + Message,

A textual representation of the object to use when debugging.

fn isProxy(&self) -> bool

where Self: Sized + Message,

Check whether the receiver is a subclass of the NSProxy root class instead of the usual NSObject.

fn retainCount(&self) -> usize

where Self: Sized + Message,

The reference count of the object.

impl PartialEq for MLModel

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl RefEncode for MLModel

const ENCODING_REF: Encoding = <NSObject as ::objc2::RefEncode>::ENCODING_REF

The Objective-C type-encoding for a reference of this type.

impl DowncastTarget for MLModel

impl Eq for MLModel