vrNav2 requires that you create an xml config file for each model you are going to navigate. By convention, you name each model config file modelname.jconf7, where modelname is the name of the model that the xml config file describes. A model config file contains model-specific information, such as the filepath of the model files and texture files, and the filename of the model file. It may also contain other xml elements which override default values and customize vrNav2 for the requirements of that specific model. The available model configuration elements are described in this document.
You run vrNav2 by entering the command:
vrNav2 [vrNav2-options] modelname.jconf7
The file examples/sample.config is a sample config file that you can copy and modify. It includes only the minimum required xml elements to run a model.
The file examples/sample_all.config is a sample config file that includes all the xml elements that are possible to include in a config file for all the optional features. The default values for elements are in the config/vrnavdefinitions/ directory jdef files.
To create a new model config file for vrNav2:
Usually only one model file is included. Normally, in that case, the model is loaded as is and you specify the initial position of the viewer in vrNav's model config file, so that when the model is loaded, the viewer is at the optimum starting position.
When more than one model file is included in the model config file, normally one model is loaded and positioned as is, and the others can be translated, rotated, or scaled independently so that the are placed correctly in the scene in relationship to the first model. In that case, you would would also position the viewer in the scene by specifying the viewer start location in world coordinates.
Those scientific models which have to be positioned with an axis other than Z up (the default) are an exception to this rule. In that case, the model itself has to be rotated.
Each vrNav2 model config file must start with the lines:
<?xml version="1.0" encoding="UTF-8"?>
<?org-vrjuggler-jccl-settings configuration.version="3.0"?>
<configuration xmlns="http://www.vrjuggler.org/jccl/xsd/3.0/configuration"
name="ConfigApp Example Configuration"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.vrjuggler.org/jccl/xsd/3.0/configuration
http://www.vrjuggler.org/jccl/xsd/3.0/configuration.xsd">
<elements>
<vrNavApp name="vrNavApp" version="1">
Do not modifiy these initial lines, as shown above. They must appear exactly as shown.
Provide the initial position of the viewer. Specify it in world coordinates as follows:
<StartLocation>X</StartLocation> <StartLocation>Y</StartLocation> <StartLocation>Z</StartLocation> <StartLocation>H</StartLocation>
Replace X, Y, and Z, with the X,Y,Z starting position of the viewer. +Y is up, +Z is toward the viewer. Replace H with the viewer's heading in degrees.
To figure out what a reasonable starting location might be, start by setting the scale in the Model chunk in the config file to 1.0 and set the X, Y, Z model offsets all to 0.0. For scientific models set the model rotations as required. Then run vrNav2. vrNav2 will print out the model center and radius. To position the viewer at the center of the model, specify a Z equal to the Z of the center of the model. To position the viewer at the edge of the model, replace Z with a value equal to the Z of the center of the model plus the radius. To position the viewer completely outside the model, use a Z that is between one and two radius lengths away from the center.
Y is used to specify the initial height of the viewer's head. Note that, by default, in vrNav, the viewer's head is 1.7 meters above the viewer's feet. For and architectural model, specify a second StartLocation that is 1.7 above the plane of the floor. So for example, if the floor of your model is at 0.0 in world coordinates, specify a starting Y of 1.7.
To center the viewer right to left, use the X of the center as the starting X.
Provide the following xml element to supply the complete file paths to all model and texture files that this model will use.
<FilePath>.:PATH1:PATH2:PATHN</FilePath>
Replace PATH1, PATH2, ...PATHN with the full path of a directory containing model files or texture maps used by this model. Example:
<FilePath>.:/demo/mymodel/models:/demo/mymodel/textures</FilePath>
You must provide at least one Model chunk in your model config file. The Model chunk contains a named Model object, which contains the items shown below:
<Model>
<Model name="MODEL_NAME">
<filename>FILENAME</filename>
<scale>SCALE</scale>
<x>XTRANSLATE</x>
<y>YTRANSLATE</y>
<z>ZTRANSLATE</z>
<rotx>XROTATE</rotx>
<roty>YROTATE</roty>
<rotz>ZROTATE</rotz>
<collidable>COL_VALUE</collidable>
</Model>
</Model>
Replace MODEL_NAME with your name for this model. If you are combining multiple models into a single larger model by providing multiple Model chunks, include multiple Model chunks as follows:
<Model>
<Model name="MODEL_NAME0">
<filename>FILENAME</filename>
<scale>SCALE</scale>
...
</Model>
</Model>
...
<Model>
<Model name="MODEL_NAMEn">
<filename>FILENAME</filename>
<scale>SCALE</scale>
...
</Model>
</Model>
Replace MODEL_NAME with a different name for each model.
Replace each FILENAME with the filename of the model file. The filename must end with .ive, .flt, .osg, .pfb, or another of the file format extensions that vrNav2 can read. If your model has a separate model for each time step, as many scientific simulation model have, replace FILENAME with the name of the first model to be loaded and include the three <timesteps> xml elements. See Section "Time Steps", below.
The <scale>, <x>, <y>, <z>, <rotx>, <roty>, and <rotz> elements are used to scale, translate, and rotate the model in relationship to the viewer. Normally, SCALE will be 1.0 and all the others will be 0.0. It is only if you have to either position a second model file in relationship with the first, or rotate a scientific model that you will need to code something other than these default values.
Replace XTRANSLATE, YTRANSLATE, ZTRANSLATE, and SCALE with float values. Replace XROTATE, YROTATE, and ZROTATE with 0.0 unless the positive Z axis is not up in your model. Otherwise, rotate the model appropriately.
If you are going to load more than one model, each a part of a larger model what you do depends upon how hou have built the individual models. If you built each model at its own location appropriately, then code 0.0 for all three translations. However, if you built all the models without reguard to placement, for example if they all have 0,0,0 going through them, then you must scale, translate, and rotate the model parts in a way that will place each part appropriately in relation to the other parts.
The <collidable> element is used to specify whether collision detection should be on or off for this model. Replace COL_VALUE with:
- 0 or notAtStart
- collision detection is initially off and can be switched during model navigation
- 1 or atStart
- collision detection is initially on and can be switched during model navigation
- 2 or always
- collision detection is always on
- 3 or never
- collision detection is never on
You can specify either the word, (e.g. notAtStart), or the value, (e.g. 0). If the value is 0 or 1 or notAtStart or atStart, then the person navigating through the model can toggle collision detection using one of the keyboard keys.
The default values are 1.0 for <scale>, 0.0 for the translations and rotations, and 0 or notAtStart for collision detection.
A model can be static and fixed or contain the following switchable elements:
- Switches
- show alternate versions of a portion of a model. Activated with the n and p keys.
- Date Switches
- show alternate versions of a portion of a model as historical changes occurred by year. Activated with the i and j keys.
- Time Steps
- usually used for scientific models created from simulation results. With time steps, an entire model for one time step is replace by the model for a different time step. Activated with the u and d keys.
A switch is a group node in a model that selects and shows either one, all, or none of its children. If you have one or more switches in your model, include a Switch chunk for each switch inside of the Model chunk, as shown below.
<Model>
<Model name="MODEL_NAME">
.
.
.
<Switch>
<Switch name="Switch 0">
<SwitchName>SWITCH_NAME</SwitchName>
<InitialState>TF</InitialState>
<InitialMask>START</InitialMask>
</Switch>
</Switch>
</Model>
</Model>
Replace SWITCH_NAME with the name of the switch. This name must be identical to the name that the modeler used for this switch in the model. Each switch has alternative child model segments for the same part of the model. A switch mask is a number that specifies the alternative child model segment to be used. The switch masks run from 0 through n-1, where n is the number of alternative child segments.
Replace TF with 1 or True or 0 or False.
Replace START with the integer mask of the first alternative to be shown.
For switches with an <InitialState> of 1 or True, the alternative with the mask of START will be shown. For switches with an <InitialState> of 0 or False, no alternative will be shown.
With the vrNav GUI interface, you can control all of the switches in all of the models specified in your model config file.
Unless the GUI interface is used, vrNav2 can switch between the alternatives of only one of the switches. Pressing the n or NEXT key to switch to the next mask, or the p or PREVIOUS key to go to the previous mask will switch between only the alternatives of the first switch of the first model specified in your model config file.
A date switch is a switch whose children all show variations in the model according to historic years. Date switches are only useful when there are more than one of them. For example, suppose your model includes a group of 5 buildings, four of which were built in 1280. If one of the four was renovated in 1526 and again in 1863, another in 1720 and the fifth building wasn't built until 1402, placing date switches on those three buildings would allow the user to view the site as it existed: before 1402, between 1402 and 1526, between 1526 and 1720, between 1720 and 1863 and after 1863. By selecting a date, the user would switch all the date switches in the model simultaneously.
Include a DateSwitch chunk for each date switch in your model, inside of the Model chunk as shown below.
<Model>
<Model name="MODEL_NAME">
.
.
.
<DateSwitch>
<DateSwitch name="DATE_SWITCH_NAME">
<DateSwitchName>DATE_SWITCH_NAME</DateSwitchName>
<PhaseDate>DATE1</PhaseDate>
<PhaseDate>DATE2</PhaseDate>
<PhaseDate>DATE3</PhaseDate>
<PhaseDate>DATEn</PhaseDate>
</DateSwitch>
</DateSwitch>
</Model>
</Model>
Replace each DATE_SWITCH_NAME with the name of that particular date switch. This name must be identical to the name that the modeler used for this switch in the model. PhaseDate elements must be in numeric order from oldest to youngest. Replace DATE1, DATE2, ... DATEn with integer values that are the same as the dates included in the model. Code negative numbers for dates that are BCE (BC).
With the vrNav GUI interface, you can control the date switches in multiple models specified in your model config file, if you have more than one.
Unless the GUI interface is used, vrNav2 can switch only between the dates in the first model. Pressing the i key to switch to the next date or the j key, to go to the previous date will switch between only the alternatives of the first date switch of the first model specified in your model config file.
Scientific models often have one model file per time step. If your model config file is for a model of this type, include the following lines in the <Model> chunk:
<Model>
<Model name="MODEL_NAME">
<filename>FILENAME</filename>
.
.
.
<TimeStep>
<TimeStep name="Timestep0">
<FileBase>FILE_NAME_BASE</FileBase>
<FileExt>EXT</FileExt>
<FileStart>START</FileStart>
<FileEnd>END</FileEnd>
</TimeStep>
</TimeStep>
</Model>
</Model>
Replace FILE_NAME_BASE with the base of the file names containing the models. Replace EXT with the file name extension and START and END with the starting and ending numbers. For example, if your model files are named: density.1001.ive through density.1100.ive, replace FILE_NAME_BASE with density., EXT with ive, START with 1001 and END with 1100.
Replace FILENAME in the <filename> element of the <Model> chunk with the file name of the first time step to be loaded.
The config file for the model must end with:
</vrNavApp>
</elements>
</configuration>
The drive height is the height of the navigator's head above the ground, floor, or steps, etc. to which all navigation is constrained in drive mode. The default is 1.7 meters, which is approximately five and a half feet.
Code the following xml element to specify the drive height in meters:
<DriveHeight>HEIGHT</DriveHeight>
Replace HEIGHT with the float value.
For the MouseNavigator, code as follows:
<MinimumSpeed>MIN</MinimumSpeed> <MaximumSpeed>MAX</MaximumSpeed> <AccelerateFactor>FACTOR</AccelerateFactor>
Replace MIN and MAX with speeds in terms of the world coordinates of your model space. Replace FACTOR with an number between 0 and 1. When you are going fast enough, your velocity will be increased by FACTOR * current velocity each time you press (or hold) the left mouse button.
When starting from stopped, each time you press the left mouse button, your speed will be increased by MIN. This will happen 1/FACTOR times. After that, your speed will be increased by FACTOR * current velocity until you have obtained a speed of MAX, after which you cannot increase your velocity further. That is, your velocity curve will be linear until a velocity of FACTOR * MIN is obtained. Then it will be exponential. This allows for the navigation of very large models which have very fine detail of interest in places. You can speed through the large places but navigate in close to the large detail. Likewise, deceleration from a large velocity, will be exponential but from a small one will be linear. Holding down the mouse button is equivalent to repetedly pressing it.
The default FACTOR is .08.
The vertical rate is used when you step left, right, up, or down (with the arrow keys). Again, the optimal step rate is dependent on model size and whether the model has been scaled. The default vertical rate is 3.0. You can add the following element to the model config file to customize the vertical rate for your model:
<VerticalRate>RATE</VerticalRate>
Replace RATE with the desired float value.
A Jump Point is a named location that the user can jump to when navigating the model. Jump Points can be supplied in a separate JumpPoints config file or in the model config file (outside of the Model element).
The best way to create Jump Points is to use the vrNav2 GUI to set and save them. The vrNav2 GUI will create Jump Points for you under its Jump tab. It allows you to navigate to a point in the model and then associate your current position/orientation with a name. It will save all the Jump Points you set, including their names and coordinates in a separate JumpPoints config file that it will creates for you.
Following is the format of the JumpPoints config file:
<?xml version="1.0" encoding="UTF-8"?>
<?org-vrjuggler-jccl-settings configuration.version="3.0"?>
<configuration xmlns="http://www.vrjuggler.org/jccl/xsd/3.0/configuration"
name="ConfigApp Example Configuration"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.vrjuggler.org/jccl/xsd/3.0/configuration
http://www.vrjuggler.org/jccl/xsd/3.0/configuration.xsd">
<elements>
<JumpPoints version="1">
<JumpPoint>
<JumpPoint name="JUMP_POINT_NAME">
<x>X</x> <y>Y</y> <z>Z</z>
<h>H</h> <p>P</p> <r>R</r>
</JumpPoint>
</JumpPoint>
.
.
.
</JumpPoints>
</elements>
</configuration>
You can copy the Jump Points from the separate JumpPoint config file and place them in your model config file. Just copy any Jump Points you want starting with <JumpPoint> and ending with the closing </JumpPoint>. Place the Jump Points in your model config file between <NavApp name="vrNavApp" version="1"> and </vrNavApp> and outside of <Model>, <Map> or any other compound element. Make sure not to copy the </JumpPoints> (with an s on the end) line as that line does not appear anywhere in the model config file. For example, if you add a Jump Point between the last <Model> element and the end of the model config file it would look like this:
.
.
.
</Model>
</Model>
<JumpPoint>
<JumpPoint name="JUMP_POINT_NAME">
<x>X</x> <y>Y</y> <z>Z</z>
<h>H</h> <p>P</p> <r>R</r>
</JumpPoint>
</JumpPoint>
.
.
.
</vrNavApp>
</elements>
</configuration>
The turning rate is used when turn left or right, up or down. Again, the optimal step rate is dependent on model size and whether the model has been scaled. The default turning rate is 1.8 and the maximum turning rate for which the rate increases when the mouse is at the edges of the screen is 6.8. If your TurningRate is greater than that, small movements of the pointer will cause greater turning but at some distance from the center of the screen, the turning cannot be increased. You can specify the TurningRate by adding the following element to the model config file to customize the turing rate for your model:
<TurningRate>RATE</TurningRate>
Models can be covered with texture maps or models can have no texture maps at all. Models with no texture maps lack definition unless OpenGL lighting is enabled. This can be done by including the -light vrNav2 argument when vrNav2 is started or you can press the L key or enable lighting via the vrNav2 GUI once the model is running.
The vrNav2 GUI includes a Lights tab. When OpenGL lighting is enabled, you can use the controls on the Lights tab of the GUI to modify the ambient and diffuse color of the sun that lights the scene and also to change its direction.
You can include the following xml in the model config file for the model to set specific lighting conditions on model startup:
<Lights>
<Lights>
<Sun>
<Sun>
<Ambient>RA</Ambient>
<Ambient>GA</Ambient>
<Ambient>BA</Ambient>
<Diffuse>RD</Diffuse>
<Diffuse>GD</Diffuse>
<Diffuse>BD</Diffuse>
<Direction>X</Direction>
<Direction>Y</Direction>
<Direction>Z</Direction>
</Sun>
</Sun>
</Lights>
</Lights>
Within the <Sun> chunk, any of the <Ambient>, <Diffuse> or <Direction> elements are optional. Replace RA, GA, and BA with the sun's ambient red, green and blue values, between 0.0 and 1.0. Replace RD, GD, and BD with the sun's diffuse red, green, and blue values, between 0.0 and 1.0. Replace X, Y, and Z with the sun's directional value between 0.0 and 1.0. This is a unit vector (normal). If the values are not normalized, they will be normalized for you by vrNav2. If all of X, Y, and Z are 0.0, which is not allowed (as it is a vector of length 0.0), the sun direction (0.0, 1.0, 0.0) will be used instead.
The Text Logo is some text that you can position anywhere on the screen or on one of the screens of a tiled display. The Text Logo is superimposed on top of the model being displayed.
To display a Text Logo place the following chunk in the model config file.
<Logo>
<Logo>
<Text>TEXT_LOGO</Text>
<Font>FULL_PATH_TO_FONT</Font>
<Pipe>PIPE</Pipe>
<VisibleAtStart>TF</VisibleAtStart>
<Color>RED</Color>
<Color>GREEN</Color>
<Color>BLUE</Color>
<Color>ALPHA</Color>
<ShadowColor>RED</ShadowColor>
<ShadowColor>GREEN</ShadowColor>
<ShadowColor>BLUE</ShadowColor>
<ShadowColor>ALPHA</ShadowColor>
<Outline>TF</Outline>
<FontHeight>DECIMAL</FontHeight>
<AspectRatio>ASPECT_RATIO</AspectRatio>
<X>NORMALIZED_X</X>
<Y>NORMALIZED_Y</Y>
<Layout>LAYOUT</Layout>
<TextPositionAtX>TEXTX</TextPositionAtX>
<TextPositionAtY>TEXTY</TextPositionAtY>
<Wrap>DECIMAL</Wrap>
</Logo>
</Logo>
Replace TEXT_LOGO with the text that you want to display.
Replace FULL_PATH_TO_FONT with the full path to the font file for the text. Several font files (the ones from OpenSceneGraph) are distributed with vrNav2 and can be found in the fonts subdirectory or you can supply a different font file. If you omit the Font element, your text will be displayed in a rather blocky font.
The Pipe element is used ONLY for tiled displays. It is ignored otherwise. For a tiled display, replace PIPE with 0 to have the Text Logo display on the control unit. To have the Text Logo display on a tile, replace PIPE with the number of the tile you want to use for the Text Logo plus 1. The tile number is the number specified in the -tile option for that tile when you started vrNav on it. For example, to have the Text Logo displayed on tile number 1, replace PIPE with 2.
Replace V with true or false depending on whether the Text Logo should be visible when vrNav2 starts up. The default is to show the Text Logo if a Logo chunk is included in the config file.
Replace RED, GREEN, BLUE and ALPHA with a rgb color where 0.0 is the absence of a color and 1.0 signifies full strength. Code ALPHA as 1.0 if you want the text to be opaque, and ALPHA as 0.0 if the text is to be completely transparent (invisible).
The text can be displayed as plain text, outlined, or with a drop shadow. The default is to display plain text. For outlined text, code the Outline element and replace TF with true. For a drop shadow code the four ShadowColor elements. If you both request an outline and code the ShadowColor elements, your text will be outlined.
The FontHeight element specifies the height of the the font. FontHeight includes the space between lines as well as the height of the letters themselves. Replace DECIMAL with a FontHeight specified in fraction of screen height. This should be a number between 0.0 and 1.0. The number you specify will be multiplied by the number of pixels in the screen height to compute the font height in pixels.
Use the AspectRatio element to specify the aspect ratio of the characters. The default aspect ratio is 1.0, i.e., the characters will be about as wide as they are high. Since character widths depend on the characters, individual character widths will vary. Character height is fixed by the FontHeight element. AspectRatios other than 1.0 adjust character widths and leave the height unchanged. Specifying an AspectRatio between 0.0 and 1.0 will result in characters that are wider than they are high. Specifying an AspectRatio greater that 1.0, for example 1.5, will result in narrower characters.
Use the X and Y tags to specify where the text should be placed on the screen. Replace NORMALIZED_X with a number between 0.0 (left edge of the screen) and 1.0 (right edge of the screen) and NORMALIZED_Y with a number between 0.0 (bottom edge of the screen) and 1.0 (top edge of the screen).
Code the Layout tag to specify the text direction. Replace LAYOUT with either leftToRight (horizontal) or topToBottom (vertical). leftToRight is the default if the Layout element is omitted.
The appearence and placement of the text block is controlled by the TextPositionAtX, TextPositionAtY and Wrap elements. If omitted, the default is to place the left justify the text at X with the text centered top to bottom around the Y position. Replace TEXTX with one of: leftJustified, rightJustified or centered. Replace TEXTY with one of:
- topAtY
- The tops of the upper-case letters will be at the position specified by Y.
- bottomAtY
- The bottoms of the extenders on letters like j and g will be at the position specified by Y.
- centerAtY
- The centers vertically of the letters will be at the position specified by Y.
- baseLineAtY
- The base line of the letters will be at the position specified by Y.
If you include the Wrap element and the text is long enough that it would continue past the distance you specify, the text will be broken at blanks and wrapped into multiple lines (if horizontal) or columns (if vertical). Replace DECIMAL with a fraction of the screen. For example, if X is at .2 (from the left edge) and you replace DECIMAL with .6, then the text will extend approximately to .8 (i.e., to within .2 of the right edge of the screen).
When the text is Wrapped, the function of TextPositionAtX and TextPositionAtY changes its meaning. For example, if the text layout is leftToRight and TextPositionAtY is bottomAtY and the text is broken into 3 lines, then the bottom of the bottommost line will be at Y.
A map is a map of the model that is shown in a small window superimposed on the scene being navigated. A small red marker marks your current location and points in the direction in which you are moving. It is useful to have a map especially if you have a large model. Having a map lets you know where you are in the model as you navigate around in it, and helps prevent you from getting lost.
There are 2 types of maps that can be constructed:
- TopView Map
- A map constructed by vrNav2 itself, automatically from the model being navigated.
- Imag Map
- A map provided by the modeler in the form of an image.
The format of the Map chunk is as follows:
<Map>
<Map name="Map">
<Pipe>PIPE</Pipe>
<ViewportLeft>LEFT</ViewportLeft>
<ViewportRight>RIGHT</ViewportRight>
<MapType>TYPE</MapType>
<VisibleAtStart>V</VisibleAtStart>
<PointerWidthFactor>WIDTHFACTOR</PointerWidthFactor>
ADDITIONAL ELEMENTS
</Map>
</Map>
The Pipe element is used ONLY for tiled displays. It is ignored otherwise. For a tiled display, replace PIPE with 0 to have the map display on the control unit. To have a map display on a tile, replace PIPE with the number of the tile you want to use for the map plus 1. The tile number is the number specified in the -tile option for that tile when you started vrNav on it. For example, to have the map displayed on tile number 1, replace PIPE with 2.
Replace LEFT and RIGHT with floating point numbers that specify the normalized left and right extents of the map on the display. 0.0 is at the left edge of the display and 1.0 is at the right edge.
Replace TYPE with 1 for a TopView Map, 2 for an Image Map. 1 is the default if the <MapType> element is omitted.
Replace V with 0 or false or 1 or true depending on if the map should be visible when vrNav2 starts up. The default is to show the map if a Map chunk is included in the config file.
Code the PointerWidthFactor tag if you want to control the size of the pointer that is displayed on the map to indicate your position. Replace WIDTHFACTOR with a number between 0 and 1. A width factor of 1 would give you a pointer that is as wide as the entire map. The default is 0.08.
ADDITIONAL ELEMENTS are as follows:
<ViewportTop>TOP</ViewportTop>
OR:
<ViewportBottom>BOTTOM</ViewportBottom>
Replace TOP or BOTTOM with the floating point number that specifies the normalized top OR bottom extent of the map on the display. 0.0 is at the bottom edge of the display and 1.0 is at the top edge.
vrNav2 will figure out the other map edge, either TOP OR BOTTOM that will make your map the same aspect ratio as your model for a TopView Map or the portion of your image that contains your map for an Image Map.
For a TopView Map only, if the model is unusually long or wide, you can ask vrNav2 to pad your map by specifying both ViewportTop and ViewportBottom and including:
<PadMap>PAD</PadMap>
Replace PAD with 1 or true. In that case, vrNav2 will center the model so it fits exactly between LEFT and RIGHT and pad the map with blank space top and bottom if the aspect ratio of the model is such that it won't extend from TOP to BOTTOM. If the model is two large to fit between TOP and BOTTOM, it will be cut off on the map.
<MapHeight>HEIGHT</MapHeight>
The map will be a top view of the model as viewed from HEIGHT above ground.
<MapFile>FILENAME</MapFile>
Replace FILENAME with the full path of the image file containing your Map. The width and height of the image must each be a power of 2 pixels.
<PercentOfImage>PERCENTX</PercentOfImage> <PercentOfImage>PERCENTY</PercentOfImage> <MapDimension>LLX</MapDimension> <MapDimension>LLY</MapDimension> <MapDimension>URX</MapDimension> <MapDimension>URY</MapDimension>
If the map is smaller than the image named by FILENAME, since the image must have a power of two number of pixels in each of its X and Y directions, place the map in the lower left of the image and fill the rest with any color. PERCENTX is the percent of the image file occupied by the map in the X direction (width); PERCENTY is the percent of the image file occupied by the map in the Y direction (height). If the map occupies the entire image, replace PERCENTX and PERCENTY each with 100.
The map should be oriented parallel to the axes in model space world coordinates with north at top. Replace LLX, LLY with the x and y coordinates, in model space, of the Lower Left corner of the map. Replace URX, URY with the x and y coordinates of the Upper Right corner of the map.
For the bird's eye view, include the following:
<BirdViewHeight>HEIGHT</BirdViewHeight> <BirdViewAngle>ANGLE</BirdViewAngle>
Replace HEIGHT with the height above the ground for the bird's eye view position. Default height is 100.0 meters. Replace ANGLE with the angle between the ground and the path on which to rise. Default angle is 45.0 degrees.
Astronomical Objects can be added to the model by including the AstronomicalObjects chunk in the model config file. Currently only the sun is supported.
<AstronomicalObjects>
<AstronomicalObjects name="AstronomicalObjects">
<TimeZoneOffset>TZ</TimeZoneOffset>
<LatitudeSign>SIGN</LatitudeSign>
<LatitudeDegrees>DEGREES</LatitudeDegrees>
<LatitudeMinutes>MINUTES</LatitudeMinutes>
<LatitudeSeconds>SECONDS</LatitudeSeconds>
<LongitudeSign>SIGN</LongitudeSign>
<LongitudeDegrees>DEGREES</LongitudeDegrees>
<LongitudeMinutes>MINUTES</LongitudeMinutes>
<LongitudeSeconds>SECONDS</LongitudeSeconds>
<ModelYOffsetFromNorth>DEGREES</ModelYOffsetFromNorth>
<SunTexture>PATH/FILE.rgb</SunTexture>
<Ephemerides>
<Ephemerides name="NAME_FOR_THIS_DATE">
<Sun>BOOL</Sun>
<SunPath>BOOL</SunPath>
<SunTimeSequence>BOOL</SunTimeSequence>
<SunPathWidth>PATHWIDTH</SunPathWidth>
<VisibleAtStart>TF</VisibleAtStart>
<Month>MONTH</Month>
<Day>DAY</Day>
<Year>YEAR</Year>
<Hours>HOUR</Hours>
<Minutes>MINUTE</Minutes>
<Seconds>SECOND</Seconds>
</Ephemerides>
</Ephemerides>
.
.
<Ephemerides>
<Ephemerides name="NAME_FOR_THIS_DATE2">
<Sun>BOOL</Sun>
<SunPath>BOOL</SunPath>
<SunTimeSequence>BOOL</SunTimeSequence>
<SunPathWidth>PATHWIDTH</SunPathWidth>
<VisibleAtStart>TF</VisibleAtStart>
<Month>MONTH</Month>
<Day>DAY</Day>
<Year>YEAR</Year>
<Hours>HOUR</Hours>
<Minutes>MINUTE</Minutes>
<Seconds>SECOND</Seconds>
</Ephemerides>
</Ephemerides>
</AstronomicalObjects>
</AstronomicalObjects>
Code the latitude and longitude for the location of your model.
Replace PATH/FILE.rgb with the name of your sun texture file. You must have a texture for the sun. You can use the ones in the examples directory if you do not have your own.
We assume that the main Y axis of the model is pointing due north. If not, supply the number of degrees that the Y axis of the model deviates from north in the <ModelYOffsetFromNorth> element.
Code one Ephemerides chunk for each date/time.
The SunPath element adds a curved line showing the sun's path. The SunTimeSequence elements adds multiple suns spaced along what would be the sun's path.
<Ephemerides>
<Ephemerides name="Spring 2004">
<Sun>1</Sun>
<SunPath>1</SunPath>
<SunTimeSequence>1</SunTimeSequence>
<SunPathWidth>PATHWIDTH</SunPathWidth>
<VisibleAtStart>TF</VisibleAtStart>
<Month>03</Month>
<Day>20</Day>
<Year>2004</Year>
<Hours>06</Hours>
<Minutes>49</Minutes>
<Seconds>00</Seconds>
</Ephemerides>
</Ephemerides>
You can ask vrNav to automatically supply a blue sky. To turn on the sky, add the following line outside of the <Model> chunk:
<EarthSky>1</EarthSky>
To turn on the UTM coordinate display in the vrNav2 GUI, code the following in the model config file:
<UTM>
<UTM>
<Easting>EAST</Easting>
<Northing>NORTH</Northing>
</UTM>
</UTM>
Replace EAST with the UTM easting of the (0,0,0) position of your model in model space. Replace NORTH with the UTM northing of the (0,0,0) position of your model.
Currently Model Feature Informative URL Links are not availavle in vrNav2osg.