Body file reference manual

Summary

This is a reference manual on the Body format model files (Body files) used by Choreonoid by default.

Model file rules

Each model file defines rules for a single robot or environment model. In order to distinguish these files from normal YAML files (.yaml), the extension is set to .body.

YAML syntax

For details on YAML syntax, please refer to the Programmer’s Guide to YAML (Beginner).

node list

The below types of nodes are defined in the specifications. By assembling these into instances, you can create models. By combining node instances into a hierarchical structure, you can define the format of the model.

Nodes that define the link structure and dynamics/mechanisms parameters are as follows.

The below nodes are defined as nodes used to define the shape and display of links.

The below nodes are defined as nodes used to define sensors and devices.

The below node is defined as a node used to define closed link mechanisms.

The below node is defined as a node used to group other nodes.

The following provides details on each node.

Headers

Placed at the beginning of a file and specifying the format of the model file.

Header fields
Key Details
format Set as “ChoreonoidBody.”
formatVersion Specifies the version of the model file format. The current version is 1.0.
angleUnit This is used to specify the units to use for joint angles in the model file. Set as “degree” or “radian.”
name Set the model name.
rootLink Set the root link name.

Nodes defining sensors and devices

Device nodes

Display common settings shared among devices.

Device node common fields
Key Details
id The device ID.
translation Give the local coordinate system position as an offset value from the parent node coordinate system.
rotation The orientation in the local coordinate system, given as an offset value from the parent node coordinate system ([x, y, z, θ] vectors: θ rotation around [x, y, z]).

Note

Each sensor node is added below the Link node to which that sensor is applied. For example, if you have attached an accelerometer to the wait of the sample model, you would use the following.

links:
  -
    name: WAIST
    elements:
      -
        type: AccelerationSensor
        id: 0

AccelerationSensor nodes

AccelerationSensor nodes are defined as 3-axis accelerometers.

AccelerationSensor node fields
Field Details
type AccelerationSensor
maxAcceleration The maximum measurable acceleration. Specify as a list containing the three elements of the 3D vector.

RateGyroSensor nodes

RateGyroSensor nodes are defined as 3-axis angular sensors.

RateGyroSensor node fields
Key Details
type RateGyroSensor
maxAngularVelocity The maximum measurable angular velocity. Specify as a list containing the three elements of the 3D vector.

ForceSensor nodes

ForceSensor nodes are defined as force/torque sensors.

ForceSensor node fields
Key Details
type ForceSensor
maxForce The maximum measurable force. Specify as a list containing the three elements of the 3D vector.
maxTorque The maximum measurable torque. Specify as a list containing the three elements of the 3D vector.

Camera nodes

Camera nodes are defined as visual sensors.

Camera node fields
Key Details
type Camera
format
Specify the type of data to be polled from the sensor.
・”COLOR” polls color data
・”DEPTH” polls depth data
・”COLOR_DEPTH” polls color depth data
・”POINT_CLOUD” polls the 3D point cloud
・”COLOR_POINT_CLOUD” polls the color data’s 3D point cloud
on Use true/false to turn the camera on/off
width The image width
height The image height
fieldOfView The camera view angle
nearClipDistance The distance to the nearest clip plane in view
farClipDistance The distance to the furthest clip plane in view
frameRate How many images the camera should output per second

Note

The view orientation is defined as follows. Forward line of sight: negative Z axis position in the local coordinate system.Upward line of sight: positive Y axis position in the local coordinate system.

Note

Internally, when the format is set as COLOR, Camera is used. When set as anything other than COLOR, RangeCamera is used.

RangeSensor nodes

The RangeSensor node is used to define range sensors.

RangeSensor node fields
Key Details
type RangeSensor
on  
yawRange The horizontal angle for the scan distance. Measured as the angle of yawRange, with 0 as a starting point and angles measured in multiples of the yawStep for either side. If there is no horizontal scan functionality in the sensor, this is treated as 0. Given as a multiple of yawStep in the range between 0 and 360.
yawStep The steps (increments) of horizontal angular distance measured during a scan.
pitchRange The perpendicular surface angle when scanning a distance. Measured as the angle of pitchRange, with 0 as a starting point and angles measured in multiples of the pitchStep for either side. If there is no perpendicular scan functionality in the sensor, this is treated as 0. Given as multiples of pitchStep in the range between 0 and 170. (If giving a large value, processing time lengthens and measurement fidelity worsens.)
pitchStep The steps (increments) of perpendicular surface angle measured during a scan.
scanRate The frequency of scans per second (Hz).
minDistance The minimum measurable distance (meters).
maxDistance The maximum measurable distance (meters).

Note

The orientation of the sensor with respect to the link on which it is installed. In the coordinate system, the negative direction on the Z axis is the front orientation of measurement. When scanning, the horizontal measurement plane is XZ, and the perpendicular measurement plane is YZ. This is the same as VisionSensor; if changing a model where this was substituted for VisionSensor, the position and orientation remain the same. The order of rotation when scanning the horizontal and perpendicular is yaw, then pitch.

SpotLight nodes

SpotLight nodes define lights.

SpotLight node fields
Key Details
type SpotLight
on Give true or false to turn the light on or off.
color The light color (give as 0.0-1.0 for each RGB value).
intensity The intensity of brightness (five as 0.0-1.0).
direction The orientation of the light. Give orientation as a list of three elements (3D vectors).
beamWidth The angle of beam width at maximum shininess. By default, this is 90 degrees.
cutOffAngle The angle at which the light is fully shut out. By default, this is 45 degrees.
cutOffExponent Given as a non-negative value. By default, set at 1.0.
attenuation The rate of attenuation. Specified as a list of three non-negative elements.

Nodes use to group other nodes

Group nodes

This is used to group select nodes together.

Group node fields
Key Details
name Group name 
(Example)
elements:
  - &SUBSYSTEM
    type: Group
    name: SUBSYSTEM
    elements:
      -
        (Group 1 element)
      -
        (Group 1 element)
       :

Adding an alias to the group node allows you to, when there is a layout the same as SUBSYSTEM in a separate location, invoke it with the below:

elements: *SUBSYSTEM

.