#986: add Blender scene export for 3D Camera Tracker

docs/agents.md

@@ -446,7 +446,12 @@ and Origin), `camera.createFromSolve {kind: text|solid|null|shadowCatcher, point
 {center, normal, size?}, multiple?}` (Create Text / Solid / Null / Shadow Catcher, Camera and Light,
 Create Multiple …), `camera.deletePoints {points?, wait?}` (re-solves; with Auto-delete Points
 Across Time the same feature's other tracks go too) and `camera.create` (the Create Camera button).
-Each is one undo step; the first create adds the one-node "3D Tracker Camera" keyed on every frame.
+Each edit is one undo step; the first create adds the one-node "3D Tracker Camera" keyed on every frame.
+
+`camera.exportBlender {path: ".py", layer?, effect?, sensorWidth?: 36, unitScale?: 0.01,
+startFrame?: 1, includePoints?: true}` exports the solve as an executable Blender scene script:
+baked camera/lens/focus, synced video background, points and ground. See
+[Blender camera export](blender-camera-export.md) for framing, assumptions and limitations.
 Changing the layer's frames clears the analysis; changing `effects/#1/shotType`,
 `effects/#1/horizontalAngleOfView`, `effects/#1/advanced/solveMethod` re-solves the stored tracks.
 

docs/blender-camera-export.md

@@ -0,0 +1,101 @@
+# 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
+
+```json
+{
+  "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:
+
+```sh
+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.