| The Java 3D Configuration File |
This document is an informal description of the syntax of the Java 3D configuration file and a tutorial of the semantics of its various commands. Such a file is written by a user or site administrator to describe the physical configuration of a local interactive viewing environment. Configuration properties that can be described in the file include the sizes, positions, and orientations of displays in either fixed screen environments or head mounted displays (HMD devices), as well as the input devices and sensors available for user interaction apart from the keyboard and mouse abstractions provided by the AWT.
A configuration file is used by passing its URL to either a ConfigContainer or a ConfiguredUniverse constructor. The method by which a user specifies the file is up to the application, but the universe utilities do provide a few means to easily enable an application to perform this task. These depend upon a Java 3D property, j3d.configURL, that the user can set on the java command line with the -D option. Its value should be a URL string indicating the location of the desired file. The application can then either call the static ConfigContainer methods getConfigURL to retrieve the value of the property, or getConfigURL(String) to specify a default file to be used in case the property is not set. Applications are encouraged to devise their own user-friendly mechanisms to retrieve the configuration file, although the setting of the j3d.configURL property should be honored if at all possible.
If the attempt to open the resource indicated by the URL is successful, then a parser will be invoked to read and evaluate the commands it contains and deposit the results in the ConfigContainer. The parser will detect syntax errors, invalid commands, and bad references, printing descriptive messages to System.out, including the line number and text of the offending command. In general the parser attempts to continue processing as much of the file as it can when encountering an error. Some errors can only be detected after the entire file has been evaluated; in those cases an exception will be thrown.
An application may choose to override the settings of the configuration file by accessing view-side scenegraph components directly from the ConfigContainer once the file is evaluated. Applications should avoid this in general, as most settings are physical calibration constants specific to the local interactive viewing environment. Nonetheless, application overrides are still sometimes appropriate; for example, the application may have knowledge of the contents of the scenegraph that enables it to make a better judgement of where the view's clipping planes should be.
| Syntax Description |
The configuration file syntax is very simple; scanning any of the sample configuration files should provide the general idea. At the broadest level there are two main types of constructs: comments and commands.
Comments can be either C or C++ style. In a C-style comment all text between successive occurances of /* and */ is ignored. A C++ comment begins with // and continues to the end of the line.
A command begins with an opening parenthesis and ends with a closing parenthesis. The elements between the parentheses can be of four types: alphanumeric strings, numbers, quoted strings, or other commands. During the evaluation of a command, any nested command encountered is itself evaluated, and the result of that evaluation replaces the nested command within the original outer command.
Strings that contain embedded white space, forward slashes, or invalid tokens must be enclosed in quotes (either single or double). Common cases are URL strings and Unix path names. Numbers are any non-quoted strings that can be parsed as double-precision floating point numbers. The strings true, True, false, and False are converted to their corresponding boolean values. Strings, quoted strings, and numbers are delimited from each other by white space.
Commands in the configuration file have four special forms: point, matrix, top-level, and built-in commands.
Points
A command that consists entirely of two, three, or four numbers is a 2D point, a 3D point, or a 4D point respectively. Any other command that starts with a number is a syntax error.Don't pass 2D, 3D, or 4D points to commands that expect two, three, or four numbers instead. This will generate a syntax error indicating an invalid number of arguments.
Matrices
A 3D matrix is a command that consists entirely of three 3D points. A 4D matrix consists entirely of either three or four 4D points; if there are only three 4D points then the fourth is implicitly considered to be (0.0 0.0 0.0 1.0). The points define the row elements of each type of matrix. Any other command that starts with a point is a syntax error.Top-level and built-in commands
All other commands start with an alphanumeric string, the command name which identifies it. The remaining elements of the command are its arguments.Command names can either specify top-level or built-in commands. Top-level commands generally configure Java 3D core and utility classes and can only appear at the outermost level of parentheses. Built-in commands are provided by the parser itself to help construct the arguments to top-level commands. Points, matrices, and built-in commands can only be nested within other commands.
An error will result if points, matrices, or built-in commands are invoked at the outermost level of nesting. Sometimes this error is caused by prematurely closing the opening parenthesis of the current top-level command. Such an error is usually preceded by an error from the command indicating an invalid number of arguments.
Similarly, errors will be generated if top-level commands are nested. Errors to this effect are sometimes caused by failing to close all the open parentheses of the preceding top-level command.
(Include "file:${user.home}/myBody.cfg")
would evaluate the contents of the file "myBody.cfg" in the user's home directory on Unix systems. An error is issued if no Java property exists with the specified name.
Java property substitution happens early, after tokenization but before command evaluation. Substitution can occur any number of times anywhere within any quoted or non-quoted string, including command names, property names, and property values, as long as the property substitution syntax is not nested.
| Command Overview |
Most top-level commands configure concrete Java 3D core and utility classes. These include PhysicalBody, PhysicalEnvironment, Screen, Sensor, View, and ViewPlatform. The Screen, View, and ViewPlatform commands also implicitly configure the Canvas3D core class and the Viewer and ViewingPlatform utility classes respectively.
These commands come in two forms: the New<class name> and <class name>Property commands. All New commands except NewSensor create new class instances and bind names to them, while the Property commands refer to these names and configure their corresponding class instances with the parameters specified by the command arguments. All references must be to objects previously instantiated in the file; forward referencing is not supported. Names must be unique within each class.
Implementations of the Java 3D InputDevice interface and concrete subclasses of the abstract ViewPlatformBehavior utility class can also be instantiated and configured with the same command forms. The New commands for these objects accept class names as command arguments and instantiate the objects through introspection. Since the details of the implementations are not known, configuration parameters are passed through methods which are invoked through introspection of the method names specified in the Property command arguments.
A method invoked through introspection with a Property command gets its arguments as a single array of Objects. Boolean strings get wrapped into Boolean objects, and number strings get wrapped into Double. 2D, 3D, and 4D points get wrapped into Point2d, Point3d, and Point4d objects respectively, while 3D and 4D matrices get wrapped into Matrix3d and Matrix4d respectively.
| Overview of Relevant View Model Parameters |
The sample configuration files are annotated to assist users in modifying them to suit their particular viewing environments, but it can be helpful to know some of the basics of the Java 3D view model that are relevant to writing a configuration file. This overview should only be considered an informal adjunct to the detailed description in the Java 3D Specification. Reading the source code to the ViewInfo utility (a public implementation of the Java 3D view model) may also be helpful in understanding the details of the view model.
| The Camera View Model |
In the traditional camera model the camera or eyepoint is positioned and oriented with respect to the virtual world via a view transform. Objects contained within the field of view are projected onto an image plane, which is then mapped onto a display surface, usually a window on a desktop display system. While the view direction and camera position can be freely oriented and placed anywhere in the virtual world, the projection is accomplished using a static frustum defined by the field of view and a flat image plane centered about and normal to the view direction.
This model emulates a typical physical camera quite well, but there are many viewing configurations that cannot be implemented using image planes that are fixed with respect to the view direction. In a multiple screen environment the projection frustum for each screen is skewed with respect to the image plane, based on the user's nominal viewing position. Realistic stereo views on fixed displays use skewed projection frustums derived from the offsets of the two eyes from the center of the image plane, while head tracking with fixed displays involves dynamically adjusting projection frustums in response to varying eye positions relative to the image plane.
In a low-level API such as OpenGL these situations are handled by concatenating all defined model and viewing transforms into a single modelview matrix, and for a fixed-screen environment explicitly computing the projection matrix for each eye, each display surface, and each new head position. Every application handling such viewing configurations typically reimplements the framework for computing those matrices itself. In these cases it would be useful to be able to separate the projection components out of the view transform in some representation based on display and eye locations.
| The Java 3D View Model |
Based on these requirements, a high-level view model should provide standard mechanisms to 1) define a screen's position and orientation in relation to other screens in the viewing environment; 2) specify the position of the user's eyes or an HMD relative to the physical space in which the screens or nominal user position are defined, and to have them updated automatically if tracking hardware exists; and 3) describe where the whole physical space is placed and oriented in the virtual world. In such a model the appropriate images could then be rendered without further computation in application code.
In the Java 3D view model, screen (image plate) positions and orientations are defined relative to a fixed frame of reference in the physical world, the tracker base, through the TrackerBaseToImagePlate property. The tracker base is somewhat abstract in that it is always used to define that fixed frame of reference, even if no physical tracking hardware is being used. If the ViewPolicy is HMD_VIEW, then the left and right image plates for head mounted displays are defined relative to the head tracking sensor, which reports head orientation and position relative to the tracker base.
Coexistence coordinates are defined with the CoexistenceToTrackerBase property. It provides a frame of reference in the physical world which can be set up by the user or application in whatever way is most convenient for positioning and orienting screens, physical body attributes, and sensing devices in the virtual world. If tracking is enabled, then the eye positions in coexistence are computed from the position and orientation of the head tracking sensor and the HeadToHeadTracker matrix; otherwise the eye positions in coexistence are set according to the CenterEyeInCoexistence property. In HMD mode the eye positions are fixed with respect to the image plates.
The mapping of coexistence coordinates into the virtual world is accomplished through the ViewAttachPolicy, which specifies the point in coexistence coordinates to which the origin of the view platform should be mapped. The view platform is positioned in the virtual world by manipulating its view transform, the composite of all the transforms from the view platform up to its Locale. The basis vectors (X, Y, and Z directions) of the view platform are always aligned with coexistence coordinates, and the scaling between view platform coordinates and physical coordinates is specified by the ScreenScalePolicy, so this establishes the complete mapping of the physical world into the virtual world. The projection of the virtual world onto the physical display surfaces is then performed automatically by the Java 3D renderer.
By default Java 3D tries to emulate the familiar camera model as much as possible to make it easy to run in a conventional windowed desktop display environment. It accomplishes this through the following default settings:
RELATIVE_TO_FIELD_OF_VIEW.PHYSICAL_WORLD.PHYSICAL_WORLD.NOMINAL_HEAD.RELATIVE_TO_COEXISTENCE.VIRTUAL_WORLD.VIRTUAL_WORLD.NOMINAL_SCREEN.| Top-Level Command Details |
Top-level commands can only appear at the outermost command nesting level.
This command instantiates the InputDevice implementation specified by the fully qualified class name and binds it to instance name. The InputDevice is instantiated through introspection of the class name. The implementation must provide a parameterless constructor; this can usually be done by extending or wrapping available InputDevice implementations.
The last two arguments are optional and define an alias for instance name. This is useful in providing a longer descriptive name for the application to recognize, or conversely, to provide a shorter alias for a longer instance name. Either name may be used to identify the instance.
At the conclusion of configuration file processing all InputDevice implementations so defined will be initialized and registered with any PhysicalEnvironments that reference them.
The details of the InputDevice implementation specified by instance name are not known to ConfigContainer, so any parameters to be set through the configuration file are passed to the InputDevice instance by invoking method name through introspection. The arguments following the method name are evaluated and the results passed to the method as an array of Objects.
The required methods can usually be provided by extending or wrapping existing InputDevice implementations.
Retrieves the Sensor at index sensor index in the InputDevice device name and binds it to the name specified by instance name. The sensor index is a number truncated to its integer value. The InputDevice implementation is responsible for creating its own Sensor objects, so this command does not create any new instances.
Instance name is used by other commands to reference the indicated Sensor. In addition, the name and its associated Sensor instance is made available to applications through a Map returned by the ConfigContainer method getNamedSensors.
The last two arguments are optional and define an alias for instance name. This is useful in providing a longer descriptive name for the application to recognize, or conversely, to provide a shorter alias for a longer instance name. Either name may be used to identify the instance.
If the Sensor is to be used for head tracking, or tracking the position and orientation of other objects in the physical world, then it must generate 6 degree of freedom data relative to the tracker base.
Sets a Sensor property. The sensor instance is specified by instance name, the property to be set by property name, and the value to be set by property value. The following sole property may be configured:
Hotspot
A 3D point in the sensor's local coordinate system. The hotspot specifies the "active" point which should interact with the virtual world, such as a point used for picking or grabbing an object. Its actual interpretation is up to the sensor behavior which uses it. Its value is ignored for head tracking sensors.
The above two commands are equivalent. Both create new window resources and associate them with the name specified by instance name. The device index is a number truncated to its integer value. This integer is the index at which the desired AWT GraphicsDevice appears in the array returned by the static getScreenDevices() method of GraphicsEnvironment, and specifies the physical screen upon which the window should be created. The GraphicsDevice order in the array is specific to the local viewing site and display system.
The last two arguments are optional and define an alias for instance name. This is useful in providing a longer descriptive name for the application to recognize, or conversely, to provide a shorter alias for a longer instance name. Either name may be used to identify the instance.
The above two commands are equivalent. The screen or window instance is specified by instance name, the property to be set by property name, and the value to be set by property value. The following properties are configurable:
PhysicalScreenWidth
A number specifying the screen's image area width in meters. When using a configuration file the default is 0.365. For head mounted displays this should be the apparent width of the display at the focal plane.PhysicalScreenHeight
A number specifying the screen's image area height in meters. When using a configuration file the default is 0.292. For head mounted displays this should be the apparent height of the display at the focal plane.WindowSize
This property's value can be a 2D point to create a window with the specified X width and Y height in pixels, or it can be either of the strings FullScreen or NoBorderFullScreen to specify a full screen canvas with visible frame borders or one with no frame borders. A NoBorderFullScreen canvas uses the entire physical display surface for its image. The default value is 512 x 512 pixels. For multiple screen virtual reality installations or head mounted displays NoBorderFullScreen should be used.WindowPosition
This property's value is a 2D point used to create a window with the specified X and Y position. These are offsets of the window's upper left corner from the screen's upper left corner.TrackerBaseToImagePlate
A 4D matrix which transforms points from tracker base coordinates to the image plate coordinates for the specified screen. This is only used when a ViewPolicy ofSCREEN_VIEWis in effect. The matrix value is identity by default.Image plate dimensions are expressed in meters. The origin of the image plate is the lower left corner of the screen's image area, with X increasing to the right, Y increasing to the top, and Z increasing away from the screen.
The tracker base is somewhat abstract. It is used as a local fixed frame of reference for specifying the orientation and position of a screen even when tracking hardware is not being used. It is also the frame of reference for defining coexistence coordinates with the CoexistenceToTrackerBase matrix.
The built-in commands Translate, Rotate, RotateTranslate, and TranslateRotate are available to make it easier to create transforms of this type.
HeadTrackerToLeftImagePlate
4D matrices which transform points in the head tracking sensor's local coordinate system to a head mounted display's left and right image plates respectively. The default value for each is the identity matrix.
HeadTrackerToRightImagePlateThese are only used when a ViewPolicy of
HMD_VIEWis in effect. As with physical screen dimensions, these matrices should indicate the apparent location and orientation of the screen images as viewed through the head mounted display's optics.The HMD manufacturer's specifications in terms of angle of view, distance to the focal plane, aspect ratio, and percentage of image overlap between the left and right views can be used to derive the apparent screen positions with respect to the head, and from there the positions with respect to the head tracker mounted on the head. In most cases there is 100% overlap between the two stereo images, so the matrices for both the left and right screens should be identical.
Some HMD devices support field-sequential stereo and are driven as if they were a single screen. In that case, only a single screen should be defined, but both the left and right head tracker to image plate transforms need to be specified for that same screen.
MonoscopicViewPolicy
This property may have the following string values:CYCLOPEAN_EYE_VIEW, LEFT_EYE_VIEW, orRIGHT_EYE_VIEW. The default value isCYCLOPEAN_EYE_VIEW. This default works for non-stereo displays and field-sequential stereo displays where the two stereo images are generated on the same canvas.Some HMD devices can be driven as a single screen if the HMD supports field-sequential stereo, so the default policy will work for them as well if a stereo view is enabled. If stereo is not enabled, an IllegalStateException will be thrown when the ViewPolicy is set to
HMD_VIEWwith the defaultCYCLOPEAN_EYE_VIEWpolicy in effect.The
LEFT_EYE_VIEWandRIGHT_EYE_VIEWmonoscopic view policies are used for generating stereo pairs on separate monoscopic canvases, including the left and right canvases needed by HMD devices that are driven by two video channels. When using these policies, stereo should not be enabled.
Creates a new PhysicalEnvironment and binds it to the name given by instance name. This specifies the available input devices, which Sensor to use as the head tracker, and defines the coexistence coordinate system. Note that aside from the head tracker, the configuration file does not provide a way to place Sensors into the array maintained by the PhysicalEnvironment. See the getNamedSensors method of ConfigContainer.
The last two arguments are optional and define an alias for instance name. This is useful in providing a longer descriptive name for the application to recognize, or conversely, to provide a shorter alias for a longer instance name. Either name may be used to identify the instance.
Sets a PhysicalEnvironment property. The instance is specified by instance name, the property to be set by property name, and the value to be set by property value. The following properties are configurable:
InputDevice
Register an InputDevice implementation instantiated by NewDevice. The InputDevice instance name is specified by the property value string. If an InputDevice is not registered then it will not be scheduled to run.HeadTracker
Register the Sensor which will be used for head tracking. It must provide 6 degree of freedom position and orientation reads relative to the tracker base. The Sensor instance name is specified by the property value string. Its corresponding input device must be registered with the InputDevice property.There is no actual method in the core PhysicalEnvironment class to set the head tracker. This property is a simplified interface for setting the PhysicalEnvironment head index and assigning the head tracking sensor to that index. Direct access to the PhysicalEnvironment Sensor array is not supported by the configuration file.
CoexistenceToTrackerBase
A 4D matrix which transforms points in coexistence coordinates to tracker base coordinates. This defines the position and orientation of coexistence coordinates relative to the tracker base. Its default value is the identity matrix, so if it is not set then coexistence coordinates will be the same as tracker base coordinates. See TrackerBaseToImagePlate.The coexistence origin (center of coexistence) positions the physical world with respect to the origin of the ViewPlatform in the virtual world. This is established through the ViewAttachPolicy, which attaches the view platform to either the center of coexistence, the nominal head, or the nominal feet. Coexistence coordinates can essentially be thought of as physical coordinates, but the real purpose is to define the space in which coordinates systems in the physical world - such as tracker base, image plate, and physical body - coexist and interact with the virtual world coordinate systems.
The basis vectors (X, Y, and Z directions) of coexistence coordinates are always aligned with the basis vectors of the ViewPlatform in the virtual world, and the scale factor going from ViewPlatform coordinates to coexistence coordinates is set by the ScreenScalePolicy. Together with the ViewPlatform's view attach policy and view transform this establishes the complete mapping of the physical world into the virtual world.
The positioning and orientation of coexistence coordinates with respect to the physical environment is up to the user or application. In a fixed screen environment it usually makes most sense to define it in a convenient relationship to the primary screen or some intersection of the available screens, such that the coexistence origin is in front of and aligned with the user's nominal forward gaze direction. This is because the -Z axis of coexistence coordinates always points along the view direction defined by the view platform's -Z axis.
For example, when using a single screen, the most common mapping puts the center of coexistence in the middle of the screen with its basis vectors aligned with the screen's image plate coordinate system. With a dual-screen system it is usually most convenient to place the center of coexistence in the middle of the edge shared by both screens, with its Z axis extending perpendicular to the shared edge and maintaining an equal angle to both screens. For a 2x2 array of four screens putting the center of coexistence at the center of the array is usually a good choice. In a cave configuration having the center of coexistence in the middle of the viewing environment can facilitate the sense of immersion.
In HMD mode the view attach policy is ignored and is always effectively
NOMINAL_SCREEN. Coexistence coordinates and view platform coordinates are then equivalent except for scale. For HMD configurations placing the coexistence coordinate system aligned with some nominal front-facing user position works well.Note: the normal Java 3D default is to place the center of coexistence in the middle of the screen or canvas by setting CoexistenceCenteringEnable true by default. This only works for a single screen and if both the TrackerBaseToImagePlate and CoexistenceToTrackerBase matrices are identity. If either of these matrices are set from their default identity values in the configuration file, and CoexistenceCenteringEnable has not been set, then the centering property will be set false by default.
Creates a new PhysicalBody and binds it to the name given by instance name. The PhysicalBody is essentiallly the users's head, with the origin halfway between the eyes in the plane of the face. Positive X extends to the right eye, positive Y up, and positive Z extends into the skull opposite to the forward gaze direction. Dimensions are expressed in meters.
The last two arguments are optional and define an alias for instance name. This is useful in providing a longer descriptive name for the application to recognize, or conversely, to provide a shorter alias for a longer instance name. Either name may be used to identify the instance.
Sets a PhysicalBody property. The instance is specified by instance name, the property to be set by property name, and the value to be set by property value. The following properties are configurable:
StereoEyeSeparation
A number indicating the interpupilary distance in meters. This will set the left and right eye positions to offsets of half this distance from the head origin along its X axis. The default is 0.066 meters.This property is a simplified interface to setting the PhysicalBody's separate left and right eye positions; there is no actual method in PhysicalBody to set stereo eye separation, but the results are exactly equivalent.
LeftEarPosition
A 3D point which sets the left ear position relative to head coordinates. The default is (-0.08, -0.03, 0.09).RightEarPosition
A 3D point which sets the right ear position relative to head coordinates. The default is (0.08, -0.03, 0.09).HeadToHeadTracker
A 4D matrix which transforms points from head coordinates to the local coordinate system of the head tracking sensor. This allows the positions of the eyes and ears to be determined from the position and orientation of the head tracker. The default is the identity matrix.NominalEyeOffsetFromNominalScreen
A distance in meters used as a calibration parameter for ViewAttachPolicy. It does not actually set the position of the eyes. The property is ignored if ViewAttachPolicy is NOMINAL_SCREEN. The default value is 0.4572 meters.NominalEyeHeightFromGround
A distance in meters used as a calibration parameter for ViewAttachPolicy. It does not actually set the position of the eyes. This property is ignored if ViewAttachPolicy is not NOMINAL_FEET. The default value is 1.68 meters.
Creates a new view and binds it to the name given by instance name. In the configuration file the term view refers to an instance of the Viewer utility class, which contains both an instance of a core Java 3D View class and an array of Canvas3D instances into which to render.
The last two arguments are optional and define an alias for instance name. This is useful in providing a longer descriptive name for the application to recognize, or conversely, to provide a shorter alias for a longer instance name. Either name may be used to identify the instance.
ConfiguredUniverse requires that at least one view be defined. If a view platform is not provided, then ConfiguredUniverse will create a default one and attach the view to that. If multiple views are defined, then at least one view platform must be explicitly provided by the configuration, and the ViewPlatform property must be used to attach each view to a view platform.
Sets a View property. The view instance is specified by instance name, the property to be set by property name, and the value to be set by property value. The following properties are configurable:
Screen
These two properties are equivalent. They include a screen created by NewScreen or a window created by NewWindow into this view. The screen or window name is specified by the property value string. Multiple-screen or multiple-window views are created by calling this command with each window or screen to be used. If no windows or screens are defined for this view then an IllegalArgumentException will be thrown after the configuration file has been processed.
WindowPhysicalEnvironment
Sets the PhysicalEnvironment to be used for this view. The property value string specifies the name of a PhysicalEnvironment instance created by the NewPhysicalEnvironment command. If no PhysicalEnvironment is specified for this view then one with default values will be created.PhysicalBody
Sets the PhysicalBody to be used for this view. The property value string specifies the name of a PhysicalBody instance created by the NewPhysicalBody command. If no PhysicalBody is specified for this view then one with default values will be created.ViewPlatform
The property value string is the name of a view platform defined by a previous NewViewPlatform command. This specifies that the view should be attached to the given view platform. ConfiguredUniverse requires that a view platform be specified for every defined view unless only a single view without a view platform is provided; in that case a view platform is created by default and the view is attached to that. If one or more view platforms are defined then the view attachments must be made explicitly.ViewPolicy
The property value string may be eitherSCREEN_VIEWorHMD_VIEWto indicate whether fixed room-mounted screens are being used or a head mounted display. The default value isSCREEN_VIEW.CoexistenceCenteringEnable
The property value is a boolean string. If true, then the origin of the coexistence coordinate system is set to either the middle of the canvas or the middle of the screen depending upon whether the WindowMovementPolicy isPHYSICAL_WORLDorVIRTUAL_WORLDrespectively. The X, Y, and Z directions of coexistence coordinates will point in the same directions as those of the screen's image plate.This only works if a single screen is being used and if both the TrackerBaseToImagePlate and CoexistenceToTrackerBase matrices are identity. If CoexistenceCenteringEnable is not explicitly set, and either the CoexistenceToTrackerBase transform for the view has been set or TrackerBaseToImagePlate has been set for any screen, then the centering enable will be set to false by default; otherwise, the normal default is true. This property is also effectively false whenever the ViewPolicy is set to
HMD_VIEW.WindowEyepointPolicy
The string value for this property may be eitherRELATIVE_TO_SCREEN, RELATIVE_TO_COEXISTENCE, RELATIVE_TO_WINDOW, orRELATIVE_TO_FIELD_OF_VIEW. The normal Java 3D default isRELATIVE_TO_FIELD_OF_VIEW. When using a configuration file the default isRELATIVE_TO_COEXISTENCEif CoexistenceCenteringEnable is false, otherwise the normal default applies. See the setWindowEyepointPolicy View method.For the
RELATIVE_TO_SCREENandRELATIVE_TO_WINDOWpolicies, the eyepoint is set by using the setLeftManualEyeInImagePlate() and setRightManualEyeInImagePlate() methods of Canvas3D. The configuration file currently does not provide any mechanism for altering these properties from their default values. These default values are (0.142, 0.135, 0.4572) for the left eye and (0.208, 0.135, 0.4572) for the right eye.These polices are ignored if head tracking is enabled.
WindowMovementPolicy
The string values for these properties may be either
WindowResizePolicyVIRTUAL_WORLDorPHYSICAL_WORLD. The normal Java 3D default value for both isPHYSICAL_WORLD. When using a configuration file the default values areVIRTUAL_WORLDif CoexistenceCenteringEnable is false, otherwise the normal defaults apply. See the setWindowMovementPolicy and setWindowResizePolicy View methods.CenterEyeInCoexistence
A 3D point which specifies the location of the center eye relative to coexistence coordinates. See CoexistenceToTrackerBase. If stereo viewing is enabled, then the left and right eye positions are set to offsets from this position using the values specified by the PhysicalBody. This property is ignored if head tracking is enabled or if WindowEyepointPolicy is notRELATIVE_TO_COEXISTENCE. The default value is (0.0, 0.0, 0.4572).This property is a simplified interface to setting the View's left and right manual eyes in coexistence; there is no actual method in View to set a center eye position.
ScreenScalePolicy
The property value string may be eitherSCALE_SCREEN_SIZEorSCALE_EXPLICITand determines the source of the screen scale, a factor in the scaling of view platform coordinates to physical world coordinates.If the value is
SCALE_SCREEN_SIZE, then the screen scale is half the physical screen width in meters. If WindowResizePolicy isPHYSICAL_WORLD, then this scale is further multiplied by the ratio of the window width to the width of the screen (the window scale) to produce the scale from view platform coordinates to physical coordinates. This allows a virtual world which spans a normalized width of [-1.0 .. 1.0] in view platform coordinates to map directly to the physical width of the window or screen, depending upon the resize policy.
SCALE_EXPLICITuses the value of the ScreenScale property as the screen scale. It is also further multiplied by the window scale when using thePHYSICAL_WORLDwindow resize policy to produce the scale from view platform coordinates to physical coordinates. Viewing configurations incorporating multiple screens should generally set the policy toSCALE_EXPLICITand choose a screen scale based on the aggregate display size, but the default value ofSCALE_SCREEN_SIZEwill usually work if all the screens are the same size and arranged in a linear array.The view platform is positioned in the virtual world through a chain of transforms to the root of the scene graph; this composite transform is its localToVWorld transform and must be congruent. If we take the the inverse of the scale factor in this transform and call it the view platform scale, then the scale from virtual world units to physical world units can be computed as the product of this view platform scale, the screen scale, and, when using a resize policy of
PHYSICAL_WORLD, the window scale. In the usual case the view platform scale is 1.0.ScreenScale
The property value is a number specifying the explicit screen scale factor. It is only used if ScreenScalePolicy isSCALE_EXPLICIT; otherwise, the screen scale is half the physical width of the screen in meters. The default value for this property is 1.0.BackClipPolicy
The string values of these properties may be either
FrontClipPolicyPHYSICAL_EYE, PHYSICAL_SCREEN, VIRTUAL_EYE, orVIRTUAL_SCREEN. The default policies arePHYSICAL_EYE. See the setFrontClipPolicy and setBackClipPolicy View methods.FrontClipDistance
These property values are numbers. The defaults are 0.1 and 10.0 respectively. See the setFrontClipDistance and setBackClipDistance View methods.
BackClipDistanceWith the default clip policies of
PHYSICAL_EYEthe clip distances are measured relative to the eye in physical units, so the clip distances specified must be scaled to virtual world units in order to determine the distances in the virtual world where they would effectively be applied. As described in the discussion of ScreenScalePolicy above, the scale from virtual units to physical units is the product of the view platform scale (usually 1.0), the screen scale, and the window scale (if the window resize policy isPHYSICAL_WORLD), so normally the scale from physical units to virtual units would be the inverse of that product.There is a quirk, however, with physical clip plane scaling when the
PHYSICAL_EYEorPHYSICAL_SCREENclip policies are used with thePHYSICAL_WORLDwindow resize policy. The locations of the clip planes in physical units are not actually set to the physical distances as specified, but are in fact scaled by the window scale. This means that when determining where the specified physical clip distances are in virtual units the scaling to be used is the inverse of the product of the screen scale and view platform scale only.This quirk applies only to scaling physical clip plane distances, and only with the
PHYSICAL_WORLDresize policy. It was implemented in this manner to prevent objects in the virtual world from getting clipped unexpectedly when the virtual world scaling changed as the result of a window resize. The quirk can be avoided by using theVIRTUAL_EYEorVIRTUAL_SCREENclip policies or by using theVIRTUAL_WORLDresize policy, but in most cases the effect is benign and doesn't lead to unexpected results.FieldOfView
This number is the view's horizontal field of view in radians. The default value is PI/4. This value is ignored if WindowEyepointPolicy is notRELATIVE_TO_FIELD_OF_VIEWor if head tracking is enabled. The eyepoint for each canvas associated with the view is set such that it is centered in X and Y, with the Z value at the appropriate distance to match the specified field of view across the width of the canvas.StereoEnable
Enable or disable stereo viewing for this view according to the boolean value specified by the property value string. The default value is false.There is no actual method in the core Java 3D View or utility Viewer class to enable stereo. A true value for this property causes ConfigContainer to attempt to create stereo-capable canvases for all the screens associated with this view. Stereo will then be enabled for each canvas successfully created with stereo capability.
TrackingEnable
Enable or disable head tracking for this view according to the boolean value specified by the property value string. The default value is false.Setting this property true causes WindowEyepointPolicy to be ignored; it will effectively be
RELATIVE_TO_COEXISTENCEwith the eyepoint in coexistence coordinates computed from reading the head tracking sensor. Tracking must be made available by registering an input device and a head tracking sensor in PhysicalEnvironment.AntialiasingEnable
Enable or disable scene antialiasing for this view according to the boolean value specified by the property value string. The default value is false.A true value for this property causes ConfigContainer to attempt to create a canvas capable of scene antialiasing on each screen associated with this view. The scene will then be antialiased on each canvas successfully created with that capability.
Line and point antialiasing are independent of scene antialiasing and are controlled by the LineAttribute and PointAttribute components of an Appearance. If line and point antialiasing is enabled, then they will be antialiased prior to scene antialiasing; if scene antialiasing is turned off, then antialiased lines and points will still be antialiased.
Creates a new view platform and binds it to the name given by instance name. In the configuration file the term view platform refers to an instance of the ViewingPlatform utility class, which is an extension of BranchGroup containing an instance of a core Java 3D ViewPlatform class.
The last two arguments are optional and define an alias for instance name. This is useful in providing a longer descriptive name for the application to recognize, or conversely, to provide a shorter alias for a longer instance name. Either name may be used to identify the instance.
Sets a ViewPlatform property. The instance is specified by instance name, the property to be set by property name, and the value to be set by property value. The following properties are configurable:
NominalViewingTransform
The property value is a boolean string indicating whether or not the view platform should be backed up in Z to allow objects at the origin to be viewed. This only has effect if the ViewAttachPolicy isNOMINAL_HEAD. The default value is false. See the setNominalViewingTransform method of ViewingPlatform.InitialViewingTransform
Sets the initial transform of the view platform to the 4D matrix specified by property value. The default value is identity.AllowPolicyRead
The property value is a boolean string indicating whether or not reading the ViewAttachPolicy is allowed. The default value is false.AllowLocalToVworldRead
The property value is a boolean string indicating whether or not reading the view platform's localToVworld transform is allowed. The default value is false.ViewPlatformBehavior
Attaches a ViewPlatformBehavior instantiated by NewViewPlatformBehavior. The property value string is the name bound to that instance.ViewAttachPolicy
The property value string can be one ofNOMINAL_SCREEN, NOMINAL_HEAD,orNOMINAL_FEET. This establishes the point in coexistence coordinates where the origin of view platform coordinates is attached. The basis vectors of view platform coordinates are always aligned with those of coexistence coordinates.For a ViewAttachPolicy of
NOMINAL_SCREEN, the ViewPlatform origin is set directly to the origin of coexistence, so that ViewPlatform coordinates and coexistence coordinates are identical except for scale.For a ViewAttachPolicy of
NOMINAL_HEAD, the ViewPlatform origin is set to the origin of the nominal head, the center eye halfway between the left and right eyes. The nominal head origin is on the Z axis of coexistence coordinates at some offset from the coexistence origin. If the WindowEyepointPolicy isRELATIVE_TO_FIELD_OF_VIEW, then this is the positive Z offset producing the required field of view relative to the width of the canvas at the coexistence origin, tracking the Z offset of the eyepoint defined by that policy; otherwise, the Z offset is the NominalEyeOffsetFromNominalScreen property of PhysicalBody and is decoupled from the actual eyepoint offset.For a ViewAttachPolicy of
NOMINAL_FEET, the ViewPlatform origin is at the ground plane, which is NominalEyeHeightFromGround meters along -Y from the origin of the nominal head. NominalEyeHeightFromGround is a property of PhysicalBody.Note: The normal Java 3D default is
NOMINAL_HEAD. When using a configuration file, the default isNOMINAL_HEADonly if every view attached to the view platform has a WindowEyepointPolicy ofRELATIVE_TO_FIELD_OF_VIEW; otherwise, the default isNOMINAL_SCREEN. If the view policy isHMD_VIEW, then the ViewAttachPolicy is ignored and is always effectivelyNOMINAL_SCREEN.
This command instantiates the concrete subclass of ViewPlatformBehavior specified by the fully qualified class name and binds it to instance name. The ViewPlatformBehavior is instantiated through introspection of the class name. The subclass must provide a parameterless constructor. If no such constructor is available, then the behavior must be extended or wrapped to provide one and the derived class used instead.
The last two arguments are optional and define an alias for instance name. This is useful in providing a longer descriptive name for the application to recognize, or conversely, to provide a shorter alias for a longer instance name. Either name may be used to identify the instance.
View platform behaviors often need sensors or canvases as event sources to drive the behavior action. A subclass of ViewPlatformBehavior always gets the current ViewingPlatform through its setViewingPlatform method. When the behavior is initialized, the canvases used by the ViewingPlatform can be retrieved by calling its getViewers method and then calling each Viewer's getCanvas3Ds method. Sensors can be retrieved by calling the ViewingPlatform method getUniverse, checking to see if the returned SimpleUniverse is a ConfiguredUniverse, and then calling its getNamedSensors method.
Alternatively, the behavior implementation can define its own properties and receive canvas and sensor instances directly through the Canvas3D and Sensor built-in commands.
Sets a property of a ViewPlatformBehavior. The instance is specified by instance name, the property to be set by property name, and the value to be set by property value. The following properties are pre-defined by the abstract ViewPlatformBehavior superclass and may be configured directly:
SchedulingBounds
The scheduling bounds for this behavior. Use the BoundingSphere built-in command to set this property. The default is whatever the application or the concrete subclass sets.SchedulingInterval
A number indicating the scheduling interval for this behavior. See the setSchedulingInterval method of Behavior.HomeTransform
See the ViewPlatformBehavior method setHomeTransform. The property value must be a 4D matrix.
The details of a concrete subclass of ViewPlatformBehavior are not known to ConfigContainer, so any properties specific to the subclass are set by using introspection to invoke property name as a method accepting an array of Objects as its single parameter. The arguments following the property name are evaluated and the results passed to the method through that array of Objects. Such methods can usually be provided by extending or wrapping existing ViewPlatformBehavior implementations.
This command instantiates a generic object specified by class name and binds it to instance name. The object is instantiated through introspection of the class name. The object must provide a parameterless constructor; this can usually be done by extending or wrapping existing objects.
The last two arguments are optional and define an alias for instance name. This is useful in providing a longer descriptive name for the application to recognize, or conversely, to provide a shorter alias for a longer instance name. Either name may be used to identify the instance.
Objects so defined may be accessed from ConfigContainer through the getNamedGenericObjects method.
Sets a property of a generic object. The details of the object specified by instance name are not known to ConfigContainer, so any parameters to be set through the configuration file are passed to the object instance by invoking method name through introspection. The arguments following the method name are evaluated and the results passed to the method as an array of Objects. The required methods can usually be provided by extending or wrapping existing objects.
Sets the Java system property propertyName to the string propertyValue. If the optional Default keyword is supplied, then the property is set only if it doesn't currently have a value.
Java system properties which affect Java 3D are evaluated at the first reference to a VirtualUniverse. Setting such properties in the configuration file is therefore ineffective if a ConfiguredUniverse constructor which accepts a URL directly is used; ConfigContainer must be used instead. Even then, care must be taken to avoid static references to VirtualUniverse from objects such as Transform3D.
The special Java property substitution syntax ${<propertyName>} may be used to access the value of a Java system property anywhere within a configuration file.
Retrieves the configuration file specified by URL string and includes it into the current configuration file at the current line. The content of the included file is evaluated exactly as if it were pasted into the current file at that line. Included files may be arbitrarily nested.
URL strings must be quoted.
Creates an alias for the object specified by originalName (which itself may be an alias). baseName may be Device, Object, PhysicalBody, PhysicalEnvironment, Screen, Window, Sensor, View, ViewPlatform, or ViewPlatformBehavior; it specifies the type of the object being aliased. Original names and aliases must be unique within a type. Note that there is no white space between baseName and Alias.
Aliases are useful for providing shorter or longer descriptive names for an original name. This function is also provided by the optional Alias keyword available for all New top-level commands. This separate command can be used to substitute new names for objects created by generic include files in order to conform to the names expected by specific applications.
| Built-In Command Details |
Built-in commands are provided by the parser itself to help construct the arguments to top-level commands. They cannot appear at the top level of command nesting.
Translate, Rotate, TranslateRotate, and RotateTranslate are useful for computing simple affine transforms of the form SourceToTarget (e.g., TrackerBaseToImagePlate). These transform points from the Source coordinate system to the Target coordinate system by concatenating translation and rotation matrices. Here is a general rule for creating such transforms:
Subtract (translate) the target origin first if it can be conveniently measured or computed relative to the source origin along the source X, Y, and Z basis vectors. Then rotate with Euler angles that move the target basis vectors to their corresponding source basis vectors.If instead it is easier to measure or compute the source origin relative to the target origin along the target basis vectors, rotate first with Euler angles that move the target basis vectors to their corresponding source basis vectors, and then add (translate) the source origin.
The Canvas3D, Sensor, Device, PhysicalBody, PhysicalEnvironment, View, ViewPlatform, ViewPlatformBehavior, and Object built-in commands return references to the objects named by their arguments. These are mostly useful for InputDevice and ViewPlatformBehavior implementations that define their own properties. The return values of these built-in commands should not be passed to commands that expect strings.
Returns a 4D matrix that translates by the given X, Y, and Z values.
Returns a 4D matrix that rotates by the given Euler angles around static X, Y, and Z basis vectors: first about X, then Y, and then Z. See the setEuler method of Transform3D.
Returns a 4D matrix that concatenates 4D matrices m1 and m2 in that order. If a point is transformed by the resulting matrix, then in effect the points are first transformed by m1 and then m2.
An alias for the Concatenate command. This is useful to make the result of the concatenation explicit.
An alias for the Concatenate command. This is useful to make the result of the concatenation explicit.
Returns a BoundingSphere object using the 3D point center and the given radius in meters. radius may be either a number or the string Infinite.
Returns the Canvas3D instance specified by the given name. A named Canvas3D is created whenever any of the following configuration commands are used:
(ViewProperty <view> Screen <screenName>)view is the name of a view created with the NewView command. The argument to the Canvas3D built-in must be a screenName or windowName parameter from one of the above commands.
(ViewProperty <view> Window <windowName>)
Note: the NewScreen and NewWindow commands do not create Canvas3D instances themselves; they are created only by the above configuration commands.
Returns the Sensor instance specified by the given name.
Returns the InputDevice instance specified by the given name.
Returns the PhysicalBody instance specified by the given name.
Returns the PhysicalEnvironment instance specified by the given name.
Returns the Viewer instance specified by the given name.
Returns the ViewingPlatform instance specified by the given name.
Returns the ViewPlatformBehavior instance specified by the given name.
Returns the generic object instance specified by the given name. A generic named object is created by the following configuration command:
(NewObject <instance name> <class name> [Alias <alias name>])
Returns a reference to the current ConfigContainer.
| Command Index |
| Command | Type |
|---|---|
| Alias | top-level |
| BoundingSphere | built-in |
| Canvas3D | built-in |
| Concatenate | built-in |
| ConfigContainer | built-in |
| Device | built-in |
| DeviceProperty | top-level |
| Include | top-level |
| JavaProperty | top-level |
| NewDevice | top-level |
| NewObject | top-level |
| NewPhysicalBody | top-level |
| NewPhysicalEnvironment | top-level |
| NewScreen | top-level |
| NewSensor | top-level |
| NewView | top-level |
| NewViewPlatform | top-level |
| NewViewPlatformBehavior | top-level |
| NewWindow | top-level |
| Object | built-in |
| ObjectProperty | top-level |
| PhysicalBody | built-in |
| PhysicalBodyProperty | top-level |
| PhysicalEnvironment | built-in |
| PhysicalEnvironmentProperty | top-level |
| Rotate | built-in |
| RotateTranslate | built-in |
| ScreenProperty | top-level |
| Sensor | built-in |
| SensorProperty | top-level |
| Translate | built-in |
| TranslateRotate | built-in |
| View | built-in |
| ViewPlatform | built-in |
| ViewPlatformBehavior | built-in |
| ViewProperty | top-level |
| ViewPlatformProperty | top-level |
| ViewPlatformBehaviorProperty | top-level |
| WindowProperty | top-level |
| Property Index |