Coorindate Systems in HoloLensARToolKit v0.1

This post is part of documentation of HoloLensARToolKit, version v0.1.

Coordinate System of Unity3D

Unity3D uses left-hand coordinate systems to define transformations. Yes, it is.

The above is a screenshot of a Unity transformation. The x, y, z axis directions are visualized with different colors, and are following left-land rules. In addition, rotation along axis is applied clockwise, unlike counter-clockwise in right-hand coordinate systems. If you are accustomed to right-hand coordinate systems as I do, please pay more attention when working with raw 4x4 matrices.

Coordinate System of ARToolKit

ARToolKit uses right-hand coordinate systems. Since OpenGL is right-handed as well, it is very comfortable to visualize the tracking result of ARToolKit by OpenGL.

In the official Unity package of ARToolKit, arunity, there exists a utility function

public static Matrix4x4 LHMatrixFromRHMatrix(Matrix4x4 rhm)

that converts the tracking result of ARToolKit to Unity environment.

Coordinate System of HoloLensARToolKit

It took me a while to figure out the complicated conversions happened inside ARToolKit, inside Unity, and in-between.

In this project, left-hand coordinate system is applied everywhere. That means, the multi-marker configuration, the tracking algorithm, the returned tracking result from native code, and of course, the visualization inside Unity. It will be elaborated by the following examples.

Single Pattern Marker

Hiro marker and Kanji marker are examples of single pattern marker. They are defined using binary files.

The coordinate system associated with a single pattern marker looks like this:

Single Matrix Marker

Single matrix marker is pre-defined in ARToolKit. User is only required to provide the ID and type of matrix code associated when using them in applications. The coordinate system associated with a matrix marker looks like this:

Multi Matrix Marker

Multi matrix marker is defined by a configuration file, that contains

  • total number of matrix markers
  • the ID of each matrix marker
  • the transformation from the multi-matrix marker to individual matrix marker.

Multi-matrix marker is useful for robust tracking, thus is much more useful for accuracy-critical augmented reality applications. Iterative Closest Point (ICP) algorithm is the underlying method for the fusion of tracking information.

The transformation field in the configuration file is also left-handed, which is different from original ARToolKit. That is to say, you have to modify the marker configuration file you used before.

For example, for a multi-barcode-4x3 configuration, the coordinate system of the multi-marker looks like this:

Thus, the transformation field of marker 0 (top-left), will be:

1.0  0.0  0.0  -105.00
0.0  1.0  0.0  -70
0.0  0.0  1.0  0.0

instead of

1.0  0.0  0.0  -105.00
0.0  1.0  0.0  70
0.0  0.0  1.0  0.0

in original ARToolKit.

Finally

You can access more articles describing the implementation details of HoloLensARToolKit in my blog, simply clicking on the tag: hololens-artoolkit.

Thanks for reading!


ARUWPController Options in HoloLensARToolKit v0.1

This post is part of documentation of HoloLensARToolKit, version v0.1.

ARUWPController

ARUWPController.cs is one of the main scripts used in HoloLensARToolKit. In this post, the options of this script are listed and discussed, along with common usecases.

Each Unity project using HoloLensARToolKit package must and must only have one ARUWPController component.

ARUWPController is very similar to ARController in ARToolKit, one of the major difference is that ARUWPController targets only at Universal Windows Platform, while ARController also handles Android, iOS, standalone and even editor. Therefore, ARUWPController has fewer attributes than ARController in general.

When ARUWPController script is attached to some Unity GameObject, its inspector window looks like this:

Camera Param

  • The field camera param specifies the name of camera calibration file, contained in the path Assets/StreamingAssets/.
  • The camera calibration file must be ARToolKit format. It is a binary file, instead of XML or YAML for OpenCV. Please refer to HoloLens Camera Calibration project for more details.
  • If you have a bytes array containing the camera calibration information, please refer to function ARUWPController::setCameraParamBuffer.

Threshold

ARToolKit first thresholds the grayscale image before corner extraction. If the Threshold Mode is set to AR_LABELING_THRESH_MODE_MANUAL, then this value is used as the threshold.

Border Size

The percentage of border of the marker, by default, it is 0.25. For example, in a 80cm width marker, the border is 20cm (25%).

Threshold Mode

You can choose different thresholding algorithm from the droplist, same as ARToolKit. Available options are:

  • AR_LABELING_THRESH_MODE_MANUAL
  • AR_LABELING_THRESH_MODE_AUTO_MEDIAN
  • AR_LABELING_THRESH_MODE_AUTO_OTSU
  • AR_LABELING_THRESH_MODE_AUTO_ADAPTIVE
  • AR_LABELING_THRESH_MODE_AUTO_BRACKETING

Labeling Mode

It configures the color of the border of the marker. AR_LABELING_BLACK_REGION is the default.

Pattern Detection Mode

This field configures what kind of marker does the detection algorithm look for.

  • If pattern markers only, e.g. Hiro or Kanji, then AR_TEMPLATE_MATCHING_COLOR or AR_TEMPLATE_MATCHING_MONO is enough.
  • If matrix marker only, e.g. 3x3 code marker, then AR_MATRIX_CODE_DETECTION is sufficient.
  • If there is need to detect both kinds of marker, then AR_TEMPLATE_MATCHING_COLOR_AND_MATRIX pr AR_TEMPLATE_MATCHING_MONO_AND_MATRIX must be chosen. Otherwise, one kind of marker is not detected.

Matrix Code Type

There are many kinds of matrix marker, some of them are supported by ARToolKit and this project. Most common one is AR_MATRIX_CODE_3x3. All available options are:

  • AR_MATRIX_CODE_3x3
  • AR_MATRIX_CODE_3x3_PARITY65
  • AR_MATRIX_CODE_3x3_HAMMING63
  • AR_MATRIX_CODE_4x4
  • AR_MATRIX_CODE_4x4_BCH_13_9_3
  • AR_MATRIX_CODE_4x4_BCH_13_5_5

Image Proc Mode

The mode of image processing, by default, AR_IMAGE_PROC_FRAME_IMAGE is chosen.

According to ARToolKit documentation,

When the mode is AR_IMAGE_PROC_FIELD_IMAGE, ARToolKit processes pixels in only every second pixel row and column. This is useful both for handling images from interlaced video sources (where alternate lines are assembled from alternate fields and thus have one field time-difference, resulting in a “comb” effect) such as Digital Video cameras.

Webcam Material

This is the Unity Material object that saves the frame data. This material can be attached to other objects as texture, or displayed in 2D mode as Unity::UI::Image.

Webcam Plane

This field is usually for debugging use. You can display the current frame on a Unity Plane object.

ARUWP Frame Rate Textbox

This field specifies the Unity::UI::Text object that ARUWPController outputs the current frame rate information. In the samples, it is a good indicator of the system runtime status. It can be visualized as a Head-Up Display (e.g. always in the top-right corner).

Finally

You can access more articles describing the implementation details of HoloLensARToolKit in my blog, simply clicking on the tag: hololens-artoolkit.

Thanks for reading!