class mrpt::viz::CVisualObject

Overview

The base class of 3D objects that can be directly rendered through OpenGL.

In this class there are a set of common properties to all 3D objects, mainly:

• Its SE(3) pose (x,y,z,yaw,pitch,roll), relative to the parent object, or the global frame of reference for root objects (inserted into a mrpt::viz::Scene).

• A name: A name that can be optionally assigned to objects for easing its reference.

• A RGBA color: This field will be used in simple elements (points, lines, text,…) but is ignored in more complex objects that carry their own color information (triangle sets,…)

• Shininess: See materialShininess(float)

See the main class opengl::Scene

RENDERING FLOW

1. User modifies a viz object:

   • Geometry or appearance (e.g. box.setBoxCorners(…), setColor()): this calls notifyChange(), which increments dataVersion().

   • Pose, scale, visibility or shadow casting: this calls notifyTransformChange(), which increments transformVersion() only, so renderers do not regenerate any buffer.

2. CompiledScene::updateIfNeeded() is called before rendering → For each object whose dataVersion() changed: a) Call sourceObj-> updateBuffersIfNeeded() ← populates viz buffers b) Call proxy->updateBuffers(sourceObj) ← Uploads to GPU → For each object whose transformVersion() changed, only its model matrix and visibility are updated.

3. Rendering proceeds with the updated GPU buffers

See also:

opengl::Scene, mrpt::viz

#include <mrpt/viz/CVisualObject.h>

class CVisualObject: public mrpt::serialization::CSerializable
{
public:
    // typedefs

    typedef std::shared_ptr<CVisualObject> Ptr;
    typedef std::shared_ptr<const CVisualObject> ConstPtr;

    // structs

    struct BuffersVersion;
    struct ChangeCounter;
    struct PoseAndScale;
    struct State;

    // methods

    virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const;
    static const mrpt::rtti::TRuntimeClassId& GetRuntimeClassIdStatic();
    void setName(const std::string& n);
    std::string getName() const;
    bool isVisible() const;
    void setVisibility(bool visible = true);
    bool castShadows() const;
    void castShadows(bool doCast);
    void enableShowName(bool showName = true);
    bool isShowNameEnabled() const;
    CVisualObject& setPose(const mrpt::poses::CPose3D& o);
    CVisualObject& setPose(const mrpt::poses::CPose2D& o);
    CVisualObject& setPose(const mrpt::math::TPose3D& o);
    CVisualObject& setPose(const mrpt::math::TPose2D& o);
    CVisualObject& setPose(const mrpt::poses::CPoint3D& o);
    CVisualObject& setPose(const mrpt::poses::CPoint2D& o);
    mrpt::math::TPose3D getPose() const;
    PoseAndScale getPoseAndScale() const;
    mrpt::poses::CPose3D getCPose() const;
    CVisualObject& setLocation(double x, double y, double z);
    CVisualObject& setLocation(const mrpt::math::TPoint3D& p);
    mrpt::img::TColorf getColor() const;
    mrpt::img::TColor getColor_u8() const;
    CVisualObject& setColorA(const float a);
    virtual CVisualObject& setColorA_u8(const uint8_t a);
    float materialShininess() const;
    void materialShininess(float shininess);
    float materialSpecularExponent() const;
    void materialSpecularExponent(float exponent);
    mrpt::img::TColorf materialEmissive() const;
    void materialEmissive(const mrpt::img::TColorf& color);
    CVisualObject& setScale(float s);
    CVisualObject& setScale(float sx, float sy, float sz);
    float getScaleX() const;
    float getScaleY() const;
    float getScaleZ() const;
    CVisualObject& setColor(const mrpt::img::TColorf& c);
    CVisualObject& setColor(float R, float G, float B, float A = 1);
    virtual CVisualObject& setColor_u8(const mrpt::img::TColor& c);
    CVisualObject& setColor_u8(uint8_t R, uint8_t G, uint8_t B, uint8_t A = 255);
    virtual bool cullElegible() const;
    virtual void toYAMLMap(mrpt::containers::yaml& propertiesMap) const;
    virtual bool isCompositeObject() const;
    virtual const std::deque<std::shared_ptr<CVisualObject>>& getInternalChildren() const;
    void notifyChange() const;
    void notifyTransformChange() const;
    void clearChangedFlag() const;
    void notifyBBoxChange() const;
    bool hasToUpdateBuffers() const;
    uint64_t dataVersion() const;
    uint64_t transformVersion() const;
    bool hasToUpdateBuffersSince(uint64_t sinceVersion) const;
    void updateBuffersIfNeeded() const;
    virtual void updateBuffers() const;
    virtual bool traceRay(const mrpt::poses::CPose3D& o, double& dist) const;
    auto getBoundingBox() const;
    auto getBoundingBoxLocal() const;
    auto getBoundingBoxLocalf() const;
    virtual mrpt::math::TPoint3Df getLocalRepresentativePoint() const;
    void setLocalRepresentativePoint(const mrpt::math::TPoint3Df& p);
    mrpt::viz::CText& labelObject() const;
    std::shared_ptr<mrpt::viz::CText> labelObjectPtr() const;
};

// direct descendants

template <int DIM>
class CGeneralizedEllipsoidTemplate;

class CArrow;
class CAxis;
class CBox;
class CCamera;
class CColorBar;
class CCylinder;
class CDisk;
class CEllipsoidInverseDepth3D;
class CEllipsoidRangeBearing2D;
class CFrustum;
class CGridPlaneXY;
class CGridPlaneXZ;
class CLight;
class CMesh;
class CMesh3D;
class CMeshFast;
class COctoMapVoxels;
class CPlanarLaserScan;
class CPointCloud;
class CPointCloudColoured;
class CPolyhedron;
class CSetOfLines;
class CSetOfObjects;
class CSetOfTexturedTriangles;
class CSetOfTriangles;
class CSimpleLine;
class CSkyBox;
class CText;
class CText3D;
class CTexturedPlane;
class CVectorField2D;
class CVectorField3D;
class VisualObjectParams_Lines;
class VisualObjectParams_Points;
class VisualObjectParams_TexturedTriangles;
class VisualObjectParams_Triangles;

Inherited Members

public:
    // typedefs

    typedef std::shared_ptr<CObject> Ptr;
    typedef std::shared_ptr<const CObject> ConstPtr;
    typedef std::unique_ptr<CObject> UniquePtr;
    typedef std::unique_ptr<const CObject> ConstUniquePtr;
    typedef std::shared_ptr<CSerializable> Ptr;
    typedef std::shared_ptr<const CSerializable> ConstPtr;

    // methods

    mrpt::rtti::CObject::Ptr duplicateGetSmartPtr() const;
    static const mrpt::rtti::TRuntimeClassId& GetRuntimeClassIdStatic();
    virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const;
    virtual CObject* clone() const = 0;
    virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const;
    static const mrpt::rtti::TRuntimeClassId& GetRuntimeClassIdStatic();

Methods

virtual const mrpt::rtti::TRuntimeClassId* GetRuntimeClass() const

Returns information about the class of an object in runtime.

void setName(const std::string& n)

Changes the name of the object.

std::string getName() const

Returns the name of the object.

bool isVisible() const

Is the object visible?

See also:

setVisibility

void setVisibility(bool visible = true)

Set object visibility (default=true)

See also:

isVisible

bool castShadows() const

Does the object cast shadows? (default=true)

void castShadows(bool doCast)

Enable/disable casting shadows by this object (default=true).

The argument is not defaulted on purpose: it would make the no-argument call resolve to this setter instead of the getter above for any non-const object.

void enableShowName(bool showName = true)

Enables or disables showing the name of the object as a label when rendering.

bool isShowNameEnabled() const

See also:

enableShowName

CVisualObject& setPose(const mrpt::poses::CPose3D& o)

Defines the SE(3) (pose=translation+rotation) of the object with respect to its parent.

CVisualObject& setPose(const mrpt::poses::CPose2D& o)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CVisualObject& setPose(const mrpt::math::TPose3D& o)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CVisualObject& setPose(const mrpt::math::TPose2D& o)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CVisualObject& setPose(const mrpt::poses::CPoint3D& o)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CVisualObject& setPose(const mrpt::poses::CPoint2D& o)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

mrpt::math::TPose3D getPose() const

Returns the 3D pose of the object as TPose3D.

mrpt::poses::CPose3D getCPose() const

Returns a const ref to the 3D pose of the object as mrpt::poses::CPose3D (which explicitly contains the 3x3 rotation matrix)

CVisualObject& setLocation(double x, double y, double z)

Changes the location of the object, keeping untouched the orientation.

Returns:

a ref to this

CVisualObject& setLocation(const mrpt::math::TPoint3D& p)

Changes the location of the object, keeping untouched the orientation.

Returns:

a ref to this

mrpt::img::TColorf getColor() const

Get color components as floats in the range [0,1].

mrpt::img::TColor getColor_u8() const

Get color components as uint8_t in the range [0,255].

CVisualObject& setColorA(const float a)

Set alpha (transparency) color component in the range [0,1].

Returns:

a ref to this

virtual CVisualObject& setColorA_u8(const uint8_t a)

Set alpha (transparency) color component in the range [0,255].

Returns:

a ref to this

float materialShininess() const

Material shininess (for specular lights in shaders that support it), between 0.0f (none) to 1.0f (shiny)

void materialShininess(float shininess)

Material shininess (for specular lights in shaders that support it), between 0.0f (none) to 1.0f (shiny)

float materialSpecularExponent() const

Blinn-Phong specular exponent.

Higher values produce a smaller, sharper specular highlight. Typical values: 8 (rough), 32 (default), 128 (metal).

void materialSpecularExponent(float exponent)

Blinn-Phong specular exponent.

Higher values produce a smaller, sharper specular highlight. Typical values: 8 (rough), 32 (default), 128 (metal).

mrpt::img::TColorf materialEmissive() const

Emissive color: light emitted by the object regardless of scene lighting.

Default is black (no emission). Useful for displays, indicator lights, laser beams, warning signs, etc. The emissive term is added to the final lighting equation as: finalColor = emissive + (ambient + diffuse + specular) * materialColor

void materialEmissive(const mrpt::img::TColorf& color)

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

CVisualObject& setScale(float s)

Scale to apply to the object, in all three axes (default=1)

Returns:

a ref to this

CVisualObject& setScale(float sx, float sy, float sz)

Scale to apply to the object in each axis (default=1)

Returns:

a ref to this

float getScaleX() const

Get the current scaling factor in one axis.

float getScaleY() const

Get the current scaling factor in one axis.

float getScaleZ() const

Get the current scaling factor in one axis.

CVisualObject& setColor(const mrpt::img::TColorf& c)

Changes the default object color.

Returns:

a ref to this

CVisualObject& setColor(float R, float G, float B, float A = 1)

Set the color components of this object (R,G,B,Alpha, in the range 0-1)

Returns:

a ref to this

CVisualObject& setColor_u8(uint8_t R, uint8_t G, uint8_t B, uint8_t A = 255)

Set the color components of this object (R,G,B,Alpha, in the range 0-255)

Returns:

a ref to this

virtual bool cullElegible() const

Return false if this object should never be checked for being culled out (=not rendered if its bbox are out of the screen limits).

For example, skyboxes or other special effects.

virtual void toYAMLMap(mrpt::containers::yaml& propertiesMap) const

Used from Scene::asYAML().

(New in MRPT 2.4.2)

virtual bool isCompositeObject() const

Should return true if enqueueForRenderRecursive() is defined since the object has inner children.

Examples: CSetOfObjects, CAssimpModel.

virtual const std::deque<std::shared_ptr<CVisualObject>>& getInternalChildren() const

Returns internal children for composite objects (e.g.

CAxis text labels). Only meaningful if isCompositeObject() returns true. Not for CSetOfObjects — those are handled as containers.

void notifyChange() const

Must be called after any change to the geometry or appearance of the object, so renderers regenerate its buffers (see updateBuffers()) before the next frame.

See also:

notifyTransformChange()

void notifyTransformChange() const

Must be called after a change in the pose, scale, visibility or shadow casting of the object: renderers update where and whether it is drawn, without regenerating its buffers.

See also:

notifyChange()

void clearChangedFlag() const

Reset the dirty flag set with notifyChange().

Deprecated Prefer using the version-counter API: dataVersion() / hasToUpdateBuffersSince(). Kept for backwards compatibility; now a no-op.

bool hasToUpdateBuffers() const

Returns whether notifyChange() has been invoked since the last call to renderUpdateBuffers(), meaning the latter needs to be called again before rendering.

Prefer hasToUpdateBuffersSince() for multi-consumer scenarios.

uint64_t dataVersion() const

Returns the current data version counter.

Incremented on each notifyChange() call. Use this with hasToUpdateBuffersSince() for multi-consumer dirty tracking.

uint64_t transformVersion() const

Returns the current counter of changes in pose, scale, visibility or shadow casting.

Incremented on each notifyTransformChange() call.

bool hasToUpdateBuffersSince(uint64_t sinceVersion) const

Returns true if this object’s data has changed since the given version.

Each consumer (e.g., CompiledScene) should store the last version it processed and pass it here.

void updateBuffersIfNeeded() const

Calls updateBuffers() only if the object data changed since its last call through this method, so several renderers of the same object do not regenerate its buffers once each.

virtual void updateBuffers() const

Called by the rendering system to update internal geometry buffers.

Derived classes should override this to populate their data buffers (triangles, points, lines) when the object geometry changes.

This is called automatically when hasToUpdateBuffers() returns true, which happens after notifyChange() was called.

The base implementation does nothing; derived classes should override.

Thread safety: implementations should lock the appropriate mutexes when writing to shared buffers.

virtual bool traceRay(const mrpt::poses::CPose3D& o, double& dist) const

Simulation of ray-trace, given a pose.

Returns true if the ray effectively collisions with the object (returning the distance to the origin of the ray in “dist”), or false in other case. “dist” variable yields undefined behaviour when false is returned

auto getBoundingBox() const

Evaluates the bounding box of this object (including possible children) in the coordinate frame of my parent object, i.e.

if this object pose changes, the bbox returned here will change too. This is in contrast with the local bbox returned by getBoundingBoxLocal()

auto getBoundingBoxLocal() const

Evaluates the bounding box of this object (including possible children) in the coordinate frame of my parent object, i.e.

if this object pose changes, the bbox returned here will change too. This is in contrast with the local bbox returned by getBoundingBoxLocal()

virtual mrpt::math::TPoint3Df getLocalRepresentativePoint() const

Provide a representative point (in object local coordinates), used to sort objects by eye-distance while rendering with transparencies (Default=[0,0,0])

void setLocalRepresentativePoint(const mrpt::math::TPoint3Df& p)

See getLocalRepresentativePoint()

mrpt::viz::CText& labelObject() const

Returns or constructs (in its first invocation) the associated mrpt::viz::CText object representing the label of the object.

See also:

enableShowName()

std::shared_ptr<mrpt::viz::CText> labelObjectPtr() const

Returns the shared_ptr to the label object (creating it if needed).

See also:

labelObject(), enableShowName()