Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
178 lines (143 loc) · 7.29 KB

DEVELOPMENT.md

File metadata and controls

178 lines (143 loc) · 7.29 KB
Raw

CloudPoint development and architecture

This is the current implementation and release guide for CloudPoint 1.3.0 source build 8. See PROJECT_MEMORY.md for durable product decisions and rejected approaches.

Runtime architecture

AppCoordinator
  -> ManagedProjectStore and security-scope lease
  -> WorkspaceViewModel per project, shared by its windows
     -> SessionController durable state machine
        -> SingleImageSharpEngine -> bundled CPython -> Apple SHARP on MPS
        -> PoseAwareReconstructionPipeline -> RealityKit pose solution
           -> owned temporary Nerfstudio dataset
           -> OpenSplatTrainer child process -> OpenSplat on MPS
        -> strict PLY/provenance validation -> offscreen Metal probe
     -> GaussianSplatRenderer -> SplatIO and MetalSplatter

Single Image runs one SHARP inference and preserves exactly 1,179,648 Gaussians. 360 Scan solves camera-to-world poses and calibrated intrinsics, writes one bounded dataset, and trains one coherent OpenSplat scene. Legacy LingBot and multi-view SHARP manifests decode read-only and never construct a retired engine.

SessionController owns durable ordering. Frames and manifests commit before engine admission; terminal publication is atomic; cancellation interrupts external work and retains exact temporary ownership until cleanup. The final real workspace window owns shutdown. View dismantling alone is not a window close.

Resource and integrity limits

Boundary Enforced limit
Manifest regular no-follow file, at most 4 MiB
Decoded media at most 8,192 pixels per side and 64,000,000 pixels
PLY header at most 65,536 bytes and 64 properties
Generic PLY at most 2,000,000 total elements and 2,000,000 list items
Raw SHARP exact 1,179,648 vertices, 56 bytes each, exact schema/body
OpenSplat 3 through 2,000,000 vertices, 62 floats each, exact schema/body
Provenance 64 KiB for SHARP, 256 KiB for pose-aware output

Bounds are checked before allocation or decode with overflow-safe arithmetic, then critical counts, dimensions, sizes, and finite values are checked again after materialization. The worker verifies and loads the same no-follow checkpoint descriptor and records its measured digest.

Prerequisites and deterministic bootstrap

  • Apple Silicon Mac
  • Xcode with Swift 6
  • uv
  • Release runtime only: Homebrew CMake, OpenCV, and PyTorch/LibTorch
scripts/bootstrap
scripts/verify-package-resolution
scripts/generate-project
open CloudPoint.xcodeproj

The root Package.resolved is canonical. Generation and CI-style builds use resolved versions only. Bootstrap downloads the pinned XcodeGen artifact into repository-local cache, verifies its checksum, and never substitutes a global binary. The worker lock must pass uv lock --check --offline.

Debug uses the ignored Config/Local.xcconfig worker path. Release packages a relocatable arm64 CPython 3.12.11 environment and pinned OpenSplat executable, rewrites non-system dylib install names, records the real minimum host macOS, preserves notices, and rejects build-machine or Homebrew paths.

Verification gate

Use one native build and then the same compiled bundle for tests:

scripts/verify-package-resolution
scripts/generate-project

xcodebuild build-for-testing \
  -project CloudPoint.xcodeproj -scheme CloudPoint -configuration Debug \
  -destination 'platform=macOS,arch=arm64' \
  -derivedDataPath /tmp/cloudpoint-native-gate \
  -parallel-testing-enabled NO CODE_SIGNING_ALLOWED=NO

xcodebuild test-without-building \
  -project CloudPoint.xcodeproj -scheme CloudPoint -configuration Debug \
  -destination 'platform=macOS,arch=arm64' \
  -derivedDataPath /tmp/cloudpoint-native-gate \
  -parallel-testing-enabled NO CODE_SIGNING_ALLOWED=NO

(cd worker && PYTHONPATH=src .venv/bin/python -m pytest -q)
(cd worker && .venv/bin/ruff check src tests)
(cd worker && uv lock --check --offline)
swift test --package-path Vendor/MetalSplatter --filter PLYIOTests.PLYIOTests
scripts/tests/test-worker-runtime-packaging
scripts/tests/test-sharp-model-packaging
git diff --check

The full native suite may skip only environment-dependent gates such as a physical camera, a supplied real video, real SHARP fixtures, or unavailable Metal. Record every skip. Running the whole vendored MetalSplatter package with plain swift test is not the PLY gate because its renderer tests require an Xcode-produced default Metal library; use the focused command above.

Real pose-aware acceptance additionally requires the packaged runtime and a representative static-object video:

CLOUDPOINT_WORKER_RUNTIME=/absolute/path/to/WorkerRuntime \
  scripts/test-pose-aware-smoke \
  /absolute/path/to/static-subject.mov \
  /absolute/path/to/sharp_2572gikvuh.pt

The exact visual contract is in verification/pose-aware-acceptance.md.

Apple SHARP model separation

Default and public builds must not contain model weights. A private local Release may set this ignored machine-local value:

CLOUDPOINT_SHARP_BUNDLE_CHECKPOINT = /absolute/path/to/sharp_2572gikvuh.pt

scripts/package-sharp-model accepts only the regular, non-symlinked 2,809,738,232-byte checkpoint with SHA-256 94211a75198c47f61fca7d739ba08a215418d8d398d48fddf023baccc24f073d. It verifies source and staged bytes, publishes the seed under Contents/Resources/Sharp, keeps it outside WorkerRuntime, and always preserves Apple's license. The installer still requires explicit acceptance and materializes the normal external verified installation.

Never commit the checkpoint, copy it into source fixtures, or put it in a public app or ZIP. Public packaging is only:

scripts/package-public-release \
  /tmp/cloudpoint-public-release-derived \
  "$HOME/Downloads/CloudPoint-v1.3.0-macOS-arm64.zip"

That command forces the model setting empty and validates both the app and ZIP.

Storage, scopes, and cleanup

  • Durable work uses the selected working directory, default ~/Downloads/CloudPoint.
  • ManagedProjectStore.live() retains one balanced security-scope lease for that root and refreshes stale bookmarks. External source and project scopes are shorter and balanced independently.
  • Temporary training data uses unique CloudPointTraining-* directories with exact ownership tokens and validated markers.
  • Verification uses explicit task-named /tmp or DerivedData paths.
  • Never broadly remove user projects, source media, model installs, installed apps, archives, or unrelated worktree files.

Local install procedure

  1. Run every gate above, then a Release build with the private model setting.
  2. Verify version 1.3.0 (8), arm64 binaries, runtime relocation, model size and digest, license digest, nested and outer signatures, and model absence from WorkerRuntime.
  3. Ad-hoc sign if no Developer ID identity is available.
  4. Quit CloudPoint, retain the current /Applications/CloudPoint.app as a uniquely named rollback copy, move the verified app into place, and launch.
  5. Confirm the running executable is the installed build and restore the rollback copy if launch or metadata verification fails.

A local install does not authorize a tag, public ZIP, notarization, GitHub release, or publication. Those require separate release approval and the guarded public packaging command.