Skip to main content

Installation Guide (Linux)

This guide details how to deploy and run MipMapEngine SDK on Linux systems.

Docker Deployment​

Linux systems only provide Docker deployment method

System Requirements​

  • Operating System: Ubuntu (WSL environment not supported)
  • Docker Version: 19.03 or higher (with GPU support)
  • GPU: NVIDIA graphics card with CUDA support, Compute Capability 5.0 or higher (Gaussian Splatting reconstruction requires 7.0 or higher)
  • Memory: 32GB or more recommended
  • Storage: At least 500GB available space

1. Environment Preparation​

1.1 Docker Environment Configuration [Skip this step if Docker is already installed]​

Ubuntu System Installation Steps​

# Update package manager
sudo apt update

# Install Docker
sudo apt install -y docker.io

# Start Docker service
sudo systemctl start docker
sudo systemctl enable docker

# Install 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

# Configure Docker to use NVIDIA runtime
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

1.2 Verify GPU Support​

# Verify Docker GPU support
[Mainland China]
docker run --gpus all registry.mipmap3d.com/docker/nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi
[Others]
docker run --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi

2. License Management​

Note: License operations are all run on the host machine

2.1 Install License Tools​

# Install SenseShield license client
Download Virbox User Tools (Linux version) (.deb 64-bit) from https://lm.virbox.com/tools.html
sudo dpkg -i senseshield-lcc-2.7.2.68616-amd64.deb

2.2 Activate License​

# Activate license using activation code (replace JJKB-NBFS-KTM6-206T with your actual activation code)
ssclt --online_bind_license_key --license_key JJKB-NBFS-KTM6-206T

2.3 Unbind License (when machine is no longer used)​

# Unbind license
ssclt --online_unbind_license_key --license_key JJKB-NBFS-KTM6-206T

4. Run Reconstruction Container​

4.1 Download Image​

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

4.2 Start Container from Image​

# Start Docker container
docker run -it --rm \
  -v /tmp:/tmp \             # Mount host directory /tmp to container [required for license access, must execute and mount as per this command]
  -v /mnt:/mnt \             # Mount host directory to container [example, adjust according to actual situation]
  --cpus 8 \                 # Limit container to use 8 CPUs
  --gpus all \               # Use all GPUs (requires NVIDIA Container Toolkit)
  --name mipmap \            # Container name is mipmap
  registry.mipmap3d.com/docker/mipmap/runtime:v4.1-ubuntu22.04 \
  /bin/bash                  # Start bash after entering container

Important Notes:

  • /mnt directory mapping: mnt is an example, the caller can flexibly mount whichever directory they want
  • /tmp directory mapping: required for license access, must be mounted
  • --cpus 8: Limit container to use 8 CPU cores
  • --gpus all: Enable all GPU support

4.2 Run Reconstruction Program​

# Run reconstruction engine in container
./mipmap_engine/reconstruct_full_engine --task_json /mnt/task.json --reconstruct_type 0

Parameter Description:

  • --task_json: Task configuration file path
  • --reconstruct_type: Reconstruction type (0=default type)

5. Troubleshooting​

5.1 Common Issues​

Issue 1: Docker cannot start GPU support

# Check NVIDIA driver
nvidia-smi

# Check Docker GPU support
[Mainland China]
docker run --gpus all registry.mipmap3d.com/docker/nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi
[Others]
docker run --gpus all nvidia/cuda:12.8.0-base-ubuntu22.04 nvidia-smi

6. File Structure Description​

mipmap_engine/
├── data/                       # gdal_folder directory
├── reconstruct_full_engine     # Main processing program

Next Steps​