tatmapper-app

Client Preview — future marker-anchored AR architecture

Status and boundary

NOT SHIPPING. This is a separately gated experimental architecture for a future Client Preview consultation tool, tracked by issue #111. PR #118 contains no ARCore, ARKit, Flutter AR plugin, video encoder, or AR camera-session code.

The current beta recommends a U.S. quarter for quick still-photo scale. A future AR session needs a trackable image anchor, so Client Preview would instead use the feature-rich TatMapper Placement Card as its known-size marker. That AR-only choice does not make the card the recommended scale method in the current app.

Client Preview would overlay the artist’s own uploaded design during a consultation. It would not replace still-photo calibration, the final stencil PDF, Print Setup correction, or physical ruler verification. A captured preview is a visual consultation artifact, never an accuracy certificate.

Artist journey

1. Open an existing design or project and choose Client Preview (Experimental).
2. Confirm that the device supports the native AR feature.
3. Place the matching Placement Card flat in the intended placement plane.
4. Keep the full marker visible while TatMapper establishes and maintains the anchor.
5. Adjust artwork position, scale, rotation, and opacity.
6. Capture either:
   • a composited still photo; or
   • a short composited video, only after platform recording performance, storage, lifecycle, and audio-free behavior are proven.
7. Save/share the preview locally with a visible consultation-only label.
8. Return to the existing calibrated photo and stencil workflow for production.

No generic flash library, client account, cloud upload, network lookup, body average, or automatic design generation is in scope.

Marker

Use the feature-rich TM-CAL-1 Placement Card as a known-size image anchor. The measurement square remains authoritative. Marker detection requires:

• the exact target version and physically measured card;
• a flat, undamaged, fully visible marker;
• adequate light, focus, contrast, and frame coverage; and
• an AR-capable device.

The marker must remain visible long enough for initial detection. The UI must distinguish searching, limited tracking, tracked, and lost using text/icons rather than color alone.

Apple’s native prototype would use a known-size ARKit reference image. Android would use a known-size ARCore Augmented Image. The exact SDK/API and privacy requirements must be reverified from official platform documentation when the prototype begins.

Platform boundary

Flutter Client Preview UI
  -> typed platform API
    -> iOS ARKit image-tracking + capture session
    -> Android ARCore Augmented Images + capture session
  <- capability, permission, tracking, anchor pose, capture state

Flutter owns design selection, opacity, artist controls, guidance, feature flag, preview gallery metadata, and share intent. Native modules own camera/session lifecycle, reference-image registration, anchor pose, interruptions, support checks, render compositing, and still/video capture. Typed data crosses the boundary; native SDK objects do not.

Still capture must produce the same composited frame the artist saw. Video capture must be audio-free by default, must never request microphone permission, and must expose recording duration/storage/thermal failures explicitly.

States and fallback

Required states:

• unsupported device;
• camera permission denied or permanently denied;
• marker searching, partial, tracked, and lost;
• limited motion or insufficient light;
• session interrupted, paused, resumed, or failed;
• capture starting, recording, saving, saved, or failed;
• insufficient storage and thermal/performance limiting.

Unsupported or failed AR returns to the still-photo workflow without modifying the calibrated project. No AR SDK initializes when the feature flag is off.

Privacy and offline behavior

Camera frames, design artwork, captured photos, and captured videos remain on-device unless the artist deliberately uses the operating-system share sheet. There is no marker lookup, analytics endpoint, cloud processing, face/body recognition, generic flash library, or client identity. Captures must avoid embedding project paths or internal identifiers. Privacy manifests and store disclosures must be reassessed after the exact native SDK graph is known.

Prototype gates

Do not create an implementation branch until:

• the Placement Card is physically validated as an image anchor;
• compatible real Android and iOS hardware is available;
• the native platform prototypes are separately scoped;
• binary-size, thermal, privacy, and recording effects are reviewed;
• owner authorization is recorded for the experimental branch; and
• PR #118 and its stack are independently reviewed.

Acceptance criteria

• feature flag off by default and zero AR dependency in the shipping beta;
• runtime support detection and a clear still-photo fallback;
• marker-version and physical-size validation;
• full camera, background, interruption, and permission recovery;
• stable anchor acquisition/loss/reacquisition on compatible Android and iOS hardware;
• position, scale, rotation, and opacity controls for artist-owned artwork;
• visible consultation-only language in the session and captured media;
• offline composited still capture;
• separately proven audio-free composited video capture;
• no modification of calibrated project or stencil geometry;
• automated typed-boundary, state-machine, and capture-metadata tests;
• physical-device testing for support/unsupported fallback, low light, occlusion, distance, rotation, motion blur, background/resume, thermal pressure, storage exhaustion, and camera interruption; and
• measured binary-size/privacy review before any shipping decision.