Design format¶
Artists can contribute art and placement fixtures without access to robot hardware. There are two halves with one hand-off between them:
Design and placement work with the source image. Inkmap places it on a body and sizes it freely; nothing there is a stroke.
Strokes are made from that image at the chosen size by the art pipeline and DrawingBot V3 (
tatbot art separate), as one acquired artwork per ink. The robot draws those.
The tattoo brief is the hand-off: each placed design’s image and the width to draw it at.
Source art¶
tatbot.inkmap-art/1 (config/inkmap/art.schema.json) is one design as an
image:
image:image/pngorimage/jpeg, its SHA-256, pixel size and base64 bytes, at most 8 MB.art_px:[x, y, width, height], the rectangle the art occupies. It is the art pipeline’s crop: the box around every pixel that is not paper (light and neutral, CIELAB L* above 85 and chroma under 12), padded by 3% of the image’s longer side, halves rounded to even. A placement’s width is this rectangle’s width.source:stock,importedorgenerated, with an identifier, licence, attribution and, for generated art, the prompt, model and generator.palette: the catalogue inks (one to five) and style it was made for, ornull. Inkmap suggests inks for imported art from its colours, and the artist can change them.
The content digest covers the whole record, image bytes included. Readers check
the digest, the image digest, the pixel size read from the PNG or JPEG header,
and that art_px lies inside the image. web/inkmap/src/core/art.ts and
tatbot_contracts.art are the two readers.
The stock collection, web/inkmap/public/designs/manifest.json
(tatbot.inkmap-art-collection/1), names each design’s image, digest, pixel
size, art_px, source and palette. Inkmap builds each record from those bytes
and refuses an image that differs. Its designs are Flow-generated and not
dedicated to the public domain.
Placement¶
Use config/inkmap/placement.schema.json for the placement record. Keep the
design identifier, surface/frame, anchor, size, rotation, mirror state, schema
version, and provenance together. Validate records before rendering or mapping.
PlacementFile v7 carries its designs as source-art records. Earlier versions carried stroke artwork and have no reader.
InkLang owns the path from placement description to the exact anchor. A PlacementFile embeds the fixed model specification and identity, the original description, normalized intent, surface-bound resolution, and any explicitly accepted candidate. Consumers must reject provenance whose body digest, face, barycentric weights, actual site, or region UV disagrees with the placement and current atlas.
A placement file distinguishes two surface hashes:
asset_sha256identifies the complete GLB bytes for provenance.surface_sha256identifies canonical non-indexed, Z-up XYZ quantized to little-endian signed integer 10-micrometre units behind face/barycentric anchors. A rig or material export may change the asset hash without changing what an anchor means.
A placement’s rotation_rad turns the design about the surface normal from the
body’s +z projected onto the rest surface. On an arm that is rarely upright:
Inkmap adds the turn that is (Inkmap).
Pose and robot-relative positioning do not belong in a placement.
The preview is an interchangeable front end. A placement file is not a motion program and must not be treated as evidence of physical reachability.
tatbot.surface-placement/2
(config/human-representation/surface-placement-v2.schema.json) binds a
stroke program to a body: the program digest, physical size, rotation, mirror,
review, provenance, and a body target with the body identity, surface digest,
barycentric anchor, semantic site and supported faces. It is the input to
material-stroke planning (InkProgram/2); the plane and cylinder targets were
removed with the paper mounts (2026-11-02). Browser and Python constructors
produce the same digests. Body v1 imports have an explicit migration preserving
their binding and constraints.
Tattoo brief¶
tatbot.inkmap-brief/1 (config/inkmap/brief.schema.json) is what Inkmap’s
Export brief writes: a name, the body identity, the art records used, and
the accepted placements in drawing order. Each placement names its art_id,
width_mm (to 0.1 mm, the pipeline’s 10 px/mm), height, rotation, mirror,
anchor, site and the sentence that placed it. The art registry holds exactly
the placed art, and the content digest covers everything.
tatbot art separate --brief brief.json --out DIR reads it
(art pipeline), checks it with tatbot_contracts.art, and separates
the placement’s image at its width. A brief carries no strokes, tool, palette
cap or execution authority.
Robot render¶
tatbot.inkmap-render/1 (config/inkmap/render.schema.json) is what comes back: inkmap-render.json, which
tatbot art separate --brief writes beside each placement’s separation. It holds a PNG of the program’s predicted ink
over white at the design’s canvas, the digest of the art it was separated from, its width_mm, height_mm and
mirror, and the separation’s minutes, dips, rinses, lost_inks and weakest_source. It carries no strokes.
tatbot_contracts.art and web/inkmap/src/core/render-record.ts are the two readers. The stock collection lists its
own under each entry’s renders, in public/designs/renders/.
Projects¶
tatbot.inkmap-project/5 encloses a PlacementFile v7, editor
pose/appearance/camera settings, bounded placement history and a recoverable
pending-edit base. Its content digest covers the entire document. Editor-only
settings do not alter the enclosed placement body/anchor contract. The project
reader validates the strict JSON Schema and canonical digest, rejects unknown
versions/fields and missing art, and checks all history frames. Loading a
project is not permission to execute it. config/inkmap/project.schema.json
defines the format.
Earlier versions have no reader or migration: Open project refuses them, and one saved in the browser gives way to a new project. Rotation stays in radians so reopening does not move an unchanged design.
Acquired artwork¶
tatbot.inkmap-artwork/2 (config/inkmap/artwork.schema.json) is what DBV3
acquisition produces and the robot compiles: a frozen TattooProgram/1, source
hash and provenance, the dbv3-batik-paths/1 adapter, the frozen recipe
identity and a metric decoding error bound. Its program is authoritative for
geometry, physical dimensions, pen widths, path order and ink assignment.
Previews derive from that geometry. Readers validate nested hashes and source
binding without re-running the original conversion. They never fetch source
identifiers. tatbot_contracts.artwork is the stdlib reader and
tatbot_surface.artwork builds public paint programs.
A DBV3 drawing is optimized for its acquisition size and pen width, so it is never resized: a different size is a new acquisition from the source image. That is why Inkmap places the image and the brief names the width.
tatbot ros compile artwork.json turns one acquisition, or several drawn as
layers (one per ink, on one canvas), into the ROS 2 stack’s program.json and
a preview.svg. --at X,Y centres it on the 128 Ă— 172 mm stencil page and
--stencil DIR names a generated print. The compile, its refusals and the
program format are in ros/README.md section 4.2. A preview is not a
deposition prediction. The simulator’s single-ink CC0 acquisitions (orbit,
sprout and ridges, 30 Ă— 30 mm) are in config/sim2/acquired/.