Vision Systems & Engineering

torchvision

The computer vision library of the PyTorch project, with its v2 transforms and TVTensors, box bookkeeping under crops, the models and weights API, detection models that resize and pad inside the model, operators, datasets and reference scripts, the 0.29 versions, and a NumPy port of RandomIoUCrop, box clamping and SanitizeBoundingBoxes.

beginner

torchvision (written TorchVision in its own citation file) is the computer vision library of the PyTorch project. Its README describes it as “popular datasets, model architectures, and common image transformations for computer vision”, and the repository’s citation file credits it to “TorchVision maintainers and contributors”, with a release date of 6 November 2016 and the BSD 3-Clause licence. It is used to load standard datasets, to transform images together with their boxes, masks and keypoints for training and inference, to build classification, segmentation, detection, video and optical-flow models with or without pretrained weights, and to run vision-specific operators such as non-maximum suppression and RoI Align. An older package with the same name, “the machine-vision package of Torch” in the title of Marcel and Rodriguez (2010), which was not read for this article, belongs to Torch, the earlier library scripted in Lua that the PyTorch article describes, and is different software.

This article describes torchvision 0.29.2, released on 28 October 2026, from its source code and the documentation sources in its repository at that tag (commit f122815), as of November 2026. It covers the package map, the v2 transforms and their tensor types, the rules that move bounding boxes when an image is cropped, the models and weights API, the wrapper that resizes and pads images inside the detection models, the operators, datasets and reference scripts, and the versions. torchvision itself was not installed or run on the machine this article was written on; the example ports four of its box rules to NumPy, and its outcomes test that port.

Purpose

torchvision supplies the parts of a vision pipeline that sit around a PyTorch model: reading a dataset into Dataset objects, augmenting each sample, defining the network, and turning its outputs into boxes or masks. Its documentation index lists the sub-packages transforms, tv_tensors, models, datasets, utils, ops, io and feature_extraction, plus training reference scripts kept outside the package. Features are labelled Stable, Beta or Prototype: Stable features are maintained long-term with backward compatibility “although breaking changes can happen and notice will be given one release ahead of time”, while Beta features carry no backward-compatibility commitment (docs/source/index.rst). The detection module, the segmentation module and rotated boxes are among those marked Beta in 0.29.2.

The library does not train models for the user; it provides datasets, transforms and model builders that ordinary PyTorch training loops use. Its own training recipes live in the references/ directory, which the documentation describes as the scripts used to train the models whose weights torchvision distributes, “not part of the core package” and without backward-compatibility guarantees (training_references.rst).

Core Capabilities

Transforms v1 and v2, TVTensors and dispatch

torchvision has two transform namespaces. The original torchvision.transforms (v1) transforms images; torchvision.transforms.v2, released in torchvision 0.15 (March 2023), also transforms bounding boxes, masks, videos and keypoints, supports arbitrary input structures such as dicts and tuples, and adds transforms such as CutMix and MixUp (described in Mixup and CutMix). The documentation recommends v2, says that v2 is “fully backward compatible” with v1 up to “negligible differences” in output, and states that new features will be added to v2 only (transforms.rst). What the individual transforms do to an image is the subject of data augmentation; this section covers how the library routes data through them.

v2 dispatches on type. TVTensors are torch.Tensor subclasses, Image, Video, BoundingBoxes, Mask and KeyPoints, that tell each transform which low-level kernel to call (tv_tensors.rst). A pure tensor is treated as an image. Each transform exists as a class (v2.Resize), as a functional (v2.functional.resize, which accepts PIL images, pure tensors and TVTensors and samples no random parameters), and as per-type kernels such as resize_bounding_boxes, which the documentation calls public but undocumented and useful mainly for TorchScript with boxes or masks. In the random transforms, make_params draws the parameters from the flattened inputs of a sample and transform applies them to each input; in RandomIoUCrop, for example, one crop is drawn and then applied to the image, the masks and the boxes alike (transforms/v2/_geometry.py lines 1180–1247), which is how an image and its annotations stay consistent.

Two conventions trip users. The expected value range of a tensor image is set by its dtype: float images are expected in [0,1][0, 1], integer images in [0, MAX_DTYPE], the largest value of the dtype, so uint8 images in [0,255][0, 255], and ToDtype(..., scale=True) converts both dtype and range (transforms.rst). And for TorchScript, transforms are composed with torch.nn.Sequential rather than Compose; calling torch.jit.script() on a v2 class gives its scripted v1 equivalent, which the documentation warns may give slightly different results, and it recommends scripting the v2 functionals instead (TorchScript itself is deprecated in PyTorch, as the PyTorch article reports). The performance guidance in the same file is to use v2, tensors rather than PIL images, uint8 especially for resizing, and bilinear or bicubic resizing.

Boxes: formats, canvas size and clamping

A BoundingBoxes tensor has shape [N,K][N, K] and carries three attributes: format, canvas_size (the height and width of the image the boxes belong to) and clamping_mode (tv_tensors/_bounding_boxes.py at 0.29.2). The formats are XYXY (corners), XYWH (top-left corner, width and height) and CXCYWH (centre, width and height), and, since torchvision 0.23 as a Beta feature, three rotated formats: XYWHR and CXCYWHR, with an angle in degrees, and XYXYXYXY, four corners (lines 14–41 and 66–71). The docstring of box_iou gives the rotation angle of cxcywhr boxes as “counter-clockwise positive” (ops/boxes.py lines 368–370). The general conventions for boxes, including continuous coordinates against inclusive pixel indices and the five-parameter ambiguity of rotated boxes, are set out in Bounding Box.

Boxes are continuous coordinates. _clamp_bounding_boxes (transforms/v2/functional/_meta.py lines 403–424) clamps xx to [0,W][0, W] and yy to [0,H][0, H] of the canvas, not to W−1W - 1 and H−1H - 1; keypoints, by contrast, are clamped to W−1W - 1 and H−1H - 1, and a comment in _clamp_keypoints points out the difference (lines 712–719). Integer boxes are converted to float for clamping and cast back to their dtype (lines 413–414 and 424), so any fractional value is truncated. clamping_mode takes "soft" (the default, lines 101 and 134 of _bounding_boxes.py), "hard" or None; a comment at line 418 of _meta.py says soft and hard are equivalent for boxes that are not rotated, and with None the function returns the boxes unclamped (lines 409–410). The modes differ only for rotated boxes, whose clamping is a separate routine (_clamp_rotated_bounding_boxes, lines 602–660).

Cropping a box (crop_bounding_boxes, functional/_geometry.py lines 1867–1896) subtracts the crop’s left and top offsets from the coordinates, sets the canvas to the crop’s height and width, and calls the clamp with the box’s own clamping_mode. SanitizeBoundingBoxes (transforms/v2/_misc.py lines 360–480) then removes boxes and the labels and per-instance masks that go with them. Its mask (_get_sanitize_bounding_boxes_mask, functional/_misc.py lines 413–444) keeps a box when its width and height are at least min_size, its area at least min_area, all its coordinates non-negative, and its xx and yy coordinates at most the canvas width and height. Both defaults are 1, and values below 1 raise a ValueError in __init__; with w≥1w \ge 1 and h≥1h \ge 1 the area is at least 1, so at the defaults the area rule never removes a box that the size rules keep. The docstring advises calling ClampBoundingBoxes first to avoid removing boxes that only stick out of the image, and says that the default labels_getter looks for a “labels” key and that masks of shape [N,H,W][N, H, W] are sanitized automatically.

RandomIoUCrop is the SSD-style crop of v2 (transforms/v2/_geometry.py lines 1123–1247). Its docstring warns that it “must be followed by” SanitizeBoundingBoxes “to properly remove the bounding boxes below the IoU threshold” (lines 1129–1132). The code removes boxes by a different rule: transform sets to zero every box whose centre was not strictly inside the crop (line 1244), whatever its overlap, and SanitizeBoundingBoxes then drops those zero-width boxes. The IoU threshold decides only whether a crop is accepted, as the example’s method describes. The data augmentation article reports the documentation’s wording. The crop’s “scale” is a factor per side, drawn in [0.3,1)[0.3, 1) for width and height separately, so the crop covers from about 0.09 to almost all of the image’s area; a comment in __init__ points to the SSD authors’ Caffe configuration. The SSD article describes the paper’s patches, which cover 0.1 to 1 of the image, and the authors’ Caffe sampler, which draws side lengths between 0.3 and 1 of the image’s.

Models and weights

torchvision.models defines models for image classification, semantic segmentation, object detection, instance segmentation, person keypoint detection, video classification and optical flow (models.rst). Each architecture has a builder function, such as resnet50, and, since version 0.13, a weights enum, such as ResNet50_Weights, whose members (IMAGENET1K_V1, IMAGENET1K_V2) each carry a URL, a meta dictionary and a transforms callable (models/_api.py, classes Weights and WeightsEnum). DEFAULT is an alias for the best available weights, and the documentation warns that these “may change across versions”. weights=None gives random initialization; strings such as "IMAGENET1K_V2" are accepted. The old pretrained=True argument is deprecated and emits warnings; models.rst at 0.29.2 still says it “will be removed on v0.15”, a version long past. Since 0.14, list_models, get_model, get_model_weights and get_weight list and retrieve models and weights by name.

Instancing a model with weights downloads them through torch.hub to a cache directory set by TORCH_HOME, and the same builders can be loaded through torch.hub.load("pytorch/vision", ...) without torchvision installed, except the detection models, which depend on torchvision’s C++ operators (models.rst). weights.transforms() returns the preprocessing the weights were evaluated with, and weights.meta["categories"] the class names. The documentation stresses that preprocessing “can vary across model families, variants or even weight versions” and that getting it wrong may lower accuracy or give incorrect outputs; the preprocessing contract and how libraries’ resize defaults differ are the subject of Model Deployment. The architecture articles hold each model’s implementation notes and weights, for example ResNet, MobileNet, EfficientNet, ConvNeXt, Vision Transformer, FCN, DeepLab, Faster R-CNN, Mask R-CNN, RetinaNet, FCOS, SSD and RAFT.

torchvision.models.feature_extraction provides create_feature_extractor, which traces a model symbolically with torch.fx, makes chosen graph nodes the outputs, removes everything downstream of them and generates a new module; nodes are named by their path in the module hierarchy, such as "layer4.2.relu" in ResNet-50, and get_graph_node_names lists them (feature_extraction.rst). The documentation’s uses include visualizing feature maps and feeding a hierarchy of features to a feature pyramid network.

Detection models: resize, normalize and pad inside the model

The detection models take a list of Tensor[C, H, W], one per image, at the image’s own size (models.rst). GeneralizedRCNNTransform (models/detection/transform.py lines 86–285), whose docstring describes it as transforming inputs and targets “before feeding the data to a GeneralizedRCNN model”, prepares the batch. For each image it first normalizes, (image - mean) / std, and raises a TypeError if the image is not a float tensor, with a message that names the range [0,1][0, 1] (lines 160–169). It then resizes with bilinear interpolation (align_corners=False), when no fixed_size is set, by the scale factor min⁡(smin⁡/short side,smax⁡/long side)\min(s_{\min} / \text{short side}, s_{\max} / \text{long side}) with recompute_scale_factor=True (lines 57–72); in training, smin⁡s_{\min} is drawn from the configured tuple of sizes, and in evaluation the last one is used (lines 184–191). Target boxes and keypoints are rescaled with the image (lines 196–203), and masks are resized by interpolate called without a mode argument (lines 77–82). Finally batch_images pads every image at its bottom and right with zeros to the largest height and width in the batch, each rounded up to a multiple of size_divisible = 32 (lines 237–255). Because normalization comes first (line 141, before batch_images at line 148), the zero padding is the mean colour of the normalization, not black. At inference, postprocess maps predicted boxes, masks and keypoints back to each original image size (lines 257–277).

The ObjectDetection preset in transforms/_presets.py (lines 23–36), one of the classes that file says are to be accessed only through the transforms of Weights, does nothing but convert the image to float in [0,1][0, 1]; in our reading it is the detection weights’ preset (the detection model files were not read), since the resize and normalization happen inside the model. The detection training reference does its multi-scale augmentation outside the model, with RandomShortestSize over shortest sides 480 to 800 in steps of 32 and max_size=1333, or RandomIoUCrop for its SSD recipes, and ends its v2 pipeline with SanitizeBoundingBoxes (references/detection/presets.py lines 42–83). Aspect-ratio grouping of batches, whose effect on padding the Detectron2 article measures for Detectron2’s own two-bucket grouping, is not part of the library: it is GroupedBatchSampler in the reference scripts, which quantizes each image’s aspect ratio into bins 2linspace(−1,1,2k+1)2^{\text{linspace}(-1, 1, 2k+1)} and builds each batch from one bin only (references/detection/group_by_aspect_ratio.py lines 22–79 and 187–194).

Operators

torchvision.ops collects operators, losses and layers specific to vision, and ops.rst notes that all its operators support TorchScript natively:

  • Detection and segmentation operators: nms and batched_nms (Non-Maximum Suppression), roi_align, roi_pool, their position-sensitive variants and MultiScaleRoIAlign (RoI Pooling), masks_to_boxes, and a FeaturePyramidNetwork module.
  • Box operators: box_area, box_convert, box_iou (axis-aligned, and rotated boxes since 0.27), clip_boxes_to_image, remove_small_boxes, and generalized_box_iou, distance_box_iou and complete_box_iou. Areas are (x2−x1)(y2−y1)(x_2 - x_1)(y_2 - y_1) with no +1+1 (ops/boxes.py line 303); Intersection over Union and Bounding Box Regression cover the measures and losses.
  • Losses: sigmoid_focal_loss (Focal Loss) and the generalized, distance and complete IoU losses.
  • Layers: Conv2dNormActivation, DeformConv2d, DropBlock2d, FrozenBatchNorm2d, MLP, SqueezeExcitation, StochasticDepth and others.

Datasets, io and utilities

torchvision.datasets holds built-in datasets for classification, detection and segmentation, optical flow, stereo matching, image pairs, captioning and video, among them ImageNet, COCO (CocoDetection) and Pascal VOC, plus base classes (VisionDataset, DatasetFolder, ImageFolder) for custom ones (datasets.rst). All are torch.utils.data.Dataset subclasses with transform and target_transform arguments. Datasets created with download=True download into their root directory, and the documentation warns that this logic is not multi-process safe, so a distributed job should trigger the download before setting up distributed mode. The documentation lists wrap_dataset_for_transforms_v2 under the heading “Transforms v2”. The README’s disclaimer says the library “downloads and prepares public datasets” but does not host or distribute them, vouch for their quality or fairness, or claim that the user has a licence to use them; checking each dataset’s licence is the user’s responsibility. Annotation file formats themselves are covered in Annotation Formats.

torchvision.io reads and writes images. Its video decoding and encoding (read_video, write_video, VideoReader) were removed in 0.26, and in 0.29.0 the image decoders and encoders were deprecated, to be removed in a future release, in favour of the separate TorchCodec library, which the release notes describe as the library for decoding and encoding all media while torchvision and TorchAudio focus on transforms. torchvision.utils provides drawing helpers such as draw_bounding_boxes.

Minimal Example

torchvision is not installed on the machine this article was written on, and no weights or datasets were downloaded. The example therefore ports four pieces of torchvision 0.29.2 to NumPy 2.3.5 (Python 3.13.9) and runs them on a synthetic image: RandomIoUCrop.make_params and transform (transforms/v2/_geometry.py lines 1180–1247), crop_bounding_boxes with the soft clamp (functional/_geometry.py lines 1867–1896, functional/_meta.py lines 403–424), the box mask of SanitizeBoundingBoxes (functional/_misc.py lines 413–444, with the ValueError of _misc.py’s __init__, lines 412–418), and box_iou for axis-aligned boxes (ops/boxes.py lines 279–347 and 388–391). The outcomes test our port, not torchvision. The ported code carries torchvision’s BSD 3-Clause licence in full.

Data. One 256 × 256 grey image, float32 in [0,1][0, 1], with six objects and one exact mask each, sampled at pixel centres; pixel (i,j)(i, j) covers [j,j+1)×[i,i+1)[j, j+1) \times [i, i+1), the convention of Bounding Box. The objects are two axis-aligned rectangles (R1, 64 × 40, whose box centre lies on integer coordinates; R2, 41 × 61, whose centre lies on half-integers), an axis-aligned ellipse (E1, semi-axes 60 and 45), an ellipse rotated by 35° (E2, semi-axes 34 and 18), and two right triangles (T1 with legs 90 and 110, its right angle at the top left; T2 with legs 70 and 40, its right angle at the bottom right). Each ground-truth box is the tight XYXY box of its mask, with edges on pixel borders, stored as float32 as a float32 BoundingBoxes would be. A data check (D) compares the mask areas with the analytic areas, checks that the rectangle masks equal their boxes, that no two masks share a pixel and that each triangle’s box centre is at least 5 pixels from its mass centroid, the asymmetry that makes triangles interesting here.

The draw. make_params loops forever. Each pass draws one of the seven options [0.0,0.1,0.3,0.5,0.7,0.9,1.0][0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0] uniformly; 1.0 means “leave the sample unchanged”. For any other option it makes up to 40 trials: draw a scale r∈[0.3,1)r \in [0.3, 1) for width and for height separately, truncate 256r256 r to an integer size, reject the trial if the aspect ratio of the crop is outside [0.5,2][0.5, 2], draw the left and top offsets and truncate them, reject a zero-area crop, reject the crop if no box centre lies strictly inside it, and reject it if the largest IoU between the crop and the boxes whose centres lie inside is below the option. The first trial that passes returns the crop; if all 40 fail, the loop draws a new option. Our port replaces torch.randint and torch.rand with a NumPy generator (integers(0, 7) for the option and random(2, dtype=float32) for each pair of uniforms), so the draws differ from torchvision’s; the rules are what is tested. The scales, sizes and IoUs of the draw are computed in float32, and NumPy 2 compares them with Python floats in float32.

The pipeline. For each of 200 samples (seed 0): draw a crop; unless it is the identity, slice the image and masks, crop and clamp the boxes, and set to zero the boxes whose centres were not strictly inside; then apply the sanitize mask on the canvas of the crop with the defaults (min_size 1, min_area 1) to the boxes, the labels and the masks.

Measures. For every kept box, the IoU, in float64 from integer corners, between the clamped box and the tight box of the object’s visible part (its mask inside the crop); for every removed box, the fraction of the object’s area left visible; for every kept box, the same fraction. Results are given per object and per shape type, over the non-identity samples. The code also prints the number of samples under each option.

Hypotheses, written before any script ran (the bars and decision rules too):

  • H1: a kept rectangle’s clamped box equals the tight box of its visible part exactly, so its IoU is 1. Clamping intersects the box with the crop, and the visible part of an axis-aligned rectangle is that intersection.
  • H2 (per shape type): ellipses and triangles give IoU below 1 in some kept crops.
  • H2′: the axis-aligned ellipse E1 gives IoU exactly 1 in every kept crop. Our derivation: the half-width of an axis-aligned ellipse is largest on its centre row, so the extreme columns of the rendered E1 lie on the two rows next to its integer centre, and likewise its extreme rows; a kept box has its centre strictly inside a crop with integer edges, so those rows and columns are inside the crop. Only the rotated ellipse and the triangles have extreme points off the box’s centre lines, so H2 can hold for ellipses only through E2.
  • H3a: a rectangle removed by the centre rule has at most half its area visible (2⋅visible≤total2 \cdot \text{visible} \le \text{total}). If the centre is at or left of the crop’s left edge, the visible width is at most half the width; the strict test makes equality possible when an integer centre lies on an integer crop edge, which R1 allows and R2 does not.
  • H3b: some removed triangle has more than half its area visible in the 200 samples. A right triangle has up to three quarters of its area on one side of a line through its box centre parallel to a leg; whether the draws produce such a case is what H3b asks.
  • H4: SanitizeBoundingBoxes removes exactly the boxes zeroed by the centre rule. Our derivation: centres lie on multiples of 0.5 and crop edges on integers, so a centre strictly inside lies at least 0.5 from every edge, and the clamped box then has width and height of at least 1 and lies on the canvas.
  • H5a: a kept rectangle has more than a quarter of its area visible, since its visible width is at least w/2+0.5w/2 + 0.5 and its height at least h/2+0.5h/2 + 0.5.
  • H5b: some kept triangle has less than a quarter of its area visible in the 200 samples: a crop whose left and top edges cut T1 at fractions uu and vv of its legs keeps its box centre but leaves only (1−u−v)2(1 - u - v)^2 of its area.

H2′, H4, H5a and H5b were added at planning, by derivation, to the hypotheses of the batch plan. Checks: D as above; C0, the base check, that the identity samples and an explicit full-image crop leave every box equal to its ground truth and remove nothing; C-draw, that every drawn crop meets the draw’s rules when they are recomputed from the returned parameters (aspect-ratio margin at least 0, sizes from 76 to 256 inside the image, a box centre at least 0.5 inside, the largest IoU in exact arithmetic at least the option minus 1.2×10−71.2 \times 10^{-7} for float32 rounding, image and mask crops of shape (h,w)(h, w)); C-clamp, that five constructed boxes against a known crop give the hand-computed intersections; and C-sanitize, that six constructed boxes (zeroed, 0.5 wide, a negative coordinate, a coordinate beyond the canvas, a 1.5 × 1.5 box and a valid box) give the expected keep-or-remove vector, that the 1.5 × 1.5 box is removed with min_area=4, and that min_size=0.5 raises. The script runs in under a second.

# NumPy port of torchvision 0.29.2's RandomIoUCrop (make_params, transform), the box
# crop and clamp kernels and SanitizeBoundingBoxes, run on a synthetic image with exact
# per-instance masks. The functions box_iou, make_params, crop_boxes and sanitize_mask are ported
# (modified) from torchvision v0.29.2 (commit f122815): transforms/v2/_geometry.py,
# transforms/v2/functional/_geometry.py, _meta.py, _misc.py and ops/boxes.py, under:
#
# BSD 3-Clause License
#
# Copyright (c) Soumith Chintala 2016,
# All rights reserved.
#
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice, this
#   list of conditions and the following disclaimer.
#
# * Redistributions in binary form must reproduce the above copyright notice,
#   this list of conditions and the following disclaimer in the documentation
#   and/or other materials provided with the distribution.
#
# * Neither the name of the copyright holder nor the names of its
#   contributors may be used to endorse or promote products derived from
#   this software without specific prior written permission.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
# DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
# FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
import os
os.environ["OPENBLAS_NUM_THREADS"] = "1"
os.environ["OMP_NUM_THREADS"] = "1"
os.environ["MKL_NUM_THREADS"] = "1"
import numpy as np

SEED = 0
H = W = 256
NAMES = ["R1", "R2", "E1", "E2", "T1", "T2"]
TYPES = {"rectangle": [0, 1], "ellipse": [2, 3], "triangle": [4, 5]}
OPTIONS = [0.0, 0.1, 0.3, 0.5, 0.7, 0.9, 1.0]

# ---------- data: one grey image, six objects with exact masks ----------
yy, xx = np.mgrid[0:H, 0:W] + 0.5          # pixel (i, j) covers [j, j+1) x [i, i+1)
t = np.deg2rad(35.0)
xp = np.cos(t) * (xx - 210) + np.sin(t) * (yy - 175)
yp = -np.sin(t) * (xx - 210) + np.cos(t) * (yy - 175)
masks = np.stack([
    (xx >= 16) & (xx < 80) & (yy >= 20) & (yy < 60),                      # R1
    (xx >= 130) & (xx < 171) & (yy >= 140) & (yy < 201),                  # R2
    ((xx - 172) / 60) ** 2 + ((yy - 70) / 45) ** 2 <= 1,                  # E1
    (xp / 34) ** 2 + (yp / 18) ** 2 <= 1,                                 # E2, 35 deg
    (xx >= 20) & (yy >= 120) & ((xx - 20) / 90 + (yy - 120) / 110 <= 1),  # T1
    (xx <= 245) & (yy <= 246) & ((245 - xx) / 70 + (246 - yy) / 40 <= 1), # T2
])
image = np.full((H, W), 0.25, np.float32)
for k, v in zip(range(6), [0.9, 0.9, 0.7, 0.7, 0.5, 0.5]):
    image[masks[k]] = v
labels = np.arange(6)


def tight_box(m):
    rows, cols = np.nonzero(m)
    return np.array([cols.min(), rows.min(), cols.max() + 1, rows.max() + 1])


gt = np.stack([tight_box(m) for m in masks])            # XYXY, edges on pixel borders
total = masks.sum(axis=(1, 2))


# ---------- ported torchvision rules ----------
def box_iou(b, c):                                        # ops/boxes.py, float32 boxes
    lt = np.maximum(b[:, :2], c[:2])
    rb = np.minimum(b[:, 2:], c[2:])
    wh = np.clip(rb - lt, 0, None)
    inter = wh[:, 0] * wh[:, 1]
    area_b = (b[:, 2] - b[:, 0]) * (b[:, 3] - b[:, 1])
    return inter / (area_b + (c[2] - c[0]) * (c[3] - c[1]) - inter)


def make_params(rng, boxes, orig_h, orig_w, min_scale=0.3, max_scale=1.0,
                min_ar=0.5, max_ar=2.0, trials=40):       # RandomIoUCrop.make_params
    while True:
        opt = OPTIONS[int(rng.integers(0, len(OPTIONS)))]
        if opt >= 1.0:                                    # leave the sample as it is
            return dict(option=opt)
        for _ in range(trials):
            r = min_scale + (max_scale - min_scale) * rng.random(2, dtype=np.float32)
            new_w, new_h = int(orig_w * r[0]), int(orig_h * r[1])
            if not (min_ar <= new_w / new_h <= max_ar):
                continue
            r = rng.random(2, dtype=np.float32)
            left, top = int((orig_w - new_w) * r[0]), int((orig_h - new_h) * r[1])
            right, bottom = left + new_w, top + new_h
            if left == right or top == bottom:
                continue
            cx = 0.5 * (boxes[:, 0] + boxes[:, 2])
            cy = 0.5 * (boxes[:, 1] + boxes[:, 3])
            within = (left < cx) & (cx < right) & (top < cy) & (cy < bottom)
            if not within.any():
                continue
            crop = np.array([left, top, right, bottom], np.float32)
            if box_iou(boxes[within], crop).max() < opt:
                continue
            return dict(option=opt, top=top, left=left, height=new_h, width=new_w, within=within)


def crop_boxes(boxes, left, top, w, h):                   # crop_bounding_boxes + clamp
    b = boxes - np.array([left, top, left, top], boxes.dtype)
    b[:, 0::2] = np.clip(b[:, 0::2], 0, w)                # x to [0, W]
    b[:, 1::2] = np.clip(b[:, 1::2], 0, h)                # y to [0, H]
    return b


def sanitize_mask(b, canvas_hw, min_size=1.0, min_area=1.0):  # _get_sanitize_bounding_boxes_mask
    if min_size < 1 or min_area < 1:                      # SanitizeBoundingBoxes.__init__
        raise ValueError("min_size and min_area must be >= 1")
    img_h, img_w = canvas_hw
    ws, hs = b[:, 2] - b[:, 0], b[:, 3] - b[:, 1]
    valid = (ws >= min_size) & (hs >= min_size) & (b >= 0).all(axis=-1) & (ws * hs >= min_area)
    valid &= (b[:, 0] <= img_w) & (b[:, 2] <= img_w)
    valid &= (b[:, 1] <= img_h) & (b[:, 3] <= img_h)
    return valid


def pipeline(p):
    """RandomIoUCrop.transform on image, masks and boxes, then SanitizeBoundingBoxes."""
    boxes = gt.astype(np.float32)
    if "left" not in p:                                   # identity option
        img, ms, canvas, within = image, masks, (H, W), np.ones(6, bool)
    else:
        l, tp, w, h = p["left"], p["top"], p["width"], p["height"]
        img, ms = image[tp:tp + h, l:l + w], masks[:, tp:tp + h, l:l + w]
        boxes = crop_boxes(boxes, l, tp, w, h)
        within = p["within"]
        boxes[~within] = 0                                # "mark" boxes as degenerate
        canvas = (h, w)
    valid = sanitize_mask(boxes, canvas)
    return img, ms, boxes, within, valid                  # kept: boxes[valid], ms[valid], labels[valid]


def iou_exact(a, b):                                      # float64 from integer corners
    ix = max(0, min(a[2], b[2]) - max(a[0], b[0]))
    iy = max(0, min(a[3], b[3]) - max(a[1], b[1]))
    inter = ix * iy
    return inter / ((a[2] - a[0]) * (a[3] - a[1]) + (b[2] - b[0]) * (b[3] - b[1]) - inter)


# ---------- data check ----------
analytic = np.array([64 * 40, 41 * 61, np.pi * 60 * 45, np.pi * 34 * 18, 90 * 110 / 2, 70 * 40 / 2])
rel = np.abs(total - analytic) / analytic
shared = sum(int((masks[i] & masks[j]).sum()) for i in range(6) for j in range(i + 1, 6))
rect_ok = all((masks[k] == ((xx > gt[k, 0]) & (xx < gt[k, 2]) & (yy > gt[k, 1]) & (yy < gt[k, 3]))).all()
              for k in (0, 1))
print(f"numpy {np.__version__}, seed {SEED}, image {H}x{W}, objects {len(masks)}")
print("D(a) area rel. diff:", " ".join(f"{n} {r:.4f}" for n, r in zip(NAMES, rel)),
      f"| max {rel.max():.4f} (bar 0.03), rectangles {rel[:2].max():.4f}")
print(f"D(b) rectangle masks equal their boxes: {rect_ok}; D(c) shared pixels {shared}, "
      f"boxes inside image {bool((gt >= 0).all() and (gt[:, 2] <= W).all() and (gt[:, 3] <= H).all())}")
for k in (4, 5):
    rows, cols = np.nonzero(masks[k])
    d = np.hypot(0.5 * (gt[k, 0] + gt[k, 2]) - (cols.mean() + 0.5), 0.5 * (gt[k, 1] + gt[k, 3]) - (rows.mean() + 0.5))
    print(f"D(d) {NAMES[k]} box centre to mass centroid {d:.2f} px (bar >= 5)")

# ---------- 200 samples ----------
rng = np.random.default_rng(SEED)
recs, draws = [], []
for s in range(200):
    p = make_params(rng, gt.astype(np.float32), H, W)
    img, ms, boxes, within, valid = pipeline(p)
    draws.append((p, img.shape, ms.shape))
    for k in range(6):
        vis = int(ms[k].sum())
        r = dict(k=k, ident="left" not in p, within=bool(within[k]), kept=bool(valid[k]), vis=vis)
        if valid[k] and vis > 0:
            vb = tight_box(ms[k])
            cb = boxes[k].astype(np.int64)
            r.update(iou=iou_exact(cb, vb), match=bool((cb == vb).all()))
        elif valid[k]:
            r.update(iou=0.0, match=False)
        recs.append(r)

n_opt = {o: sum(p["option"] == o for p, _, _ in draws) for o in OPTIONS}
print("M4 samples per option:", ", ".join(f"{o}: {n}" for o, n in n_opt.items()), f"(total {len(draws)})")

# ---------- C0 ----------
ident = [r for r in recs if r["ident"]]
_, _, b0, _, v0 = pipeline(dict(option=0.0, top=0, left=0, height=H, width=W, within=np.ones(6, bool)))
full_ok = sum(int((b0[k].astype(np.int64) == gt[k]).all()) for k in range(6))
print(f"C0 identity samples {len(ident) // 6}: mismatches {sum(not r['match'] for r in ident)}, "
      f"removed {sum(not r['kept'] for r in ident)}; full-image crop: boxes equal {full_ok}/6, removed {int((~v0).sum())}")

# ---------- C-draw ----------
ar_m, cen_m, iou_m, viol, none_in, wmis, shp = np.inf, np.inf, np.inf, 0, 0, 0, 0
for p, ishape, mshape in draws:
    if "left" not in p:
        continue
    l, tp, w, h = p["left"], p["top"], p["width"], p["height"]
    ar_m = min(ar_m, w / h - 0.5, 2.0 - w / h)
    viol += not (76 <= w <= 256 and 76 <= h <= 256 and 0 <= l and l + w <= W and 0 <= tp and tp + h <= H)
    cx, cy = 0.5 * (gt[:, 0] + gt[:, 2]), 0.5 * (gt[:, 1] + gt[:, 3])
    marg = np.minimum.reduce([cx - l, l + w - cx, cy - tp, tp + h - cy])
    inside = marg > 0
    wmis += int((inside != p["within"]).any())
    if not inside.any():
        none_in += 1
        continue
    cen_m = min(cen_m, marg[inside].max())
    best = max(iou_exact(gt[k], np.array([l, tp, l + w, tp + h])) for k in np.nonzero(inside)[0])
    iou_m = min(iou_m, best - p["option"])
    shp += (ishape != (h, w)) + (mshape != (6, h, w))
print(f"C-draw aspect margin {ar_m:.4f} (>= 0), size/offset violations {viol}, samples without a centre "
      f"inside {none_in}, centre-rule mismatches {wmis}, best-centre margin {cen_m:.4f} (>= 0.5), "
      f"IoU margin {iou_m:.3e} (>= -1.2e-07), crop shape mismatches {shp}")

# ---------- C-clamp and C-sanitize ----------
cl = crop_boxes(np.array([[30, 60, 80, 90], [120, 100, 200, 150], [0, 0, 256, 256],
                          [70, 50, 90, 70], [180, 50, 220, 70]], np.float32), 50, 40, 100, 80)
exp = np.array([[0, 20, 30, 50], [70, 60, 100, 80], [0, 0, 100, 80], [20, 10, 40, 30], [100, 10, 100, 30]])
sb = np.array([[0, 0, 0, 0], [10, 10, 10.5, 20], [-1, 10, 20, 20], [10, 10, 100.5, 20],
               [10, 10, 11.5, 11.5], [10, 10, 30, 40]], np.float32)
got = sanitize_mask(sb, (80, 100))
try:
    sanitize_mask(sb, (80, 100), min_size=0.5)
    raised = False
except ValueError:
    raised = True
print(f"C-clamp mismatches {int((cl != exp).any(axis=1).sum())}/5; C-sanitize defaults {got.tolist()} "
      f"mismatches {int((got != [False, False, False, False, True, True]).sum())}/6, 1.5x1.5 box with "
      f"min_area=4 kept {bool(sanitize_mask(sb[4:5], (80, 100), min_area=4.0)[0])}, min_size=0.5 raises {raised}")


# ---------- measures M1-M3, M5 per object and per type ----------
def summary(ks):
    rs = [r for r in recs if r["k"] in ks and not r["ident"]]
    kept = [r for r in rs if r["kept"]]
    cen = [r for r in rs if not r["within"]]
    san = [r for r in rs if r["within"] and not r["kept"]]
    zero_kept = sum(1 for r in rs if not r["within"] and r["kept"])
    tot = lambda r: int(total[r["k"]])
    return dict(
        kept=len(kept), iou_min=min(r["iou"] for r in kept), iou_mean=np.mean([r["iou"] for r in kept]),
        n_lt1=sum(r["iou"] < 1 for r in kept), mism=sum(not r["match"] for r in kept),
        empty=sum(r["vis"] == 0 for r in kept), rem=len(cen), san=len(san), zero_kept=zero_kept,
        fmax_rem=max((r["vis"] / tot(r) for r in cen), default=float("nan")),
        half_max=max((2 * r["vis"] - tot(r) for r in cen), default=None),
        n_gt_half=sum(2 * r["vis"] > tot(r) for r in cen),
        fmin_kept=min(r["vis"] / tot(r) for r in kept),
        quarter_min=min(4 * r["vis"] - tot(r) for r in kept),
        n_lt_quarter=sum(4 * r["vis"] < tot(r) for r in kept))


print("\nper object over the non-identity samples (IoU of clamped box vs visible tight box)")
print("obj   kept  IoU min   IoU mean  IoU<1 mism empty | centre-removed max vis | sanitize-only "
      "| min vis kept")
rows = [(n, [k]) for k, n in enumerate(NAMES)] + [(tn, ks) for tn, ks in TYPES.items()]
S = {}
for n, ks in rows:
    S[n] = d = summary(ks)
    print(f"{n:9s} {d['kept']:4d}  {d['iou_min']:.6f}  {d['iou_mean']:.6f} {d['n_lt1']:5d} {d['mism']:4d} "
          f"{d['empty']:5d} | {d['rem']:5d}  {d['fmax_rem']:.4f}         | {d['san']:3d} "
          f"(zeroed but kept {d['zero_kept']}) | {d['fmin_kept']:.4f}")

# ---------- hypotheses: deciding values ----------
R, E, T = S["rectangle"], S["ellipse"], S["triangle"]
print(f"\nH1  rectangles: box mismatches {R['mism']} of {R['kept']} kept, min IoU {R['iou_min']:.6f} -> {R['mism'] == 0}")
print(f"H2  IoU < 1 in kept boxes: ellipses {E['n_lt1']}, triangles {T['n_lt1']} -> "
      f"{E['n_lt1'] >= 1 and T['n_lt1'] >= 1}")
print(f"H2' E1: box mismatches {S['E1']['mism']} of {S['E1']['kept']} kept -> {S['E1']['mism'] == 0}")
print(f"H3a removed rectangles {R['rem']}: max(2*vis - total) {R['half_max']} (<= 0), max fraction "
      f"{R['fmax_rem']:.4f} -> {R['half_max'] is None or R['half_max'] <= 0}")
print(f"H3b removed triangles {T['rem']}: with more than half visible {T['n_gt_half']}, max fraction "
      f"{T['fmax_rem']:.4f} -> {T['n_gt_half'] >= 1}")
san_all = sum(S[n]["san"] for n in TYPES)
zk_all = sum(S[n]["zero_kept"] for n in TYPES)
print(f"H4  removed by Sanitize beyond the centre rule {san_all}, zeroed boxes kept {zk_all} -> "
      f"{san_all == 0 and zk_all == 0}")
print(f"H5a kept rectangles: min(4*vis - total) {R['quarter_min']} (> 0), min fraction {R['fmin_kept']:.4f} "
      f"-> {R['quarter_min'] > 0}")
print(f"H5b kept triangles with less than a quarter visible {T['n_lt_quarter']}, min fraction "
      f"{T['fmin_kept']:.4f} -> {T['n_lt_quarter'] >= 1}")

Output:

numpy 2.3.5, seed 0, image 256x256, objects 6
D(a) area rel. diff: R1 0.0000 R2 0.0000 E1 0.0007 E2 0.0014 T1 0.0010 T2 0.0000 | max 0.0014 (bar 0.03), rectangles 0.0000
D(b) rectangle masks equal their boxes: True; D(c) shared pixels 0, boxes inside image True
D(d) T1 box centre to mass centroid 23.28 px (bar >= 5)
D(d) T2 box centre to mass centroid 13.01 px (bar >= 5)
M4 samples per option: 0.0: 38, 0.1: 39, 0.3: 43, 0.5: 31, 0.7: 4, 0.9: 0, 1.0: 45 (total 200)
C0 identity samples 45: mismatches 0, removed 0; full-image crop: boxes equal 6/6, removed 0
C-draw aspect margin 0.0000 (>= 0), size/offset violations 0, samples without a centre inside 0, centre-rule mismatches 0, best-centre margin 2.0000 (>= 0.5), IoU margin 0.000e+00 (>= -1.2e-07), crop shape mismatches 0
C-clamp mismatches 0/5; C-sanitize defaults [False, False, False, False, True, True] mismatches 0/6, 1.5x1.5 box with min_area=4 kept False, min_size=0.5 raises True

per object over the non-identity samples (IoU of clamped box vs visible tight box)
obj   kept  IoU min   IoU mean  IoU<1 mism empty | centre-removed max vis | sanitize-only | min vis kept
R1          38  1.000000  1.000000     0    0     0 |   117  0.5000         |   0 (zeroed but kept 0) | 0.5250
R2          87  1.000000  1.000000     0    0     0 |    68  0.4590         |   0 (zeroed but kept 0) | 0.4282
E1          95  1.000000  1.000000     0    0     0 |    60  0.4250         |   0 (zeroed but kept 0) | 0.2919
E2          54  0.958333  0.997531     5    5     0 |   101  0.4786         |   0 (zeroed but kept 0) | 0.5417
T1          90  0.057545  0.909927    42   42     0 |    65  0.6614         |   0 (zeroed but kept 0) | 0.0192
T2          28  0.045767  0.623914    26   26     0 |   127  0.2257         |   0 (zeroed but kept 0) | 0.0171
rectangle  125  1.000000  1.000000     0    0     0 |   185  0.5000         |   0 (zeroed but kept 0) | 0.4282
ellipse    149  0.958333  0.999105     5    5     0 |   161  0.4786         |   0 (zeroed but kept 0) | 0.2919
triangle   118  0.045767  0.842059    68   68     0 |   192  0.6614         |   0 (zeroed but kept 0) | 0.0171

H1  rectangles: box mismatches 0 of 125 kept, min IoU 1.000000 -> True
H2  IoU < 1 in kept boxes: ellipses 5, triangles 68 -> True
H2' E1: box mismatches 0 of 95 kept -> True
H3a removed rectangles 185: max(2*vis - total) 0 (<= 0), max fraction 0.5000 -> True
H3b removed triangles 192: with more than half visible 3, max fraction 0.6614 -> True
H4  removed by Sanitize beyond the centre rule 0, zeroed boxes kept 0 -> True
H5a kept rectangles: min(4*vis - total) 1783 (> 0), min fraction 0.4282 -> True
H5b kept triangles with less than a quarter visible 7, min fraction 0.0171 -> True

Checks. The data check held in every part: the rendered areas are within 0.14 % of the analytic areas, the rectangles exactly; the rectangle masks equal their boxes; no two masks share a pixel; the triangles’ box centres are 23.28 and 13.01 pixels from their mass centroids. C0 held: on the 45 identity samples and on the full-image crop every box equals its ground truth and none is removed. C-draw held. Two of its margins are printed at their limits, the aspect ratio at 0.0000 and the IoU at 0.000e+00, and both are exactly 0: the .3e format prints 0.000e+00 only for an exact zero, and an aspect margin that is not zero, (2w−h)/(2h)(2w - h)/(2h) or (2h−w)/h(2h - w)/h for integer sizes up to 256, is at least 1/5121/512 and would print as at least 0.0020. So at least one accepted crop has an aspect ratio of exactly 0.5 or 2 and at least one has a best IoU exactly equal to its option, both allowed by the inclusive tests in make_params (lines 1197 and 1227). C-clamp and C-sanitize held, including the area case: the 1.5 × 1.5 box survives the defaults and is removed with min_area=4. The draw produced 200 samples; the counts per option are 38, 39, 43, 31, 4, 0 and 45 for 0.0 to 1.0.

Hypotheses. H1 held: all 125 kept rectangles have a clamped box equal to the tight box of what is visible. H2 held for both types, with 5 kept ellipse boxes and 68 kept triangle boxes looser than their visible parts, and H2′ held: all 5 of the ellipse cases are E2’s, and E1’s 95 kept boxes match exactly, like the rectangles’. So the clamped box is exact in every kept crop only for the objects whose extreme points lie on the box’s centre lines, the rectangles and the axis-aligned ellipse; for the triangles the clamped box can be much larger than the visible part, down to an IoU of 0.046 for T2. H3a held, at its bound: R1 was removed with exactly half its area visible (2⋅visible−total=02 \cdot \text{visible} - \text{total} = 0), the equality case the strict centre test allows for an integer centre; R2’s largest removed fraction is 0.459. H3b held: 3 triangles were removed with more than half their area visible, the largest with 66 % of T1 still in the crop. H4 held: Sanitize removed no box beyond those the centre rule had zeroed, and every zeroed box was removed. H5a held, with at least 43 % of a kept rectangle visible; H5b held, with 7 kept triangles that have less than a quarter of their area visible, the smallest only 1.7 % of T2.

Read together, and in our reading, the outcomes show what a detector trained with this crop is given. A kept box is a full-strength training target even when its object is a sliver near the crop edge, as long as the object’s box centre is inside, and a removed object can still be largely visible in the image, now unlabelled, when its box centre falls just outside. Boxes are sure to stay exact only for shapes whose extremes sit on the box’s centre lines; for others, clamping gives the crop’s corner of the original box rather than the visible object. Masks, carried through sanitize with their boxes, keep the exact visible region, and a pipeline that needs tight boxes after a crop can recompute them from masks (for example with masks_to_boxes).

Runs and disclosures. The hypotheses, bars and checks were written before any script ran; a planning script then checked on constructed crops (not random draws) that a correct port can reach each bound and case. The pilot ran the same script with seed 1 before this first run with seed 0, the planned difference. Every check and every hypothesis held on both seeds, so no outcome differs between them; the printed values differ. The two C-draw margins printed at their limits were also re-printed unrounded, as a verification, by a copy of the script with one added print, run once by the drafter and once by the fact-checker; it is not part of the example. After the first run, the only change to the script was to its header comment, which now also names box_iou among the ported functions; the output is identical, and the script produced identical output twice.

For comparison, the same pipeline in torchvision itself would be written with the real classes, as in the detection example of transforms.rst and the SSD preset of the reference scripts. This sketch was not run:

# Not run: torchvision 0.29.2 API, from docs/source/transforms.rst and references/detection/presets.py
import torch
from torchvision import tv_tensors
from torchvision.transforms import v2

img = tv_tensors.Image(torch.zeros(3, 256, 256, dtype=torch.uint8))
target = {
    "boxes": tv_tensors.BoundingBoxes([[16, 20, 80, 60]], format="XYXY", canvas_size=(256, 256)),
    "labels": torch.tensor([1]),
}
pipeline = v2.Compose([
    v2.RandomIoUCrop(),           # draws a crop, zeroes boxes whose centres fall outside
    v2.RandomHorizontalFlip(p=0.5),
    v2.ToDtype(torch.float32, scale=True),
    v2.SanitizeBoundingBoxes(),   # removes the zeroed boxes and their labels
])
img, target = pipeline(img, target)

Ecosystem and Integrations

torchvision is part of the PyTorch project and is built against it: its models are torch.nn.Modules, its datasets are torch.utils.data.Datasets, and its weights are fetched with torch.hub (models.rst); the PyTorch article covers the framework, whose design Paszke et al. (2019) describe, torch.hub and the project’s other libraries. Its image backends are tensors and PIL images, with Pillow-SIMD named in the README as a faster drop-in replacement for Pillow. It is handing media decoding to TorchCodec: video decoding was removed in 0.26 and the image decoders were deprecated in 0.29. Other detection platforms depend on it: Detectron2’s installation notes require “torchvision that matches the PyTorch installation” (Detectron2 INSTALL.md at commit 247691a). Models built with torchvision are ordinary PyTorch modules, which PyTorch’s tools can export, for example to ONNX, and deployment concerns such as matching the training preprocessing are covered in Model Deployment and Edge Inference.

Alternatives

torchvision is the vision library of one framework, so its alternatives depend on which part is replaced. For image processing without a deep-learning framework, OpenCV and scikit-image provide classical operations on arrays. For detection and segmentation models on PyTorch, other code bases include Detectron2 (Wu et al., 2019), which the Mask R-CNN article describes as the PyTorch successor of Detectron, and MMDetection, and the PyTorch article names TIMM as a library of vision models; this article does not compare them. Other frameworks, such as TensorFlow, have their own data and model libraries. In our reading, the conventions that matter when components are mixed are the ones this article lists: continuous box coordinates clamped to [0,W][0, W], float images in [0,1][0, 1], and where resizing and normalization happen.

Versions and Compatibility

As of November 2026 the newest release is 0.29.2 (28 October 2026), a minor release that its notes describe as compatible with PyTorch 2.14 and later, with a single py3-none wheel per platform and input checks added to the CPU RoI kernels. The recent history, from the GitHub release notes:

Version Date Main change
0.15 March 2023 transforms.v2 released (transforms.rst)
0.23 — Rotated bounding boxes, Beta (_bounding_boxes.py docstring)
0.25.0 21 January 2026 Keypoints no longer clamped by default after a transform; SanitizeKeyPoints added
0.26.0 23 March 2026 Video decoding and encoding removed in favour of TorchCodec; image decoders kept
0.27.0 13 May 2026 Lanczos interpolation for v2.Resize on CPU; rotated boxes in box_iou
0.28.0 8 July 2026 wrap() keeps metadata of custom TVTensor subclasses
0.29.0 2 September 2026 ABI stability with respect to PyTorch 2.14; image decoders and encoders deprecated in favour of TorchCodec
0.29.1 30 September 2026 Requirement relaxed from torch==2.14.0 to torch>=2.14
0.29.2 28 October 2026 Packaging and bug fixes

The 0.29.0 notes say that torchvision 0.29 will be compatible with future PyTorch versions (2.15, 2.16 and so on), so users need not install a new torchvision when they upgrade PyTorch, and that releases may no longer be in step with PyTorch’s while development continues. Before 0.29, each torchvision release matched one PyTorch release; the README’s compatibility table at the 0.29.2 tag stops at PyTorch 2.13 and torchvision 0.28, so it does not yet list 0.29. The detection, segmentation and rotated-box APIs are Beta, and the documentation warns that DEFAULT weights may change across versions, so, in our reading, code that must reproduce results should name a specific weights entry rather than DEFAULT.

Licences. The code is under the BSD 3-Clause licence (“Copyright (c) Soumith Chintala 2016”). The README’s section on pretrained models says the models “may have their own licenses or terms and conditions derived from the dataset used for training”, that users must check whether they may use them for their purpose, and that the SWAG models are released under CC-BY-NC 4.0. Datasets keep their own licences, under the disclaimer quoted above.

Limitations

  • Box bookkeeping is approximate for non-rectangular objects. Crops clamp boxes rather than recomputing them, so a box can be much looser than the visible object, and RandomIoUCrop keeps or drops an object by its box centre alone, as the example shows on its port. Masks are cropped exactly and can be used to recompute boxes.
  • Documentation and code differ on RandomIoUCrop. The docstring describes removal of boxes below an IoU threshold, while the code zeroes boxes by the centre rule (_geometry.py line 1244); users who need a different rule must filter boxes themselves.
  • Stale or Beta parts. The detection, segmentation and rotated-box APIs are Beta, without backward-compatibility commitments; models.rst still announces the removal of pretrained for v0.15; and the README’s version table stops at 0.28.
  • Detection models own their preprocessing. Resizing, normalization and padding happen inside GeneralizedRCNNTransform, so the inputs are float images in [0,1][0, 1] at their own size; in our reading, a pipeline that also resizes outside the model, as the multi-scale training preset does, resizes each image twice.
  • Weights and datasets carry their own terms. Pretrained weights are downloaded on first use and some are non-commercial; the library downloads datasets it does not host, and their licences are the user’s responsibility.
  • Media decoding is moving out. Video decoding has been removed and image decoding is deprecated in favour of TorchCodec, so code that reads media through torchvision.io will need to change.
  • Reference scripts are not the library. Training recipes, aspect-ratio grouping and detection presets live in references/, without backward-compatibility guarantees, and may need the latest PyTorch and torchvision.

Related

  • Bounding Box

    The smallest axis-aligned rectangle that encloses an object in an image, the standard way to say where an object is in detection, tracking, and annotation.

  • Deploying Vision Models

    Getting a trained vision model into use, from export and the choice of runtime to packaging the model with its preprocessing contract, serving it on a server or a device, keeping pre- and post-processing identical to training, and versioning, rolling back and monitoring it.

  • Non-Maximum Suppression

    The post-processing step that removes duplicate detections by repeatedly keeping the highest-scoring box and discarding the boxes that overlap it beyond an IoU threshold, with its soft, distance-aware and learned variants.

  • RoI Pooling

    How a region-based detector turns each candidate box on a shared feature map into a fixed-size feature grid, from RoI pooling in SPP-net and Fast R-CNN through RoI warping, RoIAlign and precise RoI pooling to position-sensitive, multi-level and rotated variants.

  • Faster R-CNN

    A two-stage object detector in which a region proposal network, sharing the detector's convolutional features, replaces hand-designed region proposals, making proposal generation nearly free and the whole detector one network.

  • ResNet

    The family of residual convolutional networks introduced by He et al. in 2015, a 7×7 stem and four stages of basic or bottleneck residual blocks at strides 4 to 32, in depths from ResNet-18 to ResNet-152, with its main variants (v1.5, pre-activation, Wide ResNet, ResNeXt, ResNet-D) and the training recipes that changed its accuracy.

References

  1. TorchVision maintainers and contributors (2016). TorchVision: PyTorch's Computer Vision library. GitHub repository pytorch/vision (CITATION.cff; BSD-3-Clause).
  2. TorchVision source code (version 0.29.2): README.md, CITATION.cff and LICENSE.
  3. TorchVision documentation (version 0.29.2): Transforming images, videos, boxes and more (docs/source/transforms.rst) and TVTensors (docs/source/tv_tensors.rst).
  4. TorchVision documentation (version 0.29.2): Models and pre-trained weights (docs/source/models.rst).
  5. TorchVision documentation (version 0.29.2): index, Operators, Datasets, Feature extraction for model inspection and Training references (docs/source/index.rst, ops.rst, datasets.rst, feature_extraction.rst, training_references.rst).
  6. TorchVision source code (version 0.29.2): torchvision/transforms/v2/_geometry.py (RandomIoUCrop) and torchvision/transforms/v2/_misc.py (SanitizeBoundingBoxes).
  7. TorchVision source code (version 0.29.2): torchvision/transforms/v2/functional (_geometry.py, _meta.py, _misc.py).
  8. TorchVision source code (version 0.29.2): torchvision/tv_tensors/_bounding_boxes.py.
  9. TorchVision source code (version 0.29.2): torchvision/ops/boxes.py.
  10. TorchVision source code (version 0.29.2): torchvision/models/_api.py, torchvision/models/detection/transform.py and torchvision/transforms/_presets.py.
  11. TorchVision source code (version 0.29.2): references/detection/presets.py and references/detection/group_by_aspect_ratio.py.
  12. TorchVision release notes (GitHub releases of pytorch/vision, v0.25.0 to v0.29.2).
  13. Meta AI Research. detectron2: INSTALL.md, commit 247691a (main, 27 October 2026). GitHub repository facebookresearch/detectron2 (read November 2026).
  14. Wu, Y., Kirillov, A., Massa, F., Lo, W.-Y. & Girshick, R. (2019). Detectron2. Source code.
  15. Paszke, A., Gross, S., Massa, F., Lerer, A., Bradbury, J., Chanan, G., Killeen, T., Lin, Z., Gimelshein, N., Antiga, L., et al. (2019). PyTorch: An Imperative Style, High-Performance Deep Learning Library. Advances in Neural Information Processing Systems 32 (NeurIPS).
  16. Marcel, S. & Rodriguez, Y. (2010). Torchvision: the machine-vision package of Torch. ACM International Conference on Multimedia (not read).