MinkowskiEngine
v0.5.4
Minkowski发动机是用于稀疏张量的自动分化库。它支持所有标准的神经网络层，例如稀疏张量的卷积，汇集，不冷冻和广播操作。有关更多信息，请访问文档页面。
Minkowski引擎支持可以在稀疏张量上构建的各种功能。我们在此处列出了一些流行的网络架构和应用程序。要运行示例，请安装软件包并在软件包root目录中运行命令。
| 例子 | 网络和命令 |
|---|---|
| 语义细分 | 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中实现的方式相同。
我们在下面的稀疏张量（卷积）上看到了稀疏的张量网络操作。稀疏张量上的卷积层与密度张量上的卷积层相似。但是，在稀疏张量上，我们在几个指定点上计算卷积输出，我们可以在广义卷积中控制。有关更多信息，请访问稀疏张量网络和术语页面上的文档页面。
| 密集张量 | 稀疏张量 |
|---|---|
conda install -y -c nvidia -c pytorch pytorch=1.8.1 cudatoolkit=10.2 ）您可以将Minkowski引擎与pip ，Anaconda或直接在系统上安装。如果您在安装软件包时遇到问题，请访问“安装Wiki”页面。如果找不到相关问题，请在GitHub问题页面上报告问题。
Minkowskiengine是通过PYPI Minkowskiengine分发的，可以简单地使用pip安装。首先，按照说明安装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
# For pip installation from the latest source
# pip install -U git+https://github.com/NVIDIA/MinkowskiEngine --no-deps
如果要为设置脚本指定参数，请参阅以下命令。
# Uncomment some options if things don't work
# export CXX=c++; # set this if you want to use a different C++ compiler
# export CUDA_HOME=/usr/local/cuda-11.1; # or select the correct cuda version on your system.
pip install -U git+https://github.com/NVIDIA/MinkowskiEngine -v --no-deps
# # uncomment the following line if you want to force cuda installation
# --install-option="--force_cuda"
# # uncomment the following line if you want to force no cuda installation. force_cuda supercedes cpu_only
# --install-option="--cpu_only"
# # uncomment the following line to override to openblas, atlas, mkl, blas
# --install-option="--blas=openblas"
Minkowskiengine支持CUDA 10.2和CUDA 11.1，它们适用于大多数最新的Pytorch版本。
我们建议python>=3.6进行安装。首先，请按照Anaconda文档在计算机上安装Anaconda。
sudo apt install g++-7 # For CUDA 10.2, must use GCC < 8
# Make sure `g++-7 --version` is at least 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
# Install MinkowskiEngine
export CXX=g++-7
# Uncomment the following line to specify the cuda home. Make sure `$CUDA_HOME/nvcc --version` is 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"
# Or if you want local 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
我们建议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
# Install MinkowskiEngine
# Uncomment the following line to specify the cuda home. Make sure `$CUDA_HOME/nvcc --version` is 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"
# Or if you want local MinkowskiEngine
git clone https://github.com/NVIDIA/MinkowskiEngine.git
cd MinkowskiEngine
python setup.py install --blas_include_dirs=${CONDA_PREFIX}/include --blas=openblas
与Anaconda安装一样，请确保您安装了与nvcc使用的CUDA版本相同的Pytorch。
# install system requirements
sudo apt install build-essential python3-dev libopenblas-dev
# Skip if you already have pip installed on your python3
curl https://bootstrap.pypa.io/get-pip.py | python3
# Get pip and install python requirements
python3 -m pip install torch numpy ninja
git clone https://github.com/NVIDIA/MinkowskiEngine.git
cd MinkowskiEngine
python setup.py install
# To specify blas, CXX, CUDA_HOME and force CUDA installation, use the following command
# export CXX=c++; export CUDA_HOME=/usr/local/cuda-11.1; python setup.py install --blas=openblas --force_cuda
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__)"
Minkowski Engine仅支持CPU建立在没有NVIDIA GPU的其他平台上。请参阅快速开始以获取更多详细信息。
要使用Minkowski引擎，您首先需要导入引擎。然后，您需要定义网络。如果未量化数据，则需要将（空间）数据量化或量化为稀疏张量。幸运的是，Minkowski引擎提供了量化功能（ 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 ) # loss and network
criterion = nn . CrossEntropyLoss ()
net = ExampleNetwork ( in_feat = 3 , out_feat = 5 , D = 2 )
print ( net )
# a data loader must return a tuple of coords, features, and labels.
coords , feat , label = data_loader ()
input = ME . SparseTensor ( feat , coordinates = coords )
# Forward
output = net ( input )
# Loss
loss = criterion ( output . F , label )有关讨论和问题，请使用[email protected] 。有关API和一般用法，请参阅Minkowskiengine文档页面以获取更多详细信息。
对于未在API上列出的问题和功能请求，请随时在GitHub问题页面上提交问题。
在某些情况下，您需要明确指定您使用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_cudaCUDA 10的推力有一个已知的问题，导致无与伦比的推力例外。请参阅该问题以获取详细信息。
此错误有一些原因。
Minkowskiengine是一个专业的库，可以在训练过程中处理不同数量的点或不同数量的非零元素，这在Point Cloud数据中很常见。但是，假设在每次迭代时都不会改变激活的点数或大小，则实现了Pytorch。因此，Pytorch使用的GPU内存缓存可能会导致不必要的大型内存消耗。
具体而言，Pytorch缓存了大量的存储空间，以加快每个张量创建中使用的分配。如果它无法找到内存空间，则如果没有足够大的缓存内存，则可以分配现有的缓存内存或分配新空间。因此，每当我们使用pytorch使用不同数量的点（非零元素的数量）时，它要么将现有缓存或保留新内存拆分。如果缓存太碎片并分配了所有GPU空间，则将出现在内存错误中。
为了防止这种情况，您必须用torch.cuda.empty_cache()定期清除缓存。
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
# Install MinkowskiEngine with CUDA 11.1
export CUDA_HOME=/usr/local/cuda-11.1; pip install MinkowskiEngine -v --no-deps
Minkowskiengine使用OpenMP并行化内核图的生成。但是，当用于并行化的线程数太大（例如OMP_NUM_THREADS = 80）时，效率会迅速下降，因为所有线程都只是等待释放多线程锁。在这种情况下，设置用于OpenMP的线程数。通常，低于24的任何数字都可以，但是在系统上搜索最佳设置。
export OMP_NUM_THREADS=<number of threads to use>; python <your_program.py>
如果您使用Minkowski引擎，请引用：
@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}
}
对于Unitests和Gradcheck，请使用Torch> = 1.7
请随时更新Wiki页面以添加您的项目！
使用Minkowskiengine的项目
细分：3D和4D时空语义分段，CVPR'19
表示学习：完全卷积的几何特征，ICCV'19
3D注册：学习多览3D点云注册，CVPR'20
3D注册：深度全球注册，CVPR'20
模式识别：用于几何模式识别的高维卷积网络，CVPR'20
检测：用于3D单光对象检测的生成稀疏检测网络，ECCV'20
图像匹配：稀疏社区共识网络，ECCV'20
