Reality Pulse

Reality Pulse is a macOS photogrammetry queue for Apple Object Capture. It turns folders of photos into USDZ 3D models with a SwiftUI batch interface, RealityKit reconstruction settings, scheduled processing windows, SwiftData persistence, and crash-aware retry recovery.

Use it when you have many capture sets to reconstruct and want a local Apple Object Capture workflow that can run overnight, survive relaunches, keep completed history, and export multiple quality levels from one job.

Why Reality Pulse?

Apple Object Capture is powerful, but running one folder at a time is tedious when you are scanning products, props, archive objects, handmade pieces, or environment assets. Reality Pulse wraps PhotogrammetrySession in a persistent queue so you can prepare a batch, choose output quality, and let the Mac process the work in order.

Features

• Batch Apple Object Capture queue: add multiple image folders and process them sequentially.
• USDZ photogrammetry output: export one or more .usdz models per job.
• USDZ conversion: queue an existing .usdz file as a job to convert it to glTF, glb, or Gaussian Splat (.ply) without reconstructing.
• Multiple detail levels: generate preview, reduced, medium, full, raw, or custom outputs from the same capture.
• Additional export formats: convert each finished USDZ to glTF/glb, a Gaussian-splat .ply, or a Text Sculpture .glb that rebuilds the model out of your own words (readable rings of text or a cloud of letters, any script, colored by the model's texture or a single ink).
• Custom reconstruction settings: configure mesh primitive, masking, bounding-box handling, polygon limits, texture maps, texture format, and texture resolution.
• Scheduled processing: delay a queue run or restrict processing to allowed hours, including overnight windows.
• Sleep prevention: optionally keep macOS awake while the queue is active.
• SwiftData persistence: queue jobs, history, schedule settings, and recovery metadata survive app quits and crashes.
• Interrupted-job recovery: running jobs are restored as interrupted on launch and can be retried.
• Retry-safe exports: completed outputs are skipped on retry, while stale partial files are replaced before reconstruction resumes.
• Sandbox-friendly folder access: user-selected input and output folders are restored with security-scoped bookmarks.
• Progress and notifications: track job progress, estimated time remaining, failures, and queue completion.

Screens And Workflow

1. Add a job from the queue dashboard.
2. Pick an image folder and an output folder.
3. Name the model and choose Object Capture settings.
4. Optionally enable additional detail-level exports.
5. Add more jobs, reorder them, and configure a schedule.
6. Press Start when you want the queue to run.

Reality Pulse restores the queue on launch, but it does not automatically start processing after a relaunch. The user stays in control.

Requirements

• macOS 15.0 or newer
• Xcode 16.0 or newer
• A Mac supported by Apple Object Capture / RealityKit photogrammetry
• Photo sets suitable for PhotogrammetrySession

Build

Clone the repo and build the macOS app:

git clone https://github.com/nuit-dhiver/reality-pulse.git
cd reality-pulse

xcodebuild -project RealityPulse.xcodeproj \
  -scheme RealityPulse \
  -configuration Debug \
  -destination 'platform=macOS' \
  build

You can also open RealityPulse.xcodeproj in Xcode and build the RealityPulse scheme.

Test

Run the persistence and scheduler-focused test suite with:

xcodebuild -project RealityPulse.xcodeproj \
  -scheme RealityPulse \
  -configuration Debug \
  -destination 'platform=macOS' \
  test

The current tests cover SwiftData persistence, schedule reloads, launch recovery, interrupted jobs, retry behavior, and one-time legacy JSON migration.

Release

Releases are driven by Git tags. To publish a new GitHub Release:

git tag v1.1.0
git push origin v1.1.0

The release workflow builds Reality Pulse.app in Release configuration, runs the test suite, packages the app as a zip, writes a SHA-256 checksum, and attaches both files to the GitHub Release.

The current release artifact is ad-hoc signed for local/open-source distribution, not notarized.

Versioning

Bump the version before tagging or uploading to App Store Connect. Every command except show also increments the build number, which App Store Connect requires to increase with each upload:

scripts/bump-version.sh patch

Use show, build, patch, minor, major, or set 1.4.0.

Mac App Store

The app target is sandboxed (com.apple.security.files.user-selected.read-write only), ships a privacy manifest (PrivacyInfo.xcprivacy), and declares ITSAppUsesNonExemptEncryption = NO. The bundle identifier is com.openmuseum.realitypulse. The privacy policy is in PRIVACY.md.

The Mac App Store build workflow (.github/workflows/app-store.yml) is started manually from the Actions tab. It runs the tests, archives, signs, and exports the .pkg using scripts/ExportOptions.plist. With upload unticked it's a dry run that attaches the signed package as an artifact; ticked, it also uploads the build to App Store Connect for TestFlight and review.

One-time setup after joining the Apple Developer Program:

1. Create the explicit App ID com.openmuseum.realitypulse and the app record in App Store Connect.
2. Create an Apple Distribution certificate and a Mac Installer Distribution certificate, then export both identities from Keychain Access into one .p12.
3. Create a Mac App Store provisioning profile for the App ID named exactly Reality Pulse Mac App Store.
4. Create an App Store Connect API key (Users and Access › Integrations) with the App Manager role.
5. In the repository's Actions settings, add the variable APPLE_TEAM_ID and the secrets SIGNING_CERTIFICATES_P12 (base64 -i certificates.p12 | pbcopy), SIGNING_CERTIFICATES_PASSWORD, ASC_KEY_ID, ASC_ISSUER_ID, and ASC_PRIVATE_KEY (the .p8 file contents).

Run scripts/bump-version.sh before each upload; App Store Connect rejects a build number it has already seen.

Usage Notes

Input Images

The app is designed for folders of still images supported by Apple Object Capture. Image metadata is inspected where available so the UI can enable bounding-box related options only when the capture set supports them.

Output Files

Each requested detail level writes a separate USDZ file named:

<model-name>-<detail-level>.usdz

For example, a model named Vase with medium and raw outputs produces:

Vase-medium.usdz
Vase-raw.usdz

Scheduling

Scheduling controls are intentionally conservative:

• delayed start waits until a selected date and time
• allowed hours constrain when new jobs begin
• if a processing window closes during an active reconstruction, the current job continues because PhotogrammetrySession does not support pausing an in-progress request
• pause takes effect between jobs

Persistence And Recovery

Reality Pulse stores jobs and schedule settings with SwiftData. On launch it:

• loads the persisted queue and history
• restores the saved schedule
• converts any previously running job to interrupted
• keeps completed, failed, cancelled, and interrupted jobs visible until the user removes them
• leaves pending and scheduled jobs idle until the user presses Start

When retrying an interrupted multi-output job, previously completed outputs are skipped only if the app recorded their completion and the file still exists. Existing files without a recorded completion are treated as stale partial outputs and replaced before retrying.

Architecture

• ObjectCaptureReconstructionApp: creates the SwiftData model container and main SwiftUI window.
• ContentView: owns the app model and routes between the queue dashboard and processing views.
• AppDataModel: central UI/application state.
• JobScheduler: sequential queue processor, schedule enforcement, sleep prevention, notifications, and retry recovery.
• JobStore: SwiftData-backed persistence API for jobs, schedule settings, and legacy JSON migration.
• ReconstructionJob: app-facing value model for input/output folders, Object Capture settings, progress, status, and completed outputs.
• Settings/: SwiftUI controls for folder selection and PhotogrammetrySession.Configuration.
• Processing/: progress display and USDZ preview with RealityKit.

See docs/ARCHITECTURE.md for a deeper code map and CONTRIBUTING.md for development conventions and test commands.

GitHub Topics

Recommended repository topics:

apple-object-capture, photogrammetry, macos, swiftui, swiftdata, realitykit, usdz, 3d-reconstruction, object-capture, batch-processing

These topics help developers find the project when searching for SwiftUI photogrammetry tools, RealityKit Object Capture examples, macOS USDZ exporters, and batch 3D reconstruction workflows.

Roadmap Ideas

• screenshot and demo media for the README
• export presets for common asset pipelines
• richer queue filtering and search
• per-job logs in the UI
• release packaging and notarized builds

License

This project is licensed under the MIT License. It also contains components originally provided by Apple Inc. under the MIT License. See LICENSE for the full license text, including the Apple notice.