class_docstr: Transformer decoder of DDQ.
class_docstr_tok: ["Transformer","decoder","of","DDQ","."]
docstr: Forward function of Transformer decoder.
  
  Args:
      query (Tensor): The input query, has shape (bs, num_queries,
          dims).
      value (Tensor): The input values, has shape (bs, num_value, dim).
      key_padding_mask (Tensor): The `key_padding_mask` of `cross_attn`
          input. ByteTensor, has shape (bs, num_value).
      self_attn_mask (Tensor): The attention mask to prevent information
          leakage from different denoising groups, distinct queries and
          dense queries, has shape (num_queries_total,
          num_queries_total). It will be updated for distinct queries
          selection in this forward function. It is `None` when
          `self.training` is `False`.
      reference_points (Tensor): The initial reference, has shape
          (bs, num_queries, 4) with the last dimension arranged as
          (cx, cy, w, h).
      spatial_shapes (Tensor): Spatial shapes of features in all levels,
          has shape (num_levels, 2), last dimension represents (h, w).
      level_start_index (Tensor): The start index of each level.
          A tensor has shape (num_levels, ) and can be represented
          as [0, h_0*w_0, h_0*w_0+h_1*w_1, ...].
      valid_ratios (Tensor): The ratios of the valid width and the valid
          height relative to the width and the height of features in all
          levels, has shape (bs, num_levels, 2).
      reg_branches: (obj:`nn.ModuleList`): Used for refining the
          regression results.
  
  Returns:
      tuple[Tensor]: Output queries and references of Transformer
          decoder
  
      - query (Tensor): Output embeddings of the last decoder, has
        shape (bs, num_queries, embed_dims) when `return_intermediate`
        is `False`. Otherwise, Intermediate output embeddings of all
        decoder layers, has shape (num_decoder_layers, bs, num_queries,
        embed_dims).
      - reference_points (Tensor): The reference of the last decoder
        layer, has shape (bs, num_queries, 4) when `return_intermediate`
        is `False`. Otherwise, Intermediate references of all decoder
        layers, has shape (1 + num_decoder_layers, bs, num_queries, 4).
        The coordinates are arranged as (cx, cy, w, h).
docstr_tok: ["Forward","function","of","Transformer","decoder",".","Args",":","query","(","Tensor",")",":","The","input","query",",","has","shape","(","bs",",","num_queries",",","dims",")",".","value","(","Tensor",")",":","The","input","values",",","has","shape","(","bs",",","num_value",",","dim",")",".","key_padding_mask","(","Tensor",")",":","The","`","key_padding_mask","`","of","`","cross_attn","`","input",".","ByteTensor",",","has","shape","(","bs",",","num_value",")",".","self_attn_mask","(","Tensor",")",":","The","attention","mask","to","prevent","information","leakage","from","different","denoising","groups",",","distinct","queries","and","dense","queries",",","has","shape","(","num_queries_total",",","num_queries_total",")",".","It","will","be","updated","for","distinct","queries","selection","in","this","forward","function",".","It","is","`","None","`","when","`","self.training","`","is","`","False","`",".","reference_points","(","Tensor",")",":","The","initial","reference",",","has","shape","(","bs",",","num_queries",",","4",")","with","the","last","dimension","arranged","as","(","cx",",","cy",",","w",",","h",")",".","spatial_shapes","(","Tensor",")",":","Spatial","shapes","of","features","in","all","levels",",","has","shape","(","num_levels",",","2",")",",","last","dimension","represents","(","h",",","w",")",".","level_start_index","(","Tensor",")",":","The","start","index","of","each","level",".","A","tensor","has","shape","(","num_levels",",",")","and","can","be","represented","as","[","0",",","h_0","*","w_0",",","h_0","*","w_0+h_1","*","w_1",",","...","]",".","valid_ratios","(","Tensor",")",":","The","ratios","of","the","valid","width","and","the","valid","height","relative","to","the","width","and","the","height","of","features","in","all","levels",",","has","shape","(","bs",",","num_levels",",","2",")",".","reg_branches",":","(","obj",":","`","nn.ModuleList","`",")",":","Used","for","refining","the","regression","results",".","Returns",":","tuple","[","Tensor","]",":","Output","queries","and","references","of","Transformer","decoder","-","query","(","Tensor",")",":","Output","embeddings","of","the","last","decoder",",","has","shape","(","bs",",","num_queries",",","embed_dims",")","when","`","return_intermediate","`","is","`","False","`",".","Otherwise",",","Intermediate","output","embeddings","of","all","decoder","layers",",","has","shape","(","num_decoder_layers",",","bs",",","num_queries",",","embed_dims",")",".","-","reference_points","(","Tensor",")",":","The","reference","of","the","last","decoder","layer",",","has","shape","(","bs",",","num_queries",",","4",")","when","`","return_intermediate","`","is","`","False","`",".","Otherwise",",","Intermediate","references","of","all","decoder","layers",",","has","shape","(","1","+","num_decoder_layers",",","bs",",","num_queries",",","4",")",".","The","coordinates","are","arranged","as","(","cx",",","cy",",","w",",","h",")","."]
code: def forward(
      self,
      query: Tensor,
      value: Tensor,
      key_padding_mask: Tensor,
      self_attn_mask: Tensor,
      reference_points: Tensor,
      spatial_shapes: Tensor,
      level_start_index: Tensor,
      valid_ratios: Tensor,
      reg_branches: nn.ModuleList,
      **kwargs,
  ) -> Tensor:
      """Forward function of Transformer decoder.
  
      Args:
          query (Tensor): The input query, has shape (bs, num_queries,
              dims).
          value (Tensor): The input values, has shape (bs, num_value, dim).
          key_padding_mask (Tensor): The `key_padding_mask` of `cross_attn`
              input. ByteTensor, has shape (bs, num_value).
          self_attn_mask (Tensor): The attention mask to prevent information
              leakage from different denoising groups, distinct queries and
              dense queries, has shape (num_queries_total,
              num_queries_total). It will be updated for distinct queries
              selection in this forward function. It is `None` when
              `self.training` is `False`.
          reference_points (Tensor): The initial reference, has shape
              (bs, num_queries, 4) with the last dimension arranged as
              (cx, cy, w, h).
          spatial_shapes (Tensor): Spatial shapes of features in all levels,
              has shape (num_levels, 2), last dimension represents (h, w).
          level_start_index (Tensor): The start index of each level.
              A tensor has shape (num_levels, ) and can be represented
              as [0, h_0*w_0, h_0*w_0+h_1*w_1, ...].
          valid_ratios (Tensor): The ratios of the valid width and the valid
              height relative to the width and the height of features in all
              levels, has shape (bs, num_levels, 2).
          reg_branches: (obj:`nn.ModuleList`): Used for refining the
              regression results.
  
      Returns:
          tuple[Tensor]: Output queries and references of Transformer
              decoder
  
          - query (Tensor): Output embeddings of the last decoder, has
            shape (bs, num_queries, embed_dims) when `return_intermediate`
            is `False`. Otherwise, Intermediate output embeddings of all
            decoder layers, has shape (num_decoder_layers, bs, num_queries,
            embed_dims).
          - reference_points (Tensor): The reference of the last decoder
            layer, has shape (bs, num_queries, 4) when `return_intermediate`
            is `False`. Otherwise, Intermediate references of all decoder
            layers, has shape (1 + num_decoder_layers, bs, num_queries, 4).
            The coordinates are arranged as (cx, cy, w, h).
      """
      intermediate = []
      intermediate_reference_points = [reference_points]
      self.cache_dict["distinct_query_mask"] = []
      if self_attn_mask is None:
          self_attn_mask = torch.zeros(
              (query.size(1), query.size(1)), device=query.device
          ).bool()
      # shape is (batch*number_heads, num_queries, num_queries)
      self_attn_mask = self_attn_mask[None].repeat(
          len(query) * self.cache_dict["num_heads"], 1, 1
      )
      for layer_index, layer in enumerate(self.layers):
          if reference_points.shape[-1] == 4:
              reference_points_input = (
                  reference_points[:, :, None]
                  * torch.cat([valid_ratios, valid_ratios], -1)[:, None]
              )
          else:
              assert reference_points.shape[-1] == 2
              reference_points_input = (
                  reference_points[:, :, None] * valid_ratios[:, None]
              )
  
          query_sine_embed = coordinate_to_encoding(
              reference_points_input[:, :, 0, :],
              num_feats=self.embed_dims // 2,
          )
          query_pos = self.ref_point_head(query_sine_embed)
  
          query = layer(
              query,
              query_pos=query_pos,
              value=value,
              key_padding_mask=key_padding_mask,
              self_attn_mask=self_attn_mask,
              spatial_shapes=spatial_shapes,
              level_start_index=level_start_index,
              valid_ratios=valid_ratios,
              reference_points=reference_points_input,
              **kwargs,
          )
  
          if not self.training:
              tmp = reg_branches[layer_index](query)
              assert reference_points.shape[-1] == 4
              new_reference_points = tmp + inverse_sigmoid(
                  reference_points, eps=1e-3
              )
              new_reference_points = new_reference_points.sigmoid()
              reference_points = new_reference_points.detach()
              if layer_index < (len(self.layers) - 1):
                  self_attn_mask = self.select_distinct_queries(
                      reference_points,
                      query,
                      self_attn_mask,
                      layer_index,
                  )
  
          else:
              num_dense = self.cache_dict["num_dense_queries"]
              tmp = reg_branches[layer_index](query[:, :-num_dense])
              tmp_dense = self.aux_reg_branches[layer_index](
                  query[:, -num_dense:]
              )
  
              tmp = torch.cat([tmp, tmp_dense], dim=1)
              assert reference_points.shape[-1] == 4
              new_reference_points = tmp + inverse_sigmoid(
                  reference_points, eps=1e-3
              )
              new_reference_points = new_reference_points.sigmoid()
              reference_points = new_reference_points.detach()
              if layer_index < (len(self.layers) - 1):
                  self_attn_mask = self.select_distinct_queries(
                      reference_points,
                      query,
                      self_attn_mask,
                      layer_index,
                  )
  
          if self.return_intermediate:
              intermediate.append(self.norm(query))
              intermediate_reference_points.append(new_reference_points)
  
      if self.return_intermediate:
          return torch.stack(intermediate), torch.stack(
              intermediate_reference_points
          )
  
      return query, reference_points
  
file_path: mmdetection/mmdet/models/layers/transformer/ddq_detr_layers.py
imports: import copy
  import torch
  from mmcv.ops import batched_nms
  from torch import Tensor, nn
  from mmdet.structures.bbox import bbox_cxcywh_to_xyxy
  from .deformable_detr_layers import DeformableDetrTransformerDecoder
  from .utils import MLP, coordinate_to_encoding, inverse_sigmoid
label_desc: Use image node_id 3 for calling the DDQTransformerDecoder obj's underlying member method code with example usage: obj.forward(query, value, key_padding_mask, _attn_mask, reference_points, spatial_shapes, level_start_index, valid_ratios, reg_branches) and returns: query,  reference_points, torch,  torch