| # Macbeth Chart Detector |
|
|
| Detects a Macbeth / ColorChecker Classic colour chart in a photograph and returns its bounding |
| box. This is the detection model used by OpenCV's `mcc` colour-correction code |
| (`objdetect`, `checker_detector.cpp`) to locate a chart before reading its patches. |
|
|
| The model is a Faster R-CNN with an Inception V2 backbone, trained as a single-class detector |
| with the TensorFlow Object Detection API. It was originally distributed as a frozen TensorFlow |
| graph (`frozen_inference_graph.pb`) and converted to ONNX for use with OpenCV's DNN module. |
|
|
| ## Model Details |
| - **Architecture**: Faster R-CNN, Inception V2 backbone, one class (the chart) |
| - **Input**: `image_tensor:0`, **NHWC** `[1, H, W, 3]`, **raw uint8 RGB** (0-255, no scaling and |
| no mean subtraction). `H`/`W` are dynamic — feed the image at its own resolution. The graph |
| resizes internally (keep aspect ratio, min side 768, max side 1024), so do not pre-resize, |
| and do not use `blobFromImage`: that produces NCHW. |
| - **Outputs** (all four must be requested together): |
| - `detection_boxes:0` — `[1, 300, 4]`, normalized, **`[ymin, xmin, ymax, xmax]`** (y first) |
| - `detection_scores:0` — `[1, 300]`, descending |
| - `detection_classes:0` — `[1, 300]`, always `1.0` (single class, so it carries no information) |
| - `num_detections:0` — `[1]` |
| - **Framework**: ONNX (converted from the TensorFlow frozen graph via tf2onnx, opset 18) |
| - **Original weights**: [gursimarsingh/opencv_zoo @ `mcc_model`](https://github.com/gursimarsingh/opencv_zoo/tree/mcc_model/models/macbeth_chart_detector) |
| — `frozen_inference_graph.pb`, sha1 `fae7dbef14c4ae1fca76f3662220fbd460ed5ed6` |
|
|
| > **`num_detections` is not a detection count.** It reports the post-NMS slot count — 100 on the |
| > example image, where exactly one chart is present. Threshold on `detection_scores` instead; |
| > iterating `num_detections` yields 99 phantom boxes. |
| |
| ## Usage |
| |
| ### Python |
| ```bash |
| python demo.py --model macbeth_chart_detector_2026sep.onnx --image example_outputs/input_image.png --output example_outputs/output_image.png --conf 0.3 |
| ``` |
| |
| On the provided `example_outputs/input_image.png` (900x463) it reports one detection: |
| |
| ``` |
| macbeth_chart_detector 1 detections |
| 0.582 x1=237 y1=79 x2=650 y2=368 |
| ``` |
| |
| `demo.py` requires OpenCV 5.1 or newer, for `cv.dnn.ENGINE_OPENCV`. On OpenCV 5.0 that constant |
| does not exist (it has `ENGINE_CLASSIC` / `ENGINE_NEW`); drop the second argument to |
| `readNetFromONNX` to use the default engine instead. |
| |
| ## Conversion |
| |
| Exported from the frozen TensorFlow graph with tf2onnx (opset 18) via |
| [convert_to_onnx.py](./convert_to_onnx.py) — input `image_tensor:0`, outputs |
| `detection_boxes:0`, `detection_scores:0`, `detection_classes:0`, `num_detections:0`. |
| Requires `tensorflow`, `tf2onnx` and `onnx`. |
| |
| ```bash |
| python convert_to_onnx.py --pb frozen_inference_graph.pb |
| ``` |
| |
| The graph needs no special handling: its weights are plain float32 (no `quantize_weights` / |
| `Dequantize` nodes) and all four detection heads are present in the frozen graph. |
| |
| ### Conversion accuracy |
| |
| Verified against the original `.pb` under TensorFlow 2.15.1, feeding both the identical uint8 |
| buffer: |
| |
| | | top score | box | |
| |---|---|---| |
| | TensorFlow `.pb` | 0.582205 | `0.171078 0.263475 0.794357 0.721806` | |
| | ONNX (onnxruntime) | 0.582205 | `0.171078 0.263475 0.794356 0.721806` | |
| |
| The conversion is faithful to within one float32 ULP. |
| |
| ## Known issue: OpenCV's DNN engine |
| |
| The conversion is correct, but **OpenCV's built-in DNN engine cannot currently run this model.** |
| On OpenCV 5.0.0 it aborts before producing output: |
| |
| ``` |
| net_impl2.cpp: (-215:Assertion failed) buf.shape() == m.shape() in function 'forwardGraph' |
| ``` |
| |
| The same failure affects the other converted Faster R-CNN / Mask R-CNN models in this |
| repository, so it is a limitation of the engine's handling of these graphs rather than |
| something specific to this model. On builds where the graph does run, the score comes out |
| around 0.02 instead of 0.582, because `Resize` with |
| `coordinate_transformation_mode="tf_crop_and_resize"` and a dynamic ROI — the ROI-pooling step |
| of the second stage — is not evaluated correctly, so every region proposal is classified from |
| the wrong features. |
| |
| Until that is fixed in `modules/dnn`, treat the ONNX file as correct (onnxruntime and |
| TensorFlow agree exactly) and the OpenCV-engine results as unreliable. |
| |
| ## License |
| See [LICENSE](./LICENSE) — Apache License 2.0, taken from the upstream |
| [opencv_zoo](https://github.com/gursimarsingh/opencv_zoo) repository that distributes the |
| original frozen graph. |
| |
