Teacher-Free Feedback-Guided Self-Distillation for Camera-Only 3D Detection (BEV)

Official implementation accompanying the paper:

Teacher-Free Feedback-Guided Self-Distillation for Camera-Only 3D Detection

[Paper PDF] ]

Overview

This repository provides a modular implementation of the proposed teacher-free self-distillation framework for BEV-based (Bird's Eye View) 3D object detection.

The framework augments a BEV detector during training with:

• Exponential Moving Average (EMA) self-teaching: Leveraging a stable temporal mean of the model.
• Same-frame spatial consistency: Ensuring robust feature representation across spatial augmentations.
• Temporally aligned consistency: via ego-motion warping to align features across frames.
• Entropy-based uncertainty weighting: Automatically weighing the reliability of pseudo-labels.
• Motion-aware gating: Filtering noise in dynamic scenes.
• Progressive loss scheduling: Gradually introducing distillation objectives.

Note: The inference architecture of the underlying detector remains unchanged, ensuring no additional computational overhead during deployment.

Training Objective

The overall training objective combines the supervised detection loss with additional consistency terms:

$$L = L_{sup} + \lambda_{sf} L_{sf} + \lambda_{temp} L_{temp}$$

Repository Structure

teacher_free/  # EMA, consistency losses, warping, weighting, wrapper
datasets/      # Ego-motion utilities and temporal helpers
configs/       # Configuration templates
tools/         # Training entry points
tests/         # Unit tests
docs/          # Integration and reproducibility notes

Installation

# Create environment
conda env create -f environment.yml
conda activate teacherfree

# Install dependencies
pip install -r requirements.txt

Integration with a BEV Detector

The framework is designed to integrate with an existing BEV detector without modifying its internal architecture. The detector's forward pass must expose specific outputs:

outputs = detector(x_t)

outputs["loss"]      # Supervised detection loss (scalar)
outputs["bev_feat"]  # (B, C, H, W) BEV feature tensor
outputs["logits"]    # (B, K, H, W) semantic logits

Wrapping the Detector

from teacher_free import TeacherFreeWrapper
from teacher_free.pose_warp import BEVGridSpec

# Define the BEV grid boundaries
bev_grid = BEVGridSpec(
    x_bound=(-51.2, 51.2, 0.4),
    y_bound=(-51.2, 51.2, 0.4),
)

# Wrap the existing detector
model = TeacherFreeWrapper(detector, bev_grid=bev_grid)

For temporal consistency, the wrapper expects one of the following:

• T_prev_to_cur: Shape representing the relative pose from to .
• warp_grid: Shape for use with torch.nn.functional.grid_sample.

Reproducibility

See docs/reproducibility.md for detailed instructions on:

• Dataset preparation
• Integration notes for BEVDet-style pipelines.
• Training schedule configuration.
• Recommended hyperparameters for optimal convergence.

Unit Tests

To verify core components (warping, EMA updates, and loss functions), run:

pytest -q