DIMPLE 0.0.6: Documentation

This documentation describes the messages received and sent by DIMPLE. The following syntax is used:

  • Square brackets [] for optional parameters
  • Triangle brackets <> for required parameters
  • Parameters are prefixed with a type indicator:
    • i: 32-bit integer
    • f: 32-bit floating point
    • s: string

Values

Any value specified by an OSC address can be set by providing a parameter directly, or retrieved by appending the suffix /get. The /get suffix with no parameters will return the value exactly once. An optional integer parameter to /get specifies that the value should be returned at regular intervals the given number of milliseconds apart. (Currently 10 ms is the lowest interval that can be specified.) These timed messages can be cancelled by specifying a parameter of 0 to /get.

Values can be either scalars or vectors. Vectors can be identified by exactly three floating-point parameters. Vectors can also be referenced by appending the /magnitude suffix which will set the magnitude of the vector, leaving its current direction the same. /get can also be appended to /magnitude.

There are currently some exceptions to these rules, but later versions of DIMPLE will attempt to mostly eliminate them.

Connecting to DIMPLE

DIMPLE communicates exclusively using Open Sound Control over UDP, using port 7770 for receiving and port 7771 for sending. In other words, using 7770 as the destination port in your application, and 7771 as the receiving port.

Messages

Enabling graphics and haptics

Graphics and haptics have to be enabled explicitly after connecting to DIMPLE.

/haptics/enable <i:0,1>
/graphics/enable <i:0,1>

Use a parameter of 1 to enable either modality. Graphics takes place in a GLUT window, and haptics opens communiation with a haptic device.

Creating objects

/object/prism/create <s:name> [f:x] [f:y] [f:z]
/object/sphere/create <s:name> [f:x] [f:y] [f:z]
/object/mesh/create <s:name> <s:filename.3ds> [f:x] [f:y] [f:z]

These messages create a named object as either a prism, sphere, or arbitrary mesh, which must be specified in the .3DS file format. Optionally, an initial position can be specified. The initial size will be quite small, so these messages are usually followed up by a /size or /radius message.

Creating constraints

/constraint/fixed/create <s:name> <s:object1> <s:object2>
/constraint/ball/create <s:name> <s:object1> <s:object2> <f:anchorx> <f:anchory> <f:anchorz>
/constraint/hinge/create <s:name> <s:object1> <s:object2> <f:anchorx> <f:anchory> <f:anchorz> <f:axisx> <f:axisy> <f:axisz>
/constraint/hinge2/create <s:name> <s:object1> <s:object2> <f:anchorx> <f:anchory> <f:anchorz> <f:axis1x> <f:axis1y> <f:axis1z> <f:axis2x> <f:axis2y> <f:axis2z>
/constraint/universal/create <s:name> <s:object1> <s:object2> <f:anchorx> <f:anchory> <f:anchorz> <f:axis1x> <f:axis1y> <f:axis1z> <f:axis2x> <f:axis2y> <f:axis2z>

Constraints can be created between two objects, or between an object and the world coordinate system. For the latter, specify object2 as world. Different constraints take different numbers of arguments depending on how many points and vectors are needed to define them. Please see the ODE documentation section on Joints for more information on each constraint type.

Object values

/object/<name>/position <f:x> <f:y> <f:z>
/object/<name>/velocity <f:x> <f:y> <f:z>
/object/<name>/acceleration <f:x> <f:y> <f:z>
/object/<name>/force <f:x> <f:y> <f:z>
/object/<name>/mass <f:mass>
/object/<name>/color <f:r> <f:g> <f:b>

Values for prisms and meshes

/object/<name>/size <f:width> <f:depth> <f:height>

Values for spheres

/object/<name>/radius <f:radius>

Other object messages

/object/<name>/texture/image <s:filename>

Sets a visual and haptic texture for the object. Currently only implemented for prisms.

/object/<name>/collide/get <i:0,1>

A parameter of 1 indicates that collisions for this object are requested. 0 indicates not to report collisions for this object.

/object/<name>/grab [i:0]

This message with no parameter indicates that this object should be “grabbed”, i.e., should be attached by virtual coupling to the location of the haptic proxy. A parameter of 0, or grabbing another object, will return the object to the default behaviour.

Constraint responses

/constraint/<name>/response/spring <f:stiffness> <f:damping>

Currently only the spring response on the hinge constraint is implemented. Stiffness and damping coefficients can be specified for this spring.

Global messages

/object/collide/get <i:0,1>

This message with a parameter of 1 specifies that collisions between any two objects should be reported. A parameter of 0 disables reporting of collisions between any two objects, but specific objects can still be enabled for collision reporting.

/world/gravity <f:x> <f:y> <f:z>

Sets the world's gravity vector to a given direction and magnitude.

/world/clear

Clears all objects in the world. (Note: A bug often causes crashing when this method is called.)

Send-only messages

These messages are sent by DIMPLE, but are not received by DIMPLE.

/object/collide <s:object1> <s:object2> <f:velocity>

A collision between the two given objects has occurred at the given velocity.

/object/<name>/collide <s:object> <f:velocity>

The object name has collided with a given object at the given velocity.