Source code for torchocr.models.orientation

"""Page orientation classification: is the page upright, or turned by 90, 180 or 270 degrees?"""

import torch
from torch import Tensor, nn

from ..transforms import ClassificationPreset
from .backbones.mobilenet_v3 import _hard_swish, _SEModule
from .hub import BASE_URL, Weights, WeightsEnum, load_weights, register_model


# (kernel, in, out, stride, SE) per depthwise-separable block: PP-LCNet x1.0 (PaddleClas NET_CONFIG).
_PP_LCNET_X1_0 = {
    "blocks2": [(3, 16, 32, 1, False)],
    "blocks3": [(3, 32, 64, 2, False), (3, 64, 64, 1, False)],
    "blocks4": [(3, 64, 128, 2, False), (3, 128, 128, 1, False)],
    "blocks5": [(3, 128, 256, 2, False)] + [(5, 256, 256, 1, False)] * 5,
    "blocks6": [(5, 256, 512, 2, True), (5, 512, 512, 1, True)],
}


@torch.fx.wrap
def _check_classifier_input(images: Tensor) -> None:
    if images.ndim != 4 or images.shape[1] != 3:
        raise ValueError(f"Expected (B, 3, H, W) images; got {tuple(images.shape)}.")


[docs] class PPLCNet_x1_0_Weights(WeightsEnum): PPOCR_DOC_ORIENTATION = Weights( url=f"{BASE_URL}/pplcnet_x1_0_doc_ori-ba9045e4.pth", transforms=ClassificationPreset, meta={ "task": "page-orientation", "backbone": "pp_lcnet_x1_0", "num_params": 1_676_644, # Class c: the page content is turned c * 90 degrees clockwise; # torch.rot90(image, c, dims=(-2, -1)) sets it upright. "categories": ["0", "90", "180", "270"], "source": "PaddleOCR PP-LCNet_x1_0_doc_ori, via scripts/convert_paddle_pplcnet.py", "license": "Apache-2.0", # Chosen on DocLayNet validation (references/orientation/evaluate.py --sweep). "min_confidence": 0.7, "_metrics": { "DocLayNet-test": { "accuracy": 0.9848, "upright_wrongly_turned": 0.0024, "turned_set_upright": 0.9753, } }, "_docs": ( "Trained by PaddleOCR on document pages (mostly Chinese and English), converted to " "PyTorch. Scored on the 4999 DocLayNet test pages (financial reports, manuals, laws, " "patents, scientific articles, tenders), each fed upright and turned 90, 180 and 270 " "degrees: accuracy is the argmax; the other two numbers are PageOrientation's decisions " "at min_confidence=0.7, chosen on DocLayNet validation and applied once to test. " "Weakest on manuals (0.973) and laws (0.979), where most errors send upright pages to " "180 degrees. Not meant for scene photos: on a street photo it is unsure (p < 0.8) and can " "still turn it. Reproduce with references/orientation/evaluate.py." ), }, ) DEFAULT = PPOCR_DOC_ORIENTATION
class _ConvBNHardSwish(nn.Module): """Conv (no bias) -> BN -> HardSwish, with submodule names ``conv`` / ``bn``.""" def __init__(self, in_channels: int, out_channels: int, kernel_size: int, stride: int, groups: int = 1) -> None: super().__init__() self.conv = nn.Conv2d( in_channels, out_channels, kernel_size, stride=stride, padding=(kernel_size - 1) // 2, groups=groups, bias=False, ) self.bn = nn.BatchNorm2d(out_channels) def forward(self, x: Tensor) -> Tensor: return _hard_swish(self.bn(self.conv(x))) class _DepthwiseSeparable(nn.Module): """Depthwise k x k -> optional SE -> pointwise 1 x 1 (PP-LCNet's only block type).""" def __init__(self, kernel_size: int, in_channels: int, out_channels: int, stride: int, use_se: bool) -> None: super().__init__() self.dw_conv = _ConvBNHardSwish(in_channels, in_channels, kernel_size, stride, groups=in_channels) self.se = _SEModule(in_channels) if use_se else nn.Identity() self.pw_conv = _ConvBNHardSwish(in_channels, out_channels, 1, 1) def forward(self, x: Tensor) -> Tensor: return self.pw_conv(self.se(self.dw_conv(x)))
[docs] class PPLCNet(nn.Module): """PP-LCNet x1.0 image classifier (Cui et al., 2021), as used by PaddleOCR for page orientation. A 1.7M-parameter CPU-oriented network: depthwise-separable blocks with HardSwish, squeeze-excitation only in the last two blocks, then global pooling and a 1280-wide 1x1 convolution before the classifier. Submodule names mirror PaddleClas so checkpoints port with a short remap (``scripts/convert_paddle_pplcnet.py``). Args: num_classes: Number of output logits. Default: from ``weights``, else 4. dropout: Dropout probability before the classifier. weights: Pretrained :class:`PPLCNet_x1_0_Weights` (member or name). progress: Show a download progress bar. Forward: ``(B, 3, H, W)`` normalized images -> ``(B, num_classes)`` logits. """ def __init__( self, num_classes: int | None = None, dropout: float = 0.2, weights: "PPLCNet_x1_0_Weights | str | None" = None, progress: bool = True, ) -> None: super().__init__() weights = PPLCNet_x1_0_Weights.verify(weights) if weights is not None: categories = len(weights.meta["categories"]) if num_classes not in (None, categories): raise ValueError(f"{weights!r} has {categories} classes; got num_classes={num_classes}.") num_classes = categories num_classes = 4 if num_classes is None else num_classes self.conv1 = _ConvBNHardSwish(3, 16, 3, 2) for name, config in _PP_LCNET_X1_0.items(): setattr(self, name, nn.Sequential(*(_DepthwiseSeparable(*block) for block in config))) self.avg_pool = nn.AdaptiveAvgPool2d(1) self.last_conv = nn.Conv2d(512, 1280, kernel_size=1, bias=False) self.dropout = nn.Dropout(dropout) self.fc = nn.Linear(1280, num_classes) if weights is not None: load_weights(self, weights, progress=progress)
[docs] def forward(self, images: Tensor) -> Tensor: _check_classifier_input(images) x = self.conv1(images) x = self.blocks6(self.blocks5(self.blocks4(self.blocks3(self.blocks2(x))))) x = _hard_swish(self.last_conv(self.avg_pool(x))) return self.fc(self.dropout(torch.flatten(x, 1)))
[docs] @register_model("pp_lcnet_x1_0", weights=PPLCNet_x1_0_Weights) def pp_lcnet_x1_0(*, weights: PPLCNet_x1_0_Weights | str | None = None, **kwargs: object) -> PPLCNet: """PP-LCNet x1.0 classifier; see :class:`PPLCNet_x1_0_Weights`.""" return PPLCNet(weights=weights, **kwargs)