Class representing object "labels" for rendering.
In a "label image" (see RenderEngine::RenderLabelImage() for details) each pixel value indicates the classification of the object that rendered into that pixel. The RenderLabel class provides that value and one label is associated with each rendered geometry.
The labels could be unique for each geometry, or multiple geometries could all share the same label (becoming indistinguishable in the label image). Ultimately, it is the user's responsibility to assign labels in a manner that is meaningful for their application.
Reserved labels
There are several RenderLabels that are reserved. They have specific meaning in the context of the rendering ecosystem and are globally available to all applications. They are:
- empty: a pixel with the empty RenderLabel value indicates that no geometry rendered to that pixel. Implemented as RenderLabel::kEmpty.
- do not render: any geometry assigned the do not render tag will not be rendered into a label image. This is a clear declaration that a geometry should be omitted. Useful for marking, e.g., glass windows so that the visible geometry behind the glass is what is included in the label image. Implemented as RenderLabel::kDoNotRender.
- don't care: the don't care label is intended as a convenient dumping ground. This would be for geometry that should render into the label image, but whose class is irrelevant (e.g., the walls of a room a robot is working in or the background terrain in driving simulation). Implemented as RenderLabel::kDontCare.
- unspecified: a default-constructed RenderLabel has an unspecified value. Implemented as RenderLabel::kUnspecified.
Generally, there is no good reason to assign empty or unspecified labels to a geometry. A RenderEngine implementation is entitled to throw an exception if you attempt to do so.
Usage
An application can simply instantiate RenderLabel with an arbitrary value. This allows the application to define a particular mapping from render label class to a preferred RenderLabel value. For a label image to be meaningful, every pixel value should admit an unambiguous interpretation. The application bears full responsibility in making sure that a single value is not inadvertently associated with multiple render classes. Finally, a RenderLabel cannot be explicitly constructed with a reserved value – those can only be accessed through the static methods provided.
- Note
- The RenderLabel class is based on a 16-bit integer. This makes the label image more compact but means there are only, approximately, 32,000 unique RenderLabel values.
