orisys-app/apps/autocal/docs/finger-debug-findings.md

Finger calibration-point debugger — findings so far

Status: subsystem 1 (UV picking) works and is measured. Subsystem 2 (simulated 5-axis pose) works and is measured. This note records the numbers, and the two solver bugs that produced confident wrong ones on the way here.

What is established

The export bundle (finger/r01, compute profile)

Quantity	Value
Mesh	1032 vertices, 1974 triangles (matches profiles/compute.yaml)
UV atlas	one connected island, u 0→1, v 0.142→0.857
Pose	world_to_cam, uniform scale 0.018388452316735537, det(R) = +1
Physical size	sensing 15.0 × 7.5 × 15.81 mm; housing 16.0 × 9.5 × 21.0 mm
Surface area	355.77 mm²
Origin	housing base at y ≈ 0; sensing spans y ≈ 0.99 … 8.49 mm
Curvature	~12% of area within 15° of one axis; area-weighted normal ≈ (0, 0.57, 0.26)

The mesh is not in millimetres. blender/scripts/export.py transforms vertices by t_sensor_from_world @ world, and the pose's linear block carries the origin_sensor empty's own uniform scale — 1/54.4 on finger/r01. Physical size is mesh units × that factor, so the factor is derived from the file (and refused if it is not a uniform rotation) rather than assumed. A consumer that treats the vertices as millimetres is wrong by 54×.

UV picking

rasterise() builds, in one pass, a flat image of the UV layout and a pixel → (position, normal, face) table, at 1024×1024 in 0.24 s. Measured:

• valid (surface-bearing) pixels: 72.9%
• round trip vertex → its UV pixel → looked-up 3D: worst error 0.0081 mm
• a pixel in a UV-island gap returns None rather than a fabricated (0,0,0)

Because the atlas is a single island, a click maps to exactly one 3D point.

The supposed finding, and its retraction

An earlier revision of this note reported that the yaw +-90 deg limit made a quarter of the patch unalignable, worst residual 65.1 deg, only 47 of 61 sampled points reachable. That was a solver bug, not a property of the machine.

A later revision then reported the residual as 0.21 deg worst with the yaw limit "not the constraint". That was also wrong, in the opposite direction: the limit itself was wrong. The bench confirmed the yaw stage turns a full half-turn either way (+-180 deg), not +-90.

With the corrected envelope, solved by closed form (see inverse-kinematics.md):

Envelope	Worst residual	Within 0.5 deg	In range
pitch 90 deg, yaw +-180 deg (the machine)	1.2e-06 deg	100%	1032 / 1032

Every vertex is reachable, and the residual is at the floating-point floor rather than at any clamp. The "0.21 deg worst, genuinely clamped vertex" claim above was an artefact of the wrong limit and no longer holds.

No mounting change is required for reachability. The three options the earlier note listed (re-mount, state a tolerance, index the plate) are all unnecessary on the reachability evidence. Whether they help repeatability — a shorter pitch move, a better-conditioned contact — is a separate bench question, not a kinematic one.

Correction (motion-correction-plan.zh.md task 1). This note used to claim that 51 of 1032 vertices end inverted whichever branch is chosen, because the tool direction was antiparallel to the sensor's own up axis. That count came from uprightness comparing a platform axis through to_sensor(np.eye(3)[1]), which is the sensor's own -Z — a horizontal axis — so a body rolled about the vertical was reported as turned over. Measured against the post-mount nominal up (the tool axis) no exported vertex is inverted, and the corrected flag changes no vertex's branch selection. What did invert poses was the approach_sign polarity bug recorded above; the residual could not see it, and neither could that up test. See inverse-kinematics.md → the face is aimed at +Z and the two exact poses of one normal.

What was wrong before, and why it is worth recording

Four solver versions preceded this one, each wrong in a way that produced confident numbers:

• rotating the sensor-frame normal while the stages act in the platform frame (uniform ~90 deg error);
• composing the stages in the wrong order;
• a seeded search, which left 22.7 deg on the table for normals whose best yaw sat far from the analytic guess;
• a sweep whose yaw ranking used "how close does the yawed normal come to the tool axis", which is not the quantity that matters. What matters is where the whole circle the pitch stage sweeps sits. Ranking by the wrong one left 68 deg on the table while looking entirely reasonable — this is the bug that produced the retracted 65 deg finding above.

The solver is now a sweep of every yaw/pitch combination, evaluated as a grid one yaw at a time (7.8 ms per point, 1032 vertices in 9 s), then a local polish to 1e-4 deg. It is verified two ways: it is never worse than a brute-force search at 2 deg on random normals, and its returned residual matches an independently composed rotation matrix to 8e-8 deg. Both checks are tests, not one-off probes.

The residual is measured from the actual rotations, so a wrong derivation shows up as a number rather than as a plausible pose.

Implemented so far

Module	State
sensor/frames.py	mount mapping as a named constant; refuses a non-rotation
sensor/export_bundle.py	load + validate; derives mm/unit; refuses a non-uniform or mirrored pose, and count mismatches
sensor/uv_flat.py	flat image + pixel→3D table; gap pixels are None
motion/kinematics.py	constrained search + measured residual; stage limits are parameters; singular case reported, not guessed
ui/sensor_panel.py	picker, readouts, point table; refuses gap pixels with a reason; picked rows kept at full precision, not re-read from the 3-decimal display text
ui/pose_preview.py	3D preview coloured by residual, tool axis drawn; the legend is a sibling label, because text composited over the GL surface is unreadable once it overflows. The scene, the palette and the framing rule are described in finger-preview.md
motion/kinematics.py	closed-form solve, exact to 1.2e-06°; the sweep is kept only as the reference the tests check it against — see inverse-kinematics.md
workspace finger tab	wired, checked at 1440×900 and 1920×1080 in both themes
startup	the remembered bundle loads automatically, so the tab comes up working instead of showing a filled-in path over two empty views
tools/preview_snapshot.py	photographs the 3D pane with a real GL context, at rest or mid-playback, pane-only or composited into the page

Not yet built: capture of picked points into the sequence, and the live-sensor counterpart of the simulated pose.