实用函数和类¶

sparse_quantize¶

MinkowskiEngine.utils.sparse_quantize(coordinates, features=None, labels=None, ignore_label=- 100, return_index=False, return_inverse=False, return_maps_only=False, quantization_size=None, device='cpu')¶

给定坐标和特征（可选标签），该函数生成量化的（体素化的）坐标。

参数

coordinates (numpy.ndarray 或 torch.Tensor)：大小为 \(N \times D\) 的矩阵，其中 \(N\) 是 \(D\) 维空间中的点数。

features (numpy.ndarray 或 torch.Tensor, 可选)：大小为 \(N \times D_F\) 的矩阵，其中 \(N\) 是点数，\(D_F\) 是特征的维度。必须与 coords 具有相同的容器（即，如果 coords 是 torch.Tensor，则 feats 也必须是 torch.Tensor）。

labels (numpy.ndarray 或 torch.IntTensor, 可选)：与每个坐标关联的整数标签。必须与 coords 具有相同的容器（即，如果 coords 是 torch.Tensor，则 labels 也必须是 torch.Tensor）。对于将一组点映射到一个标签的分类，请不要提供标签。

ignore_label (int, 可选)：IGNORE LABEL 的 int 值。 torch.nn.CrossEntropyLoss(ignore_index=ignore_label)

return_index (bool, 可选)：如果要量化坐标的索引，请设置为 True。默认为 False。

return_inverse (bool, 可选)：如果要用于恢复离散原始坐标的索引，请设置为 True。默认为 False。当 return_reverse 为 True 时，return_index 必须为 True。

return_maps_only (bool, 可选)：如果设置，则返回 unique_map 或可选的逆映射，但不返回坐标。如果您不关心最终坐标，或者如果您使用 device==cuda 并且不需要 GPU 上的坐标，则可以使用。如果设置了 return_inverse，则返回单独的 unique_map 或（unique_map，inverse_map）。

quantization_size (attr:float, 可选)：如果设置，将使用量化大小来定义坐标之间的最小距离。

device (attr:str, 可选)：‘cpu’ 或 ‘cuda’。

示例
>>> unique_map, inverse_map = sparse_quantize(discrete_coords, return_index=True, return_inverse=True)
>>> unique_coords = discrete_coords[unique_map]
>>> print(unique_coords[inverse_map] == discrete_coords)  # True
quantization_size (float, list, 或 numpy.ndarray, 可选)：网格单元的超矩形每条边的长度。

示例

>>> # Segmentation
>>> criterion = torch.nn.CrossEntropyLoss(ignore_index=-100)
>>> coords, feats, labels = MinkowskiEngine.utils.sparse_quantize(
>>>     coords, feats, labels, ignore_label=-100, quantization_size=0.1)
>>> output = net(MinkowskiEngine.SparseTensor(feats, coords))
>>> loss = criterion(output.F, labels.long())
>>>
>>> # Classification
>>> criterion = torch.nn.CrossEntropyLoss(ignore_index=-100)
>>> coords, feats = MinkowskiEngine.utils.sparse_quantize(coords, feats)
>>> output = net(MinkowskiEngine.SparseTensor(feats, coords))
>>> loss = criterion(output.F, labels.long())

batched_coordinates¶

MinkowskiEngine.utils.batched_coordinates(coords, dtype=torch.int32, device=None)¶

从坐标序列创建 ME.SparseTensor 坐标

给定 numpy 或 pytorch 张量坐标列表，返回适合 ME.SparseTensor 的批量坐标。

参数

coords (一组 torch.Tensor 或 numpy.ndarray)：坐标列表。

dtype：返回张量的 torch 数据类型。默认为 torch.int32。

返回

batched_coordindates (torch.Tensor)：批量坐标。

警告

从 v0.4 开始，批次索引将位于所有坐标之前。

sparse_collate¶

MinkowskiEngine.utils.sparse_collate(coords, feats, labels=None, dtype=torch.int32, device=None)¶

为稀疏张量创建输入参数文档。

将一组坐标和特征转换为批处理坐标和批处理特征。

参数

coords (一组 torch.Tensor 或 numpy.ndarray)：一组坐标。

feats (一组 torch.Tensor 或 numpy.ndarray)：一组特征。

labels (一组 torch.Tensor 或 numpy.ndarray)：与输入关联的一组标签。

batch_sparse_collate¶

MinkowskiEngine.utils.batch_sparse_collate(data, dtype=torch.int32, device=None)¶

该包装函数可以与 torch.utils.data.DataLoader 结合使用，以生成稀疏张量的输入。

请参考训练示例以了解用法。

参数: data：(坐标、特征、标签) 元组的列表。

cat¶

MinkowskiEngine.cat(*sparse_tensors)¶

连接稀疏张量

连接稀疏张量特征。所有稀疏张量必须具有相同的 coordinate_map_key（相同的坐标）。要连接具有不同稀疏模式的稀疏张量，请使用 SparseTensor 二进制运算，或 MinkowskiEngine.MinkowskiUnion。

示例

>>> import MinkowskiEngine as ME
>>> sin = ME.SparseTensor(feats, coords)
>>> sin2 = ME.SparseTensor(feats2, coordinate_map_key=sin.coordinate_map_key, coordinate_mananger=sin.coordinate_manager)
>>> sout = UNet(sin)  # Returns an output sparse tensor on the same coordinates
>>> sout2 = ME.cat(sin, sin2, sout)  # Can concatenate multiple sparse tensors

to_sparse¶

MinkowskiEngine.to_sparse(x: torch.Tensor, format: Optional[str] = None, coordinates=None, device=None)¶

将批处理张量（维度 0 是批处理维度）转换为 SparseTensor

x (torch.Tensor): 一个批处理张量。第一个维度是批处理维度。

format (str): 张量的格式。它必须包含 ‘B’ 和 ‘C’，分别表示批处理和通道维度。其余维度必须是 ‘X’。例如，如果使用 BCHW 格式的图像数据，则 format=”BCXX”。如果 3D 数据的通道位于最后一个维度，请使用 format=”BXXXC”，表示批处理 X 高度 X 宽度 X 深度 X 通道。如果未提供，格式将为“BCX…X”。

device: 将在其上生成稀疏张量的设备。如果未提供，将使用输入张量的设备。

to_sparse_all¶

MinkowskiEngine.to_sparse_all(dense_tensor: torch.Tensor, coordinates: Optional[torch.Tensor] = None)¶

将（可微分的）密集张量转换为具有所有坐标的稀疏张量。

假设输入为 BxCxD1xD2x….xDN 格式。

如果张量的形状没有改变，请使用 dense_coordinates 来缓存坐标。请参考 tests/python/dense.py 获取用法

示例

>>> dense_tensor = torch.rand(3, 4, 5, 6, 7, 8)  # BxCxD1xD2xD3xD4
>>> dense_tensor.requires_grad = True
>>> stensor = to_sparse(dense_tensor)

SparseCollation¶

class MinkowskiEngine.utils.SparseCollation(limit_numpoints=- 1, dtype=torch.int32, device=None)¶

为坐标、特征、标签生成排序函数。

请参考训练示例以了解用法。

参数: limit_numpoints (int): 如果是正整数，则限制批处理大小，以使输入坐标的数量低于 limit_numpoints。如果是 0 或 False，则连接所有点。默认为 -1。

示例

>>> data_loader = torch.utils.data.DataLoader(
>>>     dataset,
>>>     ...,
>>>     collate_fn=SparseCollation())
>>> for d in iter(data_loader):
>>>     print(d)

__init__(limit_numpoints=- 1, dtype=torch.int32, device=None)¶: 初始化 self。有关准确的签名，请参见 help(type(self))。

MinkowskiToSparseTensor¶

class MinkowskiEngine.MinkowskiToSparseTensor(remove_zeros=True, coordinates: Optional[torch.Tensor] = None)¶

将（可微分的）密集张量或 MinkowskiEngine.TensorField 转换为 MinkowskiEngine.SparseTensor。

对于密集张量，输入必须具有 BxCxD1xD2x….xDN 格式。

remove_zeros (bool): 如果为 True，则删除零值坐标。如果为 False，则使用所有坐标来填充稀疏张量。默认为 True。

如果张量的形状没有改变，请使用 dense_coordinates 来缓存坐标。请参考 tests/python/dense.py 获取用法。

示例

>>> # Differentiable dense torch.Tensor to sparse tensor.
>>> dense_tensor = torch.rand(3, 4, 11, 11, 11, 11)  # BxCxD1xD2x....xDN
>>> dense_tensor.requires_grad = True

>>> # Since the shape is fixed, cache the coordinates for faster inference
>>> coordinates = dense_coordinates(dense_tensor.shape)

>>> network = nn.Sequential(
>>>     # Add layers that can be applied on a regular pytorch tensor
>>>     nn.ReLU(),
>>>     MinkowskiToSparseTensor(remove_zeros=False, coordinates=coordinates),
>>>     MinkowskiConvolution(4, 5, kernel_size=3, dimension=4),
>>>     MinkowskiBatchNorm(5),
>>>     MinkowskiReLU(),
>>> )

>>> for i in range(5):
>>>   print(f"Iteration: {i}")
>>>   soutput = network(dense_tensor)
>>>   soutput.F.sum().backward()
>>>   soutput.dense(shape=dense_tensor.shape)

__init__(remove_zeros=True, coordinates: Optional[torch.Tensor] = None)¶: 初始化内部模块状态，由 nn.Module 和 ScriptModule 共享。

MinkowskiToDenseTensor¶

class MinkowskiEngine.MinkowskiToDenseTensor(shape: Optional[torch.Size] = None)¶

将（可微分的）稀疏张量转换为 torch 张量。

返回类型具有 BxCxD1xD2x….xDN 格式。

示例

>>> dense_tensor = torch.rand(3, 4, 11, 11, 11, 11)  # BxCxD1xD2x....xDN
>>> dense_tensor.requires_grad = True

>>> # Since the shape is fixed, cache the coordinates for faster inference
>>> coordinates = dense_coordinates(dense_tensor.shape)

>>> network = nn.Sequential(
>>>     # Add layers that can be applied on a regular pytorch tensor
>>>     nn.ReLU(),
>>>     MinkowskiToSparseTensor(coordinates=coordinates),
>>>     MinkowskiConvolution(4, 5, stride=2, kernel_size=3, dimension=4),
>>>     MinkowskiBatchNorm(5),
>>>     MinkowskiReLU(),
>>>     MinkowskiConvolutionTranspose(5, 6, stride=2, kernel_size=3, dimension=4),
>>>     MinkowskiToDenseTensor(
>>>         dense_tensor.shape
>>>     ),  # must have the same tensor stride.
>>> )

>>> for i in range(5):
>>>     print(f"Iteration: {i}")
>>>     output = network(dense_tensor) # returns a regular pytorch tensor
>>>     output.sum().backward()

__init__(shape: Optional[torch.Size] = None)¶: 初始化内部模块状态，由 nn.Module 和 ScriptModule 共享。

MinkowskiToFeature¶

class MinkowskiEngine.MinkowskiToFeature¶

从稀疏张量中提取特征并返回一个 pytorch 张量。

可以用于简化网络构建。

示例

>>> net = nn.Sequential(MinkowskiConvolution(...), MinkowskiGlobalMaxPooling(...), MinkowskiToFeature(), nn.Linear(...))
>>> torch_tensor = net(sparse_tensor)

__init__()¶: 初始化内部模块状态，由 nn.Module 和 ScriptModule 共享。

MinkowskiStackCat¶

class MinkowskiEngine.MinkowskiStackCat(*args: torch.nn.modules.module.Module)¶

class MinkowskiEngine.MinkowskiStackCat(arg: OrderedDict[str, Module])

__init__(*args: Any)¶: 初始化内部模块状态，由 nn.Module 和 ScriptModule 共享。

forward(x)¶

定义每次调用时执行的计算。

应被所有子类重写。

注意

尽管 forward pass 的配方需要在该函数中定义，但应该在之后调用 Module 实例而不是此函数，因为前者负责运行注册的钩子，而后者会静默地忽略它们。

MinkowskiStackSum¶

class MinkowskiEngine.MinkowskiStackSum(*args: torch.nn.modules.module.Module)¶

class MinkowskiEngine.MinkowskiStackSum(arg: OrderedDict[str, Module])

__init__(*args: Any)¶: 初始化内部模块状态，由 nn.Module 和 ScriptModule 共享。

forward(x)¶

定义每次调用时执行的计算。

应被所有子类重写。

注意

尽管 forward pass 的配方需要在该函数中定义，但应该在之后调用 Module 实例而不是此函数，因为前者负责运行注册的钩子，而后者会静默地忽略它们。

MinkowskiStackMean¶

class MinkowskiEngine.MinkowskiStackMean(*args: torch.nn.modules.module.Module)¶

class MinkowskiEngine.MinkowskiStackMean(arg: OrderedDict[str, Module])

__init__(*args: Any)¶: 初始化内部模块状态，由 nn.Module 和 ScriptModule 共享。

forward(x)¶

定义每次调用时执行的计算。

应被所有子类重写。

注意

尽管 forward pass 的配方需要在该函数中定义，但应该在之后调用 Module 实例而不是此函数，因为前者负责运行注册的钩子，而后者会静默地忽略它们。

MinkowskiStackVar¶

class MinkowskiEngine.MinkowskiStackVar(*args: torch.nn.modules.module.Module)¶

class MinkowskiEngine.MinkowskiStackVar(arg: OrderedDict[str, Module])

__init__(*args: Any)¶: 初始化内部模块状态，由 nn.Module 和 ScriptModule 共享。

forward(x)¶

定义每次调用时执行的计算。

应被所有子类重写。

注意

尽管 forward pass 的配方需要在该函数中定义，但应该在之后调用 Module 实例而不是此函数，因为前者负责运行注册的钩子，而后者会静默地忽略它们。