fw3DViewer  8.4.0
fw3DViewer: JCOP Framework 3D-Viewer widget

The fw3DWidget is a WinCC OA widget for represent 3D graphics The JCOP Framework 3D-Viewer widget is an extension of WinCC OA User Interface allowing to display 3-dimensional view ("scene") made of various geometrical objects. It allows to navigate, and interact with these object making the experience of the user interface very attractive and intuitive.

fw3DViewer_demo1.png
An example of a WinCC OA panel with fw3DViewer displaying a dummy detector

It is a WinCC OA EWO (External Widget Object) UI component that could be embedded into any WinCC OA panel. The viewer is generic: the objects displayed in the scene are created and modified using standard WinCC OA scripts, and the interaction (such as clicking in an object) is also scriptable.

This is the initial version of the documentation; we are aware that it lacks the completness and is not giving enough introduction. Please contact the authors if you need more information.

Shapes, Shape Types and the Scene

The widget displays the view of a so called "Scene": a volume filled with "Shapes". Each Shape is an instance of a Shape Type; there is a set of shape types that are available in the widget - they are documented below. Each shape is identified (and addressed) by a unique name. Each shape has individual set of properties, which define its geometry (placement, rotation, lenths of edges, radiuses, etc), and visual appearance (colour, transparency)

For instance, a scene may be composed of three cubes: "Cube1", "Cube2", "Cube3", each of which is of type "Box". Each of them may have a different colour, transparency, and placement. Each of them may be moved/changed independently of the others.

When the widget is placed in the panel, its scene is initially empty. It is the role of the panel programmer, to use the functions to add shapes to it. Typically, this should be done in the init script of the widget, or the init script of the panel. By default, when the widget is created, it contains the scene view itself (initially an empty area of navy-blue colour), and a set of additional elements called "decorations". The "decorations" elements are three "wheels" that allow to navigate the scene (two in the bottom-left corner, one in bottom-right corner), and a vertical button bar allowing to change the viewer behaviour. The decorations may be hidden (and later shown) either using the context menu (brought up by a right-click), or using the fw3DViewer::setDecoration function.

Note that a panel may contain more than one instance of fw3DViewer, and all these instances are independent and may be manipulated independently

Modes of operation of the widget, navigating in the scene

The widget has two modes of operation: "Viewing" and "Picking".

In the "Viewing" mode, the mouse may be used to navigate in the scene:

In the "Picking" mode, the mouse is used to interact with the object. Clicking in the object triggers the fw3DViewer::shapeClicked event, which may then be served by a dedicated WinCC OA script. Note that in this mode the navigation in the scene is not possible.

To switch between the "Viewing" and "Picking" mode, the following may be used:

Navigation in the scene may also be done using the "go to" functionality: it will navigate in the scene (rotate, zoom), so that the desired shape is visible at the center. To navigate to a certain shape, one should use the fw3DViewer::seekToShape function, passing the name of the shape to it. One could also use fw3DViewer::setSeek to activate the "seek mode"; in the "seek mode", the scene will navigate to a shape that was clicked.

Available Shape Types and Their Parameters

The following shape types are available in this release:

Box

A Box is a cuboid of given half lengths dx, dy, dz . The Box is centred on the origin with sides parallel to the x/y/z axes.

Available Geometry Properties:

Example

* myShape.addShape("Box","MyExampleBox",
* makeDynString("x","1.0",
* "y","2.0",
* "z","3.0",
* "dx","1.0",
* "dy","2.0"
* "dz","4.0",
* "rotationMatrix","0.0, 0.0, 1.0, 0.0, 1.0, 0.0, 1.0, 0.0, 0.0"
* )
* );
*

Sphere

a sphere with radius r

Available Geometry Properties

Cone

a Phi segment of a cone, with half-length dz, inner and outer radii specified at -dz and +dz. The Phi segment is described by a starting startphi angle, and the deltaphi delta angle for the shape. If the delta angle is >=2*M_PI, the shape is treated as continuous in Phi.

Available Geometry Properties

Tube

A tube or tube segment with curved sides parallel to the z-axis.

The tube has a specified half-length along the z axis, about which it is centred, and a given minimum and maximum radius. A minimum radius of 0 signifies a filled tube /cylinder. The tube segment is specified by starting and delta angles for phi, with 0 being the +x axis, PI/2 the +y axis. A delta angle of 2PI signifies a complete, unsegmented tube/cylinder.

Available Geometry Properties:

Trd

A Trd is a trapezoid with the x and y dimensions varying along z.

Available Geometry Properties:

Trapezoid

general trapezoid: The faces perpendicular to the z planes are tapezia, and their centres are not necessarily on a line parallel to the z axis.

Available Geometry Properties:

Text (Label)

Shape for visualizing 2D text aligned with the camera plane. The text is not scaled according to the distance from the camera, and is not influenced by rotation or scaling as 3D primitives are.

Both names: "Text" and "Label" are accepted

Available Geometry Properties:

TextFlat

Shape for visualizing a flat text (without depth), yet in 3D. Conversely to the Text (Label), the TextFlat shapes are scaled according to camera position, and influenced by rotation and scaling primitives

Available Geometry Properties:

Text3D

Shape for visualizing a 3D text. Conversely to the Text (Label), the TextFlat shapes are scaled according to camera position, and influenced by rotation and scaling primitives

Available Geometry Properties:

Axis

Shape that represents a coordinate axis.

Available Geometry Properties:

Polyhedra

Shape that represents a polyhedron.

Available Geometry Properties:

Getting/ modifying shape properties

The properties (geometrical and visual) of each object can be modified using a set of provided functions.

To move the shape to another position, or change its geometry, or rotation, one may use fw3DViewer::setGeometry

To change the color of the shape, use fw3DViewer::setColor or fw3DViewer::setColorRGB

To change the transparency of the shape, use fw3DViewer::setTransparency

To get the properties of a shape one could use the fw3DViewer::getShapeInfo function, passing the list of properties names to be queried as a parameter.

Grouping of objects

The objects may be put in the groups. By default, if they are created using the fw3DViewer::addShape function, they are put in a flat structure, in the toplevel (default) group called "root" .

One may create other groups using the fw3DViewer::addGroup function, then add objects to a specific group by using fw3DViewer::addShapeInGroup . Note that fw3DViewer::addGroup allows to have nested groups.

The grouping of the object allows to change the properties of many objects at once in a simple way. One may use the group name instead of a shape name in functions such as fw3DViewer::setColor or fw3DViewer::setTransparency , and the properties of all members of a group will be changed. This allows, for instance, to hide a big part of the scene, containing a lot of elements, by setting the transparency of the group containing all these objects to 100%.

Note that an object may not simply be moved from one group to another

Deleting the objects, cleaning the scene

One may delete an existing object using fw3DViewer::delShape function. To clean the complete scene, one may specify the name of the toplevel group ("root") as the parameter, i.e.

* myShape.delShape("root");
*