org.firstinspires.ftc.robotcore.external.navigation

## Interface VuforiaLocalizer

-     public interface VuforiaLocalizer

  Robot "localization" denotes a robot's ability to establish its own position and orientation within its frame of reference. The `VuforiaLocalizer` interface provides an interface for interacting with subsystems that can help support localization through visual means.
  See Also:
    Mobile robot navigation

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `VuforiaLocalizer.CameraDirection` `VuforiaLocalizer.CameraDirection` enumerates the identities of the builtin phone cameras that Vuforia can use.
    `static class` | `VuforiaLocalizer.CloseableFrame` `VuforiaLocalizer.CloseableFrame` exposes a close() method so that one can proactively reduce memory pressure when we're done with a Frame
    `static class` | `VuforiaLocalizer.Parameters` `VuforiaLocalizer.Parameters` provides configuration information for instantiating the Vuforia localizer

  - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `Bitmap` | `convertFrameToBitmap(Frame frame)` (Advanced) A helper utility that converts a Vuforia `Frame` into an Android `Bitmap`.
    `void` | `enableConvertFrameToBitmap()` (Advanced) Ensures that Vuforia exposes necessary data formats in `Frame`s that allows `convertFrameToBitmap(Frame)` to function
    `boolean[]` | `enableConvertFrameToFormat(int... pixelFormats)` (Advanced) Ask Vuforia to convert frames to the given requested formats.
    `Camera` | `getCamera()` Provides access to the `Camera` used by Vuforia.
    `CameraCalibration` | `getCameraCalibration()` (Advanced) Returns information about Vuforia's knowledge of the camera that it is using.
    `CameraName` | `getCameraName()` Provides access to the name of the camera used by Vuforia.
    `void` | `getFrameOnce(<any> frameConsumer)` (Advanced) Calls the indicated code with a frame from the video stream, exactly once.
    `java.util.concurrent.BlockingQueue<VuforiaLocalizer.CloseableFrame>` | `getFrameQueue()` (Advanced) Returns a queue into which, if requested, Vuforia `Frame`s are placed as they become available.
    `int` | `getFrameQueueCapacity()` (Advanced) Returns the current capacity of the frame queue.
    `VuforiaTrackables` | `loadTrackablesFromAsset(java.lang.String assetName)` Loads a Vuforia dataset from the indicated application asset, which must be of type .XML.
    `VuforiaTrackables` | `loadTrackablesFromFile(java.lang.String absoluteFileName)` Loads a Vuforia dataset from the indicated file, which must be a .XML file and contain the full file path.
    `void` | `setFrameQueueCapacity(int capacity)` (Advanced) Sets the maximum number of `Frame`s that will simultaneously be stored in the frame queue.

- - ### Method Detail

    - #### loadTrackablesFromAsset

          VuforiaTrackables loadTrackablesFromAsset(java.lang.String assetName)

      Loads a Vuforia dataset from the indicated application asset, which must be of type .XML. The corresponding .DAT asset must be a sibling. Note that this operation can be extremely lengthy, possibly taking a few seconds to execute. Loading datasets from an asset you stored in your application APK is the recommended approach to packaging datasets so they always travel along with your code.

      Datasets are created using the Vuforia Target Manager

      Parameters:
        `assetName` - the name of the .XML dataset asset to load
      Returns:
        a DataSet that can be used to manipulate the loaded data
      See Also:
        `loadTrackablesFromFile(String)`

    - #### loadTrackablesFromFile

          VuforiaTrackables loadTrackablesFromFile(java.lang.String absoluteFileName)

      Loads a Vuforia dataset from the indicated file, which must be a .XML file and contain the full file path. The corresponding .DAT file must be a sibling file in the same directory. Note that this operation can be extremely lengthy, possibly taking a few seconds to execute.

      Datasets are created using the Vuforia Target Manager

      Parameters:
        `absoluteFileName` - the full path to the .XML file of the dataset
      Returns:
        a DataSet that can be used to manipulate the loaded data
      See Also:
        `loadTrackablesFromAsset(String)`

    - #### getCamera

          Camera getCamera()

      Provides access to the `Camera` used by Vuforia. Will be null if a built-in camera is in use. Note that Vuforia is usually actively interacting with this `Camera`; users should on their own not initiate streaming, close the camera, or the like.

    - #### getCameraName

          CameraName getCameraName()

      Provides access to the name of the camera used by Vuforia.

    - #### getCameraCalibration

          CameraCalibration getCameraCalibration()

      (Advanced) Returns information about Vuforia's knowledge of the camera that it is using.
      Returns:
        information about Vuforia's knowledge of the camera that it is using.
      See Also:
        `com.vuforia.Tool#getProjectionGL(CameraCalibration, float, float)`

    - #### getFrameQueue

          java.util.concurrent.BlockingQueue<VuforiaLocalizer.CloseableFrame> getFrameQueue()

      (Advanced) Returns a queue into which, if requested, Vuforia `Frame`s are placed as they become available. This provides a means by which camera image data can be accessed even while the Vuforia engine is running.

      While the Vuforia engine is running, it takes exclusive ownership of the camera it is using. This impedes the ability to also use that camera image data in alternative visual processing algorithms. However, periodically (at a rate of tens of Hz), the Vuforia engine makes available `Frame`s containing snapshots from the camera, and through which camera image data can be retrieved. These can optionally be retrieved through the frame queue.

      To access these `Frame`s, call `setFrameQueueCapacity(int)` to enable the frame queue. Once enabled, the frame queue can be accessed using `getFrameQueue()` and the methods thereon used to access `Frame`s as they become available.

      When `setFrameQueueCapacity(int)` is called, any frame queue returned previously by `getFrameQueue()` becomes invalid and must be re-fetched.

      Returns:
        a queue through which Vuforia `Frame`s may be retrieved.
      See Also:
        `setFrameQueueCapacity(int)`, Frame (Java), Frame (C++), BlockingQueue

    - #### setFrameQueueCapacity

          void setFrameQueueCapacity(int capacity)

      (Advanced) Sets the maximum number of `Frame`s that will simultaneously be stored in the frame queue. If the queue is full and new `Frame`s become available, older frames will be discarded. The frame queue initially has a capacity of zero.

      Note that calling this method invalidates any frame queue retrieved previously through `getFrameQueue()`.

      Parameters:
        `capacity` - the maximum number of items that may be stored in the frame queue
      See Also:
        `getFrameQueue()`, `getFrameQueueCapacity()`

    - #### getFrameQueueCapacity

          int getFrameQueueCapacity()

      (Advanced) Returns the current capacity of the frame queue.
      Returns:
        the current capacity of the frame queue.
      See Also:
        `setFrameQueueCapacity(int)`, `getFrameQueue()`

    - #### getFrameOnce

          void getFrameOnce(<any> frameConsumer)

      (Advanced) Calls the indicated code with a frame from the video stream, exactly once.
      Parameters:
        `frameConsumer` - the code to call with the to-be-processed frame.

    - #### enableConvertFrameToBitmap

          void enableConvertFrameToBitmap()

      (Advanced) Ensures that Vuforia exposes necessary data formats in `Frame`s that allows `convertFrameToBitmap(Frame)` to function

    - #### enableConvertFrameToFormat

          boolean[] enableConvertFrameToFormat(int... pixelFormats)

      (Advanced) Ask Vuforia to convert frames to the given requested formats. Returns success/failure result for each format.
      Parameters:
        `pixelFormats` - Formats to request Vuforia to convert to.

    - #### convertFrameToBitmap

          Bitmap convertFrameToBitmap(Frame frame)

      (Advanced) A helper utility that converts a Vuforia `Frame` into an Android `Bitmap`.