Engineering Dynamics Company

CamMatch™

Camera Matching & Visualization for Blender

CamMatch™ — How-To Guide

A practical, step-by-step guide to solving a camera with CamMatch. It follows the add-on's panels in the order you actually use them and reflects the current UI.

CamMatch is built for fixed-focal-length footage — a camera whose lens does not zoom or change focus during the shot. You calibrate the lens once and that single calibration governs every solved frame. Zoom/variable-lens footage is supported as an advanced exception (see Lens type), but the whole workflow below assumes a fixed lens.

New to the add-on? Read Core concepts first — the rest of the guide assumes you know the difference between intrinsics and pose, and between a track and a 3D point.

• Where it lives: Movie Clip Editor > Sidebar/Tools region > CamMatch tab (with the clip in Tracking mode). Extra point tools live in 3D Viewport > Sidebar (N) > CamMatch.
• Dependency: OpenCV (cv2). Install it from Edit > Preferences > Add-ons > CamMatch if Blender can't import it, then restart Blender.

Table of contents

1. Core concepts
2. The panels at a glance
3. The full workflow
   • 1. Set up footage and 3D points
   • 2. Track features in the clip
   • 3. Link tracks to 3D objects
   • 4. Calibrate the lens (intrinsics)
   • 5. Solve the camera pose
   • 6. Solve a moving camera (multi-frame)
   • 7. Review and clean up errors
   • 8. Recalibrating: stale frames
   • 9. Pose uncertainty
   • 10. Diagnostics images
   • 11. Compositing and rendering
   • 12. Export reports
4. Track list legend (icons & colors)
5. Fixed lens vs variable lens — which to use
6. Tips for reliable solves
7. Troubleshooting

Core concepts

CamMatch answers one question: given 2D image points that you know the real 3D location of, where was the camera (and what lens did it have)? That's the PnP ("Perspective-n-Point") problem.

You supply two things and CamMatch matches them:

A link ties one track to one object. With enough good links on a frame, CamMatch can solve that frame.

Two things get solved, and it helps to keep them separate:

• Intrinsics (the lens): focal length, optical center, and lens distortion. These describe the camera/lens, not where it is. Solve them with Calibrate.
• Pose (the extrinsics): the camera's position and rotation in the scene. Solve it with Solve.

CamMatch's intended workflow is fixed-focal-length: the lens is assumed not to change during the shot, so you calibrate the lens once and then solve the camera's pose on every frame you need — the one calibration governs the entire shot. This keeps the lens well-constrained and every frame mutually consistent. Zoom/focus-pull footage (a variable lens) is the exception; see Lens type.

The panels at a glance

CamMatch is split into collapsible panels in the Clip Editor sidebar, top to bottom:

The 3D Viewport > Sidebar (N) > CamMatch tab has a small Quick Point Creation tool for placing control-point Empties by clicking in the viewport.

The full workflow

1. Set up footage and 3D points

1. Open the Movie Clip Editor and load your footage.
2. Bring your known 3D coordinates into the scene as objects (Empties are ideal). You can:
   • import surveyed points, or
   • place them by hand, or
   • drop them in the viewport with 3D Viewport > Sidebar > CamMatch > Quick Point Creation: name the point, optionally enable Continuous Placement, click Add Empty at Click, then click in the viewport — or position the 3D cursor first (Shift+Right-Click) and use Add Empty at 3D Cursor for exact placement.
3. Accuracy of these 3D points directly determines solve accuracy. Use real measurements wherever you can.

2. Track features in the clip

Use Blender's normal tracking tools to place a track on each image feature that corresponds to one of your 3D points. Each track needs a marker on every frame you intend to solve. Give tracks sensible names — matching names make linking automatic (next step).

3. Link tracks to 3D objects

Open Track & Links.

1. Click the Refresh button (⟳, top of the side button column) to populate the table from the clip.
2. Link tracks to objects using whichever is convenient:
   • By name/prefix: expand Auto-Link, Filter & Sort and set a Track Prefix / Object Prefix so matching names auto-link.
   • By hand: type/pick the object in each row's Object field.
   • By selection: select a track in the clip and its object in the viewport, then click the Link active track to active object button (target icon) in the side column.
3. Each row shows a checkbox (usage), the reprojection Err % with a colored status dot, the Track name, and the linked Object. See the legend for what the icons mean.

Handy filters (under Auto-Link, Filter & Sort):

• Unassigned — show only tracks with no object yet.
• Outside Critical — show only tracks whose error is over the critical threshold.
• Hide Disabled — hide tracks not used on the current frame (also toggles the Clip Editor's Show Disabled).
• Search box and sort mode (alphabetical or by error).

4. Calibrate the lens (intrinsics)

Skip this only if you already trust the lens values. Open Calibration.

1. Choose which parameters to solve (toggle buttons):
   • Focal — focal length.
   • Fix Aspect — keep fx = fy (leave on unless diagnosing pixel aspect).
   • Optical Center — solve the principal point (needs well-spread points).
2. Pick a distortion model and enable the coefficients to solve (K1/K2/K3, plus K4 and P1/P2 for Brown-Conrady).
3. Calibrate the fixed lens. Multi-Frame Calibration is the recommended path:
   • Multi-Frame Calibration (recommended): enable the toggle, enter two or more frames spread across the shot in Frames (e.g. 14, 28, 40-56, 89), and click Calibrate Multi-Frame. This solves one shared lens across all those views — exactly the fixed-lens assumption — and is far better conditioned than a single frame. On success it also turns Key Intrinsics off so the single calibration governs every solved frame.
   • Single frame (fallback): if you only have one good frame, go to a frame with many well-spread links and click Calibrate Camera. Prefer multi-frame whenever you can.
4. The panel shows the calibration status — e.g. Calibrated (multi-frame) @ 14, 28, 40-56 · stored @ Y (or (single-frame) @ frame X) — and the Status & Reprojection box reports the RMS error. Diagnostic images and the compositor undistort nodes are created automatically.
5. When you're happy, enable Lock Intrinsics to prevent accidental recalibration or reset. For a fixed lens this is the norm: calibrate once, then lock. (Locking only guards the Calibrate/Reset buttons — it never changes values you've already solved.)

Reset Intrinsics returns the lens to a sensible default (focal length scaled from the sensor width), available when intrinsics aren't locked.

5. Solve the camera pose

Open Solve Camera (or use the Solve button in Quick Actions).

1. Confirm the target camera in Quick Actions (the dropdown next to Auto-Create Camera). Leave Auto-Create Camera on to let CamMatch make one if needed. The button beside it selects the camera in the scene.
2. Pick the PnP function and method, or click Best Method to have CamMatch compare the available algorithms and automatically switch to the one with the lowest reprojection error.
   • Use RANSAC when some links might be wrong — it rejects outliers.
3. Set the acceptance gates (these apply to both single and multi-frame solves):
   • Min Points — minimum links required.
   • RANSAC % — inlier threshold as a percentage of the image diagonal (shown when RANSAC is active).
   • Min Inliers / Min Inlier Ratio — reject a frame that doesn't keep enough good points.
   • Reject Critical / Auto-Disable Critical — see error cleanup. Independent — use either, both, or neither.
   • Key Intrinsics — keyframe the lens on each solved frame. Leave off (the default) for the fixed-lens workflow so the one calibration governs every frame. Turn it on only for a zooming/variable lens.
4. Click Solve Camera Pose. The camera jumps into place, per-track errors populate the list, and diagnostics regenerate. The camera stays selected.

6. Solve a moving camera (multi-frame)

This solves the camera's pose on many frames — the camera moves through space, but the lens stays fixed (calibrated once in step 4). In Solve Camera, enable Solve Multi-Frame.

1. Choose Use Scene Range, or turn it off and type specific frames/ranges in Frames (e.g. 14, 28, 40-56, 89).
2. Options:
   • Force RANSAC — recommended; robustly rejects bad correspondences per frame.
   • Save Error Overlays — write a reprojection overlay image per accepted frame.
3. Click Solve Scene Range / Solve Multi-Frame. Each frame is solved and keyframed using the acceptance gates above; the status line reports how many frames were accepted, skipped, rejected, or failed.

Every solved frame gets pose keyframes (and, if Key Intrinsics is on, lens keyframes too). Frames that fail the gates are left un-keyed so they don't pollute the result.

7. Review and clean up errors

After any solve, Status & Reprojection shows the mean/worst error and inlier count, and the Track & Links rows show each track's error and status dot.

Tools for finding and fixing bad correspondences (Track & Links > Auto-Link, Filter & Sort):

• Warn % / Critical % — the thresholds that drive the yellow/red dots and the "Outside Critical" count.
• X (disable) button next to the thresholds — bulk-disables every outside-critical link so you can re-solve cleanly.
• Outside Critical filter — isolate the problem tracks.

Automatic per-frame cleanup (in Solve Camera):

• Auto-Disable Critical — before accepting a frame, CamMatch disables tracks whose error is above critical, re-solves, and keeps the cleaner result. If the whole-image mean error is still too high, the frame is rejected. Auto-disabled tracks are re-evaluated (re-enabled) automatically on the next solve, so fixing a track and re-solving brings it back.
• Reject Critical — reject a frame outright if a critical inlier remains.

Per-track manual control lives in the list:

• Click a row's checkbox/keyframe icon to toggle whether that track is used on the current frame (it writes a per-frame usage keyframe).
• Side buttons: Remove link (X), Delete marker on current frame (keyframe icon), and Enable all usage (checkbox icon — clears every per-frame usage key and re-enables all tracks).

Selecting a track in the list also selects its linked 3D point in the viewport and outliner (and vice-versa when you move a track in the clip), so you can quickly see which control point is misbehaving. Turn on Show Error Points in 3D (Quick Actions) to visualize error-colored points in the viewport.

8. Recalibrating: stale frames

Recalibration changes the lens, so any frame you already solved against the old lens is now geometrically inconsistent.

• When you recalibrate, CamMatch automatically marks any frames solved against the old lens as stale — no confirmation prompt.
• A banner then appears in Solve Camera with a one-click Re-solve Stale Frames button that re-solves exactly those frames with the new lens.
• Reports flag stale frames (a banner plus a ⚠️ marker on each stale row) so a mixed-lens reconstruction is never silent.
• A frame's stale flag clears automatically as soon as it's re-solved.

Multi-frame calibration turns Key Intrinsics off on success, so the single calibration governs every solved frame.

9. Pose uncertainty

CamMatch estimates how sensitive each solved pose is to noise, automatically, on every solve (Monte-Carlo perturbation). In Solve Camera:

• Uncertainty Samples — number of Monte-Carlo trials (default 1000).
• Auto Noise — derive the 2D noise from the solve's own RMS (recommended). Turn it off to set 2D Noise px manually.
• 3D Noise — optional survey/measurement uncertainty of your 3D points, in scene units.

Results (translation and rotation standard deviation and 95th percentile, per frame) appear in the exported reports.

10. Diagnostics images

Diagnostic images are created automatically after each calibration and solve. Open them from the Diagnostics panel:

• Heatmap — lens-distortion displacement magnitude across the frame.
• Calibration Errors — reprojection overlay from the last calibration.
• Solve Errors — reprojection overlay for the current frame's solve (markers + residual arrows over the plate).

The Diagnostics button in Quick Actions opens the current frame's overlays directly. Enable Verbose Logging (bottom of Diagnostics) for detailed console output when troubleshooting.

11. Compositing and rendering

• Compositor undistort nodes are created automatically when you calibrate (if they don't already exist), so the rendered pinhole camera lines up with an undistorted plate.
• Background Transparency (Quick Actions) sets the camera background image opacity for the viewport. Solving no longer resets it.
• Render Distortion Overscan (Quick Actions) — set a scale and click Apply for distortion-aware rendering that preserves edge content when you re-distort the render.

12. Export reports

Click Generate Reports (Quick Actions). Choose a folder and CamMatch writes one HTML file per report plus a combined AllReports file. Open any of them in a browser and use Print > Save as PDF for a PDF.

Reports include lens parameters, solve quality (per frame), track details, per-track-over-time, camera trajectory, pose uncertainty, a forensic summary, and a methodology section. Distances are reported in the active scene's length units. Frames whose camera pose keyframe was deleted are pruned automatically on export.

Track list legend (icons & colors)

Usage checkbox (left column):

Error status dot (Err % column):

The 🔘 dot next to a track name means it's currently selected/active in the Clip Editor.

Fixed lens vs variable lens — which to use

• Fixed lens (no zoom) — the intended workflow. This is what CamMatch is designed for. Calibrate once (ideally with Multi-Frame Calibration), keep Key Intrinsics off, then solve pose on your frames. One lens governs the whole shot. If you recalibrate later, use Re-solve Stale Frames to bring every solved frame onto the new lens. Use this unless you have a specific reason not to.
• Variable lens (zoom/focus pulls) — advanced exception. Only for footage whose lens genuinely changes during the shot. Turn Key Intrinsics on so each solved frame keyframes its own lens. Note this pins intrinsics per frame, so a later recalibration won't propagate to already-solved frames unless you re-solve, and results are less constrained than the fixed-lens path.

Calibration precedence, briefly: calibration always writes an intrinsic keyframe at its own frame (constant interpolation). With Key Intrinsics off, a solved frame holds the most recent calibration forward — so recalibrating and re-solving picks up the new lens. With it on, a solved frame owns its lens and won't inherit a later recalibration.

Tips for reliable solves

• Treat the shot as fixed-focal-length: calibrate the lens once (Multi-Frame Calibration), lock it, then solve pose everywhere.
• Use accurately surveyed 3D points — this is the single biggest accuracy factor.
• Spread points across the image and across depth; avoid nearly collinear or coplanar-only layouts.
• For Multi-Frame Calibration, pick frames spread across the shot with good, well-distributed links on each.
• Start with RANSAC when you're unsure about link quality, then review the outliers it flags.
• Keep track and object names consistent so auto-linking does the work.
• Use the reprojection overlays and per-track error % to hunt down bad control points, then disable or re-place them and solve again.
• Lock intrinsics after a trusted calibration and leave Key Intrinsics off.

Troubleshooting

If OpenCV still won't install

CamMatch tries the bundled offline copy first and then the internet automatically, and it works with the numpy that Blender already ships — so a Python-version mismatch (for example Blender 5.1 on Python 3.13) no longer blocks it. If it still can't install — an offline-only machine, or a corporate firewall blocking PyPI — install OpenCV into Blender's own Python by hand:

1. Close Blender completely.
2. Find Blender's bundled Python. It lives next to blender.exe — for example ...\Blender 5.1\5.1\python\bin\python.exe on Windows.
3. In a terminal, install the headless build (Blender already bundles numpy, so no extra pin is needed): "<path-to>\python.exe" -m pip install "opencv-python-headless<5"
4. Verify it imports: "<path-to>\python.exe" -c "import cv2; print(cv2.__version__)" should print a version number.
5. Reopen Blender, open CamMatch, and click Diagnostics — the warning should be gone.

If OpenCV imports in Blender's Python but CamMatch still reports it missing, disable and re-enable the CamMatch extension (or restart Blender once more) so its dependency check re-runs.

CamMatch™ is a trademark of Engineering Dynamics Company (Anthony Cornetto). The source code is GPL v3. CamMatch is a measurement/visualization aid, not a substitute for professional engineering judgment — independently validate every result. See NOTICE.md and README.md for licensing and the full disclaimer.