# Boxer lifts 2D detections into fused 3D boxes, inference only

> Boxer is the code released with the Boxer paper from Facebook Research, and the repository ships pre-trained models without any training code, so the intended use is inference: turning 2D object detections into static, global, fused 3D oriented bounding boxes from posed images and semi-dense point clouds, aimed at indoor scenes. It runs on macOS with mps acceleration and on Linux with CUDA, and the repository records its licence as a custom one rather than a standard open source licence.

**facebookresearch/boxer** — Code for the Boxer research paper

- Repository: https://github.com/facebookresearch/boxer
- Stars: 670 · Forks: 76
- Language: Python
- License: NOASSERTION
- Published: 2026-10-21 · Updated: 2026-10-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/facebookresearch-boxer

## The repository ships models, not a training pipeline

Boxer is the code for the Boxer paper, accepted to ECCV 2026, and the first thing the documentation settles is what you can and cannot do with it. The repository contains the code and the pre-trained model needed to run Boxer on a variety of input data sources, and it is described as inference only code, with no training code. That framing matters for evaluation: you can run the published system, inspect its outputs, and build on the detection and fusion code, but you cannot reproduce the training or adapt the model from this repository alone. The project page, the arXiv entry, a video, and the model and data hosting on Hugging Face are all linked from the top of the README, and the model checkpoints cover BoxerNet, DinoV3 and OWLv2, which tells you the detection stack is built on an open vocabulary 2D detector rather than a fixed category list.

## The pipeline turns 2D boxes into global 3D oriented boxes

The task is described precisely: lifting 2D object detections into static, global, fused 3D oriented bounding boxes from posed images and semi-dense point clouds, with a focus on indoor object detection. Three properties of the output are worth noting because they describe what the system does and does not do. Static means the result is a 3D box in world space rather than a per frame 2D detection. Global means the boxes live in a common coordinate frame derived from the posed images. Fused means detections are merged across frames rather than reported independently, which is also the point of the separate fusion and tracking stages described below. The inputs are posed images, so the pipeline needs camera poses, and semi-dense point clouds, which points at depth or LiDAR style data rather than a monocular estimate. The intended audience is therefore a 3D vision researcher with sensor data and a detector, not someone working on photographs alone.

## The environment is built with uv, not conda

Installation is a Python environment and a handful of packages, and the documentation recommends uv as the tool. The steps are short enough to reproduce exactly:

```bash
uv venv boxer --python 3.12
source boxer/bin/activate
uv pip install 'torch>=2.0' numpy opencv-python tqdm dill
uv pip install projectaria-tools
uv pip install moderngl moderngl-window imgui-bundle
```

The core set covers PyTorch, NumPy, OpenCV, tqdm and dill, projectaria-tools is only needed for loading Project Aria data, and the moderngl stack with imgui-bundle is for the interactive 3D viewer used by the view scripts. The project pins Python 3.12 for the environment, and the ruff configuration in pyproject.toml targets py312 with a line length of 88. The documentation states it was tested on macOS with mps acceleration and on Fedora with CUDA acceleration, which tells you the two paths to try first: a laptop path and a datacenter path.

## Checkpoints and sample sequences come from Hugging Face

Two download scripts cover the assets. Model checkpoints for BoxerNet, DinoV3 and OWLv2 are hosted on Hugging Face, and the script pulls them into the `ckpts/` directory:

```bash
bash scripts/download_ckpts.sh
```

Sample data is handled the same way, with three Project Aria sequences, `hohen_gen1`, `nym10_gen1` and `cook0_gen2`, hosted on Hugging Face and fetched into `sample_data/`:

```bash
bash scripts/download_aria_data.sh
```

Beyond Aria the repository lists CA-1M, SUN-RGBD and ScanNet as supported sources, and the two smaller datasets come with their own helper scripts, `python scripts/download_ca1m_sample.py` and `python scripts/download_omni3d_sample.py`, while ScanNet has to be downloaded by hand from its own repository and placed in `sample_data/`. That last detail is the sharpest constraint in the setup: one of the four advertised data sources is not covered by any script in this repository, so a run on ScanNet needs a manual step before anything else works.

## Seven demos, from headless batch run to interactive prompting

The demos are ordered as a progression, and the first one needs no display at all. Demo 1 runs BoxerNet in headless mode over the first 90 images of a sequence from the NymeriaPlus test set, and the documentation says it is expected to take about two minutes on mac mps and under 15 seconds on CUDA:

```bash
python run_boxer.py --input nym10_gen1 --max_n=90 --track
```

It writes static images and a video to `outputs/nym10_gen1/`, and Demos 3 and 4 require it first, because it produces the 2D and 3D bounding box CSV files. Demo 2 is the interactive one, `python view_prompt.py --input nym10_gen1`, which needs a real display and lets you draw 2D bounding box prompts and type text to prompt OWL to detect objects. Demo 3 visualises offline fusion with `python view_fusion.py --input nym10_gen1`, and Demo 4 runs the online tracker with `python view_tracker.py --input nym10_gen1 --autoplay`, which estimates 3D boxes on the fly as new images arrive. Demos 5 to 7 repeat the interactive prompt flow on CA-1M, SUN-RGBD and ScanNet data.

## The flags separate detection, tracking and fusion

The CLI reference is where the design shows through. The pipeline supports optional online 3D tracking through `--track`, for temporal consistency, and offline 3D fusion through `--fuse`, for merging detections across frames after all detections have been made. The 2D detector is selected with `--detector`, with `owl` as the value, and the prompts come from `--labels`, defaulting to the taxonomy name `lvisplus` and accepting a comma separated list of text prompts instead. Two thresholds govern the result, `--thresh2d` for 2D detection confidence and `--thresh3d` for 3D box confidence, and a precision can be forced with `--force_precision`, with bfloat16 auto-detected on supported CUDA GPUs. Results land in `output/<sequence_name>/` as `boxer_3dbbs.csv` for per frame 3D boxes, `owl_2dbbs.csv` for per frame 2D detections, `boxer_3dbbs_tracked.csv` when tracking is on, and `boxer_viz_final.mp4` as the visualisation video. The two threshold values, the defaults of 0.2 and 0.5, are the first knobs to turn when results look wrong.

## A single release, a custom licence, and a July push

The repository has one tagged release, v1.0.0 described as the stable Boxer release, published on 2026-07-01, and the last push to the repository was on 2026-07-28, with the repository not archived. So the state of the project is a first stable snapshot rather than an actively iterated line, and anyone building on it should pin that tag. The licence is recorded as a custom one that GitHub cannot classify, with the details in the LICENSE file and a NOTICE file alongside it, which is a detail to settle before any code moves into a product rather than a research setting. The repository layout separates the model code in `boxernet/`, the 2D detector integration in `owl/`, the data loaders in `loaders/`, shared helpers in `utils/`, the four entry point scripts at the root, and the download and sampling helpers under `scripts/`, with a `tests/` directory and the `docs/` folder holding the architecture diagram.

## Conclusion

Researchers working on indoor 3D detection who want to see a published system's output on real sequences, or engineers who need a working 2D-to-3D detection baseline without building a training pipeline, will get a lot from this repository because it includes checkpoints, sample data and seven runnable demos. It is the wrong tool for anyone who needs to train or fine-tune the model, since no training code is included, and for teams that need a supported dependency set or a permissive standard licence, since the project records a custom licence. Before adopting it, run `python run_boxer.py --input nym10_gen1 --max_n=90 --track` on your own hardware, because the documentation's timing claims are specific to mps and CUDA machines.

## FAQ

### Does the Boxer repository include training code?

No. The documentation describes the repository as containing the code and pre-trained model needed to run Boxer on various input data sources, and states that it is inference only code with no training code included.

### How do I install Boxer and run the first demo?

Create a virtual environment with `uv venv boxer --python 3.12`, activate it, install torch, numpy, opencv-python, tqdm and dill, then fetch the checkpoints with `bash scripts/download_ckpts.sh` and the sample Aria sequences with `bash scripts/download_aria_data.sh`. The headless demo is `python run_boxer.py --input nym10_gen1 --max_n=90 --track`.

### What is the difference between the --track and --fuse options?

The pipeline supports optional online 3D tracking with `--track` for temporal consistency, and offline 3D fusion with `--fuse` for merging detections across frames after all detections have been made. Both rely on the 2D and 3D bounding box CSVs that the base run writes first.

### Which datasets can Boxer be run on?

The repository lists Project Aria Gen 1 and 2, CA-1M, SUN-RGBD and ScanNet. Helper scripts are provided for the Aria sequences, a CA-1M sample and an Omni3D SUN-RGBD subset, while ScanNet has to be downloaded manually and placed in the sample_data directory.

## Sources

- [facebookresearch/boxer on GitHub](https://github.com/facebookresearch/boxer)
- [Issues](https://github.com/facebookresearch/boxer/issues)
- [README](https://github.com/facebookresearch/boxer/blob/main/README.md)
- [Releases](https://github.com/facebookresearch/boxer/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/facebookresearch-boxer