ArtiSynth User Interface Guide

3 The Viewer

The viewer provides interactive graphical rendering of the ArtiSynth model and permits selection of its components. A viewer is integrated into the ArtiSynth main frame; additional viewers can be created if necessary.

3.1 Viewer Toolbar

Each viewer is provided with a toolbar (Figure 3) equipped with icons for controlling the viewpoint (Section 3.2) and clipping planes (Section 3.6). The toolbar for the main viewer appears vertically at the lower left of the main frame, while toolbars for additional viewers appear horizontally at the top. Each is an instance of Java’s JToolBar, and so can be moved and docked accordingly.

Figure 3: The viewer toolbar.

3.2 Viewpoint control

The viewpoint can be controlled interactively using mouse drag actions. On systems with a three-button mouse, this is generally done using the middle mouse button (MMB), in conjunction with the SHIFT and CTRL modifier keys:

MMB

Rotates the viewpoint about the viewer center point.

MMB + SHIFT

Translates the viewpoint in a plane perpendicular to the line of sight.

MMB + CTRL or mouse WHEEL

Zooms in or out by moving the viewpoint along the line of sight. Rotate wheel forward or drag mouse forward with CTRL and middle mouse button pressed to zoom in. Rotate or drag backwards to zoom out.

On systems that have a one or two button mouse, the mouse bindings are adjusted by default so that the ALT modifier key emulates the middle mouse button. Mouse bindings are discussed in detail in Section 3.8.

Predetermined viewpoints can also be selected using the align axis button located on the viewer control bar. Clicking on this button produces an icon menu showing six different axis-aligned views. Each view is indicated by the two axes perpendicular to the line of sight, with the X, Y, and Z axes illustrated by red, green, and blue lines respectively:

Front: Z axis up, X axis to the right.
Back: Z axis up, X axis to the left.
Top: Y axis up, X axis to the right.
Bottom: Y axis down, X axis to the right.
Left: Z axis up, y axis to the right.
Right: Z axis up, y axis to the left.

The align axis button itself displays the most recently selected axis-aligned view. Hitting the ‘v’ key from within the viewer (Section 3.9) will realign the viewpoint to this view.

3.3 Adding additional viewers

Additional viewers can be created by selecting View > New viewer from the main menu. Each viewer provides independent viewing and selection control for the current model.

We are considering adding an option whereby the main viewer can be split into four independent viewing panels, providing orthogonal projections of the front, side, and top, along with a general perspective projection. This arrangement is common in CAD and geometric modeling applications.

3.4 Orthographic vs. perspective projection

The user can toggle between orthographic and perspective projection by selecting View > Orthographic view or View > Perspective view from the main menu. Toggling can also be achieved using the ‘o’ key shortcut (Section 3.9) within the viewer.

3.5 Viewer grid

Hitting the ‘g’ key within the viewer enables or disables a grid (Figure 4). Grid cells are square and appear in two resolutions, with major cells subdivided into a number of minor cells. Major cells are typically rendered more brightly than minor cells. By default, the grid computes the cell sizes automatically based on the current viewer zoom-level. However, it is possible to set an explicit grid resolution (see 3.5.1).

The grid is located in the plane perpendicular to the line of sight of the most recently selected axis-aligned view. To change the grid plane, select a new axis aligned viewpoint (Section 3.2).

Figure 4: Viewer showing the grid.

3.5.1 Grid units

When the grid is enabled, a box labeled Grid: appears in the toolbar on top of the main ArtiSynth frame which gives the current resolution of the grid, displayed as S/N, where S is the size of each major grid cell and N is the number of subdivisions per cell. If there are no subdivisions, then the /N is omitted. For example, in Figure 4, this appears as Grid: 1/10, which means that the major grid cells have a size of 1.0 and are each divided into 10 subdivisions. The numeric value of the ratio S/N gives the minor cell size.

By default, the grid automatically resizes itself to the current viewer zoom level, choosing well-rounded numbers for the grid cell size. Auto-sizing can be enabled or disabled by right-clicking on the Grid: label and choosing Turn auto-sizing on or Turn auto-sizing off, as appropriate. The user can also specify an explicit value for the grid resolution by entering the desired S/N value (or just an S value) into the Grid: box. Specifying an explicit value will disable auto-sizing, unless S is specified as 0 or the special value * is entered, both of which will re-enable auto-sizing.

3.5.2 Axis labeling

Hitting the ‘l’ key within the viewer enables or disables labeling of the major divisions along the horizontal and vertical axis (Figure 5). The division lines along which these labels appear are automatically adjusted so as to ensure proper label visibility, and do not necessarily correspond to the x, y, or z axes.

Figure 5: Viewer grid with axis labels visible.

It is possible to control various properties associated with axis labeling, such as which axes are labeled, and the label size and color. See the next section on Grid properties.

3.5.3 Grid properties

The grid has a number of properties that can be set by right-clicking in the viewer and choosing Set viewer grid properties (or by right-clicking on the Grid: label and choosing Set properties). This will bring up a property dialog, such as that shown in Figure 6.

Figure 6: Dialog to control the grid properties.

Properties that can be set include:

resolution

Grid resolution, as described above.

autoSized

If true, causes the grid resolution to be recomputed as the user adjusts the view position, orientation, and zoom.

minCellPixels

Minimum number of pixels that should appear in a minor cell division when autosizing.

majorColor

Color to use for the major axis lines.

minorColor

Color to use for the minor axis lines.

xAxisColor

Color to use for the grid line that corresponds to the world y axis, or the horizontal axis if lockAxesToWorld is false.

yAxisColor

Color to use for the grid line that corresponds to the world y axis, or the vertical axis if lockAxesToWorld is false.

zAxisColor

Color to use for the grid line that corresponds to the world z axis.

lineWidth

Width of the grid lines, in pixels.

position

Translation position of the grid, in world coordinates.

orientation

Orientation of the grid, in world coordinates.

lockAxesToWorld

If true, forces the grid to stay aligned with the orientation and position of the world axes. In particular, the horizontal and vertical axes will always be parallel to one of the x, y, or z world axes, the grid center will be a multiple of major cell sizes from the origin, and axis labels will be set relative to the world origin.

useWorldOrigin

If true, causes the principal horizontal and vertical axes to be aligned with the world origin. Otherwise, the axes will be aligned with the grid center. This property can only be true if lockAxesToWorld is also true.

xAxisLabeling

Enables labeling of the x axis.

yAxisLabeling

Enables labeling of the y axis.

labelSize

’em’ size of the label text, in pixels.

labelColor

If set, specifies the color used to draw the label text. Otherwise, the major axis color is used.

3.6 Clipping planes

The user can add clipping planes to the viewer. These are useful for restricting what is rendered and allowing a better view of interior structures, as shown in (Figure 7).

Figure 7: Clipping plane showing interior of tongue model (left), disabled (center), and in slice mode (right).

3.6.1 Adding and removing

To add a clipping plane, left click on the add clip plane button located on the viewer toolbar. This will create a clipping plane located in the plane perpendicular to the current line of sight.

It will also add to the viewer toolbar a clip plane icon for controlling the clipping plane. Right-clicking on this icon will bring up an option menu.

To delete a clipping plane, right-click on its icon and select Delete.

3.6.2 Moving

A clip plane is associated with a coordinate system and can be moved and/or rotated by dragging on the trans-rotate transformer located at its coordinate system origin. The clip region is the half space lying in the direction of the +z axis.

The transformer itself can be made invisible/visible by right-clicking on the clip plane icon and selecting Hide transformer or Show transformer.

3.6.3 Offsets

The clipping region is the half space lying in the direction of the +z axis of the plane’s local coordinate system. By default, clipping is actually offset by a small distance along the +z axis, so that small objects (such as points) lying in the x-y plane remain visible. The amount of this offset is controlled by the plane’s offset property, which is set to a nominal default value. To control this property directly, right-click on the clip plane icon and select Set properties. This will bring up a panel which allows the offset to be adjusted.

3.6.4 Enabling/disabling

Left clicking on the clip plane icon will enable/disable clipping. Disabling clipping allows the plane to be used as a regular movable grid. When clipping is disabled, the icon will change to the form .

3.6.5 Slicing mode

Clipping planes can be placed in a slicing mode, whereby half-spaces in both the positive and negative z directions are clipped. The result is a small slice about the local x-y plane (Figure 7, right). The width of this slice is controlled by the plane’s offset property, as described above.

To enable or disable slicing, right-click on the clip plane icon and select Enable slicing or Disable slicing.

3.6.6 Other features

Properties

Various properties associated with the plane, such as its color, line width, cell resolution, etc., can be set explicitly by the user. To do this, right-click on the icon, select Set properties, and edit the resulting property panel. Most properties are the same as those described for the main viewer grid in 3.5.3.

Grid visibility

To make the grid invisible/visible, right-click on the icon and select Hide grid or Show grid.

Alignment with world axes

The clip plane can be aligned so that it’s normal lies along the positive or negative direction of either the x, y, or z world axes. Right-click on the icon and select the appropriate option. Clipping is performed so that the half-space lying in the direction of the normal is clipped.

Alignment with current line of sight

To align the clipping plane so that it is perpendicular to the current line of sight, right-click on the icon and select Reset.

3.7 Indicating 3D positions with the mouse

It is possible to use a viewer in combination with a mouse to specify the position of a 3D point in space. This is commonly employed in the editing operations described in Section 13.

To specify a point, the user left-clicks the mouse in the viewer, at the screen position located over the point’s desired position. The 3D position is then determined by intersecting the ray indicated by the mouse clock with some appropriate surface or plane. Typically, a plane perpendicular to the viewing direction and passing through the model’s center is used. Alternatively, some interactions provide a constrain to plane option, which causes the ray to be intersected with a viewer clipping plane (Section 3.6), providing more precise control over the point’s position. This requires that the viewer presently contain at least one clipping plane. If more than one clipping plane is present, the first one is used.

In other applications, the desired point may be known to lie on a 3D surface, in which case the position is determined by intersecting the ray with a 3D surface mesh.

3.8 Alternate mouse bindings

The ArtiSynth GUI was originally designed for a three-button mouse, in which the left button is used for selection, the middle button controls the viewpoint, and the right button is used to activate the context menu. These are used in conjunction with the modifier keys SHIFT and CTRL to effect different actions.

For systems that do not have a three-button mouse, ArtiSynth by default detects the number of mouse buttons and adjusts the mouse bindings so that the ALT key emulates the middle button and the META key emulates the right button.

The META key is usually associated with either the COMMAND key (Mac) or the WINDOWS key.

Mouse bindings can also be explicitly set by the user, by opening the mouse preferences dialog Settings > Mouse Preferences and then choosing the desired binding. This dialog also displays the button and modifier combinations associated with different actions. Alternate bindings may also be requested from the command line using the -mousePrefs <bindings> option. Currently, there are three default and two legacy bindings:

ThreeButton

Default bindings for a three-button mouse.

TwoButton

Default bindings for a two-button mouse. The middle mouse button is emulated with the ALT key.

OneButton

Default bindings for a one-button mouse. The middle and right mouse buttons is emulated with the ALT and META keys.

Laptop

Legacy bindings for a two-button mouse.

Mac

Legacy bindings for a Mac type one-button mouse.

Tables showing the button and modifier combinations that effect different actions with each of these binding are given below, with LMB, MMB, and RMB denoting the left, right and middle mouse buttons. Actions marked with an asterisk (*) are drag actions which can have their modifier keys invoked or removed during a drag operation.

Action ThreeButton TwoButton OneButton
Viewpoint control (Section 3.2)
Rotate view MMB MMB+ALT MMB+ALT
Translate view MMB+SHIFT MMB+ALT+SHIFT MMB+ALT+SHIFT
Zoom view MMB+CTRL MMB+ALT+CTRL MMB+ALT+CTRL
Component selection (Section 4.3)
Single selection LMB LMB LMB
Multiple selection LMB+CTRL LMB+CTRL LMB+CTRL
Elliptic selection LMB LMB LMB
Elliptic deselection{}^{*} LMB+SHIFT LMB+SHIFT LMB+SHIFT
Resize paint ellipse LMB+SHIFT+CTRL LMB+SHIFT+CTRL LMB+SHIFT+CTRL
Context menu RMB RMB LMB+META
Transformer control (Section 5.2)
Move LMB LMB LMB
Constrained move{}^{*} LMB+SHIFT LMB+SHIFT LMB+SHIFT
Reposition{}^{*} LMB+CTRL LMB+CTRL LMB+CTRL

while the legacy bindings are:

Action Laptop Mac
Viewpoint control (Section 3.2)
Rotate view LMB LMB+ALT
Translate view LMB+SHIFT LMB+ALT+SHIFT
Zoom view LMB+ALT LMB+ALT+META
Component selection (Section 4.3)
Single selection LMB+CTRL LMB
Multiple selection LMB+SHIFT+CTRL LMB+META
Elliptic selection LMB+CTRL LMB
Elliptic deselection{}^{*} LMB+SHIFT+CTRL LMB+SHIFT
Resize paint ellipse LMB+SHIFT+CTRL LMB+SHIFT+CTRL
Context menu RMB LMB+CTRL
Transformer control (Section 5.2)
Move LMB LMB
Constrained move{}^{*} LMB+SHIFT LMB+SHIFT
Reposition{}^{*} LMB+ALT LMB+ALT

3.9 Keyboard shortcuts

When the viewer has the keyboard focus, the following key shortcuts are available:

Key Operation
q quit ArtiSynth
t toggle time line visibility
z undo last command
Play controls (Section 2.5):
p or SPC play/pause
s single step
r reset
Viewer controls:
v reset view (Section 3.2)
o toggle orthographic/perspective view (Section 3.4)
a toggle visibility of axes showing world coordinates
g toggle viewer grid (Section 3.5)
l toggle viewer grid labels
Selection and transformer (Sections 4.3 and 5.2):
ESC select parent of last selection
c clear selection
d reset elliptic cursor size to default
w set current transformer frame to world coordinates
b set current transformer frame to body/local coordinates