3 Interfacing to Jython

Once the Jython console is open, it can be used to query ArtiSynth structures and model components. Every publicly accessible method of every Java object can be called via the interface. The interaction syntax is similar to Java queries under MATLAB. Java objects can be created by calling their constructors directly, without the need for the keyword new. For example,

creates a new instance of maspack.matrix.Vector3d and initializes it to (1, 2, 3). However, unlike MATLAB, packages must be explicitly imported in order for their classes to be visible. Hence the code fragment above would need to be preceded at some point by

The from statement can also be used to import every class of a package so that they can be referred to without using their full package names:

For convenience, the ArtiSynth Jython console already fully imports (using from) a number of packages, including:

To easily access particular components of a model, the predefined function getsel() provides access to the ArtiSynth selection list. That means you can select items in the ArtiSynth GUI (using either the viewer or navigation panel) and then access these in Jython using getsel(). If called with no arguments, getsel() returns the entire selection list. If called with an integer argument i, getsel(i) returns the i-th entry in the selection list (where the index i is 0-based).

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

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

As with MATLAB, Jython can be used to script simulations. The scripting functions are the same as those described in Sections 2.4 and 4, except that they are predefined for the ArtiSynth Jython interpreter and do not need to be called through a handle.

To load a model, one may use the function

where name is either the fully-qualified classname of the model’s RootModel, or one of the shorter names that appears under the ArtiSynth Models menu, and args... is a variable list of optional string arguments that are used to form the args argument of the model’s build() method. Once loaded, simulation may be controlled using methods such as play(), pause(), step(), or reset(). The following example shows loading a model called RigidBodyDemo and then having it simulate for 2.5 seconds:

Note: at present, if ArtiSynth is run in batch mode (Section 3.3), then the Models menu is not created and so it is necessary to call loadModel() using the fully qualified class name for the model in question. The example above would therefore have to be written as

   >>> loadModel (’artisynth.demos.mech.RigidBodyDemo’)
   >>> play (2.5)

This restriction may change in future versions of ArtiSynth.

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

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

For convenience, ArtiSynth also searches for scripts in the folders of its search path (currently defined by the ARTISYNTH_PATH environment variable) and places any that it finds under a special Scripts menu that then appears in the main ArtiSynth menu bar. To be identified by ArtiSynth as a script file, the file must a be .py file that begins with the special first line

where scriptName is the desired name for the script.

The ARTISYNTH_PATH environment variable provides a list of directories, separated by semi-colons ’;’ (on Windows) or colons ’:’ (MacOS, Linux) that ArtiSynth uses to search for certain files. For ArtiSynth to locate script files, ARTISYNTH_PATH must be set and must include the directories in which the script files reside. Directions for setting ARTISYNTH_PATH are given in the "Environment variables" section of the Installation Guide.

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

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

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

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

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

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