MinkowskiEngine
v0.5.4
Minkowskiエンジンは、まばらなテンソル用の自動分化ライブラリです。まばらなテンソル用の畳み込み、プーリング、解放、放送操作など、すべての標準的なニューラルネットワークレイヤーをサポートします。詳細については、ドキュメントページをご覧ください。
Minkowskiエンジンは、まばらなテンソル上に構築できるさまざまな機能をサポートしています。ここには、いくつかの一般的なネットワークアーキテクチャとアプリケーションをリストします。例を実行するには、パッケージをインストールし、パッケージルートディレクトリでコマンドを実行してください。
| 例 | ネットワークとコマンド |
|---|---|
| セマンティックセグメンテーション | python -m examples.indoor |
| 分類 | python -m examples.classification_modelnet40 |
| 再建 | python -m examples.reconstruction |
| 完了 | python -m examples.completion |
| 検出 |
ニューラルネットワークを圧縮して推論を高速化し、メモリフットプリントを最小化しています。モデル圧縮の一般的な手法の1つは、コンベネットの重みを剪定することです。これは、スパース畳み込みネットワークとしても知られています。モデル圧縮に使用されるこのようなパラメーター空間のスパースは、密なテンソルで動作するネットワークとこれらのネットワークのすべての中間活性化も密なテンソルです。
ただし、この作業では、Siggraph'17で最初に提案された3Dオブジェクトの表面における空間的にスパースの高次元入力と3Dデータと畳み込みと畳み込みに焦点を当てています。また、これらのデータをまばらなテンソルとして表すこともできます。これらのまばらなテンソルは、3D認識、登録、統計データなどの高次元の問題では一般的です。これらの入力に特化したニューラルネットワークをまばらなテンソルネットワークとして定義し、これらのスパーステンソルネットワークプロセスをプロセスし、出力としてスパーステンソルを生成します。スパーステンソルネットワークを構築するために、MLP、非線形性、畳み込み、正規化、プーリング操作などのすべての標準的なニューラルネットワークレイヤーを、密なテンソルで定義し、Minkowskiエンジンで実装するのと同じ方法として構築します。
以下のまばらなテンソル、畳み込み上のスパーステンソルネットワーク操作を視覚化しました。スパーステンソル上の畳み込み層は、密なテンソル上の畳み込み層と同様に機能します。ただし、まばらなテンソルでは、一般化された畳み込みで制御できるいくつかの指定されたポイントで畳み込み出力を計算します。詳細については、スパーステンソルネットワークのドキュメントページと用語ページをご覧ください。
| 密なテンソル | まばらなテンソル |
|---|---|
conda install -y -c nvidia -c pytorch pytorch=1.8.1 cudatoolkit=10.2 ）Minkowskiエンジンをpip 、Anaconda、またはシステムに直接インストールできます。パッケージのインストールに問題がある場合は、インストールWikiページをチェックアウトしてください。関連する問題が見つからない場合は、GitHub Issueページで問題を報告してください。
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の両方をサポートしています。
インストールには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エンジンは、NVIDIA GPUを持たない他のプラットフォーム上でのみCPUをサポートしています。詳細については、クイックスタートを参照してください。
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 Issueページで問題を送信してください。
場合によっては、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は、トレーニング中のすべての反復で異なる数のポイントまたは異なる数の非ゼロ要素を処理できる専門のライブラリであり、ポイントクラウドデータで一般的です。ただし、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}
}
UnittestsおよびGradCheckについては、Torch> = 1.7を使用します
Wikiページを更新してプロジェクトを追加してください！
Minkowskiengineを使用したプロジェクト
セグメンテーション：3Dおよび4D時空間セマンティックセグメンテーション、CVPR'19
表現学習：完全に畳み込みの幾何学的特徴、ICCV'19
3D登録：MultiView 3Dポイントクラウド登録の学習、CVPR'20
3D登録：深いグローバル登録、CVPR'20
パターン認識：幾何学的パターン認識のための高次元畳み込みネットワーク、CVPR'20
検出：3Dシングルショットオブジェクト検出のための生成スパース検出ネットワーク、ECCV'20
画像のマッチング：まばらな近隣コンセンサスネットワーク、ECCV'20
