ArtiSynth Update Log

The class RenderableComponentBase has been refactored to export the standard rendering properties renderProps. This was done to make it easier to create custom renderable components by subclassing RenderableComponentBase.

However, it also means that existing subclasses of RenderableComponentBase should no longer export their own version of renderProps. If you have defined such a subclass, and it exports renderProps, such as through a static declaration like the followng,

you can either remove the declaration:

or remove the previous declaration before declaring your own:

A new section has been added to the Modeling Guide on creating components for custom rendering. Check out Section 4.4, “Custom Rendering”.

A new FEM component, FemCutPlane, as been added that allows an application to visualize internal stresses or strains through a cross section of an FEM model. For details, see the section “Cut planes” in the “Finite Element Models” chapter of the ArtiSynth Modeling Guide.

Materials defined in artisynth.core.materials for modeling line-based muscles and tendons have been updated or added, as described below.

An inertialDamping property has been added to both the MechModel and RigidBody classes. If not explicitly set in a rigid body, its value is inherited from the containing MechModel. If non-zero, inertial damping applies a spatial damping force to a rigid body that is equal to

(1)

where is the inertialDamping, is the body’s spatial inertia matrix, and is the body’s spatial velocity. This offers two advantages over translational/rotational damping:

1. 1.

   It is independent of the location of the body’s coordinate frame with respect to its center of mass;

2. 2.

   There is no need to adjust two different translational and rotational parameters or to consider their relative sizes, as these considerations are contained within the spatial inertia itself.

Inertial damping can be get/set with the MechModel or RigidBody methods

New functionality has been added to make it easier for users to select node sets within an FEM model. This can be done either in the GUI or in code, and is useful for specifying nodes that need to be attached to other components or otherwise handled specially within the model.

Control panels can now contain property widgets that control the same property across multiple host components. As described in Sections 5.1 (“Control Panels”) of the ArtiSynth Modeling Guide, these can be created with methods of the form

A new class PolygonIntersector has been added for intersecting 2D and 3D planar polygons. It is implemented using GPCJ (General Polygon Clipper for Java).

Command line options related to the layout have been modified. The options -noTimeline and timelineRight have been removed, and the following have been added:

The viewer property axisLengthRadiusRatio, used when rendering coordinate axes as solid arrows, has been replaced with axisRadiusRatio, with the value of the latter the inverse of the former.

In order to separate user-specific settings from the ArtiSynth installation, ArtiSynth now creates the configuration folder ArtiSynthConfig in the user’s home folder, and uses this to store various items such as preferences, model and script menus, the startup model, model and script history, and the external classpath.

The model menu, located under Models in the main menu bar, has been revised to include a number of new entries at the end:

The “Reload model” and “Load from class ...” entries have been relocated from the File menu, “Load recent” has replaced “Recent”, and the entry “Edit menu ...” opens a model menu editor that allows interactive editing of the upper portion of the menu.

For details on menu editing, see “Customizing the Model and Script Menus” in the User Interface Guide.

The XML files describing the model menu have also changed. The XML format has been simplified, and the default menu file has been moved from demoMenu.xml in the ArtiSynth installation folder to settings/modelMenu.xml in the user configuration folder.

The script menu, located under Scripts in the main menu bar and used to run Jython scripts, has been revised to include new entries and make it feel-compatible with the model menu:

“Run script ...” replaces “Load script” and opens a dialog that allows the user to select a script, while “Run recent” reruns recently run scripts.

The upper part of the script menu can be customized with an arrangement of entries invoking specific scripts. This menu can be customized in the same manner as the model menu by selecting “Edit menu ...” at the bottom. Script menu information is contained in the file settings/scriptMenu.xml in the user configuration folder. The default menu supplies an entry “Demo scripts” that expands to all scripts located in

  src/artisynth/demos/scripts

relative to the ArtiSynth installation folder.

The Settings menu has been revised to allow additional control over application properties related to the viewer, simulation control and GUI interaction. These are collected into the menu items “Viewers ...”, “Simulation ...”, “Interaction ...”, and “Mouse ...”.

With respect to the previous entries, “Background color” and “Selection color” are now controlled under “Viewers ...”; “Mouse preferences ...” is now “Mouse ...”; and “Enabled articulated transforms”, “Visual display rate”, “Real-time scaling”, and “Init draggers in world coords” are controlled by the properties articulatedTransforms, frameRate, realTimeScaling, and initDraggersInWorld located under “Interaction ...”.

See the “Settings” section in the User Interface Guide.

Many application properties, including those related to the viewer, simulation control, GUI interaction, window layout, and movie making can now be set permanently via the preferences editor, which can be opened via Settings > Preferences ....

See the “Preferences” section in the User Interface Guide.

The play controls have been extended to include a new stop-all button:

Located at the right with a square icon, this buttons stops simulation (in the same manner as the pause button), but also aborts any currently running Jython command or script.

A new static method has been added to ComponentUtils:

where comps is a list of model components. This can be used to “prune” components and their dependencies from existing models, with a behavior that should be identical to selecting the components in the GUI and then choosing Delete from the context menu.

The navigation panel visuals have been simplified so that composite component entries are now indicated with arrow icons (below, left), instead of folders and lines (below, right):

A startup model can now be set from within ArtiSynth to specify a model (with optional build() method arguments) to be loaded when the application first starts. To do this, select Settings > Startup model .... This capability replaces the need to specify such models using the command line option -model <modelName> (although this command line option is still supported).

See “Setting a startup model” in the User Interface Guide.

The external classpath, which contains class folders and JAR files for models and packages located outside of artisynth_core, can now be set from within ArtiSynth. To do this, select Settings > External classpath ..., which opens an external classpath editor. This capability replaces the need to edit the EXTCLASSPATH file by hand. The EXTCLASSPATH file has also been moved to the user configuration folder.

See “Setting the external classpath” in the User Interface Guide.

It is now possible to update the JAR files and native libraries from within ArtiSynth, instead of calling

  bin/updateArtisynthLibs

in the ArtiSynth installation folder. Choose Update libraries from the File menu.

• •

  The default folder for movie files is now ArtiSynthConfig/movies under the user’s home folder. This can also be customized via Settings > Preferences > Movies > movie folder.

• •

  A new Messages tab has been added to the movie panel, which displays the progress of move making commands along with any error messages.

• •

  Customized command settings for the encoder options FFMPEG, MENCODER, and AVCONV can now be stored permanently via Settings > Preferences > Movies and selecting Customize Method for the selected method. In addition, there is a new CUSTOM method which can be set to any command-line based movie making command available on the ArtiSynth host computer.

• •

  An explicit stop time can be set indicating when movie recording should stop.

See the updated section “Making Movies” in the User Interface Guide.

The following command line options have been modified or removed:

On systems where Java-browser integration is supported, the Help menu has been expanded to open browser windows to the modeling guide, user interface guide, MATLAB interface manual, and Java API.

Documentation for the Jython interface has been moved from the “Interfacing ArtiSynth to MATLAB and Jython” to the new section “Jython Interaction and Scripting” in the User Interface Guide, and the original manual has been renamed to “Interfacing ArtiSynth to MATLAB”.

The Pardiso solver has been updated to MKL 2021.1. Users updating from github should also run the command updateArtisynthLibs.

A number of new joints have been added to ArtiSynth, including:

• •

  SliderJoint: 1 DOF joint allowing translation along the axis.

• •

  CylindricalJoint: 2 DOF joint allowing translation and rotation along the axis.

• •

  SkewedUniversalJoint: 2 DOF roll-pitch joint in which the roll-pitch axes may be at a skewed angle relative to each other.

• •

  PlanarJoint: 3 DOF joint allowing translation and rotation in the - plane.

• •

  PlanarTranslationJoint: 2 DOF joint allowing translation in the - plane.

In addition, the following joints have been added to replace RevoluteJoint, RollPitchJoint and SphericalRpyJoint:

• •

  HingeJoint: Identical to RevoluteJoint, except that its coordinate is oriented counter-clockwise about the axis instead of clockwise.

• •

  UniversalJoint: Identical to RollPitchJoint, except that its roll-pitch coordinates are computed with respect to the rotation from frame C to D, instead of the rotation from frame D to C.

• •

  SkewedUniversalJoint: Identical to SphericalRpyJoint, except that its roll-pitch-yaw coordinates are computed with respect to the rotation from frame C to D, instead of the rotation from frame D to C.

Rendering of the new joints is also controlled differently, with the properties shaftLength, shaftRadius, and jointRadius used to control the size of the shaft and ball structures that are drawn for visualization.

The old joints RevoluteJoint, RollPitchJoint and SphericalRpyJoint are still supported for legacy purposes.

Full details on the new joints, along with examples, are given in the “Joint components” section of the Modeling Guide.

The documentation in the Modeling Guide describing how joints and connectors are created, used and implemented has been enhanced, with new sections describing constraints, coordinates, constraint forces, and rendering. In addition, the joint implementation has been refactored to make it easier to create custom joints, with full details given in the section “Custom Joints” in the chapter “Mechanical Models II”.

Some small changes have been made to the methods for joints and connectors:

• •

  In joints and connectors which are subclasses of BodyConnector, numUnilateralConstraints(), which returned the number of engaged unilateral constraints, has been renamed to numEnagedUnilateralConstraints(). Similarly, in subclasses of RigidBodyCoupling, numUnilaterals() has been renamed to numEnagagedUnilaterals().

• •

  In joints and connectors which are subclasses of BodyConnector, numUnilateralConstraints() now returns the total number of unilateral constraints, engaged or otherwise. Similarly, in subclasses of RigidBodyCoupling, maxUnilaterals() has been renamed to numUnilaterals().

• •

  In subclasses of BodyConnector, the spatial forces returned by the methods getBilateralForceInA() are now given in world coordinates. This was done to be consistent with Frame and RigidBody, whose forces (returned by getForce()) are also given in world coordinates.

• •

  In SphericalJoint, rendering of the joint as a ball is now controlled by setting its jointRadius property, together with the faceColor rendering property, instead of the previous method of using point rendering properties.

In addition to these changes, the penetration tolerance for unilateral constraints which are rotary in nature is now controlled by the rotaryLimitTol property, exported by both MechModel and the joint classes.

New methods are also provided for determining the constraint forces acting on a joint in different coordinate frames:

The class SkinMeshBody, which implements skinning, has been rewritten to allow skinned meshes which are connected to FEM models to behave properly under FEM rotation.

The SkinMeshBody API has also been refactored to allow greater flexibility in determining the connection weights between the mesh vertices and the underlying rigid bodies and FEM models. Markers and points can now be attached to a SkinMeshBody, even in the absence of a mesh, and this can be used as an simpler, more approximate way to implement muscle wrapping behavior.

Full details on the updated skinning mechanism and how to use it are given in the new chapter “Skinning” in the Modeling Guide.

Large probe displays have been rewritten to provide higher quality plotting, better interactive control, and the ability to export plots to svg, postscript, and image files.

Full details on these changes are given in the “Large displays” section of the User Interface Guide. To give a sense of the difference, the old display looked like this,

while the new display looks like this:

Frames and rigid bodies now have a new property called axisDrawStyle, that specifies how coordinate axes should be drawn. Its type is the enumerated type Frame.AxisDrawStyle, with the possible values OFF, LINE, and ARROW. Setting it to ARROW will cause coordinate axes to be rendered as solid arrow, as in this example:

The enumerated type FemModel.SurfaceRender, which controls the rendering of FEM surface meshes through an FEM model’s surfaceRendering property, has been extended to include MAPStress and MAPStrain, which render the surface as a color map using the maximum absolute values of the principal stress and strain components, respectively.

The TrackingController, which provides ArtiSynth’s inverse modeling capabilities, has been refactored. This includes both internal code reorganization and harmonization of the API.

It is now possible to export numeric probe data as either a .csv or .txt files. To do this, select the probe (in either the navigation panel or the timeline), and choose Export or Export as ... from the context menu.

The RootModel now contains the method resetInitialState(), which causes the initial state (i.e., the state at time 0) to be reset to the current state.

This can also be called interactively using the new reset state button located at the top left.

By default, when running with graphics enabled, the simulation tries to run in real time, with the simulation slowed down (if necessary) so it does not proceed faster then real time. This can now be disabled, using the Main method setRealTimeAdvancement(enable), so that the simulation runs as fast as possible. Note that real-time advancement is disabled by default when running in batch mode, which is why batch simulations sometimes run faster.

Real-time advancement can also be controlled with the new real-time enable button located at the top left.

The play controls in the main viewer have been extended to include the skip-back and skip-forward buttons that advance the model across waypoints.

A new set of utility methods has been added for creating embedded FEM models, and in particular voxelized embedding FEMs. The utilities were originally created by Antonio Sánchez and have now been added to the package core.femmodels, with the main class being EmbeddedFem. Two of its principal methods are:

When saving a model to a file using the Save model as ... menu item, users can now choose the following options:

Save waypoint data:

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

Core components only:

Save 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 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 that same ArtiSynth version, without needing access to any application-specific classes.

Waypoint data files (such as those written using the menu items Save waypoints as ... and Save waypoints) now contain annotations so that when they are later loaded into a model, checks are performed to help ensure that the state is consistent with that model.

It is now possible to construct, read, or write any of the mesh components (PolygonalMesh, PolylineMesh, PointMesh) by simply specifying a file and then have the file format inferred directly from the file suffix. The currently supported file formats, and their applicability to the different mesh types, are given in the table below:

The new constructors are

and the new read/write methods are:

For the latter methods, the argument zeroIndexed specifies zero-based vertex indexing (in the case of Alias Wavefront .obj files), while fmtStr is a C-style format string specifying the precision and style with which the vertex coordinates should be written. (In the former methods, zero-based indexing is false and vertices are written using full precision.)

Note: the method

   read (File file, String fmtStr)

which was specific to PolygonalMesh, has been removed. In its place, one can use

   read (File file, String fmtStr, boolean zeroIndexed)

with zeroIndexed set to false.

New commands have been added to the Matlab and Jython scripting interfaces for saving and loading models and waypoints,

where saveWayPoints specifies whether to save waypoint data and coreCompsOnly specifies whether to save only core components, as described above.

The ClassAliases package, which maps class names onto (shorter) aliases, and now also provides support for checking to see if a class is contained in artisynth_core, has been moved to maspack.util.

Field components have been added to allow the interpolation of both scalar and vector quantities over regular and FEM-based grids. Once created, a field can be “bound” to properties of various FEM materials, allowing the values of these properties to vary over the FEM domain. For example, the stiffness parameters of an FEM material may vary at different points within the volumetric mesh.

Full documentation on creating fields and binding them to materials is given in the new section “Fields”, in the “Finite Element Models” chapter of the the Modeling Guide.

FemModel3d now supports the ability to add “material bundles”, which allow supplemental materials to be added to the elements of an FEM model. A material bundle can be specified for either all elements or selected elements within the model.

Material bundles are implemented using the class MaterialBundle, and are analogous to MuscleBundle, except that they can be used for any type of FEM material and don’t specify excitation or excitation directions. It is possible to use a MaterialBundle to implement a muscle behavior, by specifying a MuscleMaterial whose excitation and restDir properties are set directly by the application (with the latter possibly attached to a Vector3d field).

Full documentation is given in the new section “Varying and augmenting materials”, in the “Finite Element Models” chapter of the the Modeling Guide.

FEM materials have been refactored in several ways:

• •

  The computeStress() and computeTangent() methods are now consolidated into a single method
  computeStressAndTangent() (in which the argument to return the tangent matrix is optional). The main reason for this is efficiency: tangent calculations often require some of the same calculations required for stress, and so computing these quantities in the same method avoids repeated computation.

• •

  The property viscoBehavior has been removed from FemMaterial. Instead, viscoelasticity is now effected by creating an instance of ViscoelasticMaterial, which takes both a base material and a viscoelastic behavior.

• •

  FEM materials can now maintain their own custom state. This is done via the interface HasMaterialState, which supplies the methods

  ⬇

    // material currently has state

    boolean hasState();

    // creates an object for storing the state

    MaterialStateObject createStateObject();

    // advances the state from time t0 to t1

    advanceState (MaterialStateObject state, double t0, double t1);

  For materials which have state, the system creates state instances which are stored at each element integration point and supplied as an additional argument to the computeStressAndTangent() method.

• •

  A new FEM material, ScaledFemMaterial, has been added which takes a base material and a scaling factor. The latter can then be attached to a scalar field to “scale” the effect of the material over an entire FEM. The old way of doing this, which involved a scaling factor in the integration data (class IntegrationData3d), has been removed.

MuscleBundle and MuscleElementDesc have been extended to allow shell as well as volumetric elements. This means that elements for these objects are now referenced by FemElement3dBase instead of FemElement3d.

With the addition of MaterialBundles, the existing means for added “extra” materials to an FEM, using
AuxiliaryMaterial, is now deprecated. AuxiliaryMaterials are still used “under the hood” to implement MuscleBundles, but it is expected that they will eventually be removed.

An undocumented feature known as AuxMaterialBundle currently exists within ArtiSynth, which allows
AuxiliaryMaterials to be added to an FEM model in a manner analogous to MaterialBundle. To accommodate MaterialBundle, the methods for adding, removing and accessing AuxMaterialBundles have been renamed as follows:

To quickly review: A MuscleBundle is the basic grouping of elements within an FemMuscleModel that share a single excitation value. Each element within a MuscleBundle is described by a single MuscleElementDesc. Removing the ExcitationComponent interface from MuscleElementDesc means that it is no longer be possible to control the excitation for one or more MuscleElementDescs separately from the excitation of the MuscleBundle. In other words, a MuscleBundle now represents the smallest possible grouping of FEM elements for which you can provide a single excitation.

Note that as before, one is still able to combine the excitations of several MuscleBundles using MuscleExciter components.

• •

  Excitation component has been simplified by removing the methods

  ⬇

    void addExcitationSource(ExcitationComponent ex)

    double getDefaultActivationWeight()
• •

  In the maspack.properties package, added setAllowedTypes() to PropertyDesc, to specify which subclasses of getValueClass() may be used for creating instances of a property within a CompositePropertyPanel.

• •

  In maspack.widgets, modified CompositePropertyPanel to use reflection to look for the method
  initializePropertyValues() in the declaration of a CompositeProperty, and use this to help initialize the subproperties of a CompositeProperty based on the value of a previous object with the same base class.

• •

  Added the methods getMaxAbsPrincipalStress() and getMaxAbsPrincipalStrain() to FemNode3d.

The method by which inertia is automatically computed for a rigid body based on the geometry of its mesh components (when its inertiaMethod is MASS or DENSITY) has been improved. Mesh components now have a property massDistribution which determines how the mesh’s inertia contribution is determined for a given mass. VOLUME, AREA, LENGTH, and POINT indicate, respectively, that the mass is distributed evenly over the mesh’s volume, area (faces), length (edges), or points. The default value is determined by the mesh type: VOLUME for a closed PolygonalMesh, AREA for an open PolygonalMesh, LENGTH for a PolylineMesh, and POINT for a PointMesh. Applications can specify an alternate value providing the mesh has the features to support it. Specifying DEFAULT will restore the default value.should be determined.

Full details are given in the section “Multiple meshes”, located under “Rigid bodies”, in the Modeling Guide.

It is now possible to save a model to a file in mid-simulation. Previously, it was assumed that the simulation “time” was 0. Now, however, you can simulate to some time , and then save the model (using File > Save model as ...). Loading the resulting file (using File > Load model ...) will restore the model to the simulation time .

If the model contains valid waypoints, the state of these waypoints is now also saved and restored. One caution is that if there are many waypoints and the model state is large, the resulting save file may also be quite large.

Forces and nodal stress/strain values are now saved as state within waypoints. This ensures that when a model is reset to a given waypoint at time , forces and stress/strains will be reset to the same values they had when the simulation originally reached .

The interface HasAuxState, used to indicate components which store state, has been renamed to HasNumericState and moved to artisynth.core.modelbase. It has also been simplified, with the methods skipAuxState() and getInitialState() removed and getAuxState(), setAuxState(), and advanceAuxState() renamed to getState(), setState() and advanceState().

Numerous internal changes have been made to the mechanism by which model state is saved and restored, both from waypoints and from model files, largely with the goal of ensuring exact repeatability of results when simulation resumes from a previously stored state.

A new set of menu commands have been added for saving and loading waypoints. These are accessed from the File menu and include:

Load wayPoints ...

Loads a set of waypoints from a specified file. As before, loading waypoints are superimposed on top of any existing waypoints.

Save wayPoints as ...

Saves the current set of waypoints to a specified file.

Save wayPoints

Saves the current set of waypoints to a previously specified file.

Previously, saving and loading waypoints had to be performed from the timeline. The save file now also includes information for all waypoints, with or without state, along with information identifying breakpoints.

As before, the waypoint data file is binary, since this typically requires half the file size and improves file I/O times by as much as tenfold.

Stress or strain computation can now be explicitly enabled for individual FEM nodes via the computeStress and computeStrain properties of FemNode3d. Otherwise, when needed for Stress or Strain rendering of an FEM mesh, nodal computation of stress/strain is now optimized to require computation of stress/strain values only for those nodes associated with the mesh.

A new property colorMapInterpolation has been added to CollisionManager and CollisionBehavior to control color interpolation when a penetration depth or contact pressure map is requested via the drawColorMap property. The default interpolation is HSV.

Bilateral and unilateral constraint impulses are now converted to forces when they are stored in the model. This means that it is no longer necessary to convert impulses to forces by dividing by the simulation time step. In particular:

• •

  The methods setBilateralImpulses(lam,h,idx) and setUnilateralImpulses(the,h,idx) (in MechSystem and Constrainer) have been changed to setBilateralForces(lam,s,idx) and setUnilateralForces(the,s,idx). Within each of these, the forces should be computed from s*lam and s*the.

• •

  The methods getBilateralImpulses(lam,idx) and getUnilateralImpulses(the,idx) have been changed to getBilateralForces(lam,idx) and getUnilateralForces(the,idx).

• •

  Related ’Impulse’ methods have been renamed to ’Force’.

• •

  CollisionResponse.getContactImpulses() has been changed to getContactForces().

• •

  The last argument for ContactForceBehavior.computeResponse() has been changed from region (giving the contact’s penetration region) to contactArea (which gives the estimated average area associated with the contact).

Muscle wrapping has now been officially added to ArtiSynth, with documentation supplied by a new chapter called “Muscle Wrapping” in the Modeling Guide. This documentation refers to a number of examples that have been added to artisynth.demos.tutorials.

It is now possible to add multiple meshes to a RigidBody, subsuming the functionality previously offered by RigidCompositeBody, which is now deprecated.

Each rigid body mesh is stored in a mesh component, RigidMeshComp, which is in turn contained in a subcomponent list named meshes. Meshes can be of any type, including PolygonalMesh, PolylineMesh and PointMesh. The method getSurfaceMesh() returns the first PolygonalMesh in the list, and getSurfaceMeshComp() returns its associated RigidMeshComp.

Meshes can be added to a RigidBody by creating a RigidMeshComp for them and then using methods such as

They can also be added directly, using the methods

which allocate and return a RigidMeshComp. The latter method also specifies hasMass, which indicates if the mesh should contribute to the body’s inertia, and isCollidable, which indicates if it should contribute to the body’s collision mesh.

RigidMeshComp also contains new properties, mass and density, that can directly control how the mesh contributes to the rigid body’s inertia when its inertiaMethod is MASS or DENSITY.

Full details are given in the new section “Multiple meshes”, located under “Rigid bodies”, in the Modeling Guide.

A new component, DistanceGridComp, has been added for containing, controlling, and visualizing the distances grids represented by DistanceGrid. Full documentation is given in the new section “Distance Grids and Components” in the Modeling Guide.

In particular, the distance grid for a rigid body has been moved into its own DistanceGridComp, which is a subcomponent of the body named "distanceGrid". One can obtain a reference to the grid component via the method

The wrapping code and the removal of RigidCompositeBody have engendered some API changes involving RigidBody.

1) The following methods concerning surface meshes have been renamed. The old methods have been retained but deprecated:

2) The field names for the enumerated type RigidBody.InertiaMethod have been capitalized, so that Density, Mass, and Explicit are now DENSITY, MASS, and EXPLICIT.

3) The rigid body’s distance grid has been moved into its own component, which is a DistanceGridComp that can be obtained via getDistanceGridComp(). The old RigidBody properties for controlling the distance grid have therefore been replaced by their equivalent properties in the grid component:

In addition, the old RigidBody property renderDistanceSurface has been replaced by the combination of the DistanceGridComp properties renderSurface and surfaceType, along with the new RigidBody property gridSurfaceRendering. The latter, if set true, will cause the grid’s isosurface to be rendered instead of the rigid body mesh components.

4) The component RigidMesh, which allowed wrapping around a rigid body with a general polygonal mesh, has been removed. Instead, wrapping is now supported for all rigid bodies. Wrapping is still computed using analytic methods for the special RigidBody subclasses RigidCylinder, RigidSphere, RigidEllipsoid, and RigidTorus.

5) In the class RigidMeshComp, the property physical has been renamed hasMass. The class no longer contains a distance grid, and so methods and properties relating to this have been removed. Also, the RigidBody method

takes the additional argument isCollidable indicating if the mesh should be treated as collidable.

A new method, addFrameMarkerWorld(frame,pos), has been added to MechModel. This creates a FrameMarker, attaches it to frame at the position pos in world coordinates, adds it to the MechModel, and returns it. It differs from the existing method addFrameMarker(frame,loc) in that the latter places the marker at the location loc in frame coordinates.

Shell elements have been added to FEM models. Full documentation on this will be provided soon; in the meantime, please note the following:

Shell elements are described by instances of ShellElement3d, and currently include ShellTriElement and ShellQuadElement. They may be added and removed from a FemModel3d using the following methods:

Both shell elements and the usual volumetric elements use the same nodes (FemNode3d), and can share nodes between elements.

Regular volumetric elements are still identified simply as “elements”, and are added and removed using the original methods addElement(e), removeElement(e), etc. In particular, numElements() still returns the number of volumetric elements. In order to query the total number of volumetric and shell elements, one should use the method

When used in connection with a shell element, an FEM node must supply an extra three degrees of freedom which specify a direction vector (known as a director) that is used for the shell computations. By default, this director vector is allocated and initialized automatically. It may be queried using the methods:

Both the artisynth_core and artisynth_models repositories have been moved to Github, where they can be accessed via the URLs

Users who were working from Subversion checkouts of these projects should replace them with fresh checkouts (’clones’) from Github. Eclipse users should remove their existing artisynth_core and artisynth_models projects from Eclipse, and all users should archive the existing project directories.

The new versions can then be cloned from Github, and libraries should be downloaded for artisynth_core. Eclipse users will also need to unpack the Eclipse project files from eclipseSettings.zip. A Unix-like command line sequence to perform these operations is as follows:

Eclipse users will also need to reimport these new projects into Eclispe. Full details on installing projects from Github are given in the updated installation guides: www.artisynth.org/doc/info/installation.

Note that users with Github accounts and SSH keys may wish to use the SSH URLs instead:

  git@github.com:artisynth/artisynth_core.git
  git@github.com:artisynth/artisynth_models.git

Write access to the old svn repositories for artisynth_core and artisynth_models has been frozen. Users posting changes should first clone the new Github repositories, and then push these changes to Github.

ArtiSynth has been updated to Java 8, and the compilation settings for both Makefiles and Eclipse projects (the latter contained in each project’s eclipseSettings.zip file) have been changed to request Java 8 compatibility.

This should mean that one should also be able to run and compile under Java 9, although we have noted some problems related to Java OpenGL (JOGL) when compiling on Java 9 and then running on Java 8. We therefore recommend that users stay with a Java 8 JDK for the moment. Java 8 is also compatible with current versions of MATLAB.

An isActive() method has been added to the Monitor and Controller interfaces, with a default implementation provided by ModelAgentBase (which also implements a setActive() method and exports active as a property).

This provides the ability to turn monitors and controllers off at run time: those for which isActive() returns false will not be called.

Existing implementations of Monitor or Controller which do not subclass MonitorBase or ControllerBase will need to be augmented to provide an isActive() method.

The URL for distributing ArtiSynth libraries and files has changed from artisynth.magic.ubc.ca/artisynth/files to www.artisynth.org/files. This should affect only applications making use of this URL.

However, it does require updating artisynth_core in order to be able to use the bin/updateArtisynthLibs command.

A new elliptic selection method has been introduced, thanks to work by Doga Tekin at ETH. To activate it, select the ellipse icon (second from the top of the selection toolbar). The viewer cursor will then change to include a surrounding ellipse (which defaults to a circle). Dragging while in elliptic selection mode will cause the cumulative selection of all objects visible within the ellipse, in a manner very much like a “paint” selection. If the SHIFT modifier key is pressed, selection is replaced with deselection. The current selection can also be cleared by hitting the ‘c’ key within the viewer. The dimensions of the selection ellipse can be adjusted by dragging with the CTRL and ALT modifier keys pressed, or hitting the ‘d’ key to cause the ellipse to be reset to its default (circular) dimensions.

Full details are given in the “Viewer Selection” section of the User Interface Guide.

http://www.artisynth.org/doc/html/uiguide/uiguide.html

The mechanism by which mouse bindings are set has been updated. Choosing Setting > Mouse Preferences ... from the main menu will bring up a dialog which allows you to adjust the mouse bindings and wheel zoom scale, and also displays the buttons and modifier keys required for different actions.

Names of the available bindings include ThreeButton, TwoButton, OneButton, Laptop, and Mac. ThreeButton, Laptop, and Mac correspond to the previous bindings default, laptop and mac. TwoButton, OneButton are identical to ThreeButton, except that the middle mouse button is emulated with the ALT key and (for the latter) the right mouse button is emulated using the META key (which is usually WINDOWS or (on Mac) COMMAND).

By default, ArtiSynth now detects the number of buttons on the mouse and sets the bindings to either ThreeButton, TwoButton or OneButton, as appropriate. It is still possible to override the mouse bindings using the -mousePrefs <bindings> command line argument.

Details are given in the “Alternate Mouse Control Settings” section of the User Interface Guide.

A new type of input probe, NumericControlProbe, has been added, that takes numeric data and passes it to an application-supplied function which can apply that data in any desired way. This is similar to using a Controller, except that the driving data can be viewed using the timeline displays or loaded from a file. NumericControlProbes are complimentary to NumericMonitorProbes, which were added last June.

For details, see the "Numeric control probes" section of the Modeling Guide.

The interface NumericMonitorProbe.DataFunction, which could be used to define the data generating function for NumericMonitorProbe, has been lifted to DataFunction and is also used to define the data application function for NumericControlProbe.

The following command line options have been added to control the MovieMaker:

  -movieFrameRate <rate> # movie frame rate (Hz)
  -movieMethod <method>  # movie making method

The movie method should be currently be one of internal, mencoder, mencoder_osx, ffmpeg, animated_gif, or avconv.

The class SignedDistanceGrid has been replaced by DistanceGrid, which can be either signed or unsigned. A number of new features have been added to distance grids, including:

• •

  The ability to explicitly specify the center and orientation of the grid with respect to its local coordinate system;

• •

  Writing and scanning the grid to and from a file;

• •

  Grid interpolation based on either linear or quadratic interpolation;

• •

  The ability to either generate the grid from mesh data, or to specify its values explicitly;

• •

  CSG operations based on signed distance grids;

It is often useful to align the local coordinate system for a mesh with its center, and sometimes also with its oriented bounding box (OBB).

To this end, we have added a number of methods to MeshBase:

The translate and transform methods reposition the vertex positions so as to achieve the required change in local coordinates. Note that this is independent of the additional mesh-to-world transform, controlled by getMeshToWorld() and setMeshToWorld(), that maps from local to world coordinates.

For PolygonalMesh, the following additional method is available:

The OpenGL rendering package has been updated to JOGL 2.3.2. Since the GL rendering implementation is hidden from the user, this should not affect application source code unless you are using GL directly for some reason. In that case, you will need to replace

with

However, the underlying JOGL libraries have changed, so after you have updated artisynth_core, you will need to run bin/updateArtisynthLibs (or run artisynth with the -updateLibs option) to obtain the new libraries.

Important: if you compile and/or run ArtiSynth from the command line, you will also need to remove from the folder $ARTISYNTH_HOME/lib any existing .jar files beginning with jogl2* or matlabcontrol*. Otherwise, these may conflict with the new libraries. Eclipse users may also wish to do this to remove clutter.

Eclipse users will need to change the JOGL libraries in their build path. Select the project for artisynth_core, and then under Properties... go to Java Build Path > Libraries, and replace

with

Also, make sure that these libraries are exported. Switch to the Order and Export tab and make sure that the export boxes are checked. The last library is used for implementing the MATLAB interface.

This change should allow ArtiSynth to run on versions of MATLAB from 2016 onward (but will prevent it from running on earlier versions).

The viewer grid now provides numeric axis labels, which can be enabled by hitting the ’l’ key in the viewer. Label properties such as size and color and which axes are labeled can be controlled by right clicking in the viewer and choosing Set viewer grid properties.

More details can be found in the "Axis Labeling" section of the User Interface Guide.

A new type of output probe, NumericMonitorProbe, has been added, which generates data through an application-supplied function. This is similar to using a Monitor, with the added advantage that the generated numeric data can be viewed using the timeline displays or saved to a file.

For details, see the "Numeric monitor probes" section of the Modeling Guide

ArtiSynth components that support signed distance grids, such as RigidBody, now support the ability to render the zero surface associated with the grid. This can controlled through the property renderDistanceSurface. When enabled, this will cause an approximation of the grid’s zero surface to be displayed instead of primary surface mesh. The purpose of this is to allow one to visualize how coarsely the distance grid approximates the mesh on which it is based.

The SurfaceMeshIntersector class in maspack.collision has been significantly upgraded for improved robustness and now supports the ability to perform constructive solid geometry (CSG) operations between two triangular meshes. The CSG methods include:

which return the intersection, union, and differences (mesh0-mesh1) and (mesh1-mesh0) with respect to mesh0 and mesh1. If the resulting CSG volume is null, then the returned mesh will be empty and its isEmpty() method will return true.

The CSG capabilities rely partly on the following enhanced version of findContoursAndRegions():

Like findContoursAndRegions (cinfo, mesh0, mesh1), this returns true if mesh0 and mesh1 intersect and places the resulting contact information in cinfo. However, the additional arguments regions0 and regions1, which are instances of SurfaceMeshIntersector.RegionType, can be used to specify how the penetration regions for each mesh should be computed:

Some effort has been put into helping ensure that the CSG methods are robust, work well in the presence of degenerate contacts (e.g., edge-edge, vertex-edge, and vertex-vertex), and return meshes that are both closed and manifold. However, it is important to remember that polygonal CSG operations are inherently ill-conditioned and problematic situations are still possible. For example, degenerate contacts are assumed to be within machine precision - essentially, vertices and edges that are within this tolerance are “snapped together”. However, near-degenerate situations which are just outside machine precision may result in ill-conditioned CSG meshes. Also, it is not always possible to ensure that the meshes are manifold in the case of intersections involving non-closed meshes.

Some changes have been made to the ContactInfo structure which returns contact information. This includes the following method name changes:

In addition, the new method getRegionsType(meshNum) can be used to query the type of regions associated with a particular mesh.

Because the penetration regions computed for a mesh may now be either inside or outside the opposite mesh, the following methods in PenetrationRegion have been renamed:

The ArtiSynth collision handling mechanism has now been extended to work using signed distance fields, in situations where at least one of the collidable bodies has a fixed mesh and maintains and exports a signed distance grid (via the CollidableBody methods hasDistanceGrid() and getDistanceGrid()). Although more approximate than the methods based on intersecting triangles and contours, signed distance methods can be significantly faster. Signed distance collisions can be activated by setting the collideType property in either the collision manager or a specific collision behavior to ColliderType.SIGNED_DISTANCE.

Updated information on signed distance collisions and the configuration and rendering of signed distance grids is given in the sections “Collision Implementation and Rendering” and “Configuring and rendering signed distance grids” of the ArtiSynth Modeling Guide.

Certain compatibility issues between Java Swing and Java OpenGL (JOGL) have been fixed by switching the default JOGL rendering widget from GLCanvas to GLJPanel. This fixes problems including: jumps and widget blanking when dragging the viewer between screens in a dual-monitor setup, the inability of the viewer to reposition itself correctly in MacOS Sierra, and widget blanking under some system configurations when using tiling widget managers.

GLJPanel works by doing all graphics rendering to an off-screen buffer and then copying the resulting pixels into the Swing widget. This introduces a slight overhead but completely isolates Swing from JOGL. In order to fix a known bug, it was also necessary to create our own implementation of GLJPanel in maspack.render.GL.jogl.

GLJPanel is now the default rendering widget. However, one can explicitly ask for either GLCanvas or GLJPanel by starting ArtiSynth with the -useGLJPanel or -useGLCanvas command line options.

A cleanup has been done in artisynth.core.femmodels.FemFactory. This includes some changes to method signatures:

createTorus() methods:

Have been modified so that the nr argument now gives the number of element layers along the inner thickness, instead of the number of node layers (since the latter definition was incompatible with quadratic elements).

createTube() methods:

Have been modified so that the nl and nr arguments now give, respectively, the number of elements along the length and the number of element layers along the thickness, instead of the number of node and node layers (since the latter definition was incompatible with quadratic elements).

createExtrusion() methods:

Have been modified so that all now take an additional argument zOffset which optionally offsets the first element layer from the surface. createTetExtrusion() and createQuadtetExtrusion() have also been restricted to triangular meshes, since it is not otherwise possible to ensure that the resulting FEM elements are conforming.

Fabien Péan at ETH has provided a patch in which some of the more commonly used Vector methods now return self-references. This allows chaining of computational statements into more compact forms such as

The ArtiSynth collision manager, which is used by MechModel to manage collisions between collidable bodies, has been rewritten to provide greater control over collision behavior, collision rendering, and the observation of collision responses.

The principal change is that CollisionBehavior objects now contains all information related to collision control, including not just the friction and whether collisions are enabled, but also the parameters used to fine tune the behavior, compliance (if desired), rendering of quantities such as contact normals and points, etc. Collision behavior objects are now stored as subcomponents of the collision manager as proper ArtiSynth components, allowing users to select them and edit their properties. Most of the properties exported by CollisionBehavior are also exported by the collision manager, from which they are inherited by behaviors which have not set them explicitly. Since behaviors are now proper components, they can also be selected and edited using the GUI navigation panel.

Full details are given in the “Collision Handling” section of the ArtiSynth Modeling Guide and, for the GUI aspects, the ArtiSynth User Interface Guide.

By separating behavior and response from the internal collision handling, the collision manager no longer needs to maintain collision handlers for all possible collision possibilities. Instead, handlers are created on demand when a collision is actually observed, and the collision manager is also free to employ bounding volume hierarchies to reduce the number of collision checks (although this has not yet been implemented).

Previously, to make detailed changes to collision behavior, one needed to either specify global properties in the collision manager, or modify properties of the CollisionHandler object that maintains the collision constraints for a specific pair of collidables.

While global behavior properties can still be set in the collision manager, behavior for specific collidables can now be managed by setting the CollisionBehavior components appropriate for the collidables in question. For example, to request the drawing of intersection contours between collidables col0 and col1, one previously would have used a code fragment like this:

Now, one would instead do something like this:

One can also still use the existing setCollisionBehavior methods, which specify whether a collision is enabled, as well as, optionally, its friction. These methods now create a default collision behavior component internally, and return it, after which it can be used to set other collision properties:

One can also retrieve an existing behavior and set its properties:

Because behaviors are now proper components, it is not permissible to add them to the collision manager twice. Specifically, the following will produce an error:

   CollisionBehavior behav = new CollisionBehavior();
   behav.setDrawIntersectionContours (true);
   mesh.setCollisionBehavior (col0, col1, behav);
   mesh.setCollisionBehavior (col2, col3, behav); // ERROR

However, a new behavior can be created from an existing one:

   CollisionBehavior behav = new CollisionBehavior();
   behav.setDrawIntersectionContours (true);
   mesh.setCollisionBehavior (col0, col1, behav);
   behav = new CollisionBehavior(behav);
   mesh.setCollisionBehavior (col2, col3, behav); // OK

Collision behaviors now contain most of the properties that used to be contained exclusively in the collision manager. Most of these are still retained in the collision manager, from which they will be inherited if not explicitly set in the behavior. A behavior can also set its own render properties, which will then be used instead of the collision manager render properties.

Another change is that information about the results of a collision are now collected by CollisionResponse components, which are created the application as needed and also stored as subcomponents of the collision manager. This removes the need for an application to query internal CollisionHandler objects to determine things like contact impulses, mesh interpenetration regions, etc.

For example, to obtain the current contact impulses between two FEM models, one would previously use the following code fragment (perhaps within a monitor apply() method):

This would now be replaced with an earlier call to set up a collision response, perhaps in a build() method,

followed by the following runtime code:

Note also that when setting up a collision response, the second collidable can be a group specification, allowing the collection of information between a specific collidable and an entire group of collidables. For example,

would create a response component to query collision responses between femA and all rigid bodies.

If desired, applications can also instantiate responses themselves and add them to the collision manager:

However, as with behaviors, the same response cannot be added to an application twice:

The type of collider used for collisions can now be specified directly in the collision manager through the colliderType property, whose value has the type CollisionManager.ColliderType. TRI_INTERSECTION is the current default, while AJL_CONTOUR specifies AJL collisions. AJL collisions can still be enabled by default through the -useAjlCollisions command line argument.

Some new properties have been added to allow the rendering of penetration depth when the collider type is set to AJL_CONTOUR. For details, see the new demo demos.tutorial.PenetrationRender and the associated documentation in the “Example: Rendering penetration depth” section of the ArtiSynth Modeling Guide.

This example makes use of the new INACTIVE setting for the method property in CollisionBehavior, which disables the generation of collision constraints and hence turns off the collision response.

Another change is that the special collidable objects Collidable.Deformable, Collidable.Rigid (formerly Collidable.RigidBodies), and Collidable.Self, used to denote all deformable bodies, all rigid bodies, and self collision, respectively, have been made instances of a special subclass Collidable.Group and extended to include Collidable.AllBodies (all rigid and deformable bodies) and Collidable.All (all bodies plus self-collision).

When calling one of the setCollisionBehavior or setCollisionResponse methods, the second argument can be an instance of Collidable.Group, allowing behaviors (or responses) to be established between a specific collidable and all members of a group. So for example,

would set the specified collision behavior between femA and all bodies.

• •

  The collidable group Collidable.RigidBodies has been renamed to Collidable.Rigid.

• •

  Some collision manager properties have had their names changes, as described in the following table. These properties are also now exported by CollisionBehavior components:

  Old name	New name
  collisionPointTol	rigidPointTol
  collisionRegionTol	rigidRegionTol
  collisionCompliance	compliance
  collisionDamping	damping

• •

  The pentrationTol property has been removed from the collision manager but remains in MechModel (where it was before). To set penetration tolerance, one should now do

  ⬇

     mech.setPenetrationTol (0.001);

  instead of

  ⬇

     CollisionManager cm = mech.getCollisionManager();

     cm.setPenetrationTol (0.001);

  Specifying a negative tolerance will cause the MechModel to compute a default value instead.

• •

  To draw contact normals, one now needs to set the drawContactNormals property to true in either the collision manager or collision behavior(s). The length of the drawn normals will be obtained, as before, from the contactNormalLen property in the collision manage (which will be set to an estimated default value if not set explicitly).

• •

  The variable doBodyFaceContact, previously located in CollisionHandler, has been replaced with the bodyFaceContact property in both the collision manager and CollisionBehavior.

• •

  The collider type used for collisions is now controlled by the collision manager property colliderType, whose value is an instance of CollisionManager.ColliderType. Current available types are TRI_INTERSECTION (the default), and AJL_CONTOUR. Either may be enabled with a code fragment like this:

  ⬇

     CollisionManager cm = mech.getCollisionManager();

     cm.setColliderType (ColliderType.AJL_CONTOUR);

It is now possible to set, or disable/enable, the selection color used in the viewer. See the commands Selection color and Disable selection highlighting in the Settings menu.

This is a follow-on to the update of Aug 10. The functionality of SurfaceMeshContourIxer to obtain intersection contours has been merged into SurfaceMeshCollider.

Instead of doing

one now does

SurfaceMeshContourIxer will remain in the distribution until we are confident this works properly. If for some reason SurfaceMeshCollider gives an incorrect result, one can simply replace SurfaceMeshCollider with SurfaceMeshContourIxer, which has been given a getContours(mesh0,mesh1) method so the new code structure does not need to be changed.

The package maspack.collision, which is used to compute collisions between polyhedral meshes, is currently being refactored to improve its efficiency and reliability. Many of these changes will be invisible to most users. However, the following classes in maspack.collision have been renamed:

In addition, the collider SurfaceMeshCollider and the intersection contour generator SurfaceMeshContourIxer now both use the same IntersectionContour to describe contours. The merge has resulted in the following method name changes within IntersectionContour:

Note also that SurfaceMeshContourIxer is now deprecated. The plan is to replace its functionality with SurfaceMeshCollider.

A major change has been made to the postprocessing done by the AJL collision scheme (which uses SurfaceMeshCollider). AJL collisions work by determining the intersection contours between two meshes. Previously, these contours were then processed to determine which interpenetrating vertices, faces, and edges they contained, and which contours were nested inside which. However, this scheme was flawed: for closed meshes, there are no “inner” or “outer” contours; instead, there are only connected penetration regions on each mesh, which are bounded by one or more contours. Moreover, these regions are not necessarily symmetric: the regions on one mesh may be different in both number and contour composition. To properly describe this, contours (represented by the class IntersectionContour) no longer contain lists of interior features. Instead, the ContactInfo class (which stores the contact information produced by the collider method getContacts()) now contains a list of penetration regions for each mesh. Each region is described by the class PenetrationRegion, which stores the bounding contours along with the vertices, faces and edges which are completely or partially inside that region. These attributes may be queried using the following methods:

Note in particular the method getArea(), which returns the exact area of the the penetration region. This quantity is computed on demand and then cached.

Note that the above only pertains to collisons preformed with AJL collisions. AJL collisions are not enabled in ArtiSynth by default (although we are working toward changing this). For the moment, AJL collisions are enabled using either the command line option -useAjlCollisions or by calling SurfaceMeshCollider.setAjlCollision(enable).

Changes have been made to the class ContactInfo, which stores the contact information produced by the collider method getContacts(). All of the fields have been made private to maspack.collision and the following accessors should instead be used to obtain its information:

A ContactPlane, as returned by getContactPlanes(), is a planar approximation to two matching penetration regions on each mesh, with the convex hull of the contours projected onto the plane. It is typically used to generate contact constraints between rigid bodies.

When contact is determined using AJL collision detection, the following information is also available:

Finally, when not using AJL collisions, it is possible to retreive the individual triangle-triangle intersections between the meshes:

Note, however, that this functionality may be removed in the future.

A new syntax has been added for passing command line arguments to either the build() method for RootModels that are loaded with the -model option, or to a Jython script that is invoked with the -script option. The syntax involves placing the desired arguments immediately after the model or script specification, enclosed inside square brackets [ ].

For example, for a model,

artisynth -model artisynth.models.stuff.MyModel [ -foo bar ]

will pass the strings "-foo" and "bar" to the build() method of MyModel (via the args argument). This functionality replaces the previous use of the -M argument (in which all arguments following -M were passed to the build() method).

For a script,

artisynth -script myscript.py [ -xxx 123 -off ]

will pass the strings "-xxx", "123" and "-off" to the script myscript.py, which can then retrieve them from sys.argv:

(thanks to Antonio for this synopsis).

The class FileGrabber, in maspack.fileutils, has been renamed to FileManager, and additional functionality has been added to allow it to also upload files onto a server using a variety of “put” methods:

Instead of using the legacy OpenGL 2 API, ArtiSynth components now draw themselves using a rendering API that is independent of the underlying implementation. The main purpose of this is to (a) allow ArtiSynth to take advantage of more advanced versions of OpenGL, and (b) ultimately allow models to be rendered with other graphical APIs such as Renderman.

Previously, renderable components drew themselves by overriding their render() method with code similar to the following:

Under the new interface, GLRenderer has been replaced by Renderer, and all draw operations now proceed through the renderer; GL is no longer used or needed. The renderer’s functionality has been significantly enhanced to accomodate this. For example, the code sample above could be now be written as

Complete documentation for the new rendering interface, with detailed examples, is given in the “Rendering” chapter of the Maspack Reference Manual. The new Renderer interface itself is described in the “Renderer Interface” section.

This update entails changes to the ArtiSynth API. For application code that does not explicitly implement component render() methods or manipulate the viewer, those changes should be limited to API changes involving RenderProps, described below. For application code those does implement render() methods or manipulate the viewer, further changes as described under API changes involving the renderer or API changes involving the viewer will likely be necessary.

The interface for setting normals, colors, and texture coordinates in meshes has been redesigned. Full documentation can be found in Section 3.5 (“Meshes”) of the ArtiSynth Modeling Guide. These changes have been made partly in preparation for switching to the upcoming new rendering interface. Some of the main changes are:

• •

  Normal, color and texture information is now stored in the mesh base class MeshBase. Colors are no longer stored in mesh vertices.

• •

  Index information can also be specified, which maps normals, colors and texture coordinates onto the vertices of individual features such as faces or lines.

• •

  Normal information for PolygonalMesh can be created automatically.

• •

  Vertex or feature coloring modes can be enabled, under which a mesh will automatically maintain colors for each vertex or feature.

For normals, some of the main methods are:

Similar methods exist for colors and texture coordinates. If automatic normal creation is available, the method

returns true and normals are created automatically whenever getNormals() is called. Vertex and feature coloring can be enabled and queried using

Note: textures may not behave correctly at the moment, as other aspects of the texture interface are being redesigned. When the new render interface is installed, texture properties will move from RenderProps into MeshBase.

In order to provide greater API uniformity, the following methods for querying the number of vertices, faces, and lines in various mesh subclasses have been renamed:

The geometry transform mechanism has been completely rewritten, to make it both more robust and more general. It is now possible to transform components, or collections of components, with a GeometryTransformer object, special instances of which can be used to apply a transformation based on a nonlinear deformation field.

Full details, and a demonstration example, as given in the section “Transforming geometry” of the ArtiSynth Modeling Guide.

The mechanism to add application-defined menu items which can be invoked from the ArtiSynth menu bar has been changed and generalized.

First, the menu name under which these items appear has been changed from Model to Application.

Second, application-defined menu items can now be provided not only by the RootModel, but by any top-level component of the RootModel (e.g., models, controllers, probes, etc.). Formerly, the RootModel could provide menu items by overriding the method makeMenuItems(). Now, instead, menu items can be provided by either the RootModel or any top-level component that implements the interface HasMenuItems, which declares the method

The total of all menu items supplied is used to populate the pull-down Application menu in the ArtiSynth menu bar.

The Application menu will only appear if getMenuItems() returns true for one or more of these components.

For more details, see the section “Application-Defined Menu Items”, in the ArtiSynth Modeling Guide.

The Pardiso library has been updated to include the ability to dynamically set the number of threads used by the solver. From code, one can do this by calling

which will then set the number of threads to num upon creation of the next instance of PardisoSolver.

Note: setting the number of threads globally affects all solver instances within the current process. There is no current way to specify the thread number for individual solver instances. Also, the specified thread number is only a hint; fewer threads may be employed, depending on the machine resources available.

The named convention for the Pardiso library has also been changed. The current library is now PardisoJNI.11.1.2.1, where the first three numbers correspond to the version numbers of the underlying MKL library. The new library should download automatically from the ArtiSynth web server.

The Tetgen library has been updated to Tetgen 1.5.1 (May 2014), with the new library named TetgenJNI.1.5.1.0. The first three numbers correspond to the version numbers of the underlying Tetgen library. The new library should download automatically from the ArtiSynth web server.

Support has been added for interactively creating and rebuilding FEM surface meshes from the right-click context menu.

• •

  Adding new surface meshes. If an FEM model is selected, then the context menu command Add new surface mesh will create a new surface mesh and add it to the set of mesh components contained in the list meshes. If a clipping plane is active, the mesh will include only those elements which are not obscured by the clipping plane.

• •

  Adding new surface meshes from selected elements. If one or more elements of an FEM are selected, then the context menu command Add new surface mesh for selected elements will create a new surface mesh encompassing only the selected elements and add it to the set of mesh components contained in the list meshes.

• •

  Rebuilding an existing surface mesh. If an FEM mesh component is selected, and the underlying mesh type is a PolygonalMesh, then the context menu command Rebuild as surface mesh will rebuild the mesh as a surface mesh for the FEM. If a clipping plane is active, the mesh will include only those elements which are not obscured by the clipping plane.

ControlPanels have been updated to take advantage of the updateReferences() method in ModelComponent to update themselves appropriately if any components associated with their widgets are deleted.

The LaTeX javaclass and javamethod commands (defined in doc/texinputs/artisynthDoc.tex to generate links to Javadoc class and method documentation from within ArtiSynth docu) have been changed as follows:

• •

  javamethodx and javaclassx, which prepended package information with a string defined by the command javabase, are no longer supported. While this means that javaclass and javamethod must now fully specify their class packages, this should result in documentation that is clearer and easier to maintain.

• •

  Antonio has added a new command, javamethodAlt, that allows one to specify arbitrary visual text for a given method link.

• •

  When compiling HTML documentation files, the postprocessing step will now produce visible WARNING messages for class and method links that cannot be located.

For more details, see the Javadoc References section in Writing Documentation for ArtiSynth.

ArtiSynth 3.2 has been released and is available on the website.

Some classes and methods were renamed as described in the following charts. The reasons for this were twofold: first, since joints can now be applied to deformable as well as rigid bodies, the notion of RigidBodyConnector not longer made sense. Second, there are a number of subclasses of MeshComponent that are used to encapsulate various mesh objects defined in maspack.geometry (such as PointMesh and PolygonalMesh). However, these container classes had names like FixedMesh and FemMesh, leading to confusion over whether they were actual mesh classes, or components that simply contained meshes.

FemMarker.setElement(e) has been renamed to FemMarker.setFromElement(e)

The long-standing ability to attach points to certain types of ArtiSynth components is now complemented by the ability to attach frames to components, including other frames and FEM models. See Sections 4.5.3 and 7.6 in the Modeling Guide, and the examples artisynth.demos.tutorial.FrameBodyAttachment and artisynth.demos.tutorial.FrameFemAttachment.

The ability to add frames to FEM models allows us to connect joints directly to these models. See Section 7.6.2 in the Modeling Guide, and the example artisynth.demos.tutorial.JointedFemBeams.

Point attachments can now be made for arbitrary collections of FEM nodes. See Sections 7.4.3 through 7.4.6 in the Modeling Guide, and the example artisynth.demos.tutorial.PointFemAttachment. The same ability holds for FEM markers; see Section 7.5.

Support has been added for wrapping surfaces. This is done by extending MultiPointSpring to make some segments wrappable, allowing them to wrap around any Wrappable obstacle that is added to the spring. Documentation is being prepared. In the meantime, see the example artisynth.demos.tutorial.CylinderWrapping.

The ArtiSynth MATLAB interface has been overhauled and significant functionality has been added to enable ArtiSynth to be run and scripted within MATLAB. The Jython interface has also been revised so that the scripting commands are essentially the same in both interfaces. A new document, “Interfacing ArtiSynth to MATLAB and Jython”, has been prepared that describes both interfaces in detail.

The Pardiso library has been recompiled with MKL 11.1.2. This is the most recent version of MKL for which hybrid solves still work properly in ArtiSynth. The updated Pardiso library is named PardisoJNI.1.1. You may want to run updateArtisynthLibs in $ARTISYNTH_HOME/bin to make sure that the library is properly updated.

The domain name of the ArtiSynth file server (used by some applications to access files using maspack.fileutil.FileManager) has been changed from

www.magic.ubc.ca

to

artisynth.magic.ubc.ca

Where necessary, application code has been updated to reflect this change.

All RootModel instances in the package artisynth.demos now create their models using the build() method. Code that depends on these packages has been updated accordingly.

To improve code modularity almost all methods and attributes in Main have now been made non-static. This means that they must now be called using a Main instance, as in:

The current Main instance can still be obtained using Main.getMain(), so that

will work if necessary.

In some cases, the required functionality has been moved directly into the RootModel, and whenever possible this interface should be used instead:

Also, these methods should ideally not be called from within the RootModel constructor but from within its build() method instead.

Please use Main.getMain() sparingly. The use of the static Main instance is being reconsidered, since it prevents the possibility of creating multiple ArtiSynth instances within the same executing program (one place where it might be useful to do this is within MATLAB).

The old collision handling code has been removed, along with the command line option -collisionHandler GENERIC.

The ability to control collisions and self-collisions among objects has been enhanced.

The Collidable interface now contains a method isCollidable(). If this method returns false, then collisions will be disabled for that collidable, regardless of which default and explicit collisions behaviors have been specified. For most currently implemented bodies, the value returned by isCollidable() is associated with a collidable property, so setting that property to false will disable collisions for that body.

Collidable has also been modified to properly support self-collisions. If a collidable A has any descendant components which are also collidable, then these descendents are called sub-collidables of A. Self-collision within A can then be effected by enabling collisions between all pairs of its sub-collidables for which its allowSelfCollision() method returns true.

As a particular example, FemModel3d is a collidable, while the mesh components located in its meshes sublist are sub-collidables. If self-collision is enabled for an FEM model, collisions will be enabled between any of these mesh components which (a) contain a polygonal mesh and (b) are marked as collidable. The surface mesh is excluded, since FemModel3d.allowSelfIntersection() returns false for the surface mesh.

More details are given in the Collision Handling section (currently 5.6) of the ArtiSynth Modeling Guide.

FemMeshVertex, which was a special subclass of Vertex3d used for creating FEM meshes, has been removed. Its purpose had been to store the FemNode3d (if any) associated with a mesh vertex. This information is now maintained elsewhere, and the node (if any) associated with a vertex can now be determined using either getSurfaceNode(vertex) (in FemModel3d), or getNodeForVertex(vertex) (in FemMesh).

One change required by this is that FemFactory.createHexWedgeExtrusion() now takes an additional fifth argument, which is either the FEM associated with the supplied surface mesh, or null if there is no FEM associated with the mesh.

Also, in FemModel3d: getSurfaceMeshVertex() has been replaced by getSurfaceVertex().

The methods scanMesh(fileName) and scanMesh(tokenizer) in FemModel3d, which read FEM meshes from a special file in which faces are identified by node numbers, have been changed so that they now create and return a FemMesh object instead of a PolygonalMesh. The PolygonalMesh itself can be obtained using getMesh() on the returned FemMesh.

Meshes can still be scanned and added to an FEM model using code snippets of the form

In addition, the file format has been changed from one in which faces are indicated simply by the numbers of the underlying FEM nodes, as in

to one where faces are specified by vertex indices and vertices are in turn specified by their associated nodes and weights, as in:

This allows the handling of situations where each vertex does not correspond exactly to one FEM node, such as fine surface and embedded meshes. For more details, see the API documentation for scanMesh() and writeMesh() in FemMesh.

The old face-node format is maintained for backward compatibility.

Note: more changes are likely in the way that FEM meshes are created and maintained.

The following methods in MechModel:

have all been replaced with the single method

where PointAttachable is an interface indicating any component that is capable of creating it’s own point attachments using the method:

Implementing components include RigidBody, Particle, FemElement3d, and FemModel3d.

For FemModel3d, the previous attachPoint() method also allowed the specification of a reduction tolerance, which if non-zero could be used to reduce the number of nodes the point was attached to. This can still be achieved by explicitly creating and adding the attachment like this:

The PointAttachment interface makes it possible to decouple MechModel from other packages that implement PointAttachable components.

Recent changes have moved the surface meshes of some body components into separate components located beneath the body in question. For example, the surface mesh for a FemModel3d is now stored as a FemMesh component located in meshes/surface beneath the FEM model. This allows for greater flexibility in controlling the visibility and rendering of mesh components, but it also means that when you graphicaly select on a body’s surface mesh, you select the component containing the mesh rather than the body itself.

To make it easy to navigate to the body in question, you can now use the ESC key to quickly select the parent of the last selected component. For surface meshes, two quick presses of ESC will get you from the surface mesh to the body itself (and the path name of the revised selection will appear in the component selection box at the bottom of the main ArtiSynth frame). While it was already possible to do parent selection using the "UP" arrow in the component selection box, using the ESC key is faster.

A new static method in FemMesh,

allows the creation of an FEM surface mesh which encloses a specified collection of elements. This should make it easier to create sub-surfaces.

The collision code has been refactored internally. These changes should be largely invisible, but if you encounter any problems, you can (at the moment) revert to the old collision code using the command line option -collisionHandler GENERIC. The old collision code will be removed completely at a later date.

Forces applied to dynamic components are now zeroed in the MechModel’s preadvance() method, before its input probes and controllers are applied. This is a subtle change, but it means that probes and controllers can now set forces directly, rather than having to set the external force. (Note that input probes and controllers not associated with the model are called before preadvance() and so these will still need to set external forces in order to have any effect.)

A new decomposition class, EigenDecomposition, has been added to maspack.matrix. This computes eigenvalue decompositions for both unsymmetric and symmetric dense matrices, using the methods factor() and factorSymmetric(). Some of the code, particularly for the unsymmetric case, was taken for the public domain JAMA library.

Changes have been made to allow ArtiSynth to be run in "batch" mode. To do this, simply run ArtiSynth with the command line option

   -noGui

and it will start up without any of the GUI structures. The options -model and -playFor can be used to load a particular model and have it play for a specific time (in seconds), as in:

It is also possible to specify a Jython script to be run, as in

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

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

When run in batch mode, certain standard GUI structures, such as the viewer, viewer manager, timeline, and main frame, will not be created and any references to them will be null. Models which refer to these structures must allow for this if they are to run properly in batch mode.

In particular, calls to the RootModel methods getMainFrame() and getMainViewer() will return null when operating in batch mode. The Main method getViewerManager() and getTimeline() will also return null.

Control panels can still be created as before: in batch mode, they will still be added to the RootModel but will not be activated or made visible.

In order to support both Swing panel and terminal versions of Jython, it was necessary to refactor the Jython support code. The Swing panel is implemented using a ReadlinePanel (formerly called ReadlineConsole), while the terminal console is implemented by subclassing the JLineConsole class found in the Jython package itself.

Because of the different underlying implementations, the Swing panel and terminal implementations may behave slightly differently. In particular, keyboard interrupts (CTRL-C) are implemented for the Swing panel and cause any currently existing command to be interrupted. However, CTRL-C may not do this for the terminal console (depending on the operating system), because of underlying issues with JLineConsole. On Linux, entering CTRL-C on the terminal console simply aborts the entire program.

It is now possible to specify command line model options that are passed to the args argument of a model’s build() method. Any command line option appearing after the delimiter option -M will be passed to args (which is a String array). For example,

will cause args to have a length of two and contain the strings "-color" and "red". If no model options are specified, then args will have a length of zero.

Model options can also be specified in Jython, by supplying additional arguments to the loadModel command:

When creating ControlPanels, it was once necessary to explicity pack them, make them visible, and set their position with respect tp the main ArtiSynth frame, using a code fragment in the attach() method that would look like this: