Drake
RenderLabel Class Reference

Detailed Description

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.

#include <drake/geometry/render/render_label.h>

Public Types

using ValueType = systems::sensors::ImageTraits< systems::sensors::PixelType::kLabel16I >::ChannelType
 

Public Member Functions

 RenderLabel ()=default
 Constructs a label with the reserved unspecified value. More...
 
 RenderLabel (int value)
 Constructs a label with the given value. More...
 
bool operator== (const RenderLabel &other) const
 Compares this label with the other label. More...
 
bool operator!= (const RenderLabel &other) const
 Compares this label with the other label. More...
 
bool operator< (const RenderLabel &other) const
 Allows the labels to be compared to imply a total ordering – facilitates use in data structures which require ordering (e.g., std::set). More...
 
bool is_reserved () const
 Reports if the label is a reserved label. More...
 
 operator ValueType () const
 Implicit conversion to its underlying integer representation. More...
 
Implements CopyConstructible, CopyAssignable, MoveConstructible, MoveAssignable
 RenderLabel (const RenderLabel &)=default
 
RenderLabeloperator= (const RenderLabel &)=default
 
 RenderLabel (RenderLabel &&)=default
 
RenderLabeloperator= (RenderLabel &&)=default
 

Static Public Attributes

The reserved render labels

See class documentation on reserved labels for details.

static const RenderLabel kEmpty
 See Reserved labels. More...
 
static const RenderLabel kDoNotRender
 See Reserved labels. More...
 
static const RenderLabel kDontCare
 See Reserved labels. More...
 
static const RenderLabel kUnspecified
 See Reserved labels. More...
 
static const ValueType kMaxUnreserved
 The largest value that a RenderLabel can be instantiated on. More...
 

Friends

class RenderEngine
 
template<class HashAlgorithm >
void hash_append (HashAlgorithm &hasher, const RenderLabel &item) noexcept
 Implements the hash_append generic hashing concept. More...
 
std::ostream & operator<< (std::ostream &out, const RenderLabel &label)
 Enables use of labels with the streaming operator. More...
 
std::string to_string (const RenderLabel &label)
 Converts the RenderLabel value to a string representation. More...
 

Member Typedef Documentation

◆ ValueType

Constructor & Destructor Documentation

◆ RenderLabel() [1/4]

RenderLabel ( const RenderLabel )
default

◆ RenderLabel() [2/4]

RenderLabel ( RenderLabel &&  )
default

◆ RenderLabel() [3/4]

RenderLabel ( )
default

Constructs a label with the reserved unspecified value.

◆ RenderLabel() [4/4]

RenderLabel ( int  value)
explicit

Constructs a label with the given value.

Exceptions
std::exceptionif a) is negative, or b) the value is one of the reserved values.

Member Function Documentation

◆ is_reserved()

bool is_reserved ( ) const

Reports if the label is a reserved label.

◆ operator ValueType()

operator ValueType ( ) const

Implicit conversion to its underlying integer representation.

◆ operator!=()

bool operator!= ( const RenderLabel other) const

Compares this label with the other label.

Reports true if they have different values.

◆ operator<()

bool operator< ( const RenderLabel other) const

Allows the labels to be compared to imply a total ordering – facilitates use in data structures which require ordering (e.g., std::set).

The ordering has no particular meaning for applications.

◆ operator=() [1/2]

RenderLabel& operator= ( RenderLabel &&  )
default

◆ operator=() [2/2]

RenderLabel& operator= ( const RenderLabel )
default

◆ operator==()

bool operator== ( const RenderLabel other) const

Compares this label with the other label.

Reports true if they have the same value.

Friends And Related Function Documentation

◆ hash_append

void hash_append ( HashAlgorithm &  hasher,
const RenderLabel item 
)
friend

Implements the hash_append generic hashing concept.

◆ operator<<

std::ostream& operator<< ( std::ostream &  out,
const RenderLabel label 
)
friend

Enables use of labels with the streaming operator.

◆ RenderEngine

friend class RenderEngine
friend

◆ to_string

std::string to_string ( const RenderLabel label)
friend

Converts the RenderLabel value to a string representation.

Member Data Documentation

◆ kDoNotRender

const RenderLabel kDoNotRender
static

◆ kDontCare

const RenderLabel kDontCare
static

◆ kEmpty

const RenderLabel kEmpty
static

◆ kMaxUnreserved

const ValueType kMaxUnreserved
static

The largest value that a RenderLabel can be instantiated on.

◆ kUnspecified

const RenderLabel kUnspecified
static

The documentation for this class was generated from the following file: