# Behavioral Imaging Toolbox
Bitbox is a free and open-source Python library including a comprehensive set of tools for the computational analysis of nonverbal human behavior. The provided tools enable analysis of face, head, and body movements, expressions, and actions from videos and images. Included algorithms and metrics have been validated using clinically vetted datasets and published extensively, therefore, can be reliably used by behavioral, social, and medical scientists in their human subject research. As we closely follow state-of-the-art in computer vision and machine learning, provided methodologies can also be relied upon by computer vision researchers and other engineers as well.
Please refer to our [Wiki](https://github.com/compsygroup/bitbox/wiki) for further details.
## Installation
Bitbox itself has minimum requirements, but it relies on face/body backends to generate expression/movement signals. These backends usually have more requirements. We highly recommend using our Docker images to install these backends as installing them from source code may prove difficult for some. **Unfortunately, for currently supported backends, you need NVIDIA GPUs.** New backends with CPU support are coming soon.
The current version of Bitbox supports two face backends, namely 3DI and 3DI-lite. While 3DI provides more detailed outputs (e.g., full 3D model of the face), 3DI-lite is much faster and more robust to occlusions, etc. If your images don't have significant occlusions and you don't need a faster solution, we recommend using 3DI.
### Installing Face Backends Using Docker (Recommended)
Using Docker is usually very straightforward; however, 3DI requires downloading an external face model (you need to register individually and request access) and updating our image with this model.
1. Download the Dockerfile. We have two options for [CUDA 11.8.0](https://raw.githubusercontent.com/compsygroup/bitbox/refs/heads/main/docker/cuda11.8_cv4.5/Dockerfile) or [CUDA 12.2.2](https://raw.githubusercontent.com/compsygroup/bitbox/refs/heads/main/docker/cuda12.2_cv4.8/Dockerfile). Select the one that is most compatible with your NVIDIA GPU.
2. Register and download the [face model](https://faces.dmi.unibas.ch/bfm/index.php?nav=1-2&id=downloads). Unfortunately this may take some time. We cannot help with this step.
3. Place the Dockerfile and the face model you downloaded (`01_MorphableModel.mat`) in the same directory
4. Within this directory, run the following command build the image
```bash
docker build -t bitbox:latest .
```
The first parameter `bitbox:latest` is the name of the image to be created. You can change it if you wish. Please don't forget the `.` at the end.
5. That's it! You will also need to set an environment variable `BITBOX_DOCKER`, which will be explained below.
### Installing Face Backends Natively (Not Recommended)
**The recommended way to install backends is to use our Docker images** as explained above. If you can install C++/CUDA codes from the source code, however, please go ahead and install 3DI from [here](https://github.com/compsygroup/3DI). The instructions are provided there. This approach will install the 3DI as a native application on your system and can be slightly faster than using Docker.
Similarly, 3DI-lite can be installed from ... (COMING SOON)
### Installing Bitbox
To install Bitbox, follow these steps. **You will need to use python 3.8 or higher**.
1. Create a virtual environment and activate it:
```bash
python3.8 -m venv env
source env/bin/activate
```
Note that this will create a virtual environment named `env` in the current directory. You can use any name, and you can install the virtual environment anywhere you like. Just don't forget where you installed it. For the following steps, we will assume you have activated the virtual environment.
2. Clone the Bitbox repository:
```bash
git clone https://github.com/compsygroup/bitbox.git
```
3. Change to the Bitbox directory:
```bash
cd bitbox
```
4. Install requirements:
```bash
pip install --upgrade pip
pip install -r requirements.txt
```
5. Install Bitbox using `python setup.py install`:
```bash
python setup.py install
```
6. If you are not using Docker, set the environment variable `BITBOX_3DI` to indicate the directory in which 3DI was installed. We recommend setting it in .bahsrc (on Linux/Mac) or in System's Environment Variables (on Windows).
- **Linux**:
```bash
export BITBOX_3DI=/path/to/3DI/directory
```
- **Windows** (Command Prompt):
```bash
set BITBOX_3DI=C:\path\to\3DI\directory
```
- **Mac**:
```bash
export BITBOX_3DI=/path/to/3DI/directory
```
7. If you are using Docker, set the environment variable `BITBOX_DOCKER` to indicate the 3DI image name/tag. Change the image name/tag if needed. We recommend setting it in .bahsrc (on Linux/Mac) or in System's Environment Variables (on Windows).
- **Linux**:
```bash
export BITBOX_DOCKER=bitbox:latest
```
- **Windows** (Command Prompt):
```bash
set BITBOX_DOCKER=bitbox:latest
```
- **Mac**:
```bash
export BITBOX_DOCKER=bitbox:latest
```
Now you are ready to use Bitbox!
## Use
Once you are done with installation, you can use Bitbox by
1. Activate the virtual environment you created for Bitbox:
```bash
source env/bin/activate
```
2. Set the environment variable `BITBOX_3DI` or `DOCKER_BITBOX` if you have not set them already in .bahsrc (on Linux/Mac) or in System's Environment Variables (on Windows). If you did that you can skip this step.
3. Import the library in your Python code:
```python
from bitbox.face_backend import FaceProcessor3DI
```
### Example Usage
```python
from bitbox.face_backend import FaceProcessor3DI as FP
input_file = 'data/elaine.mp4'
output_dir = 'output'
# define a face processor
processor = FP()
# set input and output
processor.io(input_file=input_file, output_dir=output_dir)
# detect faces
rects = processor.detect_faces()
# detect landmarks
lands = processor.detect_landmarks()
# compute global expressions
exp_global, pose, lands_can = processor.fit()
# compute localized expressions
exp_local = processor.localized_expressions()
```
Raw data
{
"_id": null,
"home_page": null,
"name": "bitbox",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "ComPsy Group <tuncb@chop.edu>",
"keywords": "behavior, body actions, computer vision, facial expressions, psychiatry, psychology",
"author": null,
"author_email": "ComPsy Group <tuncb@chop.edu>",
"download_url": "https://files.pythonhosted.org/packages/63/46/014d524430dc18401bd4b2947013ac27960b9c07d2becec42e378ef3236d/bitbox-2025.7.dev0.tar.gz",
"platform": null,
"description": "# Behavioral Imaging Toolbox\n\nBitbox is a free and open-source Python library including a comprehensive set of tools for the computational analysis of nonverbal human behavior. The provided tools enable analysis of face, head, and body movements, expressions, and actions from videos and images. Included algorithms and metrics have been validated using clinically vetted datasets and published extensively, therefore, can be reliably used by behavioral, social, and medical scientists in their human subject research. As we closely follow state-of-the-art in computer vision and machine learning, provided methodologies can also be relied upon by computer vision researchers and other engineers as well.\n\nPlease refer to our [Wiki](https://github.com/compsygroup/bitbox/wiki) for further details.\n\n## Installation\n\nBitbox itself has minimum requirements, but it relies on face/body backends to generate expression/movement signals. These backends usually have more requirements. We highly recommend using our Docker images to install these backends as installing them from source code may prove difficult for some. **Unfortunately, for currently supported backends, you need NVIDIA GPUs.** New backends with CPU support are coming soon. \n\nThe current version of Bitbox supports two face backends, namely 3DI and 3DI-lite. While 3DI provides more detailed outputs (e.g., full 3D model of the face), 3DI-lite is much faster and more robust to occlusions, etc. If your images don't have significant occlusions and you don't need a faster solution, we recommend using 3DI. \n\n### Installing Face Backends Using Docker (Recommended)\nUsing Docker is usually very straightforward; however, 3DI requires downloading an external face model (you need to register individually and request access) and updating our image with this model.\n\n1. Download the Dockerfile. We have two options for [CUDA 11.8.0](https://raw.githubusercontent.com/compsygroup/bitbox/refs/heads/main/docker/cuda11.8_cv4.5/Dockerfile) or [CUDA 12.2.2](https://raw.githubusercontent.com/compsygroup/bitbox/refs/heads/main/docker/cuda12.2_cv4.8/Dockerfile). Select the one that is most compatible with your NVIDIA GPU.\n2. Register and download the [face model](https://faces.dmi.unibas.ch/bfm/index.php?nav=1-2&id=downloads). Unfortunately this may take some time. We cannot help with this step.\n3. Place the Dockerfile and the face model you downloaded (`01_MorphableModel.mat`) in the same directory\n4. Within this directory, run the following command build the image\n ```bash\n docker build -t bitbox:latest . \n ```\n The first parameter `bitbox:latest` is the name of the image to be created. You can change it if you wish. Please don't forget the `.` at the end. \n5. That's it! You will also need to set an environment variable `BITBOX_DOCKER`, which will be explained below.\n\n### Installing Face Backends Natively (Not Recommended)\n**The recommended way to install backends is to use our Docker images** as explained above. If you can install C++/CUDA codes from the source code, however, please go ahead and install 3DI from [here](https://github.com/compsygroup/3DI). The instructions are provided there. This approach will install the 3DI as a native application on your system and can be slightly faster than using Docker.\n\nSimilarly, 3DI-lite can be installed from ... (COMING SOON)\n\n### Installing Bitbox\nTo install Bitbox, follow these steps. **You will need to use python 3.8 or higher**. \n\n1. Create a virtual environment and activate it:\n ```bash\n python3.8 -m venv env\n source env/bin/activate\n ```\n Note that this will create a virtual environment named `env` in the current directory. You can use any name, and you can install the virtual environment anywhere you like. Just don't forget where you installed it. For the following steps, we will assume you have activated the virtual environment.\n\n2. Clone the Bitbox repository:\n ```bash\n git clone https://github.com/compsygroup/bitbox.git\n ```\n\n3. Change to the Bitbox directory:\n ```bash\n cd bitbox\n ```\n\n4. Install requirements:\n ```bash\n pip install --upgrade pip\n pip install -r requirements.txt\n ```\n\n5. Install Bitbox using `python setup.py install`:\n ```bash\n python setup.py install\n ```\n\n6. If you are not using Docker, set the environment variable `BITBOX_3DI` to indicate the directory in which 3DI was installed. We recommend setting it in .bahsrc (on Linux/Mac) or in System's Environment Variables (on Windows).\n\n - **Linux**:\n ```bash\n export BITBOX_3DI=/path/to/3DI/directory\n ```\n\n - **Windows** (Command Prompt):\n ```bash\n set BITBOX_3DI=C:\\path\\to\\3DI\\directory\n ```\n\n - **Mac**:\n ```bash\n export BITBOX_3DI=/path/to/3DI/directory\n ```\n\n7. If you are using Docker, set the environment variable `BITBOX_DOCKER` to indicate the 3DI image name/tag. Change the image name/tag if needed. We recommend setting it in .bahsrc (on Linux/Mac) or in System's Environment Variables (on Windows).\n\n - **Linux**:\n ```bash\n export BITBOX_DOCKER=bitbox:latest\n ```\n\n - **Windows** (Command Prompt):\n ```bash\n set BITBOX_DOCKER=bitbox:latest\n ```\n\n - **Mac**:\n ```bash\n export BITBOX_DOCKER=bitbox:latest\n ```\n\nNow you are ready to use Bitbox!\n\n## Use\n\nOnce you are done with installation, you can use Bitbox by\n\n1. Activate the virtual environment you created for Bitbox:\n ```bash\n source env/bin/activate\n ```\n2. Set the environment variable `BITBOX_3DI` or `DOCKER_BITBOX` if you have not set them already in .bahsrc (on Linux/Mac) or in System's Environment Variables (on Windows). If you did that you can skip this step.\n\n3. Import the library in your Python code:\n ```python\nfrom bitbox.face_backend import FaceProcessor3DI\n ```\n\n### Example Usage\n\n ```python\nfrom bitbox.face_backend import FaceProcessor3DI as FP\n\ninput_file = 'data/elaine.mp4'\noutput_dir = 'output'\n\n# define a face processor\nprocessor = FP()\n\n# set input and output\nprocessor.io(input_file=input_file, output_dir=output_dir)\n\n# detect faces\nrects = processor.detect_faces()\n\n# detect landmarks\nlands = processor.detect_landmarks()\n\n# compute global expressions\nexp_global, pose, lands_can = processor.fit()\n\n# compute localized expressions\nexp_local = processor.localized_expressions()\n ```\n\n",
"bugtrack_url": null,
"license": "Creative Commons Attribution-NonCommercial 4.0 International",
"summary": "Behavioral Imaging Toolbox",
"version": "2025.7.dev0",
"project_urls": {
"Documentation": "https://github.com/compsygroup/bitbox/wiki",
"Homepage": "https://github.com/compsygroup/bitbox",
"Issues": "https://github.com/compsygroup/bitbox/issues"
},
"split_keywords": [
"behavior",
" body actions",
" computer vision",
" facial expressions",
" psychiatry",
" psychology"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "30788a442a812c8afcd967cc85f82a5ef5257ed230ea2a669830c118b7d534d4",
"md5": "fdddc8b81cbe1f11b7f08647cba28ab4",
"sha256": "715390d13148a38c6889ca5d9361358727027eb801f4fd521f4c0d7555cb2ce6"
},
"downloads": -1,
"filename": "bitbox-2025.7.dev0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fdddc8b81cbe1f11b7f08647cba28ab4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 28953,
"upload_time": "2025-07-08T21:06:30",
"upload_time_iso_8601": "2025-07-08T21:06:30.714332Z",
"url": "https://files.pythonhosted.org/packages/30/78/8a442a812c8afcd967cc85f82a5ef5257ed230ea2a669830c118b7d534d4/bitbox-2025.7.dev0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "6346014d524430dc18401bd4b2947013ac27960b9c07d2becec42e378ef3236d",
"md5": "befca85531b5e85a8227529ca18a8485",
"sha256": "4e763f3cac5aa5e76648d810b2e9a025b34dac6c3c915f9cc4bdccbd3c30083c"
},
"downloads": -1,
"filename": "bitbox-2025.7.dev0.tar.gz",
"has_sig": false,
"md5_digest": "befca85531b5e85a8227529ca18a8485",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 3031188,
"upload_time": "2025-07-08T21:06:32",
"upload_time_iso_8601": "2025-07-08T21:06:32.086531Z",
"url": "https://files.pythonhosted.org/packages/63/46/014d524430dc18401bd4b2947013ac27960b9c07d2becec42e378ef3236d/bitbox-2025.7.dev0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-07-08 21:06:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "compsygroup",
"github_project": "bitbox",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "scipy",
"specs": [
[
">=",
"1.10"
]
]
},
{
"name": "cvxpy",
"specs": [
[
">=",
"1.4"
]
]
},
{
"name": "numpy",
"specs": []
},
{
"name": "scikit-learn",
"specs": []
},
{
"name": "python-dateutil",
"specs": []
},
{
"name": "PyWavelets",
"specs": []
},
{
"name": "matplotlib",
"specs": []
},
{
"name": "pandas",
"specs": []
}
],
"lcname": "bitbox"
}
JSON
