BodyBuilder

Getting Started

What is BodyBuilder?

BodyBuilder is a MATLAB-based application that provides a graphical means to create Body Blocks for use in SimMechanics^TM. It is hoped that the interested users will also use BodyBuilder to explore MATLAB's Object-Oriented Programming Language, which is part of the general release of MATLAB as of R2008a. Indeed, users are encouraged to extend BodyBuilder to serve their own needs. Some ideas for Customizing BodyBuilder are provided in the User's Guide.

Product Requirements

MATLAB (R2008a) or later

Additional Requirements for Exporting a Body to SimMechanics

Simulink

Simscape

SimMechanics

Features

Current

Complex bodies can be constructed by assembling Primitive shapes and previously saved bodies.

There are 5 different types of Primitive Shapes: Brick, Cone, Cylinder, Sphere, and Torus.

Each Primitive shape within a Body can be assigned an associated material. This sets the density for each Primitive, which translates to inertial properties for the Body Blocks that are exported to SimMechanics.

The entire Body or Body subcomponent can be saved to a body file or exported to a SimMechanics Body Block.

Planned

Exporting facet-based Standard Triangulation Language (STL) representation of bodies.

Exporting Virtual Reality Modeling Language (VRML) reprentation of bodies.

Simple Boolean Operations such as Union, Intersect, and Subtract.

Limitations

Joints are not modeled in BodyBuilder. Hence, the product of a BodyBuilder export is a single rigid body that is passed to SimMechanics.

Part Assembly Operations are not included. (BodyBuilder is not intended to be a cheap CAD package.) Although there are plans to introduce simple Boolean operations, more complex operations such as cutting, extruding, mating, etc. are left to the industrious user.

Installation

Installing BodyBuilder is a two step process:

Extract the zip file, and
Run install_BodyBuilder.m. This script helps the user make all necessary path changes, including paths to classes and static libraries.

If there are complications with install_BodyBuilder, the user may have to manually Add requisite Java classes and libraries to the path.

NOTE: The following steps are not necessary if install_BodyBuilder ran successfully

Appending Java Class Path and Library Path

BodyBuilder employs Java classes, so we need to make sure MATLAB knows where to locate the necessary classes and libraries. The easiest way to do this is to edit the text files classpath.txt and library.txt once, close MATLAB, and then relaunch MATLAB. An alternative approach is to run the helper script set_dynclasspath.m; however, the changes are temporary for the current instance of MATLAB. Both approaches are described next.

Permanent Path Addition

Follow these steps to add the required java classes and libraries to the path. This need only be done once.

>> edit classpath.txt

>> edit librarypath.txt

Classpath.txt

At the top of classpath.txt, add the complete path description for the following four jar files:

j3d-org-java3d-all.jar
j3dcore.jar
j3dutils.jar
vecmath.jar

For example,

##

## FILE: classpath.txt

##

## Generated from: gen_classpath.pl

##

## Entries:

##    o path_to_jarfile

##    o [glnxa64,glnx86,sol2,sol64,unix,win32,win64,mac,maci,maci64]=path_to_jarfile

##    o $matlabroot/path_to_jarfile

##    o $jre_home/path_to_jarfile

##

C:/sandbox/Projects/SandV/SandV1/Projects/BodyBuilder/ext/j3d-org-java3d-all.jar

C:/sandbox/Projects/SandV/SandV1/Projects/BodyBuilder/ext/j3dcore.jar

C:/sandbox/Projects/SandV/SandV1/Projects/BodyBuilder/ext/j3dutils.jar

C:/sandbox/Projects/SandV/SandV1/Projects/BodyBuilder/ext/vecmath.jar

$matlabroot/java/patch

... snip ...

An easy way to determine the absolute paths is to run the commands:

>> fullfile(bb_root, 'ext', 'j3d-org-java3d-all.jar')

>> fullfile(bb_root, 'ext', 'j3dcore.jar')

>> fullfile(bb_root, 'ext', 'j3dutils.jar')

>> fullfile(bb_root, 'ext', 'vecmath.jar')

Librarypath.txt

At the top of librarypath.txt, add the folder that contains the dynamic link libraries. The path can be determined with the command:

>> fullfile(bb_root, 'ext')

The file should look something like:

##

## FILE: librarypath.txt

##

## Entries:

##    o path_to_jnifile

##    o [alpha,glnx86,sol2,unix,win32,mac]=path_to_jnifile

##    o $matlabroot/path_to_jnifile

##    o $jre_home/path_to_jnifile

##

$matlabroot/bin/$arch


C:/sandbox/Projects/SandV/SandV1/Projects/BodyBuilder/ext

... snip ...

After the files have been saved, exit and re-launch Matlab.

Temporary Path Addition

This approach takes effect immediately, but only lasts through the current Matlab session.

>> set_dynclasspath

Building a Body

The process of building a body from scratch and exporting to SimMechanics involves five basic tasks:

Adding shapes,
Adjusting shape geometries,
Positioning shapes in an absolute sense or relative to one another,
Assigning material to shapes, and
Export the entire body or subcomponent to SimMechanics.

For example, let us build a satellite that consists of a cylindrical body and two solar panel "wings". First, we launch BodyBuilder:

>> BodyBuilder;

which brings up the main interface.

BodyBuilder Interface

The BodyBuilder GUI consists of four regions:

Shape Addition Controls,
Shape Hierarchy Tree,
Shape Details, and
Shape Viewer.

In the Controls region, the user can select a Shape type from a popup list that is added to the body when the "Add Shape" button is hit. Currently, the list of Shapes consists of an item names "Shape Assembly" and five primitives (Brick, Cone, Cylinder, Sphere, and Torus). Shape Assembly is a container of shapes, which provides a convenient means to componentize a set of shapes into an assembly. When the user chooses to save a body or export a body to SimMechanics, either the entire body or any one of the Shape Assemblies can be selected. In the following image, the user has selected a Brick primitive and added it to the body.

Notice in the following image, that shapes appear in the Shape Hierarchy in a parent/child hierarchical tree structure. Parent shapes are always of type Shape Assembly while child shapes can be either of type Shape Assemblies or any of the Primitive Shapes. Here, we see the Brick shown as a child of the top-level Shape Assembly "body".

The Shape Details region consists of three tabbed panels: Geometry, Coordinate Systems and Material Properties. In the following image, we see that the Brick's dimension have been changed to (width=4; height=3; and depth=1) in the Geometry panel.

The previous image displays the Coordinate System panel. In the Coordinate System panel, the user can add (+) and remove (-) coordinate systems, as well as change the location and orientation of the coordinate systems. Coordinate systems can belong to Primitive Shapes or Shape Assemblies. Positioning a coordinate system involves specifying a reference coordinate system. The reference coordinate system can be either another coordinate system on the current shape, a coordinate system of the parent shape, or the World Origin coordinate system, which is fixed in space.

The Geometry Panel is active only for Primitive Shapes because an assembly's geometry depends on the Primitives that are contained within the assembly. The Geometry panel can also be used to change the preferred units for a Shape as the following image illustrates.

The Material Properties panel is used to attach a material to a Primitive Shape. Each Material has physical attributes density, elastic stiffness, and Poisson's ratio; however, only density is used at this time. Density together with shape geometries determines the inertial properties for the shapes. Materials also have display related attributes, which can be used to clearly identify shapes within an assembly. Currently, there are seven different materials. Should the user wish to add new materials or modify the properties of the ones already available, s/he would modify the constructor method in BodyBuilder.m by copying, pasting and/or modifying the ShapeMaterial calling functions (similar to the following lines) to suit.

           
materials{end+1}    =
ShapeMaterial('material_name','Steel',...

               
'density',7800,...

               
'youngs_modulus',200,...

               
'poissons_ratio',0.3,...

               
'ambientColor',[0.4805 0.4063 0.9297],...

               
'emissiveColor',[0.4805 0.4063 0.9297],...

               
'diffuseColor',[0 0 0],...

               
'specularColor',[1 1 1],...

               
'shininess',100);

To change the names of shapes, click and edit the corresponding node in the Shape Hierarchy tree.

To move and rotate a Shape Assembly, modify the values for the shape's Origin coordinate system.

Similarly, to move and rotate Primitive Shapes, change the values of its Origin.

The Shape Viewer region allows the user to inspect the body by zooming, rotating, and panning. There are also radio buttons rotate the body about the global X, then Y axes. Finally, there are a set of buttons for quick orientation (Front, Back, Top, Bottom, Right, and Left).

Once the body is ready to be exported, the user does so by selecting the Export to SimMechanics menu item under Tools as shown in the following image.

The process of exporting to SimMechanics results in a new model with a single body block as shown here.

Inspecting the body block parameters, we see the inertial properties calculated by BodyBuilder.

Back in BodyBuilder, the user can save the entire body or any Shape and its descendants ("Save Selected Body As..") to a body file, which can be used in future sessions.

Product Page