tatmapper-app

Planar Photo Mapping Beta architecture

Product boundary

The shipping workflow registers a trace and PNG design to one orientation- normalized placement photo. A two-point reference converts source-image pixels to millimetres. It does not reconstruct a 3D surface or compensate for body curvature.

Prohibited shipping claims include “body flattening,” “curved-surface unwrapping,” and “mm-true.” Those claims require a future geometry model, ground-truth fixture dataset, documented error metric, and measured tolerance.

Canonical coordinate system

Persisted geometry uses source-image pixels after EXIF orientation is baked into the saved image. The project schema stores:

schema version and project ID;
durable normalized photo path, width, and height;
calibration endpoints, known millimetres, calculated px/mm, source, and warnings;
a list of separate trace strokes, each containing source-image points;
PNG path, intrinsic dimensions, image-space center, scale, and rotation;
export page settings and timestamps.

Widget positions, arbitrary screen coordinates, and transient viewport matrices are never product geometry. ImageViewportTransform and TransformationController.toScene provide the explicit inverse transform used at interaction boundaries.

Modules

Module	Responsibility
`planar_project.dart`	Versioned model, validation, serialization, sample fixture
`planar_media.dart`	Bounded off-UI-isolate image validation, orientation normalization, atomic owned copies
`camera_capture_screen.dart`	Testable camera state machine and lifecycle recovery
`registered_photo_canvas.dart`	Registered photo rendering, scale handles, separate strokes, design drag, zoom/pan
`planar_project_store.dart`	Atomic JSON/media ownership under `projects/<project-id>/`, recovery and deletion
`project_save_coordinator.dart`	Serialized, debounced, flushable, failure-aware saves
`planar_pdf_exporter.dart`	Physical layout, vector strokes, PNG placement, warnings, 100 mm ruler
`planar_workflow_screen.dart`	Photo → Scale → Trace → Design → Export state and recovery UX

The default startup path does not initialize ads, billing, ATT, Sentry, remote configuration, or entitlement services.

Storage and ingestion boundary

Each persistent project owns project.json, its normalized placement photo, its normalized PNG design, and project-specific temporary files in one private directory. TatMapper never deletes the artist’s picker source. Replacement writes and verifies the new owned image, flushes the new project JSON, and only then deletes the superseded owned media. Startup removes interrupted imports and unreferenced TatMapper-named media without touching unknown or external paths.

Input is limited to 40 MiB and 80 million encoded pixels before full decoding. Images must be at least 256 pixels on each side and no more extreme than 20:1. EXIF orientation is baked and the longest normalized side is capped at 4096 px without upscaling. A 4096 px RGBA working frame is about 64 MiB; decoding, resizing, and encoding run outside the UI isolate. PNG design pixels are preserved by default, including white and translucent artwork.

Experimental legacy code

Older native/OpenCV and dual-photo research sources remain in repository history for reference but are not linked into Android or iOS beta artifacts and are not reachable from the shipping application root. They must not regain a default route without a separate evidence-backed product decision.

Schema changes

Schema version 2 rejects unknown versions rather than guessing. A future schema change must include explicit migration tests. File-loss recovery must present a clear user action; it must not silently substitute unrelated geometry.