TTSP is a Blender extension that reconstructs a camera move from video. It produces a keyframed camera that matches the original shot, a colored point cloud of the filmed environment, and a dense mesh of the location for reflections, shadows and occlusion, for use in matchmoving and CG integration.
TTSP implements a structure-from-motion pipeline. Each solve passes through the same sequence:
All processing runs locally. Solving and geometry building run in a separate background process, so Blender remains fully responsive throughout, and a running job can be cancelled at any time.
To install: Edit ▸ Preferences ▸ Get Extensions ▸ Install from Disk…, select the downloaded ttsp-0.9.1.zip (as-is, do not unzip it), and confirm the extension is enabled in the Add-ons list. The panel appears in the 3D viewport sidebar (N) under the TTSP tab.
Each solved video receives a sidecar folder named <video>_TTSP next to the source file. It holds the extracted frames, baked masks, the solve database, the reconstruction, the geometry, and logs. Results are cached: re-importing a finished solve is immediate.
The TTSP tab holds six panels, in workflow order: Footage, Masking, Solve, Scene geometry, Scene import, and System.
Selects the input video and controls how it is sampled for analysis. When a video is chosen, an information readout shows resolution, frame rate, duration, file size, total frame count, the number of frames that will be analyzed, and an estimated tracking time. The last two update live as the settings change.
| Setting | Default | Description |
|---|---|---|
| Analyze every _ frames | 2 | Frequency of feature detection. A value of 2 analyzes every second frame. Use 1 for fast camera moves so consecutive frames still overlap; raise the value for long, slow shots. |
| Max frames analyzed | 300 | Maximum number of keyframes. For long videos, the detection frequency is lowered automatically to stay within this limit and keep solve times short. |
| Analysis resolution (px) | 1600 | Downscale size; the value is the long edge of the downscaled video used for analysis. Raise it only if tracking struggles on fine or distant detail. |
Collapsed by default. Holds the tools for hiding moving objects from the tracker; the workflow is described in §5. Masks from selects the source: Shapes to draw them here, or Matte video to supply your own.
| Control | Source | Description |
|---|---|---|
| Open mask editor | Shapes | Opens the video in a new window, in Blender's Movie Clip Editor set to Mask mode, with a mask named TTSP Mask <clip> ready to draw on. |
| Add box shape | Shapes | Adds a closed four-point polygon in the center of the frame. Drag its points over the moving object. |
| Clear masks (bin icon) | Shapes | Removes every shape drawn for this video. |
| Matte | Matte video | The black and white video to use. A readout below reports its resolution, frame rate and duration, and confirms that it lines up with the footage. |
| White is | Matte video | The moving objects treats white as what to ignore, which is what a roto or Magic Mask matte usually looks like. The area to track is the reverse. |
| Ignore masked areas | Both | On by default. Turn off to solve without masks while keeping the shapes or matte for later. |
A status line reports how many shapes are drawn, or whether the matte lines up. The Solve panel repeats this as Masking N shapes or Masking from your matte so it is visible at the moment you start a solve.
The Engine line reports which solver will run: the bundled solver (CPU) or a system COLMAP installation with GPU acceleration, if enabled in §4.7.
| Control | Description |
|---|---|
| Quality | Fast (global) solves all frames simultaneously and is the recommended default. Robust (incremental) registers frames one at a time; slower, but more tolerant of difficult footage (motion blur, sparse detail, abrupt moves). |
| Track and solve | Starts the solve in a background process. If masks are enabled and drawn, they are baked first (Blender is briefly busy while the frames render). The progress bar reports each stage; Cancel stops the run immediately. |
Progress stages, in order:
| Stage | Meaning |
|---|---|
| Extracting Frames | Sampled stills are pulled from the video. |
| Preparing Masks | Baked shapes or your matte video are matched to the extracted frames (only when masking is active). |
| Finding Features | Each frame is scanned for trackable detail. Reads (masked) when masks are in use. |
| Matching Features | Detail is matched across neighboring frames. |
| Solving Camera | Rotations, then positions, then refinement. |
| Saving Solve | The reconstruction is written to the sidecar folder. |
A new solve discards any geometry built from the previous one, since the mesh is fitted to that specific solve.
Builds a dense mesh of the location from a finished solve. The engine line reads AI depth + Poisson (CPU); no GPU is used. The workflow and what to expect from the result are described in §6.
| Control | Default | Description |
|---|---|---|
| Frames used | 40 | How many solved frames contribute depth, spread evenly across the solve. More frames cover more of the location and take proportionally longer. 40 is enough for most handheld shots; raise it for long walks through large spaces. |
| Detail | Normal | Low is quick and coarse, sufficient for shadow catching. Normal balances surface detail against mesh weight and suits reflections and occlusion. High produces the finest surface and the heaviest mesh. |
| Build geometry | Starts the build in the background. Available once a solve has finished. Progress reports the depth pass per frame, then fusing, then meshing; Cancel stops it. | |
| Import geometry | Appears once a mesh exists. Adds the mesh to a TTSP rig already in the scene, or replaces the mesh already imported. Use it after rebuilding at a different detail level. |
When a mesh exists, a status line reports its face count and how many frames it was built from.
| Option | Description |
|---|---|
| Keyframed camera | Creates a camera keyed on every solved frame, with focal length estimated from the solve. |
| Point cloud | Imports the reconstructed 3D points as a cloud of small dots, a sketch of the filmed environment for placing CG against. |
| Video as camera background | Displays the source footage behind the camera view and sets the render resolution to match the clip. |
| Scene geometry | Imports the dense mesh, when one has been built. Ignored otherwise. |
| Build scene | Imports the selected items into a new collection. A best-effort leveling is applied automatically on import. |
| Align Floor to Selected Points | Levels the scene from points you choose. Select the point cloud, enter Edit Mode (Tab), select three or more points on the ground (box-select works well), and click the button. The whole solve rotates so those points become the level floor at Z = 0, with their center at the origin. The mesh follows. |
| Open solve folder | Reveals the <video>_TTSP sidecar folder. |
Reports the state of TTSP's components. Solver, Frame extractor, Depth runtime and Depth network should all read Bundled. System COLMAP (turbo) indicates whether a separate COLMAP installation was detected. Re-scan re-checks after installing software.
Enabling Use system COLMAP routes solving through a separate COLMAP installation, which is substantially faster on NVIDIA GPUs. Masks are honored on this path as well. A manual path to a COLMAP executable can be set in the add-on preferences. Geometry building always uses the bundled engine.
The solver assumes the world is still and only the camera moves. A person walking through the frame, a passing car, or an actor in the shot breaks that assumption: detail tracked on them is explained as camera motion, and the solve drifts or fails. Masks tell the solver which regions to disregard.
Masks come from one of two sources, selected by Masks from at the top of the panel. Draw shapes inside Blender (§5.1), or supply a matte video you made elsewhere (§5.2). Either way the solver receives the same thing: one black and white image per analyzed frame, where black is ignored.
The mask window can be closed at any time; the shapes stay with the Blender file. Reopen it with the same button.
If you already roto in another application, or want a matte tighter than shapes can follow, set Masks from to Matte video and point the Matte field at the file. Anything that produces a black and white matte works: DaVinci Resolve's Magic Mask, After Effects roto brush, Nuke, or an AI segmentation export.
The matte has to describe the same shot, frame for frame:
White is sets which side is the moving object. Roto mattes usually paint the subject white, which is the default (The moving objects); choose The area to track for a matte built the other way round. The readout under the field reports the matte's resolution, frame rate and duration, and says Lines up with the footage when it is usable.
Shapes and a matte are stored independently, so switching the source back and forth keeps both.
With Ignore masked areas on, Track and solve prepares the masks before starting the background solve. Shapes are baked for every frame that will be analyzed: baking renders through the compositor at the clip's resolution and takes a few seconds for a typical clip, during which Blender is busy and shows progress in the cursor. A matte video needs no bake and is read directly by the background process. Baked shapes are stored in masks_baked/ inside the sidecar folder, and the solver-ready masks from either source in masks/.
Masked regions are excluded from feature detection only. The camera is still keyed on every frame, and the point cloud simply has no points where the object was. Geometry building (§6) reads the same masks, whichever source produced them, so a masked person never appears in the mesh.
The masked area is grown by a few pixels on the solver's side, so a matte that traces an object exactly still excludes the detail clinging to its edge.
The point cloud from a solve is sparse: a few thousand points where the tracker found detail. Many integration tasks need a continuous surface instead: a floor to catch a shadow, walls to reflect in a chrome object, buildings to occlude a character walking behind them. Scene geometry builds that surface.
On Apple Silicon, a 40-frame build at Normal detail takes well under a minute. The result is written to geometry/ in the sidecar folder as fused.ply (the point cloud) and meshed.ply (the surface).
The mesh is imported as TTSP Geometry <clip>, parented to the rig alongside the camera and points, with a material that displays the vertex colors. Because it is fitted to the solve, it lines up with the footage through the camera on every frame.
The mesh follows the rig: leveling with Align Floor, scaling, and re-orienting (§7) apply to it as well.
The surface is a proxy, not a survey scan. Flat and gently curved surfaces (floors, walls, roads, furniture) come out clean; thin structures (railings, poles, foliage) are approximated or dropped; sky and very distant background are excluded on purpose. The mesh covers what the camera saw from the frames used, so areas the camera never looked at have no surface. Raise Frames used for coverage and Detail for finer relief; lower both for a lighter mesh on long shots.
Build scene creates a collection named TTSP <clip> containing an empty, with the camera, point cloud and geometry parented to it. The empty is the master transform for the whole solve: rotating or scaling it moves everything together, keeping the parts registered to each other.
An automatic best-effort leveling is applied on import. If the result is not level (footage varies) use Align Floor to Selected Points (§4.5) to set the ground plane exactly from points you pick. Two properties still require judgment:
CG elements placed among the points will hold their position in the shot when viewed through the camera. Parent them to the empty if you expect to re-orient or re-scale the world afterward.
| Symptom | Cause and remedy |
|---|---|
| "No reconstruction produced" | The footage lacks parallax (camera rotated without traveling) or trackable texture. Reshoot with lateral movement, or try Robust quality. |
| Erratic camera path | Motion blur, insufficient frame overlap, or a moving object dominating the frame. Set "Analyze every _ frames" to 1, raise "Max frames analyzed", mask the moving object (§5), and try Robust quality. |
| Solve drifts when a person passes | Mask them. Make the shape generous and keyframe it through the whole pass, including the frames where they are partly out of frame. |
| "Mask bake failed" | The clip could not be rendered through the compositor. Confirm the video still plays in the mask editor window, then retry. The message includes the underlying cause. |
| "The matte covers N of the M analyzed frames" | The matte video is shorter than the footage. Re-export it over the full shot length. |
| "The matte is WxH, a different shape than the footage" | The matte's aspect ratio differs from the footage. Re-export at the footage's aspect ratio; the resolution itself does not have to match. |
| Solve ignores the wrong half of the frame | The matte's polarity is reversed. Flip White is in the Masking panel. |
| Build geometry is greyed out | It needs a finished solve for the selected video. Run Track and solve first. |
| "Could not fit depth to the solve on enough frames" | The solve has too few tracked points per frame for the fit. Solve again at a higher analysis resolution, or with "Analyze every _ frames" set to 1. |
| Mesh has holes or floating fragments | Coverage gaps where frames disagreed or the camera never looked. Raise Frames used; small fragments are removed automatically on import, larger ones can be deleted in Edit Mode. |
| "Poisson meshing failed" | Rebuild at a lower Detail level. |
| "Solve data missing on disk" | The solve predates the current TTSP version. Run Track and solve again for that video. |
| Only part of the clip solved | Expected on difficult footage; the camera is keyed only where solving succeeded. More texture and slower moves raise the solved fraction. |
| Panel missing after update | Confirm the extension is enabled: Edit ▸ Preferences ▸ Get Extensions ▸ Installed. Restart Blender after installing over an older version. |
| Other failures | The complete engine log is written to solve.log or geometry.log in the sidecar folder. |