src.model.deeplearn.arch.spconv3d_pwise_classif

Classes

SpConv3DPwiseClassif(**kwargs)

class src.model.deeplearn.arch.spconv3d_pwise_classif.SpConv3DPwiseClassif(**kwargs)
Author:

Alberto M. Esmoris Pena

Sparse 3D convolutional point-wise classifier. Built on top of:

The build_input() tensor signature consists of one global feature tensor F and per-depth neighbor tables S, D, U plus per-depth real-cell masks M.

Kernel-position counts (f, df, uf in the underlying layers) are derived from the convolutional window sizes: f = (2 w[t] + 1)^3 for submanifold, df = w_D[t]^3 for downsampling, uf = w_U[t-1]^3 for upsampling. The legacy submanifold_filters configuration field is rejected; passing it raises DeepLearningException with a migration message.

The padded rows of every batch are flagged via the per-depth masks M_t so MaskedBatchNormalization skips them when computing the batch statistics — running mean / variance converge to the real-cell distribution rather than being biased by the padding ratio.

Note

Backend assumption. The slicing / padding patterns in build_output() and the encoder/decoder call bodies treat the row axis as the active-cell axis (not the Keras batch axis). This is sound for the TF backend used by VL3D; porting to the Keras 3 JAX or PyTorch backends would require revisiting those ops.

__init__(**kwargs)

See architecture.Architecture.__init__(). Reads the same set of hyperparameters as the legacy SpConv3DPwiseClassif with these differences:

  • submanifold_filters is rejected: presence in the spec raises DeepLearningException with a migration message.

  • Kernel-position counts are auto-derived from window sizes.

build_input()

Build the input layer of the neural network. The tensor signature consists of:

  1. A single feature tensor \(\pmb{F}\) of shape \((1 + R_0, n_f)\) (the concatenated level-0 features emitted by DLSparseConcatSequencer, with the single shared ground row at index 0).

  2. Submanifold neighbor tables \(\pmb{S}_t\) of shape \((1 + R_t, (2 w_t + 1)^3)\) per depth \(t \in [0, t^*)\).

  3. Downsampling neighbor tables \(\pmb{D}_t\) of shape \((1 + R_{t+1}, w^D_t{}^3)\) per depth \(t \in [0, t^* - 1)\).

  4. Upsampling neighbor tables \(\pmb{U}_t\) of shape \((1 + R_t, w^U_t{}^3)\) per depth \(t \in [0, t^* - 1)\).

  5. Per-depth real-cell masks \(\pmb{M}_t\) of shape \((R_t,)\) per depth \(t \in [0, t^*)\). Each entry is True for a real cell and False for a padded cell. The masks are forwarded to every MaskedBatchNormalization instance so the batch statistics ignore the padded zero rows.

Returns:

Flat list of Keras input tensors in the order [F, S_0, ..., S_{t*-1}, D_0, ..., D_{t*-2}, U_0, ..., U_{t*-2}, M_0, ..., M_{t*-1}].

Return type:

list of keras.KerasTensor

build_hidden(x, **kwargs)

Build the hidden layers of the SpConv hierarchy.

build_output(x, **kwargs)

Build the output head. x carries the global ground row at index 0; the output dense layer is applied to the active-cell view x[1:] so the prediction tensor matches the labels’ flat layout emitted by DLSparseConcatSequencer.

overwrite_compilation_args(new_args)

Refuse a post-build compilation_args mutation whose binary_crossentropy flag would differ from the already-built output head. Converts a silent loss / head shape mismatch into a loud, recoverable error.

Called by the model handler’s overwrite_pretrained_model after mutating mh.compilation_args. Pre-build calls update the cached compilation_args without raising; post-build calls raise when the new args imply a different output head.

Parameters:

new_args – The new compilation_args dict (or None).

Raises:

src.model.deeplearn.deep_learning_exception.DeepLearningException – when the binary_crossentropy flag would change after the model has been built.

build_spconv_hierarchy(F)

Build the SpConv encoder + decoder hierarchy on the given ground-prefixed feature tensor. Dispatches between layer-by-layer and fused encoder/decoder modes per self.layer_by_layer.