3D Models

VisualCommander handles 3D geometry for its 3D displays using geobundles. All 3D models must be in the Wavefront OBJ file format. The OBJ files and supporting files are in a geobundle folder.

OBJ Files

The OBJ file is a simple non-hierarchical 3D model file format. Within the OBJ file objects are defined by vertices and faces. The faces define geometric objects. VisualCommander can only handle triangles.

If your file has polygons with more than 3 vertices you will need to find a converter. The Princeton Satellite Systems Spacecraft Control Toolbox has a converter. This process is sometimes called tesselation.

The faces may be organized into groups. Each group may have an associated material file which defines the color of the group and textures applied to the group. Textures must be tga files. If you do not have tga files, an application, like GraphicConverter, can convert the files for you.

Geobundle Structure

A geobundle is a folder that goes in your Application Support/VisualCommander/Geometry Data folder. An example is shown below.

The geobundle consists of

An MTL file may have as many TGA files as necessary.

Manifest Files

The manifest file includes the names of the OBJ and MTL files and a scaling factor. The object name will appear in menus in VisualCommander. The scaling factor converts from model units to physical units.

Articulation

Groups in a geobundle can be articulated in VisualCommander. This allows independent rotation of each group. The manifest file contains the articulation data.

The data is in xml. The ARTICULATION_GROUP is a list of groups within the OBJ files that have the same point of roation (LOCAL_POINT), same axis of rotation (AXIS) and same limits of rotation (LIMIT). You can group objects using the model viewer and experiment with different axes and local points.

Any group that is not assigned to an ARTICULATION_GROUP can be manipulated in model viewer as shown below. The axes are x-red, y-green and z-blue and the origin is the point of rotation. You move the axes with the slider. Once you are happy with the location you use the articulation sliders to rotate the object. The viewer provides a convenient way to find the point of rotation. This may also be available from a CAD program such as SolidWorks or a 3D model in a format that has connection information. You need to enter the resulting information by hand into the manifest file.

A typical manifest.xml file used in a GeometryUtils geobundle looks like this:

<PSS_GEO_BUNDLE>
    <OBJECT_NAME>SRTFerryStage</OBJECT_NAME>
    <1.000000</METERS_TO_UNITS>
    <OBJ_FILE>srt_gear.obj</OBJ_FILE>
    <MTL_FILE>srt_gear.mtl</MTL_FILE>
    <ARTICULATION>
        <ARTICULATION_GROUP>
            <GROUP_NAME>WheelL</GROUP_NAME>
            <GROUP_NAME>GearL1mesh</GROUP_NAME>
            <GROUP_NAME>GearL2mesh</GROUP_NAME>
            <GROUP_NAME>GearDoorL1</GROUP_NAME>
            <GROUP_ID>1</GROUP_ID>
            <LOCAL_POINT>4.0 2.9 0</LOCAL_POINT>
            <AXIS>0 0 1</AXIS>
            <LIMIT>-120</LIMIT>
        </ARTICULATION_GROUP>
        <ARTICULATION_GROUP>
            <GROUP_NAME>WheelR</GROUP_NAME>
            <GROUP_NAME>GearR1mesh</GROUP_NAME>
            <GROUP_NAME>GearR2mesh</GROUP_NAME>
            <GROUP_NAME>GearDoorR1</GROUP_NAME>
            <GROUP_ID>2</GROUP_ID>
            <LOCAL_POINT>-4.0 2.9 0</LOCAL_POINT>
            <AXIS>0 0 1</AXIS>
            <LIMIT>120</LIMIT>
        </ARTICULATION_GROUP>
        <ARTICULATION_GROUP>
            <GROUP_NAME>WheelF</GROUP_NAME>
            <GROUP_NAME>GearDoorF</GROUP_NAME>
            <GROUP_NAME>GearF1</GROUP_NAME>
            <GROUP_NAME>GearF2</GROUP_NAME>
            <GROUP_NAME>GearF3</GROUP_NAME>
            <GROUP_NAME>GearF4</GROUP_NAME>
            <GROUP_ID>3<
            <LOCAL_POINT>0 4.0 4.2</LOCAL_POINT>
            <AXIS>1 0 0</AXIS>
            <LIMIT>92</LIMIT>
        </ARTICULATION_GROUP>
        <ARTICULATION_GROUP>
            <GROUP_NAME>GearF3</GROUP_NAME>
            <GROUP_NAME>GearF4</GROUP_NAME>
            <GROUP_ID>3</GROUP_ID>
            <LOCAL_POINT>0 3.5 2.5</LOCAL_POINT>
            <AXIS>1 0 0</AXIS>
            <LIMIT>-36</LIMIT>
        </ARTICULATION_GROUP>
    </ARTICULATION>
</PSS_GEO_BUNDLE>

The section can contain any number of members. Each of these is a reference to a movable part in the model identified by its group name (G tag in the OBJ file). A local point is given (in the coordinate system of the model) which is used as the rotation point.

Within an ARTICULATION_GROUP, only the GROUP_NAME is required. If no local point is given, it is assumed to rotate about 0,0,0 in the model's local coordinate system (this is rarely correct). You may also include more than one GROUP_NAME within the same ARTICULATION_GROUP to assign the same articulation parameters to multiple parts.

A GROUP_ID may be specified so that multiple parts may be articulated with a single call. This can ONLY be done by including a GROUP_ID. Simply including more than one part name within an ARTICULATION_GROUP won't allow the articulation of multiple parts with one call. Notice that in the above example, the same GROUP_ID is specified in two different ARTICULATION_GROUPs. This allows a simple articulation to be applied to all the parts specified in both ARTICULATION_GROUPs with one call.

In addition, an AXIS and LIMIT can be provided. If provided, they specify an axis of rotation (expressed as a unit vector) and an angle limit in degrees where the original position of the group is zero. For example, if axis is specified as 1 0 0 and limit is specified as 45, then the model group can be rotated about the x axis from 0 to 45 degrees. If limit were specified as -90, then rotation would be allowed from 0 to -90 in the negative direction. Specify zero for the limit to allow any rotation (or omit the LIMIT altogether for 360).

Including an AXIS does not prevent using a quaternion to rotate the group to any orientation. It only makes it easier to specify a simple value to rotate about a predefined axis. The set_group_articulation_value function allows you to specify a number between 0.0 and 1.0 representing the range from zero rotation to the LIMIT specified about the predefined axis.

The set_group_articulation_to_quat and set_group_articulation_to_rot_matrix functions allow you to set the movable group to any orientation by specifying a quaternion or rotation matrix.