class_docstr: Region Proposal Network, introduced by :paper:`Faster R-CNN`.
class_docstr_tok: ["Region","Proposal","Network",",","introduced","by",":","paper",":","`","Faster","R-CNN","`","."]
docstr: Args:
      anchors (list[Boxes]): anchors for each feature map.
      gt_instances: the ground-truth instances for each image.
  
  Returns:
      list[Tensor]:
          List of #img tensors. i-th element is a vector of labels whose length is
          the total number of anchors across all feature maps R = sum(Hi * Wi * A).
          Label values are in {-1, 0, 1}, with meanings: -1 = ignore; 0 = negative
          class; 1 = positive class.
      list[Tensor]:
          i-th element is a Rx4 tensor. The values are the matched gt boxes for each
          anchor. Values are undefined for those anchors not labeled as 1.
docstr_tok: ["Args",":","anchors","(","list","[","Boxes","]",")",":","anchors","for","each","feature","map",".","gt_instances",":","the","ground-truth","instances","for","each","image",".","Returns",":","list","[","Tensor","]",":","List","of","#","img","tensors",".","i-th","element","is","a","vector","of","labels","whose","length","is","the","total","number","of","anchors","across","all","feature","maps","R","=","sum","(","Hi","*","Wi","*","A",")",".","Label","values","are","in","{","-1",",","0",",","1","}",",","with","meanings",":","-1","=","ignore",";","0","=","negative","class",";","1","=","positive","class",".","list","[","Tensor","]",":","i-th","element","is","a","Rx4","tensor",".","The","values","are","the","matched","gt","boxes","for","each","anchor",".","Values","are","undefined","for","those","anchors","not","labeled","as","1","."]
code: def label_and_sample_anchors(
      self, anchors: List[Boxes], gt_instances: List[Instances]
  ) -> Tuple[List[torch.Tensor], List[torch.Tensor]]:
      """
      Args:
          anchors (list[Boxes]): anchors for each feature map.
          gt_instances: the ground-truth instances for each image.
  
      Returns:
          list[Tensor]:
              List of #img tensors. i-th element is a vector of labels whose length is
              the total number of anchors across all feature maps R = sum(Hi * Wi * A).
              Label values are in {-1, 0, 1}, with meanings: -1 = ignore; 0 = negative
              class; 1 = positive class.
          list[Tensor]:
              i-th element is a Rx4 tensor. The values are the matched gt boxes for each
              anchor. Values are undefined for those anchors not labeled as 1.
      """
      anchors = Boxes.cat(anchors)
  
      gt_boxes = [x.gt_boxes for x in gt_instances]
      image_sizes = [x.image_size for x in gt_instances]
      del gt_instances
  
      gt_labels = []
      matched_gt_boxes = []
      for image_size_i, gt_boxes_i in zip(image_sizes, gt_boxes):
          """
          image_size_i: (h, w) for the i-th image
          gt_boxes_i: ground-truth boxes for i-th image
          """
  
          match_quality_matrix = retry_if_cuda_oom(pairwise_iou)(
              gt_boxes_i, anchors
          )
          matched_idxs, gt_labels_i = retry_if_cuda_oom(
              self.anchor_matcher
          )(match_quality_matrix)
          # Matching is memory-expensive and may result in CPU tensors. But the result is small
          gt_labels_i = gt_labels_i.to(device=gt_boxes_i.device)
          del match_quality_matrix
  
          if self.anchor_boundary_thresh >= 0:
              # Discard anchors that go out of the boundaries of the image
              # NOTE: This is legacy functionality that is turned off by default in Detectron2
              anchors_inside_image = anchors.inside_box(
                  image_size_i, self.anchor_boundary_thresh
              )
              gt_labels_i[~anchors_inside_image] = -1
  
          # A vector of labels (-1, 0, 1) for each anchor
          gt_labels_i = self._subsample_labels(gt_labels_i)
  
          if len(gt_boxes_i) == 0:
              # These values won't be used anyway since the anchor is labeled as background
              matched_gt_boxes_i = torch.zeros_like(anchors.tensor)
          else:
              # TODO wasted indexing computation for ignored boxes
              matched_gt_boxes_i = gt_boxes_i[matched_idxs].tensor
  
          gt_labels.append(gt_labels_i)  # N,AHW
          matched_gt_boxes.append(matched_gt_boxes_i)
      return gt_labels, matched_gt_boxes
  
imports: from typing import Dict, List, Optional, Tuple, Union
  import torch
  import torch.nn.functional
  from torch import nn
  from detectron2.config import configurable
  from detectron2.layers import Conv2d, ShapeSpec, cat
  from detectron2.structures import Boxes, ImageList, Instances, pairwise_iou
  from detectron2.utils.events import get_event_storage
  from detectron2.utils.memory import retry_if_cuda_oom
  from detectron2.utils.registry import Registry
  from ..anchor_generator import build_anchor_generator
  from ..box_regression import Box2BoxTransform, _dense_box_regression_loss
  from ..matcher import Matcher
  from ..sampling import subsample_labels
  from .build import PROPOSAL_GENERATOR_REGISTRY
  from .proposal_utils import find_top_rpn_proposals
label_desc: Use image node_id 4 for calling the RPN obj's underlying member method code with example usage: obj.label_and_sample_anchors(anchors, gt_instances) and returns: gt_labels,  matched_gt_boxes