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:
ModuleResize + normalize
uint8RGB 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 withscale = input_size / output_sizeper axis.- Parameters:
max_side (int | None) – Target length of the longer side.
Nonekeeps 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)uint8RGB ->(..., 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
Moduleinstance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.
- 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:
ModuleResize + normalize one
uint8RGB text crop for a CTC recognizer.The crop is scaled to
heightwith its aspect ratio kept (width clamped to[16, max_width]), normalized to[-1, 1]by default, then right-padded with zeros tomax_widthso 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"; seeDetectionPreset.
- Forward:
(3, H, W)uint8RGB ->(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
Moduleinstance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.
- 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)uint8page once, then cut every word out of it withtorchocr.ops.crop_quads().
- 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:
ModuleResize, center-crop and normalize
uint8RGB images for an image classifier.The shorter side is scaled to
resize_size(aspect ratio kept), then the centralcrop_sizesquare is kept: torchvision’s ImageNet recipe, which PaddleOCR’s page-orientation classifier was trained with.- Parameters:
- Forward:
(..., 3, H, W)uint8RGB ->(..., 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
Moduleinstance afterwards instead of this since the former takes care of running the registered hooks while the latter silently ignores them.
Training targets#
- class torchocr.transforms.MakeDBTargets(shrink_ratio=0.4, min_text_size=8, thresh_min=0.3, thresh_max=0.7)[source]#
Bases:
objectRasterize text polygons into DB probability / threshold / mask maps.
Follows PaddleOCR’s
MakeShrinkMap+MakeBorderMap:Each polygon is shrunk by
D = A (1 - r^2) / L(areaA, perimeterL,r = shrink_ratio) withpyclipper; if that splits it,r = 2 * shrink_ratiois 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 byD, 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_sizeand polygons whose shrink fails are zeroed inmask.
Polygons are clipped to the canvas first. Coordinates follow the pixel-index convention of
cv2.fillPoly().
- class torchocr.transforms.DBTargets(probability, threshold, mask)[source]#
Bases:
objectPer-image supervision for
torchocr.DBLoss.- probability#
(1, H, W)0/1 map of the shrunk text polygons.- Type:
- threshold#
(1, H, W)border map, in[thresh_min, thresh_max]inside the dilated band around each polygon and 0 elsewhere (DBLossonly supervises its non-zero pixels).- Type:
- mask#
(1, H, W)valid-pixel mask;Falseover ignored (###) and too-small text so neither class is learned there.- Type:
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;RandomTextCropcrops without cutting through any text region (PaddleOCR’sEastRandomCropData);SanitizeTextPolygonsdrops regions moved off the canvas and marks partly visible ones don’t-care, keepingtextsandignorealigned.
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 fortorchvision.transforms.v2.- Parameters:
image (Tensor)
target (TextDetectionTarget)
- Return type:
- class torchocr.transforms.v2.RandomTextCrop(min_crop_side_ratio=0.1, max_tries=50)[source]#
Bases:
TransformRandom 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_triesmisses (e.g. text everywhere) the image is returned whole. Every polygon in the sample counts, don’t-care ones included.- Parameters:
- class torchocr.transforms.v2.SanitizeTextPolygons(partial='ignore', min_size=1.0)[source]#
Bases:
TransformDrop 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_sizepixels 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 itsignoreflag is set (withpartial="ignore") or it is dropped (partial="drop"). Vertices are not clamped:MakeDBTargetsrasterizes polygons that overhang the canvas correctly.- Parameters: