Add README.md

cf0a015 verified 1 day ago

3.87 kB

license: other
license_name: s-lab-1.0
license_link: https://github.com/pq-yang/MatAnyone/blob/main/LICENSE
library_name: coreml
pipeline_tag: image-segmentation
tags:
  - coreml
  - core-ml
  - ios
  - macos
  - apple
  - on-device
  - video-matting
  - alpha-matting
  - memory-network
  - arxiv:2501.14677

MatAnyone — Core ML

Video Matting, 2025

Temporally consistent video matting. 5-model pipeline with memory propagation.

MatAnyone demo

Core ML conversion of pq-yang/MatAnyone for on-device inference on iPhone, iPad and Mac. Converted with coremltools; the packages are stateless, so all sequencing and buffering lives in your Swift code.


Task	image segmentation
Upstream	pq-yang/MatAnyone
Packages	5
Download size	83 MB
Minimum iOS	17.0
Peak RAM	~800 MB

Files

File	Size	Compute units	SHA-256
`MatAnyone_encoder.mlpackage.zip`	17 MB	`cpuAndGPU`	`97ffd6bc4611f9a3…`
`MatAnyone_mask_encoder.mlpackage.zip`	16 MB	`cpuAndGPU`	`ba67559188ffc64d…`
`MatAnyone_read_first.mlpackage.zip`	21 MB	`cpuOnly`	`34daf7227dbcec73…`
`MatAnyone_read.mlpackage.zip`	21 MB	`cpuOnly`	`052e52c0ffb7ff9e…`
`MatAnyone_decoder.mlpackage.zip`	8 MB	`cpuAndGPU`	`67136aa67000e604…`
Total	83 MB

compute_units is not a suggestion -- it is the configuration the conversion was verified against. Moving a package to a different compute unit can silently change the numerics (FP16 attention overflow) or crash on the GPU.

Download

hf download mlboydaisuke/coreml-zoo --include "matanyone/*" --local-dir ./matanyone
unzip './matanyone/matanyone/*.zip' -d ./matanyone

Use in Swift

import CoreML

let config = MLModelConfiguration()
config.computeUnits = .cpuAndGPU   // as converted — see the table above

// Unzip the .mlpackage, drop it into your Xcode target and Xcode compiles it
// at build time:
let model = try MatAnyone_encoder(configuration: config)

// ...or compile a downloaded .mlpackage at runtime:
let compiled = try await MLModel.compileModel(at: mlpackageURL)
let model = try MLModel(contentsOf: compiled, configuration: config)

This model is split into 5 Core ML packages that are driven in sequence from Swift. Load them one at a time, copy the outputs out of the MLMultiArray buffers and release each model before loading the next — two large Core ML models resident at once will OOM on an iPhone.

Demo

Sample app — sample_apps/MatAnyoneDemo, a standalone SwiftUI project.
Models Zoo — this model is downloadable and runnable inside the Models Zoo app on the App Store, no build required.

Conversion

Script: convert_matanyone.py
Pitfalls hit during conversion (FP16 overflow, ANE buffer limits, stride handling): docs/coreml_conversion_notes.md
Model index: CoreML-Models

License

The conversion inherits the upstream license: S-Lab License 1.0. See https://github.com/pq-yang/MatAnyone/blob/main/LICENSE.

Non-commercial use only.

Credits

Upstream authors: pq-yang/MatAnyone, 2025
Core ML conversion: john-rocky (Daisuke Majima)