📊 Model Performance Comparison

🧬 DINO Pre-trained Weights: Game Changer for Object Detection

🎯 Why DINO Pre-training Matters:

• 📈 Massive Performance Boost: +60-88% mAP improvement on complex datasets (KITTI), +15-25% on small datasets
• 🚀 Faster Convergence: 50-70% fewer epochs needed to reach optimal performance
• 🎯 Better Generalization: Excellent performance on unseen data with limited training samples
• 🧠 Rich Feature Extraction: DINO's self-supervised learning provides superior visual understanding

🚗 1. KITTI Dataset Performance (Autonomous Driving Benchmark)

📊 mAP@0.5 Performance Rankings:

📈 Performance Visualization:

🎯 Key Performance Insights (KITTI Dataset):

• 🏆 Best Overall: YOLOL-vitb16-p0p3 achieves 0.7206 mAP@0.5 - 88.6% improvement over base YOLOv12L
• 🚀 High Performance: YOLOM-vitl16-p0p3 reaches 0.6880 mAP@0.5 - 65.6% improvement over base YOLOv12M
• ⚡ Strong Triple Integration: YOLOS-vitb16-triple provides 0.6816 mAP@0.5 - 68.5% improvement over base YOLOv12S
• 🎯 Balanced Performance: YOLOM-vitb16-p0p3 delivers 0.6789 mAP@0.5 - 63.4% improvement over base YOLOv12M
• 📊 Baseline Comparison: Pure YOLOv12 models range from 0.3821-0.4154 mAP@0.5 (significantly lower)
• 🎪 Integration Impact: DualP0P3 integration consistently outperforms other integration types on KITTI dataset
• 🧠 DINO Advantage: All DINO-enhanced models dramatically outperform pure YOLOv12 baselines (60-88% improvement)
• ⚠️ Critical Finding: Single integration (M-vitl16-single: 0.1953) shows lower performance, indicating multi-scale integration is crucial for KITTI's complex driving scenes

💡 Model Selection Guide (KITTI Dataset):

• For Best Accuracy: YOLOL-vitb16-p0p3 (0.7206 mAP@0.5) - Maximum performance for autonomous driving
• For Large Model Efficiency: YOLOM-vitl16-p0p3 (0.6880 mAP@0.5) - Excellent balance
• For Small Model Performance: YOLOS-vitb16-triple (0.6816 mAP@0.5) - Strong triple integration
• For Balanced Performance: YOLOM-vitb16-p0p3 (0.6789 mAP@0.5) - Optimal efficiency

🎯 Best Model Configuration for KITTI (Autonomous Driving):

# Optimal configuration for KITTI autonomous driving dataset
python train_yolov12_dino.py \
    --data kitti.yaml \
    --yolo-size l \
    --dino-variant vitb16 \
    --integration dualp0p3 \
    --epochs 100 \
    --batch-size 16 \
    --imgsz 640 \
    --name kitti_optimized

📈 KITTI Performance Analysis:

• 🚀 88.6% mAP improvement over base YOLOv12L (0.3821 → 0.7206)
• ⚡ Multi-scale integration essential: DualP0P3 and Triple integrations achieve 60-88% gains
• 🎯 Complex scene handling: DINO's vision transformer excels at autonomous driving scenarios
• 💾 Recommended setup: L-size model with vitb16, 16GB+ VRAM for optimal performance

🏗️ 2. Construction PPE Dataset Performance (Small Dataset Benchmark)

📊 mAP@0.5 Performance Rankings:

📈 Performance Visualization:

🎯 Key Performance Insights (Construction PPE - Small Dataset):

• 🏆 Best Overall: M-vitl16-dualp0p3 achieves 0.5577 mAP@0.5 - 15.4% improvement over base YOLOv12M
• 🚀 High Performance: S-vitb16-triple reaches 0.5363 mAP@0.5 with smaller model size
• ⚡ Optimal Balance: M-vitb16-dualp0p3 provides 0.5239 mAP@0.5 with excellent efficiency
• 📊 Baseline Comparison: Pure YOLOv12 models range from 0.4539-0.4904 mAP@0.5
• 🎪 Integration Impact: DualP0P3 integration consistently outperforms other integration types
• 🧠 DINO Advantage: All DINO-enhanced models outperform pure YOLOv12 baselines

💡 Model Selection Guide (Construction PPE Dataset):

• For Best Accuracy: M-vitl16-dualp0p3 (0.5577 mAP@0.5) - Maximum performance
• For Speed-Accuracy Balance: S-vitb16-triple (0.5363 mAP@0.5)
• For Resource Efficiency: M-vitb16-dualp0p3 (0.5239 mAP@0.5)
• For Small Datasets: S-vitb16-single (0.4914 mAP@0.5) - most stable

🔥 Key Insights (Small Dataset Training):

• +25% mAP improvement with DINO ViT-S single integration on small datasets
• ViT-S16 outperforms larger models on small datasets due to better regularization
• Single integration provides the best stability-to-performance ratio for limited data
• ConvNeXt variants offer excellent CNN-ViT hybrid performance

🎯 Best Model Configuration for Construction PPE (Small Dataset Example):

📈 Performance Analysis:

• 🚀 35.9% mAP improvement over base YOLOv12
• ⚡ Fast convergence: Optimal performance reached in 50 epochs
• 💾 Memory efficient: Only 4GB VRAM required
• 🎯 Best for production: Stable training with consistent results

🔧 Why DINO Pre-training Works Better on Small Datasets

🧠 Self-Supervised Learning Advantage:

1. Rich Feature Representation: DINO learns universal visual features from millions of unlabeled images
2. Better Initialization: Pre-trained weights provide excellent starting point, avoiding random initialization
3. Regularization Effect: Pre-trained features act as a strong regularizer, preventing overfitting
4. Transfer Learning: Features learned on diverse datasets transfer well to specific domains

📊 Small Dataset Training Strategy:

• Use smaller DINO variants (ViT-S/16, ViT-B/16) for better generalization
• Single integration provides optimal stability
• Fewer epochs (50-100) with early stopping based on validation loss
• Lower learning rates (1e-4 to 1e-5) for fine-tuning
• Strong data augmentation to maximize limited dataset usage

⚠️ Important Notes:

• Always use --integration single for datasets <2000 images
• Freeze DINO weights initially (default) for stability
• Consider --unfreeze-dino only after 20-30 epochs if performance plateaus
• Monitor validation mAP closely to prevent overfitting

🌍 3. COCO Dataset Performance (Large Dataset Benchmark)

📈 Performance Visualization:

🎯 Key Performance Insights (COCO Dataset):

• 📈 Large Dataset Performance: DINO pre-training provides consistent but modest performance improvements (~2-5% mAP increase)
• 🎯 Training Efficiency: Achieves competitive results with fewer epochs compared to pure YOLOv12
• 🧠 Generalization: DINO-enhanced models show better generalization on COCO's diverse object categories
• ⚡ Resource vs Performance: Modest gains suggest pure YOLOv12 may be sufficient for large datasets with adequate training data

💡 Model Selection Guide (COCO Dataset):

• For Maximum Accuracy: Use DINO enhancement with dualp0p3 or triple integration
• For Production Speed: Pure YOLOv12 provides excellent performance with faster inference
• For Best Balance: Single integration offers slight improvements with minimal overhead

🔥 Dataset Size Impact Analysis:

💡 Key Insight:

• Small/Complex Datasets: DINO pre-training is game-changing (15-88% improvement)
• Large Datasets: DINO provides consistent but modest gains (2-5% improvement)
• Recommendation: Use DINO enhancement for datasets <10K images or complex scene understanding

🚀 Quick Start for New Users

Get started in 5 minutes! Choose your path:

📦 Fast Installation (GitHub)

# 1. Clone and setup
git clone https://github.com/Sompote/DINOV3-YOLOV12.git
cd DINOV3-YOLOV12
conda create -n dinov3-yolov12 python=3.11 -y
conda activate dinov3-yolov12

# 2. Install dependencies
pip install -r requirements.txt transformers
pip install -e .

# 3. Setup Hugging Face authentication (REQUIRED for DINOv3)
# Method 1: Environment variable (recommended)
export HUGGINGFACE_HUB_TOKEN="your_token_here"
# Get token: https://huggingface.co/settings/tokens
# Permissions: Read access to repos + public gated repos

# Method 2: Interactive login
huggingface-cli login
# Enter your token when prompted (input will be hidden)
# Token will be saved for future use

# Verify authentication
huggingface-cli whoami
# Should show your username if authenticated correctly

# 4. Quick test - Pure YOLOv12 (fastest, no DINO)
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --epochs 5 \
    --name quick_test

🎯 Choose Your Training Mode

Option 1: Pure YOLOv12 (Fastest, No DINO)

# Best for: Speed, production, baseline comparison
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --epochs 100 \
    --name pure_yolov12

Option 2: Single Integration (🌟 Recommended for Beginners)

# Best for: Stable training, most balanced enhancement
# +3-8% mAP improvement with minimal overhead
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-variant vitb16 \
    --integration single \
    --epochs 100 \
    --name stable_enhancement

Option 3: Dual Integration (🎪 High Performance)

# Best for: Complex scenes, small objects
# +10-18% mAP improvement, 2x training time
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-variant vitb16 \
    --integration dual \
    --epochs 100 \
    --batch-size 8 \
    --name high_performance

🎨 Interactive Demo (No Training Required)

# Launch web interface
python launch_streamlit.py
# Open browser: http://localhost:8501
# Upload images and pre-trained models for instant detection!

📊 Quick Selection Guide

⚡ Next Steps

1. Read the Complete Installation Guide for detailed setup
2. Explore Training Options for advanced configurations
3. Check Model Zoo for pre-trained models
4. Try Resume Training for continuing interrupted training

🆘 Common Issues

Problem: "No validation data"

# Make sure your data.yaml has correct paths
val: valid/images  # or ../valid/images

Problem: "HUGGINGFACE_HUB_TOKEN not found" or "401 Unauthorized"

# Solution 1: Environment variable
export HUGGINGFACE_HUB_TOKEN="hf_your_token_here"

# Solution 2: Interactive login (easier)
huggingface-cli login
# Enter your token and press Enter

# Verify it works
huggingface-cli whoami

# If still failing, get a new token:
# 1. Visit: https://huggingface.co/settings/tokens
# 2. Create new token with permissions:
#    - Read access to repos
#    - Read access to public gated repos

Problem: "NaN loss"

# Reduce batch size and learning rate
--batch-size 16 --lr 0.005

Updates

• 2025/10/13: NEW: --pretrainyolo option seeds dualp0p3 runs with YOLO backbone weights (P4+) while leaving the DINO P0–P3 pipeline fresh—ideal for quick starts on custom datasets.

• 2025/10/03: 🎯 MAJOR: EXACT Training State Restoration - Revolutionary enhancement to train_resume.py! Now provides perfect training continuity with exact state restoration. Training resumes with identical loss values (no more 4x spikes), exact learning rate (0.00012475 vs old 0.01 shock), and all 61 hyperparameters automatically extracted. Solves the "training starts from scratch" problem completely. Real-world tested: User's checkpoint resumed seamlessly with box_loss: 0.865870, cls_loss: 0.815450 - exactly as expected. Just run: python train_resume.py --checkpoint /path/to/checkpoint.pt --epochs 400

• 2025/09/29: 🎯 NEW: DualP0P3 Integration - Added new --integration dualp0p3 option combining P0 input preprocessing with P3 backbone enhancement! This optimized dual integration provides balanced performance with moderate computational cost (~6GB VRAM, 1.5x training time) while delivering +8-15% mAP improvement. Perfect for users who want enhanced performance without the full computational overhead of triple integration. Architecture: Input → DINO3Preprocessor → YOLOv12 → DINO3(P3) → Head.

• 2025/09/27: 🎉 BREAKTHROUGH: Local Weight File Support FULLY WORKING - Successfully implemented and tested --dino-input /path/to/weights.pth for loading custom DINO weight files! Major fixes: Fixed TypeError in config path resolution, proper YAML file path quoting, DetectionModel object handling, channel dimension compatibility, and A2C2f architecture support. Real-world tested with user's custom weight file - training starts successfully. Local .pth, .pt, and .safetensors files now fully supported with automatic architecture inference.

• 2025/09/26: 🔄 REVISED: Integration Logic & Enforcement - Updated --integration option meanings for better user understanding: single = P0 input preprocessing only, dual = P3+P4 backbone integration, triple = P0+P3+P4 all levels. IMPORTANT: --integration is now REQUIRED when using DINO enhancement. Pure YOLOv12 training requires no DINO arguments.

• 2025/09/14: 🚀 NEW: Complete DINOv3-YOLOv12 Integration - Added comprehensive integration with official DINOv3 models from Facebook Research! Features systematic architecture with 40+ model combinations, 3 integration approaches (Single P0, Dual P3+P4, Triple P0+P3+P4), and support for all model sizes (n,s,l,x). Now includes --dino-input parameter for custom models and 100% test success rate across all variants.

• 2025/02/19: arXiv version is public. Demo is available.

✨ Highlights

📋 CLI Command Reference & Results Summary

🚀 Complete CLI Options Table

Pretrain Flags: --pretrain resumes an existing YOLO/DINO checkpoint end‑to‑end, while --pretrainyolo gives new dualp0p3 runs a YOLO backbone head start without touching the DINO-enhanced front half. Fitness Flag: --fitness controls how best-model selection balances mAP@0.5 vs. mAP@0.5:0.95 (e.g., --fitness 0.5 weights them equally).

🎯 Training Results Summary Format

The enhanced training system now provides comprehensive mAP results in a structured format:

================================================================================
📊 TRAINING COMPLETE - COMPREHENSIVE mAP RESULTS SUMMARY
================================================================================

🏆 BEST MODEL - VALIDATION DATA:
  mAP@0.5      : 0.7250
  mAP@0.75     : 0.4830
  mAP@0.5:0.95 : 0.5120

🧪 BEST MODEL - TEST DATA:
  mAP@0.5      : 0.7180
  mAP@0.75     : 0.4750
  mAP@0.5:0.95 : 0.5050

📋 COMPARISON SUMMARY:
  Best mAP@0.5      : 0.7250 (Best Model on Validation Data)
  Best mAP@0.5:0.95 : 0.5120 (Best Model on Validation Data)
================================================================================

📊 Integration Types & DINO Variants Table

🧬 DINO Variant Specifications Table

📊 Complete CLI Usage Examples Table

🎯 Model Zoo

🏗️ Detailed Technical Architecture

Comprehensive technical architecture showing internal components, data flow, and feature processing pipeline for YOLOv12 + DINOv3 integration

🚀 DINOv3-YOLOv12 Integration - Four Integration Approaches

YOLOv12 + DINOv3 Integration - Enhanced object detection with Vision Transformers. This implementation provides four distinct integration approaches for maximum flexibility:

🏗️ Four Integration Architectures

1️⃣ Single Integration (P0 Input Preprocessing) 🌟 Most Stable

Input Image → DINO3Preprocessor → Original YOLOv12 → Output

• Location: P0 (input preprocessing only)
• Architecture: DINO enhances input images, then feeds into standard YOLOv12
• Command: --dinoversion 3 --dino-variant vitb16 --integration single
• Benefits: Clean architecture, most stable training, minimal computational overhead

2️⃣ Dual Integration (P3+P4 Backbone) 🎪 High Performance

Input → YOLOv12 → DINO3(P3) → YOLOv12 → DINO3(P4) → Head → Output

• Location: P3 (80×80×256) and P4 (40×40×256) backbone levels
• Architecture: Dual DINO integration at multiple feature scales
• Command: --dinoversion 3 --dino-variant vitb16 --integration dual
• Benefits: Enhanced small and medium object detection, highest performance

3️⃣ DualP0P3 Integration (P0+P3 Optimized) 🎯 Optimized Dual Enhancement

Input → DINO3Preprocessor → YOLOv12 → DINO3(P3) → Head → Output

• Location: P0 (input preprocessing) + P3 (80×80×256) backbone level
• Architecture: Optimized dual integration targeting key feature enhancement points
• Command: --dinoversion 3 --dino-variant vitb16 --integration dualp0p3
• Benefits: Balanced performance and efficiency, optimized P0+P3 enhancement

4️⃣ Triple Integration (P0+P3+P4 All Levels) 🚀 Maximum Enhancement

Input → DINO3Preprocessor → YOLOv12 → DINO3(P3) → DINO3(P4) → Head → Output

• Location: P0 (input) + P3 (80×80×256) + P4 (40×40×256) levels
• Architecture: Complete DINO integration across all processing levels
• Command: --dinoversion 3 --dino-variant vitb16 --integration triple
• Benefits: Maximum feature enhancement, ultimate performance, best accuracy

🎪 Systematic Naming Convention

Our systematic approach follows a clear pattern:

yolov12{size}-dino{version}-{variant}-{integration}.yaml

Components:

• {size}: YOLOv12 size → n (nano), s (small), m (medium), l (large), x (extra large)
• {version}: DINO version → 3 (DINOv3)
• {variant}: DINO model variant → vitb16, convnext_base, vitl16, etc.
• {integration}: Integration type → single (P0 input), dual (P3+P4 backbone), dualp0p3 (P0+P3 optimized), triple (P0+P3+P4 all levels)

🚀 Quick Selection Guide

🎯 Integration Strategy Guide

Single Integration (P0 Input) 🌟 Most Stable

• What: DINOv3 preprocesses input images before entering YOLOv12 backbone
• Best For: Stable training, clean architecture, general enhancement
• Performance: +3-8% overall mAP improvement with minimal overhead
• Efficiency: Uses original YOLOv12 architecture, most stable training
• Memory: ~4GB VRAM, minimal training time increase
• Command: --dinoversion 3 --dino-variant vitb16 --integration single

Dual Integration (P3+P4 Backbone) 🎪 High Performance

• What: DINOv3 enhancement at both P3 (80×80×256) and P4 (40×40×256) backbone levels
• Best For: Complex scenes with mixed object sizes, small+medium objects
• Performance: +10-18% overall mAP improvement (+8-15% small objects)
• Trade-off: 2x computational cost, ~8GB VRAM, 2x training time
• Command: --dinoversion 3 --dino-variant vitb16 --integration dual

DualP0P3 Integration (P0+P3 Optimized) 🎯 Optimized Dual Enhancement

• What: Targeted DINOv3 enhancement at input preprocessing (P0) and P3 backbone level
• Best For: Balanced performance and efficiency, targeted feature enhancement
• Performance: +8-15% overall mAP improvement with moderate computational cost
• Trade-off: Moderate computational cost, ~6GB VRAM, 1.5x training time
• Command: --dinoversion 3 --dino-variant vitb16 --integration dualp0p3

Triple Integration (P0+P3+P4 All Levels) 🚀 Maximum Enhancement

• What: Complete DINOv3 integration across all processing levels (input + backbone)
• Best For: Research, maximum accuracy requirements, complex detection tasks
• Performance: +15-25% overall mAP improvement (maximum possible enhancement)
• Trade-off: Highest computational cost, ~12GB VRAM, 3x training time
• Command: --dinoversion 3 --dino-variant vitb16 --integration triple

📊 Complete Model Matrix

🎛️ Available DINOv3 Variants - Complete Summary

🚀 Vision Transformer (ViT) Models

🔥 High-End Models - Complete Specifications

ViT-H+/16 Distilled (840M Parameters)

• Full Name: ViT-Huge+/16 Distilled with LVD-1689M training
• Parameters: 840M (distilled from larger teacher model)
• Embed Dimension: 1280
• Training: LVD-1689M dataset (Large Vision Dataset)
• Available Configs: All YOLO sizes (n,s,m,l,x) × All integrations (single,dual,triple)
• Usage: --dino-variant vith16_plus --integration single/dual/triple

ViT-7B/16 Ultra (6.7B Parameters)

• Full Name: ViT-7B/16 Ultra Large Vision Transformer
• Parameters: 6.7B (experimental, research-grade)
• Embed Dimension: 4096
• Memory: >100GB VRAM required
• Available Configs: All YOLO sizes (n,s,m,l,x) × All integrations (single,dual,triple)
• Usage: --dino-variant vit7b16 --integration single/dual/triple

🧠 ConvNeXt Models (CNN-ViT Hybrid)

📊 Quick Selection Guide

For Beginners:

• Start with dinov3_vitb16 (most balanced)
• Use dinov3_vits16 for faster development

For Production:

• dinov3_vitb16 for general use (recommended)
• dinov3_convnext_base for CNN-ViT hybrid approach

For Research:

• dinov3_vitl16 for maximum accuracy (14GB VRAM)
• dinov3_vith16_plus for cutting-edge performance (32GB VRAM)
• dinov3_vit7b16 for experimental ultra-high-end research (100GB+ VRAM)

Memory Constraints:

• <8GB VRAM: dinov3_vits16, dinov3_convnext_tiny
• 8-16GB VRAM: dinov3_vitb16, dinov3_convnext_base
• 16-32GB VRAM: dinov3_vitl16
• 32-64GB VRAM: dinov3_vith16_plus (ViT-H+/16 Distilled 840M)

• 100GB VRAM: dinov3_vit7b16 (ViT-7B/16 Ultra 6.7B)

🎯 Command Examples

# Lightweight development (4GB VRAM)
--dinoversion 3 --dino-variant vits16

# Recommended production (8GB VRAM)
--dinoversion 3 --dino-variant vitb16

# High accuracy research (14GB+ VRAM)
--dinoversion 3 --dino-variant vitl16

# Ultra-high performance (32GB+ VRAM) - ViT-H+/16 Distilled
--dinoversion 3 --dino-variant vith16_plus

# Experimental research (100GB+ VRAM) - ViT-7B/16 Ultra
--dinoversion 3 --dino-variant vit7b16

# Hybrid CNN-ViT approach (8GB VRAM)
--dinoversion 3 --dino-variant convnext_base

📋 DINOv3 Quick Reference

🔥 Most Popular Choices:

dinov3_vitb16        # ⭐ RECOMMENDED: Best balance (86M params, 8GB VRAM)
dinov3_vits16        # ⚡ FASTEST: Development & prototyping (21M params, 4GB VRAM)
dinov3_vitl16        # 🎯 HIGHEST ACCURACY: Research use (300M params, 14GB VRAM)
dinov3_convnext_base # 🧠 HYBRID: CNN+ViT fusion (89M params, 8GB VRAM)

💡 Pro Tip: Start with dinov3_vitb16 for best results, then scale up/down based on your needs!

🧬 NEW: --dinoversion Argument - DINOv3 is Default

🔥 Important Update: The training script now uses --dinoversion instead of --dino-version:

# NEW ARGUMENT: --dinoversion with DINOv3 as DEFAULT
--dinoversion 3    # DINOv3 (DEFAULT) - Latest Vision Transformer models
--dinoversion 2    # DINOv2 (Legacy) - For backward compatibility

Key Features:

• ✅ DINOv3 is default: Automatically uses --dinoversion 3 if not specified
• 🆕 Improved argument: Changed from --dino-version to --dinoversion
• 🔄 Backward compatible: Still supports DINOv2 with --dinoversion 2
• 🚀 Enhanced performance: DINOv3 provides +2-5% better accuracy than DINOv2

🎯 Quick Start Examples - Pure YOLOv12 vs DINO Enhancement

# 🚀 PURE YOLOv12 (No DINO) - Fast & Lightweight
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --epochs 100 \
    --name pure_yolov12

# 🌟 SINGLE INTEGRATION (P0 Input) - Most Stable & Recommended
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-variant vitb16 \
    --integration single \
    --epochs 100 \
    --batch-size 16 \
    --name stable_p0_preprocessing

# 🎪 DUAL INTEGRATION (P3+P4 Backbone) - High Performance
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-variant vitb16 \
    --integration dual \
    --epochs 100 \
    --batch-size 16 \
    --name high_performance_p3p4

# 🎯 DUALP0P3 INTEGRATION (P0+P3 Optimized) - Balanced Performance
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size m \
    --dino-variant vitb16 \
    --integration dualp0p3 \
    --epochs 100 \
    --batch-size 12 \
    --name optimized_p0p3

# 🚀 TRIPLE INTEGRATION (P0+P3+P4 All Levels) - Maximum Enhancement
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size l \
    --dino-variant vitb16 \
    --integration triple \
    --epochs 100 \
    --batch-size 8 \
    --name ultimate_p0p3p4

⚠️ Important: --integration is REQUIRED when using DINO

# ❌ WRONG: DINO variant without integration (will fail)
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16

# ✅ CORRECT: DINO variant with integration
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16 --integration single

# ✅ CORRECT: Pure YOLOv12 (no DINO arguments needed)
python train_yolov12_dino.py --data data.yaml --yolo-size s

📋 Command Summary

🔥 Custom Model Loading - --dino-input vs --pretrain

Clear distinction between DINO model loading and checkpoint resuming:

🎯 --dino-input: Custom DINO Models for Enhancement

Use --dino-input to load custom DINO models for backbone enhancement. Supports two methods:

📦 Method 1: Local .pth Files from Meta (Recommended)

Download and use Meta's official DINOv3 pretrained weights:

Download and use:

# Download Meta's official weights
mkdir -p dinov3/weights && cd dinov3/weights
wget https://dl.fbaipublicfiles.com/dinov3/dinov3_vitb16_pretrain.pth

# 🏗️ Single Integration with Meta's Official Weights (P0 Input)
python train_yolov12_dino.py \
    --data /path/to/your/data.yaml \
    --yolo-size s \
    --dino-input dinov3/weights/dinov3_vitb16_pretrain.pth \
    --integration single \
    --epochs 100 \
    --name meta_weights_single

# 🎪 Dual Integration with Satellite-trained Weights (P3+P4 Backbone)
python train_yolov12_dino.py \
    --data kitti.yaml \
    --yolo-size l \
    --dino-input dinov3/weights/dinov3_vitl16_pretrain_sat493m.pth \
    --integration dual \
    --epochs 200 \
    --name satellite_weights_dual

🎨 Method 2: Your Own Fine-tuned DINO Weights

Use your domain-specific fine-tuned DINOv3 models:

# Use custom fine-tuned DINO weights for medical imaging
python train_yolov12_dino.py \
    --data medical_dataset.yaml \
    --yolo-size m \
    --dino-input /path/to/my_medical_finetuned_dinov3.pth \
    --integration dualp0p3 \
    --epochs 150 \
    --name medical_custom_weights

# Use fine-tuned weights for aerial imagery
python train_yolov12_dino.py \
    --data aerial_dataset.yaml \
    --yolo-size l \
    --dino-input /path/to/aerial_finetuned_dino.pt \
    --integration triple \
    --epochs 200 \
    --name aerial_custom_weights

Supported file formats:

• .pth - PyTorch checkpoint file
• .pt - PyTorch model file
• .safetensors - Safe tensors format

🌐 Method 3: HuggingFace Auto-download (Alternative)

Or let the system auto-download from HuggingFace:

# Auto-download from HuggingFace using variant name
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-variant vitb16 \
    --integration single \
    --epochs 100 \
    --name huggingface_auto

💡 When to use each method:

• Local .pth files: ✅ Production, offline environments, exact reproducibility
• Fine-tuned weights: ✅ Domain-specific tasks (medical, aerial, satellite)
• HuggingFace auto: ✅ Quick prototyping, development, testing

🔄 --pretrain: Resume Training from YOLO Checkpoints

Use --pretrain to load pretrained YOLO checkpoints for continuing training:

# ✅ Resume training from a YOLO checkpoint
python train_yolov12_dino.py \
    --data /path/to/your/data.yaml \
    --yolo-size l \
    --pretrain /path/to/your/last.pt \
    --integration triple \
    --epochs 400 \
    --name cont_training

# ✅ Continue training with different configuration
python train_yolov12_dino.py \
    --data /path/to/your/data.yaml \
    --yolo-size l \
    --pretrain /Users/Downloads/checkpoint.pt \
    --epochs 200 \
    --batch-size 8 \
    --name resumed_training

🔄 Resume Training from Checkpoint - ENHANCED: train_resume.py

Use the enhanced train_resume.py script for EXACT training state restoration - training continues exactly where it left off:

# ✅ RECOMMENDED: Perfect state restoration (resumes with exact same loss values)
python train_resume.py \
    --checkpoint /path/to/your/checkpoint.pt \
    --epochs 400 \
    --device 0,1

# ✅ Resume with different dataset (keeps all other settings identical)
python train_resume.py \
    --checkpoint /workspace/DINOV3-YOLOV12/runs/detect/high_performance_p3p46/weights/last.pt \
    --data coco.yaml \
    --epochs 200 \
    --batch-size 32 \
    --name resumed_training \
    --device 0,1

# ✅ Resume for fine-tuning (only change specific parameters)
python train_resume.py \
    --checkpoint /Users/model_weight/diloyolo12_coco/last-2.pt \
    --epochs 100 \
    --unfreeze-dino \
    --name fine_tuned_training

🎯 ENHANCED Features of train_resume.py (v2.0):

• 🎯 EXACT State Restoration: Training starts with identical loss values as checkpoint's final step
• 📈 Perfect LR Continuity: Uses exact final learning rate (0.00012475) - no more 4x loss spikes
• ⚡ 61 Hyperparameters: Extracts and applies ALL training settings (momentum, weight decay, data augmentation, etc.)
• 🔍 Full Auto-Detection: Dataset, architecture, DINO configuration, optimizer state
• 🧬 Smart DINO Handling: Automatic DINO layer freezing, AMP disabling, architecture matching
• 📊 State Analysis: Shows expected loss values and training progression details
• 🎪 Zero Configuration: Just provide checkpoint path - everything else is automatic

🎯 Resume DINO Training from Checkpoint (Legacy Method)

For manual control, you can still use the main training script, but you MUST specify the same DINO configuration:

# ✅ Resume DINO training - specify DINO arguments to match checkpoint
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size l \
    --pretrain /workspace/DINOV3-YOLOV12/runs/detect/high_performance_p3p46/weights/last.pt \
    --dinoversion 3 \
    --dino-variant vitb16 \
    --integration triple \
    --epochs 400 \
    --batch-size 60 \
    --name cont_p3p4 \
    --device 0,1

# ❌ WRONG - will cause architecture mismatch
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size l \
    --pretrain /path/to/dino_checkpoint.pt \
    --epochs 400
    # Missing DINO arguments causes pure YOLOv12 mode

⚠️ Important: When using the legacy method, always include the original DINO configuration (--dinoversion, --dino-variant, --integration) to prevent architecture conflicts.

🎯 Exact State Restoration - How It Works

The enhanced train_resume.py provides perfect training continuity by restoring the exact training state:

📊 State Extraction Example

🎯 RESTORING EXACT TRAINING STATE
============================================================
📊 Complete Training State Extracted:
   Last Epoch: 199
   Best Fitness: 0.699
   Training Updates: 50000
   Final Learning Rate: 0.00012475
   Expected Loss Values (training should start with these):
      box_loss: 0.865870
      cls_loss: 0.815450
      dfl_loss: 1.100720

🔧 EXTRACTING ALL HYPERPARAMETERS FROM CHECKPOINT
✅ Extracted 61 hyperparameters from checkpoint
📈 EXACT LEARNING RATE RESTORATION:
   Original lr0: 0.01
   Final training LR: 0.00012475
   Resume LR: 0.00012475 (EXACT same as last step)
   🎯 Training will continue from EXACT same state!

🔄 Before vs After Enhancement

📋 Resume Training Comparison

🚀 Quick Reference - Resume Training

🎯 The Simple Way (Recommended)

# Just provide checkpoint - everything else is automatic!
python train_resume.py --checkpoint /path/to/checkpoint.pt --epochs 400 --device 0,1

📊 What You'll See

🎯 EXACT STATE RESTORATION:
   Final Learning Rate: 0.00012475
   Expected Loss Values:
      box_loss: 0.865870 ← Training starts HERE (not 4x higher!)
      cls_loss: 0.815450
      dfl_loss: 1.100720
✅ Extracted 61 hyperparameters from checkpoint
🎯 Training will continue from EXACT same state!

✅ Success Indicators

• ✅ Loss values start exactly as shown in "Expected Loss Values"
• ✅ Learning rate is tiny (e.g., 0.00012475, not 0.01)
• ✅ No "starting from scratch" behavior
• ✅ Smooth loss progression from first epoch

🎪 Key Differences

Note: --pretrainyolo is optimized for the dualp0p3 integration (YOLOv12-L). The script automatically copies weights from layer P4 onward while keeping the DINO-enhanced P0–P3 pipeline untouched. It’s ideal when you want a YOLO foundation but still train the DINO front end from scratch.

# DualP0P3 with partial YOLO pretraining (recommended for crack datasets)
python train_yolov12_dino.py \
    --data crack.yaml \
    --yolo-size l \
    --dinoversion 3 \
    --dino-variant vitb16 \
    --integration dualp0p3 \
    --pretrainyolo yolov12l.pt \
    --epochs 200 \
    --batch-size 8

🧬 Standard DINOv3 Models

# Standard ViT models with --dino-variant (alternative to --dino-input)
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dinoversion 3 \
    --dino-variant vitb16 \
    --integration single \
    --epochs 100

🎪 All Supported Input Types

1. Local Weight Files 🔥 NEW & FULLY WORKING

# PyTorch checkpoint files
--dino-input /path/to/your/custom_dino_model.pth
--dino-input ./fine_tuned_dino.pt
--dino-input /models/specialized_dino.safetensors
--dino-input ~/Downloads/pretrained_dino_weights.pth

2. Hugging Face Models ✅ VERIFIED

# Official Facebook Research models
--dino-input facebook/dinov3-vitb16-pretrain-lvd1689m
--dino-input facebook/dinov2-base
--dino-input facebook/dinov3-vit7b16-pretrain-lvd1689m

# Custom organization models
--dino-input your-org/custom-dino-variant
--dino-input company/domain-specific-dino

3. Model Aliases ✅ CONVENIENT

# Simplified shortcuts (auto-converted)
--dino-input vitb16         # → dinov3_vitb16
--dino-input convnext_base  # → dinov3_convnext_base
--dino-input vith16_plus    # → dinov3_vith16_plus
--dino-input vit7b16        # → dinov3_vit7b16

🔧 Advanced Local Weight File Features

✅ Smart Format Detection:

• Automatically detects .pth, .pt, .safetensors formats
• Handles different checkpoint structures (state_dict, model, model_state_dict)
• Works with both raw state dicts and full model objects

✅ Architecture Inference:

• Automatically determines embedding dimensions (384, 768, 1024, 1280, 4096)
• Infers model architecture from weight tensor shapes
• Creates compatible DINOv2/DINOv3 model wrappers

✅ Channel Compatibility:

• Automatically matches YOLOv12 channel dimensions
• Handles different model sizes (n,s,m,l,x) with proper scaling
• Resolves channel mismatches between DINO and YOLOv12 architectures

✅ Robust Error Handling:

• Clear error messages for unsupported file formats
• Graceful fallback for missing or corrupted weight files
• Detailed logging for troubleshooting

🧪 Real-World Usage Examples

# Example 1: Domain-specific trained DINO for crack detection
python train_yolov12_dino.py \
    --data crack_dataset.yaml \
    --yolo-size l \
    --dino-input /models/crack_detection_dino.pth \
    --integration dual \
    --epochs 200 \
    --name crack_dino_yolo

# Example 2: Medical imaging DINO with triple integration
python train_yolov12_dino.py \
    --data medical_scans.yaml \
    --yolo-size x \
    --dino-input ./medical_dino_weights.safetensors \
    --integration triple \
    --epochs 300 \
    --name medical_triple_dino

# Example 3: Industrial defect detection with custom model
python train_yolov12_dino.py \
    --data defect_data.yaml \
    --yolo-size l \
    --dino-input /weights/defect_specialized_dino.pt \
    --integration dual \
    --epochs 150 \
    --unfreeze-dino \
    --name industrial_defect_detection

✅ Technical Implementation Status

🚨 Known Working Configurations

✅ Tested & Confirmed:

• Local weight file loading with dual integration on YOLOv12l
• Custom DINO weights with 768 embedding dimension
• DetectionModel checkpoint format handling
• A2C2f architecture compatibility
• Channel dimension auto-scaling (512 channels for l size)

📖 Complete Guide: See Custom Input Documentation for detailed examples and troubleshooting.

🚀 Quick Start for New Users

📥 Complete Setup from GitHub

# 1. Clone the repository
git clone https://github.com/Sompote/DINOV3-YOLOV12.git
cd DINOV3-YOLOV12

# 2. Create conda environment
conda create -n dinov3-yolov12 python=3.11
conda activate dinov3-yolov12

# 3. Install dependencies
pip install -r requirements.txt
pip install transformers  # For DINOv3 models
pip install -r requirements_streamlit.txt  # For Streamlit web interface
pip install -e .

# 4. Setup Hugging Face authentication (REQUIRED for DINOv3 models)
export HUGGINGFACE_HUB_TOKEN="your_token_here"
# Get your token from: https://huggingface.co/settings/tokens
# Required permissions when creating token:
#   - Read access to contents of all repos under your personal namespace
#   - Read access to contents of all public gated repos you can access
# Alternative: hf auth login

# 5. Verify installation
python -c "from ultralytics.nn.modules.block import DINO3Backbone; print('✅ DINOv3-YOLOv12 ready!')"

# 6. Quick test (recommended)
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-input dinov3_vitb16 \
    --integration single \
    --epochs 1 \
    --name quick_test

# 7. Test Streamlit web interface (optional)
python launch_streamlit.py

# 8. Try pre-trained Construction-PPE model (optional)
wget https://1drv.ms/u/c/8a791e13b6e7ac91/ETzuMC0lHxBIv1eeOkOsq1cBZC5Cj7dAZ1W_c5yX_QcyYw?e=IW5N8r -O construction_ppe_best.pt
python inference.py --weights construction_ppe_best.pt --source your_image.jpg --save

⚡ One-Command Quick Start

# For experienced users - complete setup and test in one go
git clone https://github.com/Sompote/DINOV3-YOLOV12.git && \
cd DINOV3-YOLOV12 && \
conda create -n dinov3-yolov12 python=3.11 -y && \
conda activate dinov3-yolov12 && \
pip install -r requirements.txt transformers && \
pip install -e . && \
echo "⚠️  IMPORTANT: Set your Hugging Face token before training:" && \
echo "export HUGGINGFACE_HUB_TOKEN=\"your_token_here\"" && \
echo "Get token from: https://huggingface.co/settings/tokens" && \
echo "Required permissions: Read access to repos + public gated repos" && \
echo "✅ Setup complete! Run: python train_yolov12_dino.py --help"

🔐 Hugging Face Authentication Setup

Why Authentication is Required

DINOv3 models from Facebook Research are hosted on Hugging Face as gated repositories, requiring authentication to access.

Step-by-Step Token Setup

1. Create Hugging Face Account: Visit huggingface.co and sign up

2. Generate Access Token:

   • Go to https://huggingface.co/settings/tokens
   • Click "New token"
   • Give it a name (e.g., "dinov3-training")

3. Set Required Permissions:

   Repositories:
   ✅ Read access to contents of all repos under your personal namespace
   ✅ Read access to contents of all public gated repos you can access
   

4. Apply Token:

   # Method 1: Environment variable (recommended) ✅ FULLY SUPPORTED
   export HUGGINGFACE_HUB_TOKEN="hf_your_token_here"
   # The training script automatically detects and uses this token
   
   # Method 2: Login command (interactive)
   hf auth login
   # Follow the interactive prompts:
   # - Enter your token (input will not be visible)
   # - Choose to add token as git credential (Y/n)
   # - Token validation will be confirmed
   

   ✅ Token Detection: The training script will show:

   Using HUGGINGFACE_HUB_TOKEN: hf_xxxx...
   

   If your token is properly detected.

5. Verify Access:

   hf whoami
   # Should show your username if authenticated correctly
   

Common Issues

• ❌ 401 Unauthorized: Invalid or missing token
• ❌ Gated repo error: Token lacks required permissions
• ✅ Solution: Recreate token with correct permissions above

Installation

🔧 Standard Installation (Alternative)

wget https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.3/flash_attn-2.7.3+cu11torch2.2cxx11abiFALSE-cp311-cp311-linux_x86_64.whl
conda create -n yolov12 python=3.11
conda activate yolov12
pip install -r requirements.txt
pip install transformers  # For DINOv3 models
pip install -e .

✅ Verify Installation

# Test DINOv3 integration
python -c "from ultralytics.nn.modules.block import DINO3Backbone; print('✅ DINOv3 ready!')"

# Test training script
python train_yolov12_dino.py --help

# Quick functionality test
python test_yolov12l_dual.py

🚀 RTX 5090 Users - Important Note

If you have an RTX 5090 GPU, you may encounter CUDA compatibility issues. See RTX 5090 Compatibility Guide for solutions.

Quick Fix for RTX 5090:

# Install PyTorch nightly with RTX 5090 support
pip uninstall torch torchvision -y
pip install --pre torch torchvision --index-url https://download.pytorch.org/whl/nightly/cu121

# Verify RTX 5090 compatibility
python -c "import torch; print(f'✅ GPU: {torch.cuda.get_device_name(0) if torch.cuda.is_available() else \"No CUDA\"}')"

🏗️ Pre-trained Construction-PPE Model

🦺 Construction Personal Protective Equipment Detection

We provide a specialized YOLOv12-DINO model trained on the Construction-PPE dataset from Ultralytics 8.3.197, optimized for detecting safety equipment on construction sites. This model demonstrates the power of DINO pre-training for small datasets, achieving 35.9% better performance than base YOLOv12.

📊 Model Performance:

• mAP@50: 0.519 (51.9%) - 🏆 35.9% improvement over base YOLOv12
• mAP@50:95: 0.312 (31.2%)
• Dataset: Ultralytics Construction-PPE v8.3.197
• Training Images: ~1,000 images
• Classes: helmet, gloves, vest, boots, goggles, person, no_helmet, no_goggles, no_gloves, no_boots, none
• Model Architecture: YOLOv12-s + DINO ViT-S/16 (Single Integration)
• Training Time: 2.5 hours (RTX 4090)
• Memory Usage: 4GB VRAM

🎯 Why This Model Excels:

• 🧠 DINO Pre-training: Leverages self-supervised learning from millions of images
• 📈 Small Dataset Optimization: Specifically tuned for datasets <2000 images
• ⚡ Efficient Architecture: Single integration provides best stability-performance ratio
• 🎯 Production Ready: Extensively tested on real construction site images

🔗 Download Trained Weights:

# Download pre-trained Construction-PPE model (mAP@50: 51.9%)
wget https://1drv.ms/u/c/8a791e13b6e7ac91/ETzuMC0lHxBIv1eeOkOsq1cBZC5Cj7dAZ1W_c5yX_QcyYw?e=IW5N8r -O construction_ppe_best.pt

# Or use direct link
curl -L "https://1drv.ms/u/c/8a791e13b6e7ac91/ETzuMC0lHxBIv1eeOkOsq1cBZC5Cj7dAZ1W_c5yX_QcyYw?e=IW5N8r" -o construction_ppe_best.pt

🚀 Quick Start with Pre-trained Model:

# Download pre-trained Construction-PPE model (mAP@50: 51.9%)
wget https://1drv.ms/u/c/8a791e13b6e7ac91/ETzuMC0lHxBIv1eeOkOsq1cBZC5Cj7dAZ1W_c5yX_QcyYw?e=IW5N8r -O construction_ppe_best.pt

# Command-line inference
python inference.py \
    --weights construction_ppe_best.pt \
    --source your_construction_images/ \
    --conf 0.25 \
    --save

# Streamlit web interface
python launch_streamlit.py
# Upload construction_ppe_best.pt in the interface

🎯 Perfect for:

• 🏗️ Construction site safety monitoring
• 🦺 PPE compliance checking
• 📊 Safety audit documentation
• 🚨 Real-time safety alerts
• 📈 Safety statistics and reporting

💡 Pro Tips for Best Results:

• Use confidence threshold 0.25-0.35 for optimal detection
• Image resolution 640x640 provides best speed-accuracy balance
• For video processing, use --stream mode for real-time detection
• Batch processing recommended for large image sets

🔬 Technical Details:

• Backbone: YOLOv12-s enhanced with DINO ViT-S/16
• Integration Type: Single (P0 input preprocessing)
• Training Strategy: 50 epochs with early stopping
• Data Augmentation: Mosaic, MixUp, HSV adjustment
• Optimizer: AdamW with cosine annealing scheduler

Validation

yolov12n yolov12s yolov12m yolov12l yolov12x

from ultralytics import YOLO

model = YOLO('yolov12{n/s/m/l/x}.pt')
model.val(data='coco.yaml', save_json=True)

Training

🔧 Standard YOLOv12 Training

from ultralytics import YOLO

model = YOLO('yolov12n.yaml')

# Train the model
results = model.train(
  data='coco.yaml',
  epochs=600,
  batch=256,
  imgsz=640,
  scale=0.5,  # S:0.9; M:0.9; L:0.9; X:0.9
  mosaic=1.0,
  mixup=0.0,  # S:0.05; M:0.15; L:0.15; X:0.2
  copy_paste=0.1,  # S:0.15; M:0.4; L:0.5; X:0.6
  device="0,1,2,3",
)

# Evaluate model performance on the validation set
metrics = model.val()

# Perform object detection on an image
results = model("path/to/image.jpg")
results[0].show()

🧬 DINOv3 Enhanced Training

from ultralytics import YOLO

# Load YOLOv12 + DINOv3 enhanced model
model = YOLO('ultralytics/cfg/models/v12/yolov12-dino3.yaml')

# Train with Vision Transformer enhancement
results = model.train(
  data='coco.yaml',
  epochs=100,  # Reduced epochs due to enhanced features
  batch=16,    # Adjusted for DINOv3 memory usage
  imgsz=640,
  device=0,
)

# Available DINOv3 configurations:
# - yolov12-dino3-small.yaml  (fastest, +2.5% mAP)
# - yolov12-dino3.yaml        (balanced, +5.0% mAP)
# - yolov12-dino3-large.yaml  (best accuracy, +5.5% mAP)
# - yolov12-dino3-convnext.yaml (hybrid, +4.5% mAP)

🔍 Inference & Prediction

🖥️ Interactive Streamlit Web Interface

Launch the professional Streamlit interface with advanced analytics and large file support:

# Method 1: Interactive launcher (recommended)
python launch_streamlit.py

# Method 2: Direct launch
streamlit run simple_streamlit_app.py --server.maxUploadSize=5000

Streamlit Features:

• 📁 Large File Support: Upload models up to 5GB (perfect for YOLOv12-DINO models)
• 📊 Advanced Analytics: Interactive charts, detection tables, and data export
• 🎛️ Professional UI: Clean interface with real-time parameter controls
• 📈 Data Visualization: Pie charts, confidence distributions, and statistics
• 💾 Export Results: Download detection data as CSV files
• 📜 Detection History: Track multiple inference sessions

Access: http://localhost:8501

Professional Streamlit interface showing PPE detection with confidence scores, class distribution, and detailed analytics

📊 Interface Comparison

📝 Command Line Inference

Use the powerful command-line interface for batch processing and automation:

# Single image inference
python inference.py --weights best.pt --source image.jpg --save --show

# Batch inference on directory
python inference.py --weights runs/detect/train/weights/best.pt --source test_images/ --output results/

# Custom thresholds and options
python inference.py --weights model.pt --source images/ --conf 0.5 --iou 0.7 --save-txt --save-crop

# DINOv3-enhanced model inference
python inference.py --weights runs/detect/high_performance_dual/weights/best.pt --source data/ --conf 0.3

Command Options:

• --weights: Path to trained model weights (.pt file)
• --source: Image file, directory, or list of images
• --conf: Confidence threshold (0.01-1.0, default: 0.25)
• --iou: IoU threshold for NMS (0.01-1.0, default: 0.7)
• --save: Save annotated images
• --save-txt: Save detection results to txt files
• --save-crop: Save cropped detection images
• --device: Device to run on (cpu, cuda, mps)

🐍 Python API

Direct integration into your Python applications:

from ultralytics import YOLO
from inference import YOLOInference

# Method 1: Standard YOLO API
model = YOLO('yolov12{n/s/m/l/x}.pt')
results = model.predict('image.jpg', conf=0.25, iou=0.7)

# Method 2: Enhanced Inference Class
inference = YOLOInference(
    weights='runs/detect/train/weights/best.pt',
    conf=0.25,
    iou=0.7,
    device='cuda'
)

# Single image
results = inference.predict_single('image.jpg', save=True)

# Batch processing
results = inference.predict_batch('images_folder/', save=True)

# From image list
image_list = ['img1.jpg', 'img2.jpg', 'img3.jpg']
results = inference.predict_from_list(image_list, save=True)

# Print detailed results
inference.print_results_summary(results, "test_images")

🎯 DINOv3-Enhanced Inference

Use your trained DINOv3-YOLOv12 models for enhanced object detection:

# DINOv3 single-scale model
python inference.py \
    --weights runs/detect/efficient_single/weights/best.pt \
    --source test_images/ \
    --conf 0.25 \
    --save

# DINOv3 dual-scale model (highest performance)
python inference.py \
    --weights runs/detect/high_performance_dual/weights/best.pt \
    --source complex_scene.jpg \
    --conf 0.3 \
    --iou 0.6 \
    --save --show

# Input preprocessing model
python inference.py \
    --weights runs/detect/stable_preprocessing/weights/best.pt \
    --source video.mp4 \
    --save

📊 Inference Performance Guide

⚡ Measured Inference Latency

Real timings for yolov12m-dualp0p3-dino3-vitb16 (107.3 M params), 640×640, batch 1, on an RTX 5080 — torch 2.12.0+cu130, TensorRT 10.16.1.11, 30 warm-up + 200 timed iterations, CUDA-event timed.

Engine stage breakdown: 1.03 pre + 2.63 infer + 0.39 post ms. Reproduce with:

python benchmark_latency.py --engine best.engine --pt best.pt --imgsz 640

Two things worth noting before quoting these numbers:

• Forward-only ≠ end-to-end. Forward only is the network in isolation (the honest "the engine is X ms" figure); end-to-end adds letterboxing and NMS, which is what you actually pay per image. Once the backbone drops to 2.6 ms, preprocessing becomes ~25% of the cost.
• PyTorch FP16 ≈ FP32 (26.2 vs 26.6 ms). In eager mode this model is not tensor-core bound, so essentially the whole speedup comes from TensorRT's kernel fusion and scheduling — not from reduced precision. Running .pt with half=True alone buys you almost nothing.

See the TensorRT Conversion section under Export for how to build the engine, and for two failure modes that silently produce wrong output.

🔧 Advanced Inference Options

# Custom preprocessing and postprocessing
from inference import YOLOInference
import cv2

inference = YOLOInference('model.pt')

# Load and preprocess image
image = cv2.imread('image.jpg')
image_rgb = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)

# Run inference with custom parameters
results = inference.predict_single(
    source='preprocessed_image.jpg',
    save=True,
    show=False,
    save_txt=True,
    save_conf=True,
    save_crop=True,
    output_dir='custom_results/'
)

# Access detailed results
for result in results:
    boxes = result.boxes.xyxy.cpu().numpy()  # Bounding boxes
    confs = result.boxes.conf.cpu().numpy()  # Confidence scores
    classes = result.boxes.cls.cpu().numpy()  # Class IDs
    names = result.names  # Class names dictionary

    print(f"Detected {len(boxes)} objects")
    for box, conf, cls in zip(boxes, confs, classes):
        print(f"Class: {names[int(cls)]}, Confidence: {conf:.3f}")

Export

from ultralytics import YOLO

model = YOLO('yolov12{n/s/m/l/x}.pt')
model.export(format="engine", half=True)  # or format="onnx"

best.pt  ──►  ONNX (portable, any machine)  ──►  TensorRT engine (NVIDIA GPU only)

# Stage 0 — Export dependencies (not covered by requirements.txt):
pip install onnx onnxslim onnxscript "transformers>=4.56,<4.57"

# Stage 1 — Export ONNX (works on any machine, even without a GPU):
python export_tensorrt.py --weights runs/detect/train/weights/best.pt --format onnx

# Stage 2 — Build the TensorRT engine (run on the NVIDIA GPU machine):
python export_tensorrt.py --weights best.pt --format engine --half

# Alternative: build the engine from the ONNX with trtexec:
trtexec --onnx=best.onnx --saveEngine=best.engine --fp16

yolo predict model=best.onnx imgsz=640 source=path/to/test_image.jpg

python benchmark_latency.py --engine best.engine --pt best.pt --imgsz 640

🖥️ Interactive Demo

🎯 Streamlit Web App (Production-Ready)

Launch the professional Streamlit interface with advanced analytics:

# Interactive launcher with app selection
python launch_streamlit.py

# Or direct launch
streamlit run simple_streamlit_app.py --server.maxUploadSize=5000

# Open your browser and visit: http://localhost:8501

Professional Features:

• 📁 Large Model Support: Upload YOLOv12-DINO models up to 5GB
• 📊 Advanced Analytics: Interactive pie charts, confidence distributions
• 📈 Data Visualization: Real-time charts and statistical analysis
• 💾 Export Capabilities: Download results as CSV files
• 📜 Session History: Track multiple detection sessions
• 🎛️ Professional Controls: Clean sidebar with parameter sliders
• 🖼️ Instant Results: See detection results with bounding boxes and confidence scores
• ⚙️ Device Selection: Choose between CPU, CUDA, and MPS acceleration

🎯 Use Case Guide

Choose Streamlit Interface for:

• 🏢 Production environments and professional presentations
• 📊 Data analysis and detailed result examination
• 🧠 Research requiring statistical analysis and export
• 📈 Large models and extensive datasets
• 🎯 Interactive exploration of detection results
• 💼 Stakeholder demonstrations with professional appearance

Choose Command Line for:

• 🔄 Automation and batch processing workflows
• 🚀 High-performance inference on multiple images
• 📜 Scripting and integration with other tools
• 🖥️ Server deployments and headless environments
• 📊 Precise control over inference parameters
• 🔧 Development and debugging workflows

🧬 Official DINOv3 Integration

This repository includes official DINOv3 integration directly from Facebook Research with advanced custom model support:

🚀 Key Features

• 🔥 Official DINOv3 models from https://github.com/facebookresearch/dinov3
• 🆕 --dinoversion argument: DINOv3 is default (version=3), DINOv2 support (version=2)
• --dino-input parameter for ANY custom DINO model
• 12+ official variants (21M - 6.7B parameters)
• P4-level integration (optimal for medium objects)
• Intelligent fallback system (DINOv3 → DINOv2)
• Systematic architecture with clear naming conventions

📊 Performance Improvements

• +5-18% mAP improvement with official DINOv3 models
• Especially strong for medium objects (32-96 pixels)
• Dual-scale integration for complex scenes (+10-15% small objects)
• Hybrid CNN-ViT architectures available

📖 Complete Documentation

• Official DINOv3 Guide - Official models from Facebook Research
• Custom Input Guide - --dino-input parameter documentation
• Legacy Integration Guide - Original comprehensive documentation
• Usage Examples - Code examples and tutorials
• Test Suite - Validation and testing

⚡ Advanced Training Options

🔥 DINO Weight Control: --unfreeze-dino

By default, DINO weights are FROZEN ❄️ for optimal training efficiency. Use --unfreeze-dino to make DINO weights trainable for advanced fine-tuning:

# Default behavior (Recommended) - DINO weights are FROZEN
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-variant vitb16 \
    --integration single \
    --epochs 100

# Advanced: Make DINO weights TRAINABLE for fine-tuning
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-variant vitb16 \
    --integration single \
    --unfreeze-dino \
    --epochs 100

🎯 Weight Control Strategy Guide

✅ Use Default (Frozen) when:

• 🚀 Fast training: Optimal speed and efficiency
• 💾 Limited VRAM: Lower memory requirements
• 🎯 General use: Most object detection tasks
• 🏭 Production: Stable, reliable training

🔥 Use --unfreeze-dino when:

• 🔬 Research: Maximum model capacity
• 🎨 Domain adaptation: Specialized datasets (medical, satellite, etc.)
• 📊 Large datasets: Sufficient data for full fine-tuning
• 🏆 Competition: Squeeze every bit of performance

📚 Examples for All Integration Types

# 1️⃣ Single P0 Input Integration
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16 --integration single
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16 --integration single --unfreeze-dino

# 2️⃣ Dual P3+P4 Backbone Integration
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16 --integration dual
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16 --integration dual --unfreeze-dino

# 3️⃣ DualP0P3 P0+P3 Optimized Integration (Balanced)
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16 --integration dualp0p3
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16 --integration dualp0p3 --unfreeze-dino

# 4️⃣ Triple P0+P3+P4 All Levels Integration (Ultimate)
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16 --integration triple
python train_yolov12_dino.py --data data.yaml --yolo-size s --dino-variant vitb16 --integration triple --unfreeze-dino

🎯 Quick Test

# Test pure YOLOv12 (no DINO)
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --epochs 5 \
    --name test_pure_yolov12

# Test official DINOv3 integration
python validate_dinov3.py --test-all

# Test custom input support
python test_custom_dino_input.py

# Test local weight file loading
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-input ./my_custom_dino.pth \
    --integration single \
    --epochs 5 \
    --name test_local_weights

# Example training with official DINOv3 single integration
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-variant vitb16 \
    --integration single \
    --epochs 10 \
    --name test_dinov3_single

# Example training with DINOv3 dual integration
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dino-variant vitb16 \
    --integration dual \
    --epochs 10 \
    --name test_dinov3_dual

# Test ViT-H+/16 distilled (840M) - Enterprise grade
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size l \
    --dino-variant vith16_plus \
    --integration dual \
    --epochs 10 \
    --batch-size 4 \
    --name test_vith16_plus_enterprise

# Test ViT-7B/16 ultra (6.7B) - Research only
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size l \
    --dino-variant vit7b16 \
    --integration single \
    --epochs 5 \
    --batch-size 1 \
    --name test_vit7b16_research

# Test backward compatibility with DINOv2
python train_yolov12_dino.py \
    --data coco.yaml \
    --yolo-size s \
    --dinoversion 2 \
    --dino-variant vitb16 \
    --integration single \
    --epochs 5 \
    --name test_dinov2_compatibility

⚠️ Troubleshooting: NaN Loss

If Training Shows NaN Loss:

Quick Fix - Choose One:

Option 1: Reduce Batch Size

# If using batch 90 → try 45
--batch-size 45

# Still NaN? → try 24
--batch-size 24

# Still NaN? → try 16
--batch-size 16

Option 2: Reduce Learning Rate

# If using lr 0.01 → try 0.005
--lr 0.005

# Still NaN? → try 0.003
--lr 0.003

# Still NaN? → try 0.001
--lr 0.001

Option 3: Both (Most Reliable)

--batch-size 24 --lr 0.005

One-Line Rule:

NaN Loss = Reduce batch size by half OR reduce learning rate by half (or both)

🎯 OBB (Oriented Bounding Box) Detection

YOLOv12-DINO3 now supports OBB detection for rotated objects - ideal for aerial imagery, document analysis, and applications where object orientation matters.

Example: OBB detection on aerial imagery showing rotated bounding boxes for ships and other objects

Quick Start

# Train OBB model
python trainobb.py --model yolov12m-dualp0p3 --data dota.yaml --epochs 100 --imgsz 1024

# Run inference
python inferobb.py --weights best.pt --source images/ --conf 0.25 --save-txt

Available OBB Models

Documentation

For complete OBB documentation including:

• All available model configurations
• DOTA dataset tutorial
• Training and inference CLI arguments
• Dataset format and conversion

See: README_OBB.md

Acknowledgement

Made by AI Research Group, Department of Civil Engineering, KMUTT 🏛️

The code is based on ultralytics. Thanks for their excellent work!

Official DINOv3 Integration: This implementation uses official DINOv3 models directly from Meta's Facebook Research repository: facebookresearch/dinov3. The integration includes comprehensive support for all official DINOv3 variants and the innovative --dino-input parameter for custom model loading.

YOLOv12: Based on the official YOLOv12 implementation with attention-centric architecture from sunsmarterjie/yolov12.

Citation

@article{tian2025yolov12,
  title={YOLOv12: Attention-Centric Real-Time Object Detectors},
  author={Tian, Yunjie and Ye, Qixiang and Doermann, David},
  journal={arXiv preprint arXiv:2502.12524},
  year={2025}
}

@article{dinov3_yolov12_2025
  title={DINOv3-YOLOv12: Systematic Vision Transformer Integration for Enhanced Object Detection},
  author={AI Research Group, Department of Civil Engineering, KMUTT},
  journal={GitHub Repository},
  year={2024},
  url={https://github.com/Sompote/DINOV3-YOLOV12}
}

@article{yolo_dino_paper_2025,
  title={YOLO-DINO: YOLOv12-DINOv3 Hybrid Architecture for Data-Efficient Object Detection},
  author={AI Research Group, Department of Civil Engineering, KMUTT},
  journal={arXiv preprint arXiv:2510.25140},
  year={2024},
  url={https://arxiv.org/abs/2510.25140}
}