kpconv_blocks

Kernel point convolution, its kernel point placement, and the normalized and residual blocks built on it.

Classes:

KPConv –

Kernel point convolution over a neighborhood graph.
KPConvBlock –

Kernel point convolution followed by normalization and activation.
KPResidualBlock –

Bottleneck residual block: a channel-reducing MLP, a KPConvBlock, and a channel-restoring MLP.

Functions:

create_kernel_points –

Builds the kernel point positions of a KPConv kernel, randomly rotated and jittered.

KPConv [source] ¶

KPConv(
    spatial_dim: int,
    in_channels: int,
    out_channels: int,
    kernel_size: int,
    kp_radius: float,
    kp_sigma: float,
    kp_influence: str = "linear",
    fixed_position: Literal[
        "none", "center", "vertical"
    ] = "center",
    aggregation_mode: str = "sum",
    deformable: bool = False,
    modulated: bool = False,
    bias: bool = False,
    track_running_stats: bool = True,
)

Bases: MessagePassing

Kernel point convolution over a neighborhood graph.

Each of the \(K\) kernel points carries its own weight matrix, and a neighbor contributes to a kernel point with a weight given by their distance through the influence function. When deformable is set, a nested KPConv predicts a per-point offset for every kernel point.

edge_index lists [source, target] pairs: messages flow from the support (source) points to the query (target) points, and a bipartite graph is given as a (pos_source, pos_target) pair of positions.

The message is the \((E, K)\) influence of every kernel point on every edge; the aggregation pools the neighbor features per kernel point and only then applies that kernel point's weight matrix, so the \(K\) matrix products run over the \(N_t\) target points rather than over the \(E\) edges: the neighborhoods are laid out as a padded \((N_t, k)\) table and the pooling is one batched matrix product over it.

Parameters:

spatial_dim (int) –

Spatial dimension of the input point cloud.
in_channels (int) –

Number of input channels.
out_channels (int) –

Number of output channels.
kernel_size (int) –

Number of kernel points \(K\).
kp_radius (float) –

Radius of the sphere the kernel points are placed on.
kp_sigma (float) –

Kernel extent, the distance over which a kernel point still influences a neighbor.
kp_influence (str, default: 'linear' ) –

Influence function: "constant", "linear", or "gaussian".
fixed_position (Literal['none', 'center', 'vertical'], default: 'center' ) –

Which kernel point is pinned: "none", "center", or "vertical".
aggregation_mode (str, default: 'sum' ) –

"sum" over all kernel points, or "closest" to keep only the nearest one.
deformable (bool, default: False ) –

Whether to predict per-point kernel offsets.
modulated (bool, default: False ) –

Whether the deformable branch also predicts a per-kernel-point modulation.
bias (bool, default: False ) –

Whether to add a bias to the output.
track_running_stats (bool, default: True ) –

Whether to keep the deformable statistics of the last forward pass (running_min_d2, running_deformed_kernel, running_offset_features) for losses.kpconv_deform_regularizer.

Shape

Input: \((N_s, C_\text{in})\) features, \((N, D)\) positions or a \(((N_s, D), (N_t, D))\) pair, \((2, E)\) edge index Output: \((N_t, C_\text{out})\) features

Methods:

configure_offsets –

Builds the rigid KPConv and the bias predicting the deformable offsets (and modulations).
configure_kernel –

Builds the fixed kernel point positions registered as the kernel buffer.

Attributes:

deformable (bool) –

Whether the kernel points are shifted by predicted per-point offsets.

deformable `property` ¶

deformable: bool

Whether the kernel points are shifted by predicted per-point offsets.

configure_offsets [source] ¶

configure_offsets() -> Tuple[Module, Parameter]

Builds the rigid KPConv and the bias predicting the deformable offsets (and modulations).

configure_kernel [source] ¶

configure_kernel() -> Tensor

Builds the fixed kernel point positions registered as the kernel buffer.

KPConvBlock [source] ¶

KPConvBlock(
    spatial_dim: int,
    in_channels: int,
    out_channels: int,
    kernel_size: int,
    kp_radius: float,
    kp_sigma: float,
    kp_influence: str = "linear",
    fixed_position: Literal[
        "none", "center", "vertical"
    ] = "center",
    aggregation_mode: str = "sum",
    deformable: bool = False,
    modulated: bool = False,
    act: Union[str, Callable, None] = "leaky_relu",
    act_kwargs: Optional[Dict[str, Any]] = None,
    norm: Union[str, Callable, None] = "batch_norm",
    norm_kwargs: Optional[Dict[str, Any]] = None,
    bias: bool = False,
)

Bases: Module

Kernel point convolution followed by normalization and activation.

KPResidualBlock [source] ¶

KPResidualBlock(
    spatial_dim: int,
    in_channels: int,
    out_channels: int,
    kernel_size: int,
    kp_radius: float,
    kp_sigma: float,
    kp_influence: str = "linear",
    fixed_position: Literal[
        "none", "center", "vertical"
    ] = "center",
    aggregation_mode: str = "sum",
    deformable: bool = False,
    modulated: bool = False,
    strided: bool = False,
    act: Union[str, Callable, None] = "leaky_relu",
    act_kwargs: Optional[Dict[str, Any]] = None,
    act_first: bool = False,
    norm: Union[str, Callable, None] = "batch_norm",
    norm_kwargs: Optional[Dict[str, Any]] = None,
    bias: bool = False,
)

Bases: Module

Bottleneck residual block: a channel-reducing MLP, a KPConvBlock, and a channel-restoring MLP.

Set strided=True when the block maps a support cloud onto a coarser query cloud, so that the skip connection is max-pooled over the same neighborhoods.

create_kernel_points [source] ¶

create_kernel_points(
    radius: float,
    num_points: int,
    fixed_position: Literal[
        "none", "center", "vertical"
    ] = "center",
    method: Literal["lloyd", "gradient"] = "lloyd",
) -> Tensor

Builds the kernel point positions of a KPConv kernel, randomly rotated and jittered.

Positions are optimized on the unit sphere, cached under CACHE_DIR and reused across calls.

Parameters:

radius (float) –

Radius of the sphere the kernel points are scaled to.
num_points (int) –

Number of kernel points \(K\).
fixed_position (Literal['none', 'center', 'vertical'], default: 'center' ) –

Which kernel point is pinned: "none", "center", or "vertical".
method (Literal['lloyd', 'gradient'], default: 'lloyd' ) –

Optimization used to spread the points, either "lloyd" or "gradient".

Returns:

Tensor –

Kernel point positions of shape \((K, 3)\).