ArtiSynth User Interface Guide

13 Component Editing

Component editing in ArtiSynth is driven by the current selection context: depending on what items are currently selected, different editing options will appear in the context menu. These options may allow you to add, edit, or delete components.

13.1 Generic edit operations

13.1.1 Deletion

A set of selected components can be deleted provided that

  • their parent components are editable

  • none of their ancestors are selected

If the currently selected components are deletable, then a delete option will appear in the context menu (obtained by right-clicking in the viewer or navigation panel). Selecting this will delete the components.

If the selected components are referred to by other components, then those components will be deleted also. In this case, a dialog will be presented to the user advising of this fact and requesting confirmation.

13.1.2 Duplication

A set of selected components may be duplicated provided that

  • their parent components are editable

  • none of their ancestors are selected

  • they implement CopyableComponent

If the currently selected components are duplicatable, then a duplicate option will appear in the context menu. Selecting this will enable duplication of the components: the viewer cursor will change to cross-hairs, and the user may indicate the location for the duplicated components by left-clicking in the viewer (see Section 3.7). Duplication may be canceled by right-clicking.

Sometimes, when the components to be duplicated refer to other components, those referred components will be duplicated also. This is done when the referred components are required. For example, when duplicating an AxialSpring, the two points it is attached to will also be duplicated, because AxialSprings are not permitted to exist without attached points. Such cases are indicated to the user, after the duplicate option has been selected, by expanding the current selection to include all such additional components.

13.1.3 Undo

Many of the operations described here are undoable, by choosing the Undo option from the Edit menu. The menu option will indicate the name of the operation to be undone. Hitting the ‘z’ key from within the viewer (Section 3.9) will also perform undo operations.

13.2 Editing panels

Many editing operations involve the creation of editing panels (such as Figure 38, etc.) which persist beyond the invocation of a context menu. Often, these panels are created exclusively, so that only one can be in existence at once. This is done by having the panel acquire a lock in the ArtiSynth editing manager. The panels are not modal, so the user can still interact with the viewer and other GUI components, but other exclusive editing panels can not be created until the current one is closed. This avoids problems associated with having two “edits” active on a the model at once.

If an exclusive editing panel is open, then other exclusive editing options will still be shown in the context menu but will be disabled.

13.3 Specifying position, orientation, and scaling

Sometimes, an editing panel will allow you to specify the translation and rotation associated with a RigidTransform3d. Typically, this will happen when there is a need to specify the location of a spatial coordinate frame, as in the example of Figure 36.

Figure 36: Panel for specifying the location of a coordinate frame.

Here, the translation and rotation correspond to the fields position and orientation. The position field is straightforward: it is just three numbers giving the position of the coordinate frame origin with respect to the base (usually world) coordinates. In Figure 36, this is the vector (1, 2, 3).

The orientation field is more complex. It corresponds to the rotation of the coordinate frame with respect to base coordinates, and is represented using an axis-angle format of four numbers giving the axis of the rotation, followed by the angle of rotation about this axis, in degrees. (This relies on the fact that any 3D rotation can be specified as a single rotation about a single axis.) Hence the numbers

 0 1 0 60

in Figure 36 correspond to a rotation of 60 degrees about the y axis. Alternatively, the numbers

 1 1 0 45

would correspond to a rotation of 45 degrees about the axis (1, 1, 0). (Note that the axis does not need to be a unit vector.) Finally, no rotation, or more precisely, the identity rotation, is usually represented as

 1 0 0 0

i.e., zero rotation about the x-axis. In more general situations, one may specify not only translation and rotation but also scaling, corresponding to a more general AffineTransform3d. This often occurs when reading a mesh from a file: one may wish to apply an affine transform to scale, rotate, and translate the mesh that is been read in. In such cases one will also be presented with a scale field, which accepts either a single number (to denote uniform scaling), or three numbers (to denote non-uniform scaling about the x, y, and z axes).

13.4 Editing MechModels

A MechModel is the central ArtiSynth component for mechanical simulation. It contains sets of mechanical components, including particles, rigid bodies, axial springs, rigid body connectors, as well as sub-models including other MechModels and finite element (FEM) models. Most of these components can be added to a MechModel graphically, as described below.

To add a component to a MechModel, select the MechModel and choose the appropriate edit action shown in the context menu. A MechModel cannot be selected in the viewer, but can be selected using the navigation panel (Figure 9), or by first selecting one of its visible components in the viewer and navigating up the hierarchy to it using the up arrow of the selection display (Section 4.4).

13.4.1 Adding finite element models

To add a FemModel to a MechModel, select the MechModel and choose "Add FemModel ..." in the context menu. This will open the editing panel shown in Figure 38, which allows the user to provide information about the model’s properties and geometry.

Default values are provided for almost all of this information; the only information that must be specified by the user is the model’s position (corresponding to the origin of it’s volumetric mesh). This can be done either by left-clicking in the viewer (Section 3.7), or by entering coordinates in the position field of the Location subpanel. Once a position is specified, a wireframe preview of the FEM appears in the viewer (Figure 37), showing its geometry and allowing it to be moved or rotated using an attached transformer. The user is then free to continue editing the properties and geometry information, until the model is in the desired form, at which point it can be added to the MechModel by clicking the Add button.

Figure 37: Wireframe preview of the FEM in the viewer.
Figure 38: Panel for adding finite element models.

From top to bottom, the FemModel panel contains:

  • An instruction box containing directions for the user.

  • A General Properties subpanel, which allows the user to set properties for the FemModel. For brevity, some of these properties are hidden and can be expanded by clicking the more... button.

  • A Location subpanel, allowing the position and orientation to be set manually. The position corresponds to the mesh origin, while the orientation is a rotation applied to the mesh, specified in axis-angle format (see Section 13.3).

  • A Geometry panel, allowing specification of the mesh geometry type and various properties specific to this type. Mesh types currently supported include Grid, Tube, Torus, Sphere, Extrusion, AnsysMesh, TetgenMesh and UCDMesh. For many of these, the associated element type can also be specified: Tet (tetrahedron), Hex (hexahedron), QuadTet (quadratic tetrahedron), QuadHex (quadratic hexadredron), and Wedge.

  • An option panel, containing the Add button, a Clear button which resets the displayed fields to default values, and a Cancel button which closes the panel without adding a FemModel.

13.4.2 Adding rigid bodies

To add a RigidBody to a MechModel, select the MechModel and choose "Add RigidBody ..." in the context menu to open an editing panel for rigid bodies, as shown in Figure 39.

As with adding FEM models, default values are provided for most information; the user must only specify the body’s position, either by left-clicking in the viewer (similar to Section 3.7), or by entering coordinates in the position field of the Location subpanel. Once a position is specified, a wireframe preview of the rigid body appears in the viewer (Figure 37), showing its geometry and allowing it to be moved or rotated using an attached transformer. The user is then free to continue editing the properties, geometry and inertia information, until the model is in the desired form, at which point it can be added to the MechModel by clicking the Add button.

Figure 39: Panel for adding RigidBodies.

From top to bottom, the Add RigidBody panel contains:

  • An instruction box containing directions for the user.

  • A General Properties subpanel, which allows the user to set properties for the body. For brevity, some of these properties are hidden; the panel can be expanded by clicking the more... button.

  • A Location subpanel, allowing the position and orientation of the body’s coordinate system to be set manually. Position is specified as a three-vector, while the orientation is given as a rotation in axis-angle format (see Section 13.3).

  • A Geometry And Inertia subpanel, which allows the user to specify the body’s surface mesh geometry and spatial inertia, using the same type of panel as described in Section 13.5.1.

  • An option panel, containing the Add button, a Clear button which resets the displayed fields to default values, and a Cancel button which closes the panel without adding a rigid body.

13.4.3 Adding frame markers

A FrameMarker is a massless Point attached to a RigidBody. It can be used for tracing motions of that body, or as an anchor point for attaching axial springs or other components.

To add one or more frame markers to the rigid bodies in a MechModel, you can select either the MechModel, or one of its rigid bodies, and then choose "Add FrameMarkers ..." in the context menu. This will open a FrameMarker editing panel, as shown in Figure 40. While this panel is open, frame markers can be added by using the viewer and left-clicking the mouse over the surface mesh of the rigid body at the location where you want the marker to be placed (see Section 3.7). The rigid body in question must belong to the MechModel that was originally selected; no marker will be added to bodies that belong to another MechModel or a MechModel which is a submodel of the current one.

Figure 40: Panel for adding frame markers.

From top to bottom, the FrameMarker editing panel contains

  • An Existing frame markers list, showing all the MechModel’s frame markers (expressed by their path names with respect to the MechModel). This list is connected to the selection manager and can be used to select one or more markers.

  • A name field that allows a name to be specified for the marker.

  • A Default marker properties panel, which allows the user to set properties for subsequent FrameMarkers that are added.

  • An instruction box containing directions for the user.

  • An option panel, which in this case contains a Done button which the user should click when finished.

13.4.4 Adding particles

A Particle is a dynamic component, with mass, derived from Point. It is usually connected to other components in a model with either axial springs (Section 13.4.5) or point-to-point attachments (Section 13.4.7).

To add one or more particles to a MechModel, select the MechModel in question and choose "Add Particles ..." in the context menu. This will open a Particle editing panel, as shown in Figure 41. While this panel is open, a particle can be added by left-clicking the mouse in the viewer at the location where you want the particle to be placed, using the constrain to plane option if necessary (see Section 3.7).

Figure 41: Panel for adding particles to a MechModel.

From top to bottom, the Particle editing panel contains

  • An Existing particles list, showing all the MechModel’s particles (expressed by their path names with respect to the MechModel). This list is connected to the selection manager and can be used to select one or more particles.

  • A name field that allows a name to be specified for the particle.

  • A Default particle properties panel, which allows the user to set properties for subsequent particles that are added. For brevity, some of these properties are hidden; the panel can be expanded by clicking the more... button.

  • An instruction box containing directions for the user.

  • A constrain to plane option.

  • An option panel, which in this case contains a Done button which the user should click when finished.

13.4.5 Adding axial springs and muscles

An AxialSpring is a point-to-point force effector that connects two Points and effects a force between them based on their separating distance. AxialSprings and its subclasses can be used to implement linear or nonlinear springs, as well as the subclass Muscle used to implement two-point muscles.

To add one or more axial springs to a MechModel, select the MechModel in question and choose "Add AxialSprings ..." in the context menu. This will open an AxialSpring editing panel, as shown in Figure 42. While this panel is open, axial springs can be added by selecting (using the viewer or any other selection mechanism) the two points to which the spring is attached. Points may include frame markers, particles, or FEM nodes. However, the points must be contained within the MechModel or one of its submodels.

By default, two points must be selected, in succession, for each axial spring added. Alternatively, by selecting add continuously at the bottom of the panel, a continuous sequence of springs will be created whereby the second point selected for a given spring becomes the first point for the spring following it.

Figure 42: Panel for adding axial springs and muscles.

From top to bottom, the AxialSpring editing panel contains

  • An Existing axial springs list, showing all the MechModel’s springs (expressed by the path names, with respect to the MechModel, of their points). This list is connected to the selection manager and can be used to select one or more springs.

  • A name field that allows a name to be specified for the spring.

  • A Spring type field that allows a specific subclass of AxialSpring to be selected.

  • A Default properties panel, which allows the user to set properties for subsequent springs that are added. The properties in question vary depending on the type selected in the Spring type field. For brevity, some properties may be hidden, in which case the panel can be expanded by clicking the more... button.

  • A progress field displaying the path names of the points as they are selected.

  • An instruction box containing directions for the user.

  • An add continuously option as described above.

  • An option panel, containing an Add/Stop button which is used to initiate or stop the addition of springs, and a Done button which the user should click when finished.

13.4.6 Adding rigid body connectors

A BodyConnector is a component that implements constraint-based joints between either two rigid bodies, or between one rigid body and ground. The GUI currently allows two types of joints to be added: spherical and revolute.

To add one or more rigid body connectors to a MechModel, select the MechModel in question and choose "Add RigidBodyConnectors ..." in the context menu. This will open a RigidBodyConnector editing panel, as shown in Figure 43. While this panel is open, a connector can be added by selecting in succession (using the viewer or any other selection mechanism) the rigid bodies associated with it. For the case of a single rigid body connected to ground, the user clicks the Fixed button instead of selecting a second body.

After the bodies have been selected, the connector location must then be specified by left-clicking in the viewer (Section 3.7). By default, the orientation of the connector is aligned with the world axes. This can be adjusted later using the dragger fixtures (Section 5.1).

Figure 43: Panel for adding rigid body connectors.

From top to bottom, the RigidBodyConnector editing panel contains

  • An Existing rigid body connectors list, showing all the MechModel’s connectors (expressed by the path names, with respect to the MechModel, of their rigid bodies). This list is connected to the selection manager and can be used to select one or more connectors.

  • A name field that allows a name to be specified for the connector.

  • A Connector type field that allows a specific connector type to be selected.

  • A Default properties panel, which allows the user to set properties for subsequent connectors that are added. The properties in question vary depending on the type selected in the Connector type field. For brevity, some properties may be hidden, in which case the panel can be expanded by clicking the more... button.

  • A progress field displaying the path names of the rigid bodies as they are selected.

  • An instruction box containing directions for the user.

  • An option panel, containing an Add/Stop button which can be used to initiate or stop the addition of connectors, a Fixed button used to indicate when a rigid body is to be connected to ground, and a Done button which the user should click when finished.

13.4.7 Attaching particles to particles

Within a MechModel, two particles or FEM nodes can be attached together, resulting in what is essentially a single particle that combines the dynamics of both original particles. In particular, these particle attachments are a convenient way to connect FEM models to other FEM models or to particles within a MechModel.

To attach particles contained within a MechModel, select the MechModel in question and choose "Attach particles ..." in the context menu. This will open a ParticleAttachment panel, as shown in Figure 44. While this panel is open, pairs of particles can be attached by selecting in succession (using the viewer or any other selection mechanism) the two particles to be connected.

Figure 44: Panel for attaching particles together.

From top to bottom, the ParticleAttachment panel contains

  • An Existing attachments list, showing all the MechModel’s attachments (expressed by the path names, with respect to the MechModel, of their particles). This list is connected to the selection manager and can be used to select one or more attachments.

  • A progress field displaying the path names of the particles as they are selected.

  • An instruction box containing directions for the user.

  • An option panel, containing an Attach/Stop button which can be used to initiate or stop the attachment process, and a Done button which the user should click when finished.

13.4.8 Attaching particles to rigid bodies

Within a MechModel, particles and FEM nodes can also be attached to rigid bodies. In particular, this provides a way to connect FEM models to rigid bodies within a MechModel.

To attach particles to a rigid body, select the rigid body in question and choose "Attach particles ..." in the context menu. This will open a ParticleRigidBodyAttachment panel, as shown in Figure 45. While this panel is open, particles can be attached to the body by selecting them in succession. By default, the attached particles remain where they are, so that the attachment point is determined by the current particle location relative to the rigid body’s coordinates. However, this will typically not coincide with the body’s surface mesh. By selecting project points onto body at the bottom of the panel, attached points will be relocated to the nearest location on the surface mesh as they are selected.

Figure 45: Panel for attaching particles to a rigid body.

From top to bottom, the ParticleRigidBodyAttachment panel contains

  • An Existing attachments list, showing all the MechModel’s particle to rigid body attachments (expressed by the path names, with respect to the MechModel, of the particles and the bodies). This list is connected to the selection manager and can be used to select one or more attachments.

  • A progress field displaying the path names of the particles as they are selected.

  • A project points onto body field, described above.

  • An instruction box containing directions for the user.

  • An option panel, containing an Attach/Stop button which can be used to initiate or stop the attachment process, and a Done button which the user should click when finished.

13.4.9 Collision handling

Figure 46: Dialog for setting default collision behavior in a MechModel.
Figure 47: Dialog for setting collision behavior between bodies.

In ArtiSynth, collision detection and handling can be enabled between rigid bodies (such as RigidBody), deformable bodies (such as FemModel3d), and more generally any body that implements the interface Collidable. Self intersection is not directly supported, but is indirectly supported for compound deformable bodies that contain sub-collidable components. For example, an FEM model is a compound collidable that may contain multiple surface meshes, some of which can be made to collide with each other. For more details on collision handling, see the “Collision Handling” section of the ArtiSynth Modeling Guide.

The collision response between any two pairs of bodies is determined by a CollisionBehavior component, which contains various properties controlling collision interactions. Two of these can be directly modified from the GUI:

enabled

whether or not collisions are enabled;

friction

the friction coefficient if collisions are enabled.

Collisions handling is managed by a CollisionManager component within each MechModel. Each MechModel provides four default behaviors that determine the default collision response for (a) rigid body pairs, (b) rigid-deformable body pairs, (c) deformable body pairs, and (d) deformable self-intersection. In addition to these, override collision behaviors can be specified for any pairs of bodies. In situations where a MechModel contains sub-MechModels, then the collision behavior for any pair of collidables is controlled by the lowest MechModel in the hierarchy that contains both.

Figure 48: Property panel for the collision manager.

There are several ways to edit collision behavior using the GUI.

  • For default behaviors, the enabled and friction properties can be edited by selecting the MechModel and then choosing "Set default collisions ..." from the context menu. This will open the dialog shown in Figure 46, allowing the enabled and friction properties to be adjusted. For the example shown, collisions are enabled between all rigid bodies, with a friction coefficient of 0.2, and between all rigid and deformable bodies, with a coefficient of 0.1. Other collisions are disabled.

  • If a user selects a particular set of rigid and/or deformable bodies, a specific collision behavior may be established among those bodies by choosing "Set collisions ..." from the context menu. That will open the dialog shown in Figure 47, allowing the enabled and friction properties for this behavior to be set.

  • If a user selects a single deformable body, a specific self-intersection behavior for that body may be established by selecting "Set self collision ...".

  • More detailed collision control can be realized by selecting the MechModel’s collision manager in the navigation panel (Section 4.2). Choosing Edit properties ... or Edit render props ... from the right context menu then allows other properties to be set to control either the collision behavior or the rendering of collisions. A sample property panel is shown in Figure 48, and these properties are described in the “Collision Handling” section of the ArtiSynth Modeling Guide.

  • For more fine-grained control, one may also use the navigation panel to select one or more of the behavior components located under the collision manager (see Figure 49). The first four of these control the default behaviors. Other behaviors, if any, are overrides that have been added either by application code, or through the GUI. Once selected, one can choose Edit properties ... or Edit render props ... from the right context menu to edit their properties. In the case of override behaviors, the context menu can also be used to remove them.

  • Finally, all override behaviors in a specific MechModel may be removed by selecting "Remove collision overrides". This will cause the collision behavior for all bodies to revert to default values.

Figure 49: Expanded navigation panel showing the collision manager and individual behavior components for a MechModel.

13.5 Editing rigid bodies

The GUI provides some ability to edit rigid bodies, (type RigidBody), the most important of which allows the user to edit its mesh geometry and inertia (see Section 13.5.1). If a rigid body is selected, the context menu will provide the following options:

Add FrameMarkers ...

Allows FrameMarkers to be added to the rigid body (see Section 13.4.3).

Select markers

Causes all markers attached to the rigid body to be selected.

Save mesh as ...

Allows the surface mesh to be saved as an Alias Wavefront .obj file.

Edit geometry and inertia ...

Change the mesh geometry and/or inertia (see Section 13.5.1, below).

Attach particles ...

Allows particles to be attached to the rigid body (see Section 13.4.8).

13.5.1 Geometry and inertia

Choosing "Edit geometry and inertia ..." in the context menu for a rigid body opens a geometry and inertia panel, as shown in Figure 50.

Figure 50: Panel for editing geometry and inertia.

The upper part of the panel allows the user to set the mesh geometry, according to a type specified by the geometry type field. Changing the geometry type changes the panel to include fields for setting parameters appropriate to the type. Currently supported types include:

Box

An axis-aligned box, centered with respect to body coordinates, with the x, y, and z widths set by three numbers in a widths field.

Sphere

A sphere, centered with respect to body coordinates, with the radius and the number of vertical mesh slices given by fields radius and slices.

Mesh

A mesh read in from an Alias Wavefront .obj file, whose name is specified by a file name field. The read mesh can also be scaled, offset, and rotated using information provided by scale, offset, and rotation fields (see Section 13.3). The COM button causes the mesh to be offset so that its center of mass (assuming uniform density) is coincident with the origin of the body’s coordinate system (also causing the location of the center of mass to become zero).

Note:
At present, there appears to be a bug in the code that compute inertia from geometry, producing small errors in the center of mass calculation. That means that hitting the COM button will not cause the center of mass to become zero, but instead a small number that will converge to zero if COM is hit repeatedly.

The lower part of the panel sets the body’s spatial inertia. Spatial inertia for a rigid body can be set in three ways, corresponding to the value of the body’s inertiaMethod property:

Density

The spatial inertia is calculated from the density and the surface mesh geometry, with the assumption that the density is uniform.

Mass

The spatial inertia is calculated from the mass and the surface mesh geometry, with the assumption that the density is uniform. The density is computed by dividing the mass by the mesh volume.

Explicit

The spatial inertia is explicitly specified by entering values in the mass, inertia, and center of mass fields. The density is set to the average value obtained by dividing the mass by the mesh volume.

The inertia method can be set using the set inertia by field. Four other fields describe properties associated with the spatial inertia itself:

density

The mass divided by the volume

mass

The scale mass of the body

rotational inertia

The xx, yy, zz, xy, xz, and yz components of the rotational inertia tensor about the center of mass in body coordinates

center of mass

the position of the center of mass with respect to body coordinates.

Depending on the inertia method, the contents of these fields are either set by the user or updated automatically.

13.6 Editing FEM models

The GUI also provides some ability to edit FEM models (type FemModel3d). If an FEM model is selected, the context menu will provide the following options:

Add FemMarkers ...

Allows the user to add marker points to the FEM, as described in Section 13.6.1.

Rebuild surface mesh

Rebuilds the surface mesh for the FEM. The surface mesh is computed automatically from the faces of all the elements, with inside faces being removed. Also, any elements which are fully or partly obscured by an active clipping plane are removed from the calculation, making it possible to create "partial" surface meshes that provide a cutaway view of the model.

Save surface mesh ...

Allows the current surface mesh to be saved to an Alias Wavefront .obj file.

Save mesh as ANSYS file ...

Allows the FEM volumetric mesh to be saved using the ANSYS file format.

13.6.1 Adding FEM markers

A FemMarker is a massless Point attached to a specific FemElement3d. It can be used for tracing motions within that element, or as an anchor point for attaching axial springs or other components. It is analogous to a FrameMarker for FEM elements.

To add one or more markers to an FEM model, you can select the FEM model in question and then choose "Add FemMarkers ..." in the context menu. This will open a FemMarker editing panel, as shown in Figure 51. While this panel is open, FEM markers can be added by left-clicking the mouse in the viewer over the location where you want the marker placed, using the constrain to plane option if necessary (see Section 3.7). An FEM marker is then created and attached to the nearest element in the FEM. If the marker position is outside the FEM, it is projected onto the closest point on the FEM surface.

In addition, the button Add Amira Landmarks allows a user to add a set of markers based on locations in an Amira landmark file.

Figure 51: Panel for adding markers to an FEM model.

From top to bottom, the FemMarker editing panel contains

  • An Existing markers list, showing all the FEM’s frame markers (expressed by their path names with respect to the FEM). This list is connected to the selection manager and can be used to select one or more markers.

  • A name field that allows a name to be specified for the marker.

  • A Default marker properties panel, which allows the user to set properties for subsequent markers that are added.

  • An instruction box containing directions for the user.

  • A constrain to plane option.

  • An option panel, containing an Add Amira Landmarks button, described above, and a Done button which the user should click when finished.

13.6.2 Adding muscle bundles

FemMuscleModel is a subclass of FemModel3d that supports muscle activation. A FemMuscleModel may contain muscle bundles (type MuscleBundle), each of which is composed of fibres and elements. The fibres are two-point muscles connecting nodes or markers within the FEM model, with activation provided by forces acting directly on the fibre end points. The elements are a set of references to existing elements within the FEM model, each combined with an activation direction. Each element reference within the bundle provides muscle activation behavior by superimposing a transversely isotropic material behavior on top of the underlying element’s material behavior.

Activation of a MuscleBundle can be effected by either the fibres or the elements, with the latter generally providing a superior simulation result. By default, the fibres are inactive, and are used simply to provide a good visual indication of the activation directions within the model, and a way to automatically compute the referenced elements and their directions (as described below). To make the fibres active, set the bundle’s fibresActive property to true. Conversely, to make the elements inactive, set the bundle’s muscleMaterial property to InactiveMuscle.

To add a MuscleBundle to a FemMuscleModel, select the model and then choose "Add MuscleBundle ..." from the context menu. This will immediately add a MuscleBundle to the model, and then open a MuscleFibre editing panel (see Section 13.7.1) to allow the user to add fibres to the model. The panel also contains two extra fields at the top: bundle name, allowing a name to be specified for the bundle, and bundle renderProps, allowing its render properties to be adjusted. At present, the panel does not contain a Cancel option. To remove the MuscleBundle, either select and delete it, or choose "Undo add MuscleBundle" from the Edit menu.

13.7 Editing muscle bundles

Existing muscle bundles can be editing to add or remove fibres or element references.

13.7.1 Adding fibres

Fibres can be added to a MuscleBundle by selecting the bundle and then choosing "Edit fibres ..." from the context menu. This will open a MuscleFibre editing panel as shown in Figure 52.

The operation of this panel is essentially identical to the AxialSpring editing panel described in Section 13.4.5: fibres are added by successively selecting the points (which in this case must be FEM nodes or markers) which serve as the endpoints for the fibres in question.

Figure 52: Panel for adding fibres to a muscle bundle.

The only difference from the AxialSpring panel is that the spring type is assumed to be a Muscle and there is no option to change this.

13.7.2 Adding element references

Elements can be added to a MuscleBundle by selecting the bundle and then choosing "Edit elements ..." from the context menu. This will open a MuscleElement editing panel as shown in Figure 53.

The operation of this panel is quite simple: one selects the elements that one wishes to add, and then clicks on the Add button to add them to the bundle. Elements which are already contained in the bundle will be excluded. Viewer-based element selection is described in more detail below.

Figure 53: Panel for adding elements to a muscle bundle.

From top to bottom, the MuscleElement editing panel contains

  • A list of element references already associated with the bundle (expressed by the elements’ path names with respect to the FEM muscle model). To remove element references from the bundle, one may select them in this list and then choose "Delete" from the context menu. It should be noted that this deletes the references for the elements within the bundle, and not the elements themselves from the FEM model.

  • Fields modelElementSize and bundleElementSize which control the size of the element widgets which are rendered for both the FEM muscle model and the bundle, as described below.

  • An instruction box containing directions for the user.

  • An option panel, containing an Add button which adds selected elements to the bundle, and a Done button which the user should click when finished.

Element selection is often done by clicking on an element widget in the viewer. An element widget is a simplified solid rendering of an element’s shape, with a size that varies from 0 to 1, with 0 being invisible and 1 being the full size of the element. Element widgets can be rendered for all the elements in an FEM model, with a size controlled by the model’s elementWidgetSize property. In addition, separate widgets can be rendered for the all the elements referenced by a muscle bundle, with a size controlled by the bundle’s elementWidgetSize property. In order to be able to see and select both the referenced elements in a bundle, and the other elements in the FEM model, one should set elementWidgetSize for the bundle and the model to values greater than zero, with the former larger than the latter. Figure 54 shows a simple example where referenced elements in a bundle are rendered using a widget size of 0.6, while the model elements themselves are rendered using a widget size of 0.5.

Figure 54: Element widgets rendered for both an FEM model (pink) and a muscle bundle (cyan).

To facilitate element selection and visualization, the MuscleElement panel temporarily sets elementWidgetSize to 0.6 for the bundle and 0.5 for the FEM model. These values can then be adjusted as needed.

13.7.3 Automatically setting elements and directions

Since manually selecting elements and specifying their directions for a muscle bundle can be quite tedious, a number of methods exist to help do this automatically, using the easier-to-visualize information supplied by the muscle fibres. From the MuscleBundle context menu, one may select:

Compute element directions

Automatically computes directions for all referenced elements, using a Delaunay-based interpolation of the directions of the fibres which are closest to them.

Add elements neat fibres ...

Automatically adds to the set of referenced elements all elements whose centers are within a prescribed distance of one or more of the fibres.

Delete elements

Deletes all the element references for the bundle.

13.7.4 Removing fibres and element references

To remove specific fibres or element references, simply select them (using any of the selection mechanisms), and the choose "Delete" from the context menu.

13.8 Editing muscle exciters

A MuscleExciter is a component that allows muscle excitation signals to be distributed to a set of target ExcitationComponents. Excitation components include anything that can receive a muscle excitation, including point-to-point muscles, muscle bundles, and other muscle exciters. The purpose of a muscle exciter is to facilitate grouping so that one excitation signal can drive a number of underlying components. They can be optionally added to both MechModels and FemMuscleModels, where they are stored in a component list called exciters.

The GUI provides the ability to edit the targets associated with a given exciter. To do this, select the exciter in question, and then choose "Edit targets ..." in the context menu. This will open an ExcitationTarget panel, as shown in Figure 55.

To add a new excitation target, select the desired excitation component (using any of the selection mechanisms), and it will be added to the list of existing targets. Each target is also associated with a gain, by which the excitation signal is multiplied as it is passed on to the target. Gains can be edited using the numeric field in the list of targets. Finally, to remove a target, simply select it in the list of targets, and choose "remove targets" from the context menu.

Figure 55: Panel for editing the targets of a muscle exciter.

From top to bottom, the ExcitationTarget panel contains

  • An Existing targets list, showing all the current targets, allowing them to be selected for removal or their gains to be edited.

  • An instruction box containing directions for the user.

  • An option panel, containing an Add/Stop button which can be used to initiate or stop the adding of targets, and a Done button which the user should click when finished.

13.9 Editing root models

Some very limited graphical editing is available for RootModels. It is possible to add a MechModel to the RootModel, by selecting the RootModel and then choosing "Add MechModel ..." in the context menu. This brings up a MechModel editing panel as shown in Figure 56.

Figure 56: Panel for adding a MechModel to a RootModel.

The panel is quite simple: you edit the MechModel properties to the appropriate settings, click the Add button, and a new MechModel is added. However, this is of limited use, since normally only one MechModel is placed directly under the RootModel, as multiple MechModels cannot be advanced using the same integrator and must therefore be completely decoupled.