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: Prepare intermediate variables before entering Transformer decoder,
  such as `query`, `query_pos`, and `reference_points`.
  
  Args:
      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). Will only be used when
          `as_two_stage` is `True`.
      spatial_shapes (Tensor): Spatial shapes of features in all levels.
          With shape (num_levels, 2), last dimension represents (h, w).
          Will only be used when `as_two_stage` is `True`.
      batch_data_samples (list[:obj:`DetDataSample`]): The batch
          data samples. It usually includes information such
          as `gt_instance` or `gt_panoptic_seg` or `gt_sem_seg`.
          Defaults to None.
  
  Returns:
      tuple[dict]: The decoder_inputs_dict and head_inputs_dict.
  
      - decoder_inputs_dict (dict): The keyword dictionary args of
        `self.forward_decoder()`, which includes 'query', 'memory',
        `reference_points`, and `dn_mask`. The reference points of
        decoder input here are 4D boxes, although it has `points`
        in its name.
      - head_inputs_dict (dict): The keyword dictionary args of the
        bbox_head functions, which includes `topk_score`, `topk_coords`,
        and `dn_meta` when `self.training` is `True`, else is empty.
docstr_tok: ["Prepare","intermediate","variables","before","entering","Transformer","decoder",",","such","as","`","query","`",",","`","query_pos","`",",","and","`","reference_points","`",".","Args",":","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",")",".","Will","only","be","used","when","`","as_two_stage","`","is","`","True","`",".","spatial_shapes","(","Tensor",")",":","Spatial","shapes","of","features","in","all","levels",".","With","shape","(","num_levels",",","2",")",",","last","dimension","represents","(","h",",","w",")",".","Will","only","be","used","when","`","as_two_stage","`","is","`","True","`",".","batch_data_samples","(","list","[",":","obj",":","`","DetDataSample","`","]",")",":","The","batch","data","samples",".","It","usually","includes","information","such","as","`","gt_instance","`","or","`","gt_panoptic_seg","`","or","`","gt_sem_seg","`",".","Defaults","to","None",".","Returns",":","tuple","[","dict","]",":","The","decoder_inputs_dict","and","head_inputs_dict",".","-","decoder_inputs_dict","(","dict",")",":","The","keyword","dictionary","args","of","`","self.forward_decoder","(",")","`",",","which","includes","'query","'",",","'memory","'",",","`","reference_points","`",",","and","`","dn_mask","`",".","The","reference","points","of","decoder","input","here","are","4D","boxes",",","although","it","has","`","points","`","in","its","name",".","-","head_inputs_dict","(","dict",")",":","The","keyword","dictionary","args","of","the","bbox_head","functions",",","which","includes","`","topk_score","`",",","`","topk_coords","`",",","and","`","dn_meta","`","when","`","self.training","`","is","`","True","`",",","else","is","empty","."]
code: def pre_decoder(
      self,
      memory: Tensor,
      memory_mask: Tensor,
      spatial_shapes: Tensor,
      batch_data_samples: OptSampleList = None,
  ) -> Tuple[Dict]:
      """Prepare intermediate variables before entering Transformer decoder,
      such as `query`, `query_pos`, and `reference_points`.
  
      Args:
          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). Will only be used when
              `as_two_stage` is `True`.
          spatial_shapes (Tensor): Spatial shapes of features in all levels.
              With shape (num_levels, 2), last dimension represents (h, w).
              Will only be used when `as_two_stage` is `True`.
          batch_data_samples (list[:obj:`DetDataSample`]): The batch
              data samples. It usually includes information such
              as `gt_instance` or `gt_panoptic_seg` or `gt_sem_seg`.
              Defaults to None.
  
      Returns:
          tuple[dict]: The decoder_inputs_dict and head_inputs_dict.
  
          - decoder_inputs_dict (dict): The keyword dictionary args of
            `self.forward_decoder()`, which includes 'query', 'memory',
            `reference_points`, and `dn_mask`. The reference points of
            decoder input here are 4D boxes, although it has `points`
            in its name.
          - head_inputs_dict (dict): The keyword dictionary args of the
            bbox_head functions, which includes `topk_score`, `topk_coords`,
            and `dn_meta` when `self.training` is `True`, else is empty.
      """
      bs, _, c = memory.shape
      cls_out_features = self.bbox_head.cls_branches[
          self.decoder.num_layers
      ].out_features
  
      (
          output_memory,
          output_proposals,
      ) = self.gen_encoder_output_proposals(
          memory, memory_mask, spatial_shapes
      )
      enc_outputs_class = self.bbox_head.cls_branches[
          self.decoder.num_layers
      ](output_memory)
      enc_outputs_coord_unact = (
          self.bbox_head.reg_branches[self.decoder.num_layers](
              output_memory
          )
          + output_proposals
      )
  
      # NOTE The DINO selects top-k proposals according to scores of
      # multi-class classification, while DeformDETR, where the input
      # is `enc_outputs_class[..., 0]` selects according to scores of
      # binary classification.
      topk_indices = torch.topk(
          enc_outputs_class.max(-1)[0], k=self.num_queries, dim=1
      )[1]
      topk_score = torch.gather(
          enc_outputs_class,
          1,
          topk_indices.unsqueeze(-1).repeat(1, 1, cls_out_features),
      )
      topk_coords_unact = torch.gather(
          enc_outputs_coord_unact,
          1,
          topk_indices.unsqueeze(-1).repeat(1, 1, 4),
      )
      topk_coords = topk_coords_unact.sigmoid()
      topk_coords_unact = topk_coords_unact.detach()
  
      query = self.query_embedding.weight[:, None, :]
      query = query.repeat(1, bs, 1).transpose(0, 1)
      if self.training:
          (
              dn_label_query,
              dn_bbox_query,
              dn_mask,
              dn_meta,
          ) = self.dn_query_generator(batch_data_samples)
          query = torch.cat([dn_label_query, query], dim=1)
          reference_points = torch.cat(
              [dn_bbox_query, topk_coords_unact], dim=1
          )
      else:
          reference_points = topk_coords_unact
          dn_mask, dn_meta = None, None
      reference_points = reference_points.sigmoid()
  
      decoder_inputs_dict = dict(
          query=query,
          memory=memory,
          reference_points=reference_points,
          dn_mask=dn_mask,
      )
      # NOTE DINO calculates encoder losses on scores and coordinates
      # of selected top-k encoder queries, while DeformDETR is of all
      # encoder queries.
      head_inputs_dict = (
          dict(
              enc_outputs_class=topk_score,
              enc_outputs_coord=topk_coords,
              dn_meta=dn_meta,
          )
          if self.training
          else dict()
      )
      return decoder_inputs_dict, head_inputs_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 5 for calling the DINO obj's underlying member method code with example usage: obj.pre_decoder(memory, memory_mask, spatial_shapes, batch_data_samples) and returns: decoder_inputs_dict,  head_inputs_dict