IENASA Software Releases
Overview
This page outlines changes, bug fixes, and new features in each release of IENASA software. This page serves as user documentation for the latest IENASA software.
If you want a more detailed log of what has changed, you can view the change log.
Running inspect
inspect can be run by executing:
/pub/research/ienasa/releases/$RELEASE/inspect
Where $RELEASE is the number of the release as found below. For example, to run release 20040927-01, execute:
> /pub/research/ienasa/releases/20040927-01/inspect
If you simply wish to run the latest release, execute:
> /pub/research/ienasa/releases/latest/inspect
User Data Location
Users can specify data in one of two places. The first location is the global share directory:
/pub/research/ienasa/releases/share
This directory is accessible by anyone within the IENASA project. If you place files in this directory you risk those files being edited or deleted by other IENASA users. Place files in this directory only if you wish to share your environments with other users.
The second place to store data is in:
$HOME/.ien
Where $HOME is your home directory (such as /users/andrewd). This directory is not accessible by other IENASA users. You can safely place your data files here without having to worry about other users accessing or editing your environments. Place data in $HOME/.ien if you do not wish to share your data with other IENASA users.
Data Structure
Data can be placed in any of the above directories in the following sub directories:
env/
env.obj
env.mtl
defect.obj
hull.obj
models/
bindings.cfg
client.cfg
Of the above directories, only the env directory is of importance. Subdirectories of the env directory contain environment related data. For instance, env/calib contains the "calibration" scenario. Within each sub-directory of the env directory, IENASA software looks for files with specific files names. IENASA software recognizes the following files:
| env.obj | The environment's geometry data. |
| defect.obj | The environment's defect data. |
| hull.obj | This object stores a low resolution mesh used by IENASA software to perform collision detection within the environment. |
| lights.cfg | Contains light position and color information. |
IEN-20050307-01 (ien--mainline--0.1.0--patch-34)
This release marks the first build of ien capable of being delivered to Greenville Tech. Almost all goals for the GT release have met.
inspect Improvments
Data Recording
Data recording is now fully functional. Data is recorded at 30Hz (this can be changed with cvars). To begin recording, press F1.
IMPORTANT: In order for the new key bindings to take affect you must delete $HOME/.ien/ubindings.cfg with:
> rm -f $HOME/.ien/ubindings.cfg
Time Limit
inspect now honors the time limit sent from the launcher. The time limit countdown begins when F1 is pressed (i.e. recording is started). When the time limit has been exceeded, recording is automatically stopped and a message is displayed on the screen.
New Console Variables
| recordTimeLimit | Maximum number of milliseconds recording can last. Once this limit has been reached, recording is stopped. |
launcher Improvments
Most of the launcher's interface has been unlocked and is fully functional. The single exception is the "Display Time Limit" checkbox.
Post Trial Report (ptr)
ptr is a new GUI program intended to replace vspec. ptr is currently capable of automatically finding recorded trial data on the file system which it can then analyze and display. Currently, ptr is not able to display any 3D geometry or scanpaths.
ptr can be executed with:
> /pub/research/ienasa/releases/latest/ptr
IEN-20050222-01 (ien--mainline--0.1.0--patch-31)
This is a huge release with many bugfixes and new features. Below is an overview on what has changed. For full details refer to the change log.
Launcher
The flashlight option is now available in the launcher. We've also added checks to make sure that user selects a sane set of options.
The launcher is fully functional in this release. Pressing the "Launch" button executes with inspect with the selected options.
FOB Mouse Selection
Defects can now be selected using the FOB mouse. By default, the FOB mouse's right button is used to select defects. The selection system only works if the given environment has a "defects.obj" file defined.
Pointer Device Selection
Since multiple input modes for selecting defects are now supported, we should note how ien decides which input device to listen to. If the FOB mouse is enabled (flying) ien will accept selection requests from it. Otherwise, the desktop mouse will be used for selection (which is compatiable with the WindowVR device).
Flashlight
This is the first release with flashlight support. Flashlights are enabled with the launcher or by the flashlightEnabled cvar. The shape of the flashlight can be changed by changing the flashlight texture with the flashlighttexture command. By default "flashlight.png" is used. Other options include "spotlight.png" and "rgbtrans.png". This texture can be user defined by adding your custom greyscale image to "~/.ien". The size of the flashlight can be controlled with flashlightFOV.
There are many cvars to tweak flashlight rendering. See the change log for details.
New Flashlight Console Variables
| flashlightEnabled | Globally enables/disables flashlight rendering. |
| flashlightFOV | Field of view used when creating the flashlight projection matrix. Value should be between (0.0-90.0). Larger values result in a larger flashlight area. |
| flashlighttexture | If no arguments are passes, returns the name of the current flashlight texture. If a filename is passed, sets the flashlight's texture to the filename given. |
Shadows
Environment lights and flashlights casts shadows. There are many cvars to play with to change the shadowing behaviour. See the change log for details.Improved Rendering
The rendering algorithm in inspect has changed in order to account for flashlight, env lights, and shadows. It's important to understand how the rendering algorithm works to achieve good performance when creating scenarios. The algorithm is essientially:
if( flashlightEnabled or Environment has shadow casting lights ) {
//first pass
render environment with ambient material
//second pass
render environment with specular and diffuse material
//numClient * 2 passes
foreach client {
//pass 4
render shadow map from client's flashlight
//pass 5
project flashlight tex onto env
render environment with specular and diffuse material
}
//numEnvLights * 2
foreach light {
//pass 6
render shadow map from light's flashlight
//pass 7
project spotlight tex onto env
render environment with specular and diffuse material
}
} else {
//single pass
render environment with ambient, diffuse, and specular light
}
As you can see from above, the number of lights in the scene (via "lights.cfg") and the number of flashlights in the scene (1 for each connected client), directly affects the number of passes, thereby affecting rendering time. More lights in the environment and more connected clients equals decreased performance. For instance, a scene with 4 shadow casting lights, and two connected clients while using the HMD must render the scene 28 times vs. the 2 passes with the old rendering code.
Due to the increase in the number of rendering passes per frame, prior rendering methods were inadequate. Rendering speed has been greatly improved by utilizing OpenGL's vertex buffer object (VBO) interface. VBO is detected at runtime and enabled if possible.
Lighting
The materials and light locations in the "env" and "calib" environments have been updated to take advantage of the new rendering code.
The "lights.cfg" file format has changed. The format is now:
| Position | 3 floating number (x y z). |
| Color | 3 floating point numbers (r g b). |
| Direction | Direction in which to point the light. This vector does not have to be normalized. |
| Cast Shadows? | Either 0 or 1. If 1, the light will casts shadows. If 0, the light will not casts shadows. |
| Spotlight Angle | A value between (0-90). This number is multipled by 2 to set the angle of the light cone in the direction the light is pointing. The larger the number, the more area the light will cover, but shadow quality will degrade. |
Each of the above fields should be collapsed to a single line. There can be no empty lines or comments in the file (if this is needed I can put it in). See "env/bay/lights.cfg" for an example.
When adding lights to the scene, light locations and directions can be visualized with:
| showLights | If true, renders spheres at the location of each light. Shadow casting lights are orange and are rendered with a direction vector. Non-shadow casting lights are green. |
IEN-20041118-01 (ien--mainline--0.1.0--patch-17)
Launcher
The graphical launcher has finally made its triumphant debut. You'll notice that some options are disabled, mainly "Timed Search" and "Pointer Display". These options are disabled in the launcher because ien does not yet fully support these features. This options will be enabled in the near future.
New Launcher Console Variables
| userid | The system login name of the user executing the program. |
Automatic Scenario Conversion
Old environments created for inspector can now be loaded in ien. In order for an old environments to be loadable by ien, the user must symlink the environment's geometry object file (usually named after the scenario name) to the filename "env.obj". For instance, if you wish to be able to load the old "calib" scenario, you must run the following in the "calib" directory:
> ln -s calib.obj env.obj
This command only needs to be run once.
ien and inspector operate at 2 different scales. As a result, data output by ien is currently not in the same scale as data output from inspector. We are unsure of the impact on vspec at this time but plan to address this issue in the near future.
Pausable Timers
Timers can now be paused/unpaused with the "timerpause", "timerunpause", and "timertoggle" commands. Of the three commands "timertoggle" is the most useful. If you would like to bind pausing to a key (for instance the PAUSE key) type:
> bind PAUSE "timertoggle scenario"
New Timer Console Commands
| timerpause | Given a timer name, pauses the timer. |
| timerunpause | Given a timer name, unpauses the timer. |
| timertoggle | Given a timer name, toggles if the timer is paused or not. |
2D Defect Selection
Defects can now be selected by left clicking the mouse (the desktop mouse, not the fob mouse).
This means that selecting defects on the WindowVR should be possible. Unfortunately, we are still waiting for the proper drivers to be installed on jet.vr that allow screen touches to be translated into mouse clicks.
In the meantime, this feature can be tested by simply left clicking at random. The location of the clicks may seems sporadic, but by running:
> showMouse 1
one can see the mouse cursor (thereby explaining the sporadic click behaviour). Don't worry, selecting defects will work as expected (i.e. simply touching the screen) when the WindowVR is properly working.
New Defect Selection Console Commands
| defectsintersectmouse | Attempts to select the defect at the last recorded pointer down location. Regardless if a defect was hit or not, the intersection test will be internally recorded (unless the test fails to hit the environment). |
New Defect Selection Console Variables
| showMouse | If true, displays the mouse pointer at all times. |
Data Recording/Output
This releases adds facilities to record and output data generated within ien. The launcher and vspec should hide how most of these facilities work. For the curious user, please look at the documentation for the commands and cvars prefixed with "record" below.
At this time ien output datas in a format easily readable by humans. The outputted data is not recognizable by vspec. We will be addressing this issue in the near future.
New Data Recording Console Commands
| recordStart | Starts recording. |
| recordStop | Stops recording. |
| recordDirectory | Sets the recording base directory. |
| recordFile | Sets the master recording file. |
| recordRate | Set the number of times a second data is recorded. |
New Data Recording Console Variables
| recording | If true, data is being recorded. |
| recordAppend | If true, data will be appending to existing data files upon recordStart. |
| recordCameraFile | File to which to record camera data. |
| recordDefectsFile | File to which to record defect selection data. |
IEN-20041013-01 (ien--mainline--0.1.0--patch-9)
Trial Time
Trail time is now recorded within ien. To view the current trial time, track the cvar timerScenario:
> track timerScenario
New Time Related Console Variables
| timerProgramMsec | Milliseconds the program has been running. |
| timerProgram | Time the program has been running, in HH:MM:SS format. |
| timerScenarioMsec | Milliseconds the scenario has been running. |
| timerScenario | Time the scenario has been running, in HH:MM:SS format. |
Defect Rendering/Loading
It is now possible to load defect files within ien. When loading a scenario, ien will attempt to load a file called "defect.obj" within the scenario's data directory.
At this time there is a scale discrepancy between the old "inspect" defect files and ien's new defect files. When loading defect files, ien attempts to correct these errors. Loading "inspect" scenarios should work, but has not been fully tested.
The cvar "defectsShowAll" is useful when debugging if defects are in their correct locations. Setting "defectsShowAll" to non-zero will cause all defects to be rendered.
Another useful method to debugging defect placement is to disable collision detection with the environment. This allows the user to move outside of the environment and check if any defects are hidden behind the scenario's geometry. One can disable collision detection with the command:
> sv clip 0
New Defect Rendering/Loading Console Variables
| defectsShowAll | If true renders all defects (for debugging). |
| defectsOffsetFactor | Controls the factor for glPolygonOffset. |
| defectsOffsetUnits | Controls the units for glPolygonOffset. |
| defectsShowSelected | If true renders all selected (hit) defects. |
| defectsSelectedColor | RGB color for selected (hit) defects |
| defectsSelectedAlpha | Transparency of selected (hit) defect. |
| defectsShowClicks | If true renders small spheres where the tried to select a defect. |
| defectsClickColor | RGB color of the sphere that represents defect clicks. |
| defectsClickSphereRadius | Radius of the rendered click spheres. |
| defectsClickSphereResolution | Resolution of the rendered click sphere. The higher the better the spheres will look. |
| defectsFound | Number of defects successfully clicked. |
| defectsMissing | Number of defects currently not clicked. |
Mouse Tracking
Mouse position is now tracked within ien. This new code is the first step being able to select defects within the scene.
New Mouse Related Console Variables
| pointerX | The current X position of the pointer. |
| pointerY | The current Y position of the pointer. |
| pointerDownX | The X coordinate of the pointer when the last button press was recorded. |
| pointerDownY | The Y coordinate of the pointer when the last button press was recorded. |
New Miscellaneous Console Vars
| clip | Server side cvar. If true, collision detection will be performed against other user's and the environment. Note that this cvar affects all connected clients. |
IEN-20041004-01 (ien--mainline--0.1.0--patch-6)
jet.vr Flock of Bird Fixes
The flock of birds on jet.vr should now work properly. The pin settings on the flock seem to have been changed in the move to McAdams. Also, the flock switched serial ports during move.
IEN-20040927-01 (ien--mainline--0.1.0--patch-5)
Joystick Support
Added joystick support. If a joystick is present, it will be automatically detected and any events sent from the joystick will be processed. Only 1 joystick and four buttons are supported at this time. The following key symbols can be bound to: JOY_UP, JOY_DOWN, JOY_RIGHT, JOY_LEFT, JOY1, JOY2, JOY3, JOY4.
For example, to bind moving forward to up on the joystick axis:
> bind JOY_UP "+forward 0"
By default the joystick axis' are bound to move the user. The joystick buttons currently do not have default bindings.
Custom User Settings
client.cfg and bindings.cfg are no longer written to the user's profile directory. uclient.cfg and ubindings.cfg are now written to the user's profile directory at program exit and are loaded at run-time after client.cfg and bindings.cfg are loaded. This allows us to add system level key bindings and cvar definitions and ensure that those system level keybindings and cvars are loaded.
User's profile directory is now "$HOME/.ien", not "$HOME/.inspect". This is to avoid issues with old client.cfg and binding.cfg files laying around.
"inspect" will now add "/pub/research/ienasa/releases/share" to the virtual file system. Note that this directory is added after "./data" and before "$HOME/.ien".
New Console Variables
Added the cvar warnRebind. When set to true (the default), any key that is rebound will produce a warning message containing the keys previous binding. Note this is the behaviour we have expected in the past. ubindings.cfg sets this cvar to 0 to avoid warning spam on the console when ubindings.cfg is loaded.
Added version and build cvars. version contains the ien version (such as 0.1.0). build contains the date the executable was built. To view either cvar, simply bring down the console with the "`" key and type the name of the cvar.