> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/opentrack/opentrack/llms.txt
> Use this file to discover all available pages before exploring further.

# ArUco Tracker

> Marker-based head tracking using printed ArUco patterns

The ArUco tracker uses printed fiducial markers (square patterns with unique IDs) to track head position. It's one of the easiest trackers to set up since it requires no special hardware - just a webcam and a printed marker.

## How It Works

ArUco markers are square patterns with a black border and a unique binary pattern inside. The tracker detects these markers in the camera image and calculates the 6DOF (position and orientation) pose based on the marker's size and appearance.

<Info>
  ArUco tracking is based on the ArUco library from OpenCV, which provides robust marker detection even in challenging lighting conditions.
</Info>

## Requirements

### Hardware

* **Webcam**: Any standard webcam (640x480 or higher recommended)
* **Printed marker**: ArUco marker printed on paper or cardboard
* **Mounting**: Way to attach marker to head (hat, headband, cap)

### Printing the Marker

You can generate ArUco markers using:

* Online generators: Search for "ArUco marker generator"
* OpenCV's ArUco module
* The marker should be printed at actual size (typically 5-10cm square)

<Warning>
  Print the marker with high quality on stiff paper or cardboard. Ensure the marker stays flat when mounted - warping will affect tracking accuracy.
</Warning>

## Setup Instructions

<Steps>
  <Step title="Print and Mount Marker">
    1. Print an ArUco marker (recommend 7x7cm or larger)
    2. Mount on stiff backing if using regular paper
    3. Attach to hat, headband, or cap brim
    4. Ensure marker faces the camera and stays flat

    <Info>
      Larger markers are detected more reliably at greater distances. Use at least 5x5cm for desktop use.
    </Info>
  </Step>

  <Step title="Select Camera">
    In OpenTrack tracker settings:

    ```yaml theme={null}
    Camera: Select your webcam
    Resolution: 640x480 (or higher for better accuracy)
    Force FPS: Default (or 30/60 for consistency)
    Use MJPEG: Enable if supported
    ```
  </Step>

  <Step title="Configure Field of View">
    Set the camera's field of view to match your webcam:

    ```yaml theme={null}
    Field of View: 56 degrees (typical webcam)
    ```

    If unknown, you can measure it:

    1. Place an object of known width at a known distance
    2. Measure when object fills frame width
    3. Calculate: FOV = 2 \* arctan(object\_width / (2 \* distance))
  </Step>

  <Step title="Set Head Position Offset">
    Configure the offset from the marker to your head's rotation center:

    ```yaml theme={null}
    Head Position X: 0mm (left/right from marker center)
    Head Position Y: 0mm (up/down from marker center)  
    Head Position Z: 0mm (forward/back from marker center)
    ```

    You can also use the calibration tool:

    1. Click **Calibrate** in tracker settings
    2. Rotate your head while keeping shoulders still
    3. The offset will be calculated automatically
  </Step>

  <Step title="Test Tracking">
    1. Start tracking in OpenTrack
    2. View the video preview
    3. The detected marker should be highlighted with a green outline
    4. Check that head movements are tracked smoothly

    If marker is not detected:

    * Ensure good lighting (avoid shadows on marker)
    * Check marker is flat and not warped
    * Move closer to camera
    * Try different camera angle
  </Step>
</Steps>

## Configuration Options

### Camera Settings

| Option               | Default  | Description                                       |
| -------------------- | -------- | ------------------------------------------------- |
| **Camera Name**      | -        | Select your webcam                                |
| **Force Resolution** | 0 (auto) | Set specific resolution (640x480, 1280x720, etc.) |
| **Field of View**    | 56°      | Camera horizontal FOV in degrees                  |
| **Force FPS**        | Default  | Lock framerate (30, 60, 120, etc.)                |
| **Use MJPEG**        | false    | Enable MJPEG compression                          |

<Accordion title="Available Resolutions">
  * 320x240 - Low quality, high FPS
  * 640x480 - Standard, good balance
  * 1280x720 - HD, better accuracy
  * 1920x1080 - Full HD, best accuracy

  Higher resolutions increase accuracy but may reduce framerate.
</Accordion>

### Head Position Offset

| Option              | Default | Description                        |
| ------------------- | ------- | ---------------------------------- |
| **Head Position X** | 0       | Left/right offset in millimeters   |
| **Head Position Y** | 0       | Up/down offset in millimeters      |
| **Head Position Z** | 0       | Forward/back offset in millimeters |

## Advanced Features

### Adaptive Threshold

The ArUco tracker uses adaptive thresholding to handle varying lighting conditions. The algorithm automatically adjusts detection parameters based on the scene.

### Region of Interest (ROI)

Once the marker is detected, the tracker uses a region of interest search to improve performance:

* Reduces computational load
* Increases framerate
* Makes detection more robust
* Automatically resets to full-frame search if marker is lost

### Automatic Recovery

If the marker is lost for more than 0.35 seconds, the tracker automatically:

1. Resets to full-frame detection
2. Cycles through different detection parameters
3. Adjusts threshold adaptively
4. Returns to ROI mode once marker is reacquired

## Troubleshooting

<AccordionGroup>
  <Accordion title="Marker not detected">
    **Lighting issues:**

    * Ensure even lighting on marker
    * Avoid shadows or reflections on marker
    * Don't place marker in direct sunlight
    * Avoid low-light conditions

    **Marker quality:**

    * Reprint marker with higher quality printer
    * Ensure marker is perfectly flat
    * Check for smudges or damage on marker
    * Use stiff backing to prevent warping

    **Distance:**

    * Move closer to camera
    * Use larger marker
    * Increase camera resolution
  </Accordion>

  <Accordion title="Jittery or unstable tracking">
    * Use larger marker for more stable detection
    * Increase camera resolution
    * Improve lighting conditions
    * Use higher framerate camera
    * Enable filtering in OpenTrack filter settings
    * Ensure marker is rigidly mounted
  </Accordion>

  <Accordion title="Tracking loses marker easily">
    * Increase marker size
    * Improve contrast (check printer settings)
    * Mount marker more perpendicular to camera
    * Reduce head rotation range
    * Check for camera auto-exposure issues
  </Accordion>

  <Accordion title="Wrong pose orientation">
    * Verify head position offset is correct
    * Re-run calibration procedure
    * Check marker is mounted right-side up
    * Ensure marker isn't mirrored or flipped
  </Accordion>

  <Accordion title="Low framerate">
    * Reduce camera resolution
    * Enable MJPEG compression
    * Close unnecessary applications
    * Use USB 3.0 port for camera
    * Disable video preview when not needed
  </Accordion>
</AccordionGroup>

## Advantages and Limitations

<CardGroup cols={2}>
  <Card title="Advantages" icon="check">
    * No special hardware required
    * Easy to set up
    * Works with any webcam
    * Reliable marker detection
    * Low cost (just print a marker)
    * Good accuracy for gaming
  </Card>

  <Card title="Limitations" icon="exclamation">
    * Marker must be visible to camera
    * Limited head rotation range (\~±60°)
    * Marker can be uncomfortable to wear
    * Affected by lighting conditions
    * Less accurate than IR point tracking
    * Paper markers can warp over time
  </Card>
</CardGroup>

## Tips for Best Results

1. **Print Quality**: Use a laser printer for crisp, high-contrast markers
2. **Marker Size**: Larger markers (8-10cm) work better for desktop distances
3. **Mounting**: Mount marker on cap brim or headband, keep it flat and rigid
4. **Lighting**: Use diffuse, even lighting - avoid harsh shadows
5. **Camera Position**: Mount camera at eye level, about 50-80cm away
6. **Background**: Keep background uncluttered to help detection algorithm

## Comparison with Other Trackers

| Feature          | ArUco    | PointTracker  | NeuralNet |
| ---------------- | -------- | ------------- | --------- |
| Setup difficulty | Easy     | Medium        | Very Easy |
| Hardware cost    | Very Low | Medium        | Very Low  |
| Accuracy         | Good     | Excellent     | Good      |
| Latency          | Low      | Very Low      | Medium    |
| Marker required  | Yes      | Yes (IR LEDs) | No        |
| Rotation range   | ±60°     | ±90°          | ±70°      |

## See Also

* [PointTracker](/trackers/pointtracker) - Higher precision IR LED tracking
* [NeuralNet Tracker](/trackers/neuralnet) - No marker required, AI-based
* [Hardware Guide](/trackers/hardware) - General hardware setup information