AdvancedPBRMaterial

Qualified name: algan.rendering.shaders.materials.AdvancedPBRMaterial

class AdvancedPBRMaterial(color=None, *, clearcoat=0.0, clearcoat_roughness=0.0, ior=1.5, reflectivity=None, specular_intensity=1.0, specular_color=Color([1., 1., 1., 0., 1.]), sheen=0.0, sheen_roughness=1.0, sheen_color=Color([0., 0., 0., 0., 1.]), transmission=0.0, thickness=0.0, attenuation_color=Color([1., 1., 1., 0., 1.]), attenuation_distance=inf, sigma_s=0.0, g=0.0, iridescence=0.0, iridescence_ior=1.3, **kwargs)[source]

Bases: PBRMaterial

Configure a physical surface and, optionally, a scattering interior.

Extends MeshStandardMaterial with clearcoat, sheen, refraction, absorption, and approximate iridescence. MeshPhysicalMaterial is an alias of this class. With path tracing (samples_per_pixel > 1), a nonzero sigma_s adds homogeneous scattering inside a watertight, consistently wound triangle shell. Low coefficients describe fog; high coefficients describe random-walk subsurface scattering. Use transmission to let light enter the interior; ior=1, transmission=1, roughness=0 gives an invisible fog boundary rather than a glass interface.

Animation

Construction is immediate and records no animation. Apply the material with mob.set_material(...) before spawning the mob. Afterwards, mob.sigma_s and mob.g are animatable shader parameters, like mob.roughness; coefficients are per scene-length unit, not colors.

Parameters:

  • color – Surface color. Defaults to None, preserving the mob’s existing color.

  • clearcoat – Additional coating strength. Defaults to 0, disabling it.

  • clearcoat_roughness – Coating roughness from 0 to 1. Defaults to 0.

  • ior – Interior index of refraction. Defaults to 1.5; 1 matches air.

  • reflectivity – Compatibility alias for dielectric IOR. Defaults to None, using ior; when supplied, maps to (1 + 0.4*r) / (1 - 0.4*r).

  • specular_intensity – Dielectric specular strength. Defaults to 1.

  • specular_color – Dielectric specular tint. Defaults to WHITE.

  • sheen – Sheen strength. Defaults to 0, disabling it.

  • sheen_roughness – Sheen roughness from 0 to 1. Defaults to 1.

  • sheen_color – Sheen tint. Defaults to BLACK.

  • transmission – Fraction assigned to transmission, from 0 to 1. Defaults to 0. Use 1 for a fully transmitting boundary around a scattering interior.

  • thickness – Stored compatibility value, default 0. The renderer measures actual geometric path lengths instead; this value does not scale scattering.

  • attenuation_color – Color transmitted after attenuation_distance scene units. Defaults to WHITE, giving no absorption. This defines absorption independently of sigma_s.

  • attenuation_distance – Reference absorption distance in scene-length units. Defaults to infinity, disabling absorption; non-positive values also disable it.

  • sigma_s (float | tuple[float, float, float]) – Homogeneous scattering coefficient in inverse scene-length units. Accepts a finite non-negative scalar or three RGB coefficients of shape (3,). Defaults to 0, disabling interior scattering. Values are numerical rates and are never decoded from sRGB. Requires path tracing and geometry declared closed_shell=True; built-in closed solids declare this automatically. Open surfaces are rejected.

  • g (float) – Dimensionless Henyey–Greenstein anisotropy, strictly between -1 and 1. Defaults to 0 (isotropic); positive values favor forward scattering, negative values backscattering. Used only by the scattering interior.

  • iridescence – Approximate iridescence strength. Defaults to 0, disabling it.

  • iridescence_ior – Stored compatibility index for iridescence. Defaults to 1.3.

  • **kwargs – Parameters forwarded to MeshStandardMaterial, including roughness (default 1), metalness (default 0), and texture slots.

Raises:

ValueError – If scattering coefficients are negative, non-finite, or not scalar/RGB, or if anisotropy is non-finite or outside its open interval.

Notes

Scattering is homogeneous, not a density texture. Nested interiors use a fixed four-shell stack with last-entered priority. Overflow is reported and affected paths are absorbed. Increase max_bounces for dense media: both surface and interior scatters spend that shared budget; invisible index-matched boundaries do not. Density fields and diffusion-profile approximations are not implemented.

Examples

Example: PhysicalScatteringSphere 

from algan import *

SETTINGS.raytracing.set(samples_per_pixel=64, max_bounces=32)
sphere = Sphere()
sphere.set_material(MeshPhysicalMaterial(
    color=WHITE, transmission=1, roughness=0.1,
    sigma_s=(2.0, 3.0, 5.0), g=0.2,
))
sphere.spawn()
Scene.save_video()

Methods

get_shader_param_values

Map of {shader_param_name: value} matching this material's shader signature.

shader

MeshPhysicalMaterial: MeshStandard plus clearcoat, sheen, ior-driven specular and (approximate) transmission.

Attributes

applies_color

Whether the material's color should drive the mob's base color.
get_shader_param_values()[source]

Map of {shader_param_name: value} matching this material’s shader signature. Base materials expose no extra parameters.

static shader(memory, vertex_location, vertex_normal, albedo_color, camera_location, light_origin, light_color, light_intensity, ambient_light_intensity, roughness=1.0, metalness=0.0, emissive=(0.0, 0.0, 0.0), emissive_intensity=1.0, env_map_intensity=1.0, flat_shading=0.0, ior=1.5, specular_intensity=1.0, specular_color=(1.0, 1.0, 1.0), clearcoat=0.0, clearcoat_roughness=0.0, sheen=0.0, sheen_roughness=1.0, sheen_color=(0.0, 0.0, 0.0), transmission=0.0, iridescence=0.0, attenuation_sigma=(0.0, 0.0, 0.0), sigma_s=(0.0, 0.0, 0.0), g=0.0)

MeshPhysicalMaterial: MeshStandard plus clearcoat, sheen, ior-driven specular and (approximate) transmission.

ior drives the dielectric base reflectivity F0 = ((ior - 1) / (ior + 1))^2, scaled by specular_intensity and tinted by specular_color (the KHR specular workflow). A second GGX lobe adds the clearcoat. sheen adds a soft inverted-Fresnel rim. The transmission and iridescence parameters are approximated (no refraction / thin-film spectral model in a per-vertex pass). Volumetric absorption is not approximated here at all: it is applied along the refracted path in the renderer, driven by this parameter’s packed slot.

Parameters:

  • light_intensity (float)

  • ambient_light_intensity (float)

  • roughness (float)

  • metalness (float)

  • emissive_intensity (float)

  • env_map_intensity (float)

  • flat_shading (float)

  • ior (float)

  • specular_intensity (float)

  • clearcoat (float)

  • clearcoat_roughness (float)

  • sheen (float)

  • sheen_roughness (float)

  • transmission (float)

  • iridescence (float)

  • g (float)