Context Aware Grounded Teacher for Source Free Object Detection

This is the official Pytorch implementation of Grounded Teacher:

"Grounded Teacher" by Tajamul Ashraf, Rajes Manna, Partha Sarathi Purkayastha, Tavaheed Tariq and Janibul Bashir.

---

NEWS

• [04/26/2025] 💥 We achieved new SoTA with 50.8 box mAP on Cityscapes to Foggy Cityscapes!
• [04/21/2025] We released an arxiv version.. See more details in our updated arxiv!

---

🎯 What is Grounded_Teacher?

Grounded Teacher (GT) is a standard framework in Source Free Object Detection (SFOD) designed to tackle context bias and performance drop of the student model. It models contextual relationships using a dedicated relational context module and leverages this to mitigate inherent biases. GT applies augmentations to closely related classes across and within domains, enhancing underrepresented class performance while minimizing effects on dominant classes. An expert foundational branch supervises the student model, improving prediction quality under the SFOD setting.

🔥 Check out our website for more overview!

---

🔧 Installation

Due to dependency conflicts, this project requires two separate environments. Follow the instructions below to set up each environment correctly.

🔹 Source Train Environment

Requirements:

• Python >= 3.8
• PyTorch = 1.7.1 and torchvision that matches the PyTorch installation.
• Linux, CUDA >= 11.0
• Install Faster-RCNN:

  cd Source/lib
  python setup.py build develop

• Other requirements:

  cd ../
  pip install -r requirements.txt

⚠️ For 30XX series GPUs, set CUDA architecture:

export TORCH_CUDA_ARCH_LIST="8.0"

🔹 Other Environment

Requirements:

• Python ≥ 3.6
• PyTorch ≥ 1.5 and torchvision that matches the PyTorch installation.
• Detectron2 == 0.6
• Other requirements:

  cd Expert
  pip install -r assets/requirements/requirements.txt

---

📁 Dataset Preparation

You can download the Medical datasets from here

City to Foggy dataset Structure:

└── cityscapes/
     ├── gtFine/
     |   ├── train/
     |   └── test/
     |   └── val/
     ├── leftImg8bit/
     |   ├── train/
     |   └── test/
     |   └── val/
└── cityscapes_foggy/
     ├── gtFine/
     |   ├── train/
     |   └── test/
     |   └── val/
     └── leftImg8bit/
         ├── train/
         └── test/
         └── val/

Other datasets must follow the Pascal VOC format structure:

datasets/
└── VOC_format_dataset/
    ├── Annotations/               # XML annotation files
    ├── ImageSets/
    │   └── Main/
    │       ├── train.txt          # List of training image IDs
    │       └── test.txt           # List of testing image IDs
    └── JPEGImages/                # Original images

---

🔄 Pretrained Model Setup

🔸 VGG-16 Backbone

For the VGG backbone, we use converted weights from CMT.

1. Download the pretrained weights from Google Drive Link
2. Place the weights file at: checkpoints/vgg16_bn-6c64b313_converted.pth

🔸 BoimedParse Pretrained model

1. Download the Pretrained model checkpoint from Google Drive Link.
2. Place the weights file at: Expert/pretrained/biomedparse_v1.pt

---

🚀 Training and Evaluation

The implementation follows a step-by-step process for domain adaptation in medical image analysis, requiring switching between environments for each step:

We are demonstrating the DDSM to RSNA.

▶️ Step 1: Source Training on DDSM

First, ensure the VOC_MEDICAL path is correctly set in your Grounded_Teacher/Source/lib/datasets/config_dataset.py.

Download vgg16_caffe.pth and then change the path in Grounded_Teacher/Source/lib/model/utils/config.py.

• 📋 Train on source domain:

    cd Source
    python trainval_pretrain_adv.py \
       --dataset voc_medical_train \
       --dataset_t voc_medical \
       --net vgg16 \
       --log_ckpt_name "DDSMSource" \
       --save_dir "output"

• 🏷️ Generate pseudo-labels:

    python psudo_label_generation.py \
       --dataset_t voc_medical \
       --net vgg16 \
       --log_ckpt_name "PseudoL_ddsm2rsna" \
       --save_dir "output" \
       --load_name "output/vgg16/DDSMSource/lg_adv_session_1_epoch_6_step_10000.pth"

• 📦 Generate a new RSNA directory containing source labels by executing the scripts/GenerateSF.ipynb notebook.

  cd ../scripts
  python generateSF.py
  

▶️ Step 3: Generate Expert Labels

🔄 Make sure to switch your environment from source_train to other

• Generate expert labels:

   cd ../Expert
   python prediction.py --root "<DATASET_PATH>"

  This will create the file rsna_results.txt.

▶️ Step 4: Run the Grounded Teacher

• 📝 Update configuration files:

  • Set TRAIN_LABEL to RSNA_sf with Source pseudo-labels
  • Set TRAIN_UNLABEL to RSNA
  • Set TEST to RSNA with ground truth
  • Set EXPERT_PATH to RSNA Expert pseudo-Labels

• 🏃 Run training:

  python train_net.py \
    --num-gpus 1 \
    --config configs/faster_rcnn_VGG_cross_city.yaml \
    OUTPUT_DIR output/ddsm2rsna

• 📈 Calculate Froc:

  python eval.py --setting ddsm2rsna --root output/ddsm2rsna

---

📊 Results and Model Parameters

We conduct all experiments with batch size 4, on 4 NVIDIA A100 GPUs.

🔄 rsna2inbreast: RSNA-BSD1K → INBreast

backbone	training stage	R@0.3	logs & weights
vgg16	source_only	0.31	logs & weights
vgg16	cross_domain_mae	0.28	logs & weights

---

🔄 ddsm2rsna: DDSM → RSNA-BSD1K

backbone	training stage	R@0.3	logs & weights
vgg16	source_only	0.30	logs & weights
vgg16	cross_domain_mae	0.43	logs & weights

---

🔄 ddsm2inbreast: DDSM → INBreast

backbone	training stage	R@0.3	logs & weights
vgg16	source_only	0.24	logs & weights
vgg16	cross_domain_mae	0.43	logs & weights

Acknowledgments and 🔧 Built Upon

Our implementation builds upon the following excellent repositories and research contributions:

• CAT, AASFOD, and BiomedParse:

We thank the authors for making their work publicly available.

📚 Citation

If you find this work useful, please cite our paper

@misc{ashraf2025contextawaregroundedteacher,
      title={Context Aware Grounded Teacher for Source Free Object Detection}, 
      author={Tajamul Ashraf and Rajes Manna and Partha Sarathi Purkayastha and Tavaheed Tariq and Janibul Bashir},
      year={2025},
      eprint={2504.15404},
      archivePrefix={arXiv},
      primaryClass={cs.CV},
      url={https://arxiv.org/abs/2504.15404}, 
}