Calibration Utilities

Conventions

• A teletype font indicates text that is to be typed verbatim.
• Text enclosed in angle brackets <> indicates variables that have to be replaced by their proper values.
• Command line arguments in square brackets [] are optional.
• Parentheses () are used to group multiple related options.
• Vertical bars | indicate several mutually exclusive choices of options.

There are four programs, all contained in the Calibration subdirectory of Vrui's source directory and built by running make in that directory:

XBackground

XBackground is a simple utility to draw a calibration grid on a display.

MeasureEnvironment

MeasureEnvironment is a visual application to collect 3D point measurements using a Total Station, which is directly controlled via a serial cable. MeasureEnvironment measures points on the environment's floor to establish a ground plane, measures a calibration grid on the display to establish display size and keystone correction, and measures the 3D positions of tracking markers to establish a transformation from tracking system space into Vrui space.

ScreenCalibrator

ScreenCalibrator reads a point measurement file created by MeasureEnvironment and an associated marker measurement file created by the optical tracking system, and generates appropriate settings for Vrui's configuration file.

AlignTrackingMarkers

AlignTrackingMarkers is a visual utility to create appropriate local coordinate frames for rigid bodies detected by the optical tracking system. This is essential since the optical tracking software itself assigns "random" coordinate frames to each rigid body during configuration, which are not directly useful for Vrui.

XBackground

Command line

XBackground [-display <X display name>] -type 2 -size <grid size>

Arguments

-display <X display name>

This optional argument specifies the X display on which XBackground will display the calibration grid. If omitted, it defaults to the X display specified by the DISPLAY environment variable.

-type 2

This argument sets XBackground's display mode to show a calibration grid. Other modes are supported, but are irrelevant for calibration.

-size <grid size>

This argument defines the size of the calibration grid in pixels, i.e., the horizontal and vertical distance between adjacent grid lines. The value is a trade-off between calibration accuracy and speed; a smaller grid size implies more measurement points and better results, but a longer time to complete the measurements. For a screen size of 1920x1080 pixels, such as on 3D TVs, a grid size of 300 is a good compromise.

Usage

Note: It is important that XBackground is run in fullscreen mode, as opposed to windowed mode. XBackground will start in fullscreen mode automatically, but depending on the system's display setup, it might place itself on the wrong screen. In that case, the program has to be switched back to windowed mode, moved to the proper screen, and switched back to fullscreen mode. XBackground has no built-in support for that, but desktop environments such as Gnome or KDE typically provide a keyboard shortcut to switch windows' fullscreen status. Under Gnome, the shortcut can be assigned by going to the "Keyboard Shortcuts" control panel from the "Preferences" menu, and assigning a key combination to the "Toggle fullscreen mode" shortcut in the "Window Management" section. The recommended key combination is Ctrl-Alt-F.

Note: XBackground has a bug that sometimes displays a broken grid when the program is started. To fix the grid, one has to switch the program out of fullscreen mode, and then back into fullscreen mode.

MeasureEnvironment

Command line

MeasureEnvironment -t <serial port name> [-baudRate <baud rate>] [-unitScale <unit scale>] [-prismOffset <base prism offset>] [-ballRadius <marker radius>] [-npc <NaturalPoint OptiTrack server name>] [-flipZ] [<measurement file name>]

Arguments

-t <serial port name>

This argument specifies the name of the device node associated with the serial port to which the Total Station is connected. Under Linux, this is typically /dev/ttyS0 for the first built-in serial port, or /dev/ttyUSB0 for the first USB-to-serial adapter plug. The device node must be readable and writable by the user running MeasureEnvironment. This can temporarily be achieved by running chmod o+rw <serial port name> as root, and can be reverted by running chmod o-rw <serial port name>, also as root.

-baudRate <baud rate>

This optional argument specifies the baud rate used to communicate with the Total Station. If omitted, it defaults to 19200 bps, which is the default setting on the Total Station.

-unitScale <unit scale>

This optional argument specifies a unit conversion factor that is applied to measurements taken with the Total Station. Measurements are received in meters (unless configured otherwise on the Total Station), and if the argument is omitted, it defaults to 1, meaning measurements are recorded in meters. To record measurements in inches, for example, one would specify -unitScale 39.370079.

-prismOffset <base prism offset>

This optional argument specifies the offset that must be added to distance measurements to calculate the true distance from the Total Station's pivot point to the target point in millimeters. If omitted, it defaults to the Leica TCR 407's base prism offset in reflectorless mode, 34.4mm.

-ballRadius <marker radius>

This optional argument specifies the radius of the spherical tracking markers used by the optical tracking system in millimeters. If omitted, it defaults to the radius of the small tracking markers shipped with the Optitrack tracking system, which is 1/4", or 6.35mm.

-npc <NaturalPoint OptiTrack server name>

This optional argument tells MeasureEnvironment to connect directly to a running NaturalPoint OptiTrack server, to automatically collect a marker measurement from OptiTrack every time a ball is measured using the Total Station. The NaturalPoint client requires that UDP port 1001 is allowed through the firewall on the machine running MeasureEnvironment, and it also requires that MeasureEnvironment is run as root. Both are results of NaturalPoint's poor choice of using multicast streaming on a restricted port as a basis for their streaming protocol. Bad NaturalPoint!

-flipZ

This optional argument instructs MeasureEnvironment to flip the Z coordinate of all marker positions recorded from a NaturalPoint OptiTrack server, and is only relevant in conjunction with the previous option. NaturalPoint's Rigid Body Toolkit uses a left-handed coordinate system (bad NaturalPoint!) and requires this flag, whereas the newer Tracking Toolkit uses a right-handed system by default, in which case the flag is not needed.

<measurement file name>

This optional argument allows to load a previously recorded measurement file to continue an interrupted measurement process.

Usage

Measure Floor

In this mode, measurements from the Total Station are tagged as floor points, which are used to establish a ground plane during the calibration procedure. The process is to measure an arbitrary (but larger than three) number of points on the floor surrounding the calibrated screen. We recommend measuring about 10 floor points from throughout the workspace in front of the 3D TV.

Measure Screen

In this mode, measurements from the Total Station are tagged as screen points, which are used to precisely calculate the screen's size and keystone correction factors during the calibration procedure. Screen points correspond to the intersections of grid lines displayed on the calibrated screen via the XBackground utility. The process is to measure all grid line intersections top down to bottom by row, and from left to right inside each row.
Note: While it is possible to erase measurements after they have been collected by selecting them with a "Query Points" tool, duplicate points are easy to overlook. Users should take care to measure each grid point exactly once, and delete just-collected measurement points if there is suspicion that they were measured multiple times.

Measure Balls

In this mode, measurements from the Total Station are tagged as tracking marker points, which are used to establish a transformation from the tracking system's (arbitrary) coordinate space to the physical coordinate space of the calibrated Vrui environment. The third calibration stage involves placing a single tracking marker at an arbitrary (but larger than four) number of arbitrary 3D positions inside the tracking system's tracking space, and recording those positions both from inside the tracking software, and using the Total Station. OptiTrack's point cloud calibration utility has a recording feature, toggled on and off by pressing the button labeled with a fat red dot. If the optional -npc argument is given, MeasureEnvironment will collect measurements directly from OptiTrack, and generate an OptiTrack sample file, formatted so it can be read by the ScrenCalibrator utility, upon exit.

We recommend to measure around 20 points at different horizontal positions and elevations evenly throughout the entire workspace in front of the 3D TV. If ScreenCalibrator has difficulty achieving good alignment over the entire space, it is possible to focus calibration on a smaller volume by sampling a higher density of points from a region of interest, such as close to the screen. Ideally, one would keep rearranging and recalibrating the optical tracking system until good global calibration can be achieved.

We recommend to attach one marker to a tripod, and, for each measurement point, place the tripod somewhere in the tracking space, measure the marker's position with the Total Station (the laser should be aimed directly at the marker's center), and then record its OptiTrack position by sampling around 50 frames in the point cloud tool (or using the -npc option, as described above). Before measuring a point using either the Total Station or the point cloud tool, one should check that the marker can be reconstructed by the point cloud tool, and is not too close to the boundaries of the tracking volume (since the tracking cameras introduce distortions close to their frame edges). After all positions have been measured, the recorded samples can be exported to a CSV file which is later used by the ScreenCalibrator utility.

MeasureEnvironment will visualize all collected measurement points as they are collected, color-coding them as follows: red - floor points, green - screen points, purple - ball (tracking marker) points. The usual Vrui navigation tools can be used to move the viewpoint of the visualization, and a custom "Snap To Points" transformation tool can be used to measure positions, distances, or angles (see Vrui's user's manual).

When MeasureEnvironment exits, it writes all measurements to a file MeasuredPoint.csv, which will subsequently be read by the ScreenCalibrator utility. The program does not check whether the MeasuredPoint.csv file already exists before overwriting it; it is recommended to rename the file once it is written, for example by including the name of the calibrated environment and/or the current date. If the optional -npc option was given, MeasureEnvironment will additionally write all OptiTrack samples to a file TrackingPoints.csv. The program does not check whether the TrackingPoints.csv file exists before overwriting it; it is recommended to rename the file once it is written, for example by including the name of the calibrated environment and/or the current date.

ScreenCalibrator

Command line

ScreenCalibrator -screenSize <screen width> <screen height> -squareSize <grid size> [-unitScale <unit scale>] [-metersToInches] <Total Station file name> <OptiTrack file name> [-flipZ]

Arguments

-screenSize <screen width> <screen height>

This argument specifies the width and the height of the calibrated display in pixels. The proper values for a 3D TV are -screenSize 1920 1080.

-squareSize <grid size>

This argument specifies the distance between adjacent horizontal and vertical grid lines that were drawn using the XBackground utility and measured as screen points using the MeasureEnvironment utility. The grid size value must match the value used for XBackground.

-unitScale <unit scale>

This optional argument specifies a unit conversion factor, to allow converting from the units recorded by MeasureEnvironment and the OptiTrack point cloud tool (both default to meters) to Vrui physical units. For example, to report calibration results in inches, use -unitScale 39.370079.

-metersToInches

This optional argument is a shorthand to report calibration results in inches.

<Total Station file name>

This argument specifies the name of the file that was created by the MeasureEnvironment utility.

<OptiTrack file name>

This argument specifies the name of the file that was created by OptiTrack's point cloud tool.

-flipZ

This optional argument instructs ScreenCalibrator to invert the Z coordinates of all sample points read from the OptiTrack file, to convert left-handed coordinate systems into right-handed ones. This is necessary with the older NaturalPoint Point Cloud Toolkit, but the newer Tracking Tools integrated application uses a right-handed system by default.

Usage

ScreenCalibrator prints several sections of calibration data to the console when started:

1. Screen fitting debugging output and quality control. The final fitting distances for projective and screen transformation should be small.
2. Screen configuration settings. This block of settings and values can directly be pasted into the appropriate screen section in Vrui's configuration file.
3. Tracking system fitting debugging output and quality control. The reported final distance should be small, and is a direct measure of the expected tracking inaccuracy over the entire calibrated space.
4. Tracking system configuration settings. The transformation setting can directly be pasted into the appropriate calibrator section in Vrui's VR device configuration file, VRDevices.cfg.

AlignTrackingMarkers

Command line

AlignTrackingMarkers [-size <marker size>] [-scale <unit scale>] [-inches] ( <OptiTrack marker file name> <rigid body name> ) | ( -npc < OptiTrack server name> <rigid body ID> )

Arguments

-size <marker size>

This optional argument specifies the size at which to draw markers and is given in Vrui physical coordinate units. If omitted, it defaults to 1/4", the radius of small OptiTrack tracking markers.

-scale <unit scale>

This optional argument specifies the conversion factor from OptiTrack units (meters by default) to Vrui physical units. For example, to report calibration results in inches, use -scale 39.370079.

-inches

This optional argument is a shorthand to report calibration results in inches.

<OptiTrack marker file name>

This argument specifies the name of the OptiTrack rigid body definition file from which to load the rigid body configurations.

<rigid body name>

This argument specifies the name of the rigid body to calibrate when loading an OptiTrack marker file.

-npc <NaturalPoint OptiTrack server name>

This argument specifies the host name of a running OptiTrack tracking application, from which AlignTrackingMarkers will directly query the configuration of a rigid body.

<rigid body ID>

This argument specifies the integer ID of the rigid body whose configuration to query from a running OptiTrack server indicated by the previous argument.

Usage

AlignTrackingMarkers can be started in two ways. First, it can read the configuration of a rigid body from an OptiTrack rigid body definition file (file extension .rdef), as used internally by the older Rigid Body Toolkit. If given a rigid body definition file, the program needs to know the given name of the rigid body which is to be configured. Second, the program can connect directly to a running OptiTrack tracking server, and query the configuration of a rigid body in real time. In this case, the program needs to know the numerical ID of the rigid body which is to be configured. If run with the -npc option, AlignTrackingMarkers needs to be run as root, and UDP port 1001 needs to be admitted through the local machine's firewall (see description of the MeasureEnvironment utility).

After reading a rigid body configuration using one of the two methods, AlignTrackingMarkers will visualize the rigid body as a collection of differently colored balls, and the user's first task is to match these balls with the actual tracking markers attached to the physical rigid body. If this is too hard, the rigid body is not asymmetric enough and should be rebuilt (the rigid body toolkit will have just as hard a time orienting the body during use). Once the virtual and physical rigid body are lined up, the user can interactively align coordinate axes one at a time. AlignTrackingMarkers visualizes the current local coordinate frame using three axes (X - red, Y - green, Z - blue), with the origin at the intersection of the three axes. To align an axis, the user first draws a line using a "Marker Selector" tool. The tool will snap to markers, and previously drawn lines. After a line has been drawn, the user can assign an axis to the line by selecting an option from the program's main menu. For example, to align the X axis along the line just drawn, the user selects "Align X Axis." To align the Y axis opposite to the line just drawn, the user selects "Align -Y Axis." After the axes have been oriented as desired, the user can drag the frame's origin by checking the "Move Origin" toggle button.

When AlignTrackingMarkers exits, it prints the a transformation from OptiTrack's local frame to the desired frame to the console. This transformation can directly be pasted into Vrui's VR device configuration file as a tracker post transformation.