alicevision/meshroom

Meshroom Docker 镜像文档

1. 镜像概述和主要用途

Meshroom 是一款基于 AliceVision 摄影测量计算机视觉框架开发的免费开源 3D 重建软件。该 Docker 镜像封装了 Meshroom 的完整运行环境，可快速部署并用于从二维图像序列生成三维模型，支持全流程自动化处理，包括相机标定、稠密点云重建、网格生成及纹理映射等核心步骤。

2. 核心功能和特性

2.1 核心功能

• 图像预处理：支持多格式图像导入（JPEG、PNG 等），自动校正畸变、对齐曝光参数；
• 特征匹配与相机标定：基于 SIFT/AKAZE 等算法进行图像特征提取与匹配，通过光束平差法（Bundle Adjustment）优化相机姿态与内参；
• 稠密重建：从稀疏点云生成稠密点云，支持多种重建策略（如基于深度图融合、泊松表面重建）；
• 网格生成：将稠密点云转换为三维网格模型，支持网格简化与优化；
• 纹理映射：自动将原始图像纹理投影至网格表面，生成带纹理的可视化三维模型；
• 全流程自动化：内置默认重建 pipeline，支持一键式启动从图像到三维模型的完整流程。

2.2 关键特性

• 开源免费：基于 Apache 2.0 协议开源，无商业使用限制；
• 跨平台兼容：通过 Docker 容器化，可在 Linux、macOS、Windows（需 Docker Desktop 支持）等系统运行；
• 图形界面支持：内置可视化界面（Meshroom UI），支持手动调整 pipeline 参数、实时查看中间结果；
• 可扩展性：支持自定义 pipeline 节点，集成 AliceVision 框架的底层算法接口。

3. 使用场景和适用范围

Meshroom 适用于需要快速从图像生成三维模型的场景，主要包括：

• 文化遗产数字化：文物、古建筑的三维扫描与存档；
• *******：工业零件的三维建模与尺寸检测；
• 虚拟现实（VR）/增强现实（AR）：创建沉浸式场景的三维资产；
• 影视与游戏制作：生成场景道具或角色的三维模型；
• 考古与地质：遗址地形、岩石样本的三维形态记录；
• 教育与科研：计算机视觉、摄影测量领域的教学与算法验证。

4. 使用方法和配置说明

4.1 前提条件

• 已安装 Docker Engine（20.10+）及 Docker Compose（可选）；
• 宿主环境支持 X11 图形界面（Linux/macOS 需原生 X11，Windows 需通过 X Server 工具如 VcXsrv 转发）；
• 本地图像数据需存储在可挂载至容器的目录（如 ~/meshroom_data）。

4.2 Docker 快速启动（docker run）

通过以下命令启动 Meshroom 容器，支持图形界面交互及本地数据挂载：

bash
docker run -it --rm \
  --name meshroom \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \  # 转发 X11 图形界面
  -v ~/meshroom_data:/data \  # 挂载本地数据目录（含输入图像及输出结果）
  -u $(id -u):$(id -g) \  # 避免容器内权限冲突（使用宿主用户 ID/组 ID）
  alicevision/meshroom:latest

参数说明：

• -e DISPLAY=$DISPLAY：传递宿主 X11 显示环境变量，确保图形界面正常显示；
• -v /tmp/.X11-unix:/tmp/.X11-unix：挂载 X11 套接字，实现容器与宿主的图形界面通信；
• -v ~/meshroom_data:/data：将宿主本地数据目录（如 ~/meshroom_data）挂载至容器内 /data 路径，用于输入图像读取及输出结果存储；
• -u $(id -u):$(id -g)：指定容器运行用户 ID/组 ID，与宿主一致，避免文件权限问题。

4.3 Docker Compose 配置

创建 docker-compose.yml 文件，简化部署流程：

yaml
version: '3'
services:
  meshroom:
    image: alicevision/meshroom:latest
    container_name: meshroom
    environment:
      - DISPLAY=${DISPLAY}
      - USER_ID=$(id -u)
      - GROUP_ID=$(id -g)
    volumes:
      - /tmp/.X11-unix:/tmp/.X11-unix
      - ./meshroom_data:/data  # 当前目录下的 meshroom_data 目录作为数据卷
    network_mode: "host"  # 简化网络配置（可选，根据宿主环境调整）
    restart: "no"  # 非持久化运行，退出后自动清理

启动命令：

bash
docker-compose up

4.4 基本操作流程

1. 准备数据：将待处理的图像序列放入宿主数据目录（如 ~/meshroom_data/input）；
2. 启动容器：通过上述 docker run 或 docker-compose up 命令启动 Meshroom；
3. 导入图像：在 Meshroom 图形界面中，点击 "File" → "Import Images"，选择 /data/input 路径下的图像；
4. 运行重建流程：点击界面底部 "Start" 按钮，默认 pipeline 将自动执行从相机标定到纹理映射的全流程；
5. 导出结果：重建完成后，结果文件（点云、网格、纹理）将保存至 /data/output 路径，可在宿主数据目录中查看。

5. 配置参数说明

5.1 环境变量

5.2 挂载卷

6. 注意事项

• 性能优化：3D 重建为计算密集型任务，建议在多核 CPU 及支持 CUDA 的 GPU 环境下运行（需确保 Docker 支持 GPU 转发，如使用 nvidia-docker）；
• 图像要求：输入图像需满足一定重叠度（建议 >60%），且包含丰富纹理特征，避免纯色或高反光表面；
• 权限问题：若出现 "无法连接到 X 服务器" 或文件读写权限错误，需检查 DISPLAY 变量配置及 USER_ID/GROUP_ID 是否与宿主一致。