Alignment & reconstruction failures
3D TaawnEngine segment reconstruction and TaawnEngine run alignment can fail when the video, camera, or trail conditions do not match what Taawn expects. Section timing may still work in some cases even when TaawnEngine 3D alignment fails.
This page lists common causes and how to avoid them. See also 3D features, Recording with GoPro, and Camera calibration.
Recording & camera issues
Obstructed view
Too much bike frame, handlebar, helmet, or body in the shot blocks the trail. Taawn needs a clear view of the path ahead to match frames and build a 3D trajectory.
Fix: Mount the camera higher and farther forward; angle it so the trail fills most of the frame. Avoid chest mounts that show your arms or bars across the center.
Dirt or water on the lens
Mud splatter, raindrops, or fingerprints blur and distort the image. Matching algorithms cannot find reliable visual features.
Fix: Clean the lens before every ride. Wipe it again after muddy sections if you stop to re-shoot.
Badly calibrated camera
3D TaawnEngine reconstruction and run alignment rely on accurate lens calibration (focal length, distortion). A wrong or missing calibration JSON produces misaligned overlays and failed alignment.
Fix: Re-run camera calibration with the ChArUco board, use the correct JSON for your GoPro model, and assign the camera in Garage before upload. See Camera calibration.
Upload & segment selection
Wrong segment selected
Uploading a run to a different segment than the trail you actually rode means frame matching cannot find correspondences — the scenery simply does not match the reference.
Fix: Confirm the segment name and map location before upload. Use search or the map to pick the correct trail section.
Not enough video before and after the segment
Your run file should include extra riding footage beyond the timed segment start and end. Alignment searches for visual matches in a window around the segment; if you cut the clip too tight, there is no context to lock onto.
Fix: When recording, start the GoPro before you enter the segment and stop after you exit. Do not trim the file so the segment fills the entire clip — leave several seconds (or more) of trail riding on both sides.
Riding style & trail conditions
Looking away from the trail
Glancing down at the bike, to the side, or behind you breaks the forward view Taawn expects. Short looks are usually fine; long stretches without trail in frame cause matching to fail.
Fix: Keep the camera pointed down the trail for the full segment and the padding before/after. Mount the camera so it does not tilt when you look around.
Vastly different trail conditions (seasonal change)
A reference recorded in summer with green foliage may not align to a winter run on snow, or after major trail rework. Appearance changes enough that visual matching struggles.
Work in progress
Taawn is actively improving alignment across changing seasons and conditions. For best results today, compare runs recorded under similar lighting, vegetation, and trail surface as the segment reference.
What happens when alignment fails
| Feature | TaawnEngine section match only | TaawnEngine 3D alignment |
|---|---|---|
| Section timings | Usually available | Available |
| Jump / shralp metrics | Not available | Available when 3D succeeds |
| AR ghost overlay | Limited or absent | Full trajectory overlay |
| Run detail badges | Timing badges may still show | All metric badges when eligible |
On run detail, a failed TaawnEngine 3D alignment shows a notice — you can still use section timings and report the issue if it seems wrong.
Quick checklist before upload
- Same GoPro settings as the segment reference (1080p, 25 FPS, Wide, Normal EIS)
- Clean lens, unobstructed forward view
- Correct segment selected
- Extra footage before segment start and after segment end
- Calibrated camera assigned (for 3D alignment)
- Trail conditions reasonably similar to the reference
Related pages
- Run detail — alignment status and comparison viewer
- Segment detail — trigger reconstruction
- Troubleshooting — upload errors and general FAQ