Skip to content

README.md

Latest commit

 

History

History
189 lines (134 loc) · 5.2 KB

README.md

File metadata and controls

189 lines (134 loc) · 5.2 KB

Offroad Segmentation V4 Pipeline

A high-capacity semantic segmentation system for offroad terrain classification using DINOv2 backbone with UPerNet decoder.

Architecture Overview

  • Backbone: DINOv2 (ViT-B/14) for rich spatial embeddings
  • Decoder: UPerNet with Pyramid Pooling Module (PPM) for multi-scale context
  • Loss Functions:
    • Online Hard Example Mining (OHEM)
    • Class-Weighted Lovász Loss
    • Boundary Loss
  • Inference: Hardware-aware Test-Time Augmentation (TTA)
    • 8 geometric D4 rotations
    • 3x multi-scale predictions

Setup Instructions

1. Clone Repository

git clone https://github.com/VectorFlow-vvce/Track2_code_Geass.git
cd Track2_code_Geass/vibaethon3/vibaethon3

2. Download Large Files from Google Drive

Download model and dataset files from: 📁 Google Drive Link

Extract downloaded files to repository root:

  • segmentation_head.pth → repo root
  • Dataset folders (if needed) → repo root

3. Create Virtual Environment

python -m venv env
source env/bin/activate  # On Windows: env\Scripts\activate

4. Install Dependencies

pip install -r requirements.txt

5. Configure Environment Variables

Copy the example environment file and update with your paths:

cp .env.example .env

Edit .env and set:

  • TRAIN_IMAGE_DIR: Path to training images
  • TRAIN_MASK_DIR: Path to training masks
  • TEST_IMAGE_DIR: Path to test images
  • TEST_OUTPUT_DIR: Where to save predictions (default: ./test_predictions/)

Usage

Training

python train_segmentaion.py

Training statistics will be saved to logs directory.

Testing/Inference

python test_local.py

Predictions will be saved to the test_predictions/ directory.

Project Structure

Track2_code_Geass/vibaethon3/vibaethon3/
├── .env.example            # Example environment file
├── .gitignore              # Git ignore rules
├── requirements.txt        # Python dependencies
├── train_segmentaion.py    # Training script
├── test_local.py           # Testing/inference script
├── test_segmentation.py    # Additional test script
├── README.md               # This file
├── Offroad_Segmentation_testImages/  # Sample test images
│   ├── Color_Images/       # Input images
│   └── Segmentation/       # Ground truth masks
└── .venv/                  # Virtual environment (ignored by git)

Important Notes

Files NOT Pushed to GitHub (in .gitignore)

The following large files are excluded from the GitHub repository and available in Google Drive:

  • segmentation_head.pth - Trained segmentation model (model weights)
  • best_model_v4.pth - Full trained model (too large)
  • swa_model_v4.pth - Stochastic Weight Averaging checkpoint
  • Offroad_Segmentation_Training_Dataset/ - Full training dataset
  • .venv/ - Virtual environment folder
  • *.log - Log files (torch_install.log, test_output.log, etc.)
  • test_predictions/ - Generated predictions from inference
  • rare_class_weights.json - Auto-generated class weights file

Download Large Files from Google Drive

All model files and datasets are available here:

📁 Google Drive Link

Download and extract the following files to your repository root:

your_repo/
├── segmentation_head.pth          # ← Download from Drive
├── Offroad_Segmentation_Training_Dataset/   # ← Download from Drive (if needed)
└── [other files in this repo]

Files Safe to Push to GitHub

  • train_segmentaion.py - Training script
  • test_local.py - Testing script
  • test_segmentation.py - Inference script
  • requirements.txt - Dependencies list
  • .env.example - Configuration template
  • .gitignore - Git ignore rules
  • README.md - Documentation
  • Offroad_Segmentation_testImages/ - Sample test images

Classes

The model segments 10 offroad terrain classes: 0. Landscape/Background

  1. Trees
  2. Lush Bushes
  3. Dry Grass
  4. Dry Bushes
  5. Ground Clutter
  6. Logs
  7. Rocks
  8. Unknown
  9. Sky

Hardware Requirements

  • GPU with CUDA support recommended (tested on NVIDIA GPUs)
  • Minimum 8GB VRAM for training
  • 4GB VRAM for inference with TTA

Training Configuration

Default hyperparameters (editable in train_segmentaion.py):

  • Batch Size: 4
  • Epochs: 25
  • Learning Rate: 5e-6 (backbone), 1e-4 (decoder)
  • Optimizer: AdamW with Lookahead
  • Scheduler: Cosine Annealing + OneCycleLR
  • Progressive Resizing: 252x448 → 504x896 at epoch 12

Performance

  • Model trained on offroad terrain segmentation dataset
  • Achieves state-of-the-art mIoU on test set
  • Uses DINOv2 backbone for superior feature extraction

References

License

This project is part of Track 2 - Code Geass collaboration.

Support

For issues or questions, please refer to the project repository or contact the development team.