This repository provides two run paths:

1. iPhone app path for real on-device SDK testing.
2. CLI path for macOS command-line runs.

Both paths use the same core benchmark pipeline in Sources/BenchmarkCore.

Project context and parameter rationale: docs/requirements/project-requirements.md.

Use this path when you want to run real ML Kit or Dynamsoft scanning on a physical iPhone.

cd BenchmarkApp
pod install
open BenchmarkApp.xcworkspace

Always open .xcworkspace (not .xcodeproj).

1. In Xcode, open target BenchmarkApp.
2. Go to Signing & Capabilities.
3. Enable Automatically manage signing.
4. Select your Apple Team.
5. Use a unique bundle identifier if needed.
6. Select your iPhone as run destination.
7. Press Run.

At runtime, the app resolves dataset directories in this order:

1. AppBundle/annotations and videos in AppBundle/.
2. Documents/benchmark-dataset/annotations and videos in Documents/benchmark-dataset/.

If neither is found, the app reports a clear dataset-not-found error in the log view.

Option A: Bundle files into app target

1. Drag annotations/ and your .mp4 clips into Xcode under the app target.
2. Enable Copy items if needed and add to target BenchmarkApp.

Option B: Copy into app Documents via Finder (recommended for larger datasets)

1. Build and install app once.
2. Connect iPhone to Mac.
3. Finder -> iPhone -> Files -> BenchmarkApp.
4. Copy folder structure:

benchmark-dataset/
  annotations/
    clip1.csv
    clip2.csv
  clip1.mp4
  clip2.mp4

The app does not use command-line flags. Parameters are set via UI and code defaults in BenchmarkApp/BenchmarkApp/BenchmarkViewController.swift.

1. Launch app on iPhone.
2. Pick engine in the picker.
3. Tap the gear icon (⚙️) to open Settings and adjust phase, track, sampling, and timeout.
4. Tap Run Benchmark (or Run All to run every engine preset sequentially).

Dynamsoft engine presets lock phase and track automatically. ML Kit leaves them configurable.

Outputs are written to app Documents:

• benchmark-out/benchmark.json
• benchmark-out/benchmark.csv

Use this path for scriptable terminal runs on macOS.

swift run BenchmarkCLI \
  --annotations /path/to/annotations \
  --videos /path/to/videos \
  --output /path/to/out \
  --engine mlkit-mock \
  --phase baseline \
  --track parity

• mlkit-mock and dynamsoft-mock: deterministic mock detections for pipeline validation.
• mlkit-real: requires ML Kit frameworks linked on an iOS target.
• dynamsoft-real: requires Dynamsoft SDK + license wiring for host context.

The CLI writes to your --output directory:

• benchmark.json
• benchmark.csv