org.firstinspires.ftc.robotcore.external.navigation

## Class VuforiaTrackableDefaultListener

- java.lang.Object
- - org.firstinspires.ftc.robotcore.external.navigation.VuforiaTrackableDefaultListener

- All Implemented Interfaces:
    VuforiaTrackable.Listener

      public class VuforiaTrackableDefaultListener
      extends java.lang.Object
      implements VuforiaTrackable.Listener

  `VuforiaTrackableDefaultListener` is the default listener used for `VuforiaTrackable` implementations. This listener facilitates polling for results of the tracking. (Advanced:) Alternate listeners could make use of event-driven results by taking actions in the `VuforiaTrackable.Listener` methods.
  See Also:
    `VuforiaTrackable`, `VuforiaTrackable.getListener()`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `protected static class` | `VuforiaTrackableDefaultListener.PoseAndCamera`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected CameraName` | `cameraNameBack`
    `protected CameraName` | `cameraNameFront`
    `protected VuforiaTrackableDefaultListener.PoseAndCamera` | `currentPoseAndCamera`
    `protected OpenGLMatrix` | `ftcCameraBackFromPhone`
    `protected java.util.Map<CameraName,OpenGLMatrix>` | `ftcCameraFromRobotCoords`
    `protected OpenGLMatrix` | `ftcCameraFromVuforiaCamera`
    `protected OpenGLMatrix` | `ftcCameraFrontFromPhone`
    `protected VuforiaTrackableDefaultListener.PoseAndCamera` | `lastTrackedPoseAndCamera`
    `protected java.lang.Object` | `lock`
    `protected boolean` | `newLocationAvailable`
    `protected boolean` | `newPoseAvailable`
    `protected OpenGLMatrix` | `phoneFromFtcCameraBack`
    `protected OpenGLMatrix` | `phoneFromFtcCameraFront`
    `protected OpenGLMatrix` | `phoneFromVuforiaCameraBack`
    `protected OpenGLMatrix` | `phoneFromVuforiaCameraFront`
    `protected java.util.Map<CameraName,OpenGLMatrix>` | `robotFromFtcCameraCoords`
    `static java.lang.String` | `TAG`
    `protected VuforiaTrackable` | `trackable`
    `protected OpenGLMatrix` | `vuforiaCameraFromFtcCamera`
    `protected OpenGLMatrix` | `vuforiaCameraFrontFromVuforiaCameraBack`
    `protected VuMarkInstanceId` | `vuMarkInstanceId`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `VuforiaTrackableDefaultListener()`
    `VuforiaTrackableDefaultListener(VuforiaTrackable trackable)` If a null `VuforiaTrackable` is provided, then `addTrackable(VuforiaTrackable)` must be called later, before tracking actually begins.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addTrackable(VuforiaTrackable trackable)` Adds a trackable on which this `VuforiaTrackable.Listener` is listening.
    `VuforiaLocalizer.CameraDirection` | `getCameraDirection()` Deprecated. This is of little use if a non-builtin camera is in use.
    `OpenGLMatrix` | `getCameraLocationOnRobot(CameraName cameraName)` Returns information previously set in `setCameraLocationOnRobot(CameraName, OpenGLMatrix)`
    `CameraName` | `getCameraName()` Returns the name of the camera most recently tracked, or null if tracking has never occurred.
    `protected OpenGLMatrix` | `getFtcCameraFromRobot(CameraName cameraName)`
    `OpenGLMatrix` | `getFtcCameraFromTarget()` Returns the pose of the trackable if it is currently visible.
    `OpenGLMatrix` | `getFtcFieldFromRobot()` Returns the `OpenGLMatrix` transform that represents the location of the robot on in the FTC Field Coordinate System, or null if that cannot be computed.
    `OpenGLMatrix` | `getLastTrackedPoseVuforiaCamera()` Returns the pose associated with the last known tracked location of this trackable, if any.
    `OpenGLMatrix` | `getLastTrackedRawPose()` Deprecated. use `getLastTrackedPoseVuforiaCamera()` instead
    `protected OpenGLMatrix` | `getPhoneFromVuforiaCamera(VuforiaLocalizer.CameraDirection direction)` A synonym for `getPoseCorrectionMatrix(org.firstinspires.ftc.robotcore.external.navigation.VuforiaLocalizer.CameraDirection)`.
    `OpenGLMatrix` | `getPhoneLocationOnRobot()` Deprecated. Using `getCameraLocationOnRobot(CameraName)` is a better choice.
    `OpenGLMatrix` | `getPose()` A synonym for `getPosePhone()`, the latter being more descriptive of the coordinate system of the value returned.
    `OpenGLMatrix` | `getPoseCorrectionMatrix(VuforiaLocalizer.CameraDirection direction)` Deprecated. These phone-based matrices are no longer of much relevance, as the correct values, when of interest, are fixed and known.
    `OpenGLMatrix` | `getPosePhone()` Returns the pose of the trackable if it is currently visible.
    `OpenGLMatrix` | `getRawPose()` Deprecated. use `getVuforiaCameraFromTarget()` instead
    `OpenGLMatrix` | `getRawUpdatedPose()` Deprecated. use `getUpdatedVuforiaCameraFromTarget()` instead
    `OpenGLMatrix` | `getRobotLocation()` Synonym for `getFtcFieldFromRobot()`
    `OpenGLMatrix` | `getUpdatedRobotLocation()` Returns the location of the robot, but only if a new location has been detected since the last call to `getUpdatedRobotLocation()`.
    `OpenGLMatrix` | `getUpdatedVuforiaCameraFromTarget()` Returns the raw pose of the trackable, but only if a new pose is available since the last call to `getUpdatedVuforiaCameraFromTarget()`.
    `OpenGLMatrix` | `getVuforiaCameraFromTarget()` Returns the raw pose of the trackable as reported by Vuforia.
    `VuMarkInstanceId` | `getVuMarkInstanceId()` Returns the instance id of the currently visible VuMark associated with this VuMark template, if any presently exists.
    `boolean` | `isVisible()` Answers whether the associated trackable is currently visible or not
    `void` | `onNotTracked()` Called by the system to inform the trackable that it is no longer visible.
    `void` | `onTracked(TrackableResult trackableResult, CameraName cameraName, Camera camera, VuforiaTrackable child)` `onTracked(TrackableResult, CameraName, Camera, org.firstinspires.ftc.robotcore.external.navigation.VuforiaTrackable)` is called by the system to notify the listener that its associated trackable is currently visible.
    `void` | `setCameraLocationOnRobot(CameraName cameraName, OpenGLMatrix robotFromFtcCamera)` Informs the `VuforiaTrackableDefaultListener` of the location of a particular camera on the robot.
    `void` | `setPhoneInformation(OpenGLMatrix robotFromPhone, VuforiaLocalizer.CameraDirection cameraDirection)` Informs the listener of the location of the phone on the robot and the identity of the camera being used.
    `void` | `setPoseCorrectionMatrix(VuforiaLocalizer.CameraDirection direction, OpenGLMatrix matrix)` Deprecated.

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

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

- - ### Field Detail

    - #### TAG

          public static final java.lang.String TAG

      See Also:
        Constant Field Values

    - #### lock

          protected final java.lang.Object lock

    - #### trackable

          protected VuforiaTrackable trackable

    - #### newPoseAvailable

          protected boolean newPoseAvailable

    - #### newLocationAvailable

          protected boolean newLocationAvailable

    - #### currentPoseAndCamera

          protected VuforiaTrackableDefaultListener.PoseAndCamera currentPoseAndCamera

    - #### lastTrackedPoseAndCamera

          protected VuforiaTrackableDefaultListener.PoseAndCamera lastTrackedPoseAndCamera

    - #### vuMarkInstanceId

          protected VuMarkInstanceId vuMarkInstanceId

    - #### phoneFromVuforiaCameraFront

          protected final OpenGLMatrix phoneFromVuforiaCameraFront

    - #### phoneFromVuforiaCameraBack

          protected final OpenGLMatrix phoneFromVuforiaCameraBack

    - #### vuforiaCameraFrontFromVuforiaCameraBack

          protected final OpenGLMatrix vuforiaCameraFrontFromVuforiaCameraBack

    - #### ftcCameraFromVuforiaCamera

          protected final OpenGLMatrix ftcCameraFromVuforiaCamera

    - #### vuforiaCameraFromFtcCamera

          protected final OpenGLMatrix vuforiaCameraFromFtcCamera

    - #### phoneFromFtcCameraFront

          protected final OpenGLMatrix phoneFromFtcCameraFront

    - #### phoneFromFtcCameraBack

          protected final OpenGLMatrix phoneFromFtcCameraBack

    - #### ftcCameraFrontFromPhone

          protected final OpenGLMatrix ftcCameraFrontFromPhone

    - #### ftcCameraBackFromPhone

          protected final OpenGLMatrix ftcCameraBackFromPhone

    - #### ftcCameraFromRobotCoords

          protected final java.util.Map<CameraName,OpenGLMatrix> ftcCameraFromRobotCoords

    - #### robotFromFtcCameraCoords

          protected final java.util.Map<CameraName,OpenGLMatrix> robotFromFtcCameraCoords

    - #### cameraNameFront

          protected final CameraName cameraNameFront

    - #### cameraNameBack

          protected final CameraName cameraNameBack

  - ### Constructor Detail

    - #### VuforiaTrackableDefaultListener

          public VuforiaTrackableDefaultListener()

    - #### VuforiaTrackableDefaultListener

          public VuforiaTrackableDefaultListener(VuforiaTrackable trackable)

      If a null `VuforiaTrackable` is provided, then `addTrackable(VuforiaTrackable)` must be called later, before tracking actually begins.

  - ### Method Detail

    - #### setPhoneInformation

          public void setPhoneInformation(OpenGLMatrix robotFromPhone,
                                          VuforiaLocalizer.CameraDirection cameraDirection)

      Informs the listener of the location of the phone on the robot and the identity of the camera being used. This information is needed in order to compute the robot location. Note that this is only applicable and useful when using cameras builtin to a phone.
      Parameters:
        `robotFromPhone` - the location of the phone on the robot. Maps phone coordinates to robot coordinates.
        `cameraDirection` - which camera on the phone is in use

    - #### setCameraLocationOnRobot

          public void setCameraLocationOnRobot(CameraName cameraName,
                                               OpenGLMatrix robotFromFtcCamera)

      Informs the `VuforiaTrackableDefaultListener` of the location of a particular camera on the robot.
      Parameters:
        `cameraName` - the name of the camera in question
        `robotFromFtcCamera` - the location of that camera; it transforms FTC camera coordiantes to robot coordinates

    - #### getPhoneLocationOnRobot

          @Deprecated
          public OpenGLMatrix getPhoneLocationOnRobot()

      Deprecated. Using `getCameraLocationOnRobot(CameraName)` is a better choice.
      Returns the location of the phone on the robot, as previously set, or null if that has never been set.
      Returns:
        the location of the phone on the robot, or null if that has never been set

    - #### getCameraLocationOnRobot

          public OpenGLMatrix getCameraLocationOnRobot(CameraName cameraName)

      Returns information previously set in `setCameraLocationOnRobot(CameraName, OpenGLMatrix)`
      Parameters:
        `cameraName` - the camera whose location is sought
      Returns:
        the location previously set, or the identity matrix if there is no such location

    - #### getFtcCameraFromRobot

          protected OpenGLMatrix getFtcCameraFromRobot(CameraName cameraName)

    - #### getCameraDirection

          @Deprecated
          public VuforiaLocalizer.CameraDirection getCameraDirection()

      Deprecated. This is of little use if a non-builtin camera is in use.
      Returns the identity of the camera in use
      Returns:
        the identity of the camera in use

    - #### getCameraName

          public CameraName getCameraName()

      Returns the name of the camera most recently tracked, or null if tracking has never occurred.
      Returns:
        the name of the camera most recently tracked, or null if tracking has never occurred.

    - #### getFtcFieldFromRobot

          public OpenGLMatrix getFtcFieldFromRobot()

      Returns the `OpenGLMatrix` transform that represents the location of the robot on in the FTC Field Coordinate System, or null if that cannot be computed. The returned transformation will map coordinates in the Robot Coordinate System to coordinates in the FTC Field Coordinate System.

      The pose will be null if the trackable is not currently visible. The location of the trackable will be null if a location wasn't previously provided with `VuforiaTrackable.setLocation(OpenGLMatrix)`. The camera location on the robot will be null if `setCameraLocationOnRobot(CameraName, org.firstinspires.ftc.robotcore.external.matrices.OpenGLMatrix)` has not been called. All three must be non-null for the location to be computable.

      Returns:
        the location of the robot on the field
      See Also:
        `getUpdatedRobotLocation()`, `getPosePhone()`, `setPhoneInformation(OpenGLMatrix, VuforiaLocalizer.CameraDirection)`, `VuforiaTrackable.setLocation(OpenGLMatrix)`, `getRobotLocation()`

    - #### getRobotLocation

          public OpenGLMatrix getRobotLocation()

      Synonym for `getFtcFieldFromRobot()`

    - #### getPoseCorrectionMatrix

          @Deprecated
          public OpenGLMatrix getPoseCorrectionMatrix(VuforiaLocalizer.CameraDirection direction)

      Deprecated. These phone-based matrices are no longer of much relevance, as the correct values, when of interest, are fixed and known.
      The pose correction matrices correct for the different coordinate systems used in Vuforia and our phone coordinate system here.

    - #### getPhoneFromVuforiaCamera

          protected OpenGLMatrix getPhoneFromVuforiaCamera(VuforiaLocalizer.CameraDirection direction)

      A synonym for `getPoseCorrectionMatrix(org.firstinspires.ftc.robotcore.external.navigation.VuforiaLocalizer.CameraDirection)`.

    - #### setPoseCorrectionMatrix

          @Deprecated
          public void setPoseCorrectionMatrix(VuforiaLocalizer.CameraDirection direction,
                                                          OpenGLMatrix matrix)

      Deprecated.
      See Also:
        `getPoseCorrectionMatrix(VuforiaLocalizer.CameraDirection)`

    - #### getUpdatedRobotLocation

          public OpenGLMatrix getUpdatedRobotLocation()

      Returns the location of the robot, but only if a new location has been detected since the last call to `getUpdatedRobotLocation()`.
      Returns:
        the location of the robot
      See Also:
        `getRobotLocation()`

    - #### getPosePhone

          public OpenGLMatrix getPosePhone()

      Returns the pose of the trackable if it is currently visible. If it is not currently visible, null is returned. The pose of the trackable is the location of the trackable in the phone's coordinate system. Note that this function is of little use if a webcam is used instead of a builtin phone camera. See `getFtcCameraFromTarget()` for a better choice.

      Note that whether a trackable is visible or not is constantly dynamically changing in the background as the phone is moved about. Thus, just because one call to getPose() returns a non-null matrix doesn't a second call a short time later will return the same result.

      Returns:
        the pose of the trackable, if visible; if not visible, then null is returned.
      See Also:
        `getPhoneFromVuforiaCamera(VuforiaLocalizer.CameraDirection)`, `getVuforiaCameraFromTarget()`, `isVisible()`, `getPose()`

    - #### getPose

          public OpenGLMatrix getPose()

      A synonym for `getPosePhone()`, the latter being more descriptive of the coordinate system of the value returned. Note that this function is of little use if a webcam is used instead of a builtin phone camera.

    - #### getFtcCameraFromTarget

          public OpenGLMatrix getFtcCameraFromTarget()

      Returns the pose of the trackable if it is currently visible. If it is not currently visible, null is returned. The pose of the trackable is the location of the trackable in the FTC Camera Coordinate System.
      See Also:
        `getPosePhone()`

    - #### getVuforiaCameraFromTarget

          public OpenGLMatrix getVuforiaCameraFromTarget()

      Returns the raw pose of the trackable as reported by Vuforia. This differs from the value reported by `getPosePhone()` because of the differing coordinate systems used by Vuforia and FTC
      Returns:
        the raw pose of the trackable as reported by Vuforia
      See Also:
        `getPhoneFromVuforiaCamera(VuforiaLocalizer.CameraDirection)`, `getRawPose()`

    - #### getRawPose

          @Deprecated
          public OpenGLMatrix getRawPose()

      Deprecated. use `getVuforiaCameraFromTarget()` instead

    - #### getUpdatedVuforiaCameraFromTarget

          public OpenGLMatrix getUpdatedVuforiaCameraFromTarget()

      Returns the raw pose of the trackable, but only if a new pose is available since the last call to `getUpdatedVuforiaCameraFromTarget()`.
      Returns:
        the raw pose of the trackable
      See Also:
        `getVuforiaCameraFromTarget()`, `getRawUpdatedPose()`

    - #### getRawUpdatedPose

          @Deprecated
          public OpenGLMatrix getRawUpdatedPose()

      Deprecated. use `getUpdatedVuforiaCameraFromTarget()` instead

    - #### isVisible

          public boolean isVisible()

      Answers whether the associated trackable is currently visible or not
      Returns:
        whether the associated trackable is currently visible or not
      See Also:
        `getVuforiaCameraFromTarget()`

    - #### getLastTrackedPoseVuforiaCamera

          public OpenGLMatrix getLastTrackedPoseVuforiaCamera()

      Returns the pose associated with the last known tracked location of this trackable, if any. This can be used to recall the last pose seen, even if the trackable is no longer visible.
      Returns:
        the pose associated with the last known tracked location of this trackable, if any.
      See Also:
        `getVuforiaCameraFromTarget()`

    - #### getLastTrackedRawPose

          @Deprecated
          public OpenGLMatrix getLastTrackedRawPose()

      Deprecated. use `getLastTrackedPoseVuforiaCamera()` instead

    - #### getVuMarkInstanceId

          public VuMarkInstanceId getVuMarkInstanceId()

      Returns the instance id of the currently visible VuMark associated with this VuMark template, if any presently exists.
      Returns:
        the instance id of the currently visible VuMark
      See Also:
        VuMark template

    - #### onTracked

          public void onTracked(TrackableResult trackableResult,
                                CameraName cameraName,
                                Camera camera,
                                VuforiaTrackable child)

      `onTracked(TrackableResult, CameraName, Camera, org.firstinspires.ftc.robotcore.external.navigation.VuforiaTrackable)` is called by the system to notify the listener that its associated trackable is currently visible.
      Specified by:
        `onTracked` in interface `VuforiaTrackable.Listener`
      Parameters:
        `trackableResult` - the Vuforia trackable result object in which we were located
        `cameraName` - the name of the camera used by Vuforia to track this object
        `camera` - the `Camera` instance used in the tracking. Will be null if a built-in camera is used

    - #### onNotTracked

          public void onNotTracked()

      Called by the system to inform the trackable that it is no longer visible.
      Specified by:
        `onNotTracked` in interface `VuforiaTrackable.Listener`

    - #### addTrackable

          public void addTrackable(VuforiaTrackable trackable)

      Description copied from interface: `VuforiaTrackable.Listener`
      Adds a trackable on which this `VuforiaTrackable.Listener` is listening. May not be called once tracking has begun. If the `VuforiaTrackable.Listener` is already listening to this trackable, then the call has no effect.
      Specified by:
        `addTrackable` in interface `VuforiaTrackable.Listener`