Minkowski Engine

Minkowski Engine 是一个用于稀疏张量的自动微分库。它支持所有标准的神经网络层，例如卷积、池化、反池化以及针对稀疏张量的广播操作。更多信息请访问 文档页面。

最新消息

• 2021-08-11 添加了 Docker 安装说明
• 2021-08-06 已解决与 PyTorch 1.8 和 1.9 相关的所有安装问题。
• 2021-04-08 由于近期在 PyTorch 1.8 + CUDA 11 中出现的问题，建议使用 Anaconda 进行安装。
• 2020-12-24 v0.5 现已发布！新版本为所有坐标管理函数提供了 CUDA 加速。

示例网络

Minkowski Engine 支持多种基于稀疏张量构建的功能。我们在此列出几种流行的网络架构和应用。要运行这些示例，请先安装该包，然后在包的根目录下执行相应命令。

示例	网络及命令
语义分割	python -m examples.indoor
分类	python -m examples.classification_modelnet40
重建	python -m examples.reconstruction
完善	python -m examples.completion
检测

稀疏张量网络：面向空间稀疏张量的神经网络

通过压缩神经网络来加速推理并最小化内存占用一直是广泛研究的主题。一种流行的模型压缩技术是剪枝卷积神经网络中的权重，也被称为 稀疏卷积网络。这种用于模型压缩的参数空间稀疏性通常应用于处理稠密张量的网络，而这些网络的所有中间激活也是稠密张量。

然而，在这项工作中，我们专注于 空间上 稀疏的数据，特别是高维的空间稀疏输入、3D 数据以及 3D 对象表面上的卷积，这一概念最早由 Siggraph'17 提出。我们也可以将这些数据表示为稀疏张量，而这类稀疏张量在 3D 感知、配准和统计数据分析等高维问题中非常常见。我们将专为这类输入设计的神经网络称为 稀疏张量网络，这些稀疏张量网络以稀疏张量作为输入和输出进行处理和生成。为了构建稀疏张量网络，我们可以像定义稠密张量上的网络层一样，使用 MLP、非线性变换、卷积、归一化、池化等标准神经网络层，并将其在 Minkowski Engine 中实现。

我们在下方展示了稀疏张量网络对稀疏张量进行卷积运算的过程。稀疏张量上的卷积层与稠密张量上的卷积层类似。然而，在稀疏张量上，我们只在少数指定的点上计算卷积输出，这些点可以通过 广义卷积 来控制。更多相关信息请访问 稀疏张量网络的文档页面 和 术语页面。

稠密张量	稀疏张量

---

特性

• 无限制的高维稀疏张量支持
• 所有标准神经网络层（卷积、池化、广播等）
• 动态计算图
• 自定义核形状
• 多 GPU 训练
• 多线程核映射
• 多线程编译
• 高度优化的 GPU 核

系统要求

• Ubuntu >= 14.04
• CUDA >= 10.1.243 并且 CUDA 版本需与 PyTorch 使用的版本一致（例如，如果使用 conda 的 cudatoolkit=11.1，则 MinkowskiEngine 编译时也应使用 CUDA=11.1）
• PyTorch >= 1.7 为指定 CUDA 版本，请使用 conda 进行安装。必须确保 PyTorch 和 MinkowskiEngine 使用的 CUDA 版本一致。conda install -y -c nvidia -c pytorch pytorch=1.8.1 cudatoolkit=10.2)
• Python >= 3.6
• ninja（用于安装）
• GCC >= 7.4.0

安装

您可以使用 pip、Anaconda 或直接在系统上安装 Minkowski Engine。如果您在安装过程中遇到问题，请查看安装维基页面。

如果找不到相关问题，请在GitHub 问题页面上报错。

• PIP 安装
• Conda 安装
• Python 安装
• Docker 安装

Pip

MinkowskiEngine 通过 PyPI MinkowskiEngine 发布，可以使用 pip 简单安装。

首先，按照 PyTorch 官方文档 安装 PyTorch。然后安装 openblas：

sudo apt install build-essential python3-dev libopenblas-dev
pip install torch ninja
pip install -U MinkowskiEngine --install-option="--blas=openblas" -v --no-deps

# 从最新源码安装
# pip install -U git+https://github.com/NVIDIA/MinkowskiEngine --no-deps

如果您想为安装脚本指定参数，请参考以下命令：

# 如果安装失败，可以取消注释部分选项
# export CXX=c++; # 如果您想使用不同的 C++ 编译器，请设置此环境变量
# export CUDA_HOME=/usr/local/cuda-11.1; # 或者选择您系统上正确的 CUDA 版本。
pip install -U git+https://github.com/NVIDIA/MinkowskiEngine -v --no-deps \
#                           \ # 如果您想强制安装 CUDA，请取消注释下一行
#                           --install-option="--force_cuda" \
#                           \ # 如果您想强制不安装 CUDA，请取消注释下一行。force_cuda 会覆盖 cpu_only
#                           --install-option="--cpu_only" \
#                           \ # 如果您想覆盖为 openblas、atlas、mkl 或其他 BLAS 库，请取消注释下一行
#                           --install-option="--blas=openblas" \

Anaconda

MinkowskiEngine 同时支持 CUDA 10.2 和 CUDA 11.1，适用于大多数最新的 PyTorch 版本。

CUDA 10.2

建议使用 python>=3.6 进行安装。首先，按照 Anaconda 官方文档 在您的计算机上安装 Anaconda。

sudo apt install g++-7  # 对于 CUDA 10.2，必须使用 GCC < 8
# 确保 `g++-7 --version` 至少为 7.4.0
conda create -n py3-mink python=3.8
conda activate py3-mink

conda install openblas-devel -c anaconda
conda install pytorch=1.9.0 torchvision cudatoolkit=10.2 -c pytorch -c nvidia

# 安装 MinkowskiEngine
export CXX=g++-7
# 如果需要指定 CUDA 安装路径，请取消注释下一行。确保 `$CUDA_HOME/nvcc --version` 是 10.2
# export CUDA_HOME=/usr/local/cuda-10.2
pip install -U git+https://github.com/NVIDIA/MinkowskiEngine -v --no-deps --install-option="--blas_include_dirs=${CONDA_PREFIX}/include" --install-option="--blas=openblas"

# 或者如果您想要本地安装的 MinkowskiEngine
git clone https://github.com/NVIDIA/MinkowskiEngine.git
cd MinkowskiEngine
export CXX=g++-7
python setup.py install --blas_include_dirs=${CONDA_PREFIX}/include --blas=openblas

CUDA 11.X

建议使用 python>=3.6 进行安装。首先，按照 Anaconda 官方文档 在您的计算机上安装 Anaconda。

conda create -n py3-mink python=3.8
conda activate py3-mink

conda install openblas-devel -c anaconda
conda install pytorch=1.9.0 torchvision cudatoolkit=11.1 -c pytorch -c nvidia

# 安装 MinkowskiEngine

# 如果需要指定 CUDA 安装路径，请取消注释下一行。确保 `$CUDA_HOME/nvcc --version` 是 11.X
# export CUDA_HOME=/usr/local/cuda-11.1
pip install -U git+https://github.com/NVIDIA/MinkowskiEngine -v --no-deps --install-option="--blas_include_dirs=${CONDA_PREFIX}/include" --install-option="--blas=openblas"

# 或者如果您想要本地安装的 MinkowskiEngine
git clone https://github.com/NVIDIA/MinkowskiEngine.git
cd MinkowskiEngine
python setup.py install --blas_include_dirs=${CONDA_PREFIX}/include --blas=openblas

系统 Python

与 Anaconda 安装类似，确保您安装的 PyTorch 使用的 CUDA 版本与 nvcc 的版本一致。

# 安装系统依赖
sudo apt install build-essential python3-dev libopenblas-dev

# 如果您的 Python3 已经安装了 pip，则跳过此步骤
curl https://bootstrap.pypa.io/get-pip.py | python3

# 获取 pip 并安装 Python 依赖
python3 -m pip install torch numpy ninja

git clone https://github.com/NVIDIA/MinkowskiEngine.git

cd MinkowskiEngine

python setup.py install
# 若要指定 BLAS、CXX、CUDA_HOME 并强制安装 CUDA，请使用以下命令：
# export CXX=c++; export CUDA_HOME=/usr/local/cuda-11.1; python setup.py install --blas=openblas --force_cuda

Docker

git clone https://github.com/NVIDIA/MinkowskiEngine
cd MinkowskiEngine
docker build -t minkowski_engine docker

构建完成后，请检查 Docker 是否正确加载了 MinkowskiEngine：

docker run MinkowskiEngine python3 -c "import MinkowskiEngine; print(MinkowskiEngine.__version__)"

仅 CPU 构建及 BLAS 配置（MKL）

Minkowski Engine 支持在没有 NVIDIA GPU 的平台上进行仅 CPU 构建。更多详细信息请参阅快速入门。

快速入门

要使用 Minkowski Engine，您首先需要导入该引擎。然后，您需要定义网络。如果您的数据尚未量化，您需要将其体素化或量化为稀疏张量。幸运的是，Minkowski Engine 提供了量化函数 (MinkowskiEngine.utils.sparse_quantize)。

创建网络

import torch.nn as nn
import MinkowskiEngine as ME

class ExampleNetwork(ME.MinkowskiNetwork):

    def __init__(self, in_feat, out_feat, D):
        super(ExampleNetwork, self).__init__(D)
        self.conv1 = nn.Sequential(
            ME.MinkowskiConvolution(
                in_channels=in_feat,
                out_channels=64,
                kernel_size=3,
                stride=2,
                dilation=1,
                bias=False,
                dimension=D),
            ME.MinkowskiBatchNorm(64),
            ME.MinkowskiReLU())
        self.conv2 = nn.Sequential(
            ME.MinkowskiConvolution(
                in_channels=64,
                out_channels=128,
                kernel_size=3,
                stride=2,
                dimension=D),
            ME.MinkowskiBatchNorm(128),
            ME.MinkowskiReLU())
        self.pooling = ME.MinkowskiGlobalPooling()
        self.linear = ME.MinkowskiLinear(128, out_feat)

    def forward(self, x):
        out = self.conv1(x)
        out = self.conv2(out)
        out = self.pooling(out)
        return self.linear(out)

使用自定义网络进行前向和反向传播

    # 损失函数和网络
    criterion = nn.CrossEntropyLoss()
    net = ExampleNetwork(in_feat=3, out_feat=5, D=2)
    print(net)

    # 数据加载器必须返回坐标、特征和标签的元组。
    coords, feat, label = data_loader()
    input = ME.SparseTensor(feat, coordinates=coords)
    # 前向传播
    output = net(input)

    # 损失
    loss = criterion(output.F, label)

讨论与文档

如有讨论或问题，请发送邮件至 minkowskiengine@googlegroups.com。 有关 API 和一般用法的详细信息，请参阅 MinkowskiEngine 文档页面。

对于未在 API 中列出的问题以及功能请求，欢迎在 GitHub 问题页面 上提交。

已知问题

指定 CUDA 架构列表

在某些情况下，您需要显式指定 GPU 所使用的计算能力。默认列表可能不包含您的架构。

export TORCH_CUDA_ARCH_LIST="5.2 6.0 6.1 7.0 7.5 8.0 8.6+PTX"; python setup.py install --force_cuda

未处理的内存不足 thrust::system 异常

CUDA 10 中的 thrust 存在一个 已知问题，会导致未处理的 thrust 异常。详情请参阅 此问题。

GPU 显存占用过高或频繁出现内存不足

导致此错误的原因有以下几点：

1. 长时间训练过程中内存不足

MinkowskiEngine 是一个专门用于处理点云数据的库，能够在每次迭代中处理不同数量的点或非零元素。然而，PyTorch 的实现假设每次迭代中的点数或激活大小不会发生变化。因此，PyTorch 使用的 GPU 内存缓存机制可能会导致不必要的大量内存消耗。

具体来说，PyTorch 会缓存一些内存块以加快张量创建时的分配速度。如果找不到合适的内存空间，它会分割现有的缓存块，或者在没有足够大的缓存时分配新的内存。因此，当我们使用 PyTorch 处理不同数量的点（即非零元素数量）时，它要么分割现有缓存，要么预留新内存。如果缓存被过度碎片化并占用了所有 GPU 显存，就会抛出内存不足的错误。

为防止这种情况发生，必须定期调用 torch.cuda.empty_cache() 清空缓存。

CUDA 11.1 安装

wget https://developer.download.nvidia.com/compute/cuda/11.1.1/local_installers/cuda_11.1.1_455.32.00_linux.run
sudo sh cuda_11.1.1_455.32.00_linux.run --toolkit --silent --override

# 使用 CUDA 11.1 安装 MinkowskiEngine
export CUDA_HOME=/usr/local/cuda-11.1; pip install MinkowskiEngine -v --no-deps

在具有大量 CPU 核心的节点上运行 MinkowskiEngine

MinkowskiEngine 使用 OpenMP 来并行化核映射的生成。然而，当用于并行化的线程数过多时（例如 OMP_NUM_THREADS=80），效率会迅速下降，因为所有线程都在等待多线程锁释放。在这种情况下，应设置 OpenMP 使用的线程数。通常，24 个以下的线程数即可，但您仍需根据系统情况找到最佳配置。

export OMP_NUM_THREADS=<要使用的线程数>; python <your_program.py>

引用 Minkowski Engine

如果您使用了 Minkowski Engine，请引用以下文献：

• 4D 空时卷积神经网络：Minkowski 卷积神经网络，CVPR'19, [pdf]

@inproceedings{choy20194d,
  title={4D Spatio-Temporal ConvNets: Minkowski Convolutional Neural Networks},
  author={Choy, Christopher and Gwak, JunYoung and Savarese, Silvio},
  booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition},
  pages={3075--3084},
  year={2019}
}

关于多线程核映射生成，请引用：

@inproceedings{choy2019fully,
  title={Fully Convolutional Geometric Features},
  author={Choy, Christopher and Park, Jaesik and Koltun, Vladlen},
  booktitle={Proceedings of the IEEE International Conference on Computer Vision},
  pages={8958--8966},
  year={2019}
}

关于高维卷积的步进池化层，请引用：

@inproceedings{choy2020high,
  title={High-dimensional Convolutional Networks for Geometric Pattern Recognition},
  author={Choy, Christopher and Lee, Junha and Ranftl, Rene and Park, Jaesik and Koltun, Vladlen},
  booktitle={Proceedings of the IEEE Conference on Computer Vision and Pattern Recognition},
  year={2020}
}

关于生成式转置卷积，请引用：

@inproceedings{gwak2020gsdn,
  title={Generative Sparse Detection Networks for 3D Single-shot Object Detection},
  author={Gwak, JunYoung and Choy, Christopher B and Savarese, Silvio},
  booktitle={European conference on computer vision},
  year={2020}
}

单元测试

进行单元测试和梯度检查时，请使用 PyTorch >= 1.7版本。

使用 Minkowski Engine 的项目

欢迎您更新维基页面，添加您的项目！

• 使用 MinkowskiEngine 的项目

• 分割：3D 和 4D 空时语义分割，CVPR'19

• 表征学习：全卷积几何特征，ICCV'19

• 3D 配准：学习多视角 3D 点云配准，CVPR'20

• 3D 配准：深度全局配准，CVPR'20

• 模式识别：用于几何模式识别的高维卷积网络，CVPR'20

• 检测：面向 3D 单次检测的生成式稀疏检测网络，ECCV'20

• 图像匹配：稀疏邻域一致性网络，ECCV'20

MinkowskiEngine 快速上手指南

Minkowski Engine 是一个专为稀疏张量设计的自动微分库，支持卷积、池化、广播等标准神经网络层。它特别适用于处理高维空间数据（如 3D 点云、体素网格），能够显著减少内存占用并加速推理。

1. 环境准备

在开始之前，请确保您的系统满足以下要求。关键注意：PyTorch 使用的 CUDA 版本必须与编译 MinkowskiEngine 时使用的 CUDA 版本完全一致。

系统要求

• 操作系统: Ubuntu >= 14.04 (推荐 Ubuntu 18.04/20.04)
• Python: >= 3.6
• 编译器: GCC >= 7.4.0, Ninja
• CUDA: >= 10.1.243 (需与 PyTorch 版本匹配)
• PyTorch: >= 1.7

前置依赖安装

建议先安装系统级依赖：

sudo apt install build-essential python3-dev libopenblas-dev ninja-build

2. 安装步骤

推荐使用 Conda 进行安装，因为它能更好地管理 CUDA 工具包和 Python 环境的依赖关系。

方案 A：使用 Conda 安装（推荐）

此方法可避免大多数 CUDA 版本不匹配的问题。以下以 CUDA 11.1 为例（如需 CUDA 10.2，请将 cudatoolkit 改为 10.2 并确保 GCC 版本 < 8）。

1. 创建并激活虚拟环境：

   conda create -n py3-mink python=3.8
   conda activate py3-mink
   

2. 安装 PyTorch 和 OpenBLAS： 注：国内用户可使用清华源加速 -c 后的频道或添加 -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/pytorch/

   conda install openblas-devel -c anaconda
   conda install pytorch=1.9.0 torchvision cudatoolkit=11.1 -c pytorch -c nvidia
   

3. 设置编译器并安装 MinkowskiEngine：

   # 指定 C++ 编译器 (根据系统情况可能需要调整，CUDA 11+ 通常不需要强制指定 g++-7)
   export CXX=g++
   
   # 从源码安装
   pip install -U git+https://github.com/NVIDIA/MinkowskiEngine -v --no-deps \
       --install-option="--blas_include_dirs=${CONDA_PREFIX}/include" \
       --install-option="--blas=openblas"
   

方案 B：使用 Pip 安装

如果您已经配置好了系统级的 PyTorch 和 CUDA 环境：

# 确保 torch 和 ninja 已安装
pip install torch ninja

# 安装 MinkowskiEngine
pip install -U MinkowskiEngine --install-option="--blas=openblas" -v --no-deps

如果安装失败，请尝试从最新源码安装：

export CUDA_HOME=/usr/local/cuda-11.1  # 请替换为您实际的 CUDA 路径
pip install -U git+https://github.com/NVIDIA/MinkowskiEngine -v --no-deps \
    --install-option="--force_cuda" \
    --install-option="--blas=openblas"

验证安装

运行以下命令检查是否安装成功：

python3 -c "import MinkowskiEngine; print(MinkowskiEngine.__version__)"

3. 基本使用

MinkowskiEngine 的核心是 SparseTensor。以下是构建一个简单的稀疏卷积网络的最小示例。

代码示例

import torch
import MinkowskiEngine as ME

# 1. 定义坐标和特征
# coords: [N, D] 整数坐标，例如 3D 空间为 [x, y, z]
coords = torch.IntTensor([
    [0, 0, 0],
    [1, 0, 0],
    [0, 1, 0],
    [1, 1, 0]
])

# feats: [N, C] 浮点数特征
feats = torch.rand(4, 16) 

# 2. 创建稀疏张量
# quantization_mode 用于处理重复坐标 (例如 'sum' 会将同一坐标的特征相加)
sparse_tensor = ME.SparseTensor(
    features=feats,
    coordinates=coords,
    quantization_mode=ME.SparseTensorQuantizationMode.UNIQUE
)

# 3. 定义稀疏卷积层
conv_layer = ME.MinkowskiConvolution(
    in_channels=16,
    out_channels=32,
    kernel_size=3,
    stride=1,
    dimension=3  # 指定空间维度，3 代表 3D
)

# 4. 前向传播
output_tensor = conv_layer(sparse_tensor)

print(f"输入稀疏张量形状: {sparse_tensor.shape}")
print(f"输出稀疏张量形状: {output_tensor.shape}")
print(f"输出特征维度: {output_tensor.features.shape}")

核心概念简述

• Coordinates: 稀疏数据的有效位置索引。
• Features: 对应位置上的数据值。
• Dimension: 构造层时必须指定数据的空间维度（如 2D 图像为 2，3D 点云为 3）。
• 量化 (Quantization): 当输入坐标有重复时，需要通过量化模式（如求和、平均）将其合并为唯一的稀疏坐标。