Scientific Computing and Visualization Group
Boston University

The virtual world is partitioned into `rooms’. A participant may be in only one room at a time, seeing, hearing, and/or interacting with the objects which are in that room. Each object in the room is a `group’ of sequences.

A room file defines a room, specifies certain properties of a room, and lists the group files for groups which are in that room. A group file defines a group, specifies certain properties of the group, and lists the sequence files which make up the group. A sequence file defines a sequence, specifies certain properties of the sequence, and lists the model files and sound files which define the sequence.

All variables get default values, and the commands modify them.

Coordinate systems, etc.

The basic coordinate system is the usual Cartesion system. The top level coordiante system is the physical room coordinates in the same system as the CAVE library uses for Performer, i.e., units are feet, Z is up, X points to the right, Y points forward (through the front wall), the origin is at on the floor at the center of the room.

Translations are given as (x,y,z) triples, orientations by (h,p,r) triples, using same rules as Performer, i.e., Euler angles, where heading is rotation about the Z axis, pitch is rotation about the X axis, roll is rotation about the Y axis, all using the right-hand rule for positive angles of rotation.

The Daffie viewer maintains three other coordinate systems: scene, head, and hand. When navigating, one is essentially flying the physical room through the scene space. Coordinates in the distributed protocol are in scene coordinates. Head and hand coordinate systems are kept relative to the physical (top-level) coordinate system, and are converted to scene coordinates as necessary (i.e., when broadcasting to other clients).

When defining rooms, groups, and sequences, a heirarchy of coordinate systems is maintained. A room is basically taken as sitting within it’s own coordinate system. Each group within a room has a coordinate system kept relative to the room it is in. Each sequence within a group has a coordinate system kept relative to the group it is in. Each model has a coordinate system kept relative to the sequence it is in.

The heirarchy looks like:

                    Physical
      ................/ | .............
     /                  |               
  [Mhead2phys]     [Mhand2phys]    [Mscene2phys]
     |                  |               |
    Head               Hand           Scene
                             ........../ | .......
                            /            |         
                           Room         Room      Room
                    ....../ | ...
                   /        |     
                  [M]
                   |
                 Group    Group
               ../ | ..
              /    |    
             [M]  [M]  [M]
              |    |    |
             Seq  Seq  Seq
          .../|...
         /    |    
        [M]  [M]   [M]
         |    |     |
       Model Model Model

Where each M represents a coord sys transform

Sequence Files:

Purpose: Define a sequence of models and sounds which may be played in the interactive environment.

Preferred suffix: .arp

Form:

   arp 2.0 (must be on first line, no leading spaces)
   name whatever
   geom_path dirname (rel to seqfiledir)
   sound_path path   (full path on sound server)
   playspeed s      (specify default desired framerate in frames / sec)
   tdur t           (specify default desired frame dur in sec, alt to playspeed)
   usepfb file
   frame
     playspeed s
         tdur t
         geom_size s
         geom_scale sx sy sz
         geom_xyz x y z
         geom_hpr h p r
         geom_show fname
         sound_xyz_mono x y z
         sound_hpr_mono h p r
         sound_xyz_stereo xl yl zl xr yr zr
         sound_hpr_stereo hl pl rl hr pr rr
         sound_trigger fname
         sound_move    fname
         readnth nth
   frame
     ...
   end

The commands coming before the first `frame’ keyword are `global’. Commands coming after a `frame keyword’ only apply to that frame.

Keyword usage:

arp 2.0 Required header. Must be on first line, with no spaces.
name whatever Every sequence must have a name. This name must be unique among all names used in sequences, groups, and rooms.
geom_path dirname This is the path to look in for geometry files, relative to the directory within which this .arp file is in.
sound_path path This is the FULL path ON THE SOUND SERVER to look in for sound files.
playspeed s Set the duration of a frame to 1/s.
tdur t Set the duration of a frame, i.e., how long a model will be shown. Time is in seconds.
usepfb file Read in this .pfb file for the whole sequence. If this file is not found, or if every nth (> 1) frame is being read, the individual files will be read. All sound files are always read.
frame Every line between this line and the next “frame” keyword or “end” pertains to one frame.
geom_size s Scales the model in x,y,z by the factor s, within it’s coord. sys.
geom_scale sx sy sz Scales the model in x,y,z by the factors sx, sy, sz respectively.
geom_xyz x y z Sets the position of this model relative to the (parent) group.
geom_hpr h p r Sets the orientation of this model relative to the (parent) group. (heading, pitch, and roll).
geom_show fname Add the geometry contained in this file, using the currently defined position and heading info. You may have multiple files within a frame, and may if desired change the position and heading in between.
sound_xyz_mono x y z Specify the current position to be used for sounds which will be played in this frame, use the mono command for mono sounds
sound_hpr_mono h p r Specify the current orientation to be used for sounds which will be played in this frame, use the mono command for mono sounds
sound_xyz_stereo xl yl zl xr yr zr Specify the current position to be used for sounds which will be played in this frame, use the stereo command for stereo sounds
sound_hpr_stereo hl pl rl hr pr rr Specify the current orientation to be used for sounds which will be played in this frame, use the stereo command for mono sounds
sound_trigger fname start playing the sound which is defined in this file.
sound_move fname move the sound which is defined in this file – this allows the moving of currently playing sounds.
readnth nth read every nth frame (0 or 1 read all frames, which is the default)

Sequence Group Files:

Purpose: Define a triggerable group of sequences

Preferred suffix: .arpg

Form:

   arpg 2.0  (must be on first line, no leading spaces)
   name whatever
   geom_path dirname (relative to seqgroupdir)
   geom_size s
   geom_scale sx sy sz
   geom_xyz x y z
   geom_hpr h p r
   geom_rep fname (this(these) will be the representative, gone when seq runs)
   geom_show fname (this(these) will be shown all the time)
   grab_center x y z
   grab_radius r
   trigger_center x y z
   trigger_radius r
   trigger_method
   seq_size  s
   seq_scale sx sy sz
   seq_xyz x y z
   seq_hpr h p r
   seq_path dirname  (relative to seqgroupdir)
   seq_file  fname
   ...
   seq_file  fname
   ...
   end

Keyword usage:

arpg 2.0 Required header. Must be on first line, with no spaces.
name whatever Every sequence group must have a name. This name must be unique among all names used in sequences, groups, and rooms.
geom_path dirname This is the path to look in for geom_rep and geom_show files, relative to the directory within which this .arpg file is in.
geom_size s Scales the group in x,y,z by the factor s, within it’s coord. sys.
geom_scale sx sy sz Scales the group in x,y,z by the factors sx, sy, sz respectively.
geom_xyz x y z Sets the position of the geom models relative to the group.
geom_hpr h p r Sets the orientation of the geom models relative to the group. (heading, pitch, and roll).
geom_rep fname This model will be used to represent the set of sequences indicated below. The rep will be there whenever the sequence is not playing. It is what viewer will trigger to start a sequence playing. The position and orientation of this rep uses the currently defined position and heading info.
geom_show fname Add the geometry contained in this file, using the currently defined position and heading info. This will be visible all of the time whether or not a sequence is playing.
grab_center x y z The grab_center and grab_radius define a sphere used for picking objects, when the viewer wants to grab the object. This sphere is “attached” to the sequence group, i.e., it is affected to the same transformations. Note that the intersection which is used for picking is not between the trigger wand and the sphere, but between the trigger wand and a disc of the same radius as this sphere, prependicular to the trigger wand.
grab_radius r See grab_center, above.
trigger_center x y z The trigger_center and trigger_radius define a sphere used for picking objects, when the viewer wants to grab the object. This sphere is “attached” to the sequence group, i.e., it is affected to the same transformations. Note that the intersection which is used for picking is not between the trigger wand and the sphere, but between the trigger wand and a disc of the same radius as this sphere, prependicular to the trigger wand.
trigger_radius r See trigger_center, above.
trigger_method sm Specifies which method is used for choosing the sequence to trigger within a group. sm is a string. Options are:
- uniform_random – chooses one of the sequencee randomly
- cycle – each time a trigger occurs, the next sequence is chosen (default)
- infrepeat – run the current sequence forever
Often a group has only one sequence, in which case, the trigger_method is irrelevant, with the exception of “infrepeat”.
seq_path dirname This is the path to look in for sequence files, relative to the directory within which this .arpg file is in.
seq_size s Scales the following sequences in x,y,z by the factor s, within it’s coord. sys.
seq_scale sx sy sz Scales the following sequences in x,y,z by the factors sx, sy, sz respectively.
seq_xyz x y z Sets the position of the following sequences relative to the group.
seq_hpr h p r Sets the orientation of the following sequences relative to the group. (heading, pitch, and roll).
seq_file fname Read in a sequence file. Uses the current state of all size, scale, position and orientation variables defined above it in this .arpg file.

Room Files:

Purpose: A room is a set of objects which may be seen and interacted with. A participant may be in only one room at a time, and may see, hear, and interact only with the objects in that room. A room is defined by a room file.

Preferred suffix: .arproom

Form:

   arproom 2.0  (must be on first line, no leading spaces)
   name whatever
   enter_xyz x y z
   enter_hpr h p r
   group_path dirname
   group_size
   group_scale
   group_xyz x y z
   group_hpr h p r
   group fname
   ...
   end

Keyword usage:

arproom 2.0 Required header. Must be on first line, with no spaces.
name whatever Every room must have a name. This name must be unique among all names used in sequences, groups, and rooms.
enter_xyz x y z This specifies the position a viewer will be given upon entry to the room.
enter_hpr h p r This specifies the orientation a viewer will be given upon entry to the room. (heading, pitch, and roll).
group_path dirname This is the path to look in for sequence group files, relative to the directory within which this .arproom file is in.
group_size s Scales the following sequence groups in x,y,z by the factor s, within it’s coord. sys.
group_scale sx sy sz Scales the following sequence groups in x,y,z by the factors sx, sy, sz respectively.
group_xyz x y z Sets the position of the following sequence groups relative to the room.
group_hpr h p r Sets the orientation of the following sequence groups relative to the room. (heading, pitch, and roll).
group_file fname Read in a sequence group file. Uses the current state of all size, scale, position and orientation variables defined above it in this .arproom file.