sliding_window

Sliding-window inference for large-scale point cloud segmentation.

Places block centers on a regular grid with step \(\text{block\_size} \cdot (1 - \text{overlap})\) and calls predictor once per non-empty block. Each point's predictions from all covering blocks are combined by aggregate: a distance-weighted average ("mean"), the single most confident prediction ("max"), or a count of hard votes ("vote").

With overlap=0 and mode="constant", each point lands in exactly one block and the weight division is a no-op.

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 block automatically. Non-tensor entries and tensors with a different leading dim flow through unchanged.

• predictor (Callable[[Dict[str, Any]], Tensor]) –

  Callable taking a per-block data dict and returning logits of shape \((M, C_\text{out})\), where \(M\) is the number of points in the block. The output channel count \(C_\text{out}\) is inferred from the first call.

• block_size (float) –

  Side length of each cubic block, in the same units as data[pos_key].

• overlap (float, default: 0.0 ) –

  Fraction of block_size shared between adjacent blocks, in \([0, 1)\). 0.0 gives a strict non-overlapping partition; 0.5 means adjacent block centers are spaced half a block apart.

• mode (WindowMode, default: 'constant' ) –

  Per-point weight within each block. "constant" gives equal weight to all points in the block. "gaussian" weights by \(\exp(-d^2 / 2\sigma^2)\) where \(d\) is the distance to the block center across the tiled axes and \(\sigma = \text{sigma\_scale} \cdot \text{block\_size} \cdot \sqrt{D_\text{tiled}} / 2\) with \(D_\text{tiled}\) the number of tiled axes.

• sigma_scale (float, default: 0.125 ) –

  Gaussian sigma scale factor. Only used when mode="gaussian".

• roi_num_points (Optional[int], default: None ) –

  Optional cap on points per predictor call. Blocks exceeding this are split into random sub-batches and every point is predicted exactly once per block pass. None passes the whole block in one call. To enforce a fixed-N predictor input, pair the inferer with a DivisiblePad-style transform that pads each block to a multiple of roi_num_points and writes its source-to-padded index map under inverse_key.

• softmax (bool, default: True ) –

  If True, softmax each block's logits before accumulating. Use True when averaging predictions across multiple blocks or TTA passes. Set False to accumulate raw logits. "max" and "vote" aggregation always read confidences off the softmax.

• aggregate (AggregateMode, default: 'mean' ) –

  How the predictions of the blocks covering a point are combined. "mean": distance-weighted average of the (softmax) predictions. "max": winner-takes-all, each point keeps the prediction of the block that is most confident about it (the PVCNN / PointCNN scene merge). "vote": each block casts one hard vote (its argmax) per point and the output holds the weighted vote fractions, so argmax is the majority label (the PointNet++ protocol).

• transform (Optional[Callable[[Dict[str, Any]], Dict[str, Any]]], default: None ) –

  Optional callable applied to each block's data dict before the predictor. The transform sees the whole block; if it changes the row count (pad, voxelize, ...) it must record a source-to-predictor index map under inverse_key so the inferer can gather predictions back to the original block points.

• dims (Optional[Sequence[int]], default: None ) –

  Axes (indices into pos's last dim) to tile. None tiles every axis (cubic blocks). Pass (0, 1) for 2D tiling that leaves the third axis spanning the full scene height.

• padding (float, default: 0.0 ) –

  Extra margin (in pos units) extending each block's membership on every tiled axis. Useful for including a thin context guard band.

• pos_key (str, default: POS ) –

  Dict key for the position tensor.

• batch_key (str, default: BATCH ) –

  Dict key for the per-point batch index.

• block_bbox_key (str, default: 'block_bbox' ) –

  Dict key under which the block bounding box is exposed to the transform callable.

• inverse_key (Optional[str], default: None ) –

  Dict key under which a row-altering transform records a source-to-predictor long index map of shape \((N_\text{block},)\) with values in \([0, N_\text{window})\), where \(N_\text{block}\) is the pre-transform block size and \(N_\text{window}\) is the post-transform size. When set, any scene-level value at this key is dropped from the window before transform runs, so a registered pipeline's inverse never becomes the prior the block map composes through; the inferer then pops the block map before calling the predictor and gathers predictions back to block-local rows. Leave None when the transform preserves row count, or when no transform is used.

• progress (bool, default: False ) –

  If True, show a tqdm progress bar per batch element.

• seed (Optional[int], default: None ) –

  RNG seed for sub-batch permutations when roi_num_points is set.

Returns:

• Tensor –

  Per-point output tensor of shape \((N, C_\text{out})\): with

• Tensor –

  aggregate="mean" a distance-weighted average of softmax probabilities

• Tensor –

  when softmax=True or of raw logits when softmax=False; with

• Tensor –

  "max" the most confident block's probabilities; with "vote" the

• Tensor –

  per-class vote fractions. An empty scene (\(N = 0\)) returns

• Tensor –

  a \((0, 0)\) tensor: the predictor is never called, so the channel count

• Tensor –

  cannot be inferred.