synthclaw

## 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+ installed and available in `$PATH`
- Python 3.10+ for the synthclaw package
- Cycles or EEVEE render engine (auto-selected)

## Configuration

No additional configuration required. Ensure `blender` command is available:

```bash
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):*
```json
{
  "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):*
```json
{
  "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)

### 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`, a `complexity` object evaluating scene realism, and `value_nodes` (available parameter names with current values).

## Engine Comparison

| Feature | CYCLES | EEVEE |
|---------|--------|-------|
| Quality | Photorealistic | Real-time |
| Speed | Slow (minutes) | Fast (seconds) |
| Timeout | 30 minutes | 1 minute |
| Use case | Production | Testing |
| Samples | Configurable | N/A |

## 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
- **CPU fallback:** Automatically uses CPU rendering for Cycles if no GPU available
- **Timeout protection:** Long renders are killed after timeout to prevent hanging

## Files

| File | Purpose |
|------|---------|
| `src/synthclaw/blender_skill.py` | OpenClaw execution wrapper with engine selection |
| `scripts/agent_bridge.py` | Blender-side Python script (handles both engines) |
| `scripts/analyze_blends.py` | Blender-side analysis script |
| `config/render_schema.json` | Tool schema for LLM function calling |
| `config/analyze_schema.json` | Schema for blend file analysis |

## Example Workflow

1. User: "Render with grain scale increased and surface rougher"
2. Agent calls `analyze_blend` to see available parameters
3. Agent calls `render_procedural_scene_fast` (EEVEE) for quick preview
4. If preview looks good, agent calls `render_procedural_scene_production` (CYCLES) for final output
5. Render completes, path returned to user

## Version

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