src.model.deeplearn.layer.spconv3d_decoding_layer

Classes

SpConv3DDecodingLayer(*args, **kwargs)

class src.model.deeplearn.layer.spconv3d_decoding_layer.SpConv3DDecodingLayer(*args, **kwargs)
Author:

Alberto M. Esmoris Pena

Sparse 3D convolutional decoding layer.

The decoder operates symmetrically to the encoder. At hierarchy depth \(t\), it receives the depth-\((t + 1)\) feature tensor \(\pmb{F}\), the matching encoder’s skip link \(\pmb{F^{\mathrm{skip}}}\) at depth \(t\), the submanifold neighbor table \(\pmb{S}\) at depth \(t + 1\), and the upsampling neighbor table \(\pmb{U}\) at depth \(t\). It composes: preactivation BN + ReLU, pre-wrap SharedMLP, a stack of submanifold convolutions with optional residual branch, post-wrap SharedMLP, upsampling convolution to depth \(t\), skip-link concatenation, and a final SharedMLP that fuses skip and upsampled paths.

The call takes a four- or six-element input list:

  1. \(\pmb{F}\) of shape \((1 + R_{t+1}, n_f)\) — depth-\((t+1)\) features with the shared ground row at index 0.

  2. \(\pmb{F^{\mathrm{skip}}}\) of shape \((R_t, n_{fd})\) — depth-\(t\) skip-link from the matching encoder (active form — the ground row is re-prepended at the decoder exit).

  3. \(\pmb{S}\) of shape \((1 + R_{t+1}, (2 w + 1)^3)\) — submanifold neighbor table at depth \(t + 1\).

  4. \(\pmb{U}\) of shape \((1 + R_t, w_U^3)\) — upsampling neighbor table that maps depth-\((t + 1)\) cells back to depth-\(t\) cells.

  5. (optional) \(\pmb{M}_{t+1}\) of shape \((R_{t+1},)\) — depth-\((t+1)\) real-cell mask.

  6. (optional) \(\pmb{M}_t\) of shape \((R_t,)\) — depth-\(t\) real-cell mask.

When the optional masks are provided every BN sublayer inside this decoder operates as a masked BN over the real cells only.

The call returns a single tensor of shape \((1 + R_t, n_{fd})\) with the ground row re-prepended for any downstream gather. BN sublayers receive training=training — real BN across all receptive fields in the batch, not instance-norm-via-BN.

__init__(w, uw, f, uf, nfa, nfb, nfc, nfd, num_spconvs=1, W_initializers=None, W_regularizers=None, W_constraints=None, uW_initializer=None, uW_regularizer=None, uW_constraint=None, spconv_bn=None, spconv_bn_momentum=0.9, spconv_act=None, spconv_activation=<function relu>, preact_bn=None, preact_act=None, prewrap_bn=None, postwrap_bn=None, postwrap_bn_res=None, wrap_bn_momentum=0.99, prewrap_act=None, postwrap_act=None, prewrap_activation=None, prewrap_kernel_initializer='glorot_uniform', prewrap_kernel_regularizer=None, prewrap_kernel_constraint=None, postwrap_activation=None, postwrap_kernel_initializer='glorot_uniform', postwrap_kernel_regularizer=None, postwrap_kernel_constraint=None, residual_strategy=None, res_activation=None, res_kernel_initializer='glorot_uniform', res_kernel_regularizer=None, res_kernel_constraint=None, res_spconv_activation=<function relu>, res_spconv_bn_momentum=0.9, res_spconv_bn=None, res_spconv_act=None, post_residual_shared_mlp=False, postres_activation=<function relu>, postres_bn_momentum=0.99, postres_act=None, postres_bn=None, postres_kernel_activation=None, postres_kernel_initializer='glorot_uniform', postres_kernel_regularizer=None, postres_kernel_constraint=None, up_activation=<function relu>, up_act=None, up_bn_momentum=0.9, up_bn=None, sl_bn=None, sl_bn_skip=None, sl_bn_momentum=0.99, sl_act=None, sl_kernel_activation=<function relu>, sl_kernel_initializer='glorot_uniform', sl_kernel_regularizer=None, sl_kernel_constraint=None, built_W=False, built_uW=False, built_prewrap_kernel=False, built_prewrap_bias=False, built_postwrap_kernel=False, built_postwrap_bias=False, built_res_kernel=False, built_res_bias=False, built_postres_kernel=False, built_postres_bias=False, built_sl_kernel=False, built_sl_bias=False, **kwargs)

See Layer and layer.Layer.__init__().

build(dim_in)

Build per-conv kernels, pre/post-wrap SharedMLP, residual block, upsampling kernel, and skip-link SharedMLP. dim_in[0][-1] is the input depth-\((t+1)\) feature dimension; dim_in[1][-1] is the skip-link feature dimension (which equals nfd).

call(inputs, training=None)

Compute the decoder forward pass on the concatenated global tensors.

Parameters:

inputs –

A 4- or 6-element list / tuple. The first four entries are always:

  • inputs[0]: \(\pmb{F}\) at depth \(t + 1\) with shape \((1 + R_{t+1}, n_f)\).

  • inputs[1]: skip_link at depth \(t\) with shape \((R_t, n_{skip})\) — already in active form.

  • inputs[2]: \(\pmb{S}\) — submanifold table at depth \(t + 1\).

  • inputs[3]: \(\pmb{U}\) — upsampling table from depth \(t + 1\) to depth \(t\).

When the optional 5th and 6th entries are given, they are 1-D boolean tensors:

  • inputs[4]: depth-\(t + 1\) mask of shape \((R_{t+1},)\) — used by every BN that operates on the depth-\(t + 1\) activations (preact, prewrap, spconv, residual, postwrap, up).

  • inputs[5]: depth-\(t\) mask of shape \((R_t,)\) — used by the skip-link BN after the upsampling brings the activations back to depth \(t\).

When the masks are absent the BN behavior falls back to the vanilla unmasked path.

Returns:

A tensor of shape \((1 + R_t, n_{fd})\) with the ground row at position 0.

Return type:

tf.Tensor

get_config()

Return necessary data to serialize the layer.

classmethod from_config(config)

Deserialize the layer from a config dict.

Driven by the class attributes _LAYER_INSTANCE_KEYS (scalar sublayers) and _LAYER_INSTANCE_LIST_KEYS (lists of sublayers). See SpConv3DEncodingLayer.from_config() for the rationale.