# camera_calib

**Repository Path**: rogers34/camera_calib

## Basic Information

- **Project Name**: camera_calib
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-08-19
- **Last Updated**: 2026-09-02

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fisheye camera intrinsic calibration (AprilGrid)

Standalone tool that detects AprilTags with the official `apriltag` C library
and runs `cv::fisheye::calibrate` to estimate the fisheye intrinsics
`(fx, fy, cx, cy)` and distortion `(k1, k2, k3, k4)`.

Dependencies: **OpenCV** + **libapriltag** only. No ROS, no kalibr, no boost,
no Eigen — `std::filesystem` is used for directory iteration.

## Install dependencies (Debian/Ubuntu)

```bash
sudo apt install libopencv-dev libapriltag-dev cmake g++
```

## Build

```bash
cd /home/rogers/code_ws/camera_calib
mkdir -p build && cd build
cmake ..
make -j
```

If OpenCV's CMake config isn't on the default search path, point cmake at it:

```bash
cmake .. -DOpenCV_DIR=/usr/lib/x86_64-linux-gnu/cmake/opencv4
```

## Run

All calibration parameters live in [`config/calib_config.yaml`](config/calib_config.yaml).
Edit that file (set `calibration.img_dir` to your image directory, tune the
target/detector/calibration flags), then:

```bash
# default: reads config/calib_config.yaml
./build/fisheye_calib

# explicit config file
./build/fisheye_calib --config path/to/my_config.yaml
```

A few CLI overrides are accepted for convenience — they apply **after** the YAML
is loaded, so they win over the file:

| option | meaning |
|---|---|
| `--config <yaml>` | config file (default `config/calib_config.yaml`) |
| `--img_dir <dir>` | override `calibration.img_dir` |
| `--visualize 0/1` | override `visualize` |
| `--show_undistort 0/1` | override `show_undistort` |

### Config file format (OpenCV YAML quirks)

The config is parsed with `cv::FileStorage`, whose YAML parser is a limited
subset. Two rules matter when editing `config/calib_config.yaml`:

- **The file must start with the `%YAML:1.0` header** (already present).
  Without it OpenCV rejects the file as "invalid".
- **Booleans must be `1` / `0`, not `true` / `false`.** OpenCV parses bare
  `true`/`false` as *strings*, and reading a non-empty string into a `bool`
  always yields `true` (so `fix_skew: false` would silently become `true`).
- **Comments must be on their own line.** There are no inline `#` comments —
  for string/bool values the `#...` would be absorbed into the value. (Numeric
  values happen to work because parsing stops at whitespace, but keep comments
  on their own line for consistency.)

Every key is optional: delete a key and the built-in default from `struct Config`
in `src/fisheye_calib.cpp` is used.

## Output

- stdout: a `camera_model_param` block in your config's style (copy-paste ready)
  plus `reprojection_error_rms` and the per-point average error.
- `fisheye_calib.yaml`: machine-readable (camera_matrix, distortion_coefficients,
  fx/fy/cx/cy, k1..k4, errors, used_files).
- `undistort_preview.png`: a rectified sample frame.

## How the 3D<->2D correspondences are built

Object points follow the Kalibr `GridCalibrationTargetAprilgrid` convention
exactly. The official `apriltag` library reports corners `p[0..3]` CCW starting
at the tag-local corner `(-1,-1)` — the same ordering the kalibr ethz_apriltag2
fork uses — so the pairing is consistent with Kalibr:

```
detected p[0..3] (CCW: bottom-left, bottom-right, top-right, top-left)
<-> world (x0,y0,0), (x0+s,y0,0), (x0+s,y0+s,0), (x0,y0+s,0)
x0 = col * s*(1+tag_spacing),  y0 = row * s*(1+tag_spacing),  id = row*tag_cols + col
```

> `tag_size`/`tag_spacing` only scale the extrinsic poses; the intrinsics are
> invariant to that scale. Still, set them to your real target for correct
> reprojection-error magnitudes.

## Notes

- Requires **apriltag >= 3.0** (uses `apriltag_detector_add_family`,
  `apriltag_detections_destroy`, `image_u8_t`). That is what `libapriltag-dev`
  ships on Ubuntu 20.04+.
- `std::filesystem` is used for directory iteration; on **gcc 7/8** add
  `-lstdc++fs` (handled automatically by CMakeLists.txt for gcc < 9).