potential_sphere

Potential-driven sphere voting for large-scale point cloud segmentation.

The scene is covered by radius-defined spheres centered where the cloud has been seen the least, tracked by a coarse grid of potentials; each sphere's softmax predictions are blended into the running per-point scores by an exponential moving average until every region has been covered about num_votes times.

Classes:

PotentialSphereInferer –

Potential-driven sphere voting inferer for large-scale point cloud segmentation.

Functions:

potential_sphere_inference –

Potential-driven sphere voting for large-scale point cloud segmentation.

PotentialSphereInferer ¶

PotentialSphereInferer(
    radius: float,
    num_votes: float = 10.0,
    potential_size: Optional[float] = None,
    jitter: Optional[float] = None,
    inner_ratio: float = 0.7,
    ema_smoothing: float = 0.95,
    sw_batch_size: int = 1,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    pos_key: str = POS,
    batch_key: str = BATCH,
    progress: bool = False,
    seed: Optional[int] = None,
)

Bases: Inferer

Potential-driven sphere voting inferer for large-scale point cloud segmentation.

Covers the scene with radius-defined spheres centered where a coarse potential grid is lowest and blends each sphere's softmax predictions into the running per-point scores by an exponential moving average, until every region has been covered about num_votes times.

All parameters are forwarded verbatim to potential_sphere_inference.

Example

from torch_pointcloud.inferers import PotentialSphereInferer

inferer = PotentialSphereInferer(radius=1.5, num_votes=10.0)
probs = inferer(room, predictor=lambda d: model(d["x"], d["pos"], d["batch"]))

potential_sphere_inference ¶

potential_sphere_inference(
    data: Dict[str, Any],
    *,
    predictor: Callable[[Dict[str, Any]], Tensor],
    radius: float,
    num_votes: float = 10.0,
    potential_size: Optional[float] = None,
    jitter: Optional[float] = None,
    inner_ratio: float = 0.7,
    ema_smoothing: float = 0.95,
    sw_batch_size: int = 1,
    transform: Optional[
        Callable[[Dict[str, Any]], Dict[str, Any]]
    ] = None,
    pos_key: str = POS,
    batch_key: str = BATCH,
    progress: bool = False,
    seed: Optional[int] = None,
) -> Tensor

Potential-driven sphere voting for large-scale point cloud segmentation.

The scene is covered by spheres of radius \(r\) whose centers are chosen where the cloud has been seen the least: a coarse grid of potentials (one scalar per potential_size cell, initialized with a small random value) tracks coverage, each sphere is centered on the cell with the lowest potential (plus a Gaussian jitter) and raises the potentials of the cells it covers by the Tukey window \((1 - d^2 / r^2)^2\). The predictor runs on every sphere and its softmax probabilities are blended into the running per-point scores by an exponential moving average, restricted to the points within inner_ratio \(\cdot r\) of the center where the sphere's context is complete. The loop stops once every cell's potential reaches num_votes, so each region has been predicted about that many times.

This is the test protocol of KPConv (radius-defined input spheres, test_smooth EMA, potential sampling), and it composes with any model that consumes a packed sphere: the per-sphere transform sees the centered sphere dict and can add the reference's stochastic test-time augmentation and the model's feature stack. Points that no sphere reaches keep all-zero scores.

Parameters:

data (Dict[str, Any]) –

Dict of per-point tensors. Must contain pos (shape \((N, D)\)) and batch (shape \((N,)\)); extra per-point tensors are sliced to the active sphere automatically.
predictor (Callable[[Dict[str, Any]], Tensor]) –

Callable mapping a packed sphere dict to per-point logits of shape \((M, C)\).
radius (float) –

Sphere radius, in the units of pos.
num_votes (float, default: 10.0 ) –

Potential threshold ending the loop, i.e. the number of times every region is covered (KPConv reports its numbers at the first multiple of \(10\)).
potential_size (Optional[float], default: None ) –

Cell size of the coarse potential grid. Defaults to radius / 10.
jitter (Optional[float], default: None ) –

Standard deviation of the Gaussian jitter added to each sphere center, clipped at radius / 2. Defaults to radius / 10; 0 disables it.
inner_ratio (float, default: 0.7 ) –

Fraction of radius inside which the sphere's predictions are kept.
ema_smoothing (float, default: 0.95 ) –

EMA factor \(\alpha \in [0, 1)\) of the score update \(\text{new} = \alpha \cdot \text{old} + (1 - \alpha) \cdot \text{softmax}(\text{logits})\).
sw_batch_size (int, default: 1 ) –

Number of spheres packed into one predictor call. Centers are still drawn one at a time with the potentials updated in between, as the reference sampler does.
transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

Optional per-sphere callable applied to the centered sphere dict before the predictor. The transform must preserve the sphere's row count and keep positions centered on the sphere (the inner_ratio mask is evaluated on the transformed positions, as the reference does).
pos_key (str, default: POS ) –

Dict key for the position tensor.
batch_key (str, default: BATCH ) –

Dict key for the per-point batch index.
progress (bool, default: False ) –

If True, show a tqdm progress bar per batch element.
seed (Optional[int], default: None ) –

Optional RNG seed for the initial potentials and the center jitter.

Returns:

Tensor –

Per-point score tensor of shape \((N, C)\): the EMA of softmax probabilities over the spheres covering
Tensor –

each point; points no sphere reaches keep all-zero scores. An empty scene (\(N = 0\)) returns a
Tensor –

\((0, 0)\) tensor: the predictor is never called, so the channel count cannot be inferred.