torchocr.transforms#

Inference presets#

Each weights entry’s transforms() returns the preset it was trained with.

class torchocr.transforms.DetectionPreset(max_side=960, mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225), channel_order='rgb')[source]#

Bases: Module

Resize + normalize uint8 RGB images for a text detector.

The image is scaled (aspect ratio kept) so its longer side is about max_side, then each side is rounded to the nearest multiple of 32 – the stride DBNet requires. Map predictions back to the input with scale = input_size / output_size per axis.

Parameters:
  • max_side (int | None) – Target length of the longer side. None keeps the input scale and only rounds to multiples of 32.

  • mean (tuple[float, float, float]) – Per-channel mean applied after scaling to [0, 1].

  • std (tuple[float, float, float]) – Per-channel standard deviation.

  • channel_order (Literal['rgb', 'bgr']) – "rgb" or "bgr". PaddleOCR-trained weights saw OpenCV-decoded BGR pixels normalized with RGB-ordered ImageNet statistics; "bgr" reproduces that by flipping channels before normalizing.

Forward:

(..., 3, H, W) uint8 RGB -> (..., 3, H', W') float32.

forward(image)[source]#

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Parameters:

image (Tensor)

Return type:

Tensor

extra_repr()[source]#

Return the extra representation of the module.

To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.

Return type:

str

class torchocr.transforms.RecognitionPreset(height=32, max_width=320, mean=(0.5, 0.5, 0.5), std=(0.5, 0.5, 0.5), channel_order='rgb')[source]#

Bases: Module

Resize + normalize one uint8 RGB text crop for a CTC recognizer.

The crop is scaled to height with its aspect ratio kept (width clamped to [16, max_width]), normalized to [-1, 1] by default, then right-padded with zeros to max_width so crops of different lengths stack into one batch.

Parameters:
  • height (int) – Output height. Default 32 (CRNN’s contract).

  • max_width (int) – Output width after padding. Default 320.

  • mean (tuple[float, float, float]) – Per-channel mean applied after scaling to [0, 1].

  • std (tuple[float, float, float]) – Per-channel standard deviation.

  • channel_order (Literal['rgb', 'bgr']) – "rgb" or "bgr"; see DetectionPreset.

Forward:

(3, H, W) uint8 RGB -> (3, height, max_width) float32.

forward(crop)[source]#

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Parameters:

crop (Tensor)

Return type:

Tensor

normalize(image)[source]#

The per-pixel part of the preset (channel order, scaling, mean/std), without resizing.

Because it is per-pixel it commutes with bilinear sampling: normalize a whole (..., 3, H, W) uint8 page once, then cut every word out of it with torchocr.ops.crop_quads().

Parameters:

image (Tensor)

Return type:

Tensor

extra_repr()[source]#

Return the extra representation of the module.

To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.

Return type:

str

class torchocr.transforms.ClassificationPreset(resize_size=256, crop_size=224, mean=(0.485, 0.456, 0.406), std=(0.229, 0.224, 0.225))[source]#

Bases: Module

Resize, center-crop and normalize uint8 RGB images for an image classifier.

The shorter side is scaled to resize_size (aspect ratio kept), then the central crop_size square is kept: torchvision’s ImageNet recipe, which PaddleOCR’s page-orientation classifier was trained with.

Parameters:
  • resize_size (int) – Target length of the shorter side. Default 256.

  • crop_size (int) – Side of the central square crop. Default 224.

  • mean (tuple[float, float, float]) – Per-channel mean applied after scaling to [0, 1].

  • std (tuple[float, float, float]) – Per-channel standard deviation.

Forward:

(..., 3, H, W) uint8 RGB -> (..., 3, crop_size, crop_size) float32.

forward(image)[source]#

Define the computation performed at every call.

Should be overridden by all subclasses.

Note

Although the recipe for forward pass needs to be defined within this function, one should call the Module instance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.

Parameters:

image (Tensor)

Return type:

Tensor

extra_repr()[source]#

Return the extra representation of the module.

To print customized extra information, you should re-implement this method in your own modules. Both single-line and multi-line strings are acceptable.

Return type:

str

Training targets#

class torchocr.transforms.MakeDBTargets(shrink_ratio=0.4, min_text_size=8, thresh_min=0.3, thresh_max=0.7)[source]#

Bases: object

Rasterize text polygons into DB probability / threshold / mask maps.

Follows PaddleOCR’s MakeShrinkMap + MakeBorderMap:

  • Each polygon is shrunk by D = A (1 - r^2) / L (area A, perimeter L, r = shrink_ratio) with pyclipper; if that splits it, r = 2 * shrink_ratio is tried before giving up and ignoring it. The shrunk region is the probability target.

  • The threshold target lives in the polygon dilated by D: one minus the distance to the nearest edge divided by D, clipped to [0, 1], then rescaled to [thresh_min, thresh_max]. The exact point-to-segment distance is used.

  • Ignored polygons, polygons with a side under min_text_size and polygons whose shrink fails are zeroed in mask.

Polygons are clipped to the canvas first. Coordinates follow the pixel-index convention of cv2.fillPoly().

Parameters:
  • shrink_ratio (float) – r above. Default 0.4.

  • min_text_size (int) – Minimum polygon height/width in pixels. Default 8.

  • thresh_min (float) – Threshold target far from the border. Default 0.3.

  • thresh_max (float) – Threshold target on the border. Default 0.7.

class torchocr.transforms.DBTargets(probability, threshold, mask)[source]#

Bases: object

Per-image supervision for torchocr.DBLoss.

Parameters:
probability#

(1, H, W) 0/1 map of the shrunk text polygons.

Type:

torch.Tensor

threshold#

(1, H, W) border map, in [thresh_min, thresh_max] inside the dilated band around each polygon and 0 elsewhere (DBLoss only supervises its non-zero pixels).

Type:

torch.Tensor

mask#

(1, H, W) valid-pixel mask; False over ignored (###) and too-small text so neither class is learned there.

Type:

torch.Tensor

Augmentation with torchvision.transforms.v2#

Polygon-aware augmentation on top of torchvision.transforms.v2.

torchvision’s v2 transforms move KeyPoints of any leading shape, so (N, P, 2) text polygons follow flips, rotations, affines, resizes and crops once wrapped. TextDetectionTarget is a pytree node, so its texts and ignore ride along untouched. This module adds what is specific to text:

  • wrap_sample() wraps a dataset sample as tv_tensors;

  • RandomTextCrop crops without cutting through any text region (PaddleOCR’s EastRandomCropData);

  • SanitizeTextPolygons drops regions moved off the canvas and marks partly visible ones don’t-care, keeping texts and ignore aligned.

Example:

from torchvision.transforms import v2
from torchocr.transforms.v2 import RandomTextCrop, SanitizeTextPolygons, wrap_sample

augment = v2.Compose([
    v2.RandomRotation(10), v2.RandomAffine(0, scale=(0.5, 3.0)),
    RandomTextCrop(), v2.Resize(size=None, max_size=640), SanitizeTextPolygons(),
])
image, target = augment(*wrap_sample(*dataset[0]))
db_targets = MakeDBTargets()(target.polygons, target.ignore, image.shape[-2:])

Pass images as tv_tensors.Image (what wrap_sample() does): a plain tensor would make torchvision treat the first plain tensor it meets as the image, which could be the ignore mask.

torchocr.transforms.v2.wrap_sample(image, target)[source]#

Wrap a (C, H, W) image and its target as tv_tensors for torchvision.transforms.v2.

Parameters:
Return type:

tuple[Image, TextDetectionTarget]

class torchocr.transforms.v2.RandomTextCrop(min_crop_side_ratio=0.1, max_tries=50)[source]#

Bases: Transform

Random crop whose borders never cut through a text polygon.

Crop edges are drawn from rows and columns that no polygon’s axis-aligned extent covers, so every region ends up fully inside or fully outside the crop on each axis, and the crop holds at least one region. After max_tries misses (e.g. text everywhere) the image is returned whole. Every polygon in the sample counts, don’t-care ones included.

Parameters:
  • min_crop_side_ratio (float) – Minimum crop side, as a fraction of the image side.

  • max_tries (int) – Attempts before giving up and keeping the whole image.

make_params(flat_inputs)[source]#

Method to override for custom transforms.

See How to write your own v2 transforms

Parameters:

flat_inputs (list[Any])

Return type:

dict[str, Any]

transform(inpt, params)[source]#

Method to override for custom transforms.

See How to write your own v2 transforms

Parameters:
Return type:

Any

class torchocr.transforms.v2.SanitizeTextPolygons(partial='ignore', min_size=1.0)[source]#

Bases: Transform

Drop text regions outside the canvas; mark partly visible ones don’t-care.

Run it last, after the geometric transforms. A region is dropped when its axis-aligned extent misses the canvas (or when it has fewer than min_size pixels of extent along either axis); a region that sticks out of the canvas has a clipped word whose transcription no longer matches the pixels, so its ignore flag is set (with partial="ignore") or it is dropped (partial="drop"). Vertices are not clamped: MakeDBTargets rasterizes polygons that overhang the canvas correctly.

Parameters:
  • partial (str) – "ignore" (default), "drop" or "keep" for regions partly outside the canvas.

  • min_size (float) – Minimum width and height, in pixels, of a kept region.

forward(*inputs)[source]#

Do not override this! Use transform() instead.

Parameters:

inputs (Any)

Return type:

Any