General information on Qt5 3D OpenSceneGraphDisplay and Mixins

Introduction

The Streaming Source 3D Scene Graph Display, offers the possibility to display all Mixins which are part of the project configuration.
To use the 3D Scene Graph Display, simply add it to the Streaming Graph.

Mixins are ADTF Plugins, which are a compound of an ADTF Filter and the IMixin interface. This means that they offer all functionality which is typically for a filter, and additionally functionality defined by the IMixin interface. This interface offers possibilities to add and manage 3D data which is added to a 3D scene.
The basic behaviour of a Mixin is defined by the base class cMixin. When implementing a custom Mixin, cMixin is subclassed, and methods are overwritten to provide the custom behaviour. Each custom Mixin (= plugin) can manage its data independently, without knowing about other mixins. The technique to define custom 3D data is based on the OSG Library.

Deprecated:: If you add any Mixins to the Filter Graph, these will automatically register themselves, and be displayed.

Note: Since version 3.4.0 of the ADTF DisplayToolbox it is also possible to connect the Mixins via the scene_graph BindingProxy Interface.

Plugin Information

Plugin Filename	3dscenedisplay.adtfplugin
Plugin Description	3dscenedisplay.plugindescription
Plugin Name	Qt5 3D OpenSceneGraph Display Plugin
License	ADTF
Support Mail	support@digitalwerk.net
Homepage URL	https://support.digitalwerk.net/

Plugin Versions

Plugin Version	3.8.0
Plugin File Version	1.0
adtf::disptb	3.8.0
adtf	3.14.3
adtf::ucom	3.1.0

Component Information

Name	Qt5 3D OpenSceneGraph Display
CID	3d_display.streaming_source.disptb.cid
Description	Use this Streaming Source to work on a 3D Scene based on OpenSceneGraph which is extendable with ADTF Mixins.
Type	Filter

Properties

Name	Value	Type	Description	Subproperties
background_color	#333366	cString	Set the clear color used within master camera of the view.
clipping/auto	true	tBool	Compute near/far dynamically from visible objects.
clipping/far	10000.000000	tFloat64	Maxmimum distance for objects from camera. High clipping range effectively reduces Z-buffer precision.
clipping/near	1.000000	tFloat64	Minimum distance for objects from camera. High clipping range effectively reduces Z-buffer precision.
desired_frame_rate	25.000000	tFloat64	Target frame rate for redraws. Additional frames may be rendered on ongoing user interaction. If the widget is visible, actual frame rate may be limited by V-sync. Actual rendering frame rate can differ from sample rate on output pin, if processing speed is limited.
light_ambient	#0c0c0c	cString	Set the ambient component of the light state.
light_diffuse	#cccccc	cString	Set the diffuse component of the light state.
light_mode	0	tUInt32	Set the mode for the position of the light state.
light_x	-20.000000	tFloat64	Set the x-axis coordinate for the position of the light state.
light_y	0.000000	tFloat64	Set the y-axis coordinate for the position of the light state.
light_z	50.000000	tFloat64	Set the z-axis coordinate for the position of the light state.
multisample_antialiasing	0	tInt32	Enable multi sampling anti-aliasing. Improves image quality, at the cost of proportionally increased GPU load and VRAM cost.	Extendable Value List: off = 0 2x = 2 4x = 4 8x = 8 16x = 16
osg_log_to_console	true	tBool	Enables OSG logging and maps notifications to ADTF logging.
osg_notify_level	2	tUInt32	Range of OSG notify levels from DEBUG_FP through to FATAL, ALWAYS is reserved for forcing the absorption of all messages.	Value List: Always = 0 Fatal = 1 Warn = 2 Notice = 3 Info = 4 Debug Info = 5 Debug FP = 6
output/enabled	false	tBool	Send samples on the output pin.
output/height	0	tUInt32	If height > 0, sets fixed height for output pin and snapshots. Also restricts aspect ratio.
output/width	0	tUInt32	If width > 0, sets fixed width for output pin and snapshots. Also restricts aspect ratio.
print_fps	false	tBool	Logging calculated frames per second and delay in [ms].
show_origin_coordinates	true	tBool	If enabled, coordinates are shown.
title	3D Scene Display	cString	Window title which will be used at runtime within ADTF Qt XSystem.

Output Pins

Name	Stream Type	Description
output	adtf/image	Uncompressed image samples in R(8)G(8)B(8)A(8) format. Sample size is controlled by output/width and output/height properties. Sample time is stream time at the point when OSG has finished CPU work. Sample rate is expected to be at most desired_frame_rate, and may be further limited by V-sync if currently visible, or processing speed of the connected trigger pipe. No samples are generated if output/enabled is not set.

Input Binding Objects

Name	IID	Proxy OID	Description
scene_graph	scenegraph.endor.mixinlib.disptb.adtf.iid		ISceneGraph interface for use with Openscenegraph 3.5.6

Dynamic Pins

Dynamic Input Pins	false
Dynamic Output Pins	false
Dynamic Input Binding Pins	false
Dynamic Output Binding Pins	false

Required Interfaces

IID
qt_xsystem.osborn.services.adtf.iid
kernel.devil.services.adtf.iid
reference_clock.osborn.streaming.adtf.iid

Output Pin Stream Types

Pin Name

output

Meta Type Name

adtf/image

Stream Type Properties

Name	Value	Type
data_endianess	1	tUInt32
format_name		cString
max_byte_size	0	tUInt32
pixel_height	0	tUInt32
pixel_width	0	tUInt32

Qt5 3D OpenSceneGraph Display

This section provides information about the 3D Scene Display. The 3D Scene Display renders all mixin data and provides interaction with the 3D scene. The rendering is done for all mixins which are part of the ADTF project configuration.
The interactions with the scene are:

Zoom into or out of the scene (mouse wheel)
Move through the scene (arrow keys)
Move the scene (mouse left click and move)
Context menu (right click)
1. First Person View
  Look from coordinate origin in positive direction of x-axis.
2. Bird's Eye View
  Look onto coordinate origin from top (z-axis).
3. Left View
  Look onto coordinate origin from left (y-axis).
4. Lock View
  Suppress interaction with the scene.
5. Lock Rotation
  Suppress rotation.
6. Camera Coordinate System
  Contains a sub-menu with all available coordinate systems. The system where the camera is placed in, is marked as checked.
7. Mixin Selection
  Open up a dialog which allows to manage visibility of mixins.
8. Help
  Show help.

The above list of the context menu is automatically provided by the 3D Scene Display.
Mixins may enhance this context menu with custom entries. If a right click is performed on such a Mixin, the context menu will display additional entries. This is demonstrated in the Demo 3D Road Mixin.
For a left click in the scene the 3D Scene Display does not offer any action by default. Mixins may enhance this behaviour and provide custom actions for a left click. This is demonstrated in the Demo 3D Coordinate System Mixin.
The third kind of possibility to extend the default viewer is to provide an additional panel. It will be permanently displayed on one of the corners of the viewer. In the panel, mixins can display any information they want to. This is demonstrated in the Demo 3D Object Mixin.

Mixin Library and Packages

All interfaces and functionalities related to mixins is provided by packages. These packages are part of the Display Toolbox. In the installation they can be found in the folder 'pkg'.
To address different needs, the functionality is split into 3 packages:

A basic package, called 'adtf::disptb::base', providing common functionality. It is located in folder 'adtfdisplaytoolboxbase'.
A package providing the core functionality of mixins, called 'adtf::disptb::mixin'. It is located in folder 'adtfdisplaytoolboxmixin'.
An extension package, which enhances the mixins by Qt aspects, called 'adtf::disptb::mixinextension'. It is located in folder 'adtfdisplaytoolboxmixinextension'.

Relevant for developing custom mixins are the packages 'adtf::disptb::mixin' and 'adtf::disptb::mixinextension'.

Package adtf::disptb::mixin

This package provides the core functionality of all mixins. It contains basic behaviour of mixins and associated classes (base classes), as well as interfaces defining the contracts for mixins.

Package adtf::disptb::mixinextension

This packages extends mixins by Qt functionality.

OSG and OpenGL

The 3D Scene Display and all mixins are based on the OSG Library and thus OpenGL technology. The OSG Library is a wrapper around OpenGL and provides high level classes and methods to define a scene graph which is rendered by OpenGL. Understanding OpenGL can be helpful at times, but there is no need to be an expert on this topic.
However some fundamental knowledge of the OSG Library is required. To create custom mixins it is necessary to understand the basic concepts of OSG. It is not possible to provide a comprehensive overview of OSG or OpenGL here. But there are a lot of guides and tutorials on the web.
Some help might also be provided by the examples which are shipped with the Display Toolbox see Examples.

Coordinate Systems

Part of the Mixin concept are coordinate systems. Mixins are part of a coordinate system. By default they are put into the World Coordinate System. This coordinate system is created by the 3D Scene Display.
All coordinate systems are managed by a separate class which can be accessed by all mixins. It is easy to create new coordinate systems, or make use of the existing ones.
A good example showing the creation of new coordinate systems and placing mixins within those is this example: Demo 3D Coordinate System Mixin.

3D Scene Display FAQ

I want to draw a special object list, how can I do that?

Take a look at Demo 3D Object Mixin for an example that shows you how to easily transform your custom object list into and OSG representation.

How can I embed OpenGL commands in the Scene Graph?

To do so you need to subclass from osg::Drawable and implement your OpenGL commands in the drawImplementation method. You can then add this new Drawable to your tree as you would do with any other Drawable.

class cMyDrawable: public osg::Drawable
{
    public:
        virtual Object* cloneType() const { return new cMyDrawable; }
        virtual Object* clone(const osg::CopyOp& copyop) const { return new cMyDrawable; }
 
        virtual void drawImplementation(osg::RenderInfo& renderInfo) const;
};

How can I access Qt?

Mixins can access Qt by adding their own Qt Widgets in side areas of the display. Please see the Demo 3D Object Mixin for a demonstration on how to do this.

Which settings should be properties and which should be in the context menu or custom controls?

All settings that are mandatory for displaying your data and that need not be changed after initialization should be properties (e.g the number of Pins, positions, ...) Settings that are only temporary and that are changed while the display is initialized obviously need to be either context menu items or custom controls (e.g. enabling the display of certain data attributes etc.). To store these settings see the following paragraph.

Where can I store additional Mixin settings?

The Mixin Interface (IMixin) specifies methods 'GetConfiguration' and 'SetConfiguration'. In case settings are about to be stored (e.g. by context menu option 'Export Settings'), the 'GetConfiguration' method is called. This means a custom mixin has to overwrite this method and provide all relevant data as ADTF property. In case settings have to be restored, 'SetConfiguration' is called. A custom mixin needs to overwrite this method and restore the values offered by the ADTF properties.
Compare example Demo 3D Road Mixin for further advise.

The accuracy of my data's position seems to get worse when using large coordinates, how can I fix this?

Most certainly this is due to the usage of single precision floating-point numbers when specifying the location. Please keep in mind that many setPosition like methods of OSG objects take an osg::Vec3f parameter. Even if you specify a osg::Vec3d it will automatically be cast to an osg::Vec3f.

In most cases single precision will suffice as long as you stay in the proximity of your base node (i.e. the center of the coordinate system).

You can work around that limitation by using an osg::PositionAttitudeTransform node that accepts osg::Vec3d parameters and add your nodes as sub-nodes. Remember that each osg::PositionAttitudeTransform constitutes a matrix multiplication, so do not use a new osg::PositionAttitudeTransform for each of your let's say sensor points, but use one to get near the location of interest and then add all your objects relative to that node.

How can I render large amounts of data?

To render large amounts of data it is best not to copy such data, but to access it by reference and render it in your own osg::Drawable implementation.