Material Definition

This is the documentation of Roomle's V2 material. If you are looking for information on legacy materials, look here.

Materials in Roomle are JSON files with defined attributes. One main material JSON and several texture JSON files (one for each texture variant).

Material JSON

material.json

{
    "version":"2.0.0",
    "basecolor": {
        "b": 0.9,
        "g": 0.9,
        "r": 0.9
    },
    "roughness": 0.85,
    "metallic": 0,
    "alpha": 1.0,
    "alphaMode":"OPAQUE",
    "transmission": 1.0,
    "transmissionIOR": 1.52,
    "alphaCutoff": 0.5,
    "doubleSided": true,
    "occlusion": 1.0,
    "emissiveColor":{
       "r":0.0,
       "g":0.0,
       "b":0.0
    },
    "emissiveIntensity":1.0,
    "clearcoatIntensity":0.0,
    "clearcoatRoughness":0.0,
    "clearcoatNormalScale":0.0,
    "sheenColor":{
       "r":0,
       "g":0,
       "b":0
    },
    "sheenIntensity":0.0,
    "sheenRoughness":0.65,
    "normalScale":1.0,
    "thicknessFactor":0.0,
    "attenuationColor":{
       "r":0,
       "g":0,
       "b":0
    },
    "attenuationDistance":0.0
}

Base color

Base color in sRGB color space

If a diffuse texture is present, its texel values will get multiplied with the basecolor in linear color space.

For diffuse reflection, avoid extreme values (0.0 or 1.0) and leave some headroom (min:0.04 and max:0.9).

Example: default white

"basecolor": {
    "b": 0.9,
    "g": 0.9,
    "r": 0.9
},

Roughness

0.0 is perfectly smooth with sharp reflections

1.0 is completely matte/dull surface due to lots of microsurface scattering

Default 0.85

"roughness": 0.85,

Metallic

Metallness of material

1.0 for metals

0.0 for dielectrics

A physical material is always either metal or non-metal (conductor or dielectric). Mixed values only make sense to mimic the appearance of layered materials (e.g. a bit of dust on a metal surface)

Default 0.0

"metallic": 0,

Alpha / Opacity

Opacity factor

0.0 is completely invisible

1.0 completely opaque (the default)

"alpha": 1.0,

Alpha Mode

Mode how the material is calculated over the background. If now transparency is used in a material stay at default OPAQUE. Possible values are OPAQUE, BLEND, and MASK.

"alphaMode": "OPAQUE",

Alpha / Transmission

Transmission factor. Useful for creating transparent materials like glass.

If an object is transmissive, its basecolor is used as transmissive color. This is useful to create colored glass.

0.0 fully opaque (the default) 1.0 is completely transmissive with (fresnel) reflections and specular highlights

transmissionIOR is the transmissive index of refraction (IOR), controlling the angle in which light is refracted when entering/leaving. At the moment this won't have effect in real-time renderings.

Default is IOR of plate glass ( https://en.wikipedia.org/wiki/List_of_refractive_indices )

Example: clear glass (assuming the basecolor is completely white)

"transmission": 1.0,
"transmissionIOR": 1.52,

Real-time render related

Alpha cutoff

Alpha testing - use with alpha channel (opacity) texture

Fragment only gets rendered if alpha value is greater than this value.

defaults to 0.0, meaning no alpha cutoff

"alphaCutoff": 0.5,

Double sided

By default in real-time renderings a back-face culling is applied. This means polygons/triangles are only visible from one side. If doubleSided is true, they are visible from both sides.

Useful for billboards, semi-transparent fabrics or plant leaves.

Default: false

"doubleSided": true,

Occlusion strength

If an occlusion texture is present, its values are scaled by this factor.

0 results in no occlusion, 1.0 is full occlusion (default).

"occlusion": 1.0

Emissive Color (RGB multiplier)

Emissive parts of the mesh appear shadeless. This color is an RGB multiplier for an emission map and the result is also multipied by the Emissive Intensity

Emission Map * Emissive Color * Emissive Intensity = EMISSION RESULT

so if either of the values is 0.0 or #000000 the result will be #000000 meaning NO EMISSION

"emissiveColor":{
    "r":0.0,
    "g":0.0,
    "b":0.0
}

Emissive Intensity (multiplier)

Multiplier for Emission Map and Emissive Color [0.0 to 1.0]

"emissiveIntensity":1.0

Clearcoat Intensity (multiplier)

Multiplier for the clearcoat intensity map (CCRG) [0.0 to 1.0]

"clearcoatIntensity":0.0

Clearcoat Roughness (multiplier)

Multiplier for the clearcoat roughness map (CCRG) [0.0 to 1.0]

"clearcoatRoughness":0.0

Clearcoat Normal Scale (multiplier)

Multiplier for the clearcoat normal map (CCXYZ) [0.0 to 1.0]

"clearcoatNormalScale":0.0

Sheen Color (RGB)

Color of the sheen effect

"sheenColor":{
    "r":0,
    "g":0,
    "b":0
}

Sheen Intensity

intensity of the sheen effect

"sheenIntensity":0.0

Sheen Roughness

Factor on how wide spread the sheen effect appears [0.0 to 1.0]

"sheenRoughness":0.65

Thickness Factor

This is a number that defines the thickness of the volume beneath the surface. It is given in the coordinate space of the mesh. If the valuis 0, the material is thin-walled; otherwise, it is a volume boundary. The range is [0.0 to 1.0]`

"thicknessFactor":0.0

Atenuation Color

Defines the color that white light turns into due to absorption when reaching the attenuation distance. It is a color value that changes the appearance of the material as light passes through it.

"attenuationColor":{
    "r":0,
    "g":0,
    "b":0
}

Attenuation Distance

This property specifies the distance at which the full attenuation effect is applied. Light traveling through the material will be absorbed more as it travels further, resulting in a darker color at greater distances. [0.0 to 1.0]

"attenuationDistance":0.0

Texture JSON

Here is a example texture file:

texture.json

{
    "width": 256,
    "height": 256,
    "tileable": 1,
    "url": "https://catalog.roomle.com/51a8755d-8732-4a16-9e23-ac44c0f1cf56/textures/6377/image.jpg",
    "mmHeight": 100,
    "mmWidth": 100,
    "mapping": "RGB"
}

Resolution

Width and height in pixels

"width": 256,
"height": 256,

Tileable

If 1, texture repeats itself in both axes Default: 0

"tileable": 1,

URL

URL of image file

"url": "https://catalog.roomle.com/51a8755d-8732-4a16-9e23-ac44c0f1cf56/textures/6377/image.jpg",

Size

Real world width/height.

Necessary for universal texture application with correct scaling/sizing. The idea is that this texture/material can be applied to many different objects with a consistent size/scaling appearance as long as they fulfill this requirements:

• The UVs are absolute in a certain unit (millimeter in our case)

Default: 0.0 (results in a uniform texture scale of 1.0, ordinary/normalized UV application)

"mmHeight": 100.0,
"mmWidth": 100.0,

Explanatory example

A 3D quad has the measurement 10 cm by 20 cm. Its correct UVs are in the rect x:0/y:0 to x:100/y:200. The texture we want to apply spans 50 by 50 mm.

The resulting texture tileable will be x = 50; y = 50. This way the texture is tiled twice on the x axis and 4 times on the y axis.

Mapping

Describes how texture channels are mapped to material channels.

• RGB: Albedo color

• RGBA: Albedo color plus alpha channel (opacity)

• XYZ: Normal map (Open GL style Y-up)

• ORM: Combined occlusion/roughness/metallic map (similar to glTF 2.0 specification)

• EMRGB: Emission color

• CCRG: Clear coat intensity and roughness

• CCXYZ: Clear coat normal map

• SHRGBA: Sheen color and roughness

• SPRGBA: Specular color and intensity

• TTRG: Transmission degree and thickness

Texture channel assignments

	red	green	blue	alpha
RGB	basecolor red	basecolor green	basecolor blue	-
RGBA	basecolor red	basecolor green	basecolor blue	alpha
XYZ	normal x	normal y	normal z	-
ORM	occlusion	roughness	metallic	-
EMRGB	emissive color red	emissive color green	emissive color blue	-
CCRG	clear coat intensity	clear coat roughness	-	-
CCXYZ	clear coat normal map x	clear coat normal map y	clear coat normal map z	-
SHRGBA	sheen effect color r	sheen effect color g	sheen effect color b	sheen effect roughness
SPRGBA	specular color r	specular color g	specular color b	specular intensity
TTRG	Transmission degree	transmission thickness	-	-

Default: RGB

"mapping": "RGB"

Occlusion Roughness Metallic composition

Graphical explanation of composing a combined ORM texture

The texel values are in linear color space and are multiplied with their respective factor property values:

• Metallic texel values are multiplied with the metallic factor value.

• Occlusion texel values are multiplied with the occlusion strength factor value.

• Roughness texel values are multiplied with the roughness factor value.

The occlusion is used in real-time rendering only.

Appendix

• Change log

• Feature ideas

• References

• Research resources