ArtiSynth User Interface Guide 2 Loading, Simulating and Saving Models 4 Component Navigation and Selection

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 7) equipped with icons for controlling the viewpoint (Section 3.2) and clipping planes (Section 3.7). 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 7: The viewer toolbar.

3.2 Viewpoint control

The viewpoint can be controlled interactively using mouse drag actions. There are three such actions:

Rotate: Rotates the viewpoint about the viewer center point. By default, this rotation is constrained so the viewer “up” direction remains vertical in the view plane, but this can be changed using the viewer’s rotationMode property (Section 3.9).
Translate: Translates the viewpoint in a plane perpendicular to the line of sight.
Zoom: Zooms in or out by moving the viewpoint along the line of sight.

The mouse button and modifier key combinations required to effect these actions depend on the application’s mouse bindings, which by default are set to either ThreeButton, TwoButton, or OneButton depending on the number of available mouse buttons. Button/key combinations for each of these is described in the following table,

Action	ThreeButton	TwoButton	OneButton
Rotate	MMB	LMB+ALT	LMB+ALT
Translate	MMB+SHIFT	LMB+ALT+SHIFT	LMB+ALT+SHIFT
Zoom	MMB+CTRL	LMB+ALT+CTRL	LMB+ALT+CTRL

where MMB and LMB denote the middle and left mouse buttons. If a mouse wheel is present, then this can also be used to execute zoom actions.

Mouse bindings can also be set explicitly by the user and alternative bindings are available; see Section 3.10.

Predetermined viewpoints can also be selected using the align axis button located on the viewer control bar. Clicking on this button produces a popup 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. Some examples are:

	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, and the popup menu shows this view together with five alternates which are chosen based on the current view. Reselecting the current view will realign the viewer’s viewpoint to the current view; hitting the ‘v’ key from within the viewer (Section 3.11) will do the same.

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.

3.4 World coordinate axes

Hitting the ’a’ key from within the viewer enables or disables drawing of the world coordinate axes. By default, these are drawn as simple lines, with the , and axes colored red, green and blue, respectively, and the axis length computed automatically based on the model size.

Figure 8: RigidBodyDemo with world coordinate axes drawn as simple lines (left) and solid arrows (right).

Axes can also be rendered as solid arrows by setting the axisDrawStyle property (Section 3.9) to ARROW instead of LINE, and the axis length can be set explicitly using the axisLength property (Section 3.9.1). Axes are not drawn if either axisLength is 0 or axisDrawStyle is set to OFF.

3.5 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.11) within the viewer.

3.6 Viewer grid

Hitting the ‘g’ key within the viewer enables or disables a grid (Figure 9). 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.6.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 9: Viewer showing the grid.

3.6.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 9, 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.6.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 10). 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 10: 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.6.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 11.

Figure 11: 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.7 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 12).

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

3.7.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.7.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.7.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.7.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.7.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 12, 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.7.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.6.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.8 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 16.

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.7), 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.9 Viewer properties

Viewers export a number of properties that control various aspects of their look and feel. Some of these can be modified collectively for all viewers by choosing “Settings > Viewers ...” from the main menu, which opens a viewer settings dialog (Figure 13).

Figure 13: Viewer settings dialog.

Various properties can be set by this dialog, as described below. Clicking the Save button will save the current settings to the user’s preferences (Section 11.2) so that they will be set automatically when ArtiSynth is restarted.

Properties set by the viewer settings dialog include:

backgroundColor: Color of the viewer background.
selectionColor: Color used to highlight selected items.
axisDrawStyle: Controls how world coordinate axes are drawn (Section 3.4), with LINE and ARROW specifying simple lines and solid arrows, respectively.
axisRadiusRatio: A ratio which can be used to determine the radius for an axis when the radius is not explicitly specified. The radius is computed by multiplying the ratio by the axis length. This is typically used when rendering coordinate axes as solid arrows and has a default value of 0.016.
rotationMode: Controls how the eye-to-world rotation is adjusted when the mouse is used to perform a rotate action (Section 3.2). The default value is FIXED_VERTICAL, which constrains the viewer’s “up” vector to remain vertical with respect to the view plane, at the expense of preventing the eye-to-world rotation from being adjustable to an arbitrary value. Alternate values include CONTINUOUS, which enables a track-ball type rotation that does allow arbitrary adjustment of the eye-to-world rotation, and OFF, which disables rotation adjustment.
defaultAxialView: Sets the default axis alignment indicating how the 3D world axes correspond to the horizontal “right” and vertical “up” view plane directions. Each setting takes the form _, where is the world axis pointing right and is the axis pointing up, and and can each be either X, Y, Z, NX, NY, or NZ, indicating the positive or negative , or axis.
ellipticCursorSize: Size of the elliptic cursor (Section 4.3.2) in the horizontal and vertical directions. The default value is .
surfaceResolution: Controls the number of faces or segments used for rendering built-in curved primitives, such as cylinders and spheres. For cylinders, it controls the number of sides, while for spheres it controls the number of longitudinal slices. A larger number produces a smoother effect at increased graphical cost. The default value is 32.

For OpenGL based viewers, the following properties are also provided to control how transparency is rendered:

transparencyFaceCulling: Enables or disables face culling when rendering transparency.
transparencyBlending: Enables or disables transparency blending (via glEnable() or glDisable() using GL_BLEND) when rendering transparency.
blendSourceFactor: Specifies the first (source) argument to glBlendFunc().
blendDestFactor: Specifies the second (destination) argument to glBlendFunc().

3.9.1 Viewer-specific properties

Viewer properties can also be set on a per-viewer basis. To do this, invoke the context menu (usually right-click) in the viewer when nothing is selected, and choose Set viewer properties. Individual properties include all those described above (except with defaultAxialView renamed to axialView), together with the following additional properties:

axisLength: Axis lengths used to render the world axes (Section 3.4).
viewControlMask: If set to ALONG_X_ONLY or ALONG_Y_ONLY, mouse-based view control inputs are restricted to those in the x or y screen directions, respectively. This makes it easier to limit changes in the view point. The default value is NONE (no restriction).
eye: Location of the eye position, in world coordinates.
center: Location of the viewing frustum center, in world coordinates.

Setting a viewer-specific property, such as the background color, will generally cause it to have a value that differs from its counterpart in the viewer settings (because the value was set for only a single viewer). On the other hand, properties set in the viewer settings will be applied to all open viewers.

3.10 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.

Figure 14: Mouse bindings dialog.

Mouse bindings can also be explicitly set by the user, by choosing “Settings > Mouse ...” from the main menu, which opens a mouse bindings dialog (Figure 14). This allows the user to change the bindings, and also for any given binding describes the button/key combinations to effect various actions. If the “Auto detect” checkbox is selected, then the bindings are determined automatically from the number of available mouse buttons. Unchecking this box allows the bindings to be set explicitly using the Bindings selector. The dialog also allows control of the scale factor used for mouse wheel zoom actions.

Clicking the Save button in the mouse bindings dialog will save the current bindings to the user’s preferences (Section 11.2) so that they will be set automatically when ArtiSynth is restarted. Mouse bindings can also be specified explicitly at startup using the -mousePrefs <bindings> command line option.

Currently, there are five bindings available:

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 key combinations that effect different actions for each of these 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. Button/key combinations for ThreeButton, TwoButton, and OneButton are:

Viewpoint control (Section 3.2)
Action	ThreeButton	TwoButton	OneButton
Rotate view	MMB	LMB+ALT	LMB+ALT
Translate view	MMB+SHIFT	LMB+ALT+SHIFT	LMB+ALT+SHIFT
Zoom view	MMB+CTRL	LMB+ALT+CTRL	LMB+ALT+CTRL
Component selection (Section 4.3)
Select components	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 elliptic cursor	LMB+SHIFT+CTRL	LMB+SHIFT+CTRL	LMB+SHIFT+CTRL
Context menu	RMB	RMB	LMB+META
Manipulator controls (Section 5.2)
Move dragger	LMB	LMB	LMB
Dragger constrain ${}^{*}$	LMB+SHIFT	LMB+SHIFT	LMB+SHIFT
Dragger reposition ${}^{*}$	LMB+CTRL	LMB+CTRL	LMB+CTRL

while those for Laptop and Mac 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)
Select components	LMB+CTRL	LMB
Multiple selection	LMB+SHIFT+CTRL	LMB+META
Elliptic selection	LMB+CTRL	LMB
Elliptic deselection ${}^{*}$	LMB+SHIFT+CTRL	LMB+SHIFT
Resize elliptic cursor	LMB+SHIFT+CTRL	LMB+SHIFT+CTRL
Context menu	RMB	LMB+CTRL
Transformer control (Section 5.2)
Move dragger	LMB	LMB
Dragger constrain ${}^{*}$	LMB+SHIFT	LMB+SHIFT
Dragger reposition ${}^{*}$	LMB+ALT	LMB+ALT

3.11 Keyboard shortcuts

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

Play controls (Section 2.6):
Key	Operation
q	quit ArtiSynth
t	toggle time line visibility
z	undo last command
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.5)
a	toggle visibility of axes showing world coordinates
g	toggle viewer grid (Section 3.6)
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

2 Loading, Simulating and Saving Models 4 Component Navigation and Selection

Generated on Thu Sep 5 15:24:57 2024 by LaTeXML [LOGO]