Iray Programmer's Manual

Implicit groundplane

An additional implicit "shadow catcher" groundplane can be specified. This plane weights the environment contribution of the ground using a progressive estimation of the amount of shadow on the groundplane, caused by the objects in the scene (from direct light only). The mode of the environment lookup itself remains unchanged as it is specified by the environment dome settings. The groundplane is a special case of the more general concept of matte objects.

The groundplane is controlled with the following attributes on the mi::neuraylib::IOptions class, shown here with their default settings:

bool environment_dome_ground = false

Controls whether the implicit groundplane is enabled or not.

mi::Float32_3 environment_dome_ground_position = mi::Float32_3(0,0,0)

The origin of the ground plane.

mi::Color environment_dome_ground_reflectivity = mi::Color(-1,-1,-1,1)

If set to a positive value, enables reflectivity on the groundplane weighted by the fresnel term.

mi::Float32 environment_dome_ground_glossiness = 100000.0

Controls the glossiness of the ground reflectivity. Useful values range from 0 (diffuse) to 10000000.0 (perfect mirror).

mi::Float32 environment_dome_ground_shadow_intensity = 1.0

Controls the intensity of the shadow on the groundplane with a value greater or equal to 0.0. A value of 0.0 denotes no shadow at all and a value of 1.0 denotes regular shadow intensity, thus values between 0.0 and 1.0 denote a lighter shadow. Values above 1.0 increase the shadow intensity. Note that the range of useful values above 1.0 is rather limited and exceeding this range may lead to an unnatural dark shadow that can influence other additive lighting effects, such as reflections of the objects in the scene. The exact useful range is scene dependent.

mi::Float32 environment_dome_ground_texturescale = 0

Used to control the texture projection of the environment on the ground. This can be seen as an equivalent to the distance from ground where the real life camera was placed to take the captured environment map.

bool environment_dome_ground_visible_from_below = true

When set to false, one can see geometry located above the ground plane, even when the camera is placed below it.

bool environment_dome_ground_connect_to_environment = false

Only effective if a backplate function or the backplate color is set. When set to true, secondary interactions with the groundplane will use the environment instead of the backplate.

bool environment_dome_ground_legacy_reflection = true

When set to true, the ground will only reflect objects directly, but not when seen from reflections on other objects. Also, reflections will not replace the (optional) ground shadow, which allows to have highly glossy reflections mixed with diffuse shadowing. For a more physically correct behaviour, setting the option to false will avoid this, but one has to take care to not mix strong ground shadows with a high ground glossiness (which is equivalent to the behaviour of regular matte objects).