SparseTensor 和 TensorField¶

SparseTensor¶

class MinkowskiEngine.MinkowskiSparseTensor.SparseTensor(features: torch.Tensor, coordinates: Optional[torch.Tensor] = None, tensor_stride: Union[int, collections.abc.Sequence, numpy.ndarray, torch.IntTensor] = 1, coordinate_map_key: Optional[MinkowskiEngineBackend._C.CoordinateMapKey] = None, coordinate_manager: Optional[MinkowskiCoordinateManager.CoordinateManager] = None, quantization_mode: MinkowskiTensor.SparseTensorQuantizationMode = <SparseTensorQuantizationMode.RANDOM_SUBSAMPLE: 0>, allocator_type: Optional[MinkowskiEngineBackend._C.GPUMemoryAllocatorType] = None, minkowski_algorithm: Optional[MinkowskiEngineBackend._C.MinkowskiAlgorithm] = None, requires_grad=None, device=None)¶

一个稀疏张量类。可以通过 MinkowskiEngine.SparseTensor 访问。

SparseTensor 类是 MinkowskiEngine 中的基本张量。有关稀疏张量的定义，请访问术语页面。我们使用 COOrdinate (COO) 格式来保存稀疏张量 [1]。这种表示法只是将坐标连接成一个矩阵 \(C\) 和相关的特征 \(F\)。

\[\begin{split}\mathbf{C} = \begin{bmatrix} b_1 & x_1^1 & x_1^2 & \cdots & x_1^D \\ \vdots & \vdots & \vdots & \ddots & \vdots \\ b_N & x_N^1 & x_N^2 & \cdots & x_N^D \end{bmatrix}, \; \mathbf{F} = \begin{bmatrix} \mathbf{f}_1^T\\ \vdots\\ \mathbf{f}_N^T \end{bmatrix}\end{split}\]

其中 \(\mathbf{x}_i \in \mathcal{Z}^D\) 是一个 \(D\) 维坐标，\(b_i \in \mathcal{Z}_+\) 表示相应的批次索引。\(N\) 是稀疏张量中非零元素的数量，每个元素都有坐标 \((b_i, x_i^1, x_i^1, \cdots, x_i^D)\) 和相关的特征 \(\mathbf{f}_i\)。在内部，我们将批次索引作为额外的空间维度处理。

示例

>>> coords, feats = ME.utils.sparse_collate([coords_batch0, coords_batch1], [feats_batch0, feats_batch1])
>>> A = ME.SparseTensor(features=feats, coordinates=coords)
>>> B = ME.SparseTensor(features=feats, coordinate_map_key=A.coordiante_map_key, coordinate_manager=A.coordinate_manager)
>>> C = ME.SparseTensor(features=feats, coordinates=coords, quantization_mode=ME.SparseTensorQuantizationMode.UNWEIGHTED_AVERAGE)
>>> D = ME.SparseTensor(features=feats, coordinates=coords, quantization_mode=ME.SparseTensorQuantizationMode.RANDOM_SUBSAMPLE)
>>> E = ME.SparseTensor(features=feats, coordinates=coords, tensor_stride=2)

警告

要对坐标管理使用 GPU 后端，coordinates 必须是 GPU 上的 torch 张量。在使用 CPU coordinates 初始化 MinkowskiEngine.SparseTensor 之后应用 to(device) 将浪费时间和计算资源来创建一个不必要的 CPU CoordinateMap，因为 GPU CoordinateMap 也会从头开始创建。

警告

在 MinkowskiEngine 0.4 版本之前，我们将批次索引放在最后一列。因此，直接操作坐标将与最新版本不兼容。请改用 MinkowskiEngine.utils.batched_coordinates 或 MinkowskiEngine.utils.sparse_collate 来创建批处理坐标。

此外，要批量访问坐标或特征，请使用稀疏张量的函数 coordinates_at(batch_index : int)、features_at(batch_index : int)。或者要访问所有批处理坐标和特征，则使用稀疏张量的 decomposed_coordinates、decomposed_features、decomposed_coordinates_and_features。

示例

>>> coords, feats = ME.utils.sparse_collate([coords_batch0, coords_batch1], [feats_batch0, feats_batch1])
>>> A = ME.SparseTensor(feats=feats, coords=coords)
>>> coords_batch0 = A.coordinates_at(batch_index=0)
>>> feats_batch1 = A.features_at(batch_index=1)
>>> list_of_coords, list_of_featurs = A.decomposed_coordinates_and_features

__init__(features: torch.Tensor, coordinates: Optional[torch.Tensor] = None, tensor_stride: Union[int, collections.abc.Sequence, numpy.ndarray, torch.IntTensor] = 1, coordinate_map_key: Optional[MinkowskiEngineBackend._C.CoordinateMapKey] = None, coordinate_manager: Optional[MinkowskiCoordinateManager.CoordinateManager] = None, quantization_mode: MinkowskiTensor.SparseTensorQuantizationMode = <SparseTensorQuantizationMode.RANDOM_SUBSAMPLE: 0>, allocator_type: Optional[MinkowskiEngineBackend._C.GPUMemoryAllocatorType] = None, minkowski_algorithm: Optional[MinkowskiEngineBackend._C.MinkowskiAlgorithm] = None, requires_grad=None, device=None)¶

参数

features (torch.FloatTensor, torch.DoubleTensor, torch.cuda.FloatTensor, 或 torch.cuda.DoubleTensor)：稀疏张量的特征。

coordinates (torch.IntTensor)：与特征关联的坐标。如果未提供，则必须提供 coordinate_map_key。

tensor_stride (int, list, numpy.array, 或 tensor.Tensor)：当前稀疏张量的张量步长。默认值为 1。

coordinate_map_key (MinkowskiEngine.CoordinateMapKey)：当坐标已缓存在 MinkowskiEngine 中时，我们可以通过简单地提供坐标映射键来重用相同的坐标映射。在大多数情况下，此过程是自动完成的。如果您提供一个 coordinate_map_key，coordinates 将被忽略。

coordinate_manager (MinkowskiEngine.CoordinateManager)：MinkowskiEngine 使用 _C.CoordinateMapManager 管理所有坐标映射。如果未提供，则 MinkowskiEngine 将创建一个新的计算图。在大多数情况下，此过程是自动处理的，您无需使用它。

quantization_mode (MinkowskiEngine.SparseTensorQuantizationMode)：定义如何量化连续坐标以定义稀疏张量。有关详细信息，请参阅 SparseTensorQuantizationMode。

allocator_type (MinkowskiEngine.GPUMemoryAllocatorType)：定义 GPU 内存分配器类型。默认情况下，它使用 c10 分配器。

minkowski_algorithm (MinkowskiEngine.MinkowskiAlgorithm)：控制 minkowski 引擎的运行模式。如果要减少内存占用，请使用 MinkowskiAlgorithm.MEMORY_EFFICIENT。或者，如果您想以增加更多内存为代价使其运行得更快，请使用 MinkowskiAlgorithm.SPEED_OPTIMIZED。

requires_grad (bool)：设置 requires_grad 标志。

device (torch.device)：设置稀疏张量所在的设备。

cat_slice(X)¶

参数: X (MinkowskiEngine.SparseTensor)：离散化原始输入的稀疏张量。
返回: tensor_field (MinkowskiEngine.TensorField)：生成的张量场包含原始连续坐标上的特征连接，这些坐标生成了输入 X 和 self。

示例

>>> # coords, feats from a data loader
>>> print(len(coords))  # 227742
>>> sinput = ME.SparseTensor(coordinates=coords, features=feats, quantization_mode=SparseTensorQuantizationMode.UNWEIGHTED_AVERAGE)
>>> print(len(sinput))  # 161890 quantization results in fewer voxels
>>> soutput = network(sinput)
>>> print(len(soutput))  # 161890 Output with the same resolution
>>> ofield = soutput.cat_slice(sinput)
>>> assert soutput.F.size(1) + sinput.F.size(1) == ofield.F.size(1)  # concatenation of features

coordinate_map_key¶

dense(shape=None, min_coordinate=None, contract_stride=True)¶

将 MinkowskiEngine.SparseTensor 转换为 torch 稠密张量。

参数

shape (torch.Size, 可选)：输出张量的大小。

min_coordinate (torch.IntTensor, 可选)：输出稀疏张量的最小坐标。必须能被当前的 tensor_stride 整除。如果给定 0，则将使用原点作为最小坐标。

contract_stride (bool, 可选)：输出坐标将除以张量步长，以使特征在空间上连续。默认为 True。

返回

tensor (torch.Tensor)：大小为 [Batch Dim, Feature Dim, Spatial Dim…, Spatial Dim] 的 torch 张量。每个特征的坐标都可以通过 min_coordinate + tensor_stride * [稠密张量的坐标] 访问。

min_coordinate (torch.IntTensor)：定义输出张量的最小坐标的 D 维向量。

tensor_stride (torch.IntTensor)：定义张量元素之间步长的 D 维向量。

features_at_coordinates(query_coordinates: torch.Tensor)¶

提取指定连续坐标矩阵处的特征。

参数: query_coordinates (torch.FloatTensor)：大小为 \(N \times (D + 1)\) 的坐标矩阵，其中 \(D\) 是空间维度的大小。
返回: queried_features (torch.Tensor)：大小为 \(N \times D_F\) 的特征矩阵，其中 \(D_F\) 是特征中的通道数。对于当前稀疏张量中不存在的坐标，相应的特征行将为零。

initialize_coordinates(coordinates, features, coordinate_map_key)¶

inverse_mapping¶

quantization_mode¶

slice(X)¶

参数: X (MinkowskiEngine.SparseTensor)：离散化原始输入的稀疏张量。
返回: tensor_field (MinkowskiEngine.TensorField)：生成的张量场包含生成输入 X 的连续坐标上的特征。

示例

>>> # coords, feats from a data loader
>>> print(len(coords))  # 227742
>>> tfield = ME.TensorField(coordinates=coords, features=feats, quantization_mode=SparseTensorQuantizationMode.UNWEIGHTED_AVERAGE)
>>> print(len(tfield))  # 227742
>>> sinput = tfield.sparse() # 161890 quantization results in fewer voxels
>>> soutput = MinkUNet(sinput)
>>> print(len(soutput))  # 161890 Output with the same resolution
>>> ofield = soutput.slice(tfield)
>>> assert isinstance(ofield, ME.TensorField)
>>> len(ofield) == len(coords)  # recovers the original ordering and length
>>> assert isinstance(ofield.F, torch.Tensor)  # .F returns the features

sparse(min_coords=None, max_coords=None, contract_coords=True)¶

将 MinkowskiEngine.SparseTensor 转换为 torch 稀疏张量。

参数

min_coords (torch.IntTensor, 可选)：输出稀疏张量的最小坐标。必须能被当前的 tensor_stride 整除。

max_coords (torch.IntTensor, 可选)：输出稀疏张量的最大坐标（包括）。必须能被当前的 tensor_stride 整除。

contract_coords (bool, 可选)：如果为 True，则输出坐标将除以张量步长，以使特征连续。

返回

spare_tensor (torch.sparse.Tensor)： self 在 [Batch Dim, Spatial Dims…, Feature Dim] 中的 torch 稀疏张量表示。每个特征的坐标都可以通过 min_coord + tensor_stride * [稠密张量的坐标] 访问。

min_coords (torch.IntTensor)：定义输出稀疏张量的最小坐标的 D 维向量。如果 contract_coords 为 True，则 min_coords 也会被收缩。

tensor_stride (torch.IntTensor)：定义张量元素之间步长的 D 维向量。

unique_index¶

TensorField¶

class MinkowskiEngine.MinkowskiTensorField.TensorField(features: torch.Tensor, coordinates: Optional[torch.Tensor] = None, tensor_stride: Union[int, collections.abc.Sequence, numpy.ndarray, torch.IntTensor] = 1, coordinate_field_map_key: Optional[MinkowskiEngineBackend._C.CoordinateMapKey] = None, coordinate_manager: Optional[MinkowskiCoordinateManager.CoordinateManager] = None, quantization_mode: MinkowskiTensor.SparseTensorQuantizationMode = <SparseTensorQuantizationMode.UNWEIGHTED_AVERAGE: 1>, allocator_type: Optional[MinkowskiEngineBackend._C.GPUMemoryAllocatorType] = None, minkowski_algorithm: Optional[MinkowskiEngineBackend._C.MinkowskiAlgorithm] = None, requires_grad=None, device=None)¶

__init__(features: torch.Tensor, coordinates: Optional[torch.Tensor] = None, tensor_stride: Union[int, collections.abc.Sequence, numpy.ndarray, torch.IntTensor] = 1, coordinate_field_map_key: Optional[MinkowskiEngineBackend._C.CoordinateMapKey] = None, coordinate_manager: Optional[MinkowskiCoordinateManager.CoordinateManager] = None, quantization_mode: MinkowskiTensor.SparseTensorQuantizationMode = <SparseTensorQuantizationMode.UNWEIGHTED_AVERAGE: 1>, allocator_type: Optional[MinkowskiEngineBackend._C.GPUMemoryAllocatorType] = None, minkowski_algorithm: Optional[MinkowskiEngineBackend._C.MinkowskiAlgorithm] = None, requires_grad=None, device=None)¶

参数

features (torch.FloatTensor, torch.DoubleTensor, torch.cuda.FloatTensor, 或 torch.cuda.DoubleTensor)：稀疏张量的特征。

coordinates (torch.IntTensor)：与特征关联的坐标。如果未提供，则必须提供 coordinate_map_key。

tensor_stride (int, list, numpy.array, 或 tensor.Tensor)：当前稀疏张量的张量步长。默认值为 1。

coordinate_field_map_key (MinkowskiEngine.CoordinateMapKey)：当坐标已缓存在 MinkowskiEngine 中时，我们可以通过简单地提供坐标图键来重用相同的坐标图。在大多数情况下，此过程会自动完成。当您提供 coordinate_field_map_key 时，coordinates 将被忽略。

coordinate_manager (MinkowskiEngine.CoordinateManager)：MinkowskiEngine 使用 _C.CoordinateMapManager 管理所有坐标映射。如果未提供，则 MinkowskiEngine 将创建一个新的计算图。在大多数情况下，此过程是自动处理的，您无需使用它。

quantization_mode (MinkowskiEngine.SparseTensorQuantizationMode)：定义如何量化连续坐标以定义稀疏张量。有关详细信息，请参阅 SparseTensorQuantizationMode。

allocator_type (MinkowskiEngine.GPUMemoryAllocatorType)：定义 GPU 内存分配器类型。默认情况下，它使用 c10 分配器。

minkowski_algorithm (MinkowskiEngine.MinkowskiAlgorithm)：控制 minkowski 引擎的运行模式。如果要减少内存占用，请使用 MinkowskiAlgorithm.MEMORY_EFFICIENT。或者，如果您想以增加更多内存为代价使其运行得更快，请使用 MinkowskiAlgorithm.SPEED_OPTIMIZED。

requires_grad (bool)：设置 requires_grad 标志。

device (torch.device)：设置稀疏张量所在的设备。

property C¶: coords 的别名。

coordinate_field_map_key¶

property coordinates¶: 当前稀疏张量的坐标。这些坐标表示为 \(N \times (D + 1)\) 维矩阵，其中 \(N\) 是空间中点的数量，\(D\) 是空间的维度（例如，3 表示 3D，4 表示 3D + 时间）。矩阵 C 的列的附加维度用于批量索引，该索引在内部被视为附加空间维度，以分离批处理中不同的实例。

inverse_mapping(sparse_tensor_map_key: MinkowskiEngineBackend._C.CoordinateMapKey)¶

quantization_mode¶

sparse(tensor_stride: Union[int, collections.abc.Sequence, numpy.array] = 1, coordinate_map_key: Optional[MinkowskiEngineBackend._C.CoordinateMapKey] = None, quantization_mode=None)¶: 将当前稀疏张量场转换为稀疏张量。

SparseTensorOperationMode¶

class MinkowskiEngine.MinkowskiTensor.SparseTensorOperationMode(value)¶

SparseTensor 内部实例化模式的枚举类。

SEPARATE_COORDINATE_MANAGER: 始终创建新的坐标管理器。

SHARE_COORDINATE_MANAGER: 始终使用全局定义的坐标管理器。必须手动使用 MinkowskiEngine.SparseTensor.clear_global_coordinate_manager 清除坐标管理器。

SparseTensorQuantizationMode¶

class MinkowskiEngine.MinkowskiTensor.SparseTensorQuantizationMode(value)¶: RANDOM_SUBSAMPLE: 随机地对每个量化块抽取一个坐标。UNWEIGHTED_AVERAGE: 平均量化块内的所有特征。UNWEIGHTED_SUM: 对量化块内的所有特征求和。NO_QUANTIZATION: 不应用量化。不应在正常操作中使用。

set_sparse_tensor_operation_mode¶

MinkowskiEngine.MinkowskiTensor.set_sparse_tensor_operation_mode(operation_mode: MinkowskiEngine.MinkowskiTensor.SparseTensorOperationMode)¶

定义稀疏张量坐标管理器的操作模式。

默认情况下，MinkowskiEngine.SparseTensor.SparseTensor 实例化会创建一个新的坐标管理器，该管理器不与其他稀疏张量共享。通过使用 MinkowskiEngine.SparseTensorOperationMode.SHARE_COORDINATE_MANAGER 设置此函数，您可以与其他稀疏张量全局共享坐标管理器。但是，使用后必须显式清除坐标管理器。请参阅 MinkowskiEngine.clear_global_coordinate_manager。

参数: operation_mode (MinkowskiEngine.SparseTensorOperationMode): 稀疏张量坐标管理器的操作模式。默认为 MinkowskiEngine.SparseTensorOperationMode.SEPARATE_COORDINATE_MANAGER。

示例

>>> import MinkowskiEngine as ME
>>> ME.set_sparse_tensor_operation_mode(ME.SparseTensorOperationMode.SHARE_COORDINATE_MANAGER)
>>> ...
>>> a = ME.SparseTensor(...)
>>> b = ME.SparseTensor(...)  # coords_man shared
>>> ...  # one feed forward and backward
>>> ME.clear_global_coordinate_manager()  # Must use to clear the coordinates after one forward/backward

sparse_tensor_operation_mode¶

MinkowskiEngine.MinkowskiTensor.sparse_tensor_operation_mode() → MinkowskiEngine.MinkowskiTensor.SparseTensorOperationMode ¶: 返回当前稀疏张量操作模式。

global_coordinate_manager¶

MinkowskiEngine.MinkowskiTensor.global_coordinate_manager()¶: 返回当前全局坐标管理器

set_global_coordinate_manager¶

MinkowskiEngine.MinkowskiTensor.set_global_coordinate_manager(coordinate_manager)¶

设置全局坐标管理器。

MinkowskiEngine.CoordinateManager 将被设置为全局坐标管理器的坐标管理器。

clear_global_coordinate_manager¶

MinkowskiEngine.MinkowskiTensor.clear_global_coordinate_manager()¶

清除全局坐标管理器缓存。

当您使用以下操作模式时：MinkowskiEngine.SparseTensor.SparseTensorOperationMode.SHARE_COORDINATE_MANAGER，您必须在每次正向/反向传播后显式清除坐标管理器。