# mono

**Repository Path**: bpyhome/mono

## Basic Information

- **Project Name**: mono
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-13
- **Last Updated**: 2025-11-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# CyclopsNet

**单目多对象3D视觉定位模型** - 基于CVPR 2025论文实现

[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
[![License](https://img.shields.io/badge/license-Research-green.svg)](LICENSE)

## 📋 简介

CyclopsNet是一个基于单目RGB图像的多对象3D视觉定位（3D Visual Grounding）模型。该模型能够根据自然语言描述，从候选3D对象中**筛选出**符合描述的目标物体。

**重要说明**：CyclopsNet 是一个**匹配器/过滤器**，不是3D检测器！
- ✅ CyclopsNet：语言-3D对象匹配
- ❌ CyclopsNet：不做3D检测，不预测3D坐标

### 🎯 核心任务

**输入**：
- 单目RGB图像（用于提取视觉特征）
- 自然语言描述
- 候选3D对象（来自外部检测器，已包含3D信息）

**输出**：匹配的对象索引（对应输入的候选3D对象）

**完整两阶段流程**：
1. **阶段1（外部）**：使用单目3D检测器（如MonoUNI）获得候选3D对象
2. **阶段2（CyclopsNet）**：根据语言描述判断哪些候选对象匹配
3. **最终输出**：匹配对象的3D边界框（来自阶段1，CyclopsNet不修改）

### ✨ 核心特性

- 🎯 **语言-3D对象匹配** - 根据语言描述从候选3D对象中筛选匹配项
- 🔍 **多对象匹配** - 同时判断场景中多个候选对象的匹配情况
- 🗣️ **语言引导** - 根据自然语言描述精确匹配目标
- 🧠 **State-Prompt视觉编码** - 融合3D几何属性到视觉特征
- 🎨 **去噪对齐融合** - 使用RDS减少多模态融合中的噪声
- 💡 **KAN网络** - 基于Kolmogorov-Arnold表示的高效编码

### 📊 性能指标

在MonoMulti3D-ROPE数据集上的表现：

| 模式 | F1 | Precision | Recall |
|------|-----|-----------|--------|
| GT bbox | **69.09** | 54.46 | 94.47 |
| Pred bbox | **60.16** | 51.98 | 71.40 |

## 🚀 快速开始

### 环境要求

- Python >= 3.8
- PyTorch >= 2.0
- CUDA >= 11.7 (推荐)
- GPU显存 >= 16GB

### 安装

```bash
# 1. 克隆仓库
git clone https://gitee.com/bpyhome/mono.git
cd mono

# 2. 安装依赖
pip install -r requirements.txt

# 3. 下载模型缓存（首次运行）
python download_models.py
```

### 数据准备

数据集已在 `VLMOD(train+test)` 目录中：
- 训练集：12,000个样本
- 测试集：300个样本

### 训练

```bash
# 激活环境并训练
conda activate mono
python cyclopsnet/train.py
```

配置文件位于 `cyclopsnet/configs/config.yaml`

### 评估

```bash
python cyclopsnet/evaluate.py \
    --config cyclopsnet/configs/config.yaml \
    --checkpoint checkpoints/best_model.pth
```

## 📚 文档

- [详细使用指南](docs/USAGE_GUIDE.md) - 训练、评估、推理详解
- [技术文档](docs/TECHNICAL_NOTES.md) - 模型架构和实现细节
- [模型缓存配置](docs/MODEL_CACHE.md) - 离线模型加载指南
- [项目结构](docs/PROJECT_STRUCTURE.md) - 代码组织说明
- [常见问题](docs/FAQ.md) - 疑难解答

## 🏗️ 完整系统架构

```
输入: 单目RGB图像 + 自然语言描述
    ↓
┌──────────────────────────────┐
│  阶段1: 3D目标检测             │
│  (MonoUNI / 其他单目检测器)    │
│  → 候选3D边界框               │
└──────────────────────────────┘
    ↓
候选: [obj1_3D, obj2_3D, ..., objN_3D]
    ↓
┌──────────────────────────────┐
│  阶段2: CyclopsNet语言匹配     │
│                              │
│  ┌────────────────────────┐ │
│  │  多模态编码             │ │
│  │  • RoBERTa (文本)      │ │
│  │  • ViT (视觉)          │ │
│  │  • State Prompt (3D)   │ │
│  └────────────────────────┘ │
│         ↓                    │
│  ┌────────────────────────┐ │
│  │  去噪对齐融合 (DAF)     │ │
│  │  • RDS 去噪            │ │
│  │  • VTC 对比学习         │ │
│  │  • QGJE 联合嵌入        │ │
│  └────────────────────────┘ │
│         ↓                    │
│  ┌────────────────────────┐ │
│  │  KAN + OTM匹配         │ │
│  │  → 匹配概率            │ │
│  └────────────────────────┘ │
└──────────────────────────────┘
    ↓
筛选: 保留匹配概率 > threshold 的对象
    ↓
输出: 匹配对象的3D边界框
      {位置(x,y,z), 尺寸(h,w,l), 朝向(yaw)}
```

## 📁 项目结构

```
mono/
├── cyclopsnet/           # 主代码目录
│   ├── models/          # 模型实现
│   │   ├── encoders/    # 编码器 (Text, Vision)
│   │   ├── fusion/      # 融合模块 (RDS, VTC, QGJE)
│   │   └── heads/       # 输出头 (KAN, OTM)
│   ├── data/            # 数据处理
│   ├── configs/         # 配置文件
│   ├── train.py         # 训练脚本
│   └── evaluate.py      # 评估脚本
├── docs/                # 文档目录
├── models_cache/        # 模型缓存 (不提交)
├── VLMOD(train+test)/   # 数据集
└── requirements.txt     # 依赖列表
```

## 🔧 配置说明

关键配置项 (`config.yaml`):

```yaml
training:
  batch_size: 14          # 根据显存调整
  num_workers: 8          # 数据加载线程
  mixed_precision: true   # 混合精度训练
  
model:
  cache_dir: "models_cache"  # 模型缓存目录
```

## 🐛 已知问题与解决

### 显存不足
- 降低 `batch_size` (推荐: 4-16)
- 降低 `max_objects` (默认: 20)

### 网络连接问题
- 使用离线模型缓存（参见 [MODEL_CACHE.md](docs/MODEL_CACHE.md)）
- 设置环境变量: `HF_HUB_OFFLINE=1`

### 更多问题
查看 [FAQ文档](docs/FAQ.md)

## 📝 引用

```bibtex
@inproceedings{guo2025cyclopsnet,
  title={Beyond Human Perception: Understanding Multi-Object World from Monocular View},
  author={Guo, Keyu and others},
  booktitle={CVPR},
  year={2025}
}
```

## 📄 许可证

本项目仅用于学术研究目的。请参阅原论文的许可条款。

## 🙏 致谢

- 论文作者团队
- Hugging Face (预训练模型)
- PyTorch, timm, transformers

## 📧 联系

- 🐛 Bug报告: [Issues](https://gitee.com/bpyhome/mono/issues)
- 💬 讨论: [Discussions](https://gitee.com/bpyhome/mono/issues)

---

⭐ 如果这个项目对你有帮助，请给个Star！