org.artoolkitx.arx.arxj

## Class ARController

- java.lang.Object
- - org.artoolkitx.arx.arxj.ARController

-     public class ARController
      extends java.lang.Object

  The ARController class is a singleton which manages access to the underlying native functions defined in the `ARX_jni` class. Native calls should be made only from within this class so that adequate error checking and correct type conversion can take place.

- - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `int` | `addTrackable(java.lang.String cfg)` Adds a new single marker to the set of currently active markers.
    `float[]` | `calculateReferenceMatrix(int idMarkerBase, int idMarker2)` Calculates the reference matrix for the given markers.
    `boolean` | `capture()` Checks for a new frame available from the camera and captures it if so.
    `float` | `distance(int referenceMarker, int markerId2)` Calculated the distance between two markers
    `boolean` | `drawVideo(int videoSourceIndex)` Draw a video frame.
    `boolean` | `drawVideoFinal(int videoSourceIndex)` Perform required cleanup after drawing of video frames.
    `boolean` | `drawVideoInit(int videoSourceIndex)` Perform required initialisation for future drawing of video frames.
    `boolean` | `drawVideoSettings(int videoSourceIndex, int width, int height, boolean rotate90, boolean flipH, boolean flipV, int hAlign, int vAlign, int scalingMode, int[] viewport)` Set parameters of the rendering context for future drawing of video frames.
    `java.lang.String` | `getARToolKitXVersion()`
    `float` | `getBorderSize()`
    `boolean` | `getDebugMode()` Returns whether the square tracker debug video image is enabled.
    `static ARController` | `getInstance()` Implementation of the singleton pattern to provide a sole instance of the ARController class.
    `int` | `getPatternCountMax()`
    `int` | `getPatternSize()`
    `float[]` | `getProjectionMatrix(float nearPlane, float farPlane)` Returns the projection matrix calculated from camera parameters.
    `int` | `getThreshold()` Returns the threshold used to binarize the video image for square marker detection.
    `boolean` | `initialiseNative(java.lang.String resourcesDirectoryPath)` Initialises the native code library if it is available.
    `boolean` | `isInited()` Queries whether artoolkitX is initialized.
    `boolean` | `isRunning()` Returns true when video and tracking are running.
    `boolean` | `queryTrackableVisibilityAndTransformation(int trackableUID, float[] matrix)` Returns whether the marker with the specified ID is currently visible, and if visible the trackable transformation.
    `float[]` | `retrievePosition(int referenceMarkerId, int markerIdToGetThePositionFor)` Calculates the position depending on the referenceMarker
    `void` | `setBorderSize(float size)`
    `void` | `setDebugMode(boolean debug)` Enables or disables the debug video image in the square tracker.
    `void` | `setPatternCountMax(int count)`
    `void` | `setPatternSize(int size)`
    `void` | `setThreshold(int threshold)` Sets the threshold used to binarize the video image for square marker detection.
    `boolean` | `start(int videoWidth, int videoHeight, java.lang.String pixelFormat, java.lang.String cameraParaPath, int cameraIndex, boolean cameraIsFrontFacing)` Initialises the ARController.
    `void` | `stopAndFinal()` Stop and final.
    `boolean` | `update()` Takes an incoming frame from the Android camera and passes it to native code for conversion and tracking.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Method Detail

    - #### getInstance

          public static ARController getInstance()

      Implementation of the singleton pattern to provide a sole instance of the ARController class.
      Returns:
        The single instance of ARController.

    - #### initialiseNative

          public boolean initialiseNative(java.lang.String resourcesDirectoryPath)

      Initialises the native code library if it is available.
      Parameters:
        `resourcesDirectoryPath` - The full path (in the filesystem) to the directory to be used by the native routines as the base for relative references. e.g. Activity.getContext().getCacheDir().getAbsolutePath() or Activity.getContext().getFilesDir().getAbsolutePath()
      Returns:
        true if the library was found and successfully initialised.

    - #### getARToolKitXVersion

          public java.lang.String getARToolKitXVersion()

    - #### start

          public boolean start(int videoWidth,
                               int videoHeight,
                               java.lang.String pixelFormat,
                               java.lang.String cameraParaPath,
                               int cameraIndex,
                               boolean cameraIsFrontFacing)

      Initialises the ARController.
      Parameters:
        `videoWidth` - The width of the video image in pixels.
        `videoHeight` - The height of the video image in pixels.
        `pixelFormat` - string with format in which buffers will be pushed. Supported values include "NV21", "NV12", "YUV_420_888", "RGBA", "RGB_565", and "MONO".
        `cameraParaPath` - Either: null to search for camera parameters specific to the device, or a path (in the filesystem) to a camera parameter file. The path may be an absolute path, or relative to the resourcesDirectoryPath set in initialiseNative().
        `cameraIsFrontFacing` - false to search for a rear-facing camera, or true to search for a camera facing toward the user.
        `cameraIndex` - Zero-based index of the camera in use, i.e. if 0, the first camera facing in the requested direction will be used, if 1 then the second etc.
      Returns:
        true if initialisation was successful.

    - #### getDebugMode

          public boolean getDebugMode()

      Returns whether the square tracker debug video image is enabled.
      Returns:
        Whether the square tracker debug video image is enabled.

    - #### setDebugMode

          public void setDebugMode(boolean debug)

      Enables or disables the debug video image in the square tracker.
      Parameters:
        `debug` - Whether or not to enable the square tracker debug video image.

    - #### getThreshold

          public int getThreshold()

      Returns the threshold used to binarize the video image for square marker detection.
      Returns:
        The current threshold value in the range 0 to 255, or -1 if the threshold could not be retrieved.

    - #### setThreshold

          public void setThreshold(int threshold)

      Sets the threshold used to binarize the video image for square marker detection.
      Parameters:
        `threshold` - The new threshold value in the range 0 to 255.

    - #### getBorderSize

          public float getBorderSize()

    - #### setBorderSize

          public void setBorderSize(float size)

    - #### getPatternSize

          public int getPatternSize()

    - #### setPatternSize

          public void setPatternSize(int size)

    - #### getPatternCountMax

          public int getPatternCountMax()

    - #### setPatternCountMax

          public void setPatternCountMax(int count)

    - #### getProjectionMatrix

          public float[] getProjectionMatrix(float nearPlane,
                                             float farPlane)

      Returns the projection matrix calculated from camera parameters.
      Parameters:
        `nearPlane` - The value to use for the near OpenGL clipping plane.
        `farPlane` - The value to use for the far OpenGL clipping plane.
      Returns:
        A float array containing the OpenGL compatible projection matrix, or null if an error occurred.

    - #### addTrackable

          public int addTrackable(java.lang.String cfg)

      Adds a new single marker to the set of currently active markers.
      Parameters:
        `cfg` - The settings string for the used marker. Possible configurations look like this: `single;data/hiro.patt;80` `single_buffer;80;buffer=234 221 237...` `single_barcode;0;80` `multi;data/multi/marker.dat` `nft;data/nft/pinball`
      Returns:
        The unique identifier (UID) of the new marker, or -1 on error.

    - #### queryTrackableVisibilityAndTransformation

          public boolean queryTrackableVisibilityAndTransformation(int trackableUID,
                                                                   float[] matrix)

      Returns whether the marker with the specified ID is currently visible, and if visible the trackable transformation.
      Parameters:
        `trackableUID` - The unique identifier (UID) of the trackable to query.
      Returns:
        true if the marker is visible and tracked in the current video frame.

    - #### isInited

          public boolean isInited()

      Queries whether artoolkitX is initialized. This will be true after a call to `initialiseNative(String)`. At this point arwStartRunning can be called.
      Returns:
        true artoolkitX has been initialized

    - #### isRunning

          public boolean isRunning()

      Returns true when video and tracking are running.
      Returns:
        true when video and tracking are running, otherwise false

    - #### capture

          public boolean capture()

      Checks for a new frame available from the camera and captures it if so.
      Returns:
        true if frame was captured, otherwise false.

    - #### update

          public boolean update()

      Takes an incoming frame from the Android camera and passes it to native code for conversion and tracking.
      Returns:
        true if successful, otherwise false.

    - #### stopAndFinal

          public void stopAndFinal()

      Stop and final.

    - #### calculateReferenceMatrix

          public float[] calculateReferenceMatrix(int idMarkerBase,
                                                  int idMarker2)

      Calculates the reference matrix for the given markers. First marker is the base.
      Parameters:
        `idMarkerBase` - Reference base
        `idMarker2` - Marker that will be depending on that base
      Returns:
        Matrix that contains the transformation from @idMarkerBase to @idMarker2

    - #### distance

          public float distance(int referenceMarker,
                                int markerId2)

      Calculated the distance between two markers
      Parameters:
        `referenceMarker` - Reference base. Marker from which the distance is calculated
        `markerId2` - Marker to which the distance is calculated
      Returns:
        distance

    - #### retrievePosition

          public float[] retrievePosition(int referenceMarkerId,
                                          int markerIdToGetThePositionFor)

      Calculates the position depending on the referenceMarker
      Parameters:
        `referenceMarkerId` - Reference marker id
        `markerIdToGetThePositionFor` - Id of the marker for which the position is calculated
      Returns:
        Position vector with length 4 x,y,z,1

    - #### drawVideoInit

          public boolean drawVideoInit(int videoSourceIndex)

      Perform required initialisation for future drawing of video frames. Must be called from a rendering thread with an active rendering context.
      Parameters:
        `videoSourceIndex` - 0, or a video source with multiple inputs, the 0-based index of the active video source.
      Returns:
        true if successful

    - #### drawVideoSettings

          public boolean drawVideoSettings(int videoSourceIndex,
                                           int width,
                                           int height,
                                           boolean rotate90,
                                           boolean flipH,
                                           boolean flipV,
                                           int hAlign,
                                           int vAlign,
                                           int scalingMode,
                                           int[] viewport)

      Set parameters of the rendering context for future drawing of video frames. Must be called from a rendering thread with an active rendering context.
      Parameters:
        `videoSourceIndex` - 0, or a video source with multiple inputs, the 0-based index of the active video source.
      Returns:
        true if successful

    - #### drawVideo

          public boolean drawVideo(int videoSourceIndex)

      Draw a video frame. Must be called from a rendering thread with an active rendering context.
      Parameters:
        `videoSourceIndex` - 0, or a video source with multiple inputs, the 0-based index of the active video source.
      Returns:
        true if successful

    - #### drawVideoFinal

          public boolean drawVideoFinal(int videoSourceIndex)

      Perform required cleanup after drawing of video frames. Must be called from a rendering thread with an active rendering context.
      Parameters:
        `videoSourceIndex` - 0, or a video source with multiple inputs, the 0-based index of the active video source.
      Returns:
        true if successful