"""Post-processing utilities for detector outputs."""
import cv2
import numpy as np
import pyclipper
import torch
from shapely.geometry import Polygon
from torch import Tensor
from .models.detection import DBNetOutput
from .ops import order_quad_vertices, reading_order
[docs]
class DBPostProcessor:
"""Extract per-region bounding boxes from DBNet probability maps.
Implements PaddleOCR's contour-based DB post-processing flow:
threshold the probability map, run :func:`cv2.findContours`, fit
a rotated minimum-area rectangle to each contour, score it by
averaging the probability map under the rectangle mask, expand
the polygon outward by ``unclip_ratio`` via :mod:`pyclipper`, and
refit the rectangle. Boxes whose score is below ``box_thresh`` or
whose minor side is below ``min_size`` are discarded.
Calling the processor projects the rotated rectangles to
axis-aligned ``(x1, y1, x2, y2)`` boxes (the v0.1 contract);
:meth:`quadrilaterals` returns the rotated quads themselves.
The output is shaped ``(K, 5)`` with columns
``[batch_idx, x1, y1, x2, y2]`` so it composes directly with
:func:`torchvision.ops.roi_align`. ``K`` is the *total* number of
accepted boxes across the batch (not capped at one per image).
Coordinates are floats in input-pixel units, with ``x2``/``y2``
being inclusive (``x2 = x1`` is a one-pixel-wide column) to match
the convention of :func:`torchvision.ops.masks_to_boxes`.
Note:
``cv2`` and ``pyclipper`` run on CPU. GPU probability maps are
moved to CPU for processing, then the resulting box tensor is
placed back on the original device.
Args:
threshold: Probability threshold for binarization. Default 0.3,
matching PaddleOCR.
box_thresh: Minimum mean probability under a candidate box for
it to be kept. Default 0.7.
max_candidates: Maximum number of contours examined per image.
Default 1000.
unclip_ratio: Polygon expansion ratio used by
:func:`pyclipper.PyclipperOffset.Execute`. Default 1.5
(matches PaddleOCR v2 weights). Larger values produce
looser boxes.
min_size: Reject candidates whose minor rotated-rectangle side
is below this many pixels. Default 3.
"""
def __init__(
self,
threshold: float = 0.3,
box_thresh: float = 0.7,
max_candidates: int = 1000,
unclip_ratio: float = 1.5,
min_size: int = 3,
) -> None:
if not 0.0 <= threshold <= 1.0:
raise ValueError(f"threshold must lie in [0, 1]; got {threshold}.")
if not 0.0 <= box_thresh <= 1.0:
raise ValueError(f"box_thresh must lie in [0, 1]; got {box_thresh}.")
if max_candidates <= 0:
raise ValueError(f"max_candidates must be positive; got {max_candidates}.")
if unclip_ratio <= 0:
raise ValueError(f"unclip_ratio must be positive; got {unclip_ratio}.")
if min_size < 1:
raise ValueError(f"min_size must be >= 1; got {min_size}.")
self.threshold = threshold
self.box_thresh = box_thresh
self.max_candidates = max_candidates
self.unclip_ratio = unclip_ratio
self.min_size = min_size
def __call__(self, output: DBNetOutput) -> Tensor:
"""Return ``(K, 5)`` ``[batch_idx, x1, y1, x2, y2]`` axis-aligned boxes, each image's in reading order."""
device = output.probability.device
rows = [
torch.cat([torch.full((quads.shape[0], 1), float(batch_idx)), quads.amin(1), quads.amax(1)], dim=1)
for batch_idx, quads in enumerate(q[reading_order(q)] for q in self._quadrilaterals_cpu(output))
]
return torch.cat(rows).to(device) if rows else torch.zeros((0, 5), device=device)
[docs]
def quadrilaterals(self, output: DBNetOutput) -> list[Tensor]:
"""Return one ``(N_b, 4, 2)`` tensor of rotated text quads per image.
Regions are sorted in reading order (:func:`torchocr.ops.reading_order`:
lines top to bottom, words left to right). Vertices are ``(x, y)``
input-pixel coordinates clipped to the page, ordered top-left,
top-right, bottom-right, bottom-left so they feed
:func:`torchocr.ops.crop_quads`. Unlike
:meth:`__call__`, the rotation of each region is preserved, which
is what polygon-based benchmarks such as ICDAR-2015 score.
"""
device = output.probability.device
ordered = [order_quad_vertices(quads) for quads in self._quadrilaterals_cpu(output)]
return [quads[reading_order(quads)].to(device) for quads in ordered]
def _quadrilaterals_cpu(self, output: DBNetOutput) -> list[Tensor]:
probability = output.probability
if probability.ndim != 4 or probability.shape[1] != 1:
raise ValueError(
f"Expected probability of shape (B, 1, H, W); got {tuple(probability.shape)}."
)
prob_np = probability[:, 0].detach().cpu().numpy()
per_image: list[Tensor] = []
for page in prob_np:
h, w = page.shape
mask = (page > self.threshold).astype(np.uint8) * 255
contours, _ = cv2.findContours(mask, cv2.RETR_LIST, cv2.CHAIN_APPROX_SIMPLE)
quads: list[np.ndarray] = []
for contour in contours[: self.max_candidates]:
box = self._rotated_box(contour)
if box is None:
continue
score = self._score(page, box)
if score < self.box_thresh:
continue
expanded = self._unclip(box)
if expanded is None:
continue
refit = self._rotated_box(expanded)
if refit is None:
continue
refit[:, 0] = np.clip(refit[:, 0], 0, w - 1)
refit[:, 1] = np.clip(refit[:, 1], 0, h - 1)
quads.append(refit)
per_image.append(
torch.from_numpy(np.stack(quads)) if quads else torch.zeros((0, 4, 2))
)
return per_image
def _rotated_box(self, contour: np.ndarray) -> np.ndarray | None:
"""Fit a 4-point rotated rectangle to ``contour`` if it is large enough."""
if contour.shape[0] < 4:
return None
rect = cv2.minAreaRect(contour)
(_, _), (w, h), _ = rect
if min(w, h) < self.min_size:
return None
return cv2.boxPoints(rect).astype(np.float32)
def _score(self, prob_map: np.ndarray, box: np.ndarray) -> float:
"""Average probability under the polygon defined by ``box`` (4x2)."""
h, w = prob_map.shape
xmin = int(np.clip(np.floor(box[:, 0].min()), 0, w - 1))
xmax = int(np.clip(np.ceil(box[:, 0].max()), 0, w - 1))
ymin = int(np.clip(np.floor(box[:, 1].min()), 0, h - 1))
ymax = int(np.clip(np.ceil(box[:, 1].max()), 0, h - 1))
mask = np.zeros((ymax - ymin + 1, xmax - xmin + 1), dtype=np.uint8)
shifted = box.copy()
shifted[:, 0] -= xmin
shifted[:, 1] -= ymin
cv2.fillPoly(mask, shifted.reshape(1, -1, 2).astype(np.int32), 1)
return float(cv2.mean(prob_map[ymin : ymax + 1, xmin : xmax + 1], mask=mask)[0])
def _unclip(self, box: np.ndarray) -> np.ndarray | None:
"""Expand ``box`` by ``unclip_ratio`` via :mod:`pyclipper` offsetting."""
polygon = Polygon(box)
if polygon.length < 1e-6:
return None
distance = polygon.area * self.unclip_ratio / polygon.length
offset = pyclipper.PyclipperOffset()
offset.AddPath(box.tolist(), pyclipper.JT_ROUND, pyclipper.ET_CLOSEDPOLYGON)
expanded = offset.Execute(distance)
if not expanded:
return None
return np.array(expanded[0], dtype=np.float32).reshape(-1, 1, 2)