class_docstr: Head of the Align-DETR: Improving DETR with Simple IoU-aware BCE loss
  
  Code is modified from the `official github repo
  <https://github.com/FelixCaae/AlignDETR>`_.
  
  More details can be found in the `paper
  <https://arxiv.org/abs/2304.07527>`_ .
  
  Args:
      all_layers_num_gt_repeat List[int]: Number to repeat gt for 1-to-k
          matching between ground truth and predictions of each decoder
          layer. Only used for matching queries, not for denoising queries.
          Element count is `num_pred_layer`. If `as_two_stage` is True, then
          the last element is for encoder output, and the others for
          decoder layers. Otherwise, all elements are for decoder layers.
          Defaults to a list of `1` for the last decoder layer and `2` for
          the others.
      alpha (float): Hyper-parameter of classification loss that controls
          the proportion of each item to calculate `t`, the weighted
          geometric average of the confident score and the IoU score, to
          align classification and regression scores. Defaults to `0.25`.
      gamma (float): Hyper-parameter of classification loss to do the hard
          negative mining. Defaults to `2.0`.
      tau (float): Hyper-parameter of classification and regression losses,
          it is the temperature controlling the sharpness of the function
          to calculate positive sample weight. Defaults to `1.5`.
class_docstr_tok: ["Head","of","the","Align-DETR",":","Improving","DETR","with","Simple","IoU-aware","BCE","loss","Code","is","modified","from","the","`","official","github","repo","<","https",":","\/\/github.com\/FelixCaae\/AlignDETR",">","`","_",".","More","details","can","be","found","in","the","`","paper","<","https",":","\/\/arxiv.org\/abs\/2304.07527",">","`","_",".","Args",":","all_layers_num_gt_repeat","List","[","int","]",":","Number","to","repeat","gt","for","1-to-k","matching","between","ground","truth","and","predictions","of","each","decoder","layer",".","Only","used","for","matching","queries",",","not","for","denoising","queries",".","Element","count","is","`","num_pred_layer","`",".","If","`","as_two_stage","`","is","True",",","then","the","last","element","is","for","encoder","output",",","and","the","others","for","decoder","layers",".","Otherwise",",","all","elements","are","for","decoder","layers",".","Defaults","to","a","list","of","`","1","`","for","the","last","decoder","layer","and","`","2","`","for","the","others",".","alpha","(","float",")",":","Hyper-parameter","of","classification","loss","that","controls","the","proportion","of","each","item","to","calculate","`","t","`",",","the","weighted","geometric","average","of","the","confident","score","and","the","IoU","score",",","to","align","classification","and","regression","scores",".","Defaults","to","`","0.25","`",".","gamma","(","float",")",":","Hyper-parameter","of","classification","loss","to","do","the","hard","negative","mining",".","Defaults","to","`","2.0","`",".","tau","(","float",")",":","Hyper-parameter","of","classification","and","regression","losses",",","it","is","the","temperature","controlling","the","sharpness","of","the","function","to","calculate","positive","sample","weight",".","Defaults","to","`","1.5","`","."]
docstr: AlignDETR: Get label targets, label weights, and bbox weights based
      on `t`, the weighted geometric average of the confident score and
      the IoU score, to align classification and regression scores.
  
  Args:
      cls_score (Tensor): Box score logits from the last encoder layer
          or a single decoder layer for one image. Shape
          [num_queries or num_denoising_queries, cls_out_channels].
      bbox_pred (Tensor): Sigmoid outputs from the last encoder layer
          or a single decoder layer for one image, with unnormalized
          coordinate (x, y, x, y) and shape
          [num_queries or num_denoising_queries, 4].
      gt_labels (Tensor): Ground truth classification labels for one
          image, has shape [num_gt].
      pos_gt_bboxes (Tensor): Positive ground truth bboxes for one
          image, with unnormalized coordinate (x, y, x, y) and shape
          [num_positive, 4].
      pos_inds (Tensor): Positive prediction box indices, has shape
          [num_positive].
      pos_assigned_gt_inds Tensor: Positive ground truth box indices,
          has shape [num_positive].
      layer_index (int): decoder layer index for the outputs. Defaults
          to `-1`.
      is_matching_queries (bool): The outputs are from matching
          queries or denoising queries. Defaults to `False`.
  
  Returns:
      tuple[Tensor]: a tuple containing the following for one image.
  
      - label_targets (Tensor): Labels of one image. Shape
          [num_queries or num_denoising_queries, cls_out_channels].
      - label_weights (Tensor): Label weights of one image. Shape
          [num_queries or num_denoising_queries, cls_out_channels].
      - bbox_weights (Tensor): BBox weights of one image. Shape
          [num_queries or num_denoising_queries, 4].
docstr_tok: ["AlignDETR",":","Get","label","targets",",","label","weights",",","and","bbox","weights","based","on","`","t","`",",","the","weighted","geometric","average","of","the","confident","score","and","the","IoU","score",",","to","align","classification","and","regression","scores",".","Args",":","cls_score","(","Tensor",")",":","Box","score","logits","from","the","last","encoder","layer","or","a","single","decoder","layer","for","one","image",".","Shape","[","num_queries","or","num_denoising_queries",",","cls_out_channels","]",".","bbox_pred","(","Tensor",")",":","Sigmoid","outputs","from","the","last","encoder","layer","or","a","single","decoder","layer","for","one","image",",","with","unnormalized","coordinate","(","x",",","y",",","x",",","y",")","and","shape","[","num_queries","or","num_denoising_queries",",","4","]",".","gt_labels","(","Tensor",")",":","Ground","truth","classification","labels","for","one","image",",","has","shape","[","num_gt","]",".","pos_gt_bboxes","(","Tensor",")",":","Positive","ground","truth","bboxes","for","one","image",",","with","unnormalized","coordinate","(","x",",","y",",","x",",","y",")","and","shape","[","num_positive",",","4","]",".","pos_inds","(","Tensor",")",":","Positive","prediction","box","indices",",","has","shape","[","num_positive","]",".","pos_assigned_gt_inds","Tensor",":","Positive","ground","truth","box","indices",",","has","shape","[","num_positive","]",".","layer_index","(","int",")",":","decoder","layer","index","for","the","outputs",".","Defaults","to","`","-1","`",".","is_matching_queries","(","bool",")",":","The","outputs","are","from","matching","queries","or","denoising","queries",".","Defaults","to","`","False","`",".","Returns",":","tuple","[","Tensor","]",":","a","tuple","containing","the","following","for","one","image",".","-","label_targets","(","Tensor",")",":","Labels","of","one","image",".","Shape","[","num_queries","or","num_denoising_queries",",","cls_out_channels","]",".","-","label_weights","(","Tensor",")",":","Label","weights","of","one","image",".","Shape","[","num_queries","or","num_denoising_queries",",","cls_out_channels","]",".","-","bbox_weights","(","Tensor",")",":","BBox","weights","of","one","image",".","Shape","[","num_queries","or","num_denoising_queries",",","4","]","."]
code: def _get_align_detr_targets_single(
      self,
      cls_score: Tensor,
      bbox_pred: Tensor,
      gt_labels: Tensor,
      pos_gt_bboxes: Tensor,
      pos_inds: Tensor,
      pos_assigned_gt_inds: Tensor,
      layer_index: int = -1,
      is_matching_queries: bool = False,
  ):
      """AlignDETR: Get label targets, label weights, and bbox weights based
          on `t`, the weighted geometric average of the confident score and
          the IoU score, to align classification and regression scores.
  
      Args:
          cls_score (Tensor): Box score logits from the last encoder layer
              or a single decoder layer for one image. Shape
              [num_queries or num_denoising_queries, cls_out_channels].
          bbox_pred (Tensor): Sigmoid outputs from the last encoder layer
              or a single decoder layer for one image, with unnormalized
              coordinate (x, y, x, y) and shape
              [num_queries or num_denoising_queries, 4].
          gt_labels (Tensor): Ground truth classification labels for one
              image, has shape [num_gt].
          pos_gt_bboxes (Tensor): Positive ground truth bboxes for one
              image, with unnormalized coordinate (x, y, x, y) and shape
              [num_positive, 4].
          pos_inds (Tensor): Positive prediction box indices, has shape
              [num_positive].
          pos_assigned_gt_inds Tensor: Positive ground truth box indices,
              has shape [num_positive].
          layer_index (int): decoder layer index for the outputs. Defaults
              to `-1`.
          is_matching_queries (bool): The outputs are from matching
              queries or denoising queries. Defaults to `False`.
  
      Returns:
          tuple[Tensor]: a tuple containing the following for one image.
  
          - label_targets (Tensor): Labels of one image. Shape
              [num_queries or num_denoising_queries, cls_out_channels].
          - label_weights (Tensor): Label weights of one image. Shape
              [num_queries or num_denoising_queries, cls_out_channels].
          - bbox_weights (Tensor): BBox weights of one image. Shape
              [num_queries or num_denoising_queries, 4].
      """
  
      # Classification loss
      # =           1 * BCE(prob, t * rank_weights) for positive sample;
      # = prob**gamma * BCE(prob,                0) for negative sample.
      # That is,
      # label_targets = 0                for negative sample;
      #               = t * rank_weights for positive sample.
      # label_weights = pred**gamma for negative sample;
      #               = 1           for positive sample.
      cls_prob = cls_score.sigmoid()
      label_targets = torch.zeros_like(
          cls_score, device=pos_gt_bboxes.device
      )
      label_weights = cls_prob**self.gamma
  
      bbox_weights = torch.zeros_like(
          bbox_pred, dtype=pos_gt_bboxes.dtype
      )
  
      if len(pos_inds) == 0:
          return label_targets, label_weights, bbox_weights
  
      pos_cls_score_inds = (pos_inds, gt_labels[pos_assigned_gt_inds])
      iou_scores = bbox_overlaps(
          bbox_pred[pos_inds], pos_gt_bboxes, is_aligned=True
      )
  
      # t (Tensor): The weighted geometric average of the confident score
      #   and the IoU score, to align classification and regression scores.
      #   Shape [num_positive].
      t = cls_prob[pos_cls_score_inds] ** self.alpha * iou_scores ** (
          1 - self.alpha
      )
      t = torch.clamp(t, 0.01).detach()
  
      # Calculate rank_weights for matching queries.
      if is_matching_queries:
          # rank_weights (Tensor): Weights of each group of predictions
          #   assigned to the same positive gt bbox. Shape [num_positive].
          rank_weights = torch.zeros_like(
              t, dtype=self.weight_table.dtype
          )
  
          assert 0 <= layer_index < len(self.weight_table), layer_index
          rank_to_weight = self.weight_table[layer_index].to(
              rank_weights.device
          )
          unique_gt_inds = torch.unique(pos_assigned_gt_inds)
  
          # For each positive gt bbox, get all predictions assigned to it,
          #   then calculate rank weights for this group of predictions.
          for gt_index in unique_gt_inds:
              pred_group_cond = pos_assigned_gt_inds == gt_index
              # Weights are based on their rank sorted by t in the group.
              pred_group = t[pred_group_cond]
              indices = pred_group.sort(descending=True)[1]
              group_weights = torch.zeros_like(
                  indices, dtype=self.weight_table.dtype
              )
              group_weights[indices] = rank_to_weight[: len(indices)]
              rank_weights[pred_group_cond] = group_weights
  
          t = t * rank_weights
          pos_bbox_weights = rank_weights.unsqueeze(-1).repeat(
              1, bbox_pred.size(-1)
          )
          bbox_weights[pos_inds] = pos_bbox_weights
      else:
          bbox_weights[pos_inds] = 1.0
  
      label_targets[pos_cls_score_inds] = t
      label_weights[pos_cls_score_inds] = 1.0
  
      return label_targets, label_weights, bbox_weights
  
file_path: mmdetection/projects/AlignDETR/align_detr/align_detr_head.py
imports: from typing import Any, Dict, List, Tuple, Union
  import torch
  from mmengine.structures import InstanceData
  from torch import Tensor
  from mmdet.models.dense_heads import DINOHead
  from mmdet.registry import MODELS
  from mmdet.structures.bbox import bbox_cxcywh_to_xyxy, bbox_overlaps, bbox_xyxy_to_cxcywh
  from mmdet.utils import InstanceList
  from .utils import KeysRecorder
label_desc: Use image node_id 8 for calling the AlignDETRHead obj's underlying member method code with example usage: obj._get_align_detr_targets_single(cls_score, bbox_pred, gt_labels, pos_gt_bboxes, pos_inds, pos_assigned_gt_inds, layer_index, is_matching_queries) and returns: label_targets,  label_weights,  bbox_weights, label_targets,  label_weights,  bbox_weights