The Malia Scene Format (MSF) is based on XML and handles assets that include: - Geometries - Materials - Light Sources # Presentation The .msf file store a mrf scene. It is constructed as a flat scene graph. To add a 3d object in a mrf scene you need use the ``, `` and `` nodes. The `` node lets you instantiate a 3D geometry from a .obj or .ply file. The `` node gives you the ability to reference a mesh and put it somewhere in your scene using the `` node. Here is an example: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XML ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ # Geometries ## Shape and Mesh At the moment MRF supports Mesh, Mesh instancing and analytical sphere. All geometrical elements in a .msf file appear inside a `` markup: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XML ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each geometrical element must be defined inside `` markup. A shape markup contains either a sphere or a mesh markup and eventually a geometrical transformation (with `` markup). A shape markup must reference a material defined in the XML file. Here is a partial example of a shape that includes a geometrical transformation: The special case of mesh instancing is detailed below. ## Analytical Sphere Example Analytical spheres are defined using one the two following syntaxe, either with a markup position (for the sphere center): or with attributes specifying the sphere center: ## Mesh Example A mesh is defined inside a shape markup by using the mesh markup this markup contains either an obj markup to load an OBJ file: or a ply markup to load a ply file: The name attribute must be present to use the mesh instancing mechanism. ## Mesh Instancing Example An mesh instanciation is provided in mrf. You can use the wml attribute `ref_mesh` to reference a mesh that was previously declared in the scene. Here is an example: Internally here is how we store the scene in mrf: # Materials ## Overview All materials are declared inside `` nodes, within the `` group. The material type is specified as an attribute when constructing the node ``. Most materials require to specify colors parameters. A color parameter is set using a sub-element: - `` for RGB mode, with r, g and b attributes (``) - `` for spectral mode, with either a spectrum file attribute (``) of by specifying the spectrum ramp as a value attribute (``). ## Analytical BSDF Here is the list of analytical BSDF present in Malia: - Lambert BSDF - CheckerBoard - Perfect Mirror - Fresnel Conductor - Microfacet Conductor - Fresnel Dielectric - Microfacet Dielectric - Normalized Phong - Principled ### Perfect Diffuse Material aka Lambert A Lambert material is defined by 2 parameters (as sub-elements): - its albedo (the proportion of reflected energy, the rest is absorbed) - its reflectance color: in rgb or in spectral. Here is a exemple, using a .spd file to specify the spectrum: It also possible to specify a piece-wise linear function (wavelength_1:value, ..., wavelength_n:value) spectrum instead of a file: ### Checkerboard A checkerboard has alterning square pattern composed of two Lambert color. As such, it has 3 parameters: - its repetition (attribute): the number of squares per continuous plane. - its first reflectance color (sub-element): in rgb or in spectral. - its second reflectance color (sub-element): in rgb or in spectral. Here is a exemple: ### Perfect Mirror A perfect mirror simply reflect light following a dirac distribution, without any attenuation. Here is a exemple: ### Fresnel Reflector aka FresnelMirror A Fresnel reflector is perfect (smooth) mirror with a fresnel coeffient computed from the index of refraction. This type of material is specified in the scene file with its Index of Refraction (IOR), inside a `` sub-element, with two color sub-elements: - `` for real-part of the IOR - `` for imaginary-part of the IOR ### Microfacet-based Conductors A microfacet conductor in MRF is defined using: - the chosen distribution as attribute (into "type"). - the roughness parameter is passed as attribute (into "alpha_g" for isotropic, "alpha_x" and "alpha_y" for anisotropic). - its Index of Refraction (IOR), inside a `` sub-element, with two color sub-elements: - `` for real-part of the IOR - `` for imaginary-part of the IOR At the moment, only GGX distribution is supported, more distribution will be added. ### Fresnel dielectric A Fresnel dielectric is perfect (smooth) glass with a fresnel coeffient computed from the index of refraction. This type of material is specified in the scene file with its Index of Refraction (IOR), inside a `` sub-element, with two color sub-elements: - `` for real-part of the IOR - `` for imaginary-part of the IOR For dielectric material, the imaginary part will cause absorption. It is related to Beer-Lambert: $$ T_{kappa}(d) = e^{-\frac{4 \pi \kappa(\lambda)}{\lambda} d} $$ For convenience, design or artistic purpose, one can also specify an absolute extinction coefficient (as used by Blender for instance). One can use the `` sub-element. This coefficient is used to compute the transmittance between two interfaces as: $$ T_{extinction} = 1 - extinction$$ The effective transmittance is then: $$ T(d) = T_{kappa}(d) T_{extinction}$$ When the material is perfectly know, the extinction xml element should eihter be set to 0 or even omitted. !!! A Fresnel dielectric can be used only if the shape has volume (all interfaces must exist geometrically). That is to say, it must not be applied to a shape composed of a single plane. If you want this behavior, use Fresnel thin dielectric instead: - ``. This variant emulates the presence of two interfaces, meaning the ray direction is not changed by crossing it, but it will be spatially shifted, and its radiance attenuated according to the glass thickness. Currently, the thickness (x2-x1) is not controllable and is set to 1, it will be in a future version. Exemple: a window can be represented in the scene with only a quad (two triangles), thus having no geometrical thickness. ### Microfacet-based dielectric Aka WalterBSDF, in MRF is defined using: - the chosen distribution as attribute (into "type"). Limited to GGX for now. - the roughness parameter is passed as attribute (into "alpha_g" for isotropic, "alpha_x" and "alpha_y" for anisotropic). - its Index of Refraction (IOR), inside a `` sub-element, with two color sub-elements: - `` for real-part of the IOR - `` for imaginary-part of the IOR - its extinction inside a '' sub-element, with a color sub-element. See [Fresnel Dielectric](/scene_format.md.html#toc3.2.6). ### Normalized Phong This material implements the energy conserving version of the Phong BRDF (cf. [Lafortune1997]) : !!! The Phong material can be used with textures for spatially varying diffuse, specular, shininess and/or normal map: Note that the textures are modulated by there corresponding attribute for colors and the exponent to allow for spatial variations: - diffuse color is diffuse_color * diffuse_texture - specular color is specular_color * specular_texture - exponent color is exponent * exponent_map ### Principled Aka Disney's BSDF [Burley12], in MRF, is defined using: - the chosen distribution as attribute (into "type"). Limited to GGX for now. - its base color inside a `` sub-element, with a color sub-element. The base color is the overall surface color. - its different parameters (ranging from 0 to 1) inside associated sub-element (definition from [Burley12]): - ``: "surface roughness, controls both diffuse and specular response." - ``: "controls diffuse shape using a subsurface approximation." - ``: "an additional grazing component, primarily intended for cloth." - ``: " amount to tint sheen towards base color." - ``: "the metallic-ness (0 = dielectric, 1 = metallic). This is a linear blend between two different models. The metallic model has no diffuse component and also has a tinted incidentspecular, equal to the base color." - ``: "incident specular amount. This is in lieu of an explicit index-of-refraction." - ``: "a concession for artistic control that tints incident specular towards the base color. Grazing specular is still achromatic." - ``: "degree of anisotropy. This controls the aspect ratio of the specular highlight (0 = isotropic, 1 = maximally anisotropic)." - ``: "a second, special-purpose specular lobe." - ``: "controls clearcoat glossiness (0 = a satin-like appearance, 1 = a gloss-like appearance)." Note for both sheen and specular tint, the colored response is the achromatic radiance of base color if set to 0 and equal to the base color if set to 1. In-between, a linear interpolation is performed. ## Measured BRDF Here is the list of measured BSDF supported in Malia: - ALTA BRDF (isotropic) - UTIA BRDF ### Isotropic ALTA BRDF The Measured Isotropic material supports the loading of alta file (.bin) with a $(\theta_{view},\theta_{light}, \Delta\phi = |\phi_{view} - \phi_{light}| )$ parametrization. To simplify scene authoring, both RGB and spectral data can be specify in the same node. This allows a scene to work both in rgb rendering mode and spectral rendering mode. The xml attribute file_rgb specify the alta rgb file whereas file_spectral specify the alta spectral file. You can, for instance, instantiate a Measured Isotropic material using the following code: !!! WARNING: In some scene you might find a xml attribute "file" to specify the input alta file, it overrides the "file_rgb" or "file_spectral" attribute. #### Example of supported ALTA file An ALTA file (./material_export_assets/brdf_measured_SPECTRAL.bin in the example above) consists of a header part that specifies and describes how the data part can be read. Malia implements only a subset of the ALTA format but it already supports RGB and Spectral BRDF when sampled (or measured) inside a regular multi-dimensional grid. An Header file example for a RGB BRDF is: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Bash #ALTA_BEGIN_HEADER #DIM 3 3 #PARAM_IN ISOTROPIC_TV_TL_DPHI #PARAM_OUT RGB_COLOR #VS 0 #MIN_DIM 0 0 0 #MAX_DIM 1.5621 1.5621 6.2657 #GRID 180 180 360 #VERSION 0 #FORMAT binary #ENDIAN little #PRECISION ieee754-single #ALTA_END_HEADER // BINARY DATA STARTS HERE ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ where : - `#PARAM_IN ISOTROPIC_TV_TL_DPHI` specifies a classical parametrization in terms of angle $(\theta_{view},\theta_{light}, \Delta\phi = |\phi_{view} - \phi_{light}| )$. $\theta$ angles are zenithal angles whereas $\phi$ angles are azimuthal ones. - `GRID 180 180 360` : specifies the grid resolution for the current parametrization defined by `#PARAM_IN`. In this example the number of discreet values for $\theta_{view}$ and $\theta_{light}$ (resp. $\Delta\phi$) is set to 180 (resp. 360). - `MIN_DIM` and `MAX_DIM` represent the validity domain of the binary data for each dimension specified by `#PARAM_IN`. These boundaries are NOT the boundaries of the parametrization. These keywords are currently ignored. The binary data layout follows the parametrization ($\theta_{view}$ first then $\theta_{light}$ then $\Delta\phi)$ and stores for each angular configuration the value of the BRDF for all specified wavelengths: $\underbrace{brdf(\lambda_0) brdf(\lambda_{1})... brdf(\lambda_{number\_of\_wavelength-1})}_{\theta_{v_0},\theta_{l_0},\Delta\phi_0}\underbrace{brdf(\lambda_0) brdf(\lambda_{1})... brdf(\lambda_{number\_of\_wavelength-1})}_{\theta_{v_1},\theta_{l_0},\Delta\phi_0}$... where : - $\theta_{view} \in \{\theta_{v_0},\theta_{v_1},...,\theta_{v_{n_v}}\}$ - $\theta_{light} \in \{\theta_{l_0},\theta_{l_1},...,\theta_{l_{n_l}}\}$ - $\Delta\phi \in \{\Delta\phi_{0},\Delta\phi_{1},...,\Delta\phi_{n_\phi}\}$ #### Spectral BRDF as an ALTA FILE In the case of a spectral BRDF, the sampled wavelengths should be specified in the header by the keyword WAVELENGTH (in nanometers): ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Bash #WAVELENGTH 360 370 380 390 400 410 420 430 440 800 810 820 830 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Furthermore, the output parametrization should be : ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Bash #PARAM_OUT INV_STERADIAN ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ### Analytical BRDF inside an ALTA file Although, this file format is intended for measured and simulated data, the header can also describes a perfect MIRROR BRDF. The final BRDF is given by: $$brdf(v,l) = \frac{\delta(v, refl(l))}{cos\theta_l} + Tabulated\_BRDF(v,l)$$ where $\delta$ is a dirac function. This mirror BRDF is specified with the keyword #THETA_INCI (in radians), which lists de different incident angles for which the keyword #DIRAC lists the different values of the BRDF for each specified wavelength. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Bash #THETA_INCI 0 0.0087266 0.017453 0.02618 0.034907 0.043633 0.05236 #DIRAC 0.01574565123 0.01965223287 0.02135815392 0.01776516884 0.01286714035 0.009298721691 0.007492583768 0.006895266087 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The expected number of values after #DIRAC must be equal to : $number\_of\_wavelength \times number\_of\_theta\_incident$. Note that it is also possible to specify a perfect MIRROR BRDF for RGB-BRDF (i.e., #PARAM_OUT RGB_COLOR), the Malia parser will expect 3 values per incident angles instead of number_of_wavelength. By default Malia will use all parts (analytical and measured) of an alta file to generate the image. Example to render only the Dirac part of the material: Example to render only the scattering part of the material: ### UTIA BRDF Example of UTIA materials, both 2D (isotropic) and 4D (anisotropic): ## Shadow Catcher The shadow catcher is a proxy material to project shadows on the environment. It must be use with a plane geometry. ## Emissive Materials Emissive materials are defined with the `` markup. The table below lists the allowed possibile values for the attribute type: XML Type (.msf file) | MRF (C++ class) ------------------|---------------- diffuse/uniform | DiffuseEmittance conic | ConicalEmittance dirac | DiracEmittance The table below lists for each emissivity type (row) which rendering back-end (column) supports it: XML Type | Native CPU | Optix | Embree | RadeonRays ---------|-------------|-------|--------|------------ Diffuse/Uniform | X | X | | Conic | X | | | Dirac | X | X | | Here is an example of a uniform (diffuse) emittance: The `` defines a scalar value that is multiplied to the color (in RGB mode) or the spectrum (in spectral mode). Hence, the final color (resp. spectrum) is given by: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ C++ final_color = rgb_color* radiance.value final_spectrum = spectrum * radiance.value ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Note that emittance materials need to be defined inside a light source markup (e.g., ``, ``) # Indexed Material A single mesh may use several materials on a per-face basis. MRF handles this situation by using a proxy material aggregating all these materials. This proxy material is declared as: All the materials must be present as sub-element of the multi-material. There two ways of doing so. The first is to declare the materials independently (using the "material" markup and information above) and just reference them by name below the multi-material element: It is the syntax used by our blender bridge. The order between in which the single materials and the multi-material are declared is not important. The second is to declare the materials directly under the multi-material element: Both ways are equivalent whatever the scene configuration. All type of materials supported by MRF are also supported as sub-elements of a multi-material. !!! WARNING Avoid recursivity - Undefined behavior Using a multi-material as a sub-element of another multi-material leads to undefined behavior and should be avoided. Then only the proxy multi-material is attached to the shape: !!! WARNING Limited support for PLY The support of PLY must be done manually by adding a "mat_idx" property to faces elements. In that case, the materials must be referenced by the multi-material in the exact same order as their index in the PLY (e.g., in the examples above, "mat1" must correspond to material index "0" in the PLY). If you can, prefer the OBJ mesh format, for which as long as materials have the same name in the material file and in MRF, the match between faces and materials is guaranteed regardless of the order. !!! Note No support of RTCores At the moment, this type of material does not exploit RTCores for ray-tracing acceleration in our implementation. If you experience slow performance, consider splitting you mesh beforehand to fall back to a collection of meshes with single material. The full support of RTCores is scheduled for a future version. # Light sources All the light sources are stored in the Scene object. Several types of light sources are supported: - Point light - Directional light - Background and Environment map - Quad light - Sphere light Note that some backends might not support all of these light types. ## Point Light Represent a single point in space light source, thus, it has no geometry. It does not represent a physical light source. !!! WARNING This type of light source is currently not supported in the Malia Rendering Engine with the OptiX backend. !!! WARNING Replace your point light sources with spherical light sources of small radius. ## Directional Light Represent an emitter, far away from the scene, it has no position nor geometry. It represents a dirac emitter that emits light in only one direction. Directional Light can be quickly defined by defining a Dirac emittance inside a `` markup: ## Quad light A light which shape is represened by a quadrilateral (i.e., a polygon with four edges). Below is a simple example to define a quad light: By default the shape of the light source is a unit square centered at (0,0,0) which normal is along the Z axis (i.e., (0,0,1)) As explained abobe, you can also always replace the content of the spectrum markup with a file: Finally, any type of geometrical light source markups (sphere_light, area_light ) may contain a transformation markup to apply geometrical transformations to change its position and size: ## Sphere Light A light which shape is represened by a sphere. XML Example : ## Background and Environment map You can add a constant background using the background node, here is an example: You can add an environment to you scene using the ext_resources and the background node. Both spectral and rgb envmap can be specified in the scene file, the backend will use the appropriate one. Here is an example of how to specify both spectral and rgb envmap in a scene. # Paths to external resources While using an external resources such as an environment map, or loading a file for a Measured Isotropic BRDF, you may need to add some resources path. This can be done using the XML tag `` inside ``. To retrieve a file mrf applies the following rules: - Paths are always relative to the scene file (.msf) folder which is considered as the current directory. - (First try) First mrf will try to load your file in the current directory and adding at the end of the path, the relative path specify in your xml attribute file="..." - (Second try) If not found tries from currrent_directory + a_resource_path + relative_path_to_your_file - (Third try) If not found tries from currrent_directory + a_resource_path + name_of_your_file The name_of_your_file is deduced from the relative_path_to_your_file by removing all the previous directory in it. For instance the following code: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ XML ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ in the file /c/mrf/scenes/myscene.msf will try to look for the file green_point_park_4k.hdr in: - (First try) /c/mrf/scenes/env/green_point_park_4k.hdr - (Second try) /c/mrf/scenes/materials/env/green_point_park_4k.hdr - (Second try) /c/mrf/scenes/../envmaps/env/green_point_park_4k.hdr (equivalent to /c/mrf/envmaps/env/green_point_park_4k.hdr) - (Third try) /c/mrf/scenes/materials/green_point_park_4k.hdr - (Third try) /c/mrf/scenes/../envmaps/green_point_park_4k.hdr (equivalent to /c/mrf/envmaps/green_point_park_4k.hdr)