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
