# C++ Tracker Implementation

This project implements a C++ version of the DiMP tracker, focusing on the bounding box regressor and classifier components.

## Overview

The project consists of two main components:

1. **BBRegressor**: Implements the IoU (Intersection over Union) network for bounding box regression
2. **Classifier**: Implements the feature extraction for target classification

## Requirements

- CMake (3.18 or higher)
- C++17 compatible compiler
- LibTorch (PyTorch C++ API) - Currently targeting **1.8.0+cu111**.
- **CUDA (required)** - This implementation requires CUDA. The `build.sh` script targets CUDA **11.1** for compatibility with LibTorch 1.8.0+cu111. If CUDA 11.1 is not found at `/usr/local/cuda-11.1`, the script will warn and use a fallback (e.g., `/usr/local/cuda-11.8` or an existing `CUDA_HOME`), which might lead to compilation or runtime issues if there's a significant mismatch.

## Building the Project

### Automatic Build

The easiest way to build the project is to use the provided build script:

```bash
chmod +x build.sh
./build.sh
```

This will:
1. Check for CUDA availability (and exit if not found)
2. Download LibTorch with CUDA support if not already installed
3. Configure the project with CMake
4. Build the project
5. Install the executable to the `bin/` directory

### Manual Build

If you prefer to build manually:

```bash
mkdir -p build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --config Release
```

## Running the Demo

To run the demo application:

```bash
# Make sure CUDA is properly set up in your environment
./run_demo.sh
```

The script will check for CUDA availability and set up the necessary environment variables before running the demo.

## Project Structure

- `cimp/`: Main C++ implementation
  - `bb_regressor/`: Bounding box regressor implementation
  - `classifier/`: Feature extractor implementation
  - `demo.cpp`: Demo application
- `exported_weights/`: Directory containing exported PyTorch weights
  - `backbone/`: Backbone network weights
  - `bb_regressor/`: Bounding box regressor weights
  - `classifier/`: Classifier weights
- `ltr/`: Reference Python implementation
- `bin/`: Built executables

## Implementation Notes

- The PrRoIPooling implementation requires CUDA and has no CPU fallback
- All tensor operations are performed on CUDA devices
- The tracker is optimized for GPU execution only

## Comparing Python and C++ Implementations

To compare the outputs between Python and C++ implementations:

1. Run the Python implementation to generate reference outputs:
```bash
python demo.py
```

2. Run the C++ implementation:
```bash
./run_demo.sh
```

3. Compare the output statistics in the generated files:
   - `bb_regressor_stats.txt`
   - `classifier_stats.txt`

## Automated C++/Python Model Alignment and Comparison (2024)

This project now features a fully automated pipeline to ensure the C++ and Python implementations of ResNet, Classifier, and BBRegressor are numerically aligned:

- **Identical Preprocessing:** The exact same preprocessed input tensor is exported from Python and loaded in C++ for all tests, ensuring both models receive identical data.
- **No Fallbacks or Defaults:** All models are loaded with real, user-supplied weights. If any weights or outputs are missing, the test aborts or marks the result as missing—no dummy or default values are used.
- **Intermediate Debug Export:** Both C++ and Python save all intermediate outputs (after each ResNet stage, etc.) in matching shapes and formats for direct comparison.
- **Automated Comparison:** The `test/compare_models.py` script compares all outputs, reporting cosine similarity, allclose status, max error, and more. An HTML report is generated in `test/comparison/report.html`.
- **Trustworthy Results:** If any file is missing or invalid, the report marks it as such. All agreement metrics are real and reflect true model alignment.

**To run the full comparison:**

```bash
# Build and run the C++ test pipeline
test/run_full_comparison.sh 1
# Or run steps manually (see test/README.md)
```

See `test/README.md` for details on the test pipeline and how to add new models for comparison.

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## C++ Implementation Details

The C++ version in the `cimp/` directory aims to replicate the core components of the Python tracker.

Key C++ modules:
*   **BBRegressor**: Bounding Box Regressor (based on AtomIoUNet).
*   **Classifier**: Target Classifier (based on DiMP DIMPNet classifier part).
*   **ResNet**: ResNet-50 backbone for feature extraction.
*   **Demo Application**: A simple executable in `bin/tracking_demo` to test components.
*   **Test Models**: An executable in `bin/test_models` for running comparisons and tests.