Settings

Personalize Elixihub behavior for this browser. Changes save automatically.

Preferences

Choose a section to manage your browser settings.

Stored in browser

Theme

Dark and light mode

Components per row Sets the component card density in the Components tab. Default assembly view Legend default state

Keyboard nudge distance (mm) Keyboard rotation step (degrees) Default explode amount Used when the exploded view opens.

AI Provider Locked by this deployment's configuration. Generation profile Quality keeps stronger models and larger responses. Balanced lowers cost for safer planning tasks. Cost saver pushes brief, spec, manifest, and component Q&A to smaller budgets. ElixiFree mode Strict: ElixiFree mandatory when supported (default). Hybrid: ElixiFree preferred, raw FreeCAD allowed inline for unsupported geometry. Off: raw FreeCAD only. Component generation Inference: the LLM writes each component script (default). Deterministic first: graph builders generate components where supported, falling back to inference with a warning.

Project chatbot Show the ask-about-your-project chat drawer on project pages (Ctrl+I). Chatbot AI provider Locked by this deployment's configuration. Chatbot daily message cap Hard stop per browser session per day (resets midnight UTC).

These preferences apply in this browser only. Account-level sync can come later.

Native

Static connection rules between woodworking components: panel-to-panel, shelf-to-side, back panel, and face frame interfaces.

~317 tokens

The Blender Rendering (Core) skill is always injected for every render. Add complementary skills below to guide style on top of it.

# Blender Rendering Skill **Default target: Blender 4.2+ with Cycles CPU renderer (fly.io server has no GPU). High-quality / demo renders on M1 MacBook: use Metal GPU + HDRI — see "High Quality Demo" section.** ## Quick Rules | ALWAYS | NEVER | |--------|-------| | **Generate code for the requested render_type ONLY** | ❌ Combining still + animation in one script (hangs for minutes) | | `bpy.context.scene.render.engine = 'CYCLES'` | ❌ `'BLENDER_EEVEE_NEXT'` or `'BLENDER_EEVEE'` (no GPU on this server — software fallback is 10x slower than Cycles CPU) | | **Server (default):** `scene.cycles.device = 'CPU'`, samples 64/32 | ❌ `scene.cycles.device = 'GPU'` on the fly.io server (no GPU) | | **M1 / high-quality demo:** call `enable_gpu(scene)` then `scene.cycles.samples = 256` + adaptive sampling + OIDN denoiser | ❌ High sample counts (256+) without the OIDN denoiser — wastes render time on CPU | | **M1 / high-quality demo:** use `setup_hdri_world(hdri_path)` for environment | ❌ Nishita sky for demo renders — procedural sky looks flat compared to HDRI | | **When `_HDRI_PATH` is set:** ground MUST be `ground.is_shadow_catcher = True`, size `size * 8` — HDRI provides the landscape; shadow catcher is invisible but receives shadows so model looks grounded | ❌ Textured/coloured ground plane with HDRI — creates a visible raised platform that breaks immersion; the HDRI background and the ground plane horizon never align | | **`scene.render.film_transparent = False`** always — if True, shadow catcher renders as solid black rectangle instead of showing HDRI through it | ❌ `film_transparent = True` with shadow catcher — produces black ground band in final video | | **When `_HDRI_PATH` is set:** add a large `AREA` fill light (DISK, `size * 3`, `energy = size * size * 0.8`, `use_shadow = False`) directly above the model — prevents fully-black walls when HDRI sun is behind the building during 360° orbit | ❌ HDRI-only lighting for orbit animations — half the orbit the building faces are in full shadow and render black | | **When `_HDRI_PATH` is set:** camera height MUST be `min_z + size * 0.35`, look_at target `min_z + size * 0.4` — eye-level view keeps shadow-catcher ground visible in frame so model looks grounded, not floating | ❌ `centre.z + size * 0.8` camera with HDRI — camera looks steeply down, ground plane off-frame, model hovers in mid-air | | `bpy.ops.wm.stl_import(filepath=path)` | ❌ `bpy.ops.import_mesh.stl()` (old API) | | `bpy.data.*` for object/material access | ❌ `scene.eevee.*` settings (wrong engine) | | `obj.keyframe_insert(data_path='...', frame=N)` — pass frame number directly | ❌ Face/vertex index assumptions on imported STL | | Set position THEN call `keyframe_insert(frame=N)` — never call `scene.frame_set()` inside keyframe loops | ❌ `bpy.ops.render.opengl()` (needs viewport) | | After every `render(animation=True)`, run `ffmpeg -movflags +faststart -c copy` to move moov atom to front | ❌ Skipping faststart — browsers cannot play the video without downloading the full file | | **Animations:** `1280×720`, 32 samples max, no OIDN denoiser — GPU renders 120 frames to RAM before flushing; 1080p + OIDN exhausts memory and crashes mid-render | ❌ `1920×1080` + `scene.cycles.samples = 64` + OIDN for animations — causes OOM crash, empty output file | | Clear the default scene before importing | ❌ Assume object names after STL import | | Use `_OUTPUT_DIR` for all render output paths | ❌ Hardcode `/output/dir/` paths | | Use `_COMPONENT_FILES` dict to get STL paths | ❌ Hardcode STL file paths | | **`dist = size * 3.5`** — model fills ~60% of frame | ❌ `size * 1.6` (too close) or `size * 5` (model tiny, flat) | | **`cam.data.clip_end = size * 20`** after every camera add | ❌ Leaving clip_end at default (100 units clips mm-scale models entirely) | | **`cam.data.lens = 85`** — architectural telephoto, less distortion | ❌ Default 50mm lens (too wide, distorts buildings) | | **No HDRI only:** Add **Sun lamp** (`type='SUN'`, energy 6.0) + Nishita sky for directional shadows | ❌ Sky-only lighting with no Sun lamp (flat, no shadows, looks fake) | | Always add a **ground plane** at `min_z` | ❌ No ground (model floats in void) | | Use **procedural wood/rubber** (`make_wood_material`, `make_rubber_material`) when prompt names surface materials | ❌ Flat `make_material()` for named textures (wood grain, rubber bumps invisible) | | Map texture → colour via **`ShaderNodeValToRGB`** (ColorRamp): connect wave `Fac` → ramp `Fac` → BSDF `Base Color` | ❌ Setting `Color1`/`Color2` defaults then connecting a texture to the same socket — the connection silently overrides the colour and renders gray | | Replace one still with a **material close-up** when prompt specifies surface materials | ❌ All 4 shots at same wide distance (can't see material texture) | | Camera Z: `size * 0.5` facade/side · **`size * 2.5` isometric** (shows flat roof at ~30°) · `size * 0.3` hero | ❌ `size * 0.8` for iso — only 10° down, flat roof invisible | | Sky `Strength = 0.25`, Sun `energy = 6.0` — high contrast defines edges and roof/wall boundaries | ❌ Sky `Strength = 1.0` (washes out all shadows, model looks flat) | | **Multi-STL `_COMPONENT_FILES`:** import EVERY key, per-group materials, `union_bounds` for centre/size/min_z | ❌ Importing only one entry, or single-`model` bbox math with multiple STLs (mis-framed camera, floating ground) | --- ## Injected Variables (always available) The executor injects these at the top of every script — use them, never hardcode paths: ```python # Injected by executor — do NOT redefine these # _OUTPUT_DIR : str — absolute path to write rendered files # _COMPONENT_FILES : dict — {"assembly": "/abs/model.stl"} (legacy single file) # OR per-group STLs: {"structure": ..., "finish": ..., # "roof_finish": ..., "fenestration": ...} # (only groups that exist are passed) # _HDRI_PATH : str | None — absolute path to the selected HDRI .exr, or None ``` **Always branch on `_HDRI_PATH`:** ```python if _HDRI_PATH: # Set up HDRI environment lighting world = bpy.context.scene.world world.use_nodes = True wt = world.node_tree for n in list(wt.nodes): wt.nodes.remove(n) coord = wt.nodes.new("ShaderNodeTexCoord") mapping = wt.nodes.new("ShaderNodeMapping") env_tex = wt.nodes.new("ShaderNodeTexEnvironment") bg = wt.nodes.new("ShaderNodeBackground") out_w = wt.nodes.new("ShaderNodeOutputWorld") env_tex.image = bpy.data.images.load(_HDRI_PATH) # Z rotation (yaw): point the bright part of the HDRI toward the camera side mapping.inputs["Rotation"].default_value[2] = math.radians(135.0) # X rotation (pitch): tilt HDRI horizon DOWN slightly so it aligns with the # shadow-catcher ground plane when camera is at eye level (~15° elevation). # Without this the HDRI horizon sits too high and the model still looks airborne. mapping.inputs["Rotation"].default_value[0] = math.radians(-8.0) bg.inputs["Strength"].default_value = 1.0 wt.links.new(coord.outputs["Generated"], mapping.inputs["Vector"]) wt.links.new(mapping.outputs["Vector"], env_tex.inputs["Vector"]) wt.links.new(env_tex.outputs["Color"], bg.inputs["Color"]) wt.links.new(bg.outputs["Background"], out_w.inputs["Surface"]) # CRITICAL: film_transparent MUST be False so the shadow catcher shows the # HDRI background through it instead of rendering as a solid black rectangle. bpy.context.scene.render.film_transparent = False # Shadow catcher ground — INVISIBLE, just receives shadows. # The HDRI landscape IS the background; a visible ground breaks the illusion. # Use size * 8 so the plane extends to the visible horizon at eye-level camera angles. bpy.ops.mesh.primitive_plane_add(size=size * 8, location=(centre.x, centre.y, min_z)) ground = bpy.context.active_object ground.name = "Ground" ground.is_shadow_catcher = True # Fill light: large soft dome above the model to prevent fully-black shadowed faces. # Essential for 360° orbit animations — the HDRI sun will be behind the building on # at least half the orbit, leaving walls nearly black without a fill. bpy.ops.object.light_add(type='AREA', location=(centre.x, centre.y, min_z + size * 2.5)) fill = bpy.context.active_object fill.name = "FillDome" fill.data.shape = 'DISK' fill.data.size = size * 3 # large disk = very soft, low-contrast fill fill.data.energy = size * size * 0.8 # scale with scene — mm-scale needs large values fill.data.use_shadow = False # fill light adds no shadows of its own else: # Nishita sky + Sun lamp (see World/Environment Lighting section) ... ``` To import a component STL: ```python import os stl_path = _COMPONENT_FILES["component_name"] # already absolute — use directly bpy.ops.wm.stl_import(filepath=stl_path) ``` --- ## Multi-Component Import (per-group STLs) Assembly projects may pass several STLs instead of one merged `assembly` file. Keys: `structure`, `finish`, `roof_finish`, `fenestration` — only groups that exist are passed. **Import every entry and compute framing from the union bounding box** — the single-object `model.bound_box` math in the templates below assumes ONE imported mesh and silently mis-frames multi-STL scenes. ```python import mathutils def import_components(): objs = {} for key, path in _COMPONENT_FILES.items(): for o in bpy.data.objects: o.select_set(False) bpy.ops.wm.stl_import(filepath=path) obj = bpy.context.selected_objects[0] obj.name = key objs[key] = obj return objs def union_bounds(objs): """centre (Vector), size (max dimension), min_z across ALL imported objects.""" pts = [obj.matrix_world @ mathutils.Vector(v) for obj in objs for v in obj.bound_box] xs = [p.x for p in pts]; ys = [p.y for p in pts]; zs = [p.z for p in pts] centre = mathutils.Vector(( (min(xs) + max(xs)) / 2, (min(ys) + max(ys)) / 2, (min(zs) + max(zs)) / 2, )) size = max(max(xs) - min(xs), max(ys) - min(ys), max(zs) - min(zs)) return centre, size, min(zs) components = import_components() centre, size, min_z = union_bounds(components.values()) dist = size * 3.5 ``` Use `centre` / `size` / `min_z` from `union_bounds` in every camera, ground plane, and fill-light formula in this skill wherever a template references the single `model` object's bounding box. ### Per-group materials | Key | Material | |-----|----------| | `structure` | wall cladding — `wood_planks_grey` (uv_scale 0.003) | | `finish` | its own cladding texture, distinct from structure (e.g. `weathered_brown_planks`) | | `roof_finish` | `corrugated_iron` (uv_scale 0.004) or procedural EPDM | | `fenestration` | painted frames: `make_material("Frames", (0.05, 0.05, 0.06), metallic=0.0, roughness=0.35)` | ⚠️ Fenestration solids are frame/sash/leaf geometry with NO separate glass — never assign a transmissive/glass material; render the units as solid painted frames. --- ## Scene Setup (always start here) ```python import bpy, math, os # Clear default scene for obj in bpy.data.objects: bpy.data.objects.remove(obj, do_unlink=True) for block in bpy.data.meshes: bpy.data.meshes.remove(block) ``` --- ## STL Import (Blender 4.x API) ```python # Import a single STL — store the reference immediately def import_stl(filepath, name): for obj in bpy.data.objects: obj.select_set(False) bpy.ops.wm.stl_import(filepath=filepath) obj = bpy.context.selected_objects[0] obj.name = name return obj ``` --- ## PBR Textures (`_TEXTURE_LIBRARY`) `_TEXTURE_LIBRARY` is injected into every script. It maps material id → `{color, normal, roughness}` file paths for all downloaded Poly Haven PBR materials. **Always prefer PBR textures over procedural shaders when a matching key is available.** ### `make_pbr_material` — standard function (copy into every script that uses textures) ```python def make_pbr_material(name, maps, uv_scale=1.0): """ Build a Principled BSDF material from a PBR maps dict. maps: {"color": path, "normal": path, "roughness": path} (all optional) uv_scale: tile the texture — for mm-scale FreeCAD models use ~0.001 to 0.005 so a 2K texture covers a realistic physical area rather than one giant tile. """ mat = bpy.data.materials.new(name=name) mat.use_nodes = True nt = mat.node_tree nt.nodes.clear() out = nt.nodes.new("ShaderNodeOutputMaterial") bsdf = nt.nodes.new("ShaderNodeBsdfPrincipled") coord = nt.nodes.new("ShaderNodeTexCoord") mapping = nt.nodes.new("ShaderNodeMapping") mapping.inputs["Scale"].default_value = (uv_scale, uv_scale, uv_scale) nt.links.new(coord.outputs["Object"], mapping.inputs["Vector"]) nt.links.new(bsdf.outputs["BSDF"], out.inputs["Surface"]) if "color" in maps: tex = nt.nodes.new("ShaderNodeTexImage") tex.image = bpy.data.images.load(maps["color"]) nt.links.new(mapping.outputs["Vector"], tex.inputs["Vector"]) nt.links.new(tex.outputs["Color"], bsdf.inputs["Base Color"]) if "normal" in maps: tex = nt.nodes.new("ShaderNodeTexImage") tex.image = bpy.data.images.load(maps["normal"]) tex.image.colorspace_settings.name = "Non-Color" nmap = nt.nodes.new("ShaderNodeNormalMap") nt.links.new(mapping.outputs["Vector"], tex.inputs["Vector"]) nt.links.new(tex.outputs["Color"], nmap.inputs["Color"]) nt.links.new(nmap.outputs["Normal"], bsdf.inputs["Normal"]) if "roughness" in maps: tex = nt.nodes.new("ShaderNodeTexImage") tex.image = bpy.data.images.load(maps["roughness"]) tex.image.colorspace_settings.name = "Non-Color" nt.links.new(mapping.outputs["Vector"], tex.inputs["Vector"]) nt.links.new(tex.outputs["Color"], bsdf.inputs["Roughness"]) return mat ``` ### UV scale guide for mm-scale FreeCAD models FreeCAD exports STL in millimetres. Blender treats those as metres, so textures tile at 1000× real scale without correction. Use `uv_scale` to restore physical plank/tile sizes: | Surface | Recommended `uv_scale` | Effect | |---------|----------------------|--------| | Timber cladding (150mm boards) | `0.003` | ~8 boards visible per metre | | Concrete wall/floor | `0.002` | Realistic aggregate grain size | | Grass ground plane | `0.001` | Dense blades, not giant blobs | | Corrugated metal (100mm pitch) | `0.004` | ~10 corrugations per metre | ### Usage example ```python # Assign grey timber cladding to the building walls if "wood_planks_grey" in _TEXTURE_LIBRARY: wall_mat = make_pbr_material("Cladding", _TEXTURE_LIBRARY["wood_planks_grey"], uv_scale=0.003) else: wall_mat = make_wood_material("Cladding") # fallback to procedural model.data.materials.clear() model.data.materials.append(wall_mat) # Ground — shadow catcher when HDRI is active, PBR material otherwise # ⚠️ NEVER assign a ground material when _HDRI_PATH is set — the HDRI IS the ground if _HDRI_PATH: ground.is_shadow_catcher = True # invisible; HDRI landscape shows through else: if "grass_path_2" in _TEXTURE_LIBRARY: ground_mat = make_pbr_material("Ground", _TEXTURE_LIBRARY["grass_path_2"], uv_scale=0.001) else: ground_mat = bpy.data.materials.new("GroundMat") ground_mat.use_nodes = True ground_mat.node_tree.nodes["Principled BSDF"].inputs["Base Color"].default_value = (0.3, 0.28, 0.22, 1.0) ground_mat.node_tree.nodes["Principled BSDF"].inputs["Roughness"].default_value = 0.9 ground.data.materials.append(ground_mat) ``` ### Available materials (as of current download) | Key | Visual | Best used for | |-----|--------|---------------| | `wood_planks_grey` | Grey weathered boards | SIP exterior wall cladding | | `weathered_brown_planks` | Warm brown planks | Decking, unfinished cladding | | `concrete_floor_02` | Smooth grey concrete | Foundations, slab, paths | | `grass_path_2` | Short lawn grass | Ground plane around buildings | | `corrugated_iron` | Galvanised metal sheets | Metal roofs, industrial cladding | | `metal_plate_02` | Brushed steel | Fascias, gutters, frames | ### Fallback rule Always check before use — a texture may not be downloaded on the current machine: ```python if "wood_planks_grey" in _TEXTURE_LIBRARY: mat = make_pbr_material("Cladding", _TEXTURE_LIBRARY["wood_planks_grey"], uv_scale=0.003) else: mat = make_wood_material("Cladding") ``` --- ## Materials ### Simple flat material (when no texture variation is needed) ```python def make_material(name, base_color, metallic=0.0, roughness=0.5): mat = bpy.data.materials.new(name=name) mat.use_nodes = True bsdf = mat.node_tree.nodes["Principled BSDF"] bsdf.inputs["Base Color"].default_value = (*base_color, 1.0) bsdf.inputs["Metallic"].default_value = metallic bsdf.inputs["Roughness"].default_value = roughness return mat ``` ### Procedural Wood (use for timber, cladding, decking) **⚠️ Critical node graph rule:** When you connect a texture output to a socket, it **overrides** any `default_value` you set on that socket. Never set a color default and then connect a texture to the same socket — the color will be silently ignored. Use a **ColorRamp** (`ShaderNodeValToRGB`) to map the grayscale wave output to actual wood colors. This is the only reliable pattern. ```python def make_wood_material(name, dark_color=(0.15, 0.08, 0.02), light_color=(0.55, 0.32, 0.10)): mat = bpy.data.materials.new(name=name) mat.use_nodes = True nt = mat.node_tree for n in nt.nodes: nt.nodes.remove(n) out = nt.nodes.new("ShaderNodeOutputMaterial") bsdf = nt.nodes.new("ShaderNodeBsdfPrincipled") ramp = nt.nodes.new("ShaderNodeValToRGB") # maps 0-1 float → colour wave = nt.nodes.new("ShaderNodeTexWave") noise = nt.nodes.new("ShaderNodeTexNoise") # distorts the wave for realism coord = nt.nodes.new("ShaderNodeTexCoord") # BANDS along Z = horizontal cladding boards visible from the side wave.wave_type = 'BANDS' wave.bands_direction = 'Z' wave.inputs["Scale"].default_value = 30.0 # ~30 visible boards across model height wave.inputs["Distortion"].default_value = 2.0 wave.inputs["Detail"].default_value = 4.0 wave.inputs["Detail Scale"].default_value = 2.0 noise.inputs["Scale"].default_value = 8.0 # large-scale grain variation noise.inputs["Detail"].default_value = 4.0 noise.inputs["Roughness"].default_value = 0.6 # ColorRamp: wave Fac (0-1) → dark to light wood colour ramp.color_ramp.interpolation = 'LINEAR' ramp.color_ramp.elements[0].position = 0.0 ramp.color_ramp.elements[0].color = (*dark_color, 1.0) ramp.color_ramp.elements[1].position = 1.0 ramp.color_ramp.elements[1].color = (*light_color, 1.0) bsdf.inputs["Roughness"].default_value = 0.75 nt.links.new(coord.outputs["Object"], noise.inputs["Vector"]) nt.links.new(noise.outputs["Fac"], wave.inputs["Vector"]) # noise distorts wave coords nt.links.new(wave.outputs["Fac"], ramp.inputs["Fac"]) # wave float → colour ramp nt.links.new(ramp.outputs["Color"], bsdf.inputs["Base Color"]) nt.links.new(bsdf.outputs["BSDF"], out.inputs["Surface"]) return mat ``` ### Procedural Rubber / EPDM (use for flat roofs, membranes) ```python def make_rubber_material(name, base_color=(0.03, 0.03, 0.03)): mat = bpy.data.materials.new(name=name) mat.use_nodes = True nt = mat.node_tree for n in nt.nodes: nt.nodes.remove(n) out = nt.nodes.new("ShaderNodeOutputMaterial") bsdf = nt.nodes.new("ShaderNodeBsdfPrincipled") noise = nt.nodes.new("ShaderNodeTexNoise") bump = nt.nodes.new("ShaderNodeBump") coord = nt.nodes.new("ShaderNodeTexCoord") bsdf.inputs["Base Color"].default_value = (*base_color, 1.0) bsdf.inputs["Roughness"].default_value = 0.95 bsdf.inputs["Specular IOR Level"].default_value = 0.02 noise.inputs["Scale"].default_value = 50.0 # object-space scale, visible surface texture noise.inputs["Detail"].default_value = 6.0 noise.inputs["Roughness"].default_value = 0.7 bump.inputs["Strength"].default_value = 0.2 nt.links.new(coord.outputs["Object"], noise.inputs["Vector"]) nt.links.new(noise.outputs["Fac"], bump.inputs["Height"]) nt.links.new(bump.outputs["Normal"], bsdf.inputs["Normal"]) nt.links.new(bsdf.outputs["BSDF"], out.inputs["Surface"]) return mat ``` ### Common flat materials ```python aluminium = make_material("Aluminium", (0.8, 0.8, 0.82), metallic=0.9, roughness=0.2) painted_steel= make_material("PaintedSteel",(1.0, 1.0, 1.0), metallic=0.0, roughness=0.6) concrete = make_material("Concrete", (0.55, 0.53, 0.50), metallic=0.0, roughness=0.95) ``` Exact Principled BSDF input names (4.2+): `"Base Color"`, `"Metallic"`, `"Roughness"`, `"Specular IOR Level"`, `"Emission Color"`, `"Alpha"`, `"IOR"`, `"Subsurface Weight"`. ## Material Detail Shot When the prompt specifies surface materials (wood, rubber, brick, etc.), replace one of the 4 still angles with a **material close-up** that shows the texture clearly. Aim the camera at a representative wall section from ~`size * 1.0` distance at eye height. ```python # Material detail shot — close-up of the main wall surface at eye height eye_z = min_z + size * 0.4 # ~40% up the model height render_at((cx, cy - size * 1.0, eye_z), "detail.jpg") # replaces hero.jpg ``` This gives the viewer one image that clearly shows what the materials look like up close, alongside the wider architectural shots. --- ## World / Environment Lighting Always use Nishita sky + an explicit Sun lamp. Sky alone produces flat, shadowless renders. ```python # Nishita sky (clear blue sky, midday sun) world = bpy.context.scene.world world.use_nodes = True wt = world.node_tree for n in wt.nodes: wt.nodes.remove(n) bg = wt.nodes.new("ShaderNodeBackground") sky = wt.nodes.new("ShaderNodeTexSky") out = wt.nodes.new("ShaderNodeOutputWorld") sky.sky_type = 'NISHITA' sky.sun_elevation = math.radians(55) sky.sun_rotation = math.radians(45) sky.altitude = 0.1 bg.inputs["Strength"].default_value = 0.25 # LOW ambient — let the sun create contrast wt.links.new(sky.outputs["Color"], bg.inputs["Color"]) wt.links.new(bg.outputs["Background"], out.inputs["Surface"]) # Sun lamp — high energy so shadows define edges and roof/wall contrast is clear bpy.ops.object.light_add(type='SUN', location=(0, 0, 0)) sun = bpy.context.active_object sun.data.energy = 6.0 # strong directional light sun.data.angle = math.radians(0.5) sun.rotation_euler = (math.radians(55), 0, math.radians(-45)) ``` ## Ground Plane Always add a ground plane. The treatment depends entirely on whether HDRI is active: - **HDRI active (`_HDRI_PATH` is set):** shadow catcher only — the HDRI provides the landscape, a visible ground breaks it - **No HDRI:** visible plane with a material ```python min_z = min((model.matrix_world @ mathutils.Vector(v)).z for v in model.bound_box) bpy.ops.mesh.primitive_plane_add(size=size * 4, location=(centre.x, centre.y, min_z)) ground = bpy.context.active_object ground.name = "Ground" if _HDRI_PATH: # Shadow catcher: receives shadows from the model, HDRI landscape shows through # Do NOT assign any material — shadow catcher needs no material ground.is_shadow_catcher = True else: gmat = bpy.data.materials.new("GroundMat") gmat.use_nodes = True gbsdf = gmat.node_tree.nodes["Principled BSDF"] gbsdf.inputs["Base Color"].default_value = (0.35, 0.38, 0.30, 1.0) gbsdf.inputs["Roughness"].default_value = 0.9 ground.data.materials.append(gmat) ``` --- ## Camera Setup **Always use `look_at` to point the camera — never compute rotation angles manually.** **⚠️ FreeCAD STL exports are in millimetres.** Blender's default camera `clip_end` is 100 units. For mm-scale models (3000 mm garden room, etc.) the model sits thousands of units away — completely clipped. **Always set `clip_end` to at least `size * 20`** after creating the camera. ```python from mathutils import Vector def look_at(cam, target): """Point cam's -Z axis at target (world coords). Works reliably in headless mode.""" direction = Vector(target) - cam.location rot_quat = direction.to_track_quat('-Z', 'Y') cam.rotation_euler = rot_quat.to_euler() # Add camera, position it, then aim it at the model centre bpy.ops.object.camera_add() cam = bpy.context.active_object bpy.context.scene.camera = cam # CRITICAL: expand clip range for mm-scale models (FreeCAD exports in mm) cam.data.clip_end = size * 20 # size is max(obj.dimensions) in Blender units # Example: place camera and point it at model centre cam.location = (centre.x + dist, centre.y - dist, centre.z + dist * 0.5) look_at(cam, centre) # centre = world-space bounding box centre ``` **Compute the model bounding box centre and set up camera:** (Single legacy `assembly` STL only — with per-group STLs use `centre, size, min_z = union_bounds(components.values())` from the Multi-Component Import section instead of the `obj.bound_box` math below.) ```python import mathutils obj = bpy.context.active_object # your imported mesh local_bbox = [mathutils.Vector(v) for v in obj.bound_box] cx = sum(v.x for v in local_bbox) / 8 cy = sum(v.y for v in local_bbox) / 8 cz = sum(v.z for v in local_bbox) / 8 centre = obj.matrix_world @ mathutils.Vector((cx, cy, cz)) size = max(obj.dimensions) dist = size * 3.5 # building fills ~60% of frame; not so far it looks tiny bpy.ops.object.camera_add() cam = bpy.context.active_object bpy.context.scene.camera = cam cam.data.clip_end = size * 20 # ← critical for mm-scale FreeCAD models cam.data.lens = 85 # 85mm telephoto: less distortion, more architectural cam.location = (centre.x + dist, centre.y - dist, min_z + size * 0.35) look_at(cam, Vector(centre.x, centre.y, min_z + size * 0.4)) ``` **Camera height guidance for architectural shots (HDRI grounding rule):** - **Eye-level (default for HDRI renders):** `min_z + size * 0.35` pointing at `min_z + size * 0.4` — camera ~35% up the building height, nearly level with the structure. The shadow-catcher ground plane fills the lower 20% of the frame, anchoring the model to the HDRI landscape. This is the correct height for all HDRI renders. - Front/side views: `min_z + size * 0.35` — shows facade and visible ground - Isometric: `min_z + size * 0.8` — elevated enough to see roof and both sides (only for non-HDRI stills) - Hero: `min_z + size * 0.2` — low, dramatic, above ground but below roofline - **NEVER** use `centre.z + size * 0.8` for HDRI renders — camera is too high, ground plane disappears off bottom of frame, model hovers in mid-air --- ## Cycles CPU Render Settings (Blender 4.2+) ```python scene = bpy.context.scene scene.render.engine = 'CYCLES' scene.cycles.device = 'CPU' scene.cycles.samples = 64 # 64 for stills; 32 for animation frames # Resolution scene.render.resolution_x = 1920 scene.render.resolution_y = 1080 scene.render.resolution_percentage = 100 # Output — always use _OUTPUT_DIR scene.render.image_settings.file_format = 'JPEG' scene.render.image_settings.quality = 95 scene.render.filepath = os.path.join(_OUTPUT_DIR, "image.jpg") # Render single frame bpy.ops.render.render(write_still=True) ``` --- ## ⚠️ Render Type — Output EXACTLY What Was Requested The render type is specified in the prompt header. **Generate code for that type only.** | Render type | Files to produce | Do NOT produce | |-------------|-----------------|----------------| | `isometric` | `isometric.jpg` | ❌ Any MP4 / animation or extra stills | | `still` | `front.jpg`, `side.jpg`, `isometric.jpg`, `detail.jpg` | ❌ Any MP4 / animation | | `turntable` | `turntable.mp4` | ❌ Stills or other animations | | `camera_orbit` | `orbit.mp4` | ❌ Stills or other animations | | `assembly_flyin` | `flyin.mp4` | ❌ Stills or other animations | Never combine types. A `still` or `isometric` request must never call `bpy.ops.render.render(animation=True)`. --- ## Single Isometric Render (render_type = isometric) One shot from a high isometric angle — fastest render, ideal for proof-of-concept. ```python scene = bpy.context.scene scene.render.engine = 'CYCLES' scene.cycles.device = 'CPU' scene.cycles.samples = 64 scene.render.resolution_x = 1920 scene.render.resolution_y = 1080 scene.render.image_settings.file_format = 'JPEG' scene.render.image_settings.quality = 95 bpy.ops.object.camera_add() cam = bpy.context.active_object scene.camera = cam cam.data.clip_end = size * 20 cam.data.lens = 85 cx, cy, cz = centre.x, centre.y, centre.z cam.location = (cx + dist, cy - dist, cz + size * 2.5) # HIGH: ~30° down so flat roof is visible look_at(cam, centre) scene.render.filepath = os.path.join(_OUTPUT_DIR, "isometric.jpg") bpy.ops.render.render(write_still=True) ``` --- ## Still Renders (render_type = still) ```python # Per-group STLs: centre/size/min_z/dist come from union_bounds(components.values()) # — do NOT recompute them from a single model object. scene = bpy.context.scene scene.render.engine = 'CYCLES' scene.cycles.device = 'CPU' scene.cycles.samples = 64 scene.render.resolution_x = 1920 scene.render.resolution_y = 1080 scene.render.image_settings.file_format = 'JPEG' scene.render.image_settings.quality = 95 bpy.ops.object.camera_add() cam = bpy.context.active_object scene.camera = cam cam.data.clip_end = size * 20 cam.data.lens = 85 def render_at(location, filename): cam.location = location look_at(cam, centre) scene.render.filepath = os.path.join(_OUTPUT_DIR, filename) bpy.ops.render.render(write_still=True) # write_still=True, NOT animation=True cx, cy, cz = centre.x, centre.y, centre.z min_z = min((model.matrix_world @ mathutils.Vector(v)).z for v in model.bound_box) eye_z = min_z + size * 0.4 render_at((cx, cy - dist, cz + size * 0.5), "front.jpg") # facade at mid-height render_at((cx + dist, cy, cz + size * 0.5), "side.jpg") # side elevation render_at((cx + dist, cy - dist, cz + size * 2.5), "isometric.jpg") # HIGH: ~30° down so flat roof is clearly visible render_at((cx, cy - size, eye_z), "detail.jpg") # material close-up ``` --- ## Turntable Animation (render_type = turntable only) **⚠️ Never rotate the model.** FreeCAD models have their origin at a corner, not the centre. Rotating the model pivots around that corner — the building swings out of frame and the video is mostly blank sky. **Always orbit the camera** around the bounding-box centre instead. ```python # Per-group STLs: centre/size/min_z/dist come from union_bounds(components.values()) # — do NOT recompute them from a single model object. scene = bpy.context.scene scene.render.engine = 'CYCLES' enable_gpu(scene) scene.cycles.samples = 32 # keep low — GPU renders to RAM before flush scene.cycles.use_denoising = False # OIDN adds significant RAM pressure on animations scene.render.resolution_x = 1280 # 720p for animations — 1080p causes OOM on 120 frames scene.render.resolution_y = 720 scene.render.image_settings.file_format = 'FFMPEG' scene.render.ffmpeg.format = 'MPEG4' scene.render.ffmpeg.codec = 'H264' scene.render.ffmpeg.constant_rate_factor = 'MEDIUM' scene.render.fps = 24 scene.frame_start = 1 # Duration: derive from prompt if the user specifies (e.g. "15 second turntable"). # Default is 15 s = 360 frames. Adjust DURATION_S to match prompt. DURATION_S = 15 # ← change this if prompt specifies a different duration TOTAL_FRAMES = DURATION_S * 24 scene.frame_end = TOTAL_FRAMES bpy.ops.object.camera_add() cam = bpy.context.active_object scene.camera = cam cam.data.clip_end = size * 20 cam.data.lens = 85 # Orbit camera 360° around the bounding-box centre at a fixed elevation radius = dist # same dist used for stills # ⚠️ Do NOT call scene.frame_set() inside this loop — it re-evaluates animation curves # and overwrites the location we just set, causing all frames to bake the same position. # keyframe_insert(frame=N) stores the current value at frame N without needing frame_set. # Eye-level height: ~35% up the building so the shadow-catcher ground plane # is visible in the bottom of the frame and the model looks grounded. # look_at target is ~40% up (slightly above camera height) for a natural tilt. eye_height = min_z + size * 0.35 look_target = Vector(centre.x, centre.y, min_z + size * 0.4) deg_per_frame = 360.0 / TOTAL_FRAMES # one full rotation over the whole clip for frame in range(1, TOTAL_FRAMES + 2): angle = math.radians((frame - 1) * deg_per_frame) cam.location = ( centre.x + radius * math.sin(angle), centre.y - radius * math.cos(angle), eye_height, ) look_at(cam, look_target) cam.keyframe_insert(data_path='location', frame=frame) cam.keyframe_insert(data_path='rotation_euler', frame=frame) scene.render.filepath = os.path.join(_OUTPUT_DIR, "turntable.mp4") bpy.ops.render.render(animation=True) # Move moov atom to front so browsers can play without downloading the full file import subprocess _mp4 = os.path.join(_OUTPUT_DIR, "turntable.mp4") _tmp = _mp4 + ".tmp.mp4" subprocess.run(["ffmpeg", "-i", _mp4, "-movflags", "+faststart", "-c", "copy", _tmp, "-y"], capture_output=True) os.replace(_tmp, _mp4) ``` --- ## Camera Orbit Animation (render_type = camera_orbit only) ```python # Per-group STLs: centre/size/min_z/dist come from union_bounds(components.values()) # — do NOT recompute them from a single model object. scene = bpy.context.scene scene.render.engine = 'CYCLES' enable_gpu(scene) scene.cycles.samples = 32 # keep low — GPU renders to RAM before flush scene.cycles.use_denoising = False # OIDN adds significant RAM pressure on animations scene.render.resolution_x = 1280 # 720p for animations — 1080p causes OOM on 120 frames scene.render.resolution_y = 720 scene.frame_start = 1 # Duration: derive from prompt if the user specifies (e.g. "20 second orbit"). # Default is 15 s = 360 frames. Adjust DURATION_S to match prompt. DURATION_S = 15 # ← change this if prompt specifies a different duration TOTAL_FRAMES = DURATION_S * 24 scene.frame_end = TOTAL_FRAMES bpy.ops.object.camera_add() cam = bpy.context.active_object scene.camera = cam cam.data.clip_end = size * 20 radius = dist deg_per_frame = 360.0 / TOTAL_FRAMES # one full rotation over the whole clip # Eye-level height so shadow-catcher ground fills the bottom of the frame. eye_height = min_z + size * 0.35 look_target = Vector(centre.x, centre.y, min_z + size * 0.4) for frame in range(1, TOTAL_FRAMES + 1): angle = math.radians((frame - 1) * deg_per_frame) x = centre.x + radius * math.sin(angle) y = centre.y - radius * math.cos(angle) cam.location = (x, y, eye_height) look_at(cam, look_target) cam.keyframe_insert(data_path='location', frame=frame) cam.keyframe_insert(data_path='rotation_euler', frame=frame) scene.render.image_settings.file_format = 'FFMPEG' scene.render.ffmpeg.format = 'MPEG4' scene.render.ffmpeg.codec = 'H264' scene.render.filepath = os.path.join(_OUTPUT_DIR, "orbit.mp4") bpy.ops.render.render(animation=True) _mp4 = os.path.join(_OUTPUT_DIR, "orbit.mp4") _tmp = _mp4 + ".tmp.mp4" subprocess.run(["ffmpeg", "-i", _mp4, "-movflags", "+faststart", "-c", "copy", _tmp, "-y"], capture_output=True) os.replace(_tmp, _mp4) ``` --- ## Assembly Fly-in Animation ```python # placement_manifest: {"component_name": {"location": [x,y,z], "rotation": [rx,ry,rz]}} for name, placement in placement_manifest.items(): obj = bpy.data.objects.get(name) if not obj: continue final_loc = placement["location"] start_loc = [final_loc[0], final_loc[1] - 5.0, final_loc[2] + 2.0] scene.frame_set(1) obj.location = start_loc obj.keyframe_insert(data_path='location', frame=1) obj.location = final_loc obj.keyframe_insert(data_path='location', frame=60) for fc in obj.animation_data.action.fcurves: for kp in fc.keyframe_points: kp.interpolation = 'BEZIER' ``` --- --- ## High Quality Demo (M1 MacBook / Local GPU) Use this section when the user asks for a high-quality, impressive, or demo render — especially turntable animations. Requires: - Blender running locally on an M1/M2/M3 Mac (or any machine with a GPU) - A free HDRI `.exr` file downloaded from [polyhaven.com/hdris](https://polyhaven.com/hdris) - Best choices for a garden room: **"Meadow 2"**, **"Rosendal Plains 2"**, **"Kloofendal 48d Partly Cloudy"** - Download the 4K `.exr` version; place it anywhere (e.g. `~/Downloads/meadow_2_4k.exr`) - The user includes the path in their render prompt; Claude embeds it in the script **Quality stack (combine all four for best results):** 1. `enable_gpu(scene)` — Metal on M1, 5-10× faster than CPU 2. `setup_hdri_world(hdri_path)` — real outdoor lighting + background 3. Adaptive sampling (256 max, threshold 0.02) — stops early when converged 4. OIDN denoiser — 128 adaptive samples looks like 512+ without it --- ### GPU Acceleration (M1 Metal / CUDA / OptiX) Call this before setting `scene.cycles.samples`. It detects the best available GPU and falls back to CPU gracefully. ```python def enable_gpu(scene): """Enable Metal (M1/M2), CUDA, OptiX, or HIP — whichever is available. Falls back to CPU.""" prefs = bpy.context.preferences cprefs = prefs.addons["cycles"].preferences cprefs.refresh_devices() for device_type in ('METAL', 'CUDA', 'OPTIX', 'HIP'): try: cprefs.compute_device_type = device_type devices = cprefs.get_devices_for_type(device_type) if devices: for d in devices: d.use = True scene.cycles.device = 'GPU' print(f"[CadClaude] GPU: {device_type}") return except Exception: pass scene.cycles.device = 'CPU' print("[CadClaude] GPU: none found, using CPU") ``` --- ### HDRI Environment Lighting Replaces the Nishita sky + Sun lamp setup. The HDRI provides both realistic lighting and a real outdoor background — single biggest quality jump available. ```python def setup_hdri_world(hdri_path, rotation_z_deg=135.0, strength=1.0): """ Load an HDRI .exr for environment lighting and background. rotation_z_deg rotates the HDRI so the brightest light hits the model from a good angle. Adjust until shadows fall attractively (135° is a good starting point). """ world = bpy.context.scene.world world.use_nodes = True wt = world.node_tree for n in list(wt.nodes): wt.nodes.remove(n) coord = wt.nodes.new("ShaderNodeTexCoord") mapping = wt.nodes.new("ShaderNodeMapping") env_tex = wt.nodes.new("ShaderNodeTexEnvironment") bg = wt.nodes.new("ShaderNodeBackground") out = wt.nodes.new("ShaderNodeOutputWorld") env_tex.image = bpy.data.images.load(hdri_path) mapping.inputs["Rotation"].default_value[2] = math.radians(rotation_z_deg) # Tilt horizon down so it aligns with shadow-catcher at eye-level camera mapping.inputs["Rotation"].default_value[0] = math.radians(-8.0) bg.inputs["Strength"].default_value = strength wt.links.new(coord.outputs["Generated"], mapping.inputs["Vector"]) wt.links.new(mapping.outputs["Vector"], env_tex.inputs["Vector"]) wt.links.new(env_tex.outputs["Color"], bg.inputs["Color"]) wt.links.new(bg.outputs["Background"], out.inputs["Surface"]) ``` **No Sun lamp needed** when using HDRI — the HDRI already contains directional light from the sky/sun. --- ### Shadow Catcher Ground Use with HDRI. The ground plane is invisible but catches shadows from the model, grounding it visually without the HDRI background being masked by a flat polygon. ```python # MUST be False — True renders shadow catcher as a solid black rectangle bpy.context.scene.render.film_transparent = False # Shadow catcher — invisible, only catches shadows from the building. # size * 8 so the plane extends to the visual horizon at eye-level camera angles. bpy.ops.mesh.primitive_plane_add(size=size * 8, location=(centre.x, centre.y, min_z)) ground = bpy.context.active_object ground.name = "Ground" ground.is_shadow_catcher = True # Fill light — large soft dome above the model. # Prevents fully-black walls when HDRI sun is behind the building (critical for orbit animations). bpy.ops.object.light_add(type='AREA', location=(centre.x, centre.y, min_z + size * 2.5)) fill = bpy.context.active_object fill.name = "FillDome" fill.data.shape = 'DISK' fill.data.size = size * 3 fill.data.energy = size * size * 0.8 fill.data.use_shadow = False ``` ⚠️ Do NOT use `render.film_transparent = True` with shadow catcher — it makes the shadows also transparent, producing a black ground band in the video. --- ### Adaptive Sampling + OIDN Denoiser Use for all high-quality renders. Stops sampling each pixel as soon as it converges rather than running all `samples` regardless. ```python # High quality — 256 max samples, stops early when converged, denoised scene.cycles.use_adaptive_sampling = True scene.cycles.adaptive_threshold = 0.02 # stop when per-pixel variance < 2% scene.cycles.adaptive_min_samples = 32 # always do at least 32 passes scene.cycles.samples = 256 # upper bound; most pixels finish at 64-128 scene.cycles.use_denoising = True scene.cycles.denoiser = 'OPENIMAGEDENOISE' # OIDN ships with Blender, no extra install ``` --- ### High Quality Demo Turntable (M1) Complete template combining all the above. Use this when the user asks for an impressive or demo-quality turntable. The user must provide `hdri_path` in their prompt (e.g. "use HDRI at ~/Downloads/meadow_2_4k.exr"). ```python import bpy, math, os, mathutils # Clear scene for obj in bpy.data.objects: bpy.data.objects.remove(obj, do_unlink=True) for block in bpy.data.meshes: bpy.data.meshes.remove(block) # ── Import model ────────────────────────────────────────────────────────────── stl_path = list(_COMPONENT_FILES.values())[0] for obj in bpy.data.objects: obj.select_set(False) bpy.ops.wm.stl_import(filepath=stl_path) model = bpy.context.selected_objects[0] model.name = "GardenRoom" # ── Bounding box ────────────────────────────────────────────────────────────── local_bbox = [mathutils.Vector(v) for v in model.bound_box] cx = sum(v.x for v in local_bbox) / 8 cy = sum(v.y for v in local_bbox) / 8 cz = sum(v.z for v in local_bbox) / 8 centre = model.matrix_world @ mathutils.Vector((cx, cy, cz)) size = max(model.dimensions) dist = size * 3.2 # slightly closer than 3.5 for more presence min_z = min((model.matrix_world @ mathutils.Vector(v)).z for v in model.bound_box) # ── Materials ───────────────────────────────────────────────────────────────── # (apply make_wood_material / make_rubber_material here per prompt) # ── Render engine + GPU ─────────────────────────────────────────────────────── scene = bpy.context.scene scene.render.engine = 'CYCLES' enable_gpu(scene) # Metal on M1, falls back to CPU # Adaptive sampling + OIDN scene.cycles.use_adaptive_sampling = True scene.cycles.adaptive_threshold = 0.03 # slightly looser than still renders — fine for motion scene.cycles.adaptive_min_samples = 16 scene.cycles.samples = 64 # 64 max + OIDN denoiser = excellent quality at 720p scene.cycles.use_denoising = True scene.cycles.denoiser = 'OPENIMAGEDENOISE' # ── Resolution + output ─────────────────────────────────────────────────────── scene.render.resolution_x = 1280 scene.render.resolution_y = 720 scene.render.resolution_percentage = 100 scene.render.image_settings.file_format = 'FFMPEG' scene.render.ffmpeg.format = 'MPEG4' scene.render.ffmpeg.codec = 'H264' scene.render.ffmpeg.constant_rate_factor = 'HIGH' # Do NOT set ffmpeg_preset = 'BEST' — maps to x264 veryslow and breaks moov atom finalisation in headless mode scene.render.fps = 24 scene.frame_start = 1 scene.frame_end = 120 # 5 seconds — smooth full orbit # ── HDRI world ──────────────────────────────────────────────────────────────── # _HDRI_PATH is injected by the executor — use it directly, never hardcode a path setup_hdri_world(_HDRI_PATH, rotation_z_deg=135.0, strength=1.0) # ── Shadow catcher ground ───────────────────────────────────────────────────── bpy.ops.mesh.primitive_plane_add(size=size * 4, location=(centre.x, centre.y, min_z)) ground = bpy.context.active_object ground.name = "Ground" ground.is_shadow_catcher = True # ── Camera ──────────────────────────────────────────────────────────────────── def look_at(cam, target): from mathutils import Vector direction = Vector(target) - cam.location rot_quat = direction.to_track_quat('-Z', 'Y') cam.rotation_euler = rot_quat.to_euler() bpy.ops.object.camera_add() cam = bpy.context.active_object scene.camera = cam cam.data.clip_end = size * 20 cam.data.lens = 70 # 70mm: good architectural feel, shows context without distortion radius = dist # Camera height: starts at size*0.45, rises gently to size*0.65 over the orbit # This gives a slight dolly-up feeling that makes the video feel more dynamic for frame in range(1, scene.frame_end + 2): t = (frame - 1) / scene.frame_end # 0.0 → 1.0 angle = math.radians(t * 360) # full 360° orbit height_frac = 0.45 + t * 0.20 # gentle rise: 0.45 → 0.65 cam.location = ( centre.x + radius * math.sin(angle), centre.y - radius * math.cos(angle), centre.z + size * height_frac, ) look_at(cam, centre) # Do NOT call scene.frame_set() here — it re-evaluates animation curves and # overwrites the location we just set, causing all frames to bake to frame 1's position. cam.keyframe_insert(data_path='location', frame=frame) cam.keyframe_insert(data_path='rotation_euler', frame=frame) # ── Render ──────────────────────────────────────────────────────────────────── scene.render.filepath = os.path.join(_OUTPUT_DIR, "turntable.mp4") bpy.ops.render.render(animation=True) _mp4 = os.path.join(_OUTPUT_DIR, "turntable.mp4") _tmp = _mp4 + ".tmp.mp4" subprocess.run(["ffmpeg", "-i", _mp4, "-movflags", "+faststart", "-c", "copy", _tmp, "-y"], capture_output=True) os.replace(_tmp, _mp4) ``` **Expected render time on M1 MacBook Pro:** ~30-45 minutes for 120 frames at 1280×720 with 64 adaptive samples + OIDN. The denoiser keeps each frame clean; 64 samples at 720p with OIDN is indistinguishable from 256 samples without it. --- ## Common Mistakes ```python # ❌ WRONG — manual atan2 rotation points camera the WRONG direction cam.rotation_euler = (math.pi/2 - pitch, 0, math.atan2(x, -y)) # ✅ RIGHT — use look_at with mathutils from mathutils import Vector def look_at(cam, target): direction = Vector(target) - cam.location rot_quat = direction.to_track_quat('-Z', 'Y') cam.rotation_euler = rot_quat.to_euler() look_at(cam, (cx, cy, cz)) ``` ```python # ❌ WRONG — EEVEE requires a GPU; falls back to extremely slow software rendering on this server scene.render.engine = 'BLENDER_EEVEE_NEXT' scene.render.engine = 'BLENDER_EEVEE' # ✅ RIGHT — Cycles is a proper CPU renderer, no GPU needed scene.render.engine = 'CYCLES' scene.cycles.device = 'CPU' scene.cycles.samples = 64 # ❌ WRONG — hardcoded output path scene.render.filepath = "/output/dir/image.jpg" # ✅ RIGHT — use injected _OUTPUT_DIR scene.render.filepath = os.path.join(_OUTPUT_DIR, "image.jpg") # ❌ WRONG — old STL import bpy.ops.import_mesh.stl(filepath=path) # ✅ RIGHT — Blender 4.x bpy.ops.wm.stl_import(filepath=path) # ❌ WRONG — bpy.ops.object.select_all for deselect (can fail in headless) bpy.ops.object.select_all(action='DESELECT') # ✅ RIGHT for obj in bpy.data.objects: obj.select_set(False) # ❌ WRONG — default clip_end (100 units) clips mm-scale FreeCAD models entirely bpy.ops.object.camera_add() cam = bpy.context.active_object # (clip_end never set → blank/gradient renders for any model > 100 Blender units away) # ✅ RIGHT — always set clip_end relative to model size cam.data.clip_end = size * 20 # e.g. size=3000mm → clip_end=60000 # ❌ WRONG — camera placed at world-origin offset when model is not at origin cam.location = (dist, -dist, dist * 0.5) # ✅ RIGHT — always offset from the computed bounding box centre cam.location = (centre.x + dist, centre.y - dist, centre.z + dist * 0.5) look_at(cam, centre) # ❌ WRONG — Sun lamp + HDRI doubles the lighting, blows out the render setup_hdri_world(hdri_path) bpy.ops.object.light_add(type='SUN', ...) # don't add a sun when using HDRI # ✅ RIGHT — HDRI is the only light source when using setup_hdri_world() # ❌ WRONG — film_transparent = True with shadow catcher makes shadows vanish scene.render.film_transparent = True ground.is_shadow_catcher = True # ✅ RIGHT — leave film_transparent at its default (False) ground.is_shadow_catcher = True # ❌ WRONG — HDRI strength > 1.5 washes out the model bg.inputs["Strength"].default_value = 3.0 # ✅ RIGHT — 1.0 for outdoor/meadow HDRIs bg.inputs["Strength"].default_value = 1.0 ``` --- ## Site composites For `site_composite` renders the camera is solved from the photograph and injected. Call `apply_site_camera()` and never set the camera yourself. This is a **different lighting/compositing regime from the HDRI workflow above** — do not mix the two. The HDRI section's `film_transparent = False` rule is for when the shadow catcher needs to show the *HDRI world* through it; a site composite has no HDRI world and instead composites over a real photo, which needs `film_transparent = True` (see below). Using the wrong one of these two makes the shadow catcher render solid black either way. **Backplate** — show the photo behind the model. `cam.data.background_images` is a *viewport-only* aid — it never appears in `bpy.ops.render.render()` output — so the backplate must go through the compositor instead: ```python scene = bpy.context.scene scene.render.film_transparent = True # required so the render has an alpha # channel to composite over the photo scene.use_nodes = True tree = scene.node_tree tree.nodes.clear() render_layers = tree.nodes.new("CompositorNodeRLayers") backplate = tree.nodes.new("CompositorNodeImage") backplate.image = bpy.data.images.load(_BACKPLATE) alpha_over = tree.nodes.new("CompositorNodeAlphaOver") composite = tree.nodes.new("CompositorNodeComposite") tree.links.new(backplate.outputs["Image"], alpha_over.inputs[1]) tree.links.new(render_layers.outputs["Image"], alpha_over.inputs[2]) tree.links.new(alpha_over.outputs["Image"], composite.inputs["Image"]) ``` **Shadow catcher** — with `film_transparent = True`, a shadow-catcher plane renders as an alpha-only "hole" whose alpha encodes shadow intensity, so it composites correctly over the backplate above: the model casts a real shadow onto the photo and the plane itself never appears. ```python bpy.ops.mesh.primitive_plane_add(size=200, location=(0, 0, _SITE_PLACEMENT["pad_level_m"])) plane = bpy.context.active_object plane.is_shadow_catcher = True ``` **Foreground mask** — painted regions occlude the model. Feather the edge so the brush stroke does not read as a cut-out. Insert this between `alpha_over` and `composite` above: ```python if _FOREGROUND_MASK is not None: mask_node = tree.nodes.new("CompositorNodeImage") mask_node.image = bpy.data.images.load(_FOREGROUND_MASK) blur = tree.nodes.new("CompositorNodeBlur") blur.size_x = blur.size_y = 3 mix = tree.nodes.new("CompositorNodeMixRGB") # Remove the direct alpha_over -> composite link made above; the mask # sits between them instead. for link in list(tree.links): if link.from_node == alpha_over and link.to_node == composite: tree.links.remove(link) tree.links.new(mask_node.outputs["Image"], blur.inputs["Image"]) tree.links.new(alpha_over.outputs["Image"], mix.inputs[1]) # rendered model+backplate tree.links.new(backplate.outputs["Image"], mix.inputs[2]) # bare backplate (mask "erases" to this) tree.links.new(blur.outputs["Image"], mix.inputs["Fac"]) # blurred mask drives the mix factor tree.links.new(mix.outputs["Image"], composite.inputs["Image"]) ```

Blender Rendering (Core)

Native Always loaded

Always injected for every render. Defines camera rules, lighting, ColorRamp material patterns, and render type dispatch. Read-only.

~13178 tokens

← Projects

Skills

Reusable guidance attached to projects or renders to steer generation. See also Design Profiles.

New Skill

Native

Static connection rules between woodworking components: panel-to-panel, shelf-to-side, back panel, and face frame interfaces.

~317 tokens

1267 chars

View

v0.0.985

Generic

SIP Non-Habitable Construction

SIP Multistorey

Woodworking

SIP Construction (DEPRECATED)

SIP Wall Construction (DEPRECATED)

ElixiFree Core (Generic CAD)

SIP Partition Walls (ElixiFree API)

SIP Wall Panels (ElixiFree API)

SIP Roof Construction

Deterministic Pitched-L SIP Roofs

SIP Decomposition

SIP Foundation Construction

SIP Openings Construction

SIP Interface Rules

FreeCAD Direct Modeling

Woodworking Decomposition

Wood Boards

Wood Joints

Wood Fasteners

Wood Interfaces

Blender Rendering (Core)

Skills

SIP Construction (DEPRECATED)

SIP Wall Construction (DEPRECATED)

ElixiFree Core (Generic CAD)

SIP Partition Walls (ElixiFree API)

SIP Wall Panels (ElixiFree API)

SIP Roof Construction

Deterministic Pitched-L SIP Roofs

SIP Decomposition

SIP Foundation Construction

SIP Openings Construction

SIP Interface Rules

FreeCAD Direct Modeling

Woodworking Decomposition

Wood Boards

Wood Joints

Wood Fasteners

Wood Interfaces

Settings

Preferences

Help & Guide

What is ElixiCAD?

Creating a project — step by step

Tips for better results

Navigation (⌥ = Option/Alt key)

Global

3D Viewer

Component Board

Assembly View

Assembly Edit Mode

Standard Parts

Fasteners

Anchoring & Mounting

Hinges & Motion

Latching & Locking

Structural & Joining

Woodworking

Metal Fabrication

Other

Design Profiles

Generic

SIP Non-Habitable Construction

SIP Multistorey

Woodworking

Generic

Stage skills

SIP Non-Habitable Construction

Required artifacts

Stage skills

Skill routing

Validators

Catalogs

SIP Multistorey

Required artifacts

Stage skills

Skill routing

Validators

Catalogs

Woodworking

Stage skills

Skill routing

Validators

Skills

SIP Construction (DEPRECATED)

SIP Wall Construction (DEPRECATED)

ElixiFree Core (Generic CAD)

SIP Partition Walls (ElixiFree API)

SIP Wall Panels (ElixiFree API)

SIP Roof Construction

Deterministic Pitched-L SIP Roofs

SIP Decomposition

SIP Foundation Construction

SIP Openings Construction

SIP Interface Rules

FreeCAD Direct Modeling

Woodworking Decomposition

Wood Boards

Wood Joints

Wood Fasteners

Wood Interfaces

Blender Rendering (Core)

Sign In

SIP Construction (DEPRECATED)

SIP Wall Construction (DEPRECATED)

ElixiFree Core (Generic CAD)

SIP Partition Walls (ElixiFree API)

SIP Wall Panels (ElixiFree API)

SIP Roof Construction

Deterministic Pitched-L SIP Roofs

SIP Decomposition

SIP Foundation Construction

SIP Openings Construction

SIP Interface Rules

FreeCAD Direct Modeling

Woodworking Decomposition

Wood Boards

Wood Joints

Wood Fasteners