kernelCAD

Capture Animation

capture_animation

Use this when you need to render a script's animation timeline to a video, or a 360° turntable of a model for sharing. Capture a kernelCAD script's animationView({...}) timeline to an MP4 (ffmpeg) or a PNG frame sequence, verifying the sampled poses for part interference. FILE ONLY: pass { file } (a .kcad.ts path) — there is no { code } mode, because the capture engine renders from a file on disk (its relative lib.fromSTEP imports resolve against the script directory). MP4 by default; pass { frames_dir } to write frame-0000.png... and skip ffmpeg entirely (mutually exclusive with output_path). Animation-pose interference verification runs by default (keyframe times + segment midpoints) BEFORE any browser/ffmpeg cost; { no_verify: true } skips it and { verify_every: n } additionally samples every n-th frame time. Pass { focus } or { hide } (arrays of feature ids or assembly part names, mutually exclusive) to isolate parts in the rendered frames — same semantics as kernelcad render --focus/--hide; visibility is render-only and does NOT affect the pose verification. Collisions DO NOT fail the call — the artifact is still written as evidence with ok: true; read verified: false + the collisions[] array. TURNTABLE MODE: pass { turntable: true } for a seamless 360° orbit of the model (no animationView record needed) — a share-ready loop for a README, social post or product page. It uses the 'publish' studio look by default (same as render_preview preset: 'publish': key/fill/rim lights, soft contact shadow, clean backdrop, 30° lens, constant auto-framing over the whole orbit, light rig turns with the camera); { preset: 'default' } keeps the engineering look. Knobs: width/height (default 1080×1080, max 2048, even for MP4), duration_ms (one revolution, default 6000), fps (default 30), elevation_deg (default 22), background ('white' default, 'light', 'dark', 'black', '#rrggbb', or 'transparent' with frames_dir only), shadow (default true), environment. output_path ending in .gif writes a looping GIF; otherwise MP4. Frame i sits at az 30° + 360°·i/N (the 360° endpoint is excluded, so the loop is seamless). A turntable has no poses to verify: it reports verify_skipped: true. ENVIRONMENT: needs playwright chromium (npx playwright install chromium) and ffmpeg for MP4/GIF (frames_dir needs neither); the bundled static player is served automatically, no dev server required. Returns { ok, output_path, frame_count, duration_ms, fps, verified, verify_skipped?, collisions: [{ t_ms, a, b, volume_mm3 }], diagnostics }.

Input Schema

Name	Required	Description
`fps`	No	Override the animationView record's fps.
`file`	Yes	Path to a .kcad.ts script with an animationView({...}) record (any script in turntable mode). Required (no inline { code } mode). Hosted server: cannot read files from your machine — pass `code`, or `project:<slug>` for a saved project.
`hide`	No	Hide matching feature ids / assembly part names in the rendered frames. Mutually exclusive with focus. Render-only; does not affect pose verification.
`focus`	No	Show only matching feature ids / assembly part names in the rendered frames. Mutually exclusive with hide. Render-only; does not affect pose verification.
`width`	No	Turntable frame width in px (default 1080; even for MP4).
`height`	No	Turntable frame height in px (default 1080; even for MP4).
`preset`	No	Turntable look: 'publish' (default; studio product shot) or 'default' (engineering look).
`shadow`	No	Turntable + publish: soft contact shadow under the model (default true).
`no_verify`	No	Skip the animation-pose interference verification (default: verify on).
`turntable`	No	Seamless 360° orbit of the model instead of the animationView timeline.
`background`	No	Turntable + publish: 'white' (default), 'light', 'dark', 'black', '#rrggbb', or 'transparent' (frames_dir only — MP4/GIF have no usable alpha).
`frames_dir`	No	PNG-sequence mode directory: write frame-0000.png... and skip ffmpeg. Mutually exclusive with output_path.
`duration_ms`	No	Turntable: one full revolution in ms (default 6000).
`environment`	No	Turntable: HDRI environment override ('studio', 'softbox', 'neutral', 'outdoor', 'warehouse', a URL, or 'none').
`output_path`	No	MP4 output path (.gif → looping GIF); default <scriptDir>/<basename>-animation.mp4 (-turntable.mp4 in turntable mode). Mutually exclusive with frames_dir.
`verify_every`	No	Additionally verify at every n-th frame time of the fps schedule (unioned with the keyframe sample set).
`elevation_deg`	No	Turntable: camera elevation above the horizon in degrees (default 22).

Output Schema

Name	Required	Description	Default
No arguments

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedOct 11, 2026

removedOutput schema / properties

Removed value: -{
-  "collisions": {
-    "description": "Colliding poses { t_ms, a, b, volume_mm3 }.",
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "diagnostics": {
-    "items": {
-      "additionalProperties": true,
-      "type": "object"
-    },
-    "type": "array"
-  },
-  "duration_ms": {
-    "type": "number"
-  },
-  "error": {
-    "type": "string"
-  },
-  "errorCode": {
-    "type": "string"
-  },
-  "errorHint": {
-    "type": "string"
-  },
-  "failure_kind": {
-    "type": "string"
-  },
-  "fps": {
-    "type": "number"
-  },
-  "frame_count": {
-    "type": "number"
-  },
-  "ok": {
-    "type": "boolean"
-  },
-  "output_path": {
-    "description": "Written MP4 path (MP4 mode).",
-    "type": "string"
-  },
-  "verified": {
-    "description": "Whether pose-interference verification passed.",
-    "type": "boolean"
-  },
-  "verify_skipped": {
-    "type": "boolean"
-  }
-}

removedOutput schema / required

Removed value: -[
-  "ok",
-  "diagnostics"
-]

Changed11 schema fields changedSep 28, 2026

addedInput schema / properties / background

Added value: +{
+  "description": "Turntable + publish: 'white' (default), 'light', 'dark', 'black', '#rrggbb', or 'transparent' (frames_dir only — MP4/GIF have no usable alpha).",
+  "type": "string"
+}

addedInput schema / properties / duration_ms

Added value: +{
+  "description": "Turntable: one full revolution in ms (default 6000).",
+  "maximum": 60000,
+  "minimum": 500,
+  "type": "number"
+}

addedInput schema / properties / elevation_deg

Added value: +{
+  "description": "Turntable: camera elevation above the horizon in degrees (default 22).",
+  "maximum": 89,
+  "minimum": -89,
+  "type": "number"
+}

addedInput schema / properties / environment

Added value: +{
+  "description": "Turntable: HDRI environment override ('studio', 'softbox', 'neutral', 'outdoor', 'warehouse', a URL, or 'none').",
+  "type": "string"
+}

changedInput schema / properties / file / description

Previous value: -"Path to a .kcad.ts script with an animationView({...}) record. Required (no inline { code } mode). Hosted server: cannot read files from your machine — pass `code`, or `project:<slug>` for a saved project."New value: +"Path to a .kcad.ts script with an animationView({...}) record (any script in turntable mode). Required (no inline { code } mode). Hosted server: cannot read files from your machine — pass `code`, or `project:<slug>` for a saved project."

addedInput schema / properties / height

Added value: +{
+  "description": "Turntable frame height in px (default 1080; even for MP4).",
+  "maximum": 2048,
+  "minimum": 64,
+  "type": "integer"
+}

changedInput schema / properties / output_path / description

Previous value: -"MP4 output path; default <scriptDir>/<basename>-animation.mp4. Mutually exclusive with frames_dir."New value: +"MP4 output path (.gif → looping GIF); default <scriptDir>/<basename>-animation.mp4 (-turntable.mp4 in turntable mode). Mutually exclusive with frames_dir."

addedInput schema / properties / preset

Added value: +{
+  "description": "Turntable look: 'publish' (default; studio product shot) or 'default' (engineering look).",
+  "enum": [
+    "default",
+    "publish"
+  ],
+  "type": "string"
+}

addedInput schema / properties / shadow

Added value: +{
+  "description": "Turntable + publish: soft contact shadow under the model (default true).",
+  "type": "boolean"
+}

addedInput schema / properties / turntable

Added value: +{
+  "default": false,
+  "description": "Seamless 360° orbit of the model instead of the animationView timeline.",
+  "type": "boolean"
+}

addedInput schema / properties / width

Added value: +{
+  "description": "Turntable frame width in px (default 1080; even for MP4).",
+  "maximum": 2048,
+  "minimum": 64,
+  "type": "integer"
+}

Changed1 schema field changedSep 28, 2026

changedInput schema / properties / file / description

Previous value: -"Path to a .kcad.ts script with an animationView({...}) record. Required (no inline { code } mode)."New value: +"Path to a .kcad.ts script with an animationView({...}) record. Required (no inline { code } mode). Hosted server: cannot read files from your machine — pass `code`, or `project:<slug>` for a saved project."

Changed1 schema field changedJun 15, 2026

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "additionalProperties": true,
+  "properties": {
+    "collisions": {
+      "description": "Colliding poses { t_ms, a, b, volume_mm3 }.",
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "diagnostics": {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "duration_ms": {
+      "type": "number"
+    },
+    "error": {
+      "type": "string"
+    },
+    "errorCode": {
+      "type": "string"
+    },
+    "errorHint": {
+      "type": "string"
+    },
+    "failure_kind": {
+      "type": "string"
+    },
+    "fps": {
+      "type": "number"
+    },
+    "frame_count": {
+      "type": "number"
+    },
+    "ok": {
+      "type": "boolean"
+    },
+    "output_path": {
+      "description": "Written MP4 path (MP4 mode).",
+      "type": "string"
+    },
+    "verified": {
+      "description": "Whether pose-interference verification passed.",
+      "type": "boolean"
+    },
+    "verify_skipped": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "ok",
+    "diagnostics"
+  ],
+  "type": "object"
+}

AddedJun 8, 2026

TDQS

A4.7/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Beyond the sparse annotations, the description discloses critical behavior: verification runs before browser/ffmpeg cost, collisions do not fail the call and are reported via verified:false/collisions[], turntable reports verify_skipped, focus/hide are render-only, and environment prerequisites are playwright chromium plus ffmpeg. It also explains output defaults and file resolution behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is front-loaded and every section addresses a real mode or constraint, but it is a dense wall of text with several long compound sentences. Given the tool's complexity it is appropriately sized, though tighter formatting would improve scanability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex 17-parameter tool with both animation and turntable modes, the description covers prerequisites, mode selection, verification semantics, output formats, failure behavior, and return values. With a rich output schema also present, nothing important for correct invocation appears missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Although schema coverage is 100%, the description adds substantial meaning beyond field descriptions: it explains why file is required, how frames_dir changes output naming, that output_path ending in .gif changes format, turntable-specific knobs, mutual exclusivity, and how focus/hide differ from verification. This is more than a baseline restatement.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: render a script's animationView timeline to MP4/PNG or create a 360° turntable. It clearly distinguishes the two modes (file-only animation capture vs. turntable with no animationView record) and explains the FILE ONLY constraint.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It gives explicit when-to-use conditions (animation timeline to video or model turntable for sharing) and key exclusions (no inline { code } mode, frames_dir vs output_path, focus vs hide). It does not explicitly route the agent away from neighboring tools like render_preview or export, though it references the render_preview 'publish' preset.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All kernelCAD tools Inspect

Try in Browser

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Glama MCP Gateway

Add one secure layer between your agents and this server.