effectcraft/docs/blender-camera-export.md

Exporting a tracked camera to Blender

After the 3D Camera Tracker finishes solving, click Export Scene to Blender... in its Effect Controls and save the .py file. In Blender 4.0 or newer, open it in the Scripting workspace's Text Editor and choose Run Script. The script creates and activates a new scene; it preserves existing scenes and objects. Save the resulting .blend normally.

The script uses Blender's public Python API, with no add-on or Python dependencies beyond Blender itself. For unattended use: blender --background --python "Tracked Scene.py". That imports the scene in memory; it does not automatically save a .blend.

Transferred data

• Camera position and quaternion rotation baked on every analyzed frame, with consistent quaternion signs and linear interpolation; zoom/lens animation, including Variable Zoom.
• Tracking input/video resolution, horizontal sensor fit, exact rational composition FPS, frame range and composition markers within the analyzed interval. The first analyzed frame becomes Blender frame 1 by default; the original composition timestamps remain in metadata.
• The original video or still as the camera's background image, at full opacity, refreshed on frame changes. Source-frame offsets are baked too, accounting for trim, stretch, source FPS and Time Remap. This is a viewport background, not a render/compositor background.
• Focus distance, DOF switch, f-stop, iris blade count, rotation and aspect sampled from the tracker's linked 3D Tracker Camera, including keyframes and expressions. Create that camera and adjust its Camera Options before exporting to transfer custom focus settings.
• Solved 3D points as a non-rendering vertex mesh, with point attributes for track ID, reprojection error and first/last visible frame. A chosen ground plane becomes Blender's XY plane, with its origin preserved and a non-rendering wire plane as a placement guide.
• Shutter duration (not automatically enabled), plus the original shutter phase in metadata.
• A Blender Text datablock named EffectCraft Tracking Metadata.json containing the complete solve, optional original 2D tracks, per-frame timings, source interpretation, diagnostics and export warnings. Radial distortion coefficients are also camera custom properties.

Coordinates are converted from EffectCraft's right/down/forward world to Blender's right/forward/up world, including the camera's local up and negative-Z viewing direction. Export uses the tracking input's framing, not the footage layer's final 2D placement in the composition. Camera pose and lens always come from the solve; subsequent manual pose/lens edits on the linked camera are not substituted for the tracked motion.

What cannot be inferred

Monocular tracking cannot recover absolute scene scale, physical sensor size, optical focus, f-stop or exposure from feature tracks. The default sensor width is an assumption of 36 mm; the focal length in millimeters is derived from it while preserving the solved field of view. The default scale is 0.01 Blender units per composition-world pixel, not a measurement. Without a linked camera, DOF is disabled and focus distance uses the default solved scene depth. Blender's physical DOF approximates EffectCraft's blur model: Blur Level and Iris Roundness are retained in metadata, but have no direct Blender equivalent.

Brown-model radial k1/k2 coefficients use radius normalized to half the image diagonal. They are preserved, not assigned to Blender's different lens-distortion model. For a precise match when distortion is nonzero, use an undistorted plate; the script prints a warning. The tracker assumes square pixels, so Blender renders square pixels; any non-square source interpretation is retained in metadata and flagged.

The .py references the video; it does not contain a copy of the video's bytes. When moving it, keep the video next to the script (same filename), or relink the background image in Blender. Missing/unsupported media produces a warning while retaining the imported camera and geometry. Masks and effects applied before the tracker are not baked into the original media. Export requires a direct video/still footage layer at the analyzed size; render precomps, sequences or size-changing preprocessing to a video and track that video first.

Agent / control-channel command

{
  "command": "camera.exportBlender",
  "params": {
    "layer": "#1",
    "path": "/output/Tracked Scene.py",
    "sensorWidth": 36,
    "unitScale": 0.01,
    "startFrame": 1,
    "includePoints": true
  }
}

comp, layer and effect select the tracker as with camera.analyze. Without explicit selection, the selected tracker (or first tracker in the composition) is used. sensorWidth, unitScale, startFrame and includePoints are optional. The reply contains file size, exported frame/point counts and warnings. Writing uses the host's atomic file service. Calls issued by scripts require Allow Scripts to Write Files and Access Network in Settings ▸ Scripting & Expressions. Export from the UI or control channel remains available with that preference off.

Export is limited to 100,000 analyzed frames, 100,000 points and 64 MiB of serialized scene data; invalid, stale or incomplete solves return an actionable error without modifying the document.

Verification

Engine tests check argument validation, escaped/Unicode paths, fractional FPS, trim/stretch, focus/f-stop, zoom, ground placement, malformed solves and write failures. To additionally run the generated artifact against an installed Blender's public API:

EFFECTCRAFT_BLENDER=/path/to/blender cargo test -p effectcraft-engine tests::blender -- --nocapture

Optionally set EFFECTCRAFT_BLENDER_PLATE to a local synthetic 640×360 video to exercise media loading and source-frame offsets. The oracle checks every synthetic point's projection through the imported camera on every frame, as well as animation, DOF, timing and scene preservation.