### Install Blendify (Full Package)

Source: https://github.com/ptrvilya/blendify/blob/main/docs/pip_readme.md

Installs the full Blendify package including optional requirements for utilities, examples, and documentation.

```bash
pip install blendify[all]
```

--------------------------------

### Install Blendify (Minimal)

Source: https://github.com/ptrvilya/blendify/blob/main/docs/pip_readme.md

Installs the core Blendify package without extra dependencies.

```bash
pip install blendify
```

--------------------------------

### Principled BSDF Material Setup

Source: https://context7.com/ptrvilya/blendify/llms.txt

Configures a physically-based rendering material with various parameters like roughness, metallic, transmission, IOR, and emission.

```python
# Full physically-based material (all Principled BSDF parameters available)
pbsdf = PrincipledBSDFMaterial(
    roughness=0.4,
    metallic=0.0,
    transmission_weight=0.8,   # glass-like
    ior=1.45,
    coat_weight=0.5,
    coat_roughness=0.1,
    emission_color=(1.0, 0.5, 0.0, 1.0),
    emission_strength=2.0
)
```

--------------------------------

### Uniform Color Examples

Source: https://context7.com/ptrvilya/blendify/llms.txt

Demonstrates creating solid colors with RGB or RGBA values, using floats between 0 and 1.

```python
# 1. Solid color (RGB or RGBA, floats in [0,1])
col_solid = UniformColors((0.8, 0.2, 0.1))           # RGB
col_alpha = UniformColors((0.8, 0.2, 0.1, 0.5))      # RGBA semi-transparent
```

--------------------------------

### Install Blendify and Libraries

Source: https://github.com/ptrvilya/blendify/blob/main/examples/ipynb/blendify_colab_demo.ipynb

Installs the blendify library along with trimesh and matplotlib for use in the Colab environment. Ensure your runtime is set to GPU for faster performance.

```python
# Install blendify and helpful libraries
!pip install blendify trimesh matplotlib
```

--------------------------------

### Glossy BSDF Material Setup

Source: https://context7.com/ptrvilya/blendify/llms.txt

Defines a material that behaves like a mirror, with adjustable roughness and distribution type (e.g., GGX).

```python
# Pure glossy (mirror-like) material
glossy = GlossyBSDFMaterial(roughness=0.0, distribution="GGX")
```

--------------------------------

### Install Older Blendify Versions

Source: https://github.com/ptrvilya/blendify/blob/main/docs/pip_readme.md

Installs older versions of Blendify compatible with Blender < 4.0 by specifying a find-links URL.

```bash
pip install blendify --find-links https://download.blender.org/pypi/bpy/
```

--------------------------------

### Per-Vertex Colors Example

Source: https://context7.com/ptrvilya/blendify/llms.txt

Creates colors assigned to each vertex of a mesh. Requires a NumPy array of shape (N, 3) or (N, 4) for N vertices.

```python
# 2. Per-vertex colors — array shape (N, 3) or (N, 4)
n_verts = 1000
vc = np.random.rand(n_verts, 4).astype(np.float32)
col_vertex = VertexColors(vc)
```

--------------------------------

### Set up background and point lights

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Configures the scene's background lighting and adds multiple point lights with specified strength and shadow softness.

```python
scene.lights.set_background_light(0.01)
lights = [scene.lights.add_point(strength=25, shadow_soft_size=0.1, translation=(-0.3, 1.0, 0.7)),
          scene.lights.add_point(strength=25, shadow_soft_size=0.1, translation=(1.1, 0.13, 0.6)),
          scene.lights.add_point(strength=25, shadow_soft_size=0.1, translation=(-0.1, -1.1, 1.2))]
```

--------------------------------

### Load Mesh and Set Up Scene

Source: https://github.com/ptrvilya/blendify/blob/main/examples/ipynb/blendify_colab_demo.ipynb

Loads a Stanford bunny OBJ model, creates a metallic material, and applies per-vertex colors based on vertex normals. The mesh is then added to the scene with scaled vertices.

```python
import requests, trimesh, io
import numpy as np
import matplotlib.pyplot as plt

from blendify import scene
from blendify.colors import UniformColors, VertexColors
from blendify.materials import PrincipledBSDFMaterial

#Load object
bunny_data = requests.get("https://graphics.stanford.edu/~mdfisher/Data/Meshes/bunny.obj", stream=True).raw
bunny_data.decode_content = True
bunny = trimesh.load(bunny_data, file_type="obj")

# Create metallic material
material = PrincipledBSDFMaterial(metallic=0.3)

# Create per-vertex colors
colors = VertexColors(np.abs(bunny.vertex_normals))

# Add mesh
scene.renderables.add_mesh(vertices=bunny.vertices*100, faces=bunny.faces, material=material, colors=colors)

# Set the camera
scene.set_perspective_camera((600,600), fov_y=np.pi/3, translation=(-3,10,20))

# Create light
scene.lights.add_sun(strength=7)
```

--------------------------------

### Build Blendify Documentation Locally

Source: https://github.com/ptrvilya/blendify/blob/main/docs/index.md

Use these commands to build the documentation for Blendify. The sphinx-apidoc command is optional and may require manual correction.

```bash
# Optional: updates rst files if new modules are added. However, it may need manual correction.
# sphinx-apidoc -F -o _docs blendify
# Build documentation
sphinx-autobuild docs docs/_build/html
```

--------------------------------

### Render a Cube Scene with Blendify

Source: https://github.com/ptrvilya/blendify/blob/main/docs/pip_readme.md

A basic script demonstrating how to set up a scene with a light, camera, material, and a cube, then render it to a PNG file.

```python
# Script to render cube
from blendify import scene
from blendify.materials import PrincipledBSDFMaterial
from blendify.colors import UniformColors
# Add light
scene.lights.add_point(strength=1000, translation=(4, -2, 4))
# Add camera
scene.set_perspective_camera((512, 512), fov_x=0.7, rotation=(0.82, 0.42, 0.18, 0.34), translation=(5, -5, 5))
# Create material
material = PrincipledBSDFMaterial()
# Create color
color = UniformColors((0.0, 1.0, 0.0))
# Add cube mesh
scene.renderables.add_cube_mesh(1.0, material, color)
# Render scene
scene.render(filepath="cube.png")
```

--------------------------------

### Import Scene Settings from .blend File

Source: https://context7.com/ptrvilya/blendify/llms.txt

Imports scene settings, including camera configurations, from a specified .blend file.

```python
scene.attach_blend("assets/studio.blend", with_camera=True)
```

--------------------------------

### Attach Scene from .blend File

Source: https://context7.com/ptrvilya/blendify/llms.txt

Imports objects and lights from an existing `.blend` file into the current scene, with an option to exclude the camera from the imported file.

```python
# In a new script: import walls/floor from a pre-built .blend, keep our own camera
scene.attach_blend("assets/cornell_box.blend", with_camera=False)
```

--------------------------------

### Render Scene to RAM with Depth and Albedo Maps

Source: https://context7.com/ptrvilya/blendify/llms.txt

Renders the scene to memory, capturing RGBA image, depth map, and albedo map. Requires GPU acceleration and returns numpy arrays for further processing.

```python
# Render to RAM and get depth + albedo as numpy arrays
image, depth, albedo = scene.render(
    use_gpu=True,
    samples=128,
    save_depth=True,
    save_albedo=True
)
# image:  (H, W, 4) RGBA uint8
# depth:  (H, W)    float32 depth in world units (inf where no geometry)
# albedo: (H, W, 4) RGBA uint8 raw diffuse color

# Visualize depth with matplotlib
import matplotlib as mpl, matplotlib.pyplot as plt
finite = depth[np.isfinite(depth)]
depth_norm = (depth - finite.min()) / (finite.max() - finite.min())
plt.imshow(mpl.colormaps["viridis"](depth_norm))
plt.axis("off"); plt.show()
```

--------------------------------

### Render scene with albedo map

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Renders the scene and additionally saves the albedo map. The albedo map is then displayed.

```python
image, albedo = scene.render(use_gpu=True, samples=128, save_albedo=True)
plt.axis('off')
_ = plt.imshow(albedo)
```

--------------------------------

### Fast Preview Render with Eevee/Workbench

Source: https://context7.com/ptrvilya/blendify/llms.txt

Generates a fast preview render using the Eevee or Workbench OpenGL renderer. Workbench provides extremely quick, colorless output.

```python
from blendify import scene
# fast=True uses the Workbench engine (colorless but extremely quick)
image = scene.preview(use_gpu=False, fast=False)
```

--------------------------------

### scene.preview

Source: https://context7.com/ptrvilya/blendify/llms.txt

Renders a fast preview using Blender's Eevee or Workbench engine. Available on Linux and macOS.

```APIDOC
## scene.preview

### Description
Renders using Blender's Eevee (or Workbench) OpenGL renderer for fast, non-photorealistic previews. Linux and macOS only.

### Method
`scene.preview(
    filepath: str = None,
    use_gpu: bool = True,
    fast: bool = False,
    verbose: bool = False
)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from blendify import scene
# fast=True uses the Workbench engine (colorless but extremely quick)
image = scene.preview(use_gpu=False, fast=False)

# Save preview to disk
scene.preview(filepath="preview.png", verbose=True)
```

### Response
#### Success Response (200)
Returns a numpy RGBA array representing the preview image. If `filepath` is provided, saves the image to disk and returns None.

#### Response Example
None provided.
```

--------------------------------

### Metal Material Preset

Source: https://context7.com/ptrvilya/blendify/llms.txt

Creates a material preset optimized for metallic surfaces, characterized by high metallic and low roughness values.

```python
# Convenient metal preset (high metallic + low roughness)
metal = MetalMaterial(roughness=0.05, metallic=0.95)
```

--------------------------------

### Set Perspective Camera and Lights

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Configures the scene's camera to a perspective view with specified field of view, translation, and rotation. Adds three point lights to illuminate the scene.

```python
# Set camera
scene.set_perspective_camera(
    (800, 800), fov_x=np.deg2rad(20.8),
    translation=(0, -0.56, 0.43),
    rotation=(0.889, 0.458, 0, 0),
)

```

--------------------------------

### Render Scene and Display Image

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Renders the scene using the GPU with specified samples and displays the resulting image. Requires matplotlib.pyplot to be imported as plt.

```python
# Render
image = scene.render(use_gpu=True, samples=128)
plt.axis('off')
_ = plt.imshow(image)
```

--------------------------------

### Save Preview Render to Disk

Source: https://context7.com/ptrvilya/blendify/llms.txt

Saves a preview render of the current scene to a specified file path. Can be configured with verbose output.

```python
# Save preview to disk
scene.preview(filepath="preview.png", verbose=True)
```

--------------------------------

### Set Perspective Camera with Focal Length and Look-At

Source: https://context7.com/ptrvilya/blendify/llms.txt

Configures a perspective camera using focal length and a 'look_at' rotation mode to aim at a specific point. Supports resolution and translation.

```python
# Alternatively, use "look_at" rotation mode to aim the camera at the world origin
camera2 = scene.set_perspective_camera(
    resolution=(1024, 768),
    focal_dist=50,                   # 50 mm focal length
    rotation_mode="look_at",
    rotation=np.array([0.0, 0.0, 0.0]),   # look at origin
    translation=(0, -10, 3)
)
```

--------------------------------

### Render scene with GPU acceleration

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Renders the scene using GPU acceleration with a specified number of samples. The output image is then displayed.

```python
image = scene.render(use_gpu=True, samples=128)
plt.axis('off')
_ = plt.imshow(image)
```

--------------------------------

### Add Spot Light

Source: https://context7.com/ptrvilya/blendify/llms.txt

Adds a spotlight to the scene, allowing control over its strength, cone angle, blend, and target.

```python
# Spot light
spot = scene.lights.add_spot(
    strength=300, spot_size=np.deg2rad(45), spot_blend=0.2,
    rotation_mode="look_at",
    rotation=np.array([0.0, 0.0, 0.0]),  # aim at origin
    translation=(0, -5, 5)
)
```

--------------------------------

### Define Sparse Camera Keypoints

Source: https://context7.com/ptrvilya/blendify/llms.txt

Initializes a camera trajectory with sparse keypoints, each defined by a quaternion for rotation, a position vector, and a timestamp.

```python
# Define sparse keypoints (WXYZ quaternion, XYZ position, time in seconds)
traj = Trajectory()
traj.add_keypoint(quaternion=[0.866, 0.5, 0.0, 0.0], position=[-2, -6, 2], time=0.0)
traj.add_keypoint(quaternion=[0.793, 0.505, 0.184, 0.288], position=[0, -6, 2], time=2.5)
traj.add_keypoint(quaternion=[0.612, 0.354, 0.354, 0.612], position=[2, -2, 2], time=5.0)
```

--------------------------------

### Plastic Material Preset

Source: https://context7.com/ptrvilya/blendify/llms.txt

Applies a default material preset suitable for plastic surfaces.

```python
# Plastic preset
plastic = PlasticMaterial()
```

--------------------------------

### Export Scene to .blend File

Source: https://context7.com/ptrvilya/blendify/llms.txt

Saves the current scene configuration to a `.blend` file, with an option to pack textures inline for portability.

```python
from blendify import scene

# Build scene ...

# Export to .blend (textures packed inline)
scene.export("results/my_scene.blend", include_file_textures=True)
```

--------------------------------

### Render Scene to File with GPU and Denoising

Source: https://context7.com/ptrvilya/blendify/llms.txt

Triggers a Cycles ray-trace render to a specified file path using GPU acceleration, with configurable samples and an enabled denoiser. Supports adjusting anti-aliasing filter width.

```python
import numpy as np
from blendify import scene
# ... (scene must have a camera set before calling render)

# Render to file with GPU, 256 samples, denoiser enabled
scene.render(
    filepath="output/scene.png",
    use_gpu=True,
    samples=256,
    use_denoiser=True,
    aa_filter_width=1.5
)
```

--------------------------------

### Replace lights and add donut mesh

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Removes existing point lights and point clouds from the scene, then adds the donut mesh with specified materials and colors for faces.

```python
# Remove old pc and lights from the scene
scene.renderables.remove(donut_pc)
for light in lights:
    scene.lights.remove(light)
# Add donut mesh
donut_mesh = scene.renderables.add_mesh(
    vertices, faces,
    faces_material=faces_material,
    material=[material_base, material_icing, material_sprinkles],
    colors=[colors_base, colors_icing, colors_sprinkles]
)
```

--------------------------------

### scene.export / scene.attach_blend

Source: https://context7.com/ptrvilya/blendify/llms.txt

Exports the current scene to a .blend file or imports objects/lights from an existing .blend file.

```APIDOC
## scene.export / scene.attach_blend

### Description
Exports the current scene to a `.blend` file, or imports objects and lights from an existing `.blend` file into the current scene.

### Method
`scene.export(filepath: str, include_file_textures: bool = False)`
`scene.attach_blend(filepath: str, with_camera: bool = True)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
from blendify import scene

# Build scene ...

# Export to .blend (textures packed inline)
scene.export("results/my_scene.blend", include_file_textures=True)

# In a new script: import walls/floor from a pre-built .blend, keep our own camera
scene.attach_blend("assets/cornell_box.blend", with_camera=False)
```

### Response
#### Success Response (200)
`scene.export` returns None. `scene.attach_blend` returns None.

#### Response Example
None provided.
```

--------------------------------

### Load Donut Mesh from Zip

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Loads a donut mesh from a zip file, separating it into base, icing, and sprinkles. It extracts vertices, faces, UV maps, and face material indices for each part.

```python
# system libraries needed to load the compressed mesh
from io import BytesIO
from zipfile import ZipFile

import matplotlib as mpl
import matplotlib.pyplot as plt
import numpy as np
import trimesh

from blendify import scene
from blendify.colors import UniformColors, VertexUV, FileTextureColors, VertexColors
from blendify.materials import PrincipledBSDFMaterial, MetalMaterial, \
    PlasticMaterial, PrincipledBSDFWireframeMaterial

%matplotlib inline


def load_donut_mesh(path_to_zip: str):
    donut_file = BytesIO(ZipFile(path_to_zip).read("donut.obj"))
    mesh = trimesh.load(donut_file, "obj", process=False)
    # Create accumulated mesh
    offset_v, offset_f = 0, 0
    vertices, faces, uv_map, faces_material = [], [], [], []
    vertices_count = {}
    for obj_ind, obj_key in enumerate(["donut_base", "donut_icing", "donut_sprinkles"]):
        # Select object from the TriMesh scene
        obj_vertices, obj_faces = mesh.geometry[obj_key].vertices, mesh.geometry[obj_key].faces
        vertices_count[obj_key] = len(obj_vertices)
        # Accumulate vertices and faces
        vertices.append(np.asarray(obj_vertices))
        faces.append(np.asarray(obj_faces) + offset_v)
        # Accumulate face indexes for per-face materials
        faces_material.append(np.full(len(obj_faces), fill_value=obj_ind, dtype=int))
        # Accumulate UV map
        visual_kind = mesh.geometry[obj_key].visual.kind
        if visual_kind is not None and visual_kind == "texture":
            uv_map.append(mesh.geometry[obj_key].visual.uv)
        else:
            uv_map.append(np.zeros((len(obj_vertices), 2), dtype=np.float32))
        # Accumulate offsets for vertices and faces
        offset_v += len(obj_vertices)
        offset_f += len(obj_faces)
    vertices = np.concatenate(vertices)
    faces = np.concatenate(faces)
    faces_material = np.concatenate(faces_material)
    uv_map = np.concatenate(uv_map)

    return vertices, faces, uv_map, faces_material, vertices_count
```

```python
vertices, faces, uv_map, faces_material, vertices_count = load_donut_mesh("examples/assets/donut.obj.zip")
```

--------------------------------

### Render Scene with Blendify

Source: https://github.com/ptrvilya/blendify/blob/main/examples/ipynb/blendify_colab_demo.ipynb

Renders the current scene using Blendify's raytracing capabilities. This is the primary step to generate the image output.

```python
img = scene.render()
```

--------------------------------

### Render donut as a point cloud with custom colors

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Renders the donut as a point cloud using its vertices. Custom colors are applied to different parts of the donut (base and icing) based on vertex count.

```python
# Remove old mesh
scene.renderables.remove(donut_mesh)
# Create colors for the point cloud
point_colors = np.ones((len(vertices), 4))
point_colors[:vertices_count["donut_base"]] = np.array([0.8, 0.5, 0.1, 0.4])
point_colors[vertices_count["donut_base"]:] = np.array([1.0, 0.7, 0.8, 0.6])
color = VertexColors(point_colors)
# Use only points from the mesh to create the point cloud 
donut_pc = scene.renderables.add_pointcloud(
    vertices, colors=color, material=material_base, 
    point_size=0.001, base_primitive="cube", particle_emission_strength=0.1
)
# Render
image = scene.render(use_gpu=True, samples=128)
plt.axis('off')
_ = plt.imshow(image)
```

--------------------------------

### scene.clear, scene.read_image, scene.read_exr_distmap

Source: https://context7.com/ptrvilya/blendify/llms.txt

Utility methods for resetting the scene and reading output files back into numpy arrays.

```APIDOC
## scene.clear / scene.read_image / scene.read_exr_distmap

### Description
Utility methods for resetting the scene and reading output files back into numpy arrays.

### Usage
```python
from blendify import scene

# Reset scene to empty state (removes all objects, lights, camera)
scene.clear()

# Read a previously saved PNG render back as (H, W, 4) RGBA numpy array
img = scene.read_image("output/scene.png")

# Read a depth map saved in OpenEXR format, clipping distant values
depth = scene.read_exr_distmap("output/scene.depth.0000.exr", dist_thresh=1e4)
# Values beyond dist_thresh are set to -inf
```
```

--------------------------------

### Render donut with various materials and colors

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Iteratively renders the donut mesh with different materials (wireframe, plastic, metal) and colors, displaying each result in a subplot.

```python
# Remove old mesh
scene.renderables.remove(donut_mesh)
# Create list of materials and colors to iterate over
material_iterator = [
    PrincipledBSDFWireframeMaterial(
        wireframe_color=(0.7, 0.8, 0.9, 1.0), wireframe_thickness=0.001
    ), 
    PlasticMaterial(), 
    MetalMaterial()
]
color_iterator = [
    UniformColors((0.2, 0.2, 0.2, 0.3)), 
    UniformColors((1.0, 0.9, 0.7, 1.0)), 
    UniformColors((1.0, 0.8, 0.8, 1.0))
]
# Create subplots
fig, ax = plt.subplots(1, 3, figsize=(15, 5))
# Render iteratively
donut_mesh = None
for index, (color, material) in enumerate(zip(color_iterator, material_iterator)):
    if donut_mesh is None:
        donut_mesh = scene.renderables.add_mesh(
            vertices, faces, material=material, colors=color
        )
        donut_mesh.set_smooth(True)
    else:
        donut_mesh.update_colors(color)
        donut_mesh.update_material(material)
    image = scene.render(use_gpu=True, samples=128)
    ax[index].axis('off')
    ax[index].imshow(image)
plt.show()
```

--------------------------------

### Add Point Cloud to Scene

Source: https://context7.com/ptrvilya/blendify/llms.txt

Renders a point cloud by instancing primitives at vertex positions. Supports per-point coloring and emission. Colors can be updated dynamically per frame without object recreation.

```python
import numpy as np
from blendify import scene
from blendify.materials import PrincipledBSDFMaterial
from blendify.colors import VertexColors, UniformColors

rng = np.random.default_rng(42)
pts = rng.standard_normal((5000, 3)).astype(np.float32)

# Per-vertex RGBA colors (float32, values in [0,1])
colors_array = np.ones((len(pts), 4), dtype=np.float32)
colors_array[:, 0] = np.clip(pts[:, 2] * 0.5 + 0.5, 0, 1)  # colorize by Z
colors_array[:, 2] = 1.0 - colors_array[:, 0]

pc = scene.renderables.add_pointcloud(
    vertices=pts,
    material=PrincipledBSDFMaterial(roughness=0.4),
    colors=VertexColors(colors_array),
    point_size=0.02,
    base_primitive="SPHERE",         # CUBE | SPHERE | PLANE
    particle_emission_strength=0.2,  # subtle self-glow
    translation=(0, 0, 0)
)

# In a video loop: update colors per-frame without rebuilding the object
new_colors = VertexColors(rng.random((len(pts), 4)).astype(np.float32))
pc.update_colors(new_colors)
```

--------------------------------

### File Texture Colors with Face UV Map

Source: https://context7.com/ptrvilya/blendify/llms.txt

Applies a texture from an image file using per-face UV coordinates. The UV map shape is (M_faces, 3, 2) for M triangular faces.

```python
# 4. Texture from a PNG/JPG file with a per-face UV map
#    FacesUV shape: (M_faces, 3, 2)  — 3 corners × 2 UV coords per triangle
n_faces = 500
face_uv = np.random.rand(n_faces, 3, 2).astype(np.float32)
col_file = FileTextureColors(
    texture_path="assets/donut_sprinkles.png",
    uv_map=FacesUV(face_uv)
)
```

--------------------------------

### scene.render

Source: https://context7.com/ptrvilya/blendify/llms.txt

Triggers a Cycles ray-trace render, returning an RGBA array or saving to disk. Optionally captures depth and albedo maps.

```APIDOC
## scene.render

### Description
Triggers the Cycles ray-trace render and returns a numpy RGBA array or saves a PNG to disk. Optionally captures a depth map (`.depth.npy`) and albedo map (`.albedo.png`) in the same call.

### Method
`scene.render(
    filepath: str = None,
    use_gpu: bool = False,
    samples: int = 128,
    use_denoiser: bool = False,
    aa_filter_width: float = 1.0,
    save_depth: bool = False,
    save_albedo: bool = False
)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```python
import numpy as np
from blendify import scene
# ... (scene must have a camera set before calling render)

# Render to file with GPU, 256 samples, denoiser enabled
scene.render(
    filepath="output/scene.png",
    use_gpu=True,
    samples=256,
    use_denoiser=True,
    aa_filter_width=1.5
)

# Render to RAM and get depth + albedo as numpy arrays
image, depth, albedo = scene.render(
    use_gpu=True,
    samples=128,
    save_depth=True,
    save_albedo=True
)
# image:  (H, W, 4) RGBA uint8
# depth:  (H, W)    float32 depth in world units (inf where no geometry)
# albedo: (H, W, 4) RGBA uint8 raw diffuse color

# Visualize depth with matplotlib
import matplotlib as mpl, matplotlib.pyplot as plt
finite = depth[np.isfinite(depth)]
depth_norm = (depth - finite.min()) / (finite.max() - finite.min())
plt.imshow(mpl.colormaps["viridis"](depth_norm))
plt.axis("off"); plt.show()
```

### Response
#### Success Response (200)
Returns a tuple of numpy arrays: (RGBA image, depth map, albedo map). If `filepath` is provided, it saves the image to disk and returns None.

#### Response Example
None provided.
```

--------------------------------

### Set Perspective Camera with FOV and Quaternion

Source: https://context7.com/ptrvilya/blendify/llms.txt

Configures a perspective camera using horizontal field-of-view and a WXYZ quaternion for rotation. Supports near/far clipping planes and translation.

```python
import numpy as np
from blendify import scene

# Set a 512×512 perspective camera using horizontal FOV and a WXYZ quaternion rotation
camera = scene.set_perspective_camera(
    resolution=(512, 512),
    fov_x=np.deg2rad(60),           # 60° horizontal FOV
    near=0.1,
    far=100.0,
    rotation_mode="quaternionWXYZ",
    rotation=(0.82, 0.42, 0.18, 0.34),
    translation=(5, -5, 5)
)
```

--------------------------------

### Principled BSDF Wireframe Material

Source: https://context7.com/ptrvilya/blendify/llms.txt

Sets up a material that renders a wireframe overlay on top of a Principled BSDF surface, allowing customization of wireframe color and thickness.

```python
# Wireframe overlay on top of PrincipledBSDF
wire = PrincipledBSDFWireframeMaterial(
    wireframe_color=(0.0, 0.0, 0.0, 1.0),
    wireframe_thickness=0.002,
    roughness=0.6
)
```

--------------------------------

### Add Area Lights to Scene

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Adds two area lights to the scene with specified size, strength, color, translation, and rotation. Ensure 'np' is imported as numpy.

```python
scene.lights.add_area(
    "circle", size=0.5, strength=25, color = (0.9, 0.4, 0.8),
    translation=donut_mesh.translation - np.array([0, 0, 0.3]), 
    rotation=(0, 180, 0), rotation_mode="eulerXYZ"
)
scene.lights.add_area(
    "circle", size=0.5, strength=25, color=(0.9, 0.4, 0.8),
    translation=donut_mesh.translation + np.array([0, 0, 1]), 
    rotation=(0, 0, 0), rotation_mode="eulerXYZ"
)
```

--------------------------------

### Video Rendering Loop

Source: https://context7.com/ptrvilya/blendify/llms.txt

Iterates through a dense trajectory, setting camera positions and rendering frames. The resulting frames are numpy arrays suitable for video writing.

```python
frames = []
for kp in dense_traj:
    camera.set_position(rotation=kp["quaternion"], translation=kp["position"])
    img = scene.render(use_gpu=True, samples=64)
    frames.append(img)
# frames is a list of (H, W, 4) numpy arrays ready for VideoWriter or imageio
```

--------------------------------

### Scene Clearing and File Reading

Source: https://context7.com/ptrvilya/blendify/llms.txt

Provides utility methods for resetting the scene to an empty state and reading previously saved render outputs back into numpy arrays. Use `read_image` for RGBA PNGs and `read_exr_distmap` for depth maps, with an option to clip distant values.

```python
from blendify import scene

# Reset scene to empty state (removes all objects, lights, camera)
scene.clear()

# Read a previously saved PNG render back as (H, W, 4) RGBA numpy array
img = scene.read_image("output/scene.png")

# Read a depth map saved in OpenEXR format, clipping distant values
depth = scene.read_exr_distmap("output/scene.depth.0000.exr", dist_thresh=1e4)
# Values beyond dist_thresh are set to -inf
```

--------------------------------

### scene.renderables.add_pointcloud

Source: https://context7.com/ptrvilya/blendify/llms.txt

Renders a point cloud by instancing a small 3D primitive at each vertex position, with optional per-point coloring and emission glow.

```APIDOC
## scene.renderables.add_pointcloud

### Description
Renders a point cloud by instancing a small 3D primitive (cube, sphere, or plane) at each vertex position, with optional per-point coloring and emission glow.

### Method
```python
scene.renderables.add_pointcloud(vertices, material, colors, point_size=0.01, base_primitive='CUBE', particle_emission_strength=0.0, translation=(0,0,0))
```

### Parameters
- **vertices** (numpy.ndarray) - Array of vertex positions.
- **material** (Material) - The material to apply to the point cloud instances.
- **colors** (Color) - The color information for the point cloud (e.g., `VertexColors`).
- **point_size** (float, optional) - The size of each point instance. Defaults to 0.01.
- **base_primitive** (str, optional) - The primitive to instance ('CUBE', 'SPHERE', 'PLANE'). Defaults to 'CUBE'.
- **particle_emission_strength** (float, optional) - The strength of the emission glow for each particle. Defaults to 0.0.
- **translation** (tuple, optional) - The translation offset for the point cloud. Defaults to (0,0,0).

### Request Example
```python
import numpy as np
from blendify import scene
from blendify.materials import PrincipledBSDFMaterial
from blendify.colors import VertexColors, UniformColors

rng = np.random.default_rng(42)
pts = rng.standard_normal((5000, 3)).astype(np.float32)

# Per-vertex RGBA colors (float32, values in [0,1])
colors_array = np.ones((len(pts), 4), dtype=np.float32)
colors_array[:, 0] = np.clip(pts[:, 2] * 0.5 + 0.5, 0, 1)  # colorize by Z
colors_array[:, 2] = 1.0 - colors_array[:, 0]

pc = scene.renderables.add_pointcloud(
    vertices=pts,
    material=PrincipledBSDFMaterial(roughness=0.4),
    colors=VertexColors(colors_array),
    point_size=0.02,
    base_primitive="SPHERE",
    particle_emission_strength=0.2,
    translation=(0, 0, 0)
)
```

### Response
- **pointcloud** (PointCloud object) - The created point cloud object.
```

--------------------------------

### Render scene with depth map

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Renders the scene including a depth map. Infinite depth values are filtered, and the depth map is normalized and color-mapped for visualization.

```python
image, depth = scene.render(use_gpu=True, samples=128, save_depth=True,)
# Filter infinite values
finite_depth = depth[np.isfinite(depth)]
# Normalize depth values
depth = (depth-np.min(finite_depth))/(np.max(finite_depth)-np.min(finite_depth))
# Convert to desired coolormap
depth = (mpl.colormaps['viridis'](depth)*255).astype(np.uint8)
plt.axis('off')
_ = plt.imshow(depth)
```

--------------------------------

### Add NURBS Primitives (Sphere, Ellipsoid, Curve)

Source: https://context7.com/ptrvilya/blendify/llms.txt

Adds smooth parametric NURBS primitives like spheres and ellipsoids, or a Bezier tube curve. These primitives only support UniformColors. The curve can visualize paths.

```python
import numpy as np
from blendify import scene
from blendify.materials import PrincipledBSDFMaterial, MetalMaterial
from blendify.colors import UniformColors

mat = PrincipledBSDFMaterial(roughness=0.1, transmission_weight=0.9, ior=1.5)

# Glass sphere
sphere = scene.renderables.add_sphere_nurbs(
    radius=0.5,
    material=mat,
    colors=UniformColors((0.9, 0.9, 1.0)),
    translation=(0, 0, 0.5)
)

# Stretched ellipsoid
ellipsoid = scene.renderables.add_ellipsoid_nurbs(
    radius=(1.0, 0.5, 0.3),          # (rx, ry, rz)
    material=MetalMaterial(roughness=0.2),
    colors=UniformColors((0.9, 0.8, 0.7)),
    translation=(2, 0, 0)
)

# Tube along a Bezier curve (e.g., a camera path visualizer)
keypoints = np.array([
    [0, 0, 0], [1, 1, 1], [2, 0, 2], [3, -1, 1], [4, 0, 0]
], dtype=np.float32)
curve = scene.renderables.add_curve_nurbs(
    keypoints=keypoints,
    radius=0.03,
    material=PrincipledBSDFMaterial(roughness=0.5),
    colors=UniformColors((1.0, 0.5, 0.0))
)
```

--------------------------------

### Set Background Light

Source: https://context7.com/ptrvilya/blendify/llms.txt

Configures the ambient background light for the scene, affecting overall illumination and color.

```python
# Ambient background light (low-level fill)
scene.lights.set_background_light(strength=0.05, color=(1.0, 1.0, 1.0))
```

--------------------------------

### Set Perspective Camera

Source: https://context7.com/ptrvilya/blendify/llms.txt

Configures the scene's perspective camera with specified resolution and horizontal field of view.

```python
camera = scene.set_perspective_camera(resolution=(1024, 1024), fov_x=np.deg2rad(60))
```

--------------------------------

### Add Point Light

Source: https://context7.com/ptrvilya/blendify/llms.txt

Adds an omnidirectional point light to the scene, specifying its strength, shadow softness, color, and position.

```python
# Point light (omnidirectional)
pt = scene.lights.add_point(
    strength=500, shadow_soft_size=0.3,
    color=(1.0, 0.9, 0.8),
    translation=(3, -3, 5)
)
```

--------------------------------

### Display Rendered Image

Source: https://github.com/ptrvilya/blendify/blob/main/examples/ipynb/blendify_colab_demo.ipynb

Displays the rendered image using Matplotlib's imshow function. Ensure Matplotlib is imported as plt.

```python
plt.imshow(img)
```

--------------------------------

### Refine Camera Trajectory

Source: https://context7.com/ptrvilya/blendify/llms.txt

Interpolates sparse keypoints into a dense camera path at a specified frame rate, applying smoothing for rotations and translations.

```python
# Refine to 30 fps with quadratic interpolation and smoothing
dense_traj = traj.refine_trajectory(time_step=1/30, interp_type="quadratic", smoothness=5.0)
```

--------------------------------

### Add Sun Light

Source: https://context7.com/ptrvilya/blendify/llms.txt

Adds a directional sun light to the scene, defining its strength, angular diameter, and rotation.

```python
# Directional sun light
sun = scene.lights.add_sun(
    strength=5.0, angular_diameter=0.009,
    rotation_mode="eulerXYZ",
    rotation=(np.deg2rad(60), 0, np.deg2rad(30))
)
```

--------------------------------

### scene.renderables.add_sphere_nurbs / add_ellipsoid_nurbs / add_curve_nurbs

Source: https://context7.com/ptrvilya/blendify/llms.txt

Adds smooth parametric NURBS primitives (sphere, ellipsoid) or a Bezier tube curve to the scene. These only support `UniformColors`.

```APIDOC
## scene.renderables.add_sphere_nurbs / add_ellipsoid_nurbs / add_curve_nurbs

### Description
Adds smooth parametric NURBS primitives (sphere, ellipsoid) or a Bezier tube curve to the scene. These only support `UniformColors`.

### Method
```python
scene.renderables.add_sphere_nurbs(radius, material, colors, translation=None)
scene.renderables.add_ellipsoid_nurbs(radius, material, colors, translation=None)
scene.renderables.add_curve_nurbs(keypoints, radius, material, colors, translation=None)
```

### Parameters
- **radius** (float or tuple) - The radius of the sphere/ellipsoid, or a tuple (rx, ry, rz) for ellipsoid.
- **keypoints** (numpy.ndarray) - Array of keypoints defining the Bezier curve for `add_curve_nurbs`.
- **material** (Material) - The material to apply.
- **colors** (UniformColors) - The uniform color to apply.
- **translation** (tuple, optional) - The translation offset. Defaults to None.

### Request Example
```python
import numpy as np
from blendify import scene
from blendify.materials import PrincipledBSDFMaterial, MetalMaterial
from blendify.colors import UniformColors

mat = PrincipledBSDFMaterial(roughness=0.1, transmission_weight=0.9, ior=1.5)

# Glass sphere
sphere = scene.renderables.add_sphere_nurbs(
    radius=0.5,
    material=mat,
    colors=UniformColors((0.9, 0.9, 1.0)),
    translation=(0, 0, 0.5)
)

# Stretched ellipsoid
ellipsoid = scene.renderables.add_ellipsoid_nurbs(
    radius=(1.0, 0.5, 0.3),
    material=MetalMaterial(roughness=0.2),
    colors=UniformColors((0.9, 0.8, 0.7)),
    translation=(2, 0, 0)
)

# Tube along a Bezier curve
keypoints = np.array([
    [0, 0, 0], [1, 1, 1], [2, 0, 2], [3, -1, 1], [4, 0, 0]
], dtype=np.float32)
curve = scene.renderables.add_curve_nurbs(
    keypoints=keypoints,
    radius=0.03,
    material=PrincipledBSDFMaterial(roughness=0.5),
    colors=UniformColors((1.0, 0.5, 0.0))
)
```

### Response
- **nurbs_object** (NURBS object) - The created NURBS primitive or curve object.
```

--------------------------------

### Add Donut Mesh to Scene with Per-Part Materials

Source: https://github.com/ptrvilya/blendify/blob/main/docs/walkthrough.md

Adds the loaded donut mesh to the scene, assigning distinct materials and colors to the base, icing, and sprinkles. Uses `faces_material` to map materials to mesh faces.

```python
# Create per-part materials and colors
# Base and Icing have uniform colors
material_base = PrincipledBSDFMaterial(roughness=0.4, clearcoat_roughness=0.03)
material_icing = PrincipledBSDFMaterial(roughness=0.545, clearcoat=0.1, clearcoat_roughness=0.03)
colors_base = UniformColors((0.7, 0.4, 0.1))
colors_icing = UniformColors((0.9, 0.58, 0.72))
# Sprinkles have texture colors to allow per-sprinkle coloring
material_sprinkles = PrincipledBSDFMaterial(roughness=0.894, clearcoat_roughness=0.03)
vertex_uv_map = VertexUV(uv_map)
colors_sprinkles = FileTextureColors("../assets/donut_sprinkles.png", vertex_uv_map)
# Add mesh to the scene
donut_mesh = scene.renderables.add_mesh(
    vertices, faces,
    faces_material=faces_material,
    material=[material_base, material_icing, material_sprinkles],
    colors=[colors_base, colors_icing, colors_sprinkles]
)
donut_mesh.set_smooth(True)
```

--------------------------------

### Texture Colors with Vertex UV Map

Source: https://context7.com/ptrvilya/blendify/llms.txt

Applies a texture from a NumPy array to a mesh using per-vertex UV coordinates. The UV map should have shape (N, 2) for N vertices.

```python
# 3. Texture from a numpy array with a per-vertex UV map
texture_img = np.random.randint(0, 255, (256, 256, 3), dtype=np.uint8)
uv_coords = np.random.rand(n_verts, 2).astype(np.float32)  # (N, 2) in [0,1]
col_tex = TextureColors(texture=texture_img, uv_map=VertexUV(uv_coords))
```

--------------------------------

### set_shadow_catcher

Source: https://context7.com/ptrvilya/blendify/llms.txt

Utility to make any renderable object act as a shadow catcher, allowing compositing of 3D objects over real backgrounds with realistic shadows.

```APIDOC
## Shadow Catcher — set_shadow_catcher

### Description
Utility to make any renderable object act as a shadow catcher, allowing compositing of 3D objects over real backgrounds with realistic shadows.

### Usage
```python
from blendify import scene
from blendify.materials import PrincipledBSDFMaterial
from blendify.colors import UniformColors
from blendify.utils.shadow_catcher import set_shadow_catcher

# Add a ground plane and make it a shadow catcher
floor = scene.renderables.add_plane_mesh(
    size=20.0,
    material=PrincipledBSDFMaterial(),
    colors=UniformColors((1.0, 1.0, 1.0)),
    translation=(0, 0, 0)
)
set_shadow_catcher(floor, state=True)

# To revert back to a regular visible object
set_shadow_catcher(floor, state=False)

# Can also accept a Blender tag string
set_shadow_catcher("Plane_000", state=True)
```
```

--------------------------------

### Remove Light from Scene

Source: https://context7.com/ptrvilya/blendify/llms.txt

Removes a previously added light source from the scene.

```python
# Remove a light
scene.lights.remove(sun)
```

--------------------------------

### scene.renderables.add_cube_mesh / add_cylinder_mesh / add_circle_mesh / add_plane_mesh

Source: https://context7.com/ptrvilya/blendify/llms.txt

Adds Blender mesh primitives (cube, cylinder, circle, plane). The plane primitive optionally acts as a shadow catcher.

```APIDOC
## scene.renderables.add_cube_mesh / add_cylinder_mesh / add_circle_mesh / add_plane_mesh

### Description
Adds Blender mesh primitives (cube, cylinder, circle, plane). The plane primitive optionally acts as a shadow catcher to composite objects over real backgrounds.

### Method
```python
scene.renderables.add_cube_mesh(size, material, colors, translation=None)
scene.renderables.add_cylinder_mesh(radius, height, material, colors, translation=None)
# add_circle_mesh and add_plane_mesh signatures are similar
```

### Parameters
- **size** (float) - The size of the cube.
- **radius** (float) - The radius of the cylinder.
- **height** (float) - The height of the cylinder.
- **material** (Material) - The material to apply.
- **colors** (Color) - The color to apply.
- **translation** (tuple, optional) - The translation offset. Defaults to None.

### Request Example
```python
from blendify import scene
from blendify.materials import PrincipledBSDFMaterial, PlasticMaterial
from blendify.colors import UniformColors

# Cube
cube = scene.renderables.add_cube_mesh(
    size=1.0,
    material=PlasticMaterial(),
    colors=UniformColors((0.0, 1.0, 0.0)),
    translation=(0, 0, 0.5)
)

# Cylinder
cyl = scene.renderables.add_cylinder_mesh(
    radius=0.3, height=1.0,
    material=PrincipledBSDFMaterial(metallic=1.0, roughness=0.05),
    colors=UniformColors((0.8, 0.8, 0.9)),
    translation=(2, 0, 0.5)
)
```

### Response
- **mesh_primitive** (Mesh object) - The created mesh primitive object.
```

--------------------------------

### Set Orthographic Camera

Source: https://context7.com/ptrvilya/blendify/llms.txt

Configures an orthographic camera for technical visualizations, allowing control over zoom (ortho_scale), clipping planes, rotation, and translation.

```python
from blendify import scene

camera = scene.set_orthographic_camera(
    resolution=(800, 800),
    ortho_scale=2.0,    # zoom factor; larger = wider view
    near=0.01,
    far=50.0,
    rotation_mode="eulerXYZ",
    rotation=(np.deg2rad(60), 0, np.deg2rad(45)),
    translation=(5, -5, 5)
)
```