[ VSE | The 3D environment | Requirements & Installation | Download | Simulation Models | License ]
A quick note on design philosophy: Much of this project is academic in nature. It would probably be implemented differently in the commercial world. The author is exploring aspects of OOD, and some of the design decisions may end up serving more as lessons learned in how not to do things, instead of the best way to do them. That being said, the current structure has resulted in very little time spent debugging. The use of specialized matrix and vector classes, along with the use of enumerations for indexing, has resulted in many potentially difficult to find errors being caught at compile time instead of run time. One of the design goals behind this project is to allow the compiler to do as much of the debugging as possible.
Another design goal is efficiency. First of all, the use of the "new" statement for temporary objects within methods that may occur during every integration step is avoided. Instead, such objects are initialized when the containing classes are instantiated, and reused on each call to the method. Given that most classes are kept relatively small by design, such object "global" variables should not create much confusion, especially since their purpose is generally well documented in the code. While the Java garbage collector is very efficient, there is no reason for continuously placing new objects on the heap when they can be reused. Past experience has shown that memory deallocation tends to be more resource intensive than allocation.
In addition to object reuse, loops are avoided when possible. For example, if an object has three elements, instead of looping for i=1 to 3 to multiply each element by a scalar value, each element is manually multiplied by the scalar:
a[0] *= b; for (i=0; i<3; i++) {
a[1] *= b; vs. a[i] *= b;
a[2] *= b; }
This method is obviously not employed if it makes the code harder to follow
or becomes cumbersome. It is used when convenient because
testing has shown a 10:1 improvement in performance (even when using the
JIT, which comes standard with Java now days).
Controls for each environment will depend on the model in use. However, unless the mouse has been remapped in the operating system, the left mouse button will rotate the view while the right mouse button will pan. If a scroll wheel is available, it will control zoom - otherwise, the middle mouse button can be used to zoom in and out.
Mesh models have been built with Misfit Model 3D. I am barely competent at using it, so my solid models are very basic....
To run any of the included models, it is necessary to install the Vehicle Simulation Environment. The VSE filename contains the prefix "vseLib", along with a tag in the form of "-YYYYMMDD", and ends with the filename extension ".jar". For example:
vseLib-20080930.jarIf the JAR file is not going to be extracted, it is probably easiest to rename or link it to "vseLib.jar" once downloaded. This way, the CLASSPATH environmental variable does not need to be modified each time a new version is downloaded.
Installation of the library involves copying the JAR file to whatever location you like, and adding it to your CLASSPATH. How you add it to your CLASSPATH will depend, once again, on the operating system you are using and the environment in which Java is run (command line, shortcut, IDE, etc...). From the command line, in Linux (bash), you would add the following line to your .profile (or similar):
export CLASSPATH=.:/usr/local/javalibs/vseLib.jar:$CLASSPATHThis sets your CLASSPATH environmental variable to include the current directory, the path to vseLib.jar (assuming you copied it to /usr/local/javalibs/), and to include the old CLASSPATH.
Each individual model package follows the same naming convention, and is installed in a similar fashion. For example, if the library is installed in /usr/local/javalibs/, and the model is installed in my home directory "kurt", then the update to my CLASSPATH would be:
export CLASSPATH=.:/usr/local/javalibs/vseLib.jar:/home/kurt/modeling/sixdQ.jar:$CLASSPATHModels, along with classes used to run them in a simulation, are packaged individually as libraries. The actual model typically consists of two classes. The most basic represents a system of differential equations, and does nothing more than take the current time and state vector as inputs, returning the corresponding derivative to that state vector. Another class contains this set of differential equations, and is where the integrator is chosen, the ability to propagate (take a step forward in time) is configured, outputs are generated if necessary, and accessor methods to the state vector, control values, and output values are defined. Both of these classes are very generic and independent of any GUI or graphics libraries. In fact, a set of differential equations for 6DOF simulations exists in the VSE library, eliminating the need to build this class for a large variety of models.
The remaining classes in each package define the simulation environment, and usually contain classes that generate the GUI, set up the 3D environment, select the solid model, and connect the 3D environment to the model being simulated. User input controls (keyboard, mouse, etc...) are configured in one of these classes as well.
The primary class in each model package implements an interface needed to start the simulation. This class either needs to be instantiated within an application to run, or launched directly with the RunVSim application. The JAR file containing this application is called runVSim.jar. This JAR file can either be added to the CLASSPATH, or the RunVSim.class file can be extracted from the jar file with the command:
jar xvf runVSim.jar RunVSim.classEither way, the simulation can be run with the command:
java RunVSim simulation_primary_class_nameIn the above command, if the RunVSim.class was extracted from the runVSim.jar file, then it is assumed this class resides in the current directory. Otherwise, the runVSim.jar file needs to be added to your CLASSPATH. Also, the "simulation_primary_class_name" includes the full package path to the model (see models below for the exact syntax to start each). Note that no class path is needed for the RunVSim application because it was built with the default package.
In Summary, vseLib.jar and runVSim.jar should be downloaded and added to your CLASSPATH to run any of the models included in the project. Note that all source code is included in each JAR file. It is probably easiest to forgo adding individual models to your CLASSPATH because each model is meant to act as a starting point for your own needs. It is probably best to either un-archive each model's JAR file if you code from the command line, or import each jar into your IDE.
Note that two .jar files are available on the download page. One contains the VSE library, and another is used to hold the runVSim.jar file, the example models, and some documentation.
java RunVSim com.motekew.msd3d.MassSpDp3DWhen run, it will ask for the mass, spring constant, and dampening properties, along with the initial conditions. The following are reasonable values to start with:
Mass (Kg): 5.0 Spring constant (N/m): 1.0 Dampening (N/(m/s)): 0.5 Initial position (m): 7.5 Initial velocity (m/s): 0.0 Start time (s): 0.0There is only one control for this model - the right arrow will increment a constant force in the positive X direction, and the left arrow will increment the force in the negative X direction. This force is set to zero at the start of the simulation. The above initial conditions can be replicated by setting the initial position to zero, and incrementing the force with the right arrow 15 times. This results in 7.5 units of force, that will pull the mass 7.5 units along the X-axis. Once the system dampens out, either the up or down arrow will zero the force, causing the mass to be released so it can oscillate about the origin.
More detailed information on the structure of this model can be found here.
SixDQ is the main class, and can be run from the command line with the statement:
java RunVSim com.motekew.sixdq.SixDQCurrently, all physical characteristics (mass, inertia tensor, thrust/torque levels) of the vehicle are hard coded. The vehicle can be controlled with the following commands:
E Pitch Down D Pitch Up F Roll Right Wing Down S Roll Left Wing Down G Yaw Right A Yaw Left UP_ARROW Increase Thrust DOWN_ARROW Decrease Thrust (minimum value of zero - no negative thrust) SPACE BAR Show/Hide Model State Viewer window Q Zero Thrusts & Torques R Zero All Rotation Rates T Zero All Translational Velocity
The 'R' and 'T' commands are there to help one recover from an out of control situation. These two commands simply zero the appropriate terms in the state vector. Eventually, a control system will be added to perform such tasks correctly.
The Model State Viewer is a window that shows the current simulation time, the model state vector, the controls, and the output vector. The State Vector is as follows:
X: X-axis position Y: Y-axis position Z: Z-axis position DX: X-axis velocity DY: Y-axis velocity DZ: Z-axis velocity Q0: Scalar component of Quaternion attitude QI: 1st vector component of Quaternion attitude QJ: 2nd vector component of Quaternion attitude QK: 3rd vector component of Quaternion attitude P: Rotation rate about body X-axis (rad/sec) Q: Rotation rate about body Y-axis (rad/sec) R: Rotation rate about body Z-axis (rad/sec)Everything has been normalized to some extent. The spacecraft is two distance units wide. Torques and rotations all follow the right hand rule. The Control vector contains the following elements:
FX: X-axis force FY: Y-axis force FZ: Z-axis force TX: Torque about X-axis TY: Torque about Y-axis TZ: Torque about Z-axisThe Output Vector:
BANK: Bank (deg) ELEV: Elevation (deg) HEAD: Heading (deg)The state vector labels are automatically generated from the Enumerations used to represent them.
