Finegrain iOS SDK

Pre-built XCFramework for the Finegrain SDK which brings Finegrain's image editing models directly on-device — no cloud calls, no latency, and full privacy.

Important

This SDK is not ready for production use. Breaking changes may occur between minor versions.

Requirements

• iOS 18.0+
• Xcode 16.0+
• Tested on A16 Bionic and newer devices (optimized for Neural Engine)

Available Tools

• Object Eraser: Remove unwanted objects from images
• Shadow Generator: Generate natural shadows for any object

Set It In Action

Here is a sneak peek from the Finegrain iOS app: watch | try it

Getting Started

Setting up the Finegrain SDK involves the following steps:

1. Generate a model encryption key and send it to Finegrain (more on this below)
2. Receive your encrypted model.zip
3. Install the SDK and model, then start coding

Model Setup

Note

The Finegrain SDK builds upon Apple's Core ML encryption. We will issue you a unique model that functions solely with your specific Team ID.

Step 1: Generate Your Encryption Key

Since Apple's command-line tools do not currently support key generation, you must use the Xcode interface for this step. You will generate a Core ML encryption key tied to your Apple Developer Team ID.

Important

This key MUST be generated using the same Team ID you use to sign your app. If the IDs do not match, the model will not decrypt at runtime.

1. Download a sample Core ML model (any model works - we recommend Apple's MNIST Classifier)

Note

Why a sample model? You just need to generate an encryption key tied to your Team ID. The specific model doesn't matter - you won't actually use MNIST in your app.

2. Double-click the downloaded .mlmodel file to open it in Xcode

3. In the Utilities panel (right sidebar), click "Create Encryption Key"

   

4. Select your Team ID - This MUST match the Team ID you'll use to build and sign your app

5. Rename the generated key file

   • Xcode creates MNISTClassifier.mlmodelkey next to the model file
   • Rename it to finegrain.mlmodelkey

Note

What's in this file? It's an encryption key that Finegrain will use to encrypt your model package. Only apps signed with your Team ID can decrypt it.

6. Send the .mlmodelkey file to hello@finegrain.ai
   • Keep a copy for your records - we'll use this same key for future model updates

Step 2: Receive Your Encrypted Model

Once we receive your .mlmodelkey file, we'll encrypt the model specifically for your Team ID and send you a custom model.zip file.

Installation

Once you have your encrypted model.zip:

1. Download FinegrainCore.xcframework.zip from the latest release
2. Extract and add FinegrainCore.xcframework to your Xcode project
3. Select Embed & Sign in General -> Frameworks, Libraries and Embedded Content

4. Add your model.zip to Build Phases -> Copy Bundle Resources

Usage

import FinegrainCore

let modelsDirectory = URL.applicationSupportDirectory.appendingPathComponent("finegrain-models")
let loader = FG.PipelineLoader(bundledModelName: "model", modelsDirectory: modelsDirectory)

// Eraser: remove objects from an image using a mask
let eraserPipeline = try await loader.prepare(skill: .eraser)
let eraserResult = try await eraserPipeline.generate(inputImage: image, maskImage: mask)

// Shadow: generate a shadow for an RGBA cutout, i.e., from a pre-segmented object
let shadowPipeline = try await loader.prepare(skill: .shadow)
let shadowResult = try await shadowPipeline.generate(
    cutoutImage: cutoutImage,  // RGBA image with transparency
    backgroundColor: (r: 255, g: 255, b: 255, a: 255)
)

Progress Callbacks

await loader.setOnStateChange { phase in
    print("Loading: \(phase)")
}

await pipeline.setOnPreview { previewImage in
    // Early preview during generation
}

await pipeline.setOnProgress { progress in
    // progress.completion is 0.0 to 1.0
}

Cancellation

await pipeline.cancel()

Privacy & Telemetry

FinegrainCore collects anonymous usage telemetry to understand which features are most valuable.

What we collect:

• Which skills are used (e.g., "shadow", "eraser")
• Framework version
• Platform (iOS/macOS)
• Host app bundle identifier (e.g., "com.example.myapp")
• OS version (e.g., "18.2.0")
• Device model identifier (e.g., "iPhone15,2")

What we DON'T collect:

• Device identifiers (IDFA, IDFV, etc.)
• User information or device names
• Image content
• Any personally identifiable information

Opt-out:

Telemetry is enabled by default. To disable it:

// Disable telemetry globally
FG.telemetryEnabled = false

Privacy Manifest:

FinegrainCore includes a privacy manifest (PrivacyInfo.xcprivacy) that declares this data collection. This will be included in your app's privacy report when you submit to the App Store.

Support

Join our Discord community for help and discussions.

License

Distributed under the Finegrain Terms & Conditions.

The Gist:

• Release Status: Usage is subject to the "Important" note above.
• No Model Extraction: Decoupling, distilling, or reverse-engineering the models is prohibited.
• No Competitive Training: Do not use the SDK or its outputs to train other AI models.
• Attribution: Retain all copyright and license notices.