checkboxer / npboxdetect

Fastest checkbox detector. NumPy + Numba. No deep learning.

Benchmark

50-run p50, full pipeline including imread, on 2200×1700 document images.

Pure processing (imread excluded):

Usage

from npboxdetect.detector import get_boxes

boxes = get_boxes("form.png")
# [(x, y, w, h), ...]

How it works

Five steps, all near-hardware-limit:

downsample 2x        ~0ms   stride view, zero copy
otsu + threshold      1.4ms  fused numba: histogram → binarize in one shot
morph open            1.3ms  numba parallel run-length scan (rows+cols)
connected components  1.3ms  cv2.connectedComponentsWithStats
NMS                   0.2ms  vectorized pairwise IoU matrix
─────────────────────────────
processing total      ~6ms

Key ideas:

• 2x downsample before processing — free stride view, halves pixel count
• Fused numba otsu+threshold — one serial histogram pass + one parallel binarize pass, no cv2 call
• Run-length morph open — each row/column independent → prange parallelism, no cumsum overhead
• Filter before NMS — size/ratio filter drops 1000+ blobs to ~70 before NMS

Install

git clone https://github.com/santhoshkammari/checkboxer
cd checkboxer
pip install numba opencv-python numpy

Journey

See JOURNEY.md (v0→v6, 4248ms→37ms) and JOURNEY2.md (v7→v10, 37ms→6ms).

Author

santhoshkammari