Juice File Format

Juice model files use XML syntax to structure the objects that make up each model. Before going into the details of the file format, allow me to describe the data that goes into the file.

In the Juice coordinate system, Z is the vertical axis, X is the lateral axis, and Y is the fore-aft axis. The user is of course free to build things at any angle, but Juice's "Symmetrical Editing" feature assumes that the model is symmetrical about the Y axis. The units are arbitrary, the user may interpret them as meters, inches, feet, cubits, or whatever. The only catch is that other parameters, like gravity, must use the same units, e.g. cubits per second per second if that's your chosen unit of linear measurement.

Orientations are specified with the yaw, pitch, and roll rotations that determine the object's orientation at design time. Once simulation begins the object's orientation is of course determined by the dynamics software. Yaw, pitch, and roll are stored in degrees, and must be applied in that order. The default orientation of hinges and sliders is along the vertical (Z) axis. Likewise, cylindrical bodies are by default aligned on the vertical axis.

Juice models consist of rigidy bodies connected by joints. Currently there are three types of joints: hinges, sliders, and ball joints. The C++ classes that implement bodies and joints are shown in the following inheritance tree:

The Component class contains the following attributes:

ID	A 32-bit value that uniquely identifies the object. These values are not guaranteed to be the same each time a model is saved - they are only guaranteed to be unique within a given file.
Name	A string containing a user-specified name. There is no guarantee of uniqueness; multiple objects with the same name are perfectly acceptable.
Position	A vector containing the X, Y, and Z of the object's position.
Rotation	A vector containing the waw, pitch, and roll rotations that determine the object's orientation.
Twin	This is the ID of the object's "twin." This is used to support Juice's symmetric editing feature.

The Body class contains all of the Component attributes, and adds the following:

Shape	Shape values are enumerated as follows. 0: invalid, 1: Box, 2: Capsule (capped cylinder), 3: Sphere, 4: Cylinder (flat-ended)
BoxDimensions	If Shape==1, this member contains the X, Y, and Z dimensions of the box. Otherwise, this member is ignored. It will always be present, but that's not strictly necessary, just a convenience for the user.
TubeLength	If Shape==2 or Shape==4, this is the length of the cylinder, not including the caps, if any.
TubeDiameter	If Shape==2 or Shape==4, this is the diameter of the cylinder.
BallDiameter	The meaning of this member is left as an exercist for the reader.
Mass	The mass of the rigid body. The body's inertial tensor is set to match the shape (actually, flat cylinders still have the inertial tensor of capped cylinders, but ssssh, don't tell anyone).

The Joint class contains all of the Component attributes, and adds the following:

Body1 Body1	These match the IDs of bodies in the model.
Gain MaxForce	These two parameters are used for joint motorization. The desired velocity of a joint motor is set to ((actual_postion - desired_position) * gain). This desired velocity and and the maximum force are then passed directly to ODE's joint motorization functions. (In a future version of Juice the Gain and MaxForce properties may be removed from the Juice class and placed into a AngularMotor and LinearMotor classes.)
LoStopValue HiStopValue	These values indicate the range of the joint's motion. For hinges, these are in degrees; for sliders, they are in linear units. These parameters are present in ball joint data structures, but are not presently used by ball joints. (The high stop could in the future be used to define a cone of permissible positions.)
LoStopFlag HiStopFlag	These are either 1 or 0. If 0, the stop values described above are ignored. If 1, the stops are used to limit the joint's range of motion during simulation.

RevoluteJoint and PrismaticJoint include all of the Component members, all of the Joint members, and the following two members:

Length Diameter

The length and diameter of the cylinder that will represent the joint in the Juice GUI.

SphericalJoint includes all of the Component members, all of the Joint members, and the following member:

Diameter

The diameter of the sphere that will represent the joint in the Juice GUI.

Note that none of the joint objects actually have any representation as far as the dynamics libraries are concerned. The positions and sizes are used at design time to make things more intuitive, and they're computed manually during simulations because it looks nicer that way.

In addition to the component data, each file contains a few parameters about the model itself and the virtual world it lives in. These are as follows:

Gravity	How much gravity the model expects
Friction	How much ground friction the model expects. Walking models are often quite sensitive to friction, and as you might expect the friction (or traction) greatly affects on the handling of rolling vehicles.
ERP CFM	See the ODE documentation for more explanation. Briefly, ERP should almost always be 1.0, and CFM should be between 0.01 and 0.00001. CFM values of 0.01 tend to be a bit elastic, CFM values of 0.00001 tend to be quite stiff and prone to oscillation or explosion. These are most crucial for walking models, but they will affect rolling models as well.
StandardSpeed	This governs the rate of walking vehicles, in cycles per minute. The GUI provides a slider that lets the user vary the speed from -200% to +200%, so this just provides a baseline.
PoseDelay	When entering simulation mode, it's common to "drop" the model to the ground. This delay parameter can be tuned to give the model time to drop to the ground and hold still long enough to stop bouncing or oscillating. When the delay period expires, the "main engine" kicks in and the model may begin walking. This parameter is not critical with joystick-controlled models.
PosePhase	This sets the phase of the main engine during the delay period. For walking creatures, it may be helpful to set this to a position in which the creature is statically stable. For folling vehicles, this is pretty much irrelevant.

Following is a simple Juice file:

<Model FileVersion="1">
	<Gravity>20</Gravity>
	<Friction>75</Friction>
	<ERP>1</ERP>
	<CFM>0.005</CFM>
	<StandardSpeed>35</StandardSpeed>
	<SpeedFactor>1.27</SpeedFactor>
	<PoseDelay>1</PoseDelay>
	<PosePhase>90</PosePhase>
	<Bodies>
		<Body>
			<ID>90976152</ID>
			<Name>Left Upper Hip</Name>
			<Position>
				<X>-1</X>
				<Y>0</Y>
				<Z>3.75</Z>
			</Position>
			<Rotation>
				<Y>0</Y>
				<P>0</P>
				<R>0</R>
			</Rotation>
			<Twin>90976528</Twin>
			<BoxDimensions>
				<X>0.5</X>
				<Y>0.5</Y>
				<Z>0.25</Z>
			</BoxDimensions>
			<TubeLength>1</TubeLength>
			<TubeDiameter>1</TubeDiameter>
			<BallDiameter>1</BallDiameter>
			<Shape>1</Shape>
			<Mass>0.25</Mass>
		</Body>
		<Body>
			<ID>90976528</ID>
			<Name>Right Upper Hip</Name>
			<Position>
				<X>1</X>
				<Y>0</Y>
				<Z>3.75</Z>
			</Position>
			<Rotation>
				<Y>0</Y>
				<P>0</P>
				<R>0</R>
			</Rotation>
			<Twin>90976152</Twin>
			<BoxDimensions>
				<X>0.5</X>
				<Y>0.5</Y>
				<Z>0.25</Z>
			</BoxDimensions>
			<TubeLength>1</TubeLength>
			<TubeDiameter>1</TubeDiameter>
			<BallDiameter>1</BallDiameter>
			<Shape>1</Shape>
			<Mass>0.25</Mass>
		</Body>
		... more bodies ...
	</Bodies>
	<RevoluteJoints>
		<RevoluteJoint>
			<ID>181672632</ID>
			<Name>Left Leg Lateral Joint</Name>
			<Position>
				<X>-0.75</X>
				<Y>0</Y>
				<Z>3.75</Z>
			</Position>
			<Rotation>
				<Y>0</Y>
				<P>-90</P>
				<R>0</R>
			</Rotation>
			<Twin>181672152</Twin>
			<Body1>181668752</Body1>
			<Body2>90976152</Body2>
			<Gain>10</Gain>
			<MaxForce>700</MaxForce>
			<LoStopValue>0</LoStopValue>
			<HiStopValue>0</HiStopValue>
			<LoStopFlag>0</LoStopFlag>
			<HiStopFlag>0</HiStopFlag>
			<Length>0.5</Length>
			<Diameter>0.25</Diameter>
		</RevoluteJoint>
		... more revolute joints ...
	</RevoluteJoints>
	<PrismaticJoints>
	</PrismaticJoints>
	<SphericalJoints>
	</SphericalJoints>
	<Behaviors>
		... behavior data is a whole 'nother story ...
	</Behaviors>
</Model>