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.
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.
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
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.
The following shape types are available in this release:
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:
"x"
,"y","z" - position of the shape, in x,y,z direction "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "rotationMatrix"
or "rotation"
- 3x3 rotation matrix, passed as a string of 9 float numbers separated by commas; the "rotation"
property is now deprecated - it is a synonym of "rotationMatrix"
"rotationAngle"
- rotation specified by an axis and angle; passed as a string of 4 float numbers: the first three being the vector that defines the axis, the fourth being the rotation angle in radians. "rotationAngle"
is an alternative to "rotationMatrix"
"dx"
,"dy","dz" - half-lengths along the x,y and z axisExample
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" ) );
a sphere with radius r
Available Geometry Properties
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "r"
- sphere radiusa 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
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "rotationMatrix"
or "rotation"
- 3x3 rotation matrix, passed as a string of 9 float numbers separated by commas; the "rotation"
property is now deprecated - it is a synonym of "rotationMatrix"
"rotationAngle"
- rotation specified by an axis and angle; passed as a string of 4 float numbers: the first three being the vector that defines the axis, the fourth being the rotation angle in radians. "rotationAngle"
is an alternative to "rotationMatrix"
"dz"
- half-length in z "radiusMin"
- inside radius at -dz. "radiusMax"
- ouside radius at -dz. "radiusMin2"
- inside radius at +dz. "radiusMax2"
- outside radius at +dz. "startPhi"
- starting angle of the segment in radians. "deltaPhi"
- delta angle of the segment in radians.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:
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "rotationMatrix"
or "rotation"
- 3x3 rotation matrix, passed as a string of 9 float numbers separated by commas; the "rotation"
property is now deprecated - it is a synonym of "rotationMatrix"
"rotationAngle"
- rotation specified by an axis and angle; passed as a string of 4 float numbers: the first three being the vector that defines the axis, the fourth being the rotation angle in radians. "rotationAngle"
is an alternative to "rotationMatrix"
"dz"
- half-length in z "radiusMin"
- inside radius of the tube. "radiusMax"
- outside radius of the tube. "startPhi"
- starting angle, in radians. "deltaPhi"
- delta-angle, in radians.A Trd is a trapezoid with the x and y dimensions varying along z.
Available Geometry Properties:
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "rotationMatrix"
or "rotation"
- 3x3 rotation matrix, passed as a string of 9 float numbers separated by commas; the "rotation"
property is now deprecated - it is a synonym of "rotationMatrix"
"rotationAngle"
- rotation specified by an axis and angle; passed as a string of 4 float numbers: the first three being the vector that defines the axis, the fourth being the rotation angle in radians. "rotationAngle"
is an alternative to "rotationMatrix"
"dz"
- half-length in z "dx"
- half-length of x, at -dz. "dx2"
- half-length of x, at +dz. "dy"
- half-length of y, at -dz. "dy2"
- half-length of y, at +dz.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:
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "rotationMatrix"
or "rotation"
- 3x3 rotation matrix, passed as a string of 9 float numbers separated by commas; the "rotation"
property is now deprecated - it is a synonym of "rotationMatrix"
"rotationAngle"
- rotation specified by an axis and angle; passed as a string of 4 float numbers: the first three being the vector that defines the axis, the fourth being the rotation angle in radians. "rotationAngle"
is an alternative to "rotationMatrix"
"dz"
- half-length in z "theta"
- polar angle of the line joining the centres of the faces at -/+dz. "phi"
- azimuthal angle of the line joing the centre of the face at -dz to the centre of the face at +dz. "h1"
- half-length along y of the face at -dz. "h2"
- half-length along y of the face at +dz. "bl1"
- half-length along x of the side at y=-h1 of the face at -dz. "bl2"
- half-length along x of the side at y=-h1 of the face at +dz. "tl1"
- half-length along x of the side at y=+h1 of the face at -dz. "tl2"
- half-length along x of the side at y=+h1 of the face at +dz. "alp1"
- Angle with respect to the y axis from the centre of the side at y=-h1 to the centre at y=+h1 of the face at -dz. "alp2"
-Angle with respect to the y axis from the centre of the side at y=-h1 to the centre at y=+h1 of the face at +dz.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:
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "text"
- string with text to write "fontname"
- The font name is recognized with the form "family:style". The range of supported font families depends on which fonts are installed on the system. A typical font family might be "arial" or "times". Style is either "bold"
, "italic"
or "bold italic"
. "fontsize"
- integer with the size of the font, in pixels.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:
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "text"
- string with text to write "fontname"
- The font name is recognized with the form "family:style". The range of supported font families depends on which fonts are installed on the system. A typical font family might be "arial" or "times". Style is either "bold"
, "italic"
or "bold italic"
. "fontsize"
- integer with the size of the font, in pixels.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:
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "text"
- string with text to write "fontname"
- The font name is recognized with the form "family:style". The range of supported font families depends on which fonts are installed on the system. A typical font family might be "arial" or "times". Style is either "bold"
, "italic"
or "bold italic"
. "fontsize"
- integer with the size of the font, in pixels.Shape that represents a coordinate axis.
Available Geometry Properties:
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "ndiv"
- integer with number of divisions in each axis. "divlength"
- float with the size of each division.Shape that represents a polyhedron.
Available Geometry Properties:
"x"
,"y","z" - position of the shape "position"
- position of the shape specified as a string of 3 floats (for x, y and z); alternative to the "x"
, "y"
and "z"
properties "startphi"
- initial phi. "deltaphi"
- delta phi. "npdv"
- number of steps along phi. "zsections"
- string with a list of z planes. The format is: "z,radiusmin,radiusmax,z,radiusmin,radiusmax,z..."
.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.
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
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");