From 4736b104b9b4fdaf9b130aa5a5c2f21aaf747d93 Mon Sep 17 00:00:00 2001
From: medisean <6093631+medisean@users.noreply.github.com>
Date: Sun, 9 Aug 2026 01:45:31 +0800
Subject: [PATCH] Clarify AnchorGenerator feature-map mapping

---
 torchvision/models/detection/anchor_utils.py | 23 ++++++++++++++------
 1 file changed, 16 insertions(+), 7 deletions(-)

diff --git a/torchvision/models/detection/anchor_utils.py b/torchvision/models/detection/anchor_utils.py
index 4722e1550c2..6bfcd55c97b 100644
--- a/torchvision/models/detection/anchor_utils.py
+++ b/torchvision/models/detection/anchor_utils.py
@@ -16,16 +16,25 @@ class AnchorGenerator(nn.Module):
     per feature map. This module assumes aspect ratio = height / width for
     each anchor.
 
-    sizes and aspect_ratios should have the same number of elements, and it should
-    correspond to the number of feature maps.
+    For ``N`` feature maps, ``sizes`` and ``aspect_ratios`` should each contain
+    ``N`` tuples. The values in ``sizes[i]`` and ``aspect_ratios[i]`` are used
+    only for feature map ``i``; they are not distributed across feature maps.
+    ``AnchorGenerator`` outputs ``len(sizes[i]) * len(aspect_ratios[i])`` anchors
+    per spatial location on that feature map.
 
-    sizes[i] and aspect_ratios[i] can have an arbitrary number of elements,
-    and AnchorGenerator will output a set of sizes[i] * aspect_ratios[i] anchors
-    per spatial location for feature map i.
+    ``AnchorGenerator`` itself supports a different number of anchors per location
+    on each feature map. However, detection heads that share prediction layers
+    across feature maps, such as :class:`~torchvision.models.detection.rpn.RPNHead`,
+    require the number of anchors per location to be the same for every feature map.
 
     Args:
-        sizes (Tuple[Tuple[int]]):
-        aspect_ratios (Tuple[Tuple[float]]):
+        sizes (Tuple[Tuple[int]]): Anchor sizes for each feature map. For example,
+            ``((32, 64, 128),)`` applies all three sizes to a single feature map,
+            while ``((32,), (64,), (128,))`` applies one size to each of three
+            feature maps.
+        aspect_ratios (Tuple[Tuple[float]]): Anchor aspect ratios for each feature
+            map, expressed as height divided by width. The outer tuple follows the
+            same one-to-one feature-map mapping as ``sizes``.
     """
 
     __annotations__ = {