Placing Objects on Top of the Scene

When a scene in ILNumerics is rendered, its content is distributed to individually stacked layers:

• Regular World 3D Nodes are defined by common shapes in the regular scene graph. This is the most common object type and the default for all new scene objects. These nodes are transformed into their 2D representations by using a camera. The positions and depth of such shapes are determined by their vertex positions in conjunction with the group transforms defined on their path within the scene graph (See Transformations).
• Screen 2D Nodes are always rendered on top of world 3D nodes. They are defined by the help of common scene graph objects: shapes, labels and groups. But in the rendered output they appear on top of any 3D shape – regardless of their Z coordinate. Screen 2D nodes are drawn after 3D nodes and establish their own coordinate system. However, the Z position of a screen 2D node determines the order in which the nodes appear in the output. Just like with 3D nodes, higher Z values will place the shape closer to the observer, hence above other shapes with a lower Z coordinate. Typical examples of screen 2d nodes are: markers, legends and colorbars within plots from the ILNumerics.Drawing.Plotting namespace.

By default all shapes of a scene graph target the 3D world. Special group nodes are provided, in order to establish a root node for a subtree of 2D screen nodes. All children below ScreenObject are destined as screen 2D nodes:

The default ScreenObject creates a white rectangular rendering area with a thin border. If used in conjunction with an interactive driver like Panel, they provide the option of getting translated with the mouse out of the box. When moved, the whole content moves with the screen 2D root.

ScreenObject establishes its own coordinate system. In contrast to the common accumulating transform rules, the (3D) coordinate system of the parent node is not derived, hence does not influence the transformations of the screen 2D root nor its children. However, within a screen 2D subtree, all common transform rules apply again: Transformations of group nodes are derived by their children.

The screen 2D coordinate system established by ScreenObject ranges from (0, 0, -1) to (1, 1, 1). Here, (0, 0, -1) corresponds to the upper left corner of the screen 2D area. (1, 1, 1) corresponds to the lower right corner respectively. Common group nodes can be used to modify the coordinate system for subsequent child nodes.

The position and size of the screen 2D object areas is determined by ScreenObject.Location, ScreenObject.Size and ScreenObject.Anchor. A location of (0,0,-1) corresponds to the upper left far corner of the current viewport. A location of (1,1,1) to the lower right near corner respectively. If no custom viewport is active, (0, 0, -1) corresponds to the upper left corner of the rendering panel. By default, ScreenObject is centered to the current viewport.

Regarding the Anchor property the same positioning rules as for labels apply: Location determines the position of the anchor point relative to the extents of the current viewport. Anchor determines the position of that point relative to the extents of the screen 2D area. That way it is possible to adjust the position of the screen 2D objects to exactly match, let’s say, the right edge of the rendering panel.

ScreenObject serves as base class for convenient implementation of custom screen objects. For example: legend and colorbar are objects deriving from ScreenObject.