[mrpt-viz]

Overview

3-D scene graph: visual objects, scenes, viewports, cameras, and stock objects.

Library mrpt-viz

This library is part of MRPT and can be installed in Debian-based systems with:

sudo apt install libmrpt-viz-dev

Overview

mrpt-viz contains the scene-graph API for building, manipulating, and serializing 3-D scenes. In MRPT 3.0 this API moved from the former mrpt::opengl namespace to mrpt::viz (see Porting code from MRPT 2.x to MRPT 3.0 for migration details).

Key entry points:

mrpt::viz::CVisualObject — base class for all 3-D visual objects (renamed from the former CRenderizable).
mrpt::viz::Scene — a complete 3-D scene (renamed from COpenGLScene).
mrpt::viz::Viewport — a sub-region of a scene with its own camera (renamed from COpenGLViewport).
mrpt::viz::CCamera — camera parameters for a viewport.
mrpt::viz::stock_objects — convenience factory functions for common objects (coordinate axes, robot models, etc.).

To actually render a scene on screen, use mrpt::gui::CDisplayWindow3D or mrpt::gui::CDisplayWindowGUI (library mrpt-gui). For off-screen rendering, use mrpt::opengl::CFBORender (library mrpt-opengl).

See the tutorial: Tutorial: 3D scenes

Rendering primitives

Below is a list of the available rendering primitive classes.

Pose PDF classes can be converted into visual objects with mrpt::viz::CSetOfObjects::posePDF2opengl() :

mrpt::viz::CSetOfObjects::posePDF2opengl() for mrpt::poses::CPosePDFParticles :

Note: The following extra visual classes are provided by other libraries:

mrpt::viz::CPlanarLaserScan (in mrpt-maps):

Multi-light API

MRPT 3.0 supports up to 8 simultaneous lights via mrpt::viz::TLightParameters. See Porting code from MRPT 2.x to MRPT 3.0 section 10 for details.

Library contents

Pointcloud adapter (wrapper) template classes (in #include <mrpt/viz/pointcloud_adapters.h>)

// enums

enum mrpt::viz::CUBE_TEXTURE_FACE;
enum mrpt::viz::TAlphaMode;
enum mrpt::viz::TCullFace;
enum mrpt::viz::TLightType;

// structs

struct mrpt::viz::TLight;
struct mrpt::viz::TLightParameters;
struct mrpt::viz::TTriangle;

// classes

class mrpt::viz::CAnimatedAssimpModel;
class mrpt::viz::CArrow;
class mrpt::viz::CAssimpModel;
class mrpt::viz::CAxis;
class mrpt::viz::CBox;
class mrpt::viz::CCamera;
class mrpt::viz::CColorBar;
class mrpt::viz::CCylinder;
class mrpt::viz::CDisk;
class mrpt::viz::CEllipsoid2D;
class mrpt::viz::CEllipsoid3D;
class mrpt::viz::CEllipsoidInverseDepth2D;
class mrpt::viz::CEllipsoidInverseDepth3D;
class mrpt::viz::CEllipsoidRangeBearing2D;
class mrpt::viz::CFrustum;

template <int DIM>
class mrpt::viz::CGeneralizedEllipsoidTemplate;

class mrpt::viz::CGridPlaneXY;
class mrpt::viz::CGridPlaneXZ;
class mrpt::viz::CLight;
class mrpt::viz::CMesh;
class mrpt::viz::CMesh3D;
class mrpt::viz::CMeshFast;
class mrpt::viz::COctoMapVoxels;
class mrpt::viz::COrbitCameraController;
class mrpt::viz::CPointCloud;
class mrpt::viz::CPointCloudColoured;
class mrpt::viz::CPolyhedron;
class mrpt::viz::CSetOfLines;
class mrpt::viz::CSetOfObjects;
class mrpt::viz::CSetOfTexturedTriangles;
class mrpt::viz::CSetOfTriangles;
class mrpt::viz::CSimpleLine;
class mrpt::viz::CSkyBox;
class mrpt::viz::CSphere;
class mrpt::viz::CText;
class mrpt::viz::CText3D;
class mrpt::viz::CTextMessageCapable;
class mrpt::viz::CTexturedPlane;
class mrpt::viz::CVectorField2D;
class mrpt::viz::CVectorField3D;
class mrpt::viz::CVisualObject;
class mrpt::viz::PLY_Importer;
class mrpt::viz::Scene;
class mrpt::viz::Viewport;
class mrpt::viz::Visualizable;

// global functions

uint64_t mrpt::viz::sceneChangeCount();
void mrpt::viz::notifySceneChange();
uint64_t mrpt::viz::sceneStructureChangeCount();
void mrpt::viz::notifySceneStructureChange();
void mrpt::viz::registerAllClasses_mrpt_viz();

template <class GRAPH_T>
mrpt::viz::CSetOfObjects::Ptr mrpt::viz::graph_tools::graph_visualize(const GRAPH_T& g, const mrpt::containers::yaml& extra_params = {});

Global Functions

uint64_t mrpt::viz::sceneChangeCount()

Number of changes made so far to any object or container of any scene, in this process: object data, poses, visibility, and insertions or removals.

Renderers compare it against the value they last saw, to skip re-checking a whole scene graph when nothing changed.

See also:

notifySceneStructureChange()

void mrpt::viz::notifySceneStructureChange()

Increments both sceneStructureChangeCount() and sceneChangeCount().

void mrpt::viz::registerAllClasses_mrpt_viz()

Forces manual RTTI registration of all serializable classes in this namespace.

Should never be required to be explicitly called by users, except if building MRPT as a static library.

template <class GRAPH_T>
mrpt::viz::CSetOfObjects::Ptr mrpt::viz::graph_tools::graph_visualize(
    const GRAPH_T& g,
    const mrpt::containers::yaml& extra_params = {}
    )

Returns an opengl objects representation of an arbitrary graph, as a network of 3D pose frames.

Note that the “global” coordinates of each node are taken from mrpt::graphs::CNetworkOfPoses::nodes, so if a node appears in “edges” but not in “nodes” it will be not displayed.

List of accepted extra parameters:

Parameter name	Type	Description	Default
show_ID_labels	bool	Show poses ID labels	false
show_ground_grid	bool	Creates a gray grid on the ground level (mrpt::viz::CGridPlaneXY). The extension of the grid is computed to cover the entire graph extension	true
show_edges	bool	Draw lines between nodes with at least one edge between them.	true
show_node_corners	bool	Draw a small 3D corner frame at each node (see mrpt::viz::stock_objects::CornerXYZSimple)	true
show_edge_rel_poses	bool	Draw the relative poses stored in each edge as a small extra 3D corner frame at each “node pose oplus edge pose”	false
nodes_point_size	double	If set to !=0, draw a point of the given size (glPointSize) at each node.	0.0
nodes_corner_scale	double	If show_node_corners==true, the size (length) of the corner lines.	0.7
nodes_edges_corner_scale	double	If show_edge_rel_poses==true, the size of the corners at the end of each drawn edge	0.4
nodes_point_color	int	If nodes_point_size>0, set this value to a hexadecimal int value 0xRRGGBBAA with the desired RGB+Alpha color of points.	0xA0A0A0FF
edge_color	int	If show_edges==true, the color of those edges as a hexadecimal int value 0xRRGGBBAA with RGB+Alpha color.	0x0000FF40
edge_rel_poses_color	int	If show_edge_rel_poses==true, the color of those edges as a hexadecimal int value 0xRRGGBBAA with RGB+Alpha color.	0xFF800040
edge_width	double	If show_edges==true, the width of edge lines.	1

Implemented as headers-only in graph_tools_impl.h

Parameters:

g	The graph
extra_params	An extra set of optional parameters (see below).