TorchSparse 1.1 : 概要 (README) (翻訳/解説)
翻訳 : (株)クラスキャット セールスインフォメーション
作成日時 : 03/19/2021 (1.1.0)

* 本ページは、TorchSparse 1.1 の以下のページを翻訳した上で適宜、補足説明したものです：

• README.md

* サンプルコードの動作確認はしておりますが、必要な場合には適宜、追加改変しています。
* ご自由にリンクを張って頂いてかまいませんが、sales-info@classcat.com までご一報いただけると嬉しいです。

TorchSparse 1.1 : 概要 (README)

ニュース

• 2020/09/20: We released torchsparse v1.1, which is significantly faster than our torchsparse v1.0 and is also achieves 1.9x speedup over MinkowskiEngine v0.5 alpha when running MinkUNet18C!

• 2020/08/30: We released torchsparse v1.0.

概要

torchsparse をリリースしました、効率的な 3D スパース convolution のための高性能計算ライブラリです。このライブラリは 3D のスパース計算を高速化することを目的にしています、特にスパース Convolution 演算です。

このライブラリの主要な優位点は GPU 上の総ての計算をサポートすることです、特に特にカーネルマップ構築です (これは最新の MinkowskiEngine V0.4.3 で CPU 上で成されます)。

インストール

torchsparse をインストールするために次のコマンドを実行して良いです。

pip install --upgrade git+https://github.com/mit-han-lab/torchsparse.git

このライブラリは Google の スパース・ハッシュマップ・プロジェクト に依拠していることに注意してください。このライブラリをインストールするには、次を実行して良いです :

sudo apt-get install libsparsehash-dev

on Ubuntu servers. If you are not sudo, please clone Google’s codebase, compile it and install locally. Finally, add the path to this library to your CPLUS_INCLUDE_PATH environmental variable.

For GPU server users, we currently support PyTorch 1.6.0 + CUDA 10.2 + CUDNN 7.6.2. For CPU users, we support PyTorch 1.6.0 (CPU version), MKLDNN backend is optional.

使用方法

SPVNAS プロジェクト (ECCV2020) は torchsparse で構築されています。このプロジェクトにナビゲートして遊ぶためにそのコードベースの手順に従っても良いです。

ここでは、torchsparse の幾つかの重要な概念上のウォークスルーも提供します。

スパース Tensor とポイント Tensor

torchsparse では、ポイントクラウド・ストレージのための 2 つのデータ構造を持ちます、つまり torchsparse.SparseTensor と torchsparse.PointTensor です。両者の構造は 2 つのデータフィールド C (座標 – coordinates) と F (特徴 – features) を持ちます
SparseTensor では、総ての座標は 整数 で 重複しない ことを仮定しています。けれども、PointTensor では、総ての座標は 浮動小数点 で重複可能です。

スパース量子化 (= Quantize) とスパース Collate (照合)

スパース畳込み or スパース Point-Voxel 畳込みで構築されたネットワークにより消費できるようにポイントクラウドを SparseTensor に変換する方法は関数 torchsparse.utils.sparse_quantize を使用することです。ここでサンプルは次により与えられます :

inds, labels, inverse_map = sparse_quantize(pc, feat, labels, return_index=True, return_invs=True)

ここで pc, feat, labels はポイントクラウド (座標、整数であるべきです)、特徴と正解に対応します。inds はポイントクラウド座標の一意のインデックスを表し、そして inverse_map は各ポイントが対応する一意のインデックスです。inverse マップはダウンサンプリングされた予測から full ポイントクラウド予測をリストアするために使用されます。

SparseTensors のリストをバッチに連結するには、torchsparse.utils.sparse_collate_fn function を使用することを望むかもしれません。

詳細な結果は SPVNAS プロジェクトの SemanticKITTI データセット前処理コード で与えられます。

計算 API

torchspares の計算インターフェイスは簡単で元の PyTorch に非常に類似しています。ここでのサンプルは基本的な畳込みブロックを定義しています :

class BasicConvolutionBlock(nn.Module):
    def __init__(self, inc, outc, ks=3, stride=1, dilation=1):
        super().__init__()
        self.net = nn.Sequential(
            spnn.Conv3d(inc, outc, kernel_size=ks, dilation=dilation, stride=stride),
            spnn.BatchNorm(outc),
            spnn.ReLU(True)
        )

    def forward(self, x):
        out = self.net(x)
        return out

ここで spnn は torchsparse.nn を表し、そして spnn.Conv3d は 3D スパース畳込み演算を意味し、spnn.BatchNorm と spnn.ReLU はそれぞれ 3D スパース tensor バッチ正規化と活性を表します。torchsparse.nn.functional を通して direct 畳込みカーネルもサポートします、例えば :

outputs = torchsparse.nn.functional.conv3d(inputs, kernel, stride=1, dilation=1, transpose=False)

ここで inputs(SparseTensor), kernel (of shape k^3 x OC x IC when k > 1, or OC x IC when k = 1, ここで k はカーネルサイズを表しそして IC, OC は入力 / 出力チャネルを意味します) を定義する必要があります。出力は依然として SparseTensor です。

詳細なサンプルは ここ で与えられます、そこでは重み共有 3D-NAS モジュールを実装するために torchsparse.nn.functional インターフェイスを使用します。

スパース・ハッシュマップ API

スパース・ハッシュマップ query は 3D スパース計算で重要です。それはポイントのメモリ位置 (i.e. インデックス) をその座標が与えられたときに推論するために主として利用されます。例えば、この演算を 3D スパース畳込みのカーネルマップ構築パート、そして スパース Point-Voxel 畳込み のスパース voxelization / devoxelization で使用します。ここでは、ハッシュマップ API のために次のサンプルを提供します :

source_hash = torchsparse.nn.functional.sphash(torch.floor(source_coords).int())
target_hash = torchsparse.nn.functional.sphash(torch.floor(target_coords).int())
idx_query = torchsparse.nn.functional.sphashquery(source_hash, target_hash)

このサンプルでは、sphash は整数座標をハッシングに変換する関数です。sphashquery(source_hash, target_hash) はハッシュテーブル検索を遂行します。ここで、ハッシュマップはキー target_hash とターゲット・ポイントクラウド tensor のポイント・インデックスに対応する値を持ちます。source_coords の各ポイントに対して、それと同じ座標を持つ target_coords のポイントインデックスを見つけます。

ダミー訓練サンプル

ここ でダミー入力による訓練サンプル全体を提供します。このサンプルで以下をカバーします :

• どのようにポイントクラウド・データから始めてそれを SparseTensor 形式に変換するか ;
• どのように SparseTensor バッチ処理を実装でけいるか ;
• セマンティック・セグメンテーション SparseConvNet を訓練できるか。

You are also welcomed to check out our SPVNAS project to implement training / inference with real data.

以上