VIEWS: 161 PAGES: 17

									                   HIVE API DOCUMENTATION

                       Meseret Gebre
                       Eric Hodgson

     The HIVE API was developed using C++, Python (, and
     Panda3D ( to streamline virtual reality research and
     applications in the HIVE
     (; Huge Immersive
     Virtual Environment) system at Miami University. The API handles most
     tasks involved with tracker integration and viewpoint control, and includes
     many auxiliary classes and methods to support research applications.

                                Table of Contents:

I.      Getting started
        a. The dialogue Box
             b. Specifying default options
   II.       Working with virtual objects
             a. Adding new objects
             b. Common Manipulations
             c. Adding actors (animations)
             d. Adding text
   III.      Controlling the viewpoint
             a. Input devices
                     i. Trackers
                    ii. Keyboard
                   iii. Mouse
             b. Advanced viewpoint manipulation
                     i. Offsetting
                    ii. Resets
                   iii. Gain manipulations
                   iv. Space-warping
             c. Viewpoint-updating settings
   IV.       Getting information about the viewpoint
   V.        Reading and writing data with text files
   VI.       Events and Triggers
             a. Button presses & Mouse clicks
             b. Hotspots
                     i. Standard hotspots
                    ii. Space-warp hotspots
                   iii. Directional hotspots
   VII.      Auxiliary functions and classes
             a. Mathematical functions
             b. Geometric functions
             c. The „dataStor‟ class
   VIII.     Configuration file settings **DOCUMENTATION NOT FINISHED
             a. General settings
             b. Dialogue box settings
             c. Movement keys

         Appendix I: List of classes & methods **DOCUMENTATION NOT FINISHED

                                I. Getting Started

The Hive API and Panda3D are Python ( interfaces. This manual
assumes that you have a working knowledge of the Python programming language.
To use the Hive API, you will first have to import the Hive module into your script and
create an instance of the HiveObject. The HiveObject is the main class of the API and is
provides the methods for interacting with the HIVE.

# import the Hive API for use
import Hive

# Create a HiveObject to provide access to the API‟s functionality
myHive = Hive.HiveObject( )

# Launch the VE
myHive.go( )

The Dialogue Box:
Once the HiveObject has been instantiated, a call to <HiveObject>.go( ) will start
Panda3D and the Hive API (all of the examples in this manual use the variable „myHive‟
to refer to the HiveObject). Before your VE gets up and running, a dialogue box will
appear to get information about how you want your virtual world displayed and what
navigation devices you will be using. Space is also provided for custom input. A
screenshot of the dialog box is below.

The first two sections of the dialogue box deal with the navigation devices you will be
using in your script. When running your VE in the HIVE, you will be using the PPT
(WorldViz Precision Position Tracker) to track and control the [x, y, z] position of the
viewpoint, and you will use the INERTIAL CUBE (Intersense InertiaCube2) to control
the [yaw, pitch, roll] orientation. However, it is often useful to use the keyboard and
mouse as replacements for these trackers while debugging. (Note that only one option
can be selected for position tracking, and only one option can be selected for orientation
tracking. You can‟t request, for example, to control the orientation through the mouse
and the inertial cube. This would provide conflicting data as to where the user is looking,
and is generally undesirable).

The next section of the dialogue box allows you to customize display options. Selecting
„Fullscreen‟ will run the VE in a maximized state with no window or borders. Selecting
„Stereo‟ will run the VE in stereoscopic mode, with two side-by-side views of the VE –
one for each eye. Stereo display is used for rendering a VE in a head mounted display
(HMD) to provide natural stereoscopic depth cues. The „Fullscreen‟ and „Stereo‟ options
are independent; It is possible to render the VE in stereo without rendering fullscreen and
visa versa. If neither of the options are selected, the VE will run inside a window on the

The last set of options allows for custom input that you may wish to use in your script.
For example, many of the research applications identify participants with a unique
subject number. The research experiment may run differently depending on whether the
subject number is odd or even, and this number is used to label all recorded data. The
text entry box may be used to input custom strings (such as a unique subject number).
This custom input may be accessed with the following command:

# Retrieve custom input from dialogue box
myTextInput = myHive.CustomInput                      # string

Similarly, the „Option 1‟ and „Option 2‟ checkboxes can be used to input binary
information. For example, a research experiment could be set up to skip its practice
phase if Option 1 is selected. The options are stored as boolean (True / False) values and
can be accessed as follows:

# Check to see if options 1 & 2 were selected
myOption1 = myHive.Option1          # True or False
myOption2 = myHive.Option2          # True or False

Specifying Default Options:
Sometimes it is undesirable to have to go through selecting the same options in the
dialogue box (while debugging, for example). The API provides two ways to provide
default selections to the dialogue box for specific applications.

Configuration File Method: The file „‟ contains many settings that are
can be edited to change the default behavior of the HIVE API, including the default
selections in the dialogue box. The file is set up to be very readable, and the following
code contains the options for the dialogue box.

GuiSettings = dataStor(
# Editable settings for GUI below #########################

defaultPosTracker         = ['ppt', 'keyboard'][1],
defaultOriTracker         = ['cube', 'keyboard', 'mouse'][2],
defaultFullscreen         = False,
defaultStereo             = False,
defaultOption1            = False,
defaultOption2            = False

# #########################################################

The options for the position and orientation trackers are specified as lists of all possible
options, and the choice is specified as the chosen index in that list (0, 1, or 2 to select the
1st, 2nd or 3rd options). For example, defaultPosTracker = ['ppt', 'keyboard'][0] will select
the PPT system as the position tracker and defaultPosTracker = ['ppt', 'keyboard'][0] will
select the keyboard.

In-script Method: The other way to specify the default options of the dialogue box is to
pass certain pre-defined flags to the HiveObject when it is first created. For example, the
following adaptation of the first code example starts the API as before, but first selects
the PPT and inertial cube as the tracking devices, requests the VE to render in fullscreen,
and selects Option 1.

# import the Hive API for use
import Hive

# Create a HiveObject to provide access to the API‟s functionality
myHive = Hive.HiveObject(Hive.PPT, Hive.CUBE, Hive.FULLSCREEN, Hive.OPTION1)

# Launch the VE
myHive.go( )

Any number of the flags listed in the table below may be passed (separated by commas)
to the HiveObject when it is created. Note that some flags will override others. Also
note that the flags will only specify what is selected by default – there is nothing to
prevent the options from being changed in the dialogue box at runtime.

                         Flag                              Behavior
          Hive.PPT                         Selects the PPT system as the default
                                           position tracker. (Overrides other
                                           position tracker flag.)
          Hive.CUBE                        Selects the Intersense InertiaCube2 as
                                           the default orientation tracker.
                                           (Overrides other orientation tracker
          Hive.KEYBOARD                    Selects the keyboard as the default
                                           position and orientation tracker.
          Hive.MOUSE                       Selects the mouse as the default
                                           orientation tracker. (Overrides
                             keyboard orientation flag)
         Hive.KEYBOARD_MOUSE Selects the keyboard as the default
                             position tracker, and the mouse as the
                             default orientation tracker. (Overrides
                             keyboard orientation flag)
         Hive.FULLSCREEN     Selects fullscreen rendering by default.
         Hive.STEREO         Selects stereo rendering by default
         Hive.OPTION1        Option 1 is selected by default
         Hive.OPTION2        Option 2 is selected by default

                              II. Working with Virtual Objects

Most of the object manipulation in your virtual environment will be done through the
Panda3D API, but the Hive API does provide methods to streamline some tasks.

Adding New Objects:
In Panda3D, all new objects must be loaded into memory and inserted into the scene
graph. The HIVE API allows you to do this in one step with the 'addModel' method (the
method 'loadModel' is equivalent). Note that the file path passed to the 'addModel'
method should use UNIX-style formatting (see Panda3D documentation for details), and
the model file should be a .egg file.

# Add a model to the VE
my3Dmodel = myHive.addModel('filePath')

# Equivalent command...
my3Dmodel = myHive.loadModel('filePath')

Common Manipulations:
The 'addModel' method returns a Panda3D node object that has been already loaded into
memory and inserted into the top level of the scene graph (the 'render' object). Most
subsequent manipulations of your models (such as moving, rotating, or scaling) will be
done though the functionality provided by Panda3D.

# Manipulating the model is done through Panda3D, not through the HIVE API
my3DModel.setPos(5, 10, 3)          # Move the model to (x, y, z)
my3DModel.setHpr(-90, 0, 0)         # Rotate the model to (heading/yaw, pitch, roll)
my3DModel.setScale(1, 1, 1)         # Scale the model n% in the (x, y, z) dimensions

The HIVE API does provide convenient methods for hiding visible objects or re-
displaying hidden objects. The .hide( ) and .show( ) methods accept either a single 3D
node or a list of 3D nodes and will adjust the visibility of all.
# Create an object and then hide it
myTree = myHive.addModel('tree')               # Add a tree model
myRock = myHive.addModel('rock')               # Add a rock model
myHive.hide(myTree)                            # Make the tree invisible, myRock)                    # Show both models

# Create several objects and hide them all
myForest = []                                  # Create a list to hold all of the trees
for i in range(10):                            # Loop 10 times
           tree = myHive.addModel('tree')      # Create a tree each time
           myForest.append(tree)               # Add it to the 'myForest' list

myHive.hide(myForest)                          # Hide all 10 new trees at once

# Combine two lists and show everything
otherList = [myTree, myRock]                   # Create a new list with the first tree and rock + otherList)                       # Show everything

Adding Actors (animations):
Panda3D actor objects can be added to the VE and automatically added to the scene
graph (attached to the render node) in the same way that static models are added in. The
syntax used follows Panda3D‟s „Actor.addActor( )‟ method, and requires a model path
and a dictionary containing “name”: „animation-model-path‟ pairs.

# Add an animated model „boy.egg‟ with animation files „boy_run.egg‟ and „boy_walk.egg‟
myBoy = myHive.addActor(„models/boy‟, { „run‟:‟ models/boy_run‟, „walk‟:‟ models/boy_walk‟} )

Adding Text:
The 'addText' method returns a Panda3D OnscreenText object that can be used to display
instructions or notices to the user. These text objects are attached to the screen, not to a
point in the environment, and they are always rendered on top of the scene. The
„<HiveObject>.addText‟ method takes up to six arguemtns, but may be called with no
arguments to create a text object with an empty string and the default settings. The
arguments and defaults are listed in the table below. The OnscreenText object has many
methods that can be used to further customize and manipulate the text. The most
common of these is probably the „myText.setText(“Your Message Here”)‟ command.
See Panda3D‟s documentation for further methods and options.

            argument                         default                           valid input
                text                           “”                                  string
                pos                           (0,0)                      (x, y) screen position
               color               (1, 1, 1, 1) = White                (r, g, b, alpha) 0.0 to 1.0
               align            Hive.ALIGN_CENTER                      Hive.ALIGN_CENTER,
             scale                   0.075                     (float) scaling factor
            shadow            (0, 0, 0, 1) = Black             color of back-shadow
                                                               to help text stand out
           wordwrap                     None             number of screen units at
                                                         which to wrap long strings

                              III. Controlling the Viewpoint

One of the main tasks in any virtual environment is to move the viewpoint (camera) to
allow interactive exploration of the environment. The HIVE API is set up to minimize
the amount of coding needed to complete this task. Simple navigation is handled
automatically for the input devices chosen in the dialogue box (see above), and more
complex navigation tasks can be enabled with a few simple commands.

Input Devices:
There are three types of input devices that can be used with the API – the mouse, the
keyboard, and the tracking systems in the HIVE facility. Each is covered below.

Using the Trackers: If the PPT and / or INERTIAL CUBE options are selected in the
dialogue box, then data from these devices will be read online (in real time) and used to
continually update the viewpoint. The PPT provides [x, y, z] position information, and
the inertial cube provieds [yaw (heading), pitch, roll] information. Details of how to
access the tracker data (to record a user's current heading, for example) will be discussed
in a later section.

Using the Keyboard: If the 'Keyboard' option is selected for position tracking, then
movement along the [x, y, z] axes will be controlled by key presses. Similarly, if the
'Keyboard' option is selected for orientation tracking, then rotations of [yaw, pitch, roll]
will also be controlled by key presses. Default position movement keys approximately
follow gaming standards (see table below). The '' file may be edited to
change the key assignments for translation and rotation, as well as the amount of
movement initiated by each keypress.

                        x          right          d     left              a
                        y          forward       w      backward          s
                         z         up             q     down              e
                  yaw (heading) right             4     left              6
                          pitch          down             8      down         2
                           roll          tilt right       9      tilt left    7

Using the Mouse: If the 'Mouse' option is selected for orientation, then the heading (yaw)
and pitch of the viewpoint will be determined by the [x, y] coordinates of the cursor on
the screen or window (roll will remain at zero). Moving the mouse up and down will
cause the viewpoint to pitch up or down proportionally. For example, holding the cursor
in the middle will hold the pitch steady at 0º (straight ahead); holding it at the very top of
the screen will simulate looking straight up (a pitch of +90º). Moving the cursor left or
right will cause the viewpoint to rotate in heading, with the speed of rotation in
proportion to the cursor position. Holding the mouse near the center of the screen will
keep the heading steady; holding the mouse a a bit to the right will cause the viewpoint to
slowly and continually rotate rightward; holding the mouse at the far right edge will
cause the viewpoint to rotate rightward very rapidly.

If you wish to change the yaw sensitivity or invert the pitch axis of the mouse (in a flight
simulator, for example), you may either edit the '' file or specify new
values from within your script.

# Change the mouse sensitivity for yaw rotations and invert pitch axis...
Hive.Settings.mouseSensitivity = 25
Hive.Settings.invertMouse = True

Advanced Viewpoint Manipulations:
In some circumstances, it may be desirable to change the way the viewpoint is updated.
Virtual environments, by nature, afford the possibility to change the relationship between
user movement and the resulting changes in viewpoint. For example, there is nothing to
prevent the viewpoint from moving backwards when a user moves forwards. The HIVE
API allows for these types of advanced viewpoint manipulations by separating the visual
location of the user from the physical location.

Setting the Viewpoint: You may specify a particular visual position and / or orientation
for the viewpoint with one of the following methods. Note that the default of the reset
functions technically reset the position or orientation to the defined starting location.
This location is [0,0,0, 0,0,0] by default, but can be set in the config file or by calling
„myHive.setStartLoc( [x,y,z, h,p,r] )‟:

        myHive.setPos(x,y,z)                          # Set the visual position
        myHive.setOri(yaw,pitch,roll)                 # Set the visual orientation
        myHive.setHpr(heading,pitch,roll)             # Equivilent to '.setOri( )'
        myHive.setPosHpr(x,y,z, h,p,r)                # Set the visual position and orientation
        myHive.resetPos( )                            # Set visual position to [0,0,0]
         myHive.resetXY( )                                # Set visual position to [0,0,0]
         myHive.resetOri( )                               # Set visual orientation to [0,0,0]
         myHive.resetHpr( )                               # Equivilent to '.resetOri( )'
         myHive.resetPosHpr( )                            # Reset position and orientation to zeros

                   NOTE: In general, the methods dealing with advanced
                   viewpoint manipulations are very flexible. Any method
                   that requires 3 degrees of freedom ([x,y,z] or [h,p,r]) will
                   accept 3 separate arguments, a 3-item list, or a 6-item list
                   with all 6 degrees of freedom ([x,y,z, h,p,r]. Any method
                   that requires 6 degrees of freedom will accept 6 separate
                   arguments or a 6-item list. The methods to change the
                   visual yaw (heading), pitch, and roll position for example,
                   will accept any of the following successfully...

# Various ways to store data
h = 90; p = 5; r = 30
hprList = [90, 5, 30]
sixDOF = [0,0,0, 90, 5, 30]

# All of these set the the visual yaw to 90º, the pitch to 5º, and the roll to 30º
myHive.setHpr( h, p, r )
myHive.setHpr( yprList )
myHive.setHpr( sixDOF )

Offsetting the Viewpoint: Setting the viewpoint with one of the method above implicitly
changes the physical-to-visual offset. In those cases, the amount of offset is not as
crucial as the end result of the offset – setting the viewpoint at a particular location.
However, there are cases when the situation is reversed and the amount of offset is more
important than the end-point. To accomplish this, the physical-to-visual offset can be
retrieved or changed with one of the following methods.

         myHive.getOffset( )                              # Return the offset list = [x,y,z, h,p,r]
         myHive.setPosOffset(x,y,z)                       # Offset position (x,y,z)
         myHive.setOriOffset(h,p,r)                       # Offset orientation (heading, pitch, roll)
         myHive.setHprOffset(h,p,r)                       # Equivilent to '.setOriOffset( )'
         myHive.setOffset(x,y,z, h,p,r)                   # Offset position and orientation

Gain Manipulations: Changing the gain in one of the dimensions will adjust the mapping
of movement in that dimension to the visual change in that dimension.
       Under normal viewpoint updating, all gains are equal to 1
       A gain of zero would cause that dimension to not be updated
       Gains between 0 and 1 move the viewpoint less than the user is
       Gains greater than 1 move the viewpoint more than the user is moving
          Negative gains cause viewpoint updating to be reversed (i.e., turning
           left = turning right)

The methods below allow for gain functionality. The '.useGains' method is called
implicitly when custom gains are set. It may be used to deactivate or reactivate gain
usage later. Default gains are [1,1,1, 1,1,1], but they maybe changed in the
'' configuration file.

       setGains(x,y,z, y,p,r)          # Set the gains for all 6 degrees of freedom
       getGains( )                     # Returns the gains list = [x,y,z, h,p,r]
       useGains(binaryTF)              # Use custom gains? True or False

Space-Warping: Space-warping can be thought of as a special case of setting the
viewpoint location or changing the visual offset that is triggered automatically when a
user hits a predefined location in the environment. 'Warpspots' can be defined in the
environment that, when hit, will instantly transport the viewpoint to a pre-defined goal.
For more details, see the „Events & Triggers > Space-warp hotspots‟ section of this

                      IV. Getting Information about the Viewpoint

The following methods allow you to retreive information about the user's viewpoint.

       myHive.getLoc( )                # Returns visual location = [x,y,z, h,p,r]
       myHive.getPos( )                # Returns visual position = [x,y,z]
       myHive.getOri( )                # Returns visual orientation = [h,p,r]
       myHive.getHpr( )                # Equivilent to '.getOri'
       myHive.getPosHpr( )             # Equivilent to '.getLoc'

                      V. Reading and Writing Data with Text Files

Some common tasks in research applications in the HIVE include writing out data to a
text file for later analysis and / or reading in custom settings for each participant. The
API streamlines these tasks for you with the „.writeData‟ and „.readInfile‟ methods.

The „.writeData‟ method accepts either a single item (of any type) or a list of items as its
first argument and optionally a file name to write to (default is „output.txt‟) a delimiter to
separate items in the list (default is tab-delimited) and a writing mode („a‟ = append, „w‟
= overwrite; default is „a‟). If the specified data file does not exist, it will be created the
first time the method is called. The data items(s) will be written out to a single line in the
specified text file with each item separated by the delimiter (which allows for easy
importing into spreadsheet or statistics software). If you need each data item on its own
line, specifying „\n‟ (a line break in Python) as the delimiter will cause each item to be
written on a separate line.

# Write „hello world‟ to the default file, „output.txt‟
myHive.writeData(„hello world‟)                         # Pass „hello world‟ as a single item

# Create the same output by passing each word as a list item, and separate with a space
myHive.writeData([„hello‟, „world‟], delim=‟ „)     # Prints „hello world‟ to the file

# Record a subject number, trial number, and current heading
subnum        = 999
trial         =1
heading       = myHive.getOri( )[0]         # Heading is first item in [h,p,r] orientation
trialData     = [subnum, trial, heading]    # Specify a list to hold the trial data
myHive.writeData( trialData )               #      … then write out
myHive.writeData([subnum, trial, heading]) #       … or combine in one step
                                            # Both write out:       999      1      -90.52

# Write data to „research.dat‟ instead of default output file „output.txt‟
myHive.writeData( trialData, „research.dat‟ )

To retrieve information from a text file, use the „.readInfile(“filename”)‟ method. This
method takes a string with a valid file name and returns a list with each item in the list
holding a string that represents one line of the file.

# Given the following file „input.txt‟…
Input File
997      1        23        hello
998      2        37        hello
999      1        12        goodbye

# ...The following command will read the data above…
dataFromInfile = myHive.readInfile( „input.txt‟ )

# …and return the following list:
[“997 1 23 hello”, “998 2                 37   hello”, “999      1 12     goodbye”]

# Individual lines can be further split into lists using Python‟s built-in <string>.split( )
firstLine          = dataFromInfile[0]           # Grab the first line of the infile
firstLineData      = firstLine.split( ) # Returns [„997‟, „1‟, „23‟, „hello‟]
subnumStr          = firstLineData[0]            # Get the first item in line 1 (it will be a string)
sbunum = int(subnumStr) # Convert the string to a different type if necessary

                                           VI. Events & Triggers

Key presses and Mouse clicks:
The „<HiveObject>.callback( )‟ method allows you to map a key or mouse button to a
specified function. Callbacks can be specified one at a time or as a batch. The API
defines 3 constants that can be used to assign a callback to a specific mouse button

„<HiveObject>.callback( )‟ takes a key (or mouse button), a function name to call, and
optionally a list of arguments to be passed. To define multiple callbacks at once, a series
of two- or three-item tuples containing (key, functionName [, args]) may be passed,
sepatated by commas. Alternatively, „<HiveObject>.callback( )‟ will accept a single list
of these tuples. For example…

# Define a generic function to be called when „x‟ is hit.
def myFunction( ):
         print “X was pressed”

# Define a second function that takes two arguments, to be called when “z” is pressed
def myFunc2( arg1=””, arg2=0 ):
         print “Received:”, arg1, arg2

# Associate the appropriate keys with each function
myHive.callback( „x‟, myFunction )           # Calls „myFunction( )‟ when the „x‟ key is pressed

myHive.callback( „z‟, myFunc2, [„foo‟, 4] ) # Calls „myFunc2( „foo‟, 4 )‟ when the „z‟ key is pressed

# Combine several callbacks into one statement…
myHive.callback( („x‟, myFunction), („z‟, myFunc2, [„foo‟, 4]), („space‟, myFunc3) )

# …or pre-define a long list of callbacks and create them all with one statement
myCallbackList = [
        („x‟, myFunction),
        („z‟, myFunc2, [„foo‟, 4]),
        („space‟, myFunc3)
myHive.callback( myCallbackList ) # creates a callback for each item in the list

Often it will be necessary to trigger various events when a user is at a particular point in
an environment, or to perform a certain task as long as they remain in a given region.
Hotspots allow you to associate places in the environment with a specified function,
similar to the way you would associate a key press with a certain callback function.

Hotspot objects are fairly flexible and have many options that allow you to change the
way they work, their shape, etc. Additionally, hotspots can be specialized so that they are
heading-specific (only entering from the east will trigger it), so that they „teleport‟ users
to a pre-defined destination, or both.

Standard hotspots: To create a standard hotspot and associate it with a function, use the
„<HiveObject>.addHotspot( )‟ method. „<HiveObject>.addHotspot( )‟ accepts up to six
arguments (the first three are required), representing the…
         location of the hotspot*     = [x], [x, y], [x, y, z] or a single value
         radius of the hotspot*       = [x], [x, y], [x, y, z] or a single value
         functionName*                = valid function name (no parentheses)
         args (arguments) for Function= [arg1, arg2, etc] (Default = [] )
         shape of hotspot             = Hive.ROUND, Hive.RECT, Hive.PLANE_X,
                         Hive.PLANE_Y, Hive.PLANE_Z. (Default shape = round)
         reuse or not                 = True / False (Default = False)

The type of location and radius specified will vary depending on the hotspot shape being
used and the number of dimensions required. Location refers to the center of the hotspot.
Radius refers to the half-width of the hotspot in a given dimension.

For example, a round hotspot could be spherical if an [x, y, z] location is entered, or
cylindrical if an [x, y] location is entered. Either one would only require a single value as
a radius.

Rectangular hotspots can be similarly 2D or 3D depending on whether [x, y] or [x, y, z]
coordinates are entered. Rectangles can be square or cubic if a single radius is entered, or
elongated in a dimension if [x-radius, y-radius (, z-radius)] is entered.

Plane-type hotspots create elongated thresholds across a single dimension (x, y, or z).
The desired dimension is selected by specifying the shape as PLANE_X, PLANE_Y, or
PLANE_Z. Because only a single location and radius is needed for plane (one-
dimensional) hotspots, values for the location and radius can be passed as a single value
or as an [x, y, z] list. In the latter case, the appropriate index will be pulled out of the list
and the rest of the list will be ignored.

The „reuse‟ argument specifies whether the hotspot is triggered once and then de-
activates (reuse = False; the default behavior) or fires repeatedly while the user is within
the given radius of the center location of the hotspot.

Methods to create and manipulate a hotspot…

# Create a hotspot (cylindrical) at 1m East, 2.5m North that will be triggered only once
#        …and call some „customFunction( )‟ that has been defined
myHotspot = myHive.addHotspot( [100, 250] , 50, customFunction)

# Change some of the hotspot‟s attributes
myHotspot.setPos( [300, 500] )      # Change the hotspot‟s location
myHotspot.setShape ( Hive.RECT )            # Make the hotspot rectangular
myHotspot.setRadius( [50, 25] )     # Require 50cm X-proximity & 25cm Y-proximity
myHotspot.setActive( False )                # Turn off the hotspot for now
myHotspot.setActive( True )                 # Turn it back on (i.e., reactivate after triggered)
myHotspot.setReuse( True )                  # Make it trigger continuously while being hit

Space-warping hotspots: To create a hotspot that causes the user‟s viewpoint to be
„warped,‟ „beamed,‟ or „teleported‟ to a new location, use the
<HiveObject>.addWarpspot( )‟ method. Warpspots are a sub-class of standard hotspots,
and thus share all of the same properties. However, Warpspots require one additional
offset argument, and they do not need to be associated with a callback function (although
they can be).

# Create a warp spot that teleports the user back to [0, 0]
#<HiveObject>.addWarpSpot(loc, radius, offset[, functionName, args, shape, reuse] )
myWarp = myHive.addWarpSpot( loc=[100, 500], radius=50, offset=[-100, -500, 0, 0, 0, 0] )

NOTE 1: The user‟s viewpoint is specified with 6 degrees of freedom – [x, y, z, yaw,
pitch, roll] – and offsets in any of these 6 dimensions is permissible. Thus, the offset
must always be specified as a 6-item list.

NOTE 2: If there are other offsets being applied to the user‟s viewpoint (as a result of
using the <HiveObject>.setPos( ) or <HiveObject>.setOffset( ) methods, for example),
the offset of the warp spot will be added to the total offset. It will not replace the current,
global offset.

Directional hotspots: Both Warpspots and traditional Hotspots may be set to be heading-
specific, or directional, so that they are only triggered if a user walks into them from a
particular direction. For example, a directional hotspot that requires a heading of 0º ± 15º
would be triggered by a user who is traveling / facing very close to virtual North, but not
to a user that is facing Northeast, Northwest, South, East, etc. For example…

# General form… <Hotspot>.makeDirectional( targetHeading, headingTolerance )

# Make a new hotspot that fires repeatedly as long as users are within 10º of East
mySpot = myHive.addHotspot( [100, 100], 50, someFunction, reuse=True )
mySpot.makeDirectional( 90, 10 ) # targetHeading = 90º, tolerance = ± 10º

                               VII. Auxiliary Methods and Classes

In addition to handling viewpoint manipulations, input devices, and basic file I/O, the
HIVE API provides some auxiliary functionality to support research. Many of these
functions are used internally, but may also be useful to your application.

Mathematic manipulations:

# Get the mean of a list or series of numbers
myHive.mean( 1, 2, 3, 4, 5, 6, 7 )            # Returns 4
numList = [1, 2, 3, 4, 5, 6, 7]
myHive.mean( numList)                         # Returns 4

# Add or subtract items-by-item in a list
list1 = [1, 2, 3, 4, 5]
list2 = [6, 7, 8, 9, 10]
myHive.addListwise( list1, list2)            # Returns [7, 9, 11, 13, 15]
myHive.subtractListwise( list2, list1 )      # Returns [5, 5, 5, 5, 5]
Geometric manipulations:

# Find the angular difference between two bearings / headings (corrected for circularity)
angle1 = 90
angle2 = 45
angle3 = 135
angle4 = -135
myHive.bearingDif( angle1, angle2 )         # Returns 45
myHive.bearingDif( angle1, angle3 )         # Returns -45
myHive.bearingDif( angle3, angle4 )         # Returns -90, not +270

# Correct a bearing for circularity with „.circleCorrection( angle, min=-180, max=180)‟
#       … the default circular limits are ± 180º but can be modified
myHive.circleCorrection( 189 )                  # Returns -171
myHive.circleCorrection (365, 0, 360)           # Returns 5

# Find the bearing (yaw; relative to north) from one point to a second point
currentLocation = [100, 500, 30]
targetLocation = [400, 800, 180]
myHive.findBearing( currentLocation, targetLocation )            # Returns 45

# Convert radians to degrees or visa versa
myHive.deg( .7071 )                            # Returns 45
myHive.rad( 45 )                               # Returns .7071

The dataStor Class:
The „dataStor‟ class is a flexible data storage object that is useful for organizing groups
of similar variables. For example, the HIVE API stores all of the relevant information
related to a user‟s location in a single dataStor object.

# Creating a dataStor object: A portion of the user location information…
Location = dataStor( physical=[0,0,0, -45,0,0], visualOffset=[0,0,180, 90,0,0], visual=[0,0,180, 45,0,0] )

# Data stored in the Location dataStor can be accessed as follows.
Location.physical                    # Returns the physical location [0,0,0, -45,0,0]
Location.visualOffset =[0,0,0, 0,0,0]        # Sets the visual offset to [0,0,0, 0,0,0]
print Location             # Prints [“physical”:[0,0,0, -45,0,0], “visualOffset”: [0,0,0, 0,0,0]...

# dataStor can hold any type of variable
myData = dataStor( w = True, x = 5, y = „Hello World‟, z = [] )
myData.z.append( 3 )                # Sets z = [3]
myData.w                            # Returns True
myData.x += 3              # Adds 3 to myData.x = 8)

# New attributes can be added to an existing dataStor
myData.add( a=1, b={}, c=‟spam and eggs‟ )
                         VIII. Configuration File Details

****Add documentation later

To top