Skip to content

Moving calibrate.py from the depthai to depthai-core #1578

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
MaticTonin wants to merge 6 commits into
base: develop
Choose a base branch
from
Open

Moving calibrate.py from the depthai to depthai-core #1578

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
378dac2
Add depthai-boards and depthai-calibration as submodule
MaticTonin Dec 8, 2025
14c5383
Add calibrate.py
MaticTonin Dec 8, 2025
1653a70
Fixing sync issue with RVC2 devices
MaticTonin Jan 7, 2026
33f392e
Update depthai_boards
MaticTonin Jan 7, 2026
e32a9ee
Update depthai-boards to latest housing included boards
MaticTonin Jan 7, 2026
1eabbe9
Add comments to readme
MaticTonin Jan 7, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .gitmodules
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,3 +16,9 @@
[submodule "3rdparty/ws-protocol"]
path = 3rdparty/foxglove/ws-protocol
url = https://github.com/luxonis/ws-protocol.git
[submodule "shared/depthai_boards"]
path = shared/depthai_boards
url = https://github.com/luxonis/depthai-boards
[submodule "shared/depthai_calibration"]
path = shared/depthai_calibration
url = https://github.com/luxonis/depthai-calibration
1 change: 1 addition & 0 deletions shared/depthai_boards
Open in desktop
Submodule depthai_boards added at 1dda9d
1 change: 1 addition & 0 deletions shared/depthai_calibration
Open in desktop
Submodule depthai_calibration added at b18ab9
101 changes: 100 additions & 1 deletion utilities/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -48,4 +48,103 @@ To build a bundled executable issue the following command:
pyinstaller -w cam_test.py --hidden-import PyQt5.sip
```

The executable will be located in `dist/cam_test` folder.
The executable will be located in `dist/cam_test`.

---

# DepthAI Manual Calibration Instructions

## Manual Camera Calibration with `calibrate.py`

DepthAI devices can be (re-)calibrated using the `calibrate.py` utility from the **depthai-core** repository. This tool captures **Charuco board** images and computes intrinsic and extrinsic calibration parameters for your camera configuration.

> ⚠️ Most OAK devices are factory calibrated. Manual calibration is mainly required for **Modular cameras** (e.g. OAK-FFC series), custom lenses, or non-standard mechanical mounts.

---

## Prerequisites

Before running calibration, install all required Python dependencies listed in `calib_requirements.txt`.

```bash
# Clone depthai-core (if not already cloned)
git clone https://github.com/luxonis/depthai-core.git
cd depthai-core
git submodule update --init --recursive

# Install calibration dependencies
python3 -m pip install -r utilities/calib_requirements.txt
```

---

## Running the Calibration Script

### 1. Prepare the Charuco Board

- Print or display a Charuco board on a **flat surface or screen**
- Measure the **square size in centimeters** accurately
- Know the number of squares in X and Y direction

These values are required by the calibration script.

---

### 2. Capture Calibration Images

```bash
python3 utilities/calibrate.py \
--board <BOARD_NAME_OR_JSON_PATH> \
--squareSizeCm <SQUARE_SIZE_IN_CM> \
--squaresX <NX> \
--squaresY <NY>
```

- `<BOARD_NAME_OR_JSON_PATH>` may be:
- A predefined board name, or
- A custom JSON board configuration file
- The script runs interactively and guides you through image capture

---

### 3. Process Previously Captured Images (Optional)

If images were already captured, run calibration only:

```bash
python3 utilities/calibrate.py \
--board <BOARD_NAME_OR_JSON_PATH> \
--squareSizeCm <SQUARE_SIZE_IN_CM> \
--squaresX <NX> \
--squaresY <NY> \
-m process
```

---

## Helpful Tips

- Use `python3 utilities/calibrate.py --help` to see all available options
- Move the camera through **varied angles and distances**
- Ensure **even lighting** and avoid glare or reflections
- Cover the **entire field of view**, including image corners

---

## Calibration Output

After a successful run, the calibration tool will:

- Save calibration files to the `resources/` directory
- Optionally **flash calibration data to the device EEPROM**
- Output reprojection and epipolar error statistics for quality assessment

If calibration fails:
- Verify Charuco board dimensions
- Double-check `--squareSizeCm`
- Improve lighting and marker visibility

---

For official documentation, see:
https://docs.luxonis.com/hardware/platform/depth/manual-calibration/
10 changes: 10 additions & 0 deletions utilities/calib_requirements.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
requests==2.26.0
--extra-index-url https://www.piwheels.org/simple
numpy>=1.21.4,<2.0.0 # For RPi Buster (last successful build) and macOS M1 (first build). But allow for higher versions, to support Python3.11 (not available in 1.21.4 yet)
opencv-contrib-python==4.5.5.62 # Last successful RPi build, also covers M1 with above pinned numpy (otherwise 4.6.0.62 would be required, but that has a bug with charuco boards). Python version not important, abi3 wheels
--extra-index-url https://artifacts.luxonis.com/artifactory/luxonis-depthai-data-local/wheels/
pyqt5>5,<5.15.6 ; platform_machine != "armv6l" and platform_machine != "armv7l" and platform_machine != "aarch64" and platform_machine != "arm64"
depthai
Qt.py
scipy
matplotlib
Loading