3D Viewer

The class E3DViewer is an interactive 3D viewer for point clouds, ZMaps, meshes and basic shapes (lines, planes, boxes and spheres).

□ It features multiple sources display, color ramps, 3D point picking and text label display.
□ It is compatible with Windows and Linux and can be integrated to Win32, MFC and QT frameworks.

Creating a 3D viewer

● The general constructor of a 3D viewer is:
E3DViewer(EUIAPI uiApi, int orgX, int orgY, int width, int height, void* parent)
● The way to use it depends on the Operating System and the User Interface API.

Windows only

● To create a 3D viewer stand-alone window:
□ Use E3DViewer(EUIAP::EUIAPI_Win32, orgX, orgY, width, height)
● To create a 3D viewer as a part of another window in an MFC application:
□ Use E3DViewer(EUIAP::EUIAPI_Win32, orgX, orgY, width, height, handle to the parent window)
□ See the MsVc or MsVcs Easy3DViewer sample.

Windows and Linux

● To create a 3D viewer in a Qt application:
□ Use E3DViewer(EUIAP::EUIAPI_Qt, orgX, orgY, width, height)
□ You must instance the class inside a QOpenGLWidget object.
□ See the Easy3DViewer Qt sample.

Managing the render sources

● A render source is a displayed entity. It can be an EPointCloud, an EZMap, an EMesh, an E3DBox, an E3DLine, an E3DPlane or and E3DSphere. You can display one or several render sources simultaneously in the 3D viewer.

A point cloud displayed in gray scale and a mesh in false colors in the 3D viewer

● To manage the list of render sources, use the methods:
□ AddRenderSource to add another render source to the current list. The render source has a name for further reference.
□ SetRenderSource to change the content of the render source.
□ RemoveRenderSource to remove a render source from the current list.
● The render sources API exposes several display attributes:
□ Visibility (controlled by ShowRenderSource/ HideRenderSource)
□ Color mode (SetRenderSourceColorMode): choose between constant color (the only option for basic shapes), color ramp or point cloud color attributes.
□ Color (SetRenderSourceConstantColor) for render sources with constant color.
□ Opacity (SetRenderSourceOpacity)
□ Point size (SetRenderSourcePointSize): applies to point clouds and ZMaps only.
□ Wire frame (SetRenderSourceWireFrame): applies to meshes, boxes and planes.

        

A point cloud displayed with constant color, color ramp or color attributes
(data courtesy of Zivid)

A mesh with wireframe and transparency, combined with a point cloud with color ramp

Shading

E3DViewer can shade rendering sources using a custom version of the Eye Dome Lighting (EDL) technique.

● Use SetEnableEDLShading to enable the shading.
● Use SetEDLShadingFactor to adjust the shading between 0 and 1:
□ 0 means no chasding.
□ 1 means strong shading.and 1, respectively meaning no shading and strong shading.

EDL is a post processing technique. It impacts all opaque render sources all together. With EDL, pixels that are closer to the camera occlude neighbor pixels that are further away from the camera.

    

A mesh without and with EDL enabled

Using a color ramp

● When the color mode of a render source is ESourceColorMode_Ramp, the color of each point is calculated from the position or the attribute of the point.
● Use SetColorRampMode to choose the color ramp:
□ EColorRampMode_HueFromX/Y/Z computes the colors from respectively X/Y/Z point coordinates (EColorRampMode_HueFromZ is the default color ramp mode).
□ EColorRampMode_RGBCube computes the colors by mixing X,Y,Z point coordinates.
□ EColorRampMode_HueFromIntensity computes the colors from the intensity attribute of the point.
□ EColorRampMode_HueFromNormal computes the colors from the normal attribute of the point.
□ EColorRampMode_HueFromConfidence computes the colors from the confidence attribute of the point.
□ EColorRampMode_HueFromDistance computes the colors from the distance attribute of the point.

   

Color ramp modes Hue from X/Y/Z and RGB cube

● When a color ramp is defined, you can display a legend at the right side of the window (default position). To control the color ramp legend aspect, use the methods Show/HideColorRampLegend, SetColorRampGraduationColor and SetColorRampLocation.
● When the “Smart color ramp” is enabled with the method SetEnableSmartColorRamp, an outlier filtering processing is applied to remove the noise and spread the colors on the main part of the object. The outliers are then displayed with constant red or blue colors.

To keep the same color ramp bounds instead of adaptive ones, use SetFixColorRampBounds.

A color ramp EColorRampMode_HueFromZ with outlier removal process:
- The extreme points with Z coordinate between 8.3 and 18.8 are drawn in red
- The Z coordinate of 98% of the points are between -6.7 and 8.3

Interactive controls

On Windows, the interactive controls are built in the class E3DViewer.

● The following interactions are possible:

Intercation

Control

Rotate the view

left-click + mouse move

Translate the view

right-click + mouse move

Change the view distance

mouse wheel

Reset the view

r

View along the positive / negative X axis

x / Shift+x

View along the positive / negative Y axis

y / Shift+y

View along the positive / negative Z axis

z / Shift+z

Show / hide the axis

a

Enable / disable the wireframe mode

w

Increase / decrease the point size

plus sign (+) / minus sign (-)
● Use the following methods to implement custom view controls:
□ LockRotationInitialPosition, UpdateRotationPosition and LockRotationFinalPosition correspond to the sequence click-drag-release to change the viewpoint by rotation.
□ LockTranslationInitialPosition, UpdateTranslationPosition and LockTranslationFinalPosition correspond to the sequence click-drag-release to change the viewpoint by translation.
□ UpdateViewDistance changes the view distance, usually controlled by the mouse wheel.
□ ResetView restores the default viewpoint.

See the Qt Easy3DViewer sample for a use case of this view control API.

● You can also directly configure the view position with the methods:
□ SetViewTarget (by default, it is the center of the object).
□ SetViewAngle to choose the orientation of the view.
□ SetViewDistance to choose the distance to the view target.

View parameters

You can customize the 3D view and:

□ Change the field of view with SetFieldOfView.
□ Switch between the perspective and the orthographic view with SetProjectionType.
□ Enable or disable the display of the X, Y and Z axis with SetRenderAxis.
□ Switch the axis origin between the world origin and the object center with SetAxisOrigin.
□ Enable or disable the display of a grid with SetRenderGrid.
□ Activate an auto rotate animation with SetAutoRotate.
□ Use a decimation level (remove some points to speed up the rendering) with SetRenderDecimationLevel.

   

No axis / world centered axis / bounding box axis / axis with grid

Picking a 3D point

● Picking a point means detecting the point closest to the given coordinates in a E3DViewer window. You can then display the detected 3D point, with attributes, as a text label.

Displayed coordinates and attributes of a picked point on the 3D view

● The distance threshold used to select a picked point is defined by SetPickingDistanceThreshold. There is no picked point if the point cloud distance to the picked position is greater than this threshold.
● On the Win32 interface framework, the built-in control for the picking is Ctrl + mouse button.
□ To control the picking, use the methods Pick3DPoint, GetLastPickedPoint and ResetPicking.
□ To configure the E3DViewer to call a specified function when you pick a point, use the method SetPickedPointCallBack.
● To configure the display of the picking label, use SetPickingDisplay, SetPickingLabelSize, SetPickingLabelColor and SetPickingLabelFixed.

Text labels and 3D objects

● You can add custom text labels and 3D objects to the current view of the 3D viewer.

A screen label in the top left corner and a text label with 3D anchor

● To control the text label display, use:
□ AddTextLabel to add a text label with or without a 3D anchor. AddTextLabel returns an ID used for further reference.
□ EditTextLabel to change the position, color, size or text of a label.
□ GetTextLabel to get the attributes of a label.
□ RemoveTextLabel to remove a label.
□ ClearTextLabels to remove all labels.
● The class E3DViewer can also display E3DObject over a point cloud, a ZMap or a mesh. Use the tools Easy3DObject and Easy3DMatch to create the E3DObjects.
● Use the methods Register3DObjects and RemoveCurrent3DObjects to manage the list of E3DObjects that you want to display.

An E3DObject contains several features (center point, bounding box, base plane…). Use the methods Show / HideFeatureFor3DObject and Show / HideFeatureForAll3DObjects to select the displayed features.

See the Easy3DObjectExtract MSCV sample as an example for the display of E3DObjects.

3D objects drawn with a point cloud displaying the bounding boxes and the top positions