ArtiSynth User Interface Guide

4 Component Navigation and Selection

An ArtiSynth model is composed of a hierarchical arrangement of model components (each of which implements the interface ModelComponent), some of which may themselves be models. The graphical interface allows users to navigate this hierarchy and select individual components. Selected components can then be edited, or have specific properties modified or attached to probes or control panels.

4.1 The component hierarchy

An example component hierarchy is shown in Figure 8. At the top is a root model (class RootModel), in this case named Rigid Body Spring. The root model in turn contains a list of models, one of which is a mechanical model named msmod, which here contains particles and rigid bodies.

It is important to node that in the component hierarchy, any collection of components is itself a component (usually an instance of ComponentList). This provides automatic “grouping” of components of like type, but does introduce additional levels into the hierarchy. Hence the particle red is a child not of msmod, but rather the component list particles.

Figure 8: A sample component hierarchy.

4.1.1 Component names and numbers

Model components may be assigned a string name; at the time of this writing names may not begin with a digit, have zero length, contain the characters ‘.’ or ‘/’, or equal the reserved word this. Components which do not have an assigned name are called nameless.

All components have a number, even if they do not have a name. The number is assigned automatically when the component is added to the parent, and is guaranteed to be persistent until the component is removed from the parent.

4.1.2 Component path names

The names and/or numbers of a component’s ancestors can be used to form a component path name. This path has a construction completely analogous to Unix file path names, with the ‘/’ character acting as a separator. Absolute paths start with ‘/’ and begin with the root model. Relative paths omit the leading ‘/’ and can begin lower down in the hierarchy. The absolute path name of the red particle in Figure 8 would be

/Rigid Body Spring/models/msmod/particles/red

For nameless components in the path, their numbers can be used instead:

 /Rigid Body Spring/models/msmod/rigidBodies/1

Numbers can be used even for components that have names. Hence a path name consisting only of numbers, as in

 /0/0/0/3/1

is legal, although it most likely to appear only in machine-generated output.

4.2 Navigation panel selection

A navigation panel in the main ArtiSynth frame allows direct navigation of the component hierarchy. The panel can be open or closed by clicking on the main toolbar icon .

Figure 9 shows an navigation panel containing a superset of the hierarchy diagrammed in Figure 8.

Figure 9: An typical navigation panel display.

Left clicking on any component in the navigation panel selects that component. Clicking while pressing the CTRL key (or the CMD key on some platforms, such as Mac) allows selection of multiple components. Clicking while pressing the SHIFT key allows selection of a range of components.

4.2.1 Large numbers of nameless components

In some cases, such as finite element models, the number of child components can be very large (on the order of thousands). In order to keep the navigation panel size manageable, the number of nameless children displayed is limited to a set number (currently 100). If the number of nameless children exceeds this number, the display will be augmented with an expand icon >>>. Clicking on this will expand the display to include all nameless components, and the expand icon will be replaced by a contract icon <<<. Clicking on the contract icon will cause the extra nameless components to be hidden again. This is illustrated in Figure 10.

Figure 10: Expansion of nameless components in the navigation panel.

4.3 Viewer selection

Components that are rendered in the viewer can generally be selected by variety of methods (the exception is for a few renderable components that do not support selection). These methods include click, box, and elliptic selection. The top two icons in the selection toolbar at the left of the ArtiSynth frame control the current selection method. In addition, hitting the ‘c’ key from within the viewer (Section 3.9) clears the current selection.

4.3.1 Click and box selection

Click and box selection are enabled by the arrow icon at the top of the selection toolbar:

Click selection involves left clicking on a component, causing it to be selected. Selection of multiple components is enabled by left clicking with a modifier key, which is usually CTRL but may be different for some legacy mouse bindings (Section 3.8).

Click selection selects only those components which are actually visible to the viewer; components which are hidden cannot be selected this way.

Box selection is effected by left-clicking and dragging in the viewer, causing the selection of all components rendered within the resulting drag box. Because this often results in the selection of more components than desired, it may be useful to employ a selection filter (Section 4.3.3). Any components within the drag box which are already selected will be deselected.

Box selection acts on all (filtered) components within the view frustum defined by the drag box, including those which are hidden from view.

4.3.2 Elliptic selection

Elliptic selection is enabled by the elliptic icon near the top of the selection toolbar:

This causes an additional elliptic cursor (which defaults to a circle) to be drawn around the mouse cursor. Selection is effected by dragging, and causes all visible objects within the ellipse to be selected. The selection process is cumulative, with subsequent drags selecting additional components. As with all selection operations, a filter can be set to restrict the components that are selected (Section 4.3.3). Generally, the drag select operation requires no modifier keys, although it may with some legacy mouse bindings (Section 3.8).

It is also possible to deselect components in the same way, by using the SHIFT modifier key to cause drag operations to cumulatively deselect components.

Elliptic selection selects only those components which are actually visible to the viewer; components which are hidden cannot be selected this way.

The elliptic cursor used for selection can be resized, either interactively, or by setting the ellipticCursorSize property of the viewer. To interactively change the cursor, initiate a drag operation with the CTRL and SHIFT modifiers. To set the ellipticCursorSize, invoke the context menu (usually right-click) in the viewer when nothing is selected, and choose Set viewer properties. Finally, the ‘d’ key shortcut within the viewer will cause the cursor to be reset to its default size.

4.3.3 Selection filtering

It is possible to limit viewer selection to components of a specific type. This can be done using the selection filter widget at the bottom left of the main ArtiSynth frame Figure 11.

Figure 11: The selection filter widget.

To enable filtering, type into the widget text box the class name of the component type you wish to restrict filtering to. It is generally only necessary to enter the leaf name of the class (e.g., Particle or AxialSpring), and the system will then find the full class name by searching the ArtiSynth class path.

Once filtering is enabled, only components which are instances (including subclasses) of the specified type will be selectable.

Previously selected filters can be recalled using a history list accessible using the leftmost arrow button on the selection widget.

To remove selection filtering, enter the special filter *, either by typing this in the text box, or using the history list.

4.4 Selection display

The selection display Figure 12 at the bottom of the main ArtiSynth frame shows the full path name of the last component added to the selection list. This is useful for identifying components in detail.

If no components are selected, then the selection display is blank.

Figure 12: The selection display widget.

The selection display is useful for disambiguating situations where it is not clear what component we have actually selected in the viewer. For example, FEM models keep their surface mesh contained within a descendant component. Selecting the surface mesh will cause this container component to be selected and highlighted, making it appear as though the FEM model itself is selected rather than the container. Checking the selection display makes it clear what component has actually been selected. If desired, one can easily navigate to one of the ancestor components using parent selection, as described in the next section.

4.5 Selecting parent and ancestor components

Sometimes, when you select a component, you actually want to select one of it’s ancestor components.

There are several ways to do this:

  1. 1.

    Hit the escape (ESC) key within the viewer window. This will select the parent of the currently selected component. Hitting escape repeatedly is a fast way to proceed up the component hierarchy.

  2. 2.

    Click on the “up” arrow located at the left of the selection display (Figure 12). This will also select the parent of the currently selected component.

Parent selection is particularly useful in the commonly occurring situation where a composite component is not rendered and therefore not selectable in the viewer. For instance, suppose we wish to select a FEM model. One can select any renderable descendant of the model, such as a node, element, or its surface mesh (if displayed), and then use repeated parent selection until the model itself is selected.

4.6 Highlighting selected components

Selected components are rendered in the viewer using a special selection color (yellow at the time of this writing). It is important to note that descendants of a selected component are not presently rendered in any special way. For instance, if an FEM is selected, it’s nodes and elements will be rendered normally.

While this has the potential to be confusing, we have not yet found this to be problematic, as the navigation panel and selection display provide alternative indicators as to what is currently selected.