Class Upsample3DLayer<T>

Namespace

AiDotNet.NeuralNetworks.Layers

Assembly

AiDotNet.dll

Represents a 3D upsampling layer that increases the spatial dimensions of volumetric data using nearest-neighbor interpolation.

public class Upsample3DLayer<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

object

LayerBase<T>

Upsample3DLayer<T>

Implements

ILayer<T>

IJitCompilable<T>

IDiagnosticsProvider

IWeightLoadable<T>

IDisposable

Inherited Members

LayerBase<T>.Engine

LayerBase<T>.ScalarActivation

LayerBase<T>.VectorActivation

LayerBase<T>.UsingVectorActivation

LayerBase<T>.NumOps

LayerBase<T>.Random

LayerBase<T>.Parameters

LayerBase<T>.ParameterGradients

LayerBase<T>.InputShape

LayerBase<T>.InputShapes

LayerBase<T>.UpdateInputShape(int[])

LayerBase<T>.OutputShape

LayerBase<T>.IsTrainingMode

LayerBase<T>.InitializationStrategy

LayerBase<T>.IsInitialized

LayerBase<T>.InitializationLock

LayerBase<T>.EnsureInitialized()

LayerBase<T>.UseAutodiff

LayerBase<T>.SetTrainingMode(bool)

LayerBase<T>.GetParameterGradients()

LayerBase<T>.ClearGradients()

LayerBase<T>.GetInputShape()

LayerBase<T>.GetInputShapes()

LayerBase<T>.GetOutputShape()

LayerBase<T>.GetWeights()

LayerBase<T>.GetBiases()

LayerBase<T>.MapActivationToFused()

LayerBase<T>.SupportsGpuTraining

LayerBase<T>.CanExecuteOnGpu

LayerBase<T>.CanTrainOnGpu

LayerBase<T>.UpdateParametersGpu(IGpuOptimizerConfig)

LayerBase<T>.UploadWeightsToGpu()

LayerBase<T>.DownloadWeightsFromGpu()

LayerBase<T>.ZeroGradientsGpu()

LayerBase<T>.GetActivationTypes()

LayerBase<T>.Forward(params Tensor<T>[])

LayerBase<T>.ApplyActivation(Tensor<T>)

LayerBase<T>.ApplyActivation(Vector<T>)

LayerBase<T>.ActivateTensor(IActivationFunction<T>, Tensor<T>)

LayerBase<T>.ActivateTensor(IVectorActivationFunction<T>, Tensor<T>)

LayerBase<T>.CalculateInputShape(int, int, int)

LayerBase<T>.CalculateOutputShape(int, int, int)

LayerBase<T>.DerivativeTensor(IActivationFunction<T>, Tensor<T>)

LayerBase<T>.ApplyActivationDerivative(T, T)

LayerBase<T>.ApplyActivationDerivative(Tensor<T>, Tensor<T>)

LayerBase<T>.ComputeActivationJacobian(Vector<T>)

LayerBase<T>.ApplyActivationDerivative(Vector<T>, Vector<T>)

LayerBase<T>.UpdateParameters(Vector<T>)

LayerBase<T>.GetDiagnostics()

LayerBase<T>.ApplyActivationToGraph(ComputationNode<T>)

LayerBase<T>.CanActivationBeJitted()

LayerBase<T>.RegisterTrainableParameter(Tensor<T>, PersistentTensorRole)

LayerBase<T>.InvalidateTrainableParameter(Tensor<T>)

LayerBase<T>.HasGpuActivation()

LayerBase<T>.ApplyActivationForwardGpu(IDirectGpuBackend, IGpuBuffer, IGpuBuffer, int)

LayerBase<T>.ApplyActivationBackwardGpu(IDirectGpuBackend, IGpuBuffer, IGpuBuffer, IGpuBuffer, IGpuBuffer, int)

LayerBase<T>.GetFusedActivationType()

LayerBase<T>.ApplyGpuActivation(IDirectGpuBackend, IGpuBuffer, IGpuBuffer, int, FusedActivationType)

LayerBase<T>.ApplyGpuActivationBackward(IDirectGpuBackend, IGpuBuffer, IGpuBuffer, IGpuBuffer, IGpuBuffer, int, FusedActivationType, float)

LayerBase<T>.Dispose()

LayerBase<T>.Dispose(bool)

LayerBase<T>.WeightParameterName

LayerBase<T>.BiasParameterName

LayerBase<T>.SetWeights(Tensor<T>)

LayerBase<T>.SetBiases(Tensor<T>)

LayerBase<T>.GetParameterNames()

LayerBase<T>.TryGetParameter(string, out Tensor<T>)

LayerBase<T>.SetParameter(string, Tensor<T>)

LayerBase<T>.GetParameterShape(string)

LayerBase<T>.NamedParameterCount

LayerBase<T>.ValidateWeights(IEnumerable<string>, Func<string, string>)

LayerBase<T>.LoadWeights(Dictionary<string, Tensor<T>>, Func<string, string>, bool)

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A 3D upsampling layer increases the spatial dimensions (depth, height, width) of volumetric tensors by repeating values from the input to create a larger output. This implementation uses nearest-neighbor interpolation, which copies each voxel value to fill a block in the output based on the scale factors.

For Beginners: This layer makes 3D volumes larger by simply repeating voxel values.

Think of it like zooming in on a 3D image:

• When you zoom in on a voxelized object, each original voxel becomes a larger block
• This layer does the same thing to 3D feature volumes inside the neural network
• It's like stretching a 3D volume without adding any new information

For example, with a scale factor of 2:

• A 4×4×4 volume becomes an 8×8×8 volume
• Each voxel in the original volume is copied to a 2×2×2 block in the output
• This creates a larger volume that preserves the original content but with more voxels

This is essential for 3D U-Net decoder paths, where we need to progressively increase the spatial resolution to match the original input size.

Constructors

Upsample3DLayer(int[], int)

Initializes a new instance of the Upsample3DLayer<T> class with uniform scaling.

public Upsample3DLayer(int[] inputShape, int scaleFactor)

Parameters

inputShape int[]

The shape of the input tensor [channels, depth, height, width].

scaleFactor int

The factor by which to increase all spatial dimensions.

Remarks

For Beginners: This creates a 3D upsampling layer with the same scale for all dimensions.

For example, with scaleFactor=2 and input shape [32, 8, 8, 8]: - Output shape becomes [32, 16, 16, 16] - Each voxel becomes a 2×2×2 block

Exceptions

ArgumentException

Thrown when inputShape is invalid.

ArgumentOutOfRangeException

Thrown when scaleFactor is not positive.

Upsample3DLayer(int[], int, int, int)

Initializes a new instance of the Upsample3DLayer<T> class with separate scale factors.

public Upsample3DLayer(int[] inputShape, int scaleDepth, int scaleHeight, int scaleWidth)

Parameters

inputShape int[]

The shape of the input tensor [channels, depth, height, width].

scaleDepth int

The factor by which to increase the depth dimension.

scaleHeight int

The factor by which to increase the height dimension.

scaleWidth int

The factor by which to increase the width dimension.

Remarks

For Beginners: This creates a 3D upsampling layer with different scales per dimension.

This is useful when you want non-uniform upsampling, for example: - Medical imaging where slices may have different spacing - Video data where temporal and spatial scales differ

Exceptions

ArgumentException

Thrown when inputShape is invalid.

ArgumentOutOfRangeException

Thrown when any scale factor is not positive.

Properties

ParameterCount

Gets the total number of trainable parameters in the layer.

public override int ParameterCount { get; }

Property Value

int

Always 0 as this layer has no trainable parameters.

ScaleDepth

Gets the scale factor for the depth dimension.

public int ScaleDepth { get; }

Property Value

int

Remarks

This property stores the factor by which to increase the depth dimension. A value of 2 means the output depth will be twice the input depth.

ScaleHeight

Gets the scale factor for the height dimension.

public int ScaleHeight { get; }

Property Value

int

Remarks

This property stores the factor by which to increase the height dimension. A value of 2 means the output height will be twice the input height.

ScaleWidth

Gets the scale factor for the width dimension.

public int ScaleWidth { get; }

Property Value

int

Remarks

This property stores the factor by which to increase the width dimension. A value of 2 means the output width will be twice the input width.

SupportsGpuExecution

Gets a value indicating whether this layer supports GPU execution.

protected override bool SupportsGpuExecution { get; }

Property Value

bool

Remarks

Upsample3D supports GPU execution via CUDA, OpenCL, and HIP backends using nearest neighbor interpolation.

SupportsJitCompilation

Gets a value indicating whether this layer supports JIT compilation.

public override bool SupportsJitCompilation { get; }

Property Value

bool

true if the input shape is configured.

SupportsTraining

Gets a value indicating whether this layer supports training.

public override bool SupportsTraining { get; }

Property Value

bool

true for this layer, even though it has no trainable parameters, to allow gradient propagation.

Remarks

Although this layer does not have trainable parameters, it returns true to allow gradient propagation through the layer during backpropagation.

Methods

Backward(Tensor<T>)

Performs the backward pass to propagate gradients through the upsampling.

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

Parameters

outputGradient Tensor<T>

The gradient of the loss with respect to this layer's output.

Returns

Tensor<T>

The gradient of the loss with respect to this layer's input.

Remarks

During backpropagation, gradients from each output voxel in a [scaleD × scaleH × scaleW] block are summed and assigned to the corresponding input voxel.

Exceptions

InvalidOperationException

Thrown when Forward has not been called.

BackwardGpu(IGpuTensor<T>)

Performs GPU-resident backward pass of 3D upsampling.

public override IGpuTensor<T> BackwardGpu(IGpuTensor<T> outputGradient)

Parameters

outputGradient IGpuTensor<T>

The gradient of the output on GPU.

Returns

IGpuTensor<T>

The gradient with respect to input as a GPU-resident tensor.

Clone()

Creates a deep copy of the layer with the same configuration.

public override LayerBase<T> Clone()

Returns

LayerBase<T>

A new instance of the Upsample3DLayer<T> with identical configuration.

Deserialize(BinaryReader)

Deserializes the layer from a binary stream.

public override void Deserialize(BinaryReader reader)

Parameters

reader BinaryReader

The binary reader to deserialize from.

Remarks

This method validates that the serialized scale factors match the current instance's values. For full deserialization support, use the static factory method DeserializeFrom(BinaryReader) instead.

Exceptions

InvalidOperationException

Thrown because Upsample3DLayer uses readonly properties and cannot be deserialized in-place.

DeserializeFrom(BinaryReader)

Creates a new Upsample3DLayer instance from serialized data.

public static Upsample3DLayer<T> DeserializeFrom(BinaryReader reader)

Parameters

reader BinaryReader

The binary reader containing serialized data.

Returns

Upsample3DLayer<T>

A new Upsample3DLayer instance with the deserialized configuration.

Remarks

This factory method properly deserializes Upsample3DLayer by creating a new instance with the correct scale factors and input shape from the serialized data.

ExportComputationGraph(List<ComputationNode<T>>)

Exports the layer's computation as a graph node for JIT compilation or autodiff.

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

Parameters

inputNodes List<ComputationNode<T>>

List to append input nodes to.

Returns

ComputationNode<T>

A computation node representing the upsampling operation.

Remarks

This method is not yet implemented. The TensorOperations.Upsample3D method needs to be added to support JIT compilation and automatic differentiation for 3D upsampling operations.

Exceptions

NotSupportedException

Thrown because Upsample3D autodiff is not yet implemented.

Forward(Tensor<T>)

Performs the forward pass of the 3D upsampling layer.

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

Parameters

input Tensor<T>

The input tensor with shape [batch, channels, depth, height, width] or [channels, depth, height, width].

Returns

Tensor<T>

The upsampled output tensor with increased spatial dimensions.

Remarks

This method uses the vectorized Engine.Upsample3D operation for CPU/GPU acceleration. Each voxel in the input is replicated to fill a block of size [scaleD × scaleH × scaleW] in the output.

Exceptions

ArgumentException

Thrown when input tensor has invalid rank.

ForwardGpu(params IGpuTensor<T>[])

Performs GPU-resident forward pass of 3D upsampling, keeping all data on GPU.

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

Parameters

inputs IGpuTensor<T>[]

The input tensors on GPU (uses first input).

Returns

IGpuTensor<T>

The upsampled output as a GPU-resident tensor.

GetParameters()

Gets all trainable parameters. This layer has none.

public override Vector<T> GetParameters()

Returns

Vector<T>

An empty vector.

ResetState()

Resets the 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

The binary writer to serialize to.

SetParameters(Vector<T>)

Sets parameters from a vector. This layer has no trainable parameters.

public override void SetParameters(Vector<T> parameters)

Parameters

parameters Vector<T>

Parameter vector (should be empty).

UpdateParameters(T)

Updates parameters. This layer has no trainable parameters.

public override void UpdateParameters(T learningRate)

Parameters

learningRate T

The learning rate (unused).