|
Drake
|
|
Drake
|
Construction parameters for the RenderEngineVtk.
#include <drake/geometry/render_vtk/render_engine_vtk_params.h>
Public Member Functions | |
| template<typename Archive > | |
| void | Serialize (Archive *a) |
| Passes this object to an Archive. More... | |
Public Attributes | |
| std::optional< Eigen::Vector4d > | default_diffuse {} |
| The (optional) rgba color to apply to the (phong, diffuse) property when none is otherwise specified. More... | |
| Eigen::Vector3d | default_clear_color {204 / 255., 229 / 255., 255 / 255.} |
| The rgb color to which the color buffer is cleared (each channel in the range [0, 1]). More... | |
| std::vector< render::LightParameter > | lights |
| Lights in the scene. More... | |
| std::optional< EnvironmentMap > | environment_map |
| An optional environment map. More... | |
| std::optional< double > | exposure {} |
| Exposure is an aspect of "tone mapping" (as described in VTK's description of its PBR capabilities). More... | |
| bool | cast_shadows {false} |
If true, all lights that are able to cast shadows will do so. More... | |
| int | shadow_map_size {256} |
| The size of texture map (in pixels) to use for shadow maps. More... | |
| bool | force_to_pbr {false} |
| RenderEngineVtk can use one of two illumination models: Phong or Physically based rendering (PBR). More... | |
| string_map< GltfExtension > | gltf_extensions |
| Map from the name of a glTF extension (e.g., "KHR_materials_sheen") to render engine settings related to that extension. More... | |
| std::string | backend |
| Controls which graphics library will be used to perform the rendering. More... | |
| void Serialize | ( | Archive * | a | ) |
Passes this object to an Archive.
Refer to YAML Serialization for background.
| std::string backend |
Controls which graphics library will be used to perform the rendering.
Permissible values are the empty string (default), "GLX", "EGL", and "Cocoa". Any other value will throw an error.
By default (i.e., when set to the empty string) the render engine will choose which library to use. At the moment the default is "Cocoa" on macOS and "EGL" on Linux.
If the option is set to one of the permissible values but the related graphics library has not been compiled into current build (e.g., "GLX" on macOS), then the default choice (empty string) will be used instead, with a warning.
| bool cast_shadows {false} |
If true, all lights that are able to cast shadows will do so.
Several important notes when designing your lighting:
- Point lights do not cast shadows. - Spot lights will not cast shadows if the spot light angle is 90 degrees or more. At 90 degrees, the spot light is now a half-point light. Even though 89.9 degrees _would_ enable shadows, it is still an impractical value. To actually see shadows, the `shadow_map_size` value would have to be absurdly large to support such a wide extent. - Directional lights will create a shadow map that spans the whole scene. If your scene includes a geometry that is significantly larger than the locale you're rendering, this will significantly reduce the efficacy of the directional light's shadows. Consider truncating that larger geometry. A common case would be to use a HalfSpace to define a ground. A half space has infinite extent, so any reasonable approximation would be quite large. Better to use a box targeted to where you need it. - Transparent objects cast no shadows at all, but they do receive them.
Currently, there is no way to enable/disable shadows on a per-light basis.
| Eigen::Vector3d default_clear_color {204 / 255., 229 / 255., 255 / 255.} |
The rgb color to which the color buffer is cleared (each channel in the range [0, 1]).
The default value (in byte values) would be [204, 229, 255].
| std::optional<Eigen::Vector4d> default_diffuse {} |
The (optional) rgba color to apply to the (phong, diffuse) property when none is otherwise specified.
Note: currently the alpha channel is unused by RenderEngineVtk.
| std::optional<EnvironmentMap> environment_map |
An optional environment map.
When providing the environment map, the render engine will be configured for physically-based rendering (PBR); all materials will be promoted to be a PBR material. This may change the appearance of any geometries introduced as primitives or .obj meshes.
Furthermore, if an environment map is specified, it replaces the default lighting (the map itself illuminates the scene). The usual camera head lamp will not be present. Lights can be explicitly added to combine with the environment map.
| std::optional<double> exposure {} |
Exposure is an aspect of "tone mapping" (as described in VTK's description of its PBR capabilities).
Drake uses the GenericFilmic tone mapper and this value maps to its exposure property.
By default, exposure is undefined and no tone mapping is applied to the image. Providing any value at all will enable tone mapping and can be done so whether your scene uses default Phong illumination model or physically-based rendering (e.g., such as when an environment map is present or a glTF model has been added).
This property is analogous to the concept of "exposure" in traditional photography. Exposure controls how much the film material is exposed to the light in the scene. Too little exposure and the scene is dark and muddy. Too much exposure, and the image becomes over saturated. As the amount of radiant energy in the scene increases, reducing the exposure may be necessary. In essence, exposure serves as a scale factor on the radiant energy. When thinking about it as a scale factor, it may seem that setting exposure to one would leave the image unchanged (with respect to the images that RenderEngineVtk has historically produced). This is not the case. As noted above, setting any value, including one, enables tone mapping. Without tone mapping enabled, there is a direct correlation between radiant energy on the surface and the final pixel colors. Tone mapping defines a non-linear relationship between illumination levels and pixel color.
The most common use for the exposure parameter is to combine an environment map with shadow-casting lights. If the environment map contains a great deal of light energy, it may overpower the strength of your lights. By reducing the exposure (below one), the shadows caused by the lights will become more distinct.
If you plan on working with shadows and environment maps, best practice will be to set exposure to one and enable tone mapping. You can increase the value if your image seems too dark, or reduce the value if it seems "washed out".
| bool force_to_pbr {false} |
RenderEngineVtk can use one of two illumination models: Phong or Physically based rendering (PBR).
It defaults to Phong. However, it automatically switches to PBR if:
- an environment map is added, or - a glTF mesh is added.
If force_to_pbr is set to true, it switches the engine to use PBR regardless of the scene's contents.
Be aware, switching to PBR will lead to a qualitative change in rendered images even if literally nothing else changes.
| string_map<GltfExtension> gltf_extensions |
Map from the name of a glTF extension (e.g., "KHR_materials_sheen") to render engine settings related to that extension.
| std::vector<render::LightParameter> lights |
Lights in the scene.
If no lights are defined, a single directional light, fixed to the camera frame, is used.
Note: RenderEngineVtk does not have a hard-coded limit on the number of lights; but more lights increases rendering cost. Note: the attenuation values have no effect on VTK directional lights.
| int shadow_map_size {256} |
The size of texture map (in pixels) to use for shadow maps.
Note: this is a global setting. All shadow casting lights will use a map of the same size. Larger map sizes increase GPU memory usage and rendering times but improve shadow fidelity (less obvious pixelation).
See the note on cast_shadows for the warning on directional lights and shadow maps.