Table of Contents

Class SpiralConvLayer<T>

Namespace
AiDotNet.NeuralNetworks.Layers
Assembly
AiDotNet.dll

Implements spiral convolution for mesh vertex processing.

public class SpiralConvLayer<T> : LayerBase<T>, ILayer<T>, IJitCompilable<T>, IDiagnosticsProvider, IWeightLoadable<T>, IDisposable

Type Parameters

T

The numeric type used for calculations, typically float or double.

Inheritance
SpiralConvLayer<T>
Implements
Inherited Members

Remarks

SpiralConvLayer operates on mesh vertices by aggregating features from neighbors in a consistent spiral ordering. This enables translation-equivariant convolutions on irregular mesh structures by defining a canonical ordering of vertex neighbors.

For Beginners: Unlike image convolutions where neighbors are in a grid, mesh vertices have irregular connectivity. Spiral convolution solves this by:

  1. Starting at each vertex
  2. Visiting neighbors in a consistent spiral pattern (like a clock hand)
  3. Gathering features from each neighbor in order
  4. Applying learned weights to the ordered features

This creates a consistent "template" for convolution regardless of mesh topology.

Applications:

  • 3D shape analysis and classification
  • Facial expression recognition
  • Body pose estimation
  • Medical surface analysis

Reference: "Neural 3D Morphable Models: Spiral Convolutional Networks" by Bouritsas et al. Reference: "SpiralNet++: A Fast and Highly Efficient Mesh Convolution Operator" by Gong et al.

Constructors

SpiralConvLayer(int, int, int, int, IActivationFunction<T>?)

Initializes a new instance of the SpiralConvLayer<T> class.

public SpiralConvLayer(int inputChannels, int outputChannels, int spiralLength, int numVertices = 1, IActivationFunction<T>? activationFunction = null)

Parameters

inputChannels int

Number of input feature channels per vertex.

outputChannels int

Number of output feature channels per vertex.

spiralLength int

Length of the spiral sequence (number of neighbors).

numVertices int

Expected number of vertices (for shape calculation).

activationFunction IActivationFunction<T>

Remarks

For Beginners: Creates a spiral convolution layer for mesh processing.

The spiral indices must be set via SetSpiralIndices(int[,]) before forward pass.

Exceptions

ArgumentOutOfRangeException

Thrown when parameters are non-positive.

SpiralConvLayer(int, int, int, int, IVectorActivationFunction<T>?)

Initializes a new instance of the SpiralConvLayer<T> class with vector activation.

public SpiralConvLayer(int inputChannels, int outputChannels, int spiralLength, int numVertices = 1, IVectorActivationFunction<T>? vectorActivation = null)

Parameters

inputChannels int

Number of input feature channels per vertex.

outputChannels int

Number of output feature channels per vertex.

spiralLength int

Length of the spiral sequence (number of neighbors).

numVertices int

Expected number of vertices (for shape calculation).

vectorActivation IVectorActivationFunction<T>

Vector activation function to apply.

Exceptions

ArgumentOutOfRangeException

Thrown when parameters are non-positive.

Properties

InputChannels

Gets the number of input feature channels per vertex.

public int InputChannels { get; }

Property Value

int

Remarks

Input channels represent features at each vertex. For 3D coordinates, this is 3. After processing, this can include normals, colors, or learned features.

OutputChannels

Gets the number of output feature channels per vertex.

public int OutputChannels { get; }

Property Value

int

Remarks

Each output channel represents a learned feature detector. More channels enable learning more diverse vertex patterns.

ParameterCount

Gets the total number of trainable parameters.

public override int ParameterCount { get; }

Property Value

int

SpiralLength

Gets the spiral sequence length (number of neighbors in the spiral).

public int SpiralLength { get; }

Property Value

int

Remarks

The spiral length determines how many neighbors are considered for each vertex. Longer spirals capture more context but increase computation. Typical values are 9-16 for detailed meshes.

SupportsGpuExecution

Gets a value indicating whether this layer supports GPU execution.

protected override bool SupportsGpuExecution { get; }

Property Value

bool

SupportsJitCompilation

Gets a value indicating whether this layer supports JIT compilation.

public override bool SupportsJitCompilation { get; }

Property Value

bool

true if weights are initialized and activation can be JIT compiled.

SupportsTraining

Gets a value indicating whether this layer supports training (backpropagation).

public override bool SupportsTraining { get; }

Property Value

bool

Always true for SpiralConvLayer as it has learnable parameters.

Methods

Backward(Tensor<T>)

Performs the backward pass to compute gradients.

public override Tensor<T> Backward(Tensor<T> outputGradient)

Parameters

outputGradient Tensor<T>

Gradient of loss with respect to output.

Returns

Tensor<T>

Gradient of loss with respect to input.

Exceptions

InvalidOperationException

Thrown when Forward has not been called.

Clone()

Creates a deep copy of this layer.

public override LayerBase<T> Clone()

Returns

LayerBase<T>

A new SpiralConvLayer with identical configuration and parameters.

Deserialize(BinaryReader)

Deserializes the layer from a binary stream.

public override void Deserialize(BinaryReader reader)

Parameters

reader BinaryReader

Binary reader for deserialization.

Remarks

If spiral indices were serialized with the layer, they are restored automatically. Otherwise, users must call SetSpiralIndices(int[,]) before calling Forward.

Dispose(bool)

Releases resources used by this layer.

protected override void Dispose(bool disposing)

Parameters

disposing bool

True if called from Dispose(), false if called from finalizer.

Remarks

Override this method in derived classes to release layer-specific resources. Always call base.Dispose(disposing) after releasing your resources.

For Beginners: When creating a custom layer with resources: 

protected override void Dispose(bool disposing)
{
    if (disposing)
    {
        // Release your managed resources here
        _myGpuHandle?.Dispose();
        _myGpuHandle = null;
    }
    base.Dispose(disposing);
}

ExportComputationGraph(List<ComputationNode<T>>)

Exports the layer as a computation graph for JIT compilation.

public override ComputationNode<T> ExportComputationGraph(List<ComputationNode<T>> inputNodes)

Parameters

inputNodes List<ComputationNode<T>>

List to populate with input nodes.

Returns

ComputationNode<T>

The output computation node.

Exceptions

ArgumentNullException

Thrown when inputNodes is null.

InvalidOperationException

Thrown when layer is not initialized.

Forward(Tensor<T>)

Performs the forward pass of spiral convolution.

public override Tensor<T> Forward(Tensor<T> input)

Parameters

input Tensor<T>

Vertex features tensor with shape [numVertices, InputChannels] or [batch, numVertices, InputChannels].

Returns

Tensor<T>

Output tensor with shape [numVertices, OutputChannels] or [batch, numVertices, OutputChannels].

Remarks

The forward pass: 1. Gathers neighbor features according to spiral indices 2. Concatenates gathered features into a flat vector per vertex 3. Applies linear transformation (weights + bias) 4. Applies activation function

Exceptions

InvalidOperationException

Thrown when spiral indices are not set.

ArgumentException

Thrown when input has invalid shape.

ForwardGpu(params IGpuTensor<T>[])

Performs the forward pass of the layer on GPU.

public override IGpuTensor<T> ForwardGpu(params IGpuTensor<T>[] inputs)

Parameters

inputs IGpuTensor<T>[]

The GPU-resident input tensor(s).

Returns

IGpuTensor<T>

The GPU-resident output tensor.

Remarks

This method performs the layer's forward computation entirely on GPU. The input and output tensors remain in GPU memory, avoiding expensive CPU-GPU transfers.

For Beginners: This is like Forward() but runs on the graphics card.

The key difference:

  • Forward() uses CPU tensors that may be copied to/from GPU
  • ForwardGpu() keeps everything on GPU the whole time

Override this in derived classes that support GPU acceleration.

Exceptions

NotSupportedException

Thrown when the layer does not support GPU execution.

GetBiases()

Gets the bias tensor.

public override Tensor<T> GetBiases()

Returns

Tensor<T>

Biases [OutputChannels].

GetParameters()

Gets all trainable parameters as a single vector.

public override Vector<T> GetParameters()

Returns

Vector<T>

Vector containing all weights and biases.

GetWeights()

Gets the weight tensor.

public override Tensor<T> GetWeights()

Returns

Tensor<T>

Weights [OutputChannels, InputChannels * SpiralLength].

ResetState()

Resets cached state from forward/backward passes.

public override void ResetState()

Serialize(BinaryWriter)

Serializes the layer to a binary stream.

public override void Serialize(BinaryWriter writer)

Parameters

writer BinaryWriter

Binary writer for serialization.

Remarks

If spiral indices are set, they are serialized along with the layer. Otherwise, users must call SetSpiralIndices(int[,]) after deserialization.

SetParameters(Vector<T>)

Sets all trainable parameters from a vector.

public override void SetParameters(Vector<T> parameters)

Parameters

parameters Vector<T>

Vector containing all parameters.

Exceptions

ArgumentException

Thrown when parameter count is incorrect.

SetSpiralIndices(int[,])

Sets the spiral indices for the mesh being processed.

public void SetSpiralIndices(int[,] spiralIndices)

Parameters

spiralIndices int[,]

A 2D array of shape [numVertices, SpiralLength] containing neighbor vertex indices in spiral order for each vertex.

Remarks

For Beginners: Before processing a mesh, you must define the spiral ordering of neighbors for each vertex. This method sets that ordering.

The spiral indices should be computed from the mesh topology using a consistent algorithm that starts at a fixed reference direction and visits neighbors in order.

Exceptions

ArgumentNullException

Thrown when spiralIndices is null.

ArgumentException

Thrown when spiral length doesn't match.

UpdateParameters(T)

Updates layer parameters using computed gradients.

public override void UpdateParameters(T learningRate)

Parameters

learningRate T

Learning rate for gradient descent.

Exceptions

InvalidOperationException

Thrown when Backward has not been called.

Edit this page