🚀 Getting Started#

Installing pyppbox is very easy and straightforward. You can install it from PyPI directly or use the prebuilt .whl files on GitHub releases or install from GitHub directly or build it from source on your own machine. However, in order to get it work, you need to install all the necessary dependencies or requirements for the modules you need.

⚙️ Requirements#

YOLO_Classic uses OpenCV DNN to load Darknet .cfg/.weights models and requires OpenCV 4.x. OpenCV 5 removed the Darknet importer, so pyppbox requires opencv-contrib-python<5 to preserve existing models and configurations. For GPU (CUDA) support, use a compatible OpenCV 4.x build from source or our pyppbox-opencv; the official opencv-contrib-python wheels provide CPU support only.

Prerequisite:
- Python [3.9-3.12] (For macOS GUI troubleshooting, try Python 3.11)
- Local pyppbox repo: git clone https://github.com/rathaumons/pyppbox.git
Before you install dependencies/requirements:
- For Linux, recommend changing python3 to python: sudo apt install python-is-python3
- If you prefer conda + Python [3.9-3.12]: conda create --name pyppbox_env python=3.11 Then activate it with conda activate pyppbox_env before installing packages.
- Upgrade pip and setuptools:
```
python -m pip install --upgrade pip
pip install "setuptools>=67.8.0"
```
- Recommend removing the official ultralytics:
```
pip uninstall -y ultralytics
```
Install dependencies/requirements under pyppbox/requirements/:
- For CPU-only on any platform, skip this and go straight to Setup section below.
- For GPU (CUDA) on Windows:
  - Run the cmd installer install_req_py3_cuda121.cmd (Or install_req_py3_cuda.cmd for CUDA 11.8)
  - These scripts install CUDA-enabled PyTorch. FaceNet and DeepSORT use TensorFlow: native Windows GPU support ended with TensorFlow 2.10. For newer TensorFlow GPU builds, follow the official Linux/WSL2 instructions; installing CUDA-enabled PyTorch does not enable TensorFlow GPU support.
- For GPU (CUDA) on Linux:
  - Install the CUDA version of TensorFlow and PyTorch.
  - Install the requirements.txt:
    python -m pip install -r requirements/requirements.txt
- For GPU (CUDA) on macOS:
  - Not available
(Optional) For GPU-Only (CUDA) -> Verify the installed dependencies:
- Execute the test_gpu.py
  - From the repository root on Windows -> requirements\test_gpu.cmd
  - From the repository root on Linux -> python requirements/test_gpu.py
- If there is no error, then you are all good and ready to go.
- For OpenCV, the official opencv-contrib-python (No GPU support) is set in the requirements.txt file. If you need GPU support, check our pyppbox-opencv or build one from source by yourself.

💽 Setup#

You need to install the main package which is pyppbox and the data for the modules you need pyppbox-data-xxx. If you want to have some fun with the demo on our GTA_V_DATASET, you also need to install pyppbox-data-gta5.

Install pyppbox
- Use the latest .whl from releases or install from PyPI:
```
pip install pyppbox
```
- Or install directly from GitHub:
```
pip install git+https://github.com/rathaumons/pyppbox.git
```
- Or build from source:
```
pip install setuptools wheel build PyYAML
python -m build --wheel --skip-dependency-check --no-isolation
```
  Run these commands from the repository root, then install the generated wheel in dist/ with python -m pip install followed by its path.

Install pyppbox-data-xxx

Download the latest from releases or install the ones you need directly:

pip install https://github.com/rathaumons/pyppbox-data/releases/download/v1.4.0/pyppbox_data_yolocls-1.4.0-py3-none-any.whl
pip install https://github.com/rathaumons/pyppbox-data/releases/download/v1.4.0/pyppbox_data_yoloult-1.4.0-py3-none-any.whl
pip install https://github.com/rathaumons/pyppbox-data/releases/download/v1.4.0/pyppbox_data_deepsort-1.4.0-py3-none-any.whl
pip install https://github.com/rathaumons/pyppbox-data/releases/download/v1.4.0/pyppbox_data_facenet-1.4.0-py3-none-any.whl
pip install https://github.com/rathaumons/pyppbox-data/releases/download/v1.4.0/pyppbox_data_torchreid-1.4.0-py3-none-any.whl

Install pyppbox-data-gta5

Download the latest from releases or install directly:

pip install https://github.com/numediart/PoseTReID_DATASET/releases/download/v2.0/pyppbox_data_gta5-2.0-py3-none-any.whl

Quick Test
- In your Python terminal:
```
import pyppbox
pyppbox.launchGUI()
```
  Now you should see the GUI demo like this screenshot:
- For related GUI functions and other configurations, check the Configurations page.
- Check the Examples page for some real coding!
- ⚠️ ATTENTION ⚠️
  - If you use YOLO Ultralytics without GPU/CUDA, you must set cpu as string for the parameter device in its configuration.
  - The same for Torchreid without GPU/CUDA, you must set cpu as string for the parameter device in its configuration.
Troubleshooting
- If loading a ReID classifier reports InconsistentVersionWarning, recreate the environment used to train it or retrain it in the current environment. Scikit-learn does not support loading models across different versions. Example 12 retrains the bundled GTA V classifiers and overwrites their configured .pkl files.
- For macOS, if the GUI does not work, you may try Python 3.11 as suggested in Prerequisite section above.
- For Linux, if the GUI does not work, you might need to install these:
```
sudo apt-get install '^libxcb.*-dev' libx11-xcb-dev libglu1-mesa-dev libxrender-dev libxi-dev libxkbcommon-dev libxkbcommon-x11-dev
```
- For Ubuntu on WSL 2, you need to install these:
```
sudo apt-get install libgl1-mesa-glx xdg-utils libegl1
```

📢 FYI#

1️⃣ Customized OpenCV#

OpenCV is widely used in many well-known packages, but the majority of the prebuilt WHLs on the Internet including the official one on PyPI do not include GPU support. Thus, we build our custom one which includes NVIDIA CUDA & cuDNN supports for the OpenCV DNN module. In order to well distinguish from the rest, we decided to build and change the package name from opencv-contrib-python to pyppbox-opencv -> [Repo] [WHL]

2️⃣ Customized Torchreid#

Similar to pyppbox-opencv, our custom torchreid is changed to pyppbox-torchreid. More than the normal package rename, the module name is also changed from torchreid to pyppbox_torchreid which means the import in the code must be also changed. Find out more why pyppbox needs the customized pyppbox-torchreid -> [Repo] [PyPI]

3️⃣ Customized Ultralytics#

The current requirements file installs vsensebox-ultralytics, which provides the ultralytics import used by pyppbox. It shares that import namespace with the official ultralytics distribution, so avoid installing both in the same environment.

pyppbox-ultralytics was the earlier distribution. Use the dependency specified by the requirements file for your pyppbox release. Using the current Ultralytics fork does not require the vsensebox framework.