class_docstr: Implementation of `DINO: DETR with Improved DeNoising Anchor Boxes
  for End-to-End Object Detection <https://arxiv.org/abs/2203.03605>`_
  
  Code is modified from the `official github repo
  <https://github.com/IDEA-Research/DINO>`_.
  
  Args:
      dn_cfg (:obj:`ConfigDict` or dict, optional): Config of denoising
          query generator. Defaults to `None`.
class_docstr_tok: ["Implementation","of","`","DINO",":","DETR","with","Improved","DeNoising","Anchor","Boxes","for","End-to-End","Object","Detection","<","https",":","\/\/arxiv.org\/abs\/2203.03605",">","`","_","Code","is","modified","from","the","`","official","github","repo","<","https",":","\/\/github.com\/IDEA-Research\/DINO",">","`","_",".","Args",":","dn_cfg","(",":","obj",":","`","ConfigDict","`","or","dict",",","optional",")",":","Config","of","denoising","query","generator",".","Defaults","to","`","None","`","."]
docstr: Forward with Transformer decoder.
  
  The forward procedure of the transformer is defined as:
  'pre_transformer' -> 'encoder' -> 'pre_decoder' -> 'decoder'
  More details can be found at `TransformerDetector.forward_transformer`
  in `mmdet/detector/base_detr.py`.
  
  Args:
      query (Tensor): The queries of decoder inputs, has shape
          (bs, num_queries_total, dim), where `num_queries_total` is the
          sum of `num_denoising_queries` and `num_matching_queries` when
          `self.training` is `True`, else `num_matching_queries`.
      memory (Tensor): The output embeddings of the Transformer encoder,
          has shape (bs, num_feat_points, dim).
      memory_mask (Tensor): ByteTensor, the padding mask of the memory,
          has shape (bs, num_feat_points).
      reference_points (Tensor): The initial reference, has shape
          (bs, num_queries_total, 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).
      dn_mask (Tensor, optional): The attention mask to prevent
          information leakage from different denoising groups and
          matching parts, will be used as `self_attn_mask` of the
          `self.decoder`, has shape (num_queries_total,
          num_queries_total).
          It is `None` when `self.training` is `False`.
  
  Returns:
      dict: The dictionary of decoder outputs, which includes the
      `hidden_states` of the decoder output and `references` including
      the initial and intermediate reference_points.
docstr_tok: ["Forward","with","Transformer","decoder",".","The","forward","procedure","of","the","transformer","is","defined","as",":","'pre_transformer","'","-",">","'encoder","'","-",">","'pre_decoder","'","-",">","'decoder'","More","details","can","be","found","at","`","TransformerDetector.forward_transformer","`","in","`","mmdet\/detector\/base_detr.py","`",".","Args",":","query","(","Tensor",")",":","The","queries","of","decoder","inputs",",","has","shape","(","bs",",","num_queries_total",",","dim",")",",","where","`","num_queries_total","`","is","the","sum","of","`","num_denoising_queries","`","and","`","num_matching_queries","`","when","`","self.training","`","is","`","True","`",",","else","`","num_matching_queries","`",".","memory","(","Tensor",")",":","The","output","embeddings","of","the","Transformer","encoder",",","has","shape","(","bs",",","num_feat_points",",","dim",")",".","memory_mask","(","Tensor",")",":","ByteTensor",",","the","padding","mask","of","the","memory",",","has","shape","(","bs",",","num_feat_points",")",".","reference_points","(","Tensor",")",":","The","initial","reference",",","has","shape","(","bs",",","num_queries_total",",","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",")",".","dn_mask","(","Tensor",",","optional",")",":","The","attention","mask","to","prevent","information","leakage","from","different","denoising","groups","and","matching","parts",",","will","be","used","as","`","self_attn_mask","`","of","the","`","self.decoder","`",",","has","shape","(","num_queries_total",",","num_queries_total",")",".","It","is","`","None","`","when","`","self.training","`","is","`","False","`",".","Returns",":","dict",":","The","dictionary","of","decoder","outputs",",","which","includes","the","`","hidden_states","`","of","the","decoder","output","and","`","references","`","including","the","initial","and","intermediate","reference_points","."]
code: def forward_decoder(
      self,
      query: Tensor,
      memory: Tensor,
      memory_mask: Tensor,
      reference_points: Tensor,
      spatial_shapes: Tensor,
      level_start_index: Tensor,
      valid_ratios: Tensor,
      dn_mask: Optional[Tensor] = None,
      **kwargs,
  ) -> Dict:
      """Forward with Transformer decoder.
  
      The forward procedure of the transformer is defined as:
      'pre_transformer' -> 'encoder' -> 'pre_decoder' -> 'decoder'
      More details can be found at `TransformerDetector.forward_transformer`
      in `mmdet/detector/base_detr.py`.
  
      Args:
          query (Tensor): The queries of decoder inputs, has shape
              (bs, num_queries_total, dim), where `num_queries_total` is the
              sum of `num_denoising_queries` and `num_matching_queries` when
              `self.training` is `True`, else `num_matching_queries`.
          memory (Tensor): The output embeddings of the Transformer encoder,
              has shape (bs, num_feat_points, dim).
          memory_mask (Tensor): ByteTensor, the padding mask of the memory,
              has shape (bs, num_feat_points).
          reference_points (Tensor): The initial reference, has shape
              (bs, num_queries_total, 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).
          dn_mask (Tensor, optional): The attention mask to prevent
              information leakage from different denoising groups and
              matching parts, will be used as `self_attn_mask` of the
              `self.decoder`, has shape (num_queries_total,
              num_queries_total).
              It is `None` when `self.training` is `False`.
  
      Returns:
          dict: The dictionary of decoder outputs, which includes the
          `hidden_states` of the decoder output and `references` including
          the initial and intermediate reference_points.
      """
      inter_states, references = self.decoder(
          query=query,
          value=memory,
          key_padding_mask=memory_mask,
          self_attn_mask=dn_mask,
          reference_points=reference_points,
          spatial_shapes=spatial_shapes,
          level_start_index=level_start_index,
          valid_ratios=valid_ratios,
          reg_branches=self.bbox_head.reg_branches,
          **kwargs,
      )
  
      if len(query) == self.num_queries:
          # NOTE: This is to make sure label_embeding can be involved to
          # produce loss even if there is no denoising query (no ground truth
          # target in this GPU), otherwise, this will raise runtime error in
          # distributed training.
          inter_states[0] += (
              self.dn_query_generator.label_embedding.weight[0, 0] * 0.0
          )
  
      decoder_outputs_dict = dict(
          hidden_states=inter_states, references=list(references)
      )
      return decoder_outputs_dict
  
file_path: mmdetection/mmdet/models/detectors/dino.py
imports: from typing import Dict, Optional, Tuple
  import torch
  from torch import Tensor, nn
  from torch.nn.init import normal_
  from mmdet.registry import MODELS
  from mmdet.structures import OptSampleList
  from mmdet.utils import OptConfigType
  from ..layers import CdnQueryGenerator, DeformableDetrTransformerEncoder, DinoTransformerDecoder, SinePositionalEncoding
  from .deformable_detr import DeformableDETR, MultiScaleDeformableAttention
label_desc: Use image node_id 6 for calling the DINO obj's underlying member method code with example usage: obj.forward_decoder(query, memory, memory_mask, reference_points, spatial_shapes, level_start_index, valid_ratios, dn_mask) and returns: decoder_outputs_dict