Tutorial: Proofreading Annotations¶
Proofreading is the process of reviewing and correcting annotations to ensure high-quality data. LUC3D provides several tools for systematic quality checking.
Why Proofread?¶
Common annotation errors that degrade 3D reconstruction:
- Swapped keypoints — Left/right limb confusion
- Mispositioned keypoints — Keypoint placed on the wrong body part
- Wrong instance grouping — Instances from different individuals linked together
- Missing occlusion labels — Guessed positions for hidden keypoints instead of marking them not visible
Use reprojections for proofreading
Reprojections show you exactly where keypoints should be based on 3D geometry. They're invaluable for catching errors. See Reprojection-Aided Labeling for the full workflow on using reprojections for both labeling and quality checking.
Proofreading with Reprojection Error¶
The most powerful proofreading tool is reprojection error — it quantifies how consistent your annotations are across camera views.
Step 1: Triangulate¶
- Ensure your instances are grouped across views
- Press T to triangulate the current frame
- Or use Edit → Group by Track & Triangulate All for batch processing
Step 2: Enable Error Visualization¶
- Press R to show reprojected instances (dashed outlines, white nodes)
- Press E to draw error vectors from each labeled node to its reprojection
- Both can be enabled simultaneously; turn on Display Legend in the Visibility tab for a key
Step 3: Interpret the Errors¶
Open the Instances tab in the info panel (I) to see detailed error information:
Mean error — the frame mean, shown next to the method used (DLT or Refined), and each group's mean in the Error column
| Error | Color | Action |
|---|---|---|
| < 2 px | Green | No action needed |
| 2–5 px | Amber | Review if possible |
| ≥ 5 px | Red | Needs correction |
Per-instance node breakdown — one node × camera table per instance, identifying specific problem keypoints
- A keypoint with 15px error while others are < 2px → that specific keypoint is likely mispositioned
- All keypoints with ~10px error → possible calibration issue or systematic misalignment
Per-camera error — Identifies which camera view has the problem
- One camera with 20px error, others < 2px → the annotation in that camera view needs fixing
Step 4: Fix Errors¶
For each flagged keypoint:
- Look at the reprojected position (dashed overlay) — this is where the 3D point projects
- Compare with your annotated position (solid node)
- If the reprojection looks more correct, drag your annotation toward it
- If neither looks right, check the annotation in all camera views
After fixing, re-triangulate (T) to see the updated error.
Systematic Proofreading Workflow¶
Frame-by-Frame Review¶
- Triangulate all frames first (click the toolbar Triangulate ▾ button)
- Navigate through frames with Right
- At each frame, check the
Error:readout in the status bar - Stop and fix frames with error ≥ 5 px
- Use Alt+Right to jump between user-labeled frames
Per-Keypoint Review¶
If a specific keypoint consistently has high error:
- Note which keypoint is problematic (e.g., "left_ankle")
- Go through labeled frames and verify that keypoint specifically
- Common issues:
- Left/right swap (fixing one view dramatically reduces error)
- Keypoint placed on the wrong joint
- Keypoint placed on clothing/fur instead of the actual joint
Cross-View Consistency Check¶
For each labeled frame:
- Select an instance in one camera view — its group is highlighted in the Instances tab and in the other views
- Verify all views show annotations on the same individual
- Check that keypoints correspond to the same anatomical landmarks
- Switch the toolbar Color toggle to ID to see identities at a glance
Using the 3D Viewport for Proofreading¶
The 3D viewport (\) gives you a spatial sanity check:
What to Look For¶
- Anatomically correct skeleton — Limbs should have reasonable lengths and angles
- Consistent bone lengths — The same bone shouldn't change length dramatically between frames
- No impossible poses — Limbs shouldn't pass through the body or have extreme joint angles
- Correct scale — The skeleton should be appropriately sized relative to the camera positions
Using the Environment Overlay¶
If your session folder includes environment annotations (.externals. files in each camera folder — arena corners, apparatus), click Set Env in the 3D viewport to triangulate and show them as a fixed reference, then check that the animal's skeleton sits plausibly inside it. Click Clear Env when done.
Common Error Patterns and Fixes¶
High Error on All Keypoints¶
Likely cause: Wrong instance grouping — instances from different individuals are linked.
Fix: Unlink the group (Shift+U), verify which instances belong to the same individual, re-group correctly.
High Error on One Specific Keypoint¶
Likely cause: Keypoint mispositioned in one or more views.
Fix: Check the per-camera error breakdown, fix the keypoint in the camera with the highest error.
High Error in One Camera Only¶
Likely cause: Annotation in that camera view is off.
Fix: Focus on that camera view, compare annotation positions with reprojected positions, adjust.
Error Increases Suddenly at a Frame¶
Likely cause: Identity swap — the tracker or annotator started following the wrong individual.
Fix: Go to the first wrong frame, select the animal, and press the correct identity number (1–9). The two identities are swapped from that frame to the end of the timeline. Or re-run Track Frame Range… over the affected span.
Proofreading Checklist¶
For a thorough proofread of your dataset:
- [ ] All frames triangulated
- [ ] No frames with RMS error > 5px
- [ ] No individual keypoints with error > 10px
- [ ] 3D skeletons look anatomically correct in the viewport
- [ ] Consistent bone lengths across frames
- [ ] No identity swaps (tracks are continuous in the timeline)
- [ ] Hidden keypoints are marked not visible (not guessed)
- [ ] All expected individuals are annotated in each frame
- [ ] Track assignments are consistent across all camera views