Skip to main content
Glama
gchen19

AnkusDrive

by gchen19
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Render Photoreal

render_photoreal

Create photorealistic hero images of CAD parts and assemblies in presentation quality. Works with Blender or other renderers without modifying the live model.

Instructions

Photorealistic "hero image" of a part or a whole assembly — presentation quality, unlike render_view's fast software-rasterized preview.

Call render_capabilities first when unsure what is installed. renderer='auto' (default) uses Blender (Cycles, full install, run headless) when it resolves, otherwise POV-Ray (or another FreeCAD Render add-on renderer). Name one to force it: 'Blender' | 'Povray' | 'Luxcore' | 'Appleseed' | 'Cycles' (the stripped standalone build, not Blender) | 'Ospray' | 'Pbrt'. Renders never modify the live model.

What to render: handle (a part, or an assembly handle — every leaf part is rendered in place) or parts, a list of {handle, appearance?, name?} entries. Appearance per part: appearances maps an assembly's part names (as list_assembly_parts reports them) to an appearance; parts[].appearance sets it inline; material is the fallback for every unassigned part. An appearance is a card name ('Aluminium', 'Brass', 'Carpaint', 'Emission', 'Glass', 'GlossyPlastic', 'Gold', 'Iron', 'Matte', 'RoughPlastic', ...) or a neutral PBR dict {base?, color ('#rrggbb' or linear [r,g,b]), metallic, roughness, emission, emission_strength, transmission, ior, coat, finish ('none'|'fdm_layers'|'brushed'), layer_height_mm}. Unknown cards/fields raise listing the valid ones.

Blender-only (reported under ignored on an add-on renderer): per-part appearance, scene ('studio': seamless cyclorama, soft key/fill/rim area lights, contact shadows), quality ('draft' 16 | 'preview' 64 (default) | 'final' 384 samples, OIDN-denoised), device ('auto' GPU-if-present | 'cpu' | 'gpu'), and output_dir (where render.png + render.blend are written; default a temp dir). view: 'iso' | 'top' | 'bottom' | 'front' | 'back' | 'left' | 'right' | 'side'.

Returns {png_base64, png_path, renderer, auto_selected, view, material, width, height}. The Blender backend adds {blend_path, scene, quality, samples, denoised, device, blender_version, elapsed_s, parts: [{name, material, triangles}]}: open blend_path in Blender 5.1+ (optionally with Blender's own MCP server connected) to art-direct the scene further — AnkusDrive does not drive that server. When 'auto' falls back off Blender the result carries suggestion {renderer, why, install}: relay its install command to the user verbatim rather than installing anything. Not installed: Blender/'auto' return {ok: False, renderer, status, reason, install}; a named add-on renderer raises with install guidance.

Presentation-only: output is not bit-reproducible, so it is kept out of the reliability/golden tests. Renders can take seconds to minutes (extended worker timeout); prefer render_photoreal_submit for quality='final'.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
viewNoiso
partsNo
sceneNo
widthNo
deviceNo
handleNo
heightNo
qualityNo
materialNo
rendererNoauto
output_dirNo
appearancesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed11 schema fields changedv0.5.5
    • addedInput schema / properties / appearances
      Added value: +{
+  "anyOf": [
+    {
+      "additionalProperties": true,
+      "type": "object"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Appearances"
+}
    • addedInput schema / properties / device
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Device"
+}
    • addedInput schema / properties / handle / anyOf
      Added value: +[
+  {
+    "type": "string"
+  },
+  {
+    "type": "null"
+  }
+]
    • addedInput schema / properties / handle / default
      Added value: +null
    • removedInput schema / properties / handle / type
      Removed value: -"string"
    • addedInput schema / properties / output_dir
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Output Dir"
+}
    • addedInput schema / properties / parts
      Added value: +{
+  "anyOf": [
+    {
+      "items": {
+        "additionalProperties": true,
+        "type": "object"
+      },
+      "type": "array"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Parts"
+}
    • addedInput schema / properties / quality
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Quality"
+}
    • changedInput schema / properties / renderer / default
      Previous value: -"Povray"New value: +"auto"
    • addedInput schema / properties / scene
      Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "title": "Scene"
+}
    • removedInput schema / required
      Removed value: -[
-  "handle"
-]
  2. First observed

TDQS

A4.9/5.0
Behavior5/5

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

The annotations are minimal (readOnlyHint false, destructiveHint false), so the description carries the burden and fully delivers. It states 'Renders never modify the live model,' describes output file writing, renderer fallback, `ok: False` error shapes for missing installs, and that unknown appearance cards/fields 'raise listing the valid ones.' It also discloses that Blender-only features are reported under `ignored` on add-on renderers and that output is not bit-reproducible, which is rich behavioral context.

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 long but every paragraph is purposeful: purpose, renderer selection, scene-graph input, Blender-only options, return values, and caveats. It is front-loaded with the differentiator from render_view, and lists keep the enumerations scannable. Some minor redundancy exists (e.g., repeating renderer names in prose and list), but the complexity of a 12-parameter, multi-backend tool justifies the length.

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?

This tool has 12 parameters, eight renderers, backend-specific behavior, and no output schema, yet the description covers return shapes for all paths, error/raise behavior, file outputs, and non-reproducibility. The only minor gaps are explicit width/height semantics and what happens if both `handle` and `parts` are supplied, but the 'or' wording sufficiently implies exclusivity. For a tool this complex, the coverage is near-complete.

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?

With 0% schema description coverage, the description must compensate, and it does thoroughly: `handle` vs `parts` with field shapes, precedence among `appearances`/`parts[].appearance`/`material`, valid appearance card names and PBR dict keys, and the full `view`/`scene`/`quality`/`device`/`renderer` enum sets. Width/height are the only parameters not explicitly described, but they are trivially inferable as image dimensions.

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 opens with 'Photorealistic "hero image" of a part or a whole assembly — presentation quality, unlike render_view's fast software-rasterized preview.' This names a specific verb (render), the resource (part/assembly), and immediately distinguishes it from a sibling. An agent can clearly tell this from render_view, render_views, and render_photoreal_submit without opening any other schema.

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

Usage Guidelines5/5

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

It explicitly provides when-to-use guidance: 'Call render_capabilities first when unsure what is installed,' 'prefer render_photoreal_submit for quality="final",' and contrasts itself with render_view's 'fast software-rasterized preview.' It also explains renderer auto-selection fallback and tells the agent to relay install commands verbatim rather than install anything. This is concrete, actionable direction.

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

Deploy Server

Other Tools