Introduction to CoreML

PDF for offline use
Related Samples:
Related Links:
Related Videos:

Let us know how you feel about this

Translation Quality


0/250

last updated: 2016-08

Machine learning for mobile apps on iOS 11

CoreML brings machine learning to iOS – apps can take advantage of trained machine learning models to perform all sorts of tasks, from problem solving to image recognition.

This introduction covers the following:

Getting Started with CoreML

These steps describe how to add CoreML to an iOS project. Refer to the Mars Habitat Pricer sample for a practical example.

Mars Habitat Price Predictor sample screenshot

1. Add the model to the project

Add a compiled model (a directory with the .modelc extension) to the Resources directory of the project. The directory's contents should all have a build action of BundleResource:

The Resources folder should contain the compiled model

The samples use models compiled in Xcode 9 or manually using the following terminal command:

xcrun coremlcompiler compile {model.mlmodel} {outputFolder}
ℹ️

.model files must be compiled to .modelc before they can used by CoreML

2. Load the model

Before using a model, load it using the MLModel.FromUrl static method:

var assetPath = NSBundle.MainBundle.GetUrlForResource("NameOfModel", "mlmodelc");
model = MLModel.FromUrl(assetPath, out NSError error1);

3. Set the parameters

Model parameters are passed in and out using a container class that implements IMLFeatureProvider.

Feature provider classes behave like a dictionary of string and MLFeatureValues, where each feature value could be a simple string or number, an array or data, or a pixel buffer containing an image.

Code for a single-value feature provider is shown below:

public class MyInput : NSObject, IMLFeatureProvider
{
  public double MyParam { get; set; }
  public NSSet<NSString> FeatureNames => new NSSet<NSString>(new NSString("myParam"));
  public MLFeatureValue GetFeatureValue(string featureName)
  {
    if (featureName == "myParam")
      return MLFeatureValue.FromDouble(MyParam);
    return MLFeatureValue.FromDouble(0); // default value
  }

Using classes like this, input parameters can be provided in a way that is understood by CoreML. The names of the features (such as myParam in the code example) must match what the model expects.

4. Run the model

Using the model requires that the feature provider to be instantiated and parameters set, then that the GetPrediction method be called:

var input = new MyInput {MyParam = 13};
var outFeatures = model.GetPrediction(inputFeatures, out NSError error2);

5. Extract the results

The prediction result outFeatures is also an instance of IMLFeatureProvider; output values can be accessed using GetFeatureValue with the name of each output parameter (such as theResult), as in this example:

var result = outFeatures.GetFeatureValue("theResult").DoubleValue; // eg. 6227020800

Using CoreML with the Vision Framework

CoreML can also be used in conjunction with the Vision framework to perform operations on image, such as shape recognition, object identification, and other tasks.

The steps below describe how CoreML and Vision are used together in the CoreMLVision sample. The sample combines the rectangles recognition from the Vision framework with the MNINSTClassifier CoreML model to identify a handwritten digit in a photograph.

Image recognition of number 3 Image recognition of number 5

1. Create a Vision CoreML model

The CoreML model MNISTClassifier is loaded and then wrapped in a VNCoreMLModel which makes the model available for Vision tasks. This code also creates two Vision requests: first for finding rectangles in an image, and then for processing a rectangle with the CoreML model:

// Load the ML model
var assetPath = NSBundle.MainBundle.GetUrlForResource("MNISTClassifier", "mlmodelc");
var mlModel = MLModel.FromUrl(assetPath, out NSError mlErr);
var vModel = VNCoreMLModel.FromMLModel(mlModel, out NSError vnErr);

// Initialize Vision requests
RectangleRequest = new VNDetectRectanglesRequest(HandleRectangles);
ClassificationRequest = new VNCoreMLRequest(vModel, HandleClassification);

The class still needs to implement the HandleRectangles and HandleClassification methods for the Vision requests, shown in steps 3 and 4 below.

2. Start the Vision processing

The following code starts processing the request. In the CoreMLVision sample, this code runs after the user has selected an image:

// Run the rectangle detector, which upon completion runs the ML classifier.
var handler = new VNImageRequestHandler(ciImage, uiImage.Orientation.ToCGImagePropertyOrientation(), new VNImageOptions());
DispatchQueue.DefaultGlobalQueue.DispatchAsync(()=>{
  handler.Perform(new VNRequest[] {RectangleRequest}, out NSError error);
});

This handler passes the ciImage to the Vision framework VNDetectRectanglesRequest that was created in step 1.

3. Handle the results of Vision processing

Once the rectangle detection is complete, it executes the HandleRectangles method, which crops the image to extract the first rectangle, converts the rectangle image to greyscale, and passes it to the CoreML model for classification.

The request parameter passed to this method contains the details of the Vision request, and using the GetResults<VNRectangleObservation>() method, it returns a list of rectangles found in the image. The first rectangle observations[0] is extracted and passed to the CoreML model:

void HandleRectangles(VNRequest request, NSError error) {
  var observations = request.GetResults<VNRectangleObservation>();
  // ... omitted error handling ...
  var detectedRectangle = observations[0]; // first rectangle
  // ... omitted cropping and greyscale conversion ...
  // Run the Core ML MNIST classifier -- results in handleClassification method
  var handler = new VNImageRequestHandler(correctedImage, new VNImageOptions());
  DispatchQueue.DefaultGlobalQueue.DispatchAsync(() => {
    handler.Perform(new VNRequest[] { ClassificationRequest }, out NSError err);
  });
}

The ClassificationRequest was initialized in step 1 to use the HandleClassification method defined in the next step.

4. Handle the CoreML

The request parameter passed to this method contains the details of the CoreML request, and using the GetResults<VNClassificationObservation>() method, it returns a list of possible results ordered by confidence (highest confidence first):

void HandleClassification(VNRequest request, NSError error){
  var observations = request.GetResults<VNClassificationObservation>();
  ... omitted error handling ...
  var best = observations[0]; // first/best classification result
  // render in UI
  DispatchQueue.MainQueue.DispatchAsync(()=>{
    ClassificationLabel.Text = $"Classification: {best.Identifier} Confidence: {best.Confidence * 100f:#.00}%";
  });
}

Samples

There are three CoreML samples to try:

  • The Mars Habitat Price Predictor sample has simple numeric inputs and outputs.

  • The Vision & CoreML sample accepts an image parameter, and uses the Vision framework to identify square regions in the image, which are passed to a CoreML model that recognizes single digits.

  • Finally, the CoreML Image Recognition sample uses CoreML to identify features in a photo. By default it uses the smaller SqueezeNet model (5MB), but it's been written so that you can download and incorporate the larger VGG16 model (553MB). For more information, see the sample's readme.

Xamarin Workbook

If it's not already installed, install the Xamarin Workbooks app first. The workbook file should download automatically, but if it doesn't, just click to start the workbook download manually.