Ubuntu16.04下matterport3D simulator的安装与常见问题解决指南

1. 环境准备与数据集获取

在Ubuntu16.04上部署matterport3D simulator之前，需要先搞定两件基础工作：硬件环境检查和数据集获取。我当初第一次安装时，就因为显卡驱动版本不对浪费了半天时间，这里把踩过的坑都总结出来。

硬件要求方面，NVIDIA显卡是刚需，建议使用GTX 1060及以上型号。驱动版本必须≥396.37，可以用nvidia-smi命令查看。如果版本不够，先去官网下载最新驱动。有个容易忽略的点：Ubuntu16.04默认的gcc版本是5.4，但后续编译时可能需要更高版本，建议提前安装gcc-7：

sudo add-apt-repository ppa:ubuntu-toolchain-r/test sudo apt-get update sudo apt-get install gcc-7 g++-7

数据集申请流程比想象中复杂。需要先到Matterport官网签署使用协议，这个步骤很多新手会卡住。具体操作是：

1. 访问https://niessner.github.io/Matterport/
2. 找到"Dataset Download"部分填写申请表单
3. 收到邮件后执行附件的Python脚本

实测发现用Python2.7运行下载脚本最稳定。如果只需要基础功能，建议先下载20GB的skybox图像：

python2 download_mp.py -o ~/matterport_data --type matterport_skybox_images

完整数据集有1.3TB，建议根据实际需求选择下载类型。我遇到过下载中断的情况，这时可以添加--resume参数继续下载。

2. Docker安装方案详解

用Docker部署是最推荐的方式，能避免污染本地环境。但Ubuntu16.04的Docker安装有些特殊注意事项，这里分享我的实操经验。

前置依赖有三个关键点：

1. 必须安装docker-ce而非默认仓库的旧版
2. 需要配置nvidia-docker2的专属仓库
3. 要禁用Ubuntu自带的nouveau驱动

完整安装命令序列如下：

# 卸载旧版本 sudo apt-get remove docker docker-engine docker.io # 安装依赖 sudo apt-get install apt-transport-https ca-certificates curl software-properties-common # 添加官方GPG密钥 curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add - # 设置稳定版仓库 sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" # 安装docker-ce sudo apt-get update && sudo apt-get install docker-ce # 测试安装 sudo docker run hello-world

nvidia-docker2的配置有个坑：Ubuntu16.04需要手动添加仓库源：

curl -s -L https://nvidia.github.io/nvidia-docker/ubuntu16.04/nvidia-docker.list | sudo tee /etc/apt/sources.list.d/nvidia-docker.list sudo apt-get update && sudo apt-get install nvidia-docker2 sudo pkill -SIGHUP dockerd

构建镜像时如果遇到网络问题，建议更换Dockerfile中的pip源：

RUN pip install -i https://pypi.tuna.tsinghua.edu.cn/simple torch torchvision

构建成功后，启动容器要特别注意目录映射。这是我验证过的命令模板：

nvidia-docker run -it --mount type=bind,source=$MATTERPORT_DATA_DIR,target=/root/mount/Matterport3DSimulator/data/v1/scans --volume `pwd`:/root/mount/Matterport3DSimulator mattersim:9.2-devel-ubuntu18.04

3. 本地环境编译指南

虽然Docker方案简单，但有些研究需要修改底层代码，这时候就得本地编译。我在三台不同配置的Ubuntu16.04机器上实测过，总结出这套可靠流程。

基础依赖必须逐个确认，缺一不可：

sudo apt-get install -y \ libopencv-dev \ libglm-dev \ libjsoncpp-dev \ libglew-dev \ libpython3-dev \ python3-pip \ libegl1-mesa-dev \ libgl1-mesa-dev

CMake配置是最容易出错的环节。关键是要指定正确的OpenGL路径和Python解释器位置：

cmake -D OPENGL_opengl_LIBRARY=/usr/lib/x86_64-linux-gnu/libGL.so \ -D PYTHON_EXECUTABLE=$(which python3) \ -D EGL_RENDERING=ON \ ..

如果使用Anaconda环境，需要替换为conda的python路径，例如：

-D PYTHON_EXECUTABLE=/home/username/anaconda3/envs/vln/bin/python3

编译问题排查记录几个典型错误：

1. 报错fatal error: glm/glm.hpp：

   sudo apt-get install libglm-dev

2. 报错No package 'jsoncpp' found：

   sudo apt-get install libjsoncpp-dev

3. 报错EGL not found：

   sudo apt-get install libegl1-mesa-dev

编译完成后，需要手动将生成的.so文件复制到Python路径：

cp build/MatterSim.cpython-36m-x86_64-linux-gnu.so $(python3 -c "import site; print(site.getsitepackages()[0])")

4. 常见问题解决方案

实际使用中会遇到各种奇怪报错，这里整理出高频问题的解决方法，都是血泪经验。

数据集路径问题是最常见的坑。症状包括：

• 报错ScanNotFoundError
• 提示缺少house_segmentations等文件

解决方案分三步：

1. 确认数据集目录结构应为：

   v1/scans/ ├── 17DRP5sb8fy │ ├── matterport_skybox_images │ ├── undistorted_camera_parameters │ └── ... └── ...

2. 设置环境变量：

   export MATTERPORT_DATA_DIR=/path/to/v1/scans

3. 在Python代码中初始化时指定路径：

   sim = MatterSim.Simulator() sim.setDatasetPath(os.environ['MATTERPORT_DATA_DIR'])

图形渲染问题主要表现为黑屏或闪退。解决方法：

1. 对于Docker方案，启动时添加显示相关参数：

   -e DISPLAY -v /tmp/.X11-unix:/tmp/.X11-unix

2. 本地环境需要安装mesa-utils：

   sudo apt-get install mesa-utils glxinfo | grep OpenGL # 验证安装

3. 如果使用远程服务器，需要配置X11转发

Python导入错误通常有三种表现：

1. ImportError: No module named 'MatterSim'
   • 解决方案：检查.so文件是否在Python路径
2. undefined symbol类错误
   • 需要重新编译，确保Python版本一致
3. 段错误(segmentation fault)
   • 通常是CUDA版本不匹配导致

5. 进阶使用技巧

成功安装后，这里分享几个提升效率的实用技巧，都是项目实战中积累的经验。

数据集预处理可以大幅节省内存。如果只做导航任务，可以使用压缩版数据：

python scripts/downsize_skybox.py --width 256 --height 256

这会生成256x256分辨率的图像，体积减少到原图的1/16。

多线程加载对提升性能很关键。正确的初始化方式：

sim = MatterSim.Simulator() sim.setCameraResolution(640, 480) sim.setDepthEnabled(True) sim.setBatchSize(4) # 根据GPU显存调整 sim.initialize()

自定义观察模式可以通过修改渲染参数实现：

sim.setRenderingEnabled(True) sim.setDiscretizedViewAngles(True) sim.setRestrictedNavigation(False)

对于科研用途，建议记录仿真元数据：

state = sim.getState() print(state.scanId, state.location, state.heading, state.elevation)

最后提醒一个性能优化点：在循环中避免频繁创建/销毁对象，尽量复用simulator实例。我在i7-8700K + RTX 2080Ti的机器上测试，合理配置后可以稳定达到200+ FPS。