安装指南(Linux)

本指南详细介绍如何在 Linux 系统上部署和运行 MipMapEngine SDK。

Docker部署

系统要求

• 操作系统: Ubuntu
• Docker版本: 19.03 或更高版本（支持GPU）
• GPU: 支持CUDA的NVIDIA显卡，计算力75及以上
• 内存: 建议8GB以上
• 存储: 至少10GB可用空间

---

1. 环境准备

1.1 Docker环境配置

Ubuntu系统安装步骤

# 更新包管理器
sudo apt update

# 安装Docker
sudo apt install -y docker.io

# 启动Docker服务
sudo systemctl start docker
sudo systemctl enable docker

# 安装NVIDIA Container Toolkit（Ubuntu, Debian）
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 配置Docker使用NVIDIA运行时
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

1.2 验证GPU支持

# 验证Docker GPU支持
[中国大陆]
docker run --gpus all registry.mipmap3d.com/docker/nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi
[其他]
docker run --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi

---

2. 许可证管理

2.1 安装许可证工具

# 安装SenseShield许可证客户端
在网站 https://lm.virbox.com/tools.html下载 Virbox 用户工具（Linux版）（.deb(64位)）
sudo dpkg -i senseshield-lcc-2.7.2.68616-amd64.deb

2.2 激活许可证

# 使用激活码激活许可证（请将JJKB-NBFS-KTM6-206T替换为您的实际激活码）
ssclt --online_bind_license_key --license_key JJKB-NBFS-KTM6-206T

2.3 解绑许可证（机器不再使用时）

# 解绑许可证
ssclt --online_unbind_license_key --license_key JJKB-NBFS-KTM6-206T

---

4. 运行重建容器

4.1 下载镜像

docker pull registry.mipmap3d.com/docker/mipmap/runtime:v4.1-ubuntu22.04

4.2 从镜像启动容器

# 启动 Docker 容器
docker run -it --rm \
  -v /tmp:/tmp \             # 挂载宿主机目录 /tmp 到容器[许可访问需要，必须执行且按此命令挂载]
  -v /mnt:/mnt \             # 挂载宿主机目录到容器[示例，按实际情况调整]
  --cpus 8 \                 # 限制容器使用 8 个 CPU
  --gpus all \               # 使用所有 GPU（需要 NVIDIA Container Toolkit）
  --name mipmap \            # 容器名称为 mipmap
  registry.mipmap3d.com/docker/mipmap/runtime:v4.1-ubuntu22.04 \
  /bin/bash                  # 进入容器后启动 bash

重要说明：

• /mnt 目录映射：mnt是示例，实际调用者想挂载那个目录灵活执行
• /tmp 目录映射：许可访问需要，必须挂载
• --cpus 8：限制容器使用8个CPU核心
• --gpus all：启用所有GPU支持

4.2 运行重建程序

# 在容器内运行重建引擎
./mipmap_engine/reconstruct_full_engine --task_json /mnt/task.json --reconstruct_type 0

参数说明：

• --task_json：任务配置文件路径
• --reconstruct_type：重建类型（0=默认类型）

---

5. 故障排除

5.1 常见问题

问题1: Docker无法启动GPU支持

# 检查NVIDIA驱动
nvidia-smi

# 检查Docker GPU支持
[中国大陆]
docker run --gpus all registry.mipmap3d.com/docker/nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi
[其他]
docker run --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi

问题2: 容器内无法访问数据

# 检查目录映射
docker run -it -v /mnt:/mnt mipmap-engine:4.0 ls -la /mnt

5.2 日志查看

# 查看容器日志
docker logs <container_id>

# 查看许可证状态
ssclt --status

---

6. 文件结构说明

mipmap_engine/
├── reconstruct_full_engine     # 主处理程序
├── divide_engine              # 分割引擎
├── fs_proc                    # 文件系统处理
├── license_engine             # 许可证引擎
├── hardware_check             # 硬件检查工具
└── lib*.so.*                  # 依赖库文件

---

本机环境部署

📋 系统要求

推荐配置

组件	要求
操作系统	Ubuntu 22.04
CPU	Intel/AMD x86_64 8 核心以上
内存	32 GB RAM
GPU	NVIDIA GPU（支持 CUDA）
显卡驱动	NVIDIA Driver >= 525.60.33
CUDA	CUDA 12.8
磁盘空间	1 TB 可用空间

🚀 安装步骤

步骤 1：检查硬件和驱动

检查 GPU 信息

# 检查是否安装了 NVIDIA GPU
lspci | grep -i nvidia

# 检查 NVIDIA 驱动版本
nvidia-smi

如果未安装驱动或版本过低：

# Ubuntu 安装 NVIDIA 驱动
sudo apt update
sudo apt install nvidia-driver-***

步骤 2：安装 Virbox 驱动

Virbox 是 SDK 的加密工具，必须安装。

# 安装 Virbox 用户工具
下载 Virbox 用户工具：[https://lm.virbox.com/tools.html](https://lm.virbox.com/tools.html) 并安装

步骤 3：激活许可证

# 激活许可证
ssclt --online_bind_license_key --license_key JJKB-NBFS-KTM6-206T

步骤 4：解压 SDK

# 解压 SDK 包

# 查看目录结构
cd SDK-XXX
ls -la
# 应该包含：
# - bin/                # 可执行程序和动态库
# - gdal_data/          # GDAL 数据文件
# - docs/               # 使用手册

步骤 5：配置环境变量

# 设置 SDK 路径（替换为实际路径）
export MIPMAP_SDK_PATH=/path/to/MipMapEngine_SDK

# 设置库路径(追加SDK的Bin目录)
export LD_LIBRARY_PATH=$MIPMAP_SDK_PATH/bin:$LD_LIBRARY_PATH

# 建议添加到 ~/.bashrc 或 ~/.profile
echo 'export MIPMAP_SDK_PATH=/path/to/MipMapEngine_SDK' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=$MIPMAP_SDK_PATH/bin:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc

步骤 6：检查依赖

# 检查可执行程序的依赖
ldd $MIPMAP_SDK_PATH/lib/reconstruct_full_engine

# 如果有缺失的库，安装系统包
# Ubuntu
apt-get update && apt-get install -y libgl1-mesa-dev libgeos-dev libgomp1 liblcms2-2 libquadmath0 libjbig0 libdeflate0 libopenexr25 libproj22

步骤 7：验证安装

创建测试配置文件 test.json：

{
  "working_dir": "./test_output",
  "gdal_folder": "/path/to/MipMapEngine_SDK/gdal_data",
  "input_image_type": 1,
  "resolution_level": 3,
  "coordinate_system": {
    "type": 2,
    "epsg_code": 4326
  },
  "image_meta_data": [
    {
      "id": 1,
      "path": "/path/to/test/image1.jpg"
    },
    {
      "id": 2,
      "path": "/path/to/test/image2.jpg"
    }
  ]
}

运行测试：

# 进入 SDK 目录
cd $MIPMAP_SDK_PATH/bin

# 运行重建
./reconstruct_full_engine -reconstruct_type 0 -task_json test.json

# 检查输出
ls -la ./test_output/

🔧 常见问题

1. 缺少 libmipmap_engine.so

错误信息：

error while loading shared libraries: libmipmap_engine.so: cannot open shared object file

解决方法：

# 确保库路径正确
export LD_LIBRARY_PATH=$MIPMAP_SDK_PATH/bin:$LD_LIBRARY_PATH

2. CUDA 相关错误

错误信息：

CUDA error: no CUDA-capable device is detected

解决方法：

# 检查 GPU 驱动
nvidia-smi

# 更新驱动
sudo apt update
sudo apt upgrade nvidia-driver-*

4. 库版本冲突

某些系统库可能与 SDK 提供的库冲突：

# 识别冲突的库
ldd -v $MIPMAP_SDK_PATH/bin/reconstruct_full_engine

# 临时移除冲突库
mv $MIPMAP_SDK_PATH/libconflict.so $MIPMAP_SDK_PATH/libconflict.so.bak

# 使用系统库
# 系统会自动从 /usr/lib 加载

下一步

• 查看快速开始运行第一个项目
• 阅读API 参考了解详细接口
• 参考故障排除解决常见问题

---

提示：Linux 部署可能因发行版和环境差异需要调整。建议先在测试环境验证，再部署到生产环境。