SynthClaw

Agent Rules & Guidelines (CRITICAL)

[!IMPORTANT] To ensure correct execution and environment compatibility, any agent ingesting this skill MUST adhere to the following rules:

1. Strictly Use Provided Tools: You MUST use the provided high-level python tools (render_procedural_scene, render_procedural_dataset, analyze_blend, analyze_dataset) for all Blender rendering and analysis tasks.
2. Prohibition of Custom Python Scripts: Do NOT write custom Python scripts that import bpy (Blender Python API) or write manual file-writing rendering loops. The environment does not support direct bpy imports outside of the provided headless context wrapper.
3. Prohibition of Direct CLI Calls: Do NOT execute raw blender commands directly in the shell (e.g. blender -b -P ...). Always use the designated tool calls.
4. Mandatory Discovery Phase: You MUST call analyze_blend first before attempting to render any .blend file. This is required to discover the exact names of the available Value Nodes, materials, objects, and collections in the scene.
5. Handling Heavy Scenes & Timeouts: For heavy scenes with complex compositing pipelines or large file sizes (e.g. over 200 MB), EEVEE may time out. If EEVEE runs exceed the 60-second limit, pass a custom, larger timeout argument to render_procedural_scene or run production Cycles rendering (which automatically configures Metal GPU on macOS and CUDA elsewhere).
6. Multi-Pass Compositing and Missing Composite Output Nodes: When rendering complex multi-pass blend files (like plaque_plate.blend) that utilize compositor File Output nodes but lack the standard Composite node:
   • The skill automatically detects the missing output node and dynamically creates/links a Composite fallback node (fully compatible with Blender 4.x and Blender 5.0+ group outputs) so that standard single-frame renders (render_procedural_scene) correctly write the fully fused image to the main output file rather than an empty base plate.
   • Relative output paths (e.g., ../output/masks/) configured in the compositor are automatically cleaned and routed under the target output_dir.

When to Use

• Generate synthetic training data with controlled parameter variations
• Create procedural image datasets with ground truth metadata
• Automate rendering workflows for ML training data
• When you need parameter-sweep renders without manual Blender interaction

When NOT to Use

• Real-time rendering or interactive preview needs (this is batch/offline)
• Complex scene manipulation beyond Value Node adjustments
• If Blender is not installed or unavailable in PATH

Requirements

• Blender 4.0+ / 5.0+ installed and available in $PATH (fully compatible with Blender 5.0+ compositor APIs)
• Python 3.10+ for the synthclaw package
• Cycles or EEVEE render engine (auto-selected, Cycles utilizes GPU acceleration natively via Metal on macOS and CUDA elsewhere)

Configuration

No additional configuration required. Ensure blender command is available:

blender --version

Tools

render_procedural_scene

Adjusts procedural Value Nodes and renders a frame in Blender.

Parameters:

• blend_file (string, required): Absolute path to the .blend file
• parameters (object, required): Key-value pairs of Value Node names and float values (e.g., {"GrainScale": 2.5, "Roughness": 0.3})
• output_path (string, required): Where to save the rendered image (e.g., /path/to/output.png)
• samples (integer, optional): Cycles samples (default: 128). Ignored for EEVEE.
• engine (string, optional): Render engine - "CYCLES" (default) or "EEVEE"
• timeout (integer, optional): Custom timeout in seconds. Defaults: 1800 for CYCLES, 60 for EEVEE.
• reference_image (string, optional): Complete path to a real-world reference image. Used for computing LPIPS similarity and Naturalness Delta.
• compute_metrics (boolean, optional): Set to true to compute Naturalness/LPIPS metrics after rendering. Default false.

Returns:

• On success: {"status": "success", "output": "/path/to/output.png", "log": "...", "engine": "CYCLES", "samples": 128, "metrics": {"naturalness_mean": 0.85, "lpips_alex": 0.12}}
• On error: {"status": "error", "message": "..."}

Examples:

Production quality (CYCLES):

{
  "blend_file": "/home/user/project/assets/test.blend",
  "output_path": "/home/user/output/render_01.png",
  "parameters": {
    "GrainScale": 3.0,
    "DisplacementStrength": 1.5
  },
  "engine": "CYCLES",
  "samples": 256
}

Fast testing (EEVEE):

{
  "blend_file": "/home/user/project/assets/test.blend",
  "output_path": "/home/user/output/test_render.png",
  "parameters": {
    "GrainScale": 3.0
  },
  "engine": "EEVEE"
}

render_procedural_scene_fast

Convenience function for fast EEVEE rendering. Same as render_procedural_scene with engine="EEVEE".

Parameters:

• blend_file (string, required): Absolute path to the .blend file
• parameters (object, required): Key-value pairs of Value Node names and float values
• output_path (string, required): Where to save the rendered image

render_procedural_scene_production

Convenience function for production Cycles rendering. Same as render_procedural_scene with engine="CYCLES" and higher samples.

Parameters:

• blend_file (string, required): Absolute path to the .blend file
• parameters (object, required): Key-value pairs of Value Node names and float values
• output_path (string, required): Where to save the rendered image
• samples (integer, optional): Cycles samples (default: 512)

render_procedural_dataset

Generates a procedural dataset from any .blend file by applying dynamic randomization rules frame-by-frame and routing compositor file outputs automatically.

[!NOTE] Compositor Path Preservation: The skill automatically detects and preserves any relative output paths configured in the .blend file's Compositor File Output nodes (e.g. images/, masks/well_masks/, or ../output/masks/plaque_masks/), stripping parent traversal prefixes and routing them cleanly under the user-defined output_dir.

Parameters:

• blend_file (string, required): Absolute path to the .blend file
• output_dir (string, required): Absolute path where generated images/masks will be saved
• num_images (integer, optional): Number of images to render (default: 2)
• randomizations (array of objects, optional): List of randomization rules.
  • Supported distributions: "uniform", "int_range", "boolean", "choice", and "sequence" (cycles through the provided list of range/choices frame-by-frame).
• engine (string, optional): "CYCLES" (default) or "EEVEE"
• samples (integer, optional): Cycles samples per frame (default: 128)

analyze_blend

Analyzes a .blend file and returns available Value Nodes that can be manipulated.

Parameters:

• blend_file (string, required): Absolute path to the .blend file

Returns: Dict containing:

• status (string): "success" or "error"
• parameters (object): Contains:
  • complexity (object): Scene realism evaluation (rating, score, polygon/light counts)
  • value_nodes (object): Available parameter node names, current values, and their assigned materials/node groups
  • collections (object): Hierarchical tree of scene collections and their direct object memberships
  • objects (object): Detailed dictionary of scene objects (type, location, rotation, scale, visibility in render, and assigned materials)
  • materials (object): Detailed dictionary of materials (use_nodes status, user count)
• blend_file (string): Path to the analyzed file

analyze_dataset

Computes dataset-wide diversity (Shannon entropy) and average Naturalness across a list of generated images. Together with Naturalness, Diversity allows iterative improvement of the synthetic data's usefulness.

Parameters:

• image_paths (array of strings, required): List of absolute paths to images in the dataset

Returns: Dict containing status, diversity (overall Shannon entropy across all images), naturalness_mean (average naturalness factor), and individual_metrics (per-image naturalness details).

Engine Comparison

Safety & Limitations

• Headless execution: Blender runs with -b flag for security
• Parameter validation: Only float values accepted; non-numeric input is rejected
• No shell injection: Uses subprocess.run(shell=False) with -- separator
• GPU Acceleration: Automatically configures Metal (Apple Silicon) or CUDA/OptiX GPU rendering for Cycles, fallback to CPU is automatic if no compatible GPU is active
• Timeout protection: Long renders are killed after timeout to prevent hanging

Files

Example Workflow (Metric-Guided Optimization)

1. User: "Render a realistic surface texture matching this real-world reference image"
2. Agent calls analyze_blend to see available parameters.
3. Agent renders a fast test image passing compute_metrics=true and a reference_image path.
4. Agent receives feedback metrics (e.g. lpips_alex similarity score and naturalness_mean).
5. Guided by these metric results, the agent iteratively adjusts parameters (e.g., grain scale, roughness) to optimize realism.
6. The agent performs a few iterations of this optimization loop until the metric values reach the desired threshold.
7. Agent calls render_procedural_scene_production (CYCLES) to render the final optimized output.

Version

Compatible with Blender 4.0+. Not backwards compatible with 2.7x.