ArtiSynth User Interface Guide

By default, ArtiSynth tries to store user-specific settings and configuration information in various files located under the user configuration folder, the path to which is given by

  <HOME>/ArtiSynthConfig

where <HOME> is the user’s home folder. Default instances of these files will be created when they are first accessed or recreated if they are later found to be corrupt or missing.

Some models can be loaded directly using the Models menu located in the ArtiSynth menu bar (Figure 1). By default, the upper part of this menu contains a number of submenus:

In addition, if artisynth_models has also been installed, or if ArtiSynth otherwise detects the presence of the superpackage artisynth.models, then the Models menu will also contain:

Each submenu expands out to identify a set of models. Selecting one of the models will cause it to be loaded into ArtiSynth and displayed in the viewer. Hovering over one of the entries will display the full classname of the associated RootModel. The files demoModels.txt and mainModels.txt are located in the settings subfolder of the user configuration folder (Section 1.1); default instances of these are created the first time ArtiSynth is run, and they can later be modified by the user.

The lower part of the model menu, beneath the separator, contains entries for reloading recent models (Section 2.4), loading a model from an explicitly specified class (Section 2.2), and customizing the upper part of the the model menu (Section 13).

Model menu customization is is needed to create menu entries for root models not defined within (or beneath) the packages artisynth.demos or artisynth.models.

As mentioned above, models are defined by subclasses of RootModel. A model may therefore be loaded into ArtiSynth by directly specifying the class that defines its RootModel. To do this, choose “Load from class ...” from the lower part of the model menu, which will bring up a model selection dialog as shown in Figure 2.

Users should specify the name of the package containing the model in the “Model package” field at the top. Using the <TAB> character in this field will invoke auto-completion based on currently know packages, while repeated use of either <TAB> or the up/down arrows will scroll through known packages. Package entry is completed using the <ENTER> key, and any models that appear in that package (but not its subpackages) will then be displayed in the “Model class” panel below it. The user can then select the desired model by clicking on it. In Figure 2, the model defined by the class artisynth.demos.mech.LaymanDemo has been selected.

If the model requires command-line style arguments to its build() method (as described in the section “Implementing the build() method” of the ArtiSynth Modeling Guide), these can be entered in the “Build args” field near the dialog bottom. Arguments should be separated by white space, with those containing white space placed between double quotes ‘"’. The last field, “Waypoints file”, can optionally be used to specify a file containing simulation way points (Section 7.3.1). As with all externally loaded waypoint data, the waypoints must match the current model structure.

When all desired settings have been made, the model can be loaded by clicking the Load button.

Finally, it is possible to load a model from a file. Selecting “Load model ...” from the File menu will bring up a File browser that lets you select and load a model from an ArtiSynth model file. ArtiSynth model files are text-based documents that contain a hierarchical description of all the model’s components, and are typically identified by the extension .art.

When loading a model from a .art file, it is necessary to have all classes associated with that model in the current Java classpath. This can be an issue when loading files generated by other users using application-specific Java code. Two possible solutions to this are: (a) bundling the application-specific code into a .jar file and adding it to the external classpath (Section 2.9), or (b) making sure that the file was saved using only artisynth_core components, as described in Section 2.8.

After a model has been loaded by any of the methods described above, it can be reloaded by selecting “Reload model” from the lower part of the model menu. Models which have been recently loaded can be reloaded by selecting “Load recent” from the Models menu.

When working repeatedly with a specific model, it can be useful to set that model to automatically load when ArtiSynth starts up. This can be done by setting the startup model, by choosing “Startup model ...” from the Settings menu. This will open a startup model dialog as shown in Figure 3.

The model to load can be specified either by class or by file. To specify the model by class, one uses the “Model package”, “Model class” and “Build args” fields to choose the model class and optional build() method arguments in the same manner as described in Section 2.2. To specify the model by file, one instead uses the “Model file” field to select a model file, as described in Section 2.3.

For either kind of model, it is also possible to use the “Waypoints file” field to specify a file of saved waypoints to be loaded along with the model. As with all externally loaded waypoint data, the waypoints must match the current model structure. Waypoints are described in Section 7.3.1.

• •

  To save the startup model, click the Save button at the bottom of the dialog.

• •

  To clear the startup model (so that no model is loaded), click the Clear button followed by the Save button.

• •

  To load a specified model immediately, click the Load Model button.

Once a model is loaded, simulation of the model can be started, paused, single-stepped, or reset using the play controls (Figure 4) located at the upper right of the ArtiSynth window frame. Play controls are discussed in more detail in Section 7.2.1.

Play controls are also available in the ArtiSynth timeline (Section 7). Also, hitting the ‘p’, ‘s’ and ‘r’ keys from within the viewer (Section 3.11) can be used to play/pause, single step and reset the simulation.

The ArtiSynth application contains a toolbar that runs along the top of the frame. The right side contains the play controls shown in Figure 4.

When a grid is enabled in the viewer (Section 3.6), a text box appears in the center of the toolbar displaying the current grid units (Section 3.6.1).

The left side of the toolbar contains the following buttons:

If real-time is enabled (via the last button), the ArtiSynth scheduler will try to make the apparent simulation speed equal to real time. Simulations can of course run much slower than real time if they involve complex models with many degrees of freedom (such as large finite element models). However, for simpler models, real-time can also increase the overall simulation time, which is why the option to disable real-time is provided.

An ArtiSynth model can be saved to a file to be reloaded and used later. Selecting “Save model as ...” from the File menu will bring up a dialog that lets you select the name and directory for the model file (Figure 5). If a model file has already been specified, then one can save to it again by selecting the Save model menu item. ArtiSynth model files are text-based and are typically identified by the extension .art.

When using the “Save model as ...” menu item, the user may choose the following options:

Save waypoint data:

Causes the state data for any valid waypoints (Section 7.3) to be saved (within the file) in addition to the waypoint locations. This is optional because a large number of waypoints may significantly increase the file size for models with a large state sizes.

Core components only:

Saves only those components which are present in the main artisynth_core package. Any non-core components, and any other components which have a hard dependency on them, will not be written, and the user will be advised of this via a message dialog. The root model (Section 4.1) is saved as a pure instance of RootModel, instead of the application-specific class that was used to build it. This means that any properties or class overrides specific to the application root model class will not be present in the saved model. The advantage to storing a model using only core components is that it can be loaded by any other user running the same ArtiSynth version, without needing access to any application-specific classes.

As mentioned above, the classpath(s) for models declared outside of artisynth_core must be made visible to ArtiSynth so that they can be found and loaded. Detailed information on this topic is given in the section “Making external models visible to ArtiSynth” of the ArtiSynth Installation Guide.

An easy way to make classpaths visible to ArtiSynth is to add them to the external classpath, which is a list of top-level class folders and/or .JAR files containing the classes required to run external models. These may include both model classes and any external Java libraries that they require.

The external classpath is contained in a file named EXTCLASSPATH in the user configuration folder (Section 1.1). This file can be edited directly from ArtiSynth by selecting “External classpath ...” from the Settings menu, which will open the editing dialog shown in Figure 6.

The current class folders and JAR files are listed, one per line, in the large panel at the left. If the external classpath is empty, this panel will be blank. New class folders or JAR files can be added using the “Add class folder” and “Add JAR file” buttons at the right, which invoke file choosers appropriate to the file type. Existing entries can be selected and then edited, moved up or down in the list (using the up/down arrow buttons), or deleted (using the X button). When editing is complete, the updated external classpath can be saved using the Save button at the bottom.

ArtiSynth must be restarted for external classpath changes to come into effect.

ArtiSynth maintains the notion of a working folder, which is the default folder (or directory, in Unix parlance) under which the files used to store various types of model information are stored. This includes model files, as described above, along with other files such as those used to store waypoints, probe configurations, or probe data (Section 8).

Chooser dialogs for these files will generally be initialized to the working folder if their files have not been previously set.

The working folder is initialized to the system working folder from which the ArtiSynth application is started. Once ArtiSynth is running, it can be set by choosing “Set working folder ...” from the File menu, or by calling

   ArtisynthPath.setWorkingFolder (file)

in code. When a model is saved (Section 2.8), the working folder is saved with it and restored when the model file is subsequently loaded.

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.

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,

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:

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.

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.

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.

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.

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.

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

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

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.

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

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().

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 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:

while those for Laptop and Mac are:

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

An example component hierarchy is shown in Figure 15. 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.

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 16 shows an navigation panel containing a superset of the hierarchy diagrammed in Figure 15.

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.

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.11) clears the current selection.

The selection display Figure 19 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.

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.

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 19). 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.

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.

A specialized tool is available for selecting FEM nodes, because it is often necessary to identify collections of nodes for connecting to rigid bodies or other FEM models, or to set localized properties and/or boundary conditions.

To open the node selection tool, first select the FEM model containing the nodes, and then invoke the context menu (usually via right-click) and choose “Select nodes ...”. A node selection tool will appear, as shown in Figure 20. From top to bottom, this contains several controls:

1. 1.

   A selection mode chooser that specifies how nodes are selected, possibly followed by mode-specific fields to adjust the selection behavior;

2. 2.

   An instruction box describing what action the user should take;

3. 3.

   A surfaceNodesOnly check box that allows selected nodes to be restricted to the FEM model’s surface;

4. 4.

   Buttons for clearing, growing or shrinking the selection, reducing the selection to its boundary, or for filling it in;

5. 5.

   Buttons for saving/loading a list of the selected nodes to/from a file, or for attaching or detaching selected nodes from other bodies.

While a node selection tool is open, GUI selections are restricted to certain components, usually nodes of the indicated FEM model. If surfaceNodesOnly is checked, selection is restricted to the FEM surface nodes. Selection is also held in a “multiple component” mode, equivalent to holding down the multiple selection key (usually CTRL), so that the selection can be easily edited and is not reset with each selection action.

The different selection modes and their parameters include:

INDIVIDUAL

Nodes are selected directly by the user, using click, box or elliptic selection (Sections 4.3.1 and 4.3.2). Selection is held in a “multiple component” mode, regardless of whether the “multiple selection” modifier key is pressed.

PATCH

Nodes are selected, on the mesh surface, within a patch region defined by a set of faces for which the bend angle between adjacent faces is less than or equal to a specified maximum bend angle. The bend angle is defined as the absolute value of the angle between two faces along their common edge, such that parallel faces have a bend angle of and perpendicular ones have a bend angle of . Within the tool, the maximum bend angle is specified (in degrees) by the field maxBendAngle. To find the patch nodes, the user selects a node within the desired patch area. Starting with the node’s adjacent faces, the patch is then grown outwards to find all neighboring faces such that the bend angle between them does not exceed maxBendAngle (Figure 21, left).

EDGE_LINE

Nodes are selected, on the mesh surface, along an edge line defined by faces meeting at a bend angle greater than or equal to a specified minimum bend angle. Within the tool, this minimum angle is specified (in degrees) by the field minBendAngle. To find edge line nodes, the user selects a node lying along the desired edge line. The line is then followed from node to node, by locating edges with a large enough bend angle.

EDGE_LINE selection is illustrated in Figure 22, and the following fields adjust its behavior:

minBendAngle

Minimum bend angle, described above.

maxEdgeAngle

Specifies (in degrees) the maximum edge angle between two adjacent edges along the edge line. Line following is terminated when the angle between the current edge and the next edge exceeds this threshold.

allowBranching

If selected, allows the edge line to branch in different directions. Otherwise, edges are followed sequentially so as to minimize the edge angle between them.

DISTANCE

Nodes are selected based on being within a prescribed distance of a polygonal mesh, which may be the surface mesh for a rigid body or FEM model, or some other mesh component. The distance threshold is specified by the field distance. To select nodes, the user may select any mesh component containing a polygonal mesh. The user may also select a rigid body or FEM model, which will cause the body’s surface mesh to be used for the distance calculation.

The following fields adjust the behavior of DISTANCE selection:

distance

Distance threshold, described above.

useSignedDistance

If selected, causes the distance computation for closed meshes to be signed, so that nodes inside the mesh will have a negative distance. This means that for a non-negative distance threshold, nodes inside the mesh will always be selected.

surfaceNodesOnly

If checked, the selection is restricted to the FEM model’s surface.

MINIMUM_PATH

In this mode, the user selects an individual node, and the tool then selects a minimum path of nodes between it and the previously selected node. This is particularly useful for “drawing” the boundary of a nodal region on the FEM model’s surface.

If surfaceNodesOnly is checked, the path will be restricted to the FEM surface; otherwise, the path may proceed through the FEM interior.

When forming the path, the tool chooses from adjacent nodes based on the topology induced by the FEM elements. This can sometimes lead to a path that is less minimal than if nodes could be chosen arbitrarily, particularly for quadratic hex, wedge and pyramid elements.

The user is free to change modes during the selection process. Because selection is held in multiple selection mode, it is easy to edit the selection. In particular, INDIVIDUAL selection can be used for fine editing of selections obtained using PATCH, EDGE_LINE, DISTANCE, or MINIMAL_PATH.

Below the surfaceNodesOnly check box, the tool contains a number of buttons:

Clear

Unselects all the nodes.

Grow

Enlarges the current selection to include adjacent nodes.

Shrink

Reduces the current selection by removing nodes on the boundary.

Boundary

Reduces the current selection to include only its boundary nodes (Figure 21, right).

Fill

Fills a region in the current selection. After clicking this button, the user selects a node inside the desired region. The selection is then grown outward from the selected node until it reaches the region’s boundary.

Attach nodes

Attaches the selected nodes to another body which is either a rigid body or an FEM model. The body may be chosen by selecting it directly, or by selecting one of its component meshes. Nodes which are currently attached are not attached to the body.

Detach nodes

Detaches all selected nodes from any body or particle that they are currently attached to.

Save

Saves the nodes to a file that has been previously specified using either “Save as ...” or “Load ...”.

Save as ...

Saves the nodes to a user-specified text file. The format consists simply of integer node numbers (with respect to the selection tool’s FEM model), separated by white space. More details on the file format are given in the section “Selecting nodes in the viewer” of the ArtiSynth Modeling Guide.

Load ...

Loads the selected nodes from a text file, the format for which is described under “Save as ...”.

The transformation tools employ the dragger fixtures shown in Figure 23, which allow 3D geometrical transformations to be performed within the viewer.

Translator

Effects a translation. The x, y, and z axes are indicated by red, green, and blue lines. Dragging any line causes a one-dimensional motion along the associated axis. Dragging one of the boxes causes a two-dimensional motion in the associated plane.

Rotator

Effects a rotation. Rotation about the x, y, and z axes is indicated by red, green, and blue circles. Selecting and dragging along one of these circles produces a rotation about the corresponding axis.

TransRotator

Combines the translator and rotator into a single tool. One difference is that the axes of the transRotator move with any rotation, and so operations are done with respect to the transRotator coordinate frame at the beginning of the drag.

Under the default mouse bindings, the basic drag operations involving these fixtures are invoked using the left mouse button with no modifier keys. Additional modifier keys allow constrained transformation or repositioning of the fixture, as described below.

A number of transformer tools use the dragger fixtures described above to translate, rotate, and scale components. Once a tool is activated, then selecting one or more transformable components will cause the corresponding dragger fixture to appear in the viewer at the components’ location. If a single component is selected and that component is associated with a coordinate frame (by implementing the HasCoordinateFrame interface), then the dragger’s initial position and orientation are aligned with this coordinate frame. Otherwise, the dragger is initially placed at the center of the selected components with an orientation aligned to world coordinates.

The initial dragger orientation can be adjusted in the following ways:

1. 1.

   To request that a dragger’s initial orientation is always aligned with world coordinates, choose “Interaction ...” from the Settings menu and set initDraggersInWorld to true.

2. 2.

   Conversely, when transforming a set of point-like objects which lie either within a plane or along a straight line, it can be useful to align the dragger’s orientation to the points. To request this behavior, choose “Interaction ...” from the Settings menu and set alignDraggersToPoints to true.

The transformer tools include:

. Translation:
Translates selected components using the translator dragger.

. Rotation:
Rotates selected components using the rotator dragger.

. TransRotation:
Translates and rotates selected components using the transRotate dragger. The transformation reference frame moves with the tool.

. Constrained translation:
Translates selected components using the translate dragger while ensuring that they are constrained to remain on a surface mesh. Only components with an associated surface mesh (such as FrameMarkers attached to a RigidBody) can be transformed this way.

. Scaling:
Scales selected components using the transrotator fixture. Instead of translating, translational drag operations scale the component along the x, y, or z axes, or in the x-y, y-z, or z-x planes. Rotational operations, if used in conjunction with an appropriate modifier key, can be used to change the orientation of the scaling axes, as described in 5.2.2.

. Pull tool:
Pulls on certain components using a spring-like force when simulation is running.

Selecting the pull tool allows a user to interactively apply a spring-like force to certain component types by clicking on it and then dragging (Figure 25). Double clicking on the component adds a pull point that persists between mouse clicks; to remove the pull point, double click on the viewer background.

The pull tool works on points, rigid bodies, FEM models, or any other component that implements the PointAttachable interface and has a surface mesh. Pull manipulation is only effective when simulation is running. It works by adding a special PullController to the current root model’s set of controllers. When attached to the root model, the controller attempts to estimate an appropriate spring stiffness based on the overall mass and dimensions of the first underlying MechModel.

If necessary, the pull tool’s stiffness setting can also be adjusted manually by selecting PullController > properties in the Settings menu. Render properties for the pull controller can be set from this menu also.

. Marker tool:
Adds point markers to certain components.

Selecting the marker tool allows a user to interactively add point markers to various components in the model.

Markers can be added by double-clicking on rigid bodies, FEM models, and other components that implement the IsMarkable interface.

Markers are typically added to a component’s surface mesh, and in such cases it is necessary that this surface mesh be visible. For FEM models in particular, the surfaceRendering property should be set to something other than None. To ensure this is the case, select the FEM model, right-click and choose “Edit properties ...”, and examine the setting for surfaceRendering. An FEM model can sometimes appear to have a visible surface mesh, even if it doesn’t, if its elementWidgetSize property is close to 1.

The markers themselves are added to the current root model at a location that depends on the component being marked:

• •

  Rigid bodies: marker is added to the frameMarker list for the body’s parent MechModel;

• •

  FEM models: marker is added to the FEM model’s marker list;

• •

  IsMarkable components: marker is added to the root model’s marker list (which is created on demand if needed).

In order for added markers to be visible, the component list into which they are placed needs to be visible, with its point rendering properties set to appropriate values. That usually means that pointStyle is set to SPHERE or CUBE, with pointRadius set to a value commensurate with the model’s dimensions, or pointStyle is set to POINT, with pointSize set to a sufficiently large value in pixels. If not set within the list itself, the point rendering properties will be inherited from ancestor components. For example, if a MechModel’s point render properties are set for good visibility, then all points within subcomponents will be visible unless these setting have been overridden at a lower point in the hierarchy.

If markers are not appearing when using the marker tool, use the navigation panel to open the component list to which the markers are added (as described above). Verify that markers are actually being appended to the end of the list. If they are not, ensure that the component’s surface mesh is visible. If they are, select the list itself, right-click, and choose “Edit render props ...”. Check that visible is true, and that pointStyle and pointRadius (or pointSize) are set appropriately.

Once created, markers can be removed by selecting them and choosing Delete from the context menu.

To edit properties for a set of components, select the components in question, then right-click in either the viewer or the navigation panel, and select Edit properties. This will create a property panel for all properties which are common to the selected components. All typical property panel is shown in Figure 26.

Property panels are initialized with the current values of the selected components, providing a view of the current property state. A blank property value will be displayed when more than one component is selected and the corresponding property value differs across components.

Some properties are read only. In this case, the corresponding widget in the property panel will display the value but will be disabled.

Property panels are non-modal and persistent. They can be deleted by closing them or clicking the OK button. Clicking the Cancel button will cause the properties to be reset to their values at the time to panel was created.

Normally, a property panel will refresh its widget values whenever the model view is rerendered. In particular, this will happen repeatedly while simulation is running. To disable the automatic refresh, click the live updating button at the lower left of the panel.

Render properties are associated with any component that is renderable. They are defined in the class RenderProps. Because of their complexity, they are adjusted through a separate panel from the standard property panel.

To adjust the property panel for a set of components, select the components in question, using either the viewer window or navigation panel, and then right click in either the viewer or the navigation panel. Several options may appear in the context menu:

Edit render props

This will create a special property panel allowing the render properties for the selected components to be set (see Section 6.2.1 and Figure 28).

Clear render props

This will actually remove the render properties from the selected components (i.e., their render properties will be set to null). Nominally, this means that the components will not be rendered, unless their parents take responsibility for rendering children without render properties. The latter behavior is common for lists of particles, springs, finite elements, etc., in order to avoid the need for defining render properties in a large number of objects.

Set visible

This option will appear if any of the selected objects are invisible. Selecting it will set the render properties so that all components are visible.

Set invisible

This option will appear if any of the selected objects are visible. Selecting it will set the render properties so that all components are invisible.

ArtiSynth allows models to connect to special components, known as probes, which can either supply input values or monitor output values over time as the simulation proceeds. Probes attached to simulation inputs are known as input probes (class InputProbe), while those attached to outputs are known as output probes (class OutputProbe). Each probe has a start time and a stop time, and implements an apply(t0,t1) method that supplies (or collects) data for the simulation step between time t0 and t1. Probes are described in more detail, along with specifics about how to code them into applications, in the “Simulation Control” chapter of the ArtiSynth Modeling Guide.

The most commonly used probe subclasses are NumericInputProbe and NumericOutputProbe, each of which is associated with a vector of floating point values that are interpolated over time. This data is usually connected to various model component properties, and used to either set (for input probes) or collect (for output probes) the values of those properties. The size of the vector is known as the probe’s vector size and matches the properties that the probe is connected to. For example, a probe controlling a single muscle excitation value will have a vector size of one, whereas a probe collecting the 3D velocity of a point will have a vector size of three.

Within a numeric probe, data is defined by a temporal sequence of knots points which give the vector values at prescribed times, with values in between determined by interpolation (Section 7.5.7). For input probes, the knot density is often sparse, whereas for output probes it matches the sample rate at which data is collected, which is usually the simulation step size.

Input and output probes are arranged and displayed graphically in the timeline, within a set of tracks (Section 7.4). Each probe is displayed as a bar within one of these tracks. The display for numeric probes can also be expanded to show a graph of the numeric data (Section 7.5).

ArtiSynth allows models to set temporal waypoints, which are designated times at which the model state is saved during simulation. This allows the simulation to be later reset to that time without having to recompute the simulation from the beginning. A special type of waypoint is known as a breakpoint, which causes the simulation to pause when it is reached. The timeline displays the waypoints, and allows them to be created and edited (Section 7.3).

The basic structure of the timeline is shown in Figure 29.

The toolbar at the top contains the following widgets:

Zoom controls

Shrinks or expands the timescale.

Play controls

Starts, pauses, or resets the simulation.

Save button

Saves the data for all output probes with attached files.

Time box

Shows the current simulation time.

Time step box

Shows the length of time associated with a “single step” command.

Probes are arranged on tracks located beneath the waypoint track. Input probes must be placed on input tracks and output probes must be placed on output tracks. Furthermore, probes on the same track are not allowed to overlap.

Note:
In the future, additional restrictions may be placed on what type of probe can be placed on what track.

Probes can be moved horizontally to different times as well as vertically onto different tracks. They can also be stretched by dragging the edges of the probe and cropped by holding the control key while stretching.

On the left side of the timeline is the track panel, which contains a number of track control widgets (Figure 31).

Data associated with numeric probes is displayed as a graph within the display (Figure 32), with each entry in a probe’s data vector drawn as a separate trace. If the probe’s vector size is greater than one, each trace is drawn using a different color (up to a limit, after which colors are reused).

Each ArtiSynth probe can be associated with an attached file to (or from) which its data can be saved (or loaded). The attached file is specified by the probe’s attachedFile property, which is a string giving the file’s path name. An absolute path locates the file relative to the system root folder, while a relative path locates it relative to the current value of ArtiSynth’s working folder (Section 2.10). If the attachedFile property is null, then the probe does not have an attached file.

For numeric probes, the file format used to save and load data is described in the “Data file format” subsection of the “Simulation Control” chapter of the ArtiSynth Modeling Guide.

Data for an individual probe can be saved or loaded by first selecting it (either within the navigation panel or by left-clicking on its timeline display bar), and then right-clicking and choosing one of the following options from the resulting pull-down menu:

Save data

If the probe has an attached file, saves its data to that file.

Save data as ...

Brings up a file chooser allowing the user to specify an attached file for the probe. Clicking the Save As button then sets the attached file and saves the probe’s data in it. The probe’s attachedFile property will be set to a relative path name if the file is located beneath the current ArtiSynth working folder (Section 2.10), and an absolute path name otherwise.

Load data

If the probe has an attached file, loads its data from that file.

Load data from ...

Brings up a file chooser allowing the user to specify an attached file for the probe. Clicking the Load button then sets the attached file and loads the probe’s data from it. The probe’s attachedFile property will be set to a relative path name if the file is located beneath the current ArtiSynth working folder, and an absolute path name otherwise.

In addition, data can be saved for all output probes that have attached files by either selecting “Save output probe data” from the ArtiSynth File menu, or by clicking on the timeline’s save button (C in Figure 29).

The data associated with a numeric probe can also be exported to either a CSV file (*.csv) or a regular text file (*.txt).

Each line in the file describes the numeric data associated with one of the probe’s knot points, and consists simply of a sequence of numbers, where is the probe’s vector size. For CSV files, the numbers are separated by commas, while for text files they are separated by spaces. If “include time data” is selected in the export dialog (see below), then the knot’s time value is also included at the beginning of the line, so that the complete sequence includes numbers.

The time values exported with a probe are probe relative, so that corresponds to the probe’s start time and any scaling is ignored.

To export a probe’s data, first select the probe (either within the navigation panel or by left-clicking on its timeline display bar), and then right-click and choose “Export data as ...” from the resulting pull-down menu.

This brings up a dialog (Figure 42) that allows the user to specify the file name and output file type (CSV or text). It also allows the user to specify export-specific properties, such as:

numeric format

A printf-style format string specifying the formatting for floating point data. The default value is %g, which means all numbers will be written to full precision with a variable length and using scientific notation if needed. Other allowed formats are described in the documentation for maspack.util.NumberFormat.

include time data

A Boolean value which if true indicates that time data should be included along with the numeric values. Not including time data may be appropriate when the data is spaced at a known time interval.

The model’s entire configuration of input and output probes can be saved to (or loaded from) a single file. This file stores, in an ASCII text format, complete information about each probe, including its start and stop times, location within the timeline, which model properties it connects to, the name of its attached file (if any), and its current data. The file also stores the current waypoint locations, but does not store waypoint data.

Once saved, a probe file can be later loaded to reset the entire probe configuration.

Probes can be saved or loaded by either opening the ArtiSynth File menu, or by right-clicking on the timeline’s waypoint track, and selecting one of the following:

Save probes as ...

Brings up a file chooser that allows the user to specify a file for saving the current probe configuration. Clicking Save As completes the operation.

Save probes

If a probe file has already been specified using either “Save probes as ...” or “Load probes ...”, then the current probe configuration is saved to that file.

Load probes ...

Brings up a file chooser that allows the user to specify a file from which the probe configuration will be loaded. Clicking Load completes the operation.

To add a numeric output probe, go to the main menu and choose edit > add output probe. This will create a numeric output probe editor, as shown in Figure 43.

The editor contains three main panels:

• •

  A property panel at the upper left in which allows you to add or edit the properties of model components whose values will be used in computing the final output probe value. Each property is associated with a component/property widget, which allows you to first select a component and then choose one of its properties.

• •

  A formula panel at the the upper right which allows you to add or edit formulae which convert the values from the properties into numeric values for the output probe.

• •

  A probe property panel at the bottom which allows properties of the probe itself to be set.

To add a numeric input probe, go to the main menu and choose edit > add input probe. This will create a numeric input probe editor, as shown in Figure 45.

The editor contains three main panels:

• •

  An input panel at the upper left which allows you to add or edit input variables. Each of these variables represents a sub-vector of the probe’s numeric input vector.

• •

  A formula/property panel at the the upper right which allows you to add or edit numeric properties (using component/property widgets), along with formulae to determine values for these properties based on the input variables.

• •

  A probe property panel at the bottom which allows properties of the probe itself to be set.

The lower part of the probe editor contains a set of fields for editing various probe properties.

name

The name of the of the probe.

start time

Start time for the probe, in seconds.

stop time

Stop time for the probe, in seconds.

scale

Specifies the scale for this probe, which relates the internal probe time to the external simulation (or timeline) time . If is the time at which the probe starts on the timeline, then .

attached file

Names the attached file for this probe, used for storing the probe’s date. See Section 8.1.

display range

Minimum and maximum range values used for the graphical display of the probe’s data. If these values are left blank, then the range is computed automatically.

update interval

(Output probes only). A time interval, in seconds, specifying how often data should be output to the probe.

Settings for the viewer and mouse are discussed in Sections 3.9 and 3.10. Settings related to model interaction and simulation as discussed in the sections below.

Preferences are settings saved in the user’s configuration data so that they are restored when ArtiSynth is restarted. They are stored in the file settings/preferences within the configuration folder (Section 1.1).

Preferences can be edited by selecting “Preferences ...” from the Settings menu, which opens a preferences editor dialog (Figure 51). A panel on the left contains a tree-based representation of the different preferences, which can be used to select a specific set of preferences which can then be adjusted using a preferences panel panel displayed on the right.

Values shown in the preferences editor describe stored values that are set when ArtiSynth is restarted, and setting them will not change the current settings in the ArtiSynth application. However, most preferences panels contain the button “Apply to current” which will apply the values to the current application settings. Other buttons include “Set from current”, which loads the values from the current application settings, and “Reset defaults”, which resets the panel values to their defaults.

To save preferences in the user’s configuration data, one should click the Save button at the bottom right of the preferences editor. The “Reset all defaults” button located at the bottom left resets all preference values to their defaults; the Save button must subsequently be used to save these reset values.

Preferences that can be set include settings for the viewer and mouse (Sections 3.9 and 3.10), model interaction and simulation (Section 11.1), and making movies (Section 14.5). Preferences can also be set for the application layout, as described in the next section.

Layout preferences control the size and visibility of different application windows, as well as the look and feel of the user interface.

viewerWidth

Width of the main ArtiSynth viewer (in pixels). Note that this and the viewerHeight property describe the size of the viewer itself, and not the overall application window containing the viewer. The viewer width can also be set from the command line with the option

  -width <pixels>

viewerHeight

Height of the main ArtiSynth viewer window (in pixels). This can also be set from the command line with the option

  -height <pixels>

screenLocX

Screen x location of the main ArtiSynth frame (in pixels). This can also be set from the command line with the option

  -screenx <pixels>

screenLocY

Screen y location of the main ArtiSynth frame (in pixels, with 0 at the top of the screen). This can also be set from the command line with the option

  -screeny <pixels>

timelineVisible

Whether or not the timeline (Section 7) is visible when ArtiSynth starts up. The default value is true. Initial timeline visibility can also be controlled with the command line options

  -timelineVisible
  -timelineHidden

timelineWidth

Initial width of the timeline (in pixels). This can also be set from the command line with the option

  -timelineWidth <pixels>

timelineHeight

Initial height of the timeline (in pixels). This can also be set from the command line with the option

  -timelineHeight <pixels>

timelineRange

Default timeline range that is used to initialize the visible part of the timeline when a model is loaded. A value implies that the range will be set automatically. If set to a value , the actual amount of time visible may be slightly larger because of the way the timeline is scaled. The timeline range can also be set from the command line with the option

  -timelineRange <value>

timelineLocation

Initial location of the timeline with respect to the main ArtiSynth application window. This can also be set from the command line option with the option

  -timelineLocation <loc>

where loc is one of CENTER, LEFT, RIGHT, ABOVE or BELOW.

jythonFrameVisible

Whether or not a Jython console frame (Section 12) should be displayed when ArtiSynth starts up. The default value is false. A Jython console can also be requested at startup with the command line option

  -showJythonConsole

jythonLocation

Initial location of the Jython frame with respect to the main ArtiSynth application window. This can also be set from the command line with the option

  -jythonLocation <loc>

where loc is one of CENTER, LEFT, RIGHT, ABOVE or BELOW.

lookAndFeel

Controls the look and feel of the user interface (UI). The ArtiSynth UI is built using Java Swing, which supports pluggable look and feel. At the time of this writing, the look and feel options are:

DEFAULT

The default provided by the Java environment. On Windows and Linux systems, this is METAL, while MacOS provides its own proprietary look and feel.

METAL

The standard Swing cross-platform look and feel. On MacOS, it is necessary to specify this explicitly to avoid its native look and feel.

SYSTEM

The native system look and feel.

A restart is required when changing the look and feel. It is also possible to specify the look and feel from the command line using the option

  -lookAndFeel <laf>

where laf is one of the options described above.

The SYSTEM look and feel may cause problems on some systems. For example, at the time of this writing, the Windows UI is not fully compatible with certain dialogs used to save files.

Once the Jython console is open, it can be used to query ArtiSynth structures and model components. Every publicly accessible method of every Java object can be called via the interface. To easily access particular components of a model, the predefined list variable sel provides access to the current ArtiSynth selection list. That means you can select items in the ArtiSynth GUI (using either the viewer or navigation panel) and then access these in Jython. By itself, sel supplies the entire selection list. Specific selected components can be accessed by indexing into this list, so that sel[i] returns the i-th entry (where the index i is 0-based).

For example, if two particles are currently selected in ArtiSynth, then sel can be used as follows:

Once a component has been selected, then one has access to all its public methods. This can be quite useful for setting or querying items are that are not normally available via the ArtiSynth GUI. For example, if we want to find the number of nodes in a FemModel3d, then we can select the FEM and then in the console do

Java objects can also be created by calling their constructors directly, without the need for the keyword new. For example,

creates a new instance of Vector3d and initializes it to (1, 2, 3).

As with Java code, Java class definitions need to be imported into Jython in order for them to be visible. For example,

will import all classes defined in the package maspack.matrix. However, unlike in Java, classes imported into Jython this way will still need to be accessed using their fully qualified class names (e.g., maspack.matrix.Vector3d, maspack.matrix.Matrix3d, etc.). In order to make classes visible using only their basic names, one may use the from statement, as in

To import all classes within a package by basic name, one may employ the wildcard *:

although this may occasionally miss certain classes.

For convenience, the ArtiSynth Jython console already fully imports, by basic name, the classes from the following packages:

Jython can also be used to run simulations, using various built-in functions that allow models to be loaded and run. A full summary of these is given in Section 12.7. In particular, it is possible to load a model and then run or single step a simulation.

To load a model, one may use the function

where name is the classname of the model’s RootModel, and args... is an optional variable-length list of string arguments that are used to form the args argument of the model’s build() method (see the section “Implementing the build() method” in the ArtiSynth Modeling Guide). In general, the name argument should be the fully qualified name of the root model class, as in

However, if the model has been previously loaded by ArtiSynth, the class’s simple name should work as well:

Once loaded, simulation may be controlled using functions such as play(), pause(), step(), or reset(). The play() function may take a time argument indicating the length of time the simulation should be run for; if this argument is omitted, the simulation will run indefinitely or until a breakpoint is encountered. Play requests are issued asynchronously; to make the Jython console wait for simulation to halt, one may use the waitForStop() function:

One can also execute a single simulation step using step():

As with play(), step() does not wait for the simulation to complete. To do that without calling waitForStop(), one may use stepAndWait().

When controlling simulations, it is often easiest to create a script of Jython commands in a Python-style .py file and then "source" them into the Jython console. In Python, one can use exec() or execfile() to do this. However, in ArtiSynth it is recommended to use the ArtiSynth supplied script() function, as in

This is particularly true for longer scripts, since script() interacts better with the GUI and allows the script commands to be displayed in the console as they are being executed.

Scripts are particularly useful for running multiple simulations with varying inputs and outputs. Arguments supplied to a model’s build() method provide a convenient way to adjust input and output parameters between simulations.

As will be seen below, it is also possible to pass command-line style arguments to the script itself. Within the script, such arguments can the retrieved from sys.argv, as illustrated by the following code fragment:

Jython commands, including scripts, can be aborted by clicking the stop-all button to the right of the play controls (Section 7.2.1).

For convenience, ArtiSynth provides a Scripts menu in the main application menu bar that is similar in function to the Models menu and can be used to run script files from predefined menu entries (Figure 53). By default, the upper part of this menu contains a single submenu:

Selecting a submenu entry will cause the Jython console to be opened (if necessary) and the associated script to be executed. At the time of this writing, “Demo scripts” contains a single entry for a demonstration script named demoScript.py.

The lower part of the script menu, beneath the separator, contains entries for reloading recent scripts (”Run recent ...”), running a script from an explicitly specified file (“Run script ...”, Section 12.5), and adding custom entries to the upper part of the script menu ( “Edit menu ...”, Section 13).

To explicitly specify a script file, choose “Run script ...” from the lower part of the script menu, which will bring up a script selection dialog as shown in Figure 54.

Users should specify the folder containing the script in the “Script folder” field at the top. This folder will then be searched for files ending in .py and .jy, with the results listed in the “Script file” panel, from which the user can then select the desired script by clicking on it. If the script requires command-line style arguments (Section 12.3), these can be entered in the “Args” field near the dialog bottom. Arguments should be separated by white space, with those containing white space placed between with double quotes ‘"’.

When all desired settings have been made, the user runs the script using the Run button.

It is possible to specify Jython scripts directly on the ArtiSynth command line using the -script option. For example,

will start ArtiSynth and then immediately invoke the script experiment.py. Scripts can also be run in "batch" mode, without starting the GUI or explicitly opening the Jython console. This can be useful when running ArtiSynth remotely, or in parallel on a cluster of machines. To run a script in batch mode, simply add the -noGui command line option:

Since there is no GUI, Jython will then be initiated using a terminal console instead of the usual GUI-based text window. When the script finishes, the console will remain available for interactive operation.

One may also simply start with a Jython console, with no initial script:

Finally, arguments may be passed to scripts invoked using -script, by placing them immediately after the script specification, enclosed within square brackets [ ]. For example,

will pass the strings "-xxx", "123" and "-off" to the script myscript.py. Within the script, these arguments can the retrieved from sys.argv, as described in Section 12.3.

The following is a summary of the built-in Jython console functions:

getMain()

Returns the ArtiSynth Main object.

loadModel (name, args...)

Loads the named model along with optional arguments. name is the classname of the model’s RootModel and args... is an optional variable-length list of string arguments that are used to form the args argument of the model’s build() method. Nominally, name should be a fully-qualified classname (for example, artisynth.demos.mech.RigidBodyDemo), but if the model has been loaded before, the simple class name should work as well (e.g., RigidBodyDemo).

loadModelFile (filename)

Loads a model from an ArtiSynth file. filename is a string giving the file’s path.

saveModelFile (filename)

Save a model to an ArtiSynth file.

saveModelFile (filename, saveWayPointData, coreCompsOnly)

Save a model to an ArtiSynth file. The options saveWayPointData and coreCompsOnly specify whether to (a) save waypoint data, and (b) save only components from artisynth_core.

play()

Starts the simulation running.

play(t)

Starts and runs the simulation for t seconds.

pause()

Pauses the simulation.

step()

Starts a single simulation step.

stepAndWait()

Starts a single simulation step and waits for it to complete.

reset()

Resets the simulation to time 0.

forward()

Forwards the simulation to the next waypoint.

rewind()

Rewinds the simulation to the last waypoint.

delay(t)

Delays execution for t seconds.

waitForStop()

Blocks until the simulation has completed.

isPlaying()

Returns true if simulation is still running.

getTime()

Returns current ArtiSynth simulation time in seconds.

reload()

Reloads the current model.

addWayPoint(t)

Adds a simulation waypoint at time t, where t is a floating point value giving the time in seconds.

addBreakPoint(t)

Adds a breakpoint at time t.

removeWayPoint(t)

Removes any waypoint or breakpoint at time t.

clearWayPoints()

Removes all waypoints and breakpoints.

saveWayPoints (filename)

Save waypoints and their data to a specified file

loadWayPoints (fileName)

Load waypoints and their data from a specified file

root()

Returns the current RootModel.

find (path)

Finds a component defined by path with respect to the current RootModel.

getsel()

Returns the current ArtiSynth selection list (which is the same as the built-in variable sel).

getsel(i)

Returns the i-th selection list item (where i is 0-based).

quit()

Quits ArtiSynth.

The upper part of the model menu may be customized using the model menu editor (Figure 55), which may be opened by selecting “Edit menu ...” at the bottom of the model menu. The editor comprises a large menu panel on the left side, containing a tree representation of the menu, and an edit panel on the right side which supports various editing actions.

A model menu is composed of a hierarchical arrangement of six types of menu entries, summarized in Table 1 and described in more detail in Section 13.3. Every entry has a title attribute denoting the text used in the actual menu. The set of menu entries is displayed hierarchically in the editor’s menu panel, with each entry indicated by an icon (see Table 1) followed by its title. Entries can be selected by clicking on them using the left mouse button, using the CTRL and SHIFT modifier keys to enable multiple and contiguous selection. Figure 56 shows an example menu panel display on the left with the corresponding model menu on the right.

Editing actions that may be initiated include:

Adding menu entries

The Add buttons in the edit panel allow the different menu entries to be added to the the menu. Add operations for all entry types except separators invoke a dialog for configuring the new entry; details on these are given in Section 13.3. If no entries are selected when the add operation is initiated, the new entry will be placed at the end of the top-level menu. Otherwise, if a submenu entry is selected, the new entry will be placed at the end of that submenu. Finally, if a non-submenu entry is selected, the new entry will be inserted in the location of the selected entry.

Editing menu entries

All menu entries except separators have attributes that can be edited by selecting the entry and clicking the Edit button in the editing panel. Details on these attributes are given in Section 13.3.

Rearranging and deleting menu entries

Menu entries can be rearranged or deleted using the up/down arrow and X buttons:

Rearrangement can be done within a submenu by selecting a contiguous set of entries within that submenu and using the up/down arrows to move them up or down with respect to other submenu entries. Entries can be deleted by selecting any number of them, within any submenu, and clicking the X button.

Saving and loading from files

The Save and Reload buttons at the bottom of the edit panel can be used to save/reload the current menu to/from the initialization file settings/modelMenu.xml, located in the user configuration folder (Section 1.1). The buttons ”Save to ...” and “Load from ...” can be used to save/load the menu from alternative files. The “Reset to default” button in the lower left corner of the dialog resets the menu and its configuration files to their original settings.

Changes that are made in the menu editor appear immediately in the model menu itself. Changes which involve adding, deleting or rearranging entries can be undone using the Undo option in ArtiSynth’s main Edit menu (Section 16.1.3).

Submenus which are empty are displayed in the menu editor but not in the menu itself. Submenus may be empty if no entries have been added to them, or if the model entries specified within them are not actually found. The latter most commonly occurs when the packages containing said models are not visible to ArtiSynth.

The upper part of the script menu may be customized using the script menu editor (Figure 57), which may be opened by selecting “Edit menu ...” at the bottom of the script menu. Its structure and function is essentially identical to the model menu editor (Section 13.1), except that the Package, Model, and Demo file entries are replaced by the Script folder and Script entries, as shown in in Table 2 and described in more detail in Section 13.3. The initialization file accessed by the Save and Reload buttons is settings/scriptMenu.xml, located in the user configuration folder (Section 1.1).

It is also possible to explicitly set the model menu using ArtiSynth command line arguments:

-modelMenu <xmlFileName>

Specifies the model menu using an XML file, the format for which is described in Section 13.6. When this is done, the Save and Reload operations described in Section 13.1 are redirected to the specified file instead of the default configuration file.

-demoFile <fileName>

Specifies a basic menu from a simple list of models provided by <fileName>, using the format described in Section 13.5. When this option is used, the model menu editor is not available and the resulting menu cannot be edited.

A plain text file format is used to supply a list of model menu items, for either demo file menu entries (Section 13.3.3), or use with the -demoFile command line option (Section 13.4). In this format, entries are listed as title-class pairs, separated by whitespace. Lines beginning with a hash (#) are ignored. Titles containing spaces must be surrounded by quotation marks. The following is an example:

Model and script menus are stored using a custom XML file format, which is documented here in case users which to create their own files from scratch. The default files specifying the model and script menus are modelMenu.xml and scriptMenu.xml, located in the settings subfolder of the configuration folder (Section 1.1).

XML schemas are provided that describe and enforce the required document structure. The schemas for the model and script menus are located, respectively, in

src/artisynth/core/modelmenu/modelmenu.xsd
src/artisynth/core/modelmenu/scriptmenu.xsd

relative to the ArtiSynth installation folder. The following XML elements are defined:

Detailed descriptions of these element types and their supported attributes are provided in the following sections. Attributes of the model, package, demoFile, script, scriptMenu, submenu, demoFile, label, and separator types correspond to attributes of the menu entry types described in Section 13.3. Attributes marked by an asterisk are required in the element definition.

The Recorder tab (Figure 59) controls which image region to capture along with various recording and other options. Options within the tab are organized into three groups:

The Encoder tab (Figure 61) controls encoder options and the output size.

These options are only used when the capture area is set to Viewer and control the size of the output video, allowing the contents of the viewer to be magnified.

Same as original

The output video is created at the original size.

Constrain proportions

The output video is created with constrained proportions, such that the ratio between height and width are maintained.

Width

Defines the width of the output video.

Height

Defines the height of the output video.

# samples

Sets the number of samples to use for the multi-sample buffer. This only applies in Viewer mode, and is used to perform anti-aliasing.

Note: If your movie comes out black or only shows a section of the viewer correctly in Viewer mode, then it is likely your graphics card does not support multi-sample buffers. On machines with multiple graphics cards (e.g. laptops with both discrete and integrated graphics), make sure the Java process is set to use the discrete card. Otherwise, set # samples = 1 to disable the multi-sample buffer.

The Advanced tab (Figure 62) presently provides two options:

1. 1.

   A “Movie folder” field which allows the movie folder to be customized. This folder can also be saved permanently in the user’s preferences, as described in Section 14.5.

2. 2.

   A “Movie from waypoints” button which creates a movie from the model’s waypoint data. To work correctly, the model must have valid waypoints defined at regular intervals corresponding to the frame rate specified in the Encoder tab. The viewer image of the model at each of these waypoints is used to generate the frame image files from which the movie is then created. This enables a movie to be created from waypoint data without having to run a simulation.

Some of the movie settings described above can be saved permanently in the user’s preferences (Section 11.2). To do this, choose Preferences from the application Settings menu and open the Movies panel.

Preferences that can be currently saved include:

• •

  Frame rate

• •

  Movie method

• •

  Movie method customization

• •

  Movie folder

To specify a method customization, select the desired method and then click the “Customize Method” button.

As described above, movies produced by the default method, which creates JPEG-based movie files, tend to be rather large. If you are making movies regularly, you should consider installing an external movie making application such as FFmpeg, and then setting the movie maker to use this via the Method field on the Encoder tab (Section 14.2). This will significantly reduce the size of the movie file and likely improve movie quality.

At the time of this writing, FFmpeg is available for Windows, Mac and Linux through

ffmpeg.org/download.html

The easiest option is to download a precompiled release. The FFmpeg download site does not provide these itself, but refers to other sites that do. For example, the Windows download page currently contains a link to

Windows builds from gyan.dev

which under git master builds contains a download link for ffmpeg-git-full.7z. This can be extracted into a location such as C:\ffmpeg, after which the installation’s bin folder (e.g., C:\ffmpeg\bin) should be added to your Windows Path environment variable. How to do this is described in the section “Adding Directories to the System Path” in the Windows version of the ArtiSynth Installation Guide.

Detailed instructions for installing FFmpeg on Windows can also be found at sites such as

phoenixnap.com/kb/ffmpeg-windows.

To create a control panel, select Edit > Add control panel from the ArtiSynth main menu. This will cause a blank control panel to appear.