# COD-TDQ 中文文档 🧊

本文档对应论文 **When W4A4 Breaks Camouflaged Object Detection: Token-Group Dual-Constraint Activation Quantization**，论文已被 ECCV 2026 接收。

中文论文：[PDF](./COD-TDQ-zh.pdf) / [TeX](./COD-TDQ-zh.tex)

## ✨ 工作亮点

<p align="center">
  <img src="../assets/failure_machnism.png" alt="朴素 W4A4 量化在伪装目标检测中的失效机制" width="88%">
</p>

朴素 W4A4 量化容易压制伪装目标检测依赖的弱激活线索，导致量化后目标区域消失。

<p align="center">
  <img src="../assets/framework.png" alt="COD-TDQ 方法框架" width="88%">
</p>

- Token-group 激活量化在低比特推理下保留细粒度 COD 响应。
- 双约束联合控制目标敏感裁剪和激活范围校准。
- 开源 CFRN/ESCNet 的 W4A4 训练后量化流程、脚本和权重。

## 📦 仓库说明

COD-TDQ 面向伪装目标检测模型的训练后量化。这个 GitHub 仓库主要用于发布可复现实验代码，数据集和大模型权重单独托管。

当前代码包含：

- CFRN/CFRNet 的 W8A8、W4A8、W4A4 量化导出与推理。
- ESCNet 的 W8A8、W4A8、W4A4 量化导出与推理。
- DSTG token-group 激活量化、DCRP 双约束裁剪、QDQ 模块重建、校准和 checkpoint 导出。
- CFRN W4A4 公开路径对应的真实量化 Triton 推理算子。
- 常用量化和推理脚本封装。

## 🗂️ 目录结构

```text
cod-tdq/
├── assets/                 # 数据集和权重占位，不提交大文件
├── configs/                # CFRN/ESCNet 主配置
├── model_sources/          # CFRN 与 ESCNet backbone
├── quantization/           # COD-TDQ 核心实现
├── scripts/                # 量化与推理脚本
├── docs/index.html         # 项目主页
├── environment.yml
└── requirements.txt
```

## ⚙️ 环境安装

```bash
cd cod-tdq
conda env create -f environment.yml
conda activate cod-tdq
python -m pip install -e .
```

如果需要手动安装 PyTorch，请先根据本机 CUDA 版本安装匹配 wheel，再执行：

```bash
python -m pip install -r requirements.txt
python -m pip install -e .
```

## 📁 数据集与权重

大文件不提交到 GitHub。推荐放置结构：

```text
assets/
├── datasets/cod/
│   ├── TrainValDataset/{Imgs,GT,Edge}
│   └── TestDataset/{CHAMELEON,CAMO,COD10K,NC4K}/{Imgs,GT}
├── model_weights/
│   ├── cfrn/Net_epoch_best.pth
│   └── escnet/epoch_120.pth
└── quantized_models/
    ├── cfrn/our.pth
    └── escnet/our.pt
```

下载链接：

- 数据集：[Hugging Face Dataset: cod-tdq/cod](https://huggingface.co/datasets/cod-tdq/cod)
- FP32 权重：[Hugging Face Model: cod-tdq/cod-tdq](https://huggingface.co/cod-tdq/cod-tdq)
- 量化权重：[Hugging Face Model: cod-tdq/cod-tdq](https://huggingface.co/cod-tdq/cod-tdq)

模型权重仓库中，默认发布权重和消融权重分开放置：

```text
cfrn/fp32/Net_epoch_best.pth
cfrn/cod-tdq/our.pth
escnet/fp32/epoch_120.pth
escnet/cod-tdq/our.pt
ablation/
├── cfrn/{cfrn_per_tensor_tuned.pth,cfrn_dstg_only_tuned.pth,cfrn_dcrp_only_tuned.pth}
├── escnet/{escnet_per_tensor_tuned.pt,escnet_dstg_only_tuned.pt,escnet_dcrp_only_tuned.pt}
├── reports/{final_manifest.json,final_results.md}
└── SHA256SUMS
```

消融权重位于 Hugging Face model repository 的 `ablation/` 目录；普通推理示例默认使用 `cfrn/cod-tdq/our.pth` 和 `escnet/cod-tdq/our.pt`。

推荐托管方式：Hugging Face、Google Drive、百度网盘；小体积权重也可使用 GitHub Release。

## ⚡ CFRN 真实量化 Triton 算子

当前公开仓库包含 CFRN 真实量化 Triton 推理路径：

- `quantization/cfrn/quantlib/triton_kernels.py`
- `quantization/cfrn/quantlib/triton_qmodules.py`

该路径在加载 CFRN 量化 checkpoint 后，将支持的 `QuantLinear` 和 1x1 `QuantConv2d` 替换为 Triton integer GEMM 算子；其余不支持层继续使用现有 fallback/cached 路径。

使用前请单独安装 Triton：

```bash
python -m pip install triton
```

启用 CFRN Triton 真实量化路径：

```bash
CFRN_QUANT_CKPT=assets/quantized_models/cfrn/our.pth \
COD_TEST_ROOT=assets/datasets/cod/TestDataset/CHAMELEON \
PRED_DIR=artifacts/preds/cfrn_codtdq_triton_CHAMELEON \
bash scripts/run_infer.sh --backbone cfrn --triton
```

`--triton` 需要 CUDA GPU 和 CFRN 量化 checkpoint；FP32 推理和 ESCNet 推理不使用该开关。

## 🚀 量化命令

CFRN:

```bash
bash scripts/run_quant.sh --backbone cfrn --mode w4a4
```

ESCNet:

```bash
bash scripts/run_quant.sh --backbone escnet --mode w4a4
```

可用环境变量覆盖路径：

```bash
CFRN_CKPT=assets/model_weights/cfrn/Net_epoch_best.pth \
COD_TRAIN_ROOT=assets/datasets/cod/TrainValDataset \
bash scripts/run_quant.sh --backbone cfrn --mode w4a4
```

```bash
ESCNET_CKPT=assets/model_weights/escnet/epoch_120.pth \
ESCNET_CALIB_DIR=assets/datasets/cod/TrainValDataset \
bash scripts/run_quant.sh --backbone escnet --mode w4a4
```

## 🔍 推理命令

CFRN:

```bash
bash scripts/run_infer.sh --backbone cfrn
```

ESCNet:

```bash
bash scripts/run_infer.sh --backbone escnet
```

示例：

```bash
CFRN_QUANT_CKPT=assets/quantized_models/cfrn/our.pth \
COD_TEST_ROOT=assets/datasets/cod/TestDataset/CHAMELEON \
PRED_DIR=artifacts/preds/cfrn_codtdq_CHAMELEON \
bash scripts/run_infer.sh --backbone cfrn
```

## ✅ Smoke Test

无数据和权重时可先执行：

```bash
python -m compileall -q model_sources quantization
python -m py_compile quantization/cfrn/quantlib/triton_kernels.py quantization/cfrn/quantlib/triton_qmodules.py
python quantization/cfrn/tools/quantize_cfrn.py --help
python quantization/cfrn/tools/infer_cfrn.py --help
bash scripts/run_infer.sh --backbone cfrn --triton --dry-run
python quantization/escnet/scripts/quantize_escnet.py --help
python quantization/escnet/scripts/infer_quant_escnet.py --help
bash scripts/run_quant.sh --backbone cfrn --mode w4a4 --dry-run
bash scripts/run_quant.sh --backbone escnet --mode w4a4 --dry-run
bash scripts/run_infer.sh --backbone cfrn --dry-run
bash scripts/run_infer.sh --backbone escnet --dry-run
```

本次开源整理已实际运行上述 smoke test。

## 🧩 后续扩展入口

- 新 backbone：添加到 `model_sources/<name>/`。
- 新模型量化入口：添加到 `quantization/<name>/` 和 `scripts/`。
- 项目主页：编辑 `docs/index.html`。
- ECCV 官方页发布后更新根 README 与本文件。

## 📚 引用

在 ECCV proceedings 页面发布前，请引用 arXiv 版本：

```bibtex
@article{li2026codtdq,
  title={When W4A4 Breaks Camouflaged Object Detection: Token-Group Dual-Constraint Activation Quantization},
  author={Li, Tianqi and Fang, Wenyu and He, Xin and Geng, Xue and Cheng, Xu and Liu, Yun},
  journal={arXiv preprint arXiv:2604.16855},
  year={2026},
  eprint={2604.16855},
  archivePrefix={arXiv},
  primaryClass={cs.CV}
}
```

## 📬 联系方式

COD-TDQ 相关问题请联系：[litianqi12](https://github.com/litianqi12)（3021210579@qq.com）。