tatmapper-app

TatMapper

A local-first Flutter app for photo-registered tattoo placement planning and physically scaled PDF export on Android and iOS.

[!IMPORTANT] TatMapper is a planar placement beta, not a curved-surface unwrapping system. Camera angle, curvature, and printer settings can change physical results. Every export includes a 100 mm ruler that must be measured before use. No public store release has been verified yet.

What the beta does

TatMapper keeps the photo, calibration, trace, and artwork in one normalized source-image coordinate system:

1. Photo — capture or import the placement area with a known-size reference in the same physical plane.
2. Scale — use a flat U.S. quarter as the recommended quick shop reference, or choose the four-corner TatMapper Placement Card when planar perspective correction is more useful. Other measured round objects and known lengths remain available.
3. Trace — draw directly over the registered photo with separate finger or stylus strokes.
4. Design — import PNG, JPEG, or WebP artwork; optionally prepare its background locally; then position, rotate, and scale it without losing the transform on save/resume.
5. Export — review physical dimensions and create a single-sheet or tiled full-size PDF with an explicitly selected Print Setup (or none) and final X/Y 100 mm verification rulers.

TatMapper can generate an offline one-page A4 or U.S. Letter Placement Card backup without requiring printer calibration; a second page of extra cards is optional. Artists who want to account for physical output can separately create a Print Setup. It represents the complete stencil-production path—not merely a printer model—and retains independent X/Y measurements plus append-only verification history.

The home screen includes an Explore the sample action. It uses synthetic practice-skin media, so the entire workflow can be reviewed without granting camera access or using a person’s photo.

_{Privacy-safe generated demo media. These are sample inputs, not screenshots of functionality.}

Product walkthrough

_{Nine deterministic Flutter renders produced from the shipping widget code in CI: Home → Photo → Scale → Trace → Design → Export, plus non-blocking Scale review, local background removal, and tiled export. No client photo or product mockup is used. See the media provenance and reproduction notes.}

For a hands-on review, launch the app and choose Explore the sample. The guided demo script covers calibration, separate strokes, artwork placement, export review, and the 100 mm print check without requiring personal media.

Engineering status

Area	Evidence-backed state
Product workflow	Android-first artist experience is implemented on an unmerged feature branch; full exact-head and physical validation remain
Flutter quality	Local analysis and focused unit tests pass; the latest remote PR head has eight green quality/build/license checks
Android	API 36 release APK/AAB build; Play signing/internal track remains owner-controlled
iOS	Xcode 26 no-sign release build; signing/TestFlight remains owner-controlled
Monetization	Free keeps every core tool; reviewed static banners and an explicit rewarded export; optional Google Play Pro removes ads; no TatMapper account, Firebase Analytics, ATT prompt, or Sentry
Data behavior	Project media and geometry stay on-device; no app telemetry transport
Web/desktop	Intentionally unsupported and blocked by CI

The complete, deliberately conservative ledger is in docs/RELEASE_READINESS_2026.md.

Run locally

Prerequisites: Flutter 3.44.6, Dart 3.12.2, Java 17, Android SDK 36, and Xcode 26 for iOS builds.

git clone https://github.com/GenghisDarb/tatmapper-app.git
cd tatmapper-app/app
flutter pub get
flutter run

Quality and local release builds:

cd app
dart format --output=none --set-exit-if-changed lib test tool
dart run tool/verify_shipping_policy.dart
dart run tool/verify_license_hygiene.dart
flutter analyze --no-pub --fatal-warnings
flutter test --no-pub
flutter build apk --release --target-platform android-arm,android-arm64,android-x64
flutter build appbundle --release
# macOS only
flutter build ios --release --no-codesign

GitHub Actions applies a one-day, ephemeral test certificate to its minified release APK so that exact artifact can be installed on QA devices. It is never a production or Play upload key. The release AAB remains unsigned until the owner supplies protected signing credentials outside source control.

Architecture

flowchart LR
  P["Placement photo\nnormalized pixels"] --> C["Printed target\nfour-corner rectification"]
  P --> Q["Quarter / measured reference\nquick planar scale"]
  C --> W["Rectified working image\ncanonical pixels"]
  Q --> W
  W --> T["Separate trace strokes"]
  W --> D["PNG transform"]
  C --> E["Physical PDF layout"]
  T --> E
  D --> E
  R["Optional Print Setup\nfinal X/Y correction"] --> E
  E --> V["Final X/Y 100 mm checks"]

The persisted schema never stores widget or screen coordinates. Viewport pan/zoom is an explicit reversible transform around canonical image pixels. See docs/PLANAR_V1_ARCHITECTURE.md.

Safety and privacy principles

• The beta is free end-to-end; no paid-access lockout.
• No advertising, billing, tracking-prompt, or crash-reporting SDK ships.
• Android requests camera access only. The system picker handles imports and PDF sharing without broad storage permission.
• iOS includes a privacy manifest and truthful camera/photo usage text.
• Unsupported artwork formats fail before placement; supported still images are normalized into a safe project-owned working copy.
• Oversized art is never silently shrunk or clipped; it can be tiled at full size with overlap, alignment, trim, and assembly marks.
• “Body flattening,” “curved-surface unwrapping,” and “mm-true” claims are not made by the shipping workflow.

Documentation

• Planar architecture
• Product summary, artist tutorial, and specifications
• Artist-facing terminology
• Placement Card
• Print Setup
• Tiled printing
• Measurement units
• Android beta roadmap
• Calibration protocol
• Calibration method chooser
• Calibration/PDF engineering contract
• Print Setup engineering model
• Printed-target perspective model
• Coin and custom-round fallback
• PDF and print-scale validation
• Physical print validation
• Future Client Preview AR architecture
• Future local multi-project library
• Android internal release
• Google Play release sequence
• Help and support
• Privacy Policy source
• Terms of Use source
• Shop-beta checklist
• iOS/TestFlight release
• QA device matrix
• Privacy data inventory
• Unreleased changelog
• Contributing and security reporting

Release boundaries

Repository/build readiness is not store readiness. A public beta additionally requires owner-controlled signing, store records, privacy/support URLs, listing assets, Play internal testing, TestFlight installation, real-camera QA, and a physical 100 mm printer measurement.

TatMapper’s first-party source is proprietary and all rights are reserved; see LICENSE.md. Bradley C. Peter is the confirmed copyright holder for 2025–2026 and the creator/owner of the current TatMapper logo. The owner directed that the repository remain private and authorized no public source distribution. Third-party rights remain intact and are listed in THIRD_PARTY_NOTICES.md.