org.scijava.java3d.utils.universe.doc-files.config-syntax.html Maven / Gradle / Ivy
Show all versions of j3dutils Show documentation
The Java 3D Configuration File
The Java 3D Configuration File
Syntax Description
Command Overview
Overview of Relevant View Model Parameters
Top-Level Command Details
Built-In Command Details
Command Index
Property Index
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.
Java property substitution syntax
All strings are additionally scanned for text enclosed by a starting ${ and a
matching }. Such text is looked up as a Java system property name and the
result is substituted back into the string after eliding the starting and
ending delimiters. For example, the 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:
-
WindowEyepointPolicy is set to
RELATIVE_TO_FIELD_OF_VIEW.
-
WindowMovementPolicy is set to
PHYSICAL_WORLD.
-
WindowResizePolicy is set to
PHYSICAL_WORLD.
-
ViewAttachPolicy is set to
NOMINAL_HEAD.
-
CoexistenceCenteringEnable is set to
true.
When a configuration file is being used the defaults are oriented towards
making the setup of multiple screen environments as easy as possible. If the
coexistence centering enable has not been explicitly set, and either the
CoexistenceToTrackerBase transform for the view has been set or
TrackerBaseToImagePlate has been set for any screen, then the following
defaults are used instead:
-
WindowEyepointPolicy is set to
RELATIVE_TO_COEXISTENCE.
-
WindowMovementPolicy is set to
VIRTUAL_WORLD.
-
WindowResizePolicy is set to
VIRTUAL_WORLD.
-
ViewAttachPolicy is set to
NOMINAL_SCREEN.
-
CoexistenceCenteringEnable is set to
false.
The avove defaults are also used if coexistence centering enable has been
explictly set false.
Top-Level Command Details
Top-level commands can only appear at the outermost command nesting level.
NewDevice
Syntax:
(NewDevice <instance name> <class name>
[Alias <alias name>])
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.
DeviceProperty
Syntax:
(DeviceProperty <instance name> <method name> <arg0>
... <argn>)
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.
NewSensor
Syntax:
(NewSensor <instance name> <device name>
<sensor index> [Alias <alias name>])
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.
SensorProperty
Syntax:
(SensorProperty <instance name> <property name>
<property value>)
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.
NewScreen
NewWindow
Syntax:
(NewScreen <instance name> <device index>
[Alias <alias name>])
(NewWindow <instance name> <device index>
[Alias <alias name>])
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.
ScreenProperty
WindowProperty
Syntax:
(ScreenProperty <instance name> <property name>
<property value>)
(WindowProperty <instance name> <property name>
<property value>)
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 of SCREEN_VIEW is 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
HeadTrackerToRightImagePlate
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.
These are only used when a ViewPolicy of HMD_VIEW is 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, or RIGHT_EYE_VIEW. The default value is
CYCLOPEAN_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_VIEW with the default
CYCLOPEAN_EYE_VIEW policy in effect.
The LEFT_EYE_VIEW and RIGHT_EYE_VIEW monoscopic 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.
NewPhysicalEnvironment
Syntax:
(NewPhysicalEnvironment <instance name>
[Alias <alias name>])
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.
PhysicalEnvironmentProperty
Syntax:
(PhysicalEnvironmentProperty <instance name>
<property name> <property value>)
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.
NewPhysicalBody
Syntax:
(NewPhysicalBody <instance name>
[Alias <alias name>])
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.
PhysicalBodyProperty
Syntax:
(PhysicalBodyProperty <instance name> <property name>
<property value>)
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.
NewView
Syntax:
(NewView <instance name>
[Alias <alias name>])
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.
ViewProperty
Syntax:
(NewView <instance name> <property name>
<property value>)
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
Window
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.
PhysicalEnvironment
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 either SCREEN_VIEW or
HMD_VIEW to indicate whether fixed room-mounted screens are being
used or a head mounted display. The default value is SCREEN_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 is
PHYSICAL_WORLD or VIRTUAL_WORLD respectively. 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 either RELATIVE_TO_SCREEN,
RELATIVE_TO_COEXISTENCE, RELATIVE_TO_WINDOW, or
RELATIVE_TO_FIELD_OF_VIEW. The normal Java 3D default is
RELATIVE_TO_FIELD_OF_VIEW. When using a configuration file the
default is RELATIVE_TO_COEXISTENCE if
CoexistenceCenteringEnable is false,
otherwise the normal default applies. See the
setWindowEyepointPolicy View method.
For the RELATIVE_TO_SCREEN and RELATIVE_TO_WINDOW
policies, 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
WindowResizePolicy
The string values for these properties may be either VIRTUAL_WORLD
or PHYSICAL_WORLD. The normal Java 3D default value for both is
PHYSICAL_WORLD. When using a configuration file the default
values are VIRTUAL_WORLD if
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
not RELATIVE_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 either SCALE_SCREEN_SIZE
or SCALE_EXPLICIT and 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 is
PHYSICAL_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_EXPLICIT uses the value of the ScreenScale property as the
screen scale. It is also further multiplied by the window scale when using the
PHYSICAL_WORLD window resize policy to produce the scale from view
platform coordinates to physical coordinates. Viewing configurations
incorporating multiple screens should generally set the policy to
SCALE_EXPLICIT and choose a screen scale based on the aggregate
display size, but the default value of SCALE_SCREEN_SIZE will
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 is SCALE_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
FrontClipPolicy
The string values of these properties may be either PHYSICAL_EYE,
PHYSICAL_SCREEN, VIRTUAL_EYE, or VIRTUAL_SCREEN. The
default policies are PHYSICAL_EYE. See the
setFrontClipPolicy and
setBackClipPolicy View methods.
FrontClipDistance
BackClipDistance
These property values are numbers. The defaults are 0.1 and 10.0
respectively. See the
setFrontClipDistance and
setBackClipDistance View methods.
With the default clip policies of PHYSICAL_EYE the 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 is PHYSICAL_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_EYE or PHYSICAL_SCREEN clip policies are
used with the PHYSICAL_WORLD window 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_WORLD resize 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 the VIRTUAL_EYE or
VIRTUAL_SCREEN clip policies or by using the
VIRTUAL_WORLD resize 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 not
RELATIVE_TO_FIELD_OF_VIEW or 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_COEXISTENCE with 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.
NewViewPlatform
Syntax:
(NewViewPlatform <instance name>
[Alias <alias name>])
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.
ViewPlatformProperty
Syntax:
(ViewPlatformProperty <instance name> <property name>
<property value>)
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 is
NOMINAL_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 of NOMINAL_SCREEN,
NOMINAL_HEAD, or NOMINAL_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 is RELATIVE_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 is NOMINAL_HEAD only if
every view attached to the view platform has a WindowEyepointPolicy of
RELATIVE_TO_FIELD_OF_VIEW; otherwise, the default is
NOMINAL_SCREEN. If the view policy is HMD_VIEW, then
the ViewAttachPolicy is ignored and is always effectively
NOMINAL_SCREEN.
NewViewPlatformBehavior
Syntax:
(NewViewPlatformBehavior <instance name> <class name>
[Alias <alias name>])
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.
ViewPlatformBehaviorProperty
Syntax:
(ViewPlatformBehaviorProperty <instance name>
<property name> <property value>)
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.
NewObject
Syntax:
(NewObject <instance name> <class name>
[Alias <alias name>])
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.
ObjectProperty
Syntax:
(ObjectProperty <instance name> <method name> <arg0>
... <argn>)
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.
JavaProperty
Syntax:
(JavaProperty <propertyName> [Default]
<propertyValue>)
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.
Include
Syntax:
(Include <URL string>)
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.
Alias
Syntax:
(<baseName>Alias <aliasName>
<originalName>)
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.
Translate
Syntax:
(Translate <x offset> <y offset> <z offset>)
Returns a 4D matrix that translates by the given X, Y, and Z values.
Rotate
Syntax:
(Rotate <x degrees> <y degrees> <z degrees>)
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.
Concatenate
Syntax:
(Concatenate <m1> <m2>)
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.
RotateTranslate
Syntax:
(RotateTranslate <m1> <m2>)
An alias for the Concatenate command. This is useful to make the
result of the concatenation explicit.
TranslateRotate
Syntax:
(TranslateRotate <m1> <m2>)
An alias for the Concatenate command. This is useful to make the
result of the concatenation explicit.
BoundingSphere
Syntax:
(BoundingSphere <center> <radius>)
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.
Canvas3D
Syntax:
(Canvas3D <screen or window name>)
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>)
(ViewProperty <view> Window <windowName>)
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.
Note: the NewScreen and NewWindow commands do not create Canvas3D
instances themselves; they are created only by the above configuration
commands.
Sensor
Syntax:
(Sensor <sensor name>)
Returns the Sensor instance specified by the given name.
Device
Syntax:
(Device <device name>)
Returns the InputDevice instance specified by the given name.
PhysicalBody
Syntax:
(PhysicalBody <body name>)
Returns the PhysicalBody instance specified by the given name.
PhysicalEnvironment
Syntax:
(PhysicalEnvironment <environment name>)
Returns the PhysicalEnvironment instance specified by the given name.
View
Syntax:
(View <view name>)
Returns the Viewer instance specified by the given name.
ViewPlatform
Syntax:
(ViewPlatform <view platform name>)
Returns the ViewingPlatform instance specified by the given name.
ViewPlatformBehavior
Syntax:
(ViewPlatformBehavior <behavior name>)
Returns the ViewPlatformBehavior instance specified by the given name.
Object
Syntax:
(Object <generic object 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>])
ConfigContainer
Syntax:
(ConfigContainer)
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