Skip to main content
Glama

Render Photoreal

render_photoreal

Generate presentation-quality photorealistic hero images of parts or assemblies with configurable materials, views, and studio lighting for client-facing visuals instead of quick previews.

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'.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "render_photoreal"
  }
}

Input Schema

NameRequiredDescriptionDefault
viewNoiso
partsNo
sceneNo
widthNo
deviceNo
handleNo
heightNo
qualityNo
materialNo
rendererNoauto
workspaceNoRun this call in this named workspace
output_dirNo
appearancesNo

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed1 schema field changedv0.5.7
    • addedInput schema / properties / workspace
      Added value: +{
      +  "default": "",
      +  "description": "Run this call in this named workspace",
      +  "title": "Workspace",
      +  "type": "string"
      +}
  2. 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"
      -]
  3. First observed

TDQS

A4.9/5.0
Behavior5/5

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

Annotations (readOnly=false, destructive=false, openWorld=false) are corroborated: 'Renders never modify the live model' explains why it is non-destructive while still writing files. Beyond annotations it discloses timing risk (seconds to minutes, extended worker timeout), install/fallback behavior, the `suggestion` relay contract, non-reproducibility, and error return shapes.

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?

Purpose is front-loaded, then renderer selection, then what-to-render, then returns and caveats. Nearly every sentence adds operative detail, but the block is dense and sprawling; a shorter appearance-schema summary would read better. Length is justified by complexity, so only mildly penalized.

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?

Despite no output schema, the return dict is fully enumerated (png_base64, png_path, renderer, auto_selected, view, material, dimensions, plus Blender-only blend_path/parts/etc.). Error and fallback paths are covered, so an agent knows what to expect before calling.

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?

Schema coverage is only 8%, so the description must carry the load and it does: it enumerates renderer, view, scene, quality, device, output_dir, handle, parts, appearances, material and the appearance card/PBR dict format. Only width/height lack explicit prose, which is negligible against the 13-param surface.

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?

Opens with a specific verb+resource (photorealistic 'hero image' of a part or whole assembly) and immediately distinguishes it from render_view's fast software-rasterized preview and from render_photoreal_submit. An agent can route correctly without opening any 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?

Explicitly tells the agent to call render_capabilities first when unsure what is installed, explains renderer='auto' resolution order, states how to force a renderer, and directs to render_photoreal_submit for quality='final'. When-to-use, when-not, and alternatives are all present.

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