The built-in Easy3D viewer. More...

#include <easy3d/viewer/viewer.h>

Inheritance diagram for Viewer:

Public Member Functions
	Viewer (const std::string &title="Easy3D Viewer", int samples=4, int gl_major=3, int gl_minor=2, bool full_screen=false, bool resizable=true, int depth_bits=24, int stencil_bits=8, int width=800, int height=600)
	Constructor.

virtual	~Viewer ()
	The destructor.

int	run (bool see_all=true)
	Run the viewer.

virtual void	exit ()
	Terminate the viewer.

Viewer properties
void	set_title (const std::string &title)
	Set the window title of the viewer.

const std::string &	title () const
	Query the window title of the viewer.

void	resize (int w, int h)
	Set/Change the viewer size.

int	width () const
	Returns the width of the viewer/window.

int	height () const
	Returns the height of the viewer/window.

void	viewer_size (int &w, int &h) const
	Queries the size of the viewer/window.

int	framebuffer_width () const
	Returns the width of the framebuffer, which is identical to: width() * dpi_scaling().

int	framebuffer_height () const
	Returns the height of the framebuffer, which is identical to: height() * dpi_scaling().

void	framebuffer_size (int &w, int &h) const
	Queries the size of the framebuffer.

void	set_position (int xpos, int ypos)
	Sets the position of the content area of the viewer.

int	samples () const
	Query the actual samples of the viewer.

float	dpi_scaling () const
	Query the scaling factor for high DPI devices (e.g., MackBook pro).

void	set_background_color (const vec4 &color)
	Set the background color of the viewer.

const vec4 &	background_color () const
	Query the background color of the viewer.

Camera *	camera ()
	Returns the camera used by the viewer. See `Camera`.

const Camera *	camera () const
	Returns the camera used by the viewer. See `Camera`.

File IO
virtual bool	open ()
	Open a model (PointCloud/SurfaceMesh/Graph) from a file into the viewer. On success, the viewer will be in charge of the memory management of the model.

virtual bool	save () const
	Save the active model (if exists) to a file.

Drawable management
Drawable *	add_drawable (std::shared_ptr< Drawable > drawable)
	Add a drawable to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the drawable.

Drawable *	add_drawable (Drawable *drawable)
	Add a drawable to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the drawable.

bool	delete_drawable (Drawable *drawable)

const std::vector< std::shared_ptr< Drawable > > &	drawables () const
	Query the drawables managed by this viewer.

void	clear_scene ()
	Delete all visual contents of the viewer (all models and drawables).

UI-related functions
void	update () const
	Update the display (i.e., repaint).

void	fit_screen (const Model *model=nullptr)
	Moves the camera so that the entire scene or the active model is centered on the screen at a proper scale.

virtual bool	snapshot () const
	Take a snapshot of the screen and save it to a file.

bool	snapshot (const std::string &file_name, float scaling=1.0f, int samples=4, int back_ground=1, bool expand=true) const
	Take a snapshot of the screen and save it to an image file. Supported image format: png, jpg, bmp, and tga.

virtual vec3	point_under_pixel (int x, int y, bool &found) const
	Query the XYZ coordinates of the surface point under the cursor.

void	set_usage (const std::string &manual="default", const std::string &screen_hint="")
	The usage information of the viewer.

Algorithm execution
enum	Key { KEY_UNKNOWN = -1 , KEY_0 = 48 , KEY_1 = 49 , KEY_2 = 50 , KEY_3 = 51 , KEY_4 = 52 , KEY_5 = 53 , KEY_6 = 54 , KEY_7 = 55 , KEY_8 = 56 , KEY_9 = 57 , KEY_A = 65 , KEY_B = 66 , KEY_C = 67 , KEY_D = 68 , KEY_E = 69 , KEY_F = 70 , KEY_G = 71 , KEY_H = 72 , KEY_I = 73 , KEY_J = 74 , KEY_K = 75 , KEY_L = 76 , KEY_M = 77 , KEY_N = 78 , KEY_O = 79 , KEY_P = 80 , KEY_Q = 81 , KEY_R = 82 , KEY_S = 83 , KEY_T = 84 , KEY_U = 85 , KEY_V = 86 , KEY_W = 87 , KEY_X = 88 , KEY_Y = 89 , KEY_Z = 90 , KEY_RIGHT = 262 , KEY_LEFT = 263 , KEY_DOWN = 264 , KEY_UP = 265 , KEY_F1 = 290 , KEY_F2 = 291 , KEY_F3 = 292 , KEY_F4 = 293 , KEY_F5 = 294 , KEY_F6 = 295 , KEY_F7 = 296 , KEY_F8 = 297 , KEY_F9 = 298 , KEY_SPACE = 32 , KEY_COMMA = 44 , KEY_MINUS = 45 , KEY_PERIOD = 46 , KEY_SLASH = 47 , KEY_SEMICOLON = 59 , KEY_EQUAL = 61 , KEY_LEFT_BRACKET = 91 , KEY_BACKSLASH = 92 , KEY_RIGHT_BRACKET = 93 }
	The keys. Currently only a limited number of commonly used keys are supported.

enum	Modifier { MODIF_NONE = 0x0000 , MODIF_SHIFT = 0x0001 , MODIF_CTRL = 0x0002 , MODIF_ALT = 0x0004 }
	The key modifiers. Currently only Shift, Ctrl, and Alt are supported.

enum	Button { BUTTON_LEFT = 0 , BUTTON_RIGHT = 1 , BUTTON_MIDDLE = 2 }
	Mouse buttons.

using	Function = std::function<bool(Viewer* viewer, Model* model)>

void	bind (const Function &func, Model *model, Key key, Modifier modifier=MODIF_NONE)
	Bind a function that will be triggered by the shortcut 'modifier + key'.

Animation
std::function< bool(Viewer *viewer)>	animation_func_
	Function called at an equal interval for animation.

void	set_animation (bool b)
	Enable/Disable animation.

bool	is_animating () const
	Is animation currently being performed.

Model management
Model *	add_model (Model *model, bool create_default_drawables=true)
	Add an existing model to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the model.

virtual bool	delete_model (Model *model)
	Delete a model. The memory of the model will be released and its existing drawables also be deleted.

const std::vector< std::shared_ptr< Model > > &	models () const
	Query the models managed by this viewer.

Model *	current_model () const
	Query the active model.

virtual Model *	add_model (const std::string &file_name, bool create_default_drawables=true)
	Add a model from a file to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the model. The loaded model can be accessed by the 'current_model()' method.

Model *	add_model (std::shared_ptr< Model > model, bool create_default_drawables=true)
	Add an existing model to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the model.

Detailed Description

The built-in Easy3D viewer.

Easy3D is really easy to use. That's why it has such a name. To use the viewer, simply create an instance of Viewer, and call the run() method, e.g.,

MyViewer viewer("Example");

viewer.run();

The default Easy3D viewer can be easily extended by deriving your enhanced viewer from it by re-implementing some of its functions (see the documentation of Viewer).

Examples: Tutorial_201_Viewer_default/main.cpp, Tutorial_206_CameraInterpolation/main.cpp, Tutorial_207_RealCamera/main.cpp, Tutorial_301_Drawables/main.cpp, Tutorial_302_Imposters/main.cpp, Tutorial_303_ScalarField/main.cpp, Tutorial_304_VectorField/main.cpp, Tutorial_305_Texture/main.cpp, Tutorial_306_ImageViewer/main.cpp, Tutorial_309_TextRendering/main.cpp, Tutorial_310_TextMesher/main.cpp, Tutorial_311_Animation/main.cpp, Tutorial_312_MultiThread/main.cpp, Tutorial_401_ModelPicker/main.cpp, Tutorial_402_FacePicker/main.cpp, Tutorial_403_PointSelection/main.cpp, Tutorial_404_VirtualScanner/main.cpp, Tutorial_405_ObjectManipulation/main.cpp, Tutorial_406_CollisionDetection/main.cpp, Tutorial_501_AmbientOcclusion/main.cpp, Tutorial_502_HardShadow/main.cpp, Tutorial_503_SoftShadow/main.cpp, Tutorial_504_Transparency/main.cpp, Tutorial_505_EyeDomeLighting/main.cpp, Tutorial_506_DepthMap/main.cpp, Tutorial_601_Tessellator/main.cpp, Tutorial_602_ConvexPartition/main.cpp, Tutorial_603_Curves/main.cpp, Tutorial_701_Cloud_NormalEstimation/main.cpp, Tutorial_702_Cloud_SurfaceReconstruction/main.cpp, and Tutorial_703_Cloud_PlaneExtraction/main.cpp.

Member Typedef Documentation

◆ Function

using Function = std::function<bool(Viewer* viewer, Model* model)>

A function type, which applies the user's algorithm(s)/operation(s) on the given model.

Parameters

viewer A pointer to this viewer.

model

The model to be operated on. Example of defining such a function:

bool reconstruct(Viewer* viewer, Model* model) {
    auto cloud = dynamic_cast<PointCloud *>(model);
    auto mesh = surface_reconstruction(cloud);
    if (!mesh)
        return false;
    viewer->add_model(mesh);
    viewer->update();
    return true;
}

Constructor & Destructor Documentation

◆ Viewer()

Viewer	(	const std::string &	title = "Easy3D Viewer",
		int	samples = 4,
		int	gl_major = 3,
		int	gl_minor = 2,
		bool	full_screen = false,
		bool	resizable = true,
		int	depth_bits = 24,
		int	stencil_bits = 8,
		int	width = 800,
		int	height = 600 )

explicit

Constructor.

Parameters

title	The window title of the viewer, which can be changed by calling set_title() after construction.
samples	The number of samples for multisample antialiasing
gl_major	The OpenGL major version to request. Must be >= 3. The minimal version of OpenGL required to use the Core Profile is OpenGL 3.2.
gl_minor	The OpenGL minor version to request. Must be >= 2. The minimal version of OpenGL required to use the Core Profile is OpenGL 3.2.
full_screen	Do you want the viewer to be fullscreen?
resizable	Whether the viewer will be resizable by the user.
depth_bits	The desired bit depths of the depth component of the default framebuffer.
stencil_bits	The desired bit depths of the stencil component of the default framebuffer.
width	The width of the viewer, which can be changed by calling resize() after construction.
height	The height of the viewer, which can be changed by calling resize() after construction.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp, and Tutorial_204_Viewer_Qt/main.cpp.

Member Function Documentation

◆ add_drawable() [1/2]

Drawable * add_drawable ( Drawable * drawable )

Add a drawable to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the drawable.

The use of drawables for visualization is quite flexible. Drawables are typically created for rendering 3D models (e.g., point clouds, meshes, graphs) and a 3D model is usually loaded from a file or generated by an algorithm. This method allows the user to visualize drawables without defining a 3D model.

Parameters

drawable The pointer to the drawable.

Returns: The pointer of the drawable added to the viewer.

◆ add_drawable() [2/2]

Drawable * add_drawable ( std::shared_ptr< Drawable > drawable )

Add a drawable to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the drawable.

The use of drawables for visualization is quite flexible. Drawables are typically created for rendering 3D models (e.g., point clouds, meshes, graphs) and a 3D model is usually loaded from a file or generated by an algorithm. This method allows the user to visualize drawables without defining a 3D model.

Parameters

drawable The pointer to the drawable.

Returns: The pointer of the drawable added to the viewer.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp.

◆ add_model()

Model * add_model	(	Model *	model,
		bool	create_default_drawables = true )

Add an existing model to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the model.

This method adds a model into the viewer. It allows the user to control if default drawables will be created. The default drawables are

for point clouds: "vertices".
for surface meshes: "faces", "vertices", "edges", "borders", and "locks".
for graphs: "vertices" and "edges".
polyhedral meshes: "faces:border"， "faces:interior"， "vertices"， and "edges". These drawables are usually sufficient for basic rendering of the model. In case the default drawables don't meet the particular visualization purpose, you can set 'create_default_drawables' to false and create your needed drawables by calling model->renderer()->add_[type]_drawable(). Here the [type] must be one of "points", "lines", and "triangles'.
Parameters

model The pointer to the model.

create_default_drawables If true, the default drawables will be created.

Returns
The pointer to the model added to the viewer (nullptr if failed).

See also
add_model(const std::string&, bool).

◆ background_color()

const vec4 & background_color ( ) const

inline

Query the background color of the viewer.

Returns: The background color of the viewer

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp.

◆ bind()

void bind	(	const Function &	func,
		Model *	model,
		Key	key,
		Modifier	modifier = MODIF_NONE )

inline

Bind a function that will be triggered by the shortcut 'modifier + key'.

This operation will overwrite the previous function (if exist) bound to the same key-modifier shortcut.

Parameters

func	The function to be executed, which will be triggered by the shortcut.
model	The model to be processed.
key	The shortcut key.
modifier	The shortcut key modifier (e.g., Ctrl, Shift, Alt). This can be MODIF_NONE.

See also: Function

◆ current_model()

Model * current_model ( ) const

Query the active model.

The viewer can manage/visualize/process multiple models. The default behavior of the Easy3D viewer is, when a command is triggerred (e.g., the Save menu was clicked), only the active model is processed. This method is used to identify the active model.

Returns: The active model.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp.

◆ delete_drawable()

bool delete_drawable ( Drawable * drawable )

Delete the drawable from the viewer. The related drawables will also be deleted.

Parameters

drawable The pointer to the drawable.

Returns: True if the drawable has been deleted.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp.

◆ delete_model()

bool delete_model ( Model * model )

virtual

Delete a model. The memory of the model will be released and its existing drawables also be deleted.

Parameters

model The pointer to the model.

Returns: True if the model has been deleted.

Reimplemented in OffScreen.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp.

◆ dpi_scaling()

float dpi_scaling ( ) const

inline

Query the scaling factor for high DPI devices (e.g., MackBook pro).

Returns: The high DPI scaling factor.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp.

◆ drawables()

const std::vector< std::shared_ptr< Drawable > > & drawables ( ) const

inline

Query the drawables managed by this viewer.

Returns: The drawables managed by this viewer.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp, and Tutorial_204_Viewer_Qt/main.cpp.

◆ fit_screen()

void fit_screen ( const Model * model = nullptr )

Moves the camera so that the entire scene or the active model is centered on the screen at a proper scale.

Parameters

model The pointer to the model to be centered on the screen. If nullptr, the entire scene (i.e., all models) will be centered on the screen at a proper scale.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp, and Tutorial_306_ImageViewer/main.cpp.

◆ models()

const std::vector< std::shared_ptr< Model > > & models ( ) const

inline

Query the models managed by this viewer.

Returns: The models managed by this viewer.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp, and Tutorial_204_Viewer_Qt/main.cpp.

◆ open()

bool open ( )

virtual

Open a model (PointCloud/SurfaceMesh/Graph) from a file into the viewer. On success, the viewer will be in charge of the memory management of the model.

This method loads a model into the viewer. Internally, it will pop up a file dialog for the user to navigate to the file. After loading the model, the necessary drawables (e.g., "vertices" for point clouds, "faces" for surface meshes, and "edges" and "vertices" for graphs) will be created for visualization.

Returns: true on success and false otherwise.

◆ point_under_pixel()

vec3 point_under_pixel	(	int	x,
		int	y,
		bool &	found ) const

virtual

Query the XYZ coordinates of the surface point under the cursor.

Parameters

x	The cursor x-coordinate, relative to the left edge of the content area.
y	The cursor y-coordinate, relative to the top edge of the content area.
found	indicates whether the point was found or not.

Returns: The coordinates of the 3D point located at pixel (x,y) on screen. The returned point is valid only if found was returned true.

Attention: The screen point (x, y) is expressed in the screen coordinate system with an origin in the upper left corner. So it doesn't necessarily correspond to a pixel on High DPI devices, e.g., a Mac with a Retina display. If your inherited viewer uses a customized content area, you must also reimplement this function such that the x and y are relative to left and top edges of the content area, respectively.

Note: This method assumes that a GL context is available, and that its content was drawn using the Camera (i.e. using its projection and model-view matrices). This method hence cannot be used for offscreen Camera computations. Use cameraCoordinatesOf() and worldCoordinatesOf() to perform similar operations in that case. The precision of the method highly depends on the z-Buffer, i.e., how the zNear() and zFar() values are fitted to your scene. Loose boundaries will result in imprecision along the viewing direction.

Reimplemented in MultiViewer.

◆ resize()

void resize	(	int	w,
		int	h )

Set/Change the viewer size.

Parameters

w/h	The requested width/height (in pixels) of the viewer.

◆ run()

int run ( bool see_all = true )

Run the viewer.

Parameters

see_all See all contents within the screen? If true, the entire scene (i.e., all models) will be centered on the screen at a proper scale.

◆ samples()

int samples ( ) const

inline

Query the actual samples of the viewer.

Note: The requested sample may not be supported by the context or graphics driver. This method returns the actual samples that the viewer supports.

Examples: Tutorial_204_Viewer_Qt/main.cpp.

◆ save()

bool save ( ) const

virtual

Save the active model (if exists) to a file.

This method saves the active model to a file. Internally, it will pop up a file dialog for specifying the file name.

Returns: true on success and false otherwise.

◆ set_animation()

void set_animation ( bool b )

Enable/Disable animation.

Attention: To have animation, animation_func_ must be provided to specify how scene geometry is modified.

◆ set_background_color()

void set_background_color ( const vec4 & color )

inline

Set the background color of the viewer.

Parameters

color The background color.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp.

◆ set_position()

void set_position	(	int	xpos,
		int	ypos )

Sets the position of the content area of the viewer.

This function sets the position, in screen coordinates, of the upper-left corner of the content area of the viewer. If the viewer is a full screen window, this function does nothing.

Parameters

xpos	The x-coordinate of the upper-left corner of the content area.
ypos	The y-coordinate of the upper-left corner of the content area.

Note: This function must only be called from the main thread.

◆ set_title()

void set_title ( const std::string & title )

Set the window title of the viewer.

Parameters

title The string of the title.

◆ set_usage()

void set_usage	(	const std::string &	manual = "default",
		const std::string &	screen_hint = "" )

The usage information of the viewer.

Parameters

manual	The manual of the viewer, to be shown in the console window. Using "default" will show the default shortcuts of the viewer.
screen_hint	The hint to the user, which will be sown in the top-left corner of the viewer.

Attention: The default shortcuts could be overridden by bind() function calls.

◆ snapshot() [1/2]

bool snapshot ( ) const

virtual

Take a snapshot of the screen and save it to a file.

This method takes a snapshot of the screen and saves the snapshot into an image file. Internally, it will pop up a file dialog for specifying the file name.

Returns: true on success and false otherwise.

Reimplemented in MultiViewer.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp.

◆ snapshot() [2/2]

bool snapshot	(	const std::string &	file_name,
		float	scaling = 1.0f,
		int	samples = 4,
		int	back_ground = 1,
		bool	expand = true ) const

Take a snapshot of the screen and save it to an image file. Supported image format: png, jpg, bmp, and tga.

This function renders the scene into a framebuffer and takes a snapshot of the framebuffer. It allows the snapshot image to have a dimension different from the viewer, and it has no limit on the image size (if memory allows).

Parameters

file_name	The image file name.
scaling	The scaling factor that determines the size of the image (default to 1.0, using the viewer size), i.e., image_width = viewer_width * scaling; image_height = viewer_height * scaling;
samples	The required number of samples for antialiased rendering (which can be different from that of the default framebuffer). The default value is 4.
back_ground	Determines the background color. 0: current color; 1: white; 2: transparent.
expand	Expand the frustum to ensure the image aspect ratio.

Returns: true on success and false otherwise.

◆ title()

const std::string & title ( ) const

inline

Query the window title of the viewer.

Returns: The string of the window title.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp.

◆ update()

void update ( ) const

Update the display (i.e., repaint).

This method is used to update the display of the rendering. Client should call it when your data/view is changed.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp, and Tutorial_204_Viewer_Qt/main.cpp.

Friends And Related Symbol Documentation

◆ add_model() [1/2]

Model * add_model	(	const std::string &	file_name,
		bool	create_default_drawables = true )

Add a model from a file to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the model. The loaded model can be accessed by the 'current_model()' method.

This method loads a model into the viewer. It allows the user to control if default drawables will be created. The default drawables are

for point clouds: "vertices".
for surface meshes: "faces", "vertices", "edges", "borders", and "locks".
for graphs: "vertices" and "edges".
polyhedral meshes: "faces:border"， "faces:interior"， "vertices"， and "edges". These drawables are usually sufficient for basic rendering of the model. In case the default drawables don't meet the particular visualization purpose, you can set 'create_default_drawables' to false and create your needed drawables by calling model->renderer()->add_[type]_drawable(). Here the [type] must be one of "points", "lines", and "triangles'.
Parameters

file_name The string of the file name.

create_default_drawables If true, the default drawables will be created.

Returns
The pointer to the model added to the viewer (nullptr if failed). (Model*, bool).

Reimplemented in OffScreen.

Examples: Tutorial_203_Viewer_wxWidgets/main.cpp, Tutorial_308_TexturedMesh/main.cpp, and Tutorial_402_FacePicker/main.cpp.

◆ add_model() [2/2]

Model * add_model	(	std::shared_ptr< Model >	model,
		bool	create_default_drawables = true )

Add an existing model to the viewer to be visualized. On success, the viewer will be in charge of the memory management of the model.

This method adds a model into the viewer. It allows the user to control if default drawables will be created. The default drawables are

for point clouds: "vertices".
for surface meshes: "faces", "vertices", "edges", "borders", and "locks".
for graphs: "vertices" and "edges".
polyhedral meshes: "faces:border"， "faces:interior"， "vertices"， and "edges". These drawables are usually sufficient for basic rendering of the model. In case the default drawables don't meet the particular visualization purpose, you can set 'create_default_drawables' to false and create your needed drawables by calling model->renderer()->add_[type]_drawable(). Here the [type] must be one of "points", "lines", and "triangles'.
Parameters

model The pointer to the model.

create_default_drawables If true, the default drawables will be created.

Returns
The pointer to the model added to the viewer (nullptr if failed). (const std::string&, bool).

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

G:/3_code/Easy3D/easy3d/viewer/viewer.h
G:/3_code/Easy3D/easy3d/viewer/snapshot.cpp
G:/3_code/Easy3D/easy3d/viewer/viewer.cpp

model	The pointer to the model.
create_default_drawables	If true, the default drawables will be created.

file_name	The string of the file name.
create_default_drawables	If true, the default drawables will be created.

Public Member Functions

Algorithm execution

Animation

Model management

Detailed Description

Member Typedef Documentation

◆ Function

Constructor & Destructor Documentation

◆ Viewer()

Member Function Documentation

◆ add_drawable() [1/2]

◆ add_drawable() [2/2]

◆ add_model()

◆ background_color()

◆ bind()

◆ current_model()

◆ delete_drawable()

◆ delete_model()

◆ dpi_scaling()

◆ drawables()

◆ fit_screen()

◆ models()

◆ open()

◆ point_under_pixel()

◆ resize()

◆ run()

◆ samples()

◆ save()

◆ set_animation()

◆ set_background_color()

◆ set_position()

◆ set_title()

◆ set_usage()

◆ snapshot() [1/2]

◆ snapshot() [2/2]

◆ title()

◆ update()

Friends And Related Symbol Documentation

◆ add_model() [1/2]

◆ add_model() [2/2]