CCFAM: Contrastive Constraint-Based Feature Alignment Module

Official PyTorch implementation of the IJCNN 2026 paper:
"Illumination-Invariant Real-Time Semantic Segmentation via Contrastive Learning for Nighttime Autonomous Driving"

Core Advantages: Zero Inference Overhead · Minimal Dependencies · One-Click Reproduction · Code as Documentation

---

✨ Highlights

• 🧹 Extremely Clean Code: Only requires six libraries – torch, torchvision, numpy, opencv, Pillow, easydict. No heavy frameworks (mmseg, detectron2, etc.).
• ⚡ Zero Inference Overhead: CCFAM performs feature alignment only during training; no extra computation or parameters are added at inference.
• 🔁 One-Click Reproduction: Just run python train.py to start training on the ACDC dataset and reproduce the reported metrics.
• 📚 Code as Paper: The directory structure maps directly to paper equations, with exhaustive comments. It can serve as a ready-to-use template for this direction.
• 🤝 Fair Comparisons: Clean baseline implementations (PSPNet-R18, DeepLabV3-R18 + IAPM) are all integrated within the same lightweight framework.

---

📦 Dependencies

torch==2.1.2+cu121
torchvision==0.16.2+cu121
numpy==1.24.1
opencv_python==4.9.0.80
Pillow==12.2.0
easydict==1.13

Install:

pip install -r requirements.txt

Verified environment: Python 3.11.5 + CUDA 12.1 + RTX 3090

---

📂 Project Structure (Minimalist View)

CCFAM/
├── models/                     # Core models (PSPNet+CCFAM)
│   ├── pspnet_r18_ccfam.py     # 🎯 Main method: PSPNet + CCFAM
│   ├── ccfam.py                # CCFAM core module (contrastive loss + Memory Bank)
│   └── memorybank.py           # Per-class dynamic memory bank
├── dataset/                    # ACDC dataset loading and augmentations
│   ├── acdc.py                 # ACDC abnormal/reference set loading
│   ├── transforms.py           # Data augmentations (random scale, crop, flip)
│   └── ...
├── train/                      # Training utilities
│   ├── trainer.py              # Generic trainer (mixed precision, checkpointing)
│   ├── lr_schedulers.py        # Poly learning rate decay
│   └── ...
├── evaluate/                   # Evaluator (mIoU, per-class IoU)
├── baselines/                  # Cleanly reproduced baseline models
│   ├── pspnet_r18.py
│   ├── deeplabv3_r18.py
│   ├── pspnet_r18_iapm.py      # PSPNet + IAPM enhancement
│   └── ...
├── utils.py                    # Image normalization constants, etc.
├── start.py                    # 🚀 One-click training launch
└── README.md

No need to jump across folders hunting for dependencies – all module paths use relative imports, and the repo works out of the box after cloning.

---

🚀 Quick Start

1. Clone and Install Dependencies

git clone https://github.com/zsjntm/CCFAM.git
cd CCFAM
pip install -r requirements.txt

2. Prepare Data

• Download the ACDC dataset. Ensure rgb_anon and gt are inside the same parent folder (e.g., ACDC/), then set the ACDC_DIR path in env.py to point to that folder.

3. Train

python train.py

The training script automatically carries out two-stage training (50 epochs + 10 epochs). Evaluation intervals and hyperparameters are pre-configured – no extra tuning needed.
Loss and mIoU are printed during training, and checkpoints are saved under CCFAM_results/.

4. Evaluate

After training, the best model is saved at CCFAM_results/xxx/best.pth.
Use evaluate to directly evaluate single images or the validation set – see that package for details.

5. Reproduce Paper Results

Due to hardware differences, the reproduced mIoU may fluctuate within ±1%, which is entirely normal.

---

📊 Main Results (ACDC val night)

Method	mIoU(%)	FPS	Inference Overhead
PSPNet-R18 (baseline)	38.97	28.7	-
+ DisM	38.91	16.9	Additional enhancement module
+ IAPM	40.88	26.2	Additional enhancement module
+ CCFAM (Ours)	41.53	28.7	None (training‑time alignment)

Speed measured on an RTX 3090 at 1920×1080 resolution. CCFAM preserves the original backbone, so inference speed is identical to the vanilla model.

---

🤔 Why Is This Repository “Minimalist”?

Most paper codebases come with redundant configuration systems, multiple layers of inheritance, and heavy dependencies (like mmcv). Reproducers often have to learn a framework before they can even run the code.
We deliberately avoided all of that:

• Models are built with native torch.nn, clean and readable.
• Augmentations are hand‑written in transforms.py, without pulling in extra libraries.
• The training loop is only a few hundred lines, supports mixed precision and checkpoint resumption, yet remains straightforward.
• Comments are entirely in English, follow international open‑source conventions, and directly reference paper equations.

This is not “laziness” – it’s the deepest respect for those who come after us.
We believe good open‑source code should let readers spend their time on innovation, not fighting the environment.

---

📝 Citation

If you use this project or our method, please cite:

@inproceedings{he2026ccfam,
  title     = {Contrastive Constraint-Based Feature Alignment Module for Nighttime Semantic Segmentation},
  author    = {Cong He and Renping Xie},
  booktitle = {Proceedings of the International Joint Conference on Neural Networks (IJCNN)},
  year      = {2026},
  note      = {Accepted},
  organization = {IEEE}
}

---

Dedicated to every researcher who has struggled to reproduce a paper late at night – this repository was written for you.