LightGlue 部署项目 - 完整文档

📋 项目概述

本项目是基于 LightGlue 的特征匹配与相机位置跟踪系统，支持实时视频流处理、UDP 图片传输、TensorRT 加速等功能。

🚀 快速开始

基础运行（异步版本，推荐）

 python demo_lightglue_camera_position_async.py ^
    --input "udp://0.0.0.0:12346" ^
    --max_keypoints 64 ^
    --use_fp16 ^
    --use_tensorrt ^
    --tensorrt_precision fp16 ^
    --depth_confidence 0.90 ^
    --width_confidence 0.95 ^
    --keypoint_threshold 0.015 ^
    --nms_radius 5

📁 项目结构

LightGlue_Deployment/
│
├── demo_lightglue_camera_position_async.py    # 异步版本主程序（推荐）
├── demo_lightglue_camera_position_single_window.py  # 单窗口版本
│
├── udp_jpeg_receiver.py                       # UDP JPEG 接收器
├── tensorrt_wrapper.py                        # TensorRT 包装器
├── trt_engine.py                              # TensorRT 引擎管理
│
├── lightglue/                                 # LightGlue 核心库
│   ├── __init__.py
│   ├── lightglue.py                           # LightGlue 匹配器
│   ├── superpoint.py                          # SuperPoint 特征提取器
│   ├── aliked.py                              # ALIKED 特征提取器
│   ├── disk.py                                # DISK 特征提取器
│   ├── sift.py                                # SIFT 特征提取器
│   ├── dog_hardnet.py                         # DoG-HardNet 特征提取器
│   ├── utils.py                               # 工具函数
│   └── viz2d.py                               # 可视化工具
│
├── scripts/                                   # 工具脚本
│   ├── build_tensorrt.py                      # TensorRT 构建脚本
│   ├── export_to_onnx.py                     # ONNX 导出脚本
│   └── demo_tensorrt_async.py                 # TensorRT 异步示例
│
├── requirements.txt                           # 基础依赖
├── requirements_tensorrt.txt                  # TensorRT 版本依赖
│
├── install.bat                                # 基础安装脚本
├── install_all.bat                            # 完整安装脚本
├── install_tensorrt.bat                        # TensorRT 安装脚本
│
└── [文档文件]
    ├── GTX1660完整部署指南.md
    ├── TENSORRT_QUICKSTART.md
    └── ...

🔄 异步 Demo 运行流程详解

整体架构

异步版本采用多线程架构，将视频采集、模型推理、可视化分离到不同线程，最大化性能：

┌─────────────────────────────────────────────────────────┐
│                   主线程（Main Thread）                   │
│  - 参数解析                                              │
│  - 模型加载（SuperPoint + LightGlue）                   │
│  - TensorRT 编译（可选）                                 │
│  - 主循环：推理 + 显示                                    │
└─────────────────────────────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
        ▼                 ▼                 ▼
┌──────────────┐  ┌──────────────┐  ┌──────────────┐
│ 线程1        │  │ 线程2        │  │ 线程3        │
│              │  │              │  │              │
│ UDP接收线程   │  │ 视频流读取    │  │ 可视化线程    │
│              │  │              │  │              │
│ - 接收UDP包  │  │ - 读取帧      │  │ - Tensor转换 │
│ - 重组JPEG   │  │ - 放入队列    │  │ - 单应性计算 │
│ - 解码图片    │  │ - 非阻塞     │  │ - 绘制图像   │
└──────────────┘  └──────────────┘  └──────────────┘

详细执行流程

1. 初始化阶段（`main()` 函数开始）

# 步骤1: 解析命令行参数
opt = parse_args()
# - 输入源（UDP/摄像头/文件）
# - 模型参数（特征点数、阈值等）
# - 优化选项（FP16、TensorRT等）

# 步骤2: 设置设备（CUDA/CPU）
device = "cuda" if torch.cuda.is_available() else "cpu"

# 步骤3: 加载模型
extractor = SuperPoint(...).eval().to(device)  # 特征提取器
matcher = LightGlue(...).eval().to(device)     # 特征匹配器

# 步骤4: TensorRT 优化（可选）
if opt.use_tensorrt:
    # 编译 SuperPoint encoder 为 TensorRT
    # 创建 HybridSuperPoint（TensorRT encoder + PyTorch 后处理）
    extractor = compile_with_tensorrt(extractor)

2. 视频流初始化

# 步骤1: 创建 VideoStreamer
streamer = VideoStreamer(opt.input, opt.resize, ...)
# - 检测输入类型（UDP/摄像头/文件）
# - 如果是 UDP，创建 UDPJPEGReceiver
# - 如果是摄像头，创建 cv2.VideoCapture

# 步骤2: 创建异步视频流读取器
async_streamer = AsyncVideoStreamer(streamer, queue_size=1)
# - 启动后台线程持续读取帧
# - 将最新帧放入队列（只保留最新1帧）

UDP 模式特殊处理：

VideoStreamer.__init__() 检测到 udp:// 前缀
创建 UDPJPEGReceiver 实例
启动 UDP 接收线程（_receive_loop()）
UDP 线程持续接收数据包，重组 JPEG，解码后放入队列

3. 主循环（`while True:`）

while True:
    # ========== 阶段1: 获取帧 ==========
    frame, ret = async_streamer.read()  # 从队列获取最新帧（非阻塞）
    if not ret:
        continue  # UDP模式：继续等待
    
    # ========== 阶段2: 预处理 ==========
    frame = apply_orientation(frame, opt)  # 旋转/翻转
    frame_tensor = frame2tensor(frame, device)  # numpy → torch tensor
    
    # ========== 阶段3: 模型推理（GPU）==========
    if opt.use_fp16:
        with torch.cuda.amp.autocast():  # FP16 混合精度
            curr_data = extractor({"image": frame_tensor})      # SuperPoint
            matches01 = matcher({"image0": last_data, "image1": curr_data})  # LightGlue
    else:
        curr_data = extractor({"image": frame_tensor})
        matches01 = matcher({"image0": last_data, "image1": curr_data})
    
    # ========== 阶段4: 提交可视化任务（非阻塞）==========
    async_visualizer.submit(
        frame, last_frame, last_data, curr_data, matches01, ...
    )
    # 将原始数据提交到后台线程处理（不等待）
    
    # ========== 阶段5: 获取可视化结果（非阻塞）==========
    viz_result = async_visualizer.get_result(timeout=0.0)
    if viz_result:
        reference_view = viz_result[1]
        cv2.imshow("Camera Position in Reference", reference_view)
    
    # ========== 阶段6: 更新参考帧 ==========
    if key == 'n':
        last_data = curr_data
        last_frame = frame

4. 后台线程工作流程

线程1: AsyncVideoStreamer._reader()

while not stop:
    frame, ret = streamer.next_frame()  # 读取帧（可能阻塞）
    if ret:
        # 只保留最新帧（丢弃旧帧）
        if queue.full():
            queue.get_nowait()  # 丢弃旧帧
        queue.put(frame)  # 放入新帧

线程2: AsyncVisualizer._visualizer_worker()

while not stop:
    # 从输入队列获取数据
    viz_data = input_queue.get()
    
    # CPU操作（在主线程会阻塞，现在在后台线程）
    kpts0 = last_data["keypoints"][0].cpu().numpy()  # GPU → CPU
    kpts1 = curr_data["keypoints"][0].cpu().numpy()
    matches = matches01["matches0"][0].cpu().numpy()
    
    # 计算单应性矩阵
    current_H, mask = cv2.findHomography(mkpts0, mkpts1, ...)
    
    # 绘制参考视图
    reference_view = draw_camera_position_on_reference(...)
    
    # 放入输出队列
    output_queue.put((display_frame, reference_view, ...))

线程3: UDPJPEGReceiver._receive_loop()（仅UDP模式）

while running:
    data, addr = socket.recvfrom(65507)  # 接收UDP包
    _process_data(data)  # 处理数据包
    
    # _process_data 逻辑：
    # 1. 检测 JPEG 开始标记（FFD8）
    # 2. 累积数据到 buffer
    # 3. 检测 JPEG 结束标记（FFD9）
    # 4. 验证并解码 JPEG
    # 5. 放入 image_queue

📦 核心模块详解

1. `demo_lightglue_camera_position_async.py` - 异步主程序

功能：异步版本的 LightGlue 演示程序

主要类：

AsyncVisualizer：异步可视化器
- 在后台线程处理 CPU 操作（tensor 转换、单应性计算、绘制）
- 使用队列传递数据，避免阻塞主线程
- 位置：第48-175行
AsyncVideoStreamer：异步视频流读取器
- 在后台线程持续读取帧
- 只保留最新帧，丢弃旧帧（降低延迟）
- 位置：第178-230行

主要函数：

main()：主函数
- 初始化模型、视频流、可视化器
- 主循环：推理 + 显示
- 位置：第323-815行
parse_args()：命令行参数解析
- 输入源、模型参数、优化选项
- 位置：第253-292行

2. `udp_jpeg_receiver.py` - UDP JPEG 接收器

功能：接收 UDP 传输的 JPEG 图片并重组

核心类：UDPJPEGReceiver

工作原理：

UDP 接收（_receive_loop()）
- 持续调用 socket.recvfrom(65507) 接收 UDP 包
- 每个包最大 65507 字节（UDP 最大负载）
JPEG 重组（_process_data()）
- 检测 JPEG 开始标记：0xFF 0xD8（JPEG_START）
- 累积数据到 buffer
- 检测 JPEG 结束标记：0xFF 0xD9（JPEG_END）
- 提取完整 JPEG 数据
验证和解码
- 验证 JPEG 头尾标记
- 使用 cv2.imdecode() 解码
- 解码成功则放入队列
超时处理
- 如果 2 秒内未收到完整图片，重置缓冲区

关键方法：

__init__(host, port, timeout)：初始化 UDP socket
start()：启动接收线程
get_image(timeout)：从队列获取解码后的图像
stop()：停止接收

使用示例：

receiver = UDPJPEGReceiver(host='0.0.0.0', port=5000)
receiver.start()
frame = receiver.get_image(timeout=0.1)

3. `demo_lightglue_camera_position_single_window.py` - 单窗口版本

功能：同步版本的演示程序（用于对比和调试）

特点：

所有操作在主线程执行（同步）
代码更简单，易于理解
性能较低（阻塞操作多）

主要类：

VideoStreamer：视频流读取器
- 支持多种输入源（UDP、摄像头、文件、图片序列）
- UDP 模式集成 UDPJPEGReceiver
- 位置：第66-216行

主要函数：

draw_camera_position_on_reference()：绘制相机位置
- 在参考图像上绘制当前相机位置
- 使用单应性矩阵计算位置
- 位置：第227-350行

4. `lightglue/` - LightGlue 核心库

4.1 `lightglue/superpoint.py` - SuperPoint 特征提取器

功能：提取图像特征点和描述符

核心类：SuperPoint

工作流程：

编码器：卷积网络提取特征图
特征点检测：从特征图检测关键点
NMS：非极大值抑制去除重复点
描述符提取：为每个关键点计算描述符

输出：

{
    "keypoints": tensor,      # [B, N, 2] 关键点坐标
    "keypoint_scores": tensor, # [B, N] 关键点分数
    "descriptors": tensor      # [B, N, 256] 描述符
}

4.2 `lightglue/lightglue.py` - LightGlue 匹配器

功能：匹配两幅图像的特征点

核心类：LightGlue

工作流程：

特征归一化：归一化关键点坐标
注意力机制：使用 Transformer 计算特征相似度
匹配计算：找到最佳匹配对
置信度过滤：根据置信度过滤匹配

输出：

{
    "matches0": tensor,         # [B, N0] 匹配索引
    "matches1": tensor,         # [B, N1] 匹配索引
    "matching_scores0": tensor  # [B, N0] 匹配分数
}

4.3 `lightglue/utils.py` - 工具函数

功能：提供辅助函数

主要函数：

numpy_image_to_torch()：numpy 图像转 torch tensor
match_pair()：匹配图像对的便捷函数

4.4 其他特征提取器

aliked.py：ALIKED 特征提取器
disk.py：DISK 特征提取器
sift.py：SIFT 特征提取器（传统方法）
dog_hardnet.py：DoG-HardNet 特征提取器

5. `tensorrt_wrapper.py` - TensorRT 包装器

功能：封装 TensorRT 编译和推理

核心类：

TensorRTWrapper：TensorRT 推理包装器
- 支持 Torch-TensorRT 编译
- 自动保存/加载编译后的模型
- 位置：第15-125行
SuperPointTensorRT：SuperPoint TensorRT 包装器
LightGlueTensorRT：LightGlue TensorRT 包装器

使用方式：

wrapper = TensorRTWrapper(model, precision="fp16")
result = wrapper(input_tensor)

6. `scripts/` - 工具脚本

6.1 `scripts/build_tensorrt.py`

功能：构建 TensorRT 引擎（ONNX → TensorRT）

6.2 `scripts/export_to_onnx.py`

功能：导出 PyTorch 模型为 ONNX 格式

6.3 `scripts/demo_tensorrt_async.py`

功能：TensorRT 异步演示示例

🔄 数据流图

UDP 模式数据流

发送端
  │
  │ UDP 包（JPEG数据片段）
  ▼
┌─────────────────────────────────┐
│ UDPJPEGReceiver._receive_loop() │ ← 线程1：接收UDP包
│  - recvfrom()                    │
│  - 检测 FFD8/FFD9                │
│  - 重组完整JPEG                  │
│  - cv2.imdecode()                │
└─────────────────────────────────┘
  │
  │ 完整图像（numpy array）
  ▼
┌─────────────────────────────────┐
│ image_queue (Queue)             │
└─────────────────────────────────┘
  │
  │ get_image()
  ▼
┌─────────────────────────────────┐
│ VideoStreamer.next_frame()      │
│  - 灰度转换                      │
│  - Resize（如需要）              │
└─────────────────────────────────┘
  │
  │ 灰度图像
  ▼
┌─────────────────────────────────┐
│ AsyncVideoStreamer._reader()    │ ← 线程2：读取帧
│  - 放入队列（只保留最新）         │
└─────────────────────────────────┘
  │
  │ frame (numpy)
  ▼
┌─────────────────────────────────┐
│ 主线程主循环                      │
│  - frame2tensor()               │
│  - SuperPoint 推理               │
│  - LightGlue 推理                │
└─────────────────────────────────┘
  │
  │ 推理结果（tensor）
  ▼
┌─────────────────────────────────┐
│ AsyncVisualizer._visualizer_     │ ← 线程3：可视化
│   worker()                       │
│  - tensor → numpy                │
│  - 计算单应性矩阵                 │
│  - 绘制参考视图                   │
└─────────────────────────────────┘
  │
  │ 绘制好的图像
  ▼
┌─────────────────────────────────┐
│ cv2.imshow()                    │
│ 显示窗口                         │
└─────────────────────────────────┘

模型推理流程

输入图像（灰度）
  │
  ▼
┌─────────────────┐
│ frame2tensor()   │ numpy → torch tensor
└─────────────────┘
  │
  │ [1, 1, H, W] tensor
  ▼
┌─────────────────────────────────┐
│ SuperPoint                      │
│  ├─ Encoder (卷积层)            │ ← TensorRT 优化部分
│  ├─ 特征点检测                  │
│  ├─ NMS                         │
│  └─ 描述符提取                  │
└─────────────────────────────────┘
  │
  │ {keypoints, descriptors, scores}
  ▼
┌─────────────────────────────────┐
│ LightGlue                       │
│  ├─ 特征归一化                  │
│  ├─ Transformer 注意力         │
│  ├─ 匹配计算                    │
│  └─ 置信度过滤                  │
└─────────────────────────────────┘
  │
  │ {matches0, matches1, scores}
  ▼
┌─────────────────────────────────┐
│ 后处理                          │
│  ├─ tensor → numpy              │
│  ├─ 计算单应性矩阵               │
│  └─ 可视化                      │
└─────────────────────────────────┘

🎯 关键设计模式

1. 异步架构

目的：减少阻塞，提高性能

实现：

视频采集：后台线程
可视化：后台线程
主线程：只做 GPU 推理（最快）

优势：

GPU 推理不等待 I/O
CPU 操作不阻塞 GPU
延迟更低，FPS 更高

2. 队列缓冲

目的：解耦生产者和消费者

实现：

AsyncVideoStreamer：帧队列（size=1，只保留最新）
AsyncVisualizer：输入队列 + 输出队列（size=2）

优势：

生产者不会阻塞消费者
自动丢弃旧数据（降低延迟）

3. 混合优化（TensorRT）

目的：平衡性能和兼容性

实现：

SuperPoint encoder：TensorRT 优化（卷积层）
SuperPoint 后处理：PyTorch（动态操作）
LightGlue：PyTorch（复杂输入）

优势：

主要计算加速（encoder 占大部分时间）
保持灵活性（动态操作不受限）

📊 性能优化要点

1. 异步处理

✅ 视频采集异步（不阻塞推理）
✅ 可视化异步（不阻塞推理）
✅ GPU 推理连续（最大化利用率）

2. TensorRT 优化

✅ SuperPoint encoder 加速（2-3倍）
✅ FP16 精度（1.5-2倍）
⚠️ LightGlue 未优化（复杂，难以编译）

3. 数据流优化

✅ 只保留最新帧（降低延迟）
✅ 队列大小最小化（减少内存）
✅ 非阻塞操作（避免等待）

🔧 配置说明

输入源配置

输入格式	示例	说明
UDP JPEG	`udp://0.0.0.0:12346`	UDP 透传 JPEG
USB 摄像头	`0`	摄像头索引
IP 摄像头	`http://192.168.1.100:8080/video`	IP 摄像头 URL
视频文件	`video.mp4`	视频文件路径
图片序列	`images/`	图片目录

性能参数

参数	默认值	说明
`--max_keypoints`	1024	最大特征点数（影响速度）
`--resize`	640 480	输入分辨率（影响速度）
`--use_fp16`	False	FP16 半精度（提升30%）
`--use_tensorrt`	False	TensorRT 加速（提升50-100%）
`--tensorrt_precision`	fp16	TensorRT 精度（fp16/int8）

📝 代码关键位置索引

异步版本主程序

功能	文件	行号
主函数入口	`demo_lightglue_camera_position_async.py`	323
参数解析	`demo_lightglue_camera_position_async.py`	253
模型加载	`demo_lightglue_camera_position_async.py`	348-360
TensorRT 编译	`demo_lightglue_camera_position_async.py`	364-555
主循环	`demo_lightglue_camera_position_async.py`	710-815
异步可视化器	`demo_lightglue_camera_position_async.py`	48-175
异步视频流	`demo_lightglue_camera_position_async.py`	178-230

UDP 接收

功能	文件	行号
UDP 接收器类	`udp_jpeg_receiver.py`	16-211
UDP 接收循环	`udp_jpeg_receiver.py`	62-85
JPEG 重组逻辑	`udp_jpeg_receiver.py`	87-138
UDP 集成	`demo_lightglue_camera_position_single_window.py`	82-111

模型核心

功能	文件	行号
SuperPoint 类	`lightglue/superpoint.py`	-
LightGlue 类	`lightglue/lightglue.py`	321+
工具函数	`lightglue/utils.py`	-

🐛 调试建议

1. 检查 UDP 接收

# 在 udp_jpeg_receiver.py 中添加调试输出
print(f"[DEBUG] Received {len(data)} bytes from {addr}")
print(f"[DEBUG] Buffer size: {len(self.buffer)}")

2. 检查帧率

# 使用 --show_fps 参数
python demo_lightglue_camera_position_async.py --show_fps ...

3. 检查 TensorRT

# 查看编译输出
# 应该看到 "[OK] Encoder compiled with TensorRT successfully"

✅ 总结

本项目采用异步多线程架构，通过以下方式实现高性能：

异步视频采集：不阻塞 GPU 推理
异步可视化：CPU 操作在后台线程
TensorRT 优化：加速主要计算部分
队列缓冲：解耦生产者和消费者

核心优势：

高 FPS（25-35 FPS，取决于配置）
低延迟（只保留最新帧）
灵活输入（UDP/摄像头/文件）
易于扩展（模块化设计）

README.md 22 KB Permalink History Raw

LightGlue 部署项目 - 完整文档

📋 项目概述

🚀 快速开始

基础运行（异步版本，推荐）

📁 项目结构

🔄 异步 Demo 运行流程详解

整体架构

详细执行流程

1. 初始化阶段（main() 函数开始）

2. 视频流初始化

3. 主循环（while True:）

4. 后台线程工作流程

📦 核心模块详解

1. demo_lightglue_camera_position_async.py - 异步主程序

2. udp_jpeg_receiver.py - UDP JPEG 接收器

3. demo_lightglue_camera_position_single_window.py - 单窗口版本

4. lightglue/ - LightGlue 核心库

4.1 lightglue/superpoint.py - SuperPoint 特征提取器

4.2 lightglue/lightglue.py - LightGlue 匹配器

4.3 lightglue/utils.py - 工具函数

4.4 其他特征提取器

5. tensorrt_wrapper.py - TensorRT 包装器

6. scripts/ - 工具脚本

6.1 scripts/build_tensorrt.py

6.2 scripts/export_to_onnx.py

6.3 scripts/demo_tensorrt_async.py

🔄 数据流图

UDP 模式数据流

模型推理流程

🎯 关键设计模式

1. 异步架构

2. 队列缓冲

3. 混合优化（TensorRT）

📊 性能优化要点

1. 异步处理

2. TensorRT 优化

3. 数据流优化

🔧 配置说明

输入源配置

性能参数

📝 代码关键位置索引

异步版本主程序

UDP 接收

模型核心

🐛 调试建议

1. 检查 UDP 接收

2. 检查帧率

3. 检查 TensorRT

✅ 总结

README.md 22 KB

Permalink History Raw

1. 初始化阶段（`main()` 函数开始）

3. 主循环（`while True:`）

1. `demo_lightglue_camera_position_async.py` - 异步主程序

2. `udp_jpeg_receiver.py` - UDP JPEG 接收器

3. `demo_lightglue_camera_position_single_window.py` - 单窗口版本

4. `lightglue/` - LightGlue 核心库

4.1 `lightglue/superpoint.py` - SuperPoint 特征提取器

4.2 `lightglue/lightglue.py` - LightGlue 匹配器

4.3 `lightglue/utils.py` - 工具函数

5. `tensorrt_wrapper.py` - TensorRT 包装器

6. `scripts/` - 工具脚本

6.1 `scripts/build_tensorrt.py`

6.2 `scripts/export_to_onnx.py`

6.3 `scripts/demo_tensorrt_async.py`