HappyPose

Toolbox and trackers for object pose-estimation. Based on the work CosyPose and MegaPose. This directory is currently under development. Please refer to the documentation for more details.

Installation

To install happypose, you can use pip or uv.

We strongly suggest to install it in either a venv or a conda environment.

Example with conda

git clone --branch dev --recurse-submodules https://github.com/agimus-project/happypose.git
cd happypose
conda env create -f environment.yml
conda activate happypose
pip install -r requirements/base.txt

Example with uv

git clone --branch dev --recurse-submodules https://github.com/agimus-project/happypose.git
cd happypose
uv sync --extra pypi --extra cpu  # you *must* choose between cpu / cu124

Example with venv

git clone --branch dev --recurse-submodules https://github.com/agimus-project/happypose.git
cd happypose
python -m venv .venv
source .venv/bin/activate
pip install -r requirements/pypi.txt -r requirements/cpu.txt  # you *must* choose between cpu / cu124

Install extras:

• pypi: install pinocchio & opencv from PyPI (don't use this with conda)
• cpu: install torch for CPU from wheel (don't use this with conda)
• cu124: install torch for CUDA 12.4 from wheel (don't use this with conda)

Create data directory

Create data dir /somewhere/convenient. The dataset to store are quite large.
export HAPPYPOSE_DATA_DIR=/somewhere/convenient

Test the install

CPU

If you work on CPU, these models need to be download :

#hope dataset models for CosyPose
python -m happypose.toolbox.utils.download --cosypose_models \
            detector-bop-hope-pbr--15246 \
            coarse-bop-hope-pbr--225203 \
            refiner-bop-hope-pbr--955392

# For MegaPose
python -m happypose.toolbox.utils.download --megapose_models

and the examples

python -m happypose.toolbox.utils.download --examples barbecue-sauce

In the HappyPose folder:

pytest -v ./tests

You may need to install pytest-order : pip installp pytest-order. In this case, test related to the evaluation and the training of CosyPose are not run. If you want to use these functionalities, you need a GPU.

GPU

Tests related to evaluation and training will be run if a GPU is available. Hence, a few more downloads are needed :

#ycbv models
python -m happypose.toolbox.utils.download --cosypose_models \
            coarse-bop-ycbv-pbr--724183 \
            refiner-bop-ycbv-pbr--604090

python -m happypose.toolbox.utils.download --bop_dataset ycbv

python -m happypose.toolbox.utils.download --test-results

The tests take much longer in this case.