The lab¶
tatbot lab runs studies of what the rig can tattoo. A study asks one question, fixes the print its cells sit on and
the constants it holds, and bounds every setting its trials may vary. A trial is one technique drawn at one settings
vector in one cell. A plan turns proposed trials into the runs tatbot ros draw draws, and tatbot lab read
measures each drawn cell from the rig’s own camera frames: no person’s photo, no wipe.
The library is python/tatbot_lab; the records are tatbot_contracts.lab. It runs in the shared offline drawing
interpreter (numpy, OpenCV, PyYAML) and moves no arm.
tatbot lab new --id card-3rl --question "What does the 3RL lay at each depth?" --stencil /tmp/stencil-bef888 \
--cartridges lutin-3rl-bugpin --inks true_black,bright_red \
--palette true_black=inkcap_large_2,bright_red=inkcap_medium_1,water=inkcap_large_1 \
--bound trim_mm=-2.5:-1.0 --bound speed_mm_s=2.5:6
tatbot lab propose card-3rl --card lutin-3rl-bugpin
tatbot lab plan card-3rl --stencil /tmp/stencil-bef888 --sheet bef888-a
tatbot lab capture card-3rl --plan p0001 --run run-01 --side before
tatbot ros draw ~/tatbot-lab/card-3rl/plans/p0001/run-01/program/program.json --trim-mm=-1
tatbot lab capture card-3rl --plan p0001 --run run-01 --side after
tatbot lab read card-3rl --plan p0001 --run run-01 --stencil /tmp/stencil-bef888
tatbot lab status card-3rl
plan prints each run’s tatbot ros draw command, its depth trim included.
Records¶
A study is a directory under TATBOT_LAB_ROOT, else ~/tatbot-lab, never in the repository:
File |
Holds |
|---|---|
|
the study, |
|
trial records, |
|
the plan: its runs, their draw commands and modelled minutes |
|
|
A trial moves through proposed, planned, drawn and read (or failed, dropped), and records the program and
run that drew it. Every record is validated
when it is written, and a batch is written whole or not at all. A study holds the machine constants it was run at:
by default the battery at 6.0 V, which runs the pen at 51 Hz, and its 4.0 mm stroke.
What a trial can vary¶
Setting |
Level |
Applied by |
|---|---|---|
|
run |
|
|
program |
the compile’s draw speed |
|
program |
a study’s bound only: needle pokes per millimetre of line in a stroke’s middle, stored as the |
|
resource |
the trial’s own resource’s |
|
geometry |
the technique’s strokes |
Every trial states its depth trim and its speed; neither is ever defaulted. A setting the study gives no bounds is held at its technique’s default, or for the dip settings the cartridge datasheet’s, and a trial that sets it is refused. Trials that differ in trim or speed cannot share a run, so a plan draws one run per cartridge, trim and speed.
Every trial is its own resource. Changing to another resource of the same tool and ink costs nothing at the arm, and the compiler dips afresh at each resource, so every cell starts on a fresh dip whatever the cell before it drew, at the cost of a dip a cell. A change of ink rinses.
Technique |
Strokes |
Read for |
|---|---|---|
|
parallel strokes, 2 mm apart |
darkening and ink width per stroke |
|
a serpentine of 14 strokes 1 mm apart, 168 mm of line |
how far one dip carries |
|
a square of strokes at the pitch |
a fill’s darkness and its bands |
|
strokes fading from full deposition to |
the fade, bands and speckle |
|
an L, a zigzag and three short strokes |
what stopping, turning and lifting leave |
The compiler dips again every mm_per_dip, so a carry cell reads one dip whole only at a mm_per_dip above its
168 mm of line; at the datasheet’s cadence it is read dip by dip and a dip that outlasts its share reads “at least”.
A cell 20 mm wide (--cell-mm 20, lines 18, length_mm 18) holds 324 mm, enough for black at depth. Not settings
yet: the rinse, the pen’s angle to the stroke, and dots, which the program format has no way to draw. A whip compiles only for a tool whose datasheet records
fade_lift_mm (tools).
Cells and sheets¶
The lab draws on the tag prints the rig tracks, so every cell sits over markers. A cell is centred on one grid
marker and is no wider than the grid’s pitch less a millimetre, so inking it costs that marker alone. The corner
anchors, which the overhead reads the print by, carry no cell. The silicone print holds 19 cells, named by their
marker (m12), so a cell is the same place on every sheet of one print.
Cells are spent from the edge inward, each next one as far as it can be from those already drawn, so the markers
still readable stay spread over the sheet. A sheet is a physical skin: --sheet names it, and a fresh name starts
with every cell free. It is the same skin to every study of its print: a study made for new bounds takes only the cells no other study’s live trial holds, and a trial marked dropped frees its cell. Trials that find no cell stay proposed for the next sheet.
Within a plan, runs go cartridge by cartridge in the study’s order, lightest ink to darkest, so black comes last: a 30 s rinse does not clear a heavy black run. Within a run each ink is a layer, lightest first, rinsed between. A plan that fails to compile leaves no directory and moves no trial.
Mounts¶
Any number of skin mounts can stand on the table, each carrying a sheet of the print, and they can be moved, added
or taken away while a run draws on another. They carry no identity of their own: a sheet is told from the others by
where it stands. tatbot ros page says where each sheet the overhead reads stands, in mm in the arm’s base, and
--sheet-at X,Y on tatbot ros draw, ros touch and lab capture makes the one nearest that point the page.
Once chosen, the page follows its own sheet as it slides, and while the arm hides it no other sheet stands in for
it. Moved far at once, it stands lost until chosen again. Choose a sheet before a run draws on it; a mount being
re-skinned stays out of every run until it is chosen. Name the sheet the same way in the plan (--sheet) as on the
table.
The characterization card¶
tatbot lab propose STUDY --card CARTRIDGE proposes the standard card for a cartridge in the study’s inks, the
first being its main ink. In each ink: a depth ladder of four lines across the trim bounds, carry cells at the
deepest and a middle depth, and an A/A repeat of the middle line, which gives each metric its noise floor. In the
main ink: a speed ladder, a whip, corners and a solid patch. In two inks that is 19 cells, one silicone sheet, in six
runs. When the study bounds mm_per_dip, the carry cells draw at its top, on one dip.
The dip card¶
tatbot lab propose STUDY --dip-card CARTRIDGE proposes the card that measures how a cartridge takes ink, in the
study’s first ink (or --inks’ first). It is for a cartridge whose datasheet dip is another’s: dip.card.status: borrowed, which tatbot ros compile refuses for a design (tools). The lab may still draw with it. All
its cells are drawn at the middle of the study’s depth and speed bounds, so it is one run:
two
linecells at the datasheet’s dip, an A/A pair: the mark (ink_width_mm) and the flood’s noise floor;a
carrycell at the top of themm_per_dipbound: how far one dip carries;three
linecells over each ofdip_dwell_s,dip_above_ink_mmanddip_drain_sthat the study bounds (the drain’s rung at 0 is the first two cells’ dip).
Every cell is its own resource and starts on a fresh dip, so each cell’s flood is its own dip’s. Choose the
shallowest dwell and depth whose flood is within the A/A pair’s spread and whose line still holds its darkness, the
shortest drain that brings the rest there, and the carry’s strong_mm; write them into the datasheet’s dip: and
set card: {status: read, study: <id>}. The study states the bounds:
tatbot lab new --id dip-7rl --question "How does the 1007RL take red?" --stencil /tmp/stencil-bef888 \
--cartridges lutin-7rl --inks bright_red --palette bright_red=inkcap_medium_1,water=inkcap_large_1 \
--bound trim_mm=-2.5:-2.5 --bound speed_mm_s=3.5:3.5 --bound mm_per_dip=40:300 \
--bound dip_dwell_s=0.25:1.5 --bound dip_above_ink_mm=0.5:3 --bound dip_drain_s=0:3
tatbot lab propose dip-7rl --dip-card lutin-7rl
Capturing a run¶
tatbot lab capture STUDY --plan P --run R --side before|after photographs a run’s cells on the rig through
tatbot ros views. For each cell the pen is held over its centre as ros inspect’s close-up holds it, 12 mm over
the skin, and every wrist D405 the arm carries grabs nine frames there, their per-pixel median kept as
v<NN>-<role>.png. Every hold is planned, and its wrist checked against the arm model’s range, before the arm moves.
The views aim by the newest page set-up (a draw’s or a tatbot ros touch’s); the after side names the page the
before side used, so both stand at the same poses. Without a set-up, --sheet-at X,Y aims by the overhead tracker
at the sheet of the run’s print nearest that point (see Mounts); those holds hover at the stack’s close-up
height, 12 mm (the tracker reads the skin to about 2 mm since its re-registration through the wrist D405), and the
after and dry sides aim at the sheet the before side named. The wrist D405s ride about 150 mm behind the tip, so a
lower hold sees a cell only somewhat finer.
Before leaves the arm holding for the draw; after lands it and marks the run’s trials drawn. The frames come back to <run>/views/<side>/ with views.json (the page, each view’s
joints and pose, each camera’s intrinsics). --rest-view takes the one view where the arm stands instead, with no
motion: 2026-11-05’s method on the WXAI follower.
The overhead D555’s view comes first, unless --no-overhead: the median of nine exposures from its owner’s capture
over the bus, each newer than the last, as overhead.png, taken with the arm at rest so it hides the same part of
the table before and after. --overhead-only takes it alone and never touches the arm, so one mount can be read
while the arm works on another. --side dry takes the views again once the ink has dried, aimed by the before side’s
page, and changes no trial.
Running a planned run¶
tatbot lab run STUDY --plan P --run R --stencil DIR --sheet-at X,Y takes one planned run through the rig in four
steps:
before: the capture before it draws, which leaves the arm holding.draw: the run’statbot ros draw, with its depth trim, on the chosen sheet, with no inspection, the arm landed after, so the overhead sees the sheet from the same rest as before. It states the run’s cartridge with--ee-tool, so a cartridge the mount does not hold is refused, not drawn over: a cartridge swap is asked for between runs, and the run is started again once it is fitted.after: the capture after it, from rest as the before capture was, which lands the arm.read:lab readfrom the wrist views, then from the overhead’s, with the ros node’s draw run id recorded.
Each step’s exit and time go to <run>/lab-run.json. A failed step stops the run, and --from STEP resumes at it
with what the earlier steps recorded.
Reading a cell¶
tatbot lab read STUDY --plan P --run R --stencil DIR reads every cell of a drawn run from its captured views (the
after side, or --side dry), or from --before B --after A. --instrument overhead reads overhead.png instead
of the wrist views. Both hold frames by the same names, one pair per view, each pair taken from one pose:
the wrist camera’s rest view, or one hold, which the arm repeats.
Registration. The before frame’s markers within 52 mm of the cell give a homography to the page, each marker weighted by
exp(-(d / 25 mm)²)of its distance from the cell. The skin curves, so no single homography fits every marker, and the weighting keeps the fit truest where the cell is. A marker the fit misses by more than 25 px is a bad read and is dropped, worst first. The fit is deterministic: RANSAC drew different inliers on different calls and moved a cell by a millimetre.Alignment. The after frame is aligned to the before in the image by ECC over the cell and 40 mm of skin around it, with every cell of the run left out. It is then sampled through the before frame’s homography, so the curve bends both alike. Ink over a marker cannot move the registration.
Fusion. A scan’s views are combined per pixel by their median, which drops a wet-ink glint that only some views see and samples finer than any single view.
Difference. A gain and offset per channel, fitted on the skin outside the run’s cells, matches the light.
dLis the L* the cell lost,daanddbthe a* and b* it gained, andcthe share of light the ink takes (1 − after/before in linear luminance), which blur does not change. Subtracting the before frame cancels the print. Hue is read only where the before frame is light: on the violet print, red reads as darkening.
Metric |
What it is |
|---|---|
|
the standard deviation of |
|
the cell’s mean change; a* and b* on unprinted skin only |
|
each stroke’s darkening within 0.45 mm of it, its ends left out |
|
per stroke, the integral of |
|
per dip cycle, from the dip, where the level falls below half its peak ( |
|
the darkening in tenths of the strokes’ length, and first over last |
|
the strongest periods across the strokes in each quarter of their length |
|
the share of the ring 1.5–8 mm around the strokes darkened by more than 8 |
|
the darkening in the millimetre beyond the strokes’ far end |
|
what a fresh dip lays before its load settles: the ink width over the first 3 mm of each stroke that follows a dip, over the strokes’ steady width ( |
|
every technique: the darkening over each stroke’s first millimetre ( |
Every stroke starts on a needle that dwells, so a start is wider than a middle with or without a dip:
over_other_starts is the dip’s own share, and a cell needs strokes that follow no dip for it. A dip that floods
nothing reads 1.0 on both.
--instrument overhead reads the overhead D555’s frames, its markers found as the stencil observer finds them
(small ones upsampled). At about 0.86 px/mm it keeps a cell’s mean change only and cannot see a line. Two sheets of
one print in its view give every marker twice, so a capture made with --sheet-at is read inside the chosen sheet’s
region alone: the tracker’s pose of that sheet, which the capture records, projected through the overhead’s
intrinsics, 15 mm past the print on every side. --roi x0,y0,x1,y1 gives a region by hand instead, and reads.json
says which was used. On 2026-11-08 the merged rig’s first capture read forearm18’s 18 mm markers at about 14 px a
side, on both mounts at once.
Comparing settings¶
A trial’s numbers mean something only against the noise between repeats. Every card carries A/A cells, two trials
at one settings vector; a setting changes a metric only where the difference exceeds the largest A/A difference of
that metric, and a change that makes missing ink or speckle worse by more than their A/A spread is not an
improvement whatever else it gains. That is the rule tatbot research promoted DrawingBot baselines by, folded into
the lab on 2026-11-08 with the rest of its paired studies.
Each trial records what drew it: the digest of its run’s compiled program when it is planned, and the ros-draw
run id when it is read (--run-id). The run’s meta.json holds the software the stack drew with
(ros_runtime.software_digest), so a difference between two trials can be checked against a change of software
as well as of settings.
Searching¶
tatbot lab propose STUDY --search N --technique T proposes N trials aimed at what the study does not yet know about
one technique’s marks with one cartridge and ink (--cartridge and --ink, by default the study’s first). It moves
only the settings the study bounds, so it never leaves them.
The archive. A read trial’s marks are placed on two descriptors: darkness (ΔL*, in bins from under 3, which is no mark, to over 40) and the technique’s own one. That is the median width for
line, how far the first dip carried forcarry, the speckle share forsolid, the fade’s first-over-last forwhip, and ends over middles forcorners. A bin’s elite is its cleanest trial, the one with the least speckle about its strokes; of two as clean, the faster one wins.tatbot lab map STUDYprints each archive as a grid of elites, darkest at the top.The surrogate. Once four trials are read, each descriptor gets a model of the settings: a linear trend (deeper is darker) and a Gaussian process over what the trend leaves.
A batch mixes three kinds of trial, and each records why it was proposed in its
hypothesis:Surprises, once eight trials are read: an A/A repeat of a read trial that the surrogate, refitted without it, predicted more than three standard deviations off. A bad read and a real cliff look alike until repeated.
Quality: a near neighbour of an elite whose speckle is worse than the median elite’s.
Novelty, the rest: settings the surrogate puts in a bin no trial holds, or else where it is least sure and farthest from every trial. Before there is a surrogate, simply the settings farthest from every trial.
Each distinct depth trim and speed is a run of its own, and so a page set-up. A batch therefore holds at most
--max-runs of them (default 3), with trims snapped to 0.25 mm and speeds to 0.5 mm/s. Past that, its trials take the
nearest run already in the batch. When depth and speed are all the study lets vary and every run is taken, the rest
of the batch repeats its own picks, which measures their noise floor. --seed makes a batch reproducible.
How closely it reproduces the 2026-11-05 skin tests¶
These are the wrist camera’s rest frames before and after each test on the silicone print, read by the lab and by the scratch readers that produced that day’s numbers (trim −2.5 throughout):
Test |
Scratch reader |
|
|---|---|---|
Black carry block: strong, visible |
257, 296 mm |
277, 308 mm |
Red after the black: strong, visible |
178, 197 mm |
187, 197 mm |
Red, fresh cartridge: strong, visible |
217, 217 mm |
213, 225 mm |
Whip, 60 mm a dip: speckle, first over last, band period |
0.16, 1.1, 1.6 mm |
0.17, 1.08, 1.57 mm |
Whip, 200 mm a dip: speckle, first over last, band period |
0.10, 1.3, 5.2 mm |
0.10, 1.33, 5.23 mm |
The per-stroke darkening agrees stroke for stroke. The carry distances differ by less than one 19.7 mm stroke, because the scratch readers counted whole strokes and the lab interpolates within the stroke where the level crosses its threshold.
Limits¶
The wrist’s rest view resolves about 3.7 px/mm, so a 0.5 mm line is two pixels.
ink_width_mmmeasures it through the blur, but on synthetic frames it read 0.47–0.54 mm for a true 0.47 mm, and less over the violet print, whose light the ink takes a smaller share of. A scan’s fusion is meant to sample finer, but how much finer is not yet measured.Unwiped silicone holds ink on its surface. A read straight after drawing sees that ink, and wet ink may hide a fade. Read again when it is dry.
A held view sees its cell from about 170 mm, near 3.9 px/mm, the pen’s tube hiding one side of the tip; a second D405 turned 180 degrees about the wrist sees the other.
The overhead hides nothing behind a tube but sees a 10 mm cell as nine pixels across, and the arm at rest hides whatever it stands over: a cell under the arm reads in neither of its overhead frames.