🌊 CDP Training Framework

Contour-Detail Prior Guided Underwater Object Detection

Degradation · Framework · Results · Protocol · Implementation · Installation · Dataset · Feature Map · License

This repository provides the official open-source implementation of CDP, a contour-detail prior guided framework for underwater object detection under noise-coupled degradation.

Focus	Description
🧩 Core idea	Introduce contour-detail priors to guide robust underwater feature representation.
📏 Training protocol	COCO AP aligned training/evaluation for fair checkpoint selection.
📝 Paper status	Accepted for publication in Optics & Laser Technology.

🌫️ Underwater Degradation Across Water Conditions

Underwater scenes exhibit substantial variation in turbidity, color cast, contrast, and structural cue strength. The figure below pairs representative underwater images with their local Sobel gradient-energy surfaces, showing how contour, texture, and other high-frequency responses weaken under severe degradation.

_{Underwater degradation analysis. Increasing turbidity produces progressively sparser gradient-energy responses before feature extraction.}

🧠 Framework Overview

_{CDP-YOLO framework. CDPB and CDPD preserve contour-detail priors throughout feature extraction and downsampling.}

🔍 Qualitative Results Across Water Conditions

The following comparisons cover complementary underwater conditions and compare the Baseline, AHFI-Res, and CDP-YOLO in the same row order.

_{Qualitative comparisons. Top: occlusion, background interference, and target-scale variation. Bottom: severe color cast, low contrast, and dense small-target distribution. Pass, Fail, and Extra counts are summarized on the right.}

🎯 COCO-Aligned Evaluation Protocol

🎯 Goal: reduce unfair comparison caused by fixed-epoch training in detection experiments.

Underwater degradation weakens contour continuity and fine-detail responses before feature extraction begins. CDP is designed to stabilize these structural cues through contour-detail priors and residual-path high-frequency compensation, while the training protocol aligns checkpoint selection with COCO AP to reduce fixed-epoch comparison bias.

Icon	Common issue	Impact
📏	mAP != COCO AP	A higher mAP may not mean a higher reported AP.
⏱️	AP peaks at different epochs	Early models may be evaluated after overfitting.
⚖️	Fixed final checkpoint	Results mix model quality with convergence timing.

CDP Training Framework runs COCO evaluation during training and keeps the best-AP checkpoint.

✅ Capability	Function
COCO AP selection	Uses COCO mAP50-95(B) as fitness.
Periodic COCO eval	Runs COCO API every N epochs.
Best checkpoint guard	Blocks non-COCO epochs from replacing best.pt.
COCO image-id mapping	Aligns prediction image_id with annotation JSON.

In short, training-time checkpoint selection follows the evaluation metric used in detection papers.

🛠️ Fair-Comparison Implementation

Detailed changes are in FAIR_COMPARISON_IMPLEMENTATION.md. In brief, this release adds COCO API evaluation, COCO-based best.pt selection, custom COCO JSON lookup, image-id mapping, optimizer fallback, and visualization utilities.

🚀 Installation

🔁 1. Clone the repository

git clone https://github.com/Sihang-Geng/CDP-Train.git
cd CDP-Train

🧪 2. Create the environment

conda create -n CDP python=3.10 -y
conda activate CDP

📦 3. Install dependencies

pip install -e .
pip install pycocotools

Install the PyTorch version that matches your CUDA environment if it is not already available.

🗂️ Dataset

This project uses the RUOD dataset: RUOD on Baidu AI Studio.

🧰 Data Preparation

Keep your RUOD files in a COCO-style structure and point your YAML to the local paths, for example:

RUOD/
├─ images/
│  ├─ train/
│  └─ val/
└─ annotations/
   ├─ instances_train.json
   └─ instances_val.json

Use your dataset YAML to map train and val to local paths.

python ultralytics/train.py

Minimal training example:

from ultralytics import YOLO

model = YOLO("/root/ultralytics/ultralytics/cfg/models/v8/yolov8s.yaml")

results = model.train(
    data="/root/ultralytics/ultralytics/cfg/datasets/RUOD/RUOD_YOLO/data.yaml",
    epochs=250,
    imgsz=640,
    seed=0,
    deterministic=True,
    save_json=True,
    use_coco_fitness=True,
    coco_eval_interval=5,
    coco_only_best=True,
    coco_start_epoch=100,
    patience=100,
)

results = model.val()

🗂️ COCO JSON Compatibility (click to expand)

The validator searches common annotation locations:

{data_path}/instances_val2017.json
{data_path}/annotations/instances_val2017.json
{data_path}/annotations/instances_val.json
{data_path}/annotations/instances_{split}.json
{data_path}/val/_annotations.coco.json
{data_path}/instances_val.json
{data_path}/_annotations.coco.json

For custom filenames, an annotation-based image ID map is built:

self.img_id_map[Path(img["file_name"]).name] = img["id"]
self.img_id_map[Path(img["file_name"]).stem] = img["id"]

This avoids AP mismatch when filenames are not numeric COCO IDs.

🧪 Recommended Modes

Mode	Use case	Key settings
CDP-style fair comparison	Paper experiments and ablation studies.	save_json=True, use_coco_fitness=True, coco_eval_interval=5, coco_only_best=True
Fast pipeline check	Debug whether training runs.	save_json=False, use_coco_fitness=False

📈 AP Alignment Curves

The curve visualizes the temporal mismatch between internal mAP and COCO AP, motivating COCO AP-based checkpoint selection.

## 🧭 Feature Map

Module	File	Role
🧠 Trainer	ultralytics/engine/trainer.py	COCO fitness and best.pt control.
⏱️ Validator	ultralytics/engine/validator.py	Scheduled JSON and COCO API calls.
🚀 Training	ultralytics/train.py	Example training entry.
🖼️ Visualization	visual.py	Qualitative detection view.
📊 Plotting / 3D	plotfig2.py, 3d.py	Figure plotting and 3D visualization.
📘 Notes	FAIR_COMPARISON_IMPLEMENTATION.md	Full implementation notes.

📦 Released Scope

This repository provides the training, evaluation, and visualization utilities used in the current research codebase.

📄 License

This project is released under the GNU AGPL-3.0 license inherited from Ultralytics. See LICENSE.

Upstream project: ultralytics/ultralytics