Built-in component reference

This section describes build-in components. The label of each entry shows the key with interface::implementation format used in the instantiation of the component. The parameters of the components are given as an argument of Json type to lm::Component::construct() function.

Material

Components implementing lm::Material.

material::diffuse

Lambertian diffuse model.

Parameters

  • mapKd (str) – Diffuse reflectance as texture specified by asset name or locator.

  • Kd (color) – Diffuse reflectance as color value. If both mapKd and Kd are specified, mapKd has priority. Default: [1,1,1].

This component implements Lambertian diffuse BRDF defined as

\[f_r(\omega_i, \omega_o) = \frac{\rho}{\pi},\]

where \(\rho\) is diffuse reflectance.

material::glossy

Cook-Torrance BRDF with anisotropic GGX as NDF.

Parameters

  • Ks (color) – Specular reflectance.

  • ax (float) – \(\alpha_x\) parameter in anisotropic GGX.

  • ay (float) – \(\alpha_y\) parameter in anisotropic GGX.

material::mirror

Ideal mirror reflection.

This component implements ideal mirror reflection BRDF:

\[f_r(\omega_i, \omega_o) = \delta_\Omega(\omega_{\mathrm{refl}}, \omega_o),\]

where \(\omega_{\mathrm{refl}}\equiv2(\omega_i\cdot\mathbf{n})\mathbf{n} - \omega_i\) is the reflected direction of \(\omega_i\), and \(\delta_\Omega\) is the Dirac delta function w.r.t. solid angle measure: \(\int_\Omega \delta_\Omega(\omega', \omega) d\omega = \omega'\).

material::glass

Fresnel reflection and refraction.

Parameters

Ni (float) – Relative index of refraction.

This component implement Fresnel reflection and refraction BSDF, which reads

\[f_s(\omega_i, \omega_o) = F\, \delta_\Omega(\omega_{\mathrm{refl}}, \omega_o) + (1-F)\, \delta_\Omega(\omega_{\mathrm{refr}}, \omega_o),\]

where \(F\) is Fresnel term and \(\delta_\Omega\) is the Dirac delta function w.r.t. solid angle measure. \(\omega_{\mathrm{refl}}\) and \(\omega_{\mathrm{refr}}\) are reflected and refracted directions of \(\omega_i\) respectively defined as

\[\begin{split}\begin{eqnarray} \omega_{\mathrm{refl}} &=& 2(\omega_i\cdot\mathbf{n})\mathbf{n} - \omega_i, \\ \omega_{\mathrm{refr}} &=& -\eta\omega_i + \left[ \eta(\omega_i\cdot\mathbf{n})-\sqrt{1-\eta^2(1-(\omega_i\cdot\mathbf{n})^2)} \right] \mathbf{n}, \end{eqnarray}\end{split}\]

where \(\mathbf{n}\) is the shading normal on a position of the scene surface and \(\eta\) is relative index of refraction: \(\eta\equiv\frac{n_i}{n_t}\) where \(n_i\) and \(n_t\) is the index of refraction of the media on incident and transmitted sides of scene surface respectively.

For Fresnel term, we used Schlick’s approximation [Schlick1994]:

\[\begin{eqnarray} F = R_0 + (1-R_0)(1-(\omega_i\cdot\mathbf{n})^2),\; R_0 = \left( \frac{1-\eta}{1+\eta} \right)^2. \end{eqnarray}\]

Reflection or refraction is determined by sampling Fresnel term.

Schlick1994

C. Schlick. An Inexpensive BRDF Model for Physically-based Rendering. Computer Graphics Forum. 13 (3): 233. 1994.

material::proxy

Proxy material.

Parameters

ref (str) – Asset name or locator of the referencing material.

This component gives proxy interface to the other predefined material. This component is useful when we want to reuse predefined material but we also need to create a new instance.

material::mask

Pass-through material.

This component implements a special material that only sample the outgoing ray into the same direction as the incoming ray. This material is used to implement texture-masked materials. BSDF reads

\[f_s(\omega_i, \omega_o) = \delta_\Omega(-\omega_i, \omega_o).\]
material::proxy

Proxy material.

Parameters

ref (str) – Asset name or locator of the referencing material.

This component gives proxy interface to the other predefined material. This component is useful when we want to reuse predefined material but we also need to create a new instance.

material::constant_weight_mixture_rr

Mixture material with constant weights (using Russian roulette).

Parameters

entries (list) – A list of tupels (material, weight) where material is a locator to the underlying material and weight is the weight multiplied by the BSDF of the material.

material::constant_weight_mixture_marginalized

Mixture material with constant weights (using marginalization).

Parameters

entries (list) – A list of tupels (material, weight) where material is a locator to the underlying material and weight is the weight multiplied by the BSDF of the material.

material::mixture_wavefrontobj

Mixture material for Wavefront OBJ model.

This asset is internally used by the framework.

Camera

Components implementing lm::Camera.

camera::pinhole

Pinhole camera.

Parameters

  • film (str) – Underlying film specified by asset name or locator.

  • position (vec3) – Camera position.

  • center (vec3) – Look-at position.

  • up (vec3) – Up vector.

  • vfov (float) – Vertical field of view.

  • aspect – Aspect ratio (height / width).

This component implements pinhole camera where all the incoming lights pass through an small aperture and projected onto a film in the opposite side of the aperture. Unlike real pinhole camera, the apearture is modeled as a point, and the film can be placed in front of the pinhole.

The configuration of the pinhole camera is described by a 3-tuple by position, center, and up vector. position represents a position of the pinhole, center for look-at position. This means the camera faces toward the direction to center from position. up describes the upward direction of the camera.

Field of view (FoV) describe the extent of the viewing angle of the camera. In this implementation, the configuration is given by vfov parameter. Note that we adopted vertical FoV. Be careful if you want to convert from other tools that might adopt horizontal FoV.

The aspect ratio must be specified as a parameter of the film. If the aspect ratio is different from that can be calculated from the film, the skieed image will be recorded.

Light

Components implementing lm::Light.

light::area

Area light.

Parameters

  • Ke (color) – Luminance.

  • mesh (str) – Underlying mesh specified by asset name or locator.

light::env

Environment light.

Parameters

  • envmap_path (str) – Path to environment map.

  • rot (float) – Rotation angle of the environment map around up vector in degrees. Default value: 0.

light::envconst

Constant environment light.

Parameters

Le (color) – Luminance.

light::point

Point light.

Parameters

  • Le (color) – Luminance.

  • position (vec3) – Position of the light.

light::directional

Directional light.

Parameters

  • Le (color) – Luminance.

  • direction (vec3) – Direction of the light.

Medium

Components implementing lm::Medium.

medium::homogeneous

Homogeneous medium.

Parameters

  • density (float) – Density of the medium.

  • albedo (color) – Albedo of the medium.

  • phase (str) – Locator to phase asset.

  • bound_min (vec3) – Minimum bound of the volume.

  • bound_max (vec3) – Maximum bound of the volume.

medium::heterogeneous

Heterogeneous medium.

Parameters

  • density (str) – Locator to volume asset representing density of the medium.

  • albedo (str) – Locator to volume asset representing albedo of the medium.

  • phase (str) – Locator to phase asset.

Volume

Components implementing lm::Volume.

volume::constant

Constant volume.

Parameters

  • color (color) – Stored color value.

  • scalar (float) – Stored scalar value.

  • bound_min (float) – Minimum bound of the volume.

  • bound_max (float) – Maximum bound of the volume.

volume::checker

Checker volume.

Parameters

  • bound_min (float) – Minimum bound of the volume.

  • bound_max (float) – Maximum bound of the volume.

Phase

Components implementing lm::Phase.

phase::isotropic

Isotropic phase function.

phase::hg

Henyey-Greenstein phase function.

Parameters

g (float) – Asymmetry parameter in [-1,1].

Mesh

Components implementing lm::Mesh.

mesh::raw

Mesh from raw data.

Parameters

  • ps (list) – Vertex positions of the mesh.

  • ns (list) – Vertex normals of the mesh.

  • ts (list) – Texture coordinates for the vertices.

  • fs (dist) – Index list. Indices for each vertex element are specified by p, t, and n respectively.

mesh::wavefrontobj_ref

Mesh for Wavefront OBJ model.

This asset is internally used by the framework.

Texture

Components implementing lm::Texture.

texture::constant

Texture with constant color.

Parameters

  • color (color) – Color.

  • alpha (float) – Alpha value.

texture::bitmap

Bitmap texture.

Parameters

  • path (str) – Path to texture.

  • flip (bool) – Flip loaded texture if true.

Model

Components implementing lm::Model.

model::wavefrontobj

Wavefront OBJ model.

Parameters

path (str) – Path to .obj file.

Acceleration structure

Components implementing lm::Accel.

accel::sahbvh

Bounding volume hierarchy with surface area heuristics.

Features

  • Parallel construction.

  • Split axis is determined by longest axis.

  • Split position is determined by minimum SAH cost.

  • Uses full-sort of underlying geometries.

  • Uses triangle intersection by Möller and Trumbore [Möller1997].

Möller1997

T. Möller & B. Trumbore. Fast, Minimum Storage Ray-Triangle Intersection. Journal of Graphics Tools. 2(1):21–28. 1997.

Film

Components implementing lm::Film.

film::bitmap

Bitmap film.

Parameters

  • w (int) – Width of the film.

  • h (int) – Height of the film.

This component implements thread-safe bitmap film. The invocation of lm::Film::setPixel() function is thread safe.