materials¶

Three.js-style material classes for Algan.

These mirror the Three.js mesh materials – the same material types, property names and default settings – so a material can be configured the familiar way and applied to a mob with set_material(). One deliberate deviation: color defaults to None, meaning “keep the mob’s existing color”, whereas Three.js defaults it to white (which would silently repaint any mob the material is applied to):

from algan import Sphere, MeshStandardMaterial

Sphere().set_material(MeshStandardMaterial(metalness=1.0, roughness=0.2)).spawn()

Each Material is a thin configuration object: it knows its lighting shader (a function from algan.rendering.shaders.material_shaders) and, via get_shader_param_values(), the per-vertex shader parameters that set_material registers as animatable attributes on the mob. So after applying a material you can animate e.g. mob.roughness = 0.1 or mob.emissive_intensity = 3.

Texture maps¶

set_material forwards the image slots the renderer has a sampler for – map, normal_map, roughness_map and metalness_map – onto the geometry, which is where Algan’s texture pipeline lives. Each one takes a path or an [H, W, C] image and is sampled bilinearly per fragment in the trace kernel:

Sphere().set_material(
    MeshStandardMaterial(map="earth.png", roughness_map="ocean_gloss.png")
)

Sampling needs per-vertex UVs, so this reaches a Surface (and its subclasses – Sphere, Cylinder, Torus, ImageMob, …) or a TriangleMesh built with uvs. On any other Mob – a Polyhedron, a Cube – the maps are ignored, with a warning saying so.

A forwarded map is static: unlike the scalar properties a material installs (mob.roughness and the rest), it is not an animatable attribute, and setting one warns to that effect. The one exception is map on a Surface, which lands on the animatable color_texture and so warns not at all.

Limitations¶

The image slots with no channel in the renderer (env_map, matcap, gradient_map, ao_map, transmission_map, …) are still accepted for API parity and dropped, with a warning naming them. wireframe, vertexColors and non-default side are likewise unsupported. The matcap, normal and depth materials use documented approximations (see algan.rendering.shaders.material_shaders). Every built-in material class shades per fragment in the render kernel; only a custom per-vertex shader (set_shader with a plain function) is baked into vertex colors, which is what costs it every light beyond a plain PointLight, all shadows, and an environment map’s diffuse contribution. Combining one with a lighting rig that asks for any of those warns, both where the shader is set and once per render.

Classes

`AdvancedPBRMaterial`	Configure a physical surface and, optionally, a scattering interior.
`DiffuseMaterial`	Lambertian (diffuse-only) shading plus emissive.
`ManimMaterial`	Manim's default 3-D shading: one achromatic offset per light, nothing else.
`Material`	Base class holding the Three.js shared material properties + defaults.
`MeshBasicMaterial`	alias of `UnlitMaterial`
`MeshDepthMaterial`	Renders camera distance as grayscale (near=bright, far=dark).
`MeshLambertMaterial`	alias of `DiffuseMaterial`
`MeshMatcapMaterial`	Material-capture shading.
`MeshNormalMaterial`	Encodes the surface normal as RGB.
`MeshPhongMaterial`	alias of `SpecularMaterial`
`MeshPhysicalMaterial`	alias of `AdvancedPBRMaterial`
`MeshStandardMaterial`	alias of `PBRMaterial`
`MeshToonMaterial`	Cel-shaded (banded diffuse) material plus emissive.
`PBRMaterial`	Metalness/roughness physically-based (Cook-Torrance) material.
`Side`	Which faces of a surface a material is for -- Three.js's `side`.
`SpecularMaterial`	Blinn-Phong shading: diffuse + specular highlight + emissive.
`UnlitMaterial`	Unlit material: renders the flat base color, ignoring lights.