Struct TensorShape

Represents the shape of a tensor.

Inherited Members

object.Equals(object, object)

object.GetType()

object.ReferenceEquals(object, object)

Namespace: Unity.InferenceEngine

Assembly: Unity.InferenceEngine.dll

Syntax

[MovedFrom("Unity.Sentis")]
[Serializable]
public struct TensorShape

Remarks

A TensorShape describes the shape of a Tensor or FunctionalTensor.

TensorShape supports rank up to maxRank (8).

Create a TensorShape using one of the constructors, or by passing an array of integers.

TensorShape provides methods for common shape transformations such as Squeeze() and Squeeze(int), Unsqueeze(int), Flatten(), Broadcast(TensorShape), and Reduce(int, bool). These methods return new TensorShapes without modifying the original.

The rank property returns the number of dimensions, and the length property returns the total number of elements (the product of all dimensions).

Additional resources:

• Tensor
• FunctionalTensor
• DynamicTensorShape

Examples

Create `TensorShapes` and get their properties

using Unity.InferenceEngine;
// Create TensorShape
var shape = new TensorShape(3, 4);       // Shape: (3, 4), rank: 2
// Create shape from an array
var shape2 = new TensorShape(new[] { 2, 3, 4, 5 });
// Shape: (2, 3, 4, 5), rank: 4
// Shape properties
shape.rank;    // Returns 2
shape.length;  // Returns 12 (3 * 4)
shape[0];      // Returns 3
shape[-1];     // Returns 4 (last dimension)

Constructors

TensorShape(int)

Initializes and returns an instance of TensorShape with a rank of 1 (vector).

Declaration

public TensorShape(int d0)

Parameters

Type	Name	Description
int	d0	Length of axis 0.

Examples

Create a `TensorShape` of rank `1` (vector)

var shape = new TensorShape(42);
// Result: shape of rank 1

TensorShape(int, int)

Initializes and returns an instance of TensorShape with a rank of 2 (matrix).

Declaration

public TensorShape(int d0, int d1)

Parameters

Type	Name	Description
int	d0	Length of axis 0.
int	d1	Length of axis 1.

Examples

Create a `TensorShape` of rank `2` (matrix)

var shape = new TensorShape(8, 2);
// Result: shape of rank 2

TensorShape(int, int, int)

Initializes and returns an instance of TensorShape with a rank of 3.

Declaration

public TensorShape(int d0, int d1, int d2)

Parameters

Type	Name	Description
int	d0	Length of axis 0.
int	d1	Length of axis 1.
int	d2	Length of axis 2.

Examples

Create a `TensorShape` of rank `3`

var shape = new TensorShape(2, 3, 4);
// Result: shape of rank 3

TensorShape(int, int, int, int)

Initializes and returns an instance of TensorShape with a rank of 4.

Declaration

public TensorShape(int d0, int d1, int d2, int d3)

Parameters

Type	Name	Description
int	d0	Length of axis 0.
int	d1	Length of axis 1.
int	d2	Length of axis 2.
int	d3	Length of axis 3.

Examples

Create a `TensorShape` of rank `4`

var shape = new TensorShape(6, 7, 8, 9);
// Result: shape of rank 4

TensorShape(int, int, int, int, int)

Initializes and returns an instance of TensorShape with a rank of 5.

Declaration

public TensorShape(int d0, int d1, int d2, int d3, int d4)

Parameters

Type	Name	Description
int	d0	Length of axis 0.
int	d1	Length of axis 1.
int	d2	Length of axis 2.
int	d3	Length of axis 3.
int	d4	Length of axis 4.

Examples

Create a `TensorShape` of rank `5`

var shape = new TensorShape(5, 6, 7, 8, 9);
// Result: shape of rank 5

TensorShape(int, int, int, int, int, int)

Initializes and returns an instance of TensorShape with a rank of 6.

Declaration

public TensorShape(int d0, int d1, int d2, int d3, int d4, int d5)

Parameters

Type	Name	Description
int	d0	Length of axis 0.
int	d1	Length of axis 1.
int	d2	Length of axis 2.
int	d3	Length of axis 3.
int	d4	Length of axis 4.
int	d5	Length of axis 5.

Examples

Create a `TensorShape` of rank `6`

var shape = new TensorShape(4, 5, 6, 7, 8, 9);
// Result: shape of rank 6

TensorShape(int, int, int, int, int, int, int)

Initializes and returns an instance of TensorShape with a rank of 7.

Declaration

public TensorShape(int d0, int d1, int d2, int d3, int d4, int d5, int d6)

Parameters

Type	Name	Description
int	d0	Length of axis 0.
int	d1	Length of axis 1.
int	d2	Length of axis 2.
int	d3	Length of axis 3.
int	d4	Length of axis 4.
int	d5	Length of axis 5.
int	d6	Length of axis 6.

Examples

Create a `TensorShape` of rank `7`

var shape = new TensorShape(3, 3, 4, 4, 5, 5, 6);
// Result: shape of rank 7

TensorShape(int, int, int, int, int, int, int, int)

Initializes and returns an instance of TensorShape with a rank of 8.

Declaration

public TensorShape(int d0, int d1, int d2, int d3, int d4, int d5, int d6, int d7)

Parameters

Type	Name	Description
int	d0	Length of axis 0.
int	d1	Length of axis 1.
int	d2	Length of axis 2.
int	d3	Length of axis 3.
int	d4	Length of axis 4.
int	d5	Length of axis 5.
int	d6	Length of axis 6.
int	d7	Length of axis 7.

Examples

Create a `TensorShape` of rank `8`

var shape = new TensorShape(2, 3, 4, 5, 6, 7, 8, 9);
// Result: shape of rank 8

TensorShape(ReadOnlySpan<int>)

Initializes a TensorShape from a span of integers.

Declaration

public TensorShape(ReadOnlySpan<int> shape)

Parameters

Type	Name	Description
ReadOnlySpan<int>	shape	A span of integers representing each dimension.

Remarks

This constructor creates a TensorShape from a span of integers, where each element specifies a dimension. The maximum rank is maxRank (8 dimensions).

Examples

Create a `TensorShape` from an array of integers

// Create shape from an array
var shape = new TensorShape(new[] { 3, 4, 5, 6 });
// Result: (3, 4, 5, 6)

Fields

maxRank

The maximum rank (number of dimensions) a TensorShape can have.

Declaration

public const int maxRank = 8

Field Value

Type	Description
int

Remarks

This constant defines the upper limit for rank in Unity Inference Engine.

Properties

this[int]

Gets or sets the dimension of the TensorShape at a given axis.

Declaration

public int this[int axis] { get; set; }

Parameters

Type	Name	Description
int	axis	The axis to get or set. Must be in the range [-rank, rank-1].

Property Value

Type	Description
int

Remarks

This indexer provides access to individual dimensions. Axes are indexed from 0 to rank-1. Negative indices count backwards from the last dimension.

Examples

Access and modify dimensions of a `TensorShape`

var shape = new TensorShape(2, 3, 4);
// Access a dimension
shape[1];   // Returns 3
shape[-1];  // Returns 4
// Modify a dimension
shape[1] = 5;
// shape is now (2, 5, 4)

length

Gets the total number of elements in a tensor with this shape.

Declaration

public int length { get; }

Property Value

Type	Description
int

Remarks

The length is the product of all dimensions. A scalar tensor (rank 0) has a length of 1. A shape with any dimension 0 has a length of 0.

Examples

Get the total number of elements in a `TensorShape`

var shape = new TensorShape(4, 3, 2);
shape.length;  // Returns 24

rank

Gets the number of dimensions in the TensorShape.

Declaration

public int rank { get; }

Property Value

Type	Description
int

Remarks

The rank indicates how many dimensions the shape has. For example:

• A scalar has rank 0
• A 1D tensor (vector) has rank 1
• A 2D tensor (matrix) has rank 2
• A 3D tensor has rank 3, and so on

The maximum rank is maxRank, which is 8.

Examples

Get the rank of a `TensorShape`

var shape = new TensorShape(4, 3, 2, 4);
shape.rank;  // Returns 4

Methods

Broadcast(TensorShape)

Broadcasts this TensorShape with another TensorShape.

Declaration

public TensorShape Broadcast(TensorShape other)

Parameters

Type	Name	Description
TensorShape	other	The other TensorShape to broadcast with.

Returns

Type	Description
TensorShape	A new TensorShape representing the broadcasted result.

Remarks

This method computes the broadcasted shape following NumPy broadcasting rules:

• Shapes are aligned from the innermost (rightmost) dimension
• Dimensions are compatible if they're equal, or one of them is 1
• The result shape has the maximum of compatible dimensions
• The result rank is the maximum of the two input ranks

An error occurs if dimensions are incompatible (neither equal nor 1).

Examples

Broadcast two `TensorShapes` together

var shape1 = new TensorShape(1, 3, 4);
var shape2 = new TensorShape(2, 1, 4);
var broadcast = shape1.Broadcast(shape2);
// Result: (2, 3, 4)
var shape3 = new TensorShape(3, 4);
var broadcast2 = shape2.Broadcast(shape3);
// Result: (2, 3, 4)

Equals(object)

Determines whether this TensorShape is equal to the specified object.

Declaration

public override bool Equals(object obj)

Parameters

Type	Name	Description
object	obj	The object to compare.

Returns

Type	Description
bool	true if obj is a TensorShape equal to this shape; otherwise, false.

Overrides

ValueType.Equals(object)

Remarks

This method checks if obj is a TensorShape with the same rank and dimensions. Returns false if obj is null or not a TensorShape.

Examples

Check if a `TensorShape` equals another object

var shape1 = new TensorShape(2, 3, 4);
var shape2 = new TensorShape(2, 3, 4);
var shape3 = new TensorShape(2, 3, 5);
var notShape = "not a shape";
shape1.Equals(shape2);    // Returns true
shape1.Equals(shape3);    // Returns false
shape1.Equals(notShape);  // Returns false

Flatten()

Gets a 1D TensorShape (vector) representation of this TensorShape.

Declaration

public TensorShape Flatten()

Returns

Type	Description
TensorShape	A new TensorShape of rank 1 with length equal to the original length.

Remarks

This method returns a new TensorShape of rank 1 (vector). The flattened shape has a single dimension equal to the original length.

Examples

Flatten a `TensorShape` to a vector shape

var shape = new TensorShape(2, 3, 4);
var flattened = shape.Flatten();
// Result: (24)

GetHashCode()

Returns a hash code for this TensorShape.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	A hash code value for this TensorShape.

Overrides

ValueType.GetHashCode()

Remarks

The hash code is computed from the rank and all dimension values. TensorShapes that are Equals(object) produce the same hash code.

Examples

Get the hash code for a `TensorShape`

var shape = new TensorShape(2, 3, 4);
shape.GetHashCode();  // Hash code specific to shape (2, 3, 4)

HasZeroDims()

Checks whether the shape has any dimension equal to 0.

Declaration

public bool HasZeroDims()

Returns

Type	Description
bool	true if the shape has rank greater than 0 and at least one dimension is 0; otherwise, false.

Remarks

A shape with any dimension equal to 0 has a length of 0, even if other dimensions are non-zero. This method returns false for scalar tensors (rank 0).

Examples

Check if a `TensorShape` has any dimension equal to `0`

var shape1 = new TensorShape(3, 4, 5);
shape1.HasZeroDims();  // Returns false
var shape2 = new TensorShape(3, 0, 5);
shape2.HasZeroDims();  // Returns true

Length(int)

Returns the number of elements from a given start axis to the end.

Declaration

public int Length(int start)

Parameters

Type	Name	Description
int	start	The first axis to count from. Negative values count from the end.

Returns

Type	Description
int	The product of dimensions from start to the last axis.

Remarks

This method calculates the product of dimensions from the start axis through the last axis. Negative start values count backwards from the innermost dimension. If start is beyond the shape's rank, returns 1.

Examples

Calculate the number of elements from a given axis to the end

var shape = new TensorShape(2, 3, 4, 5);
shape.Length(1);   // Returns 60 (3 * 4 * 5)
shape.Length(-2);  // Returns 20 (4 * 5)

Length(int, int)

Returns the number of elements within a range of axes.

Declaration

public int Length(int start, int end)

Parameters

Type	Name	Description
int	start	The first axis to count from (inclusive). Negative values count from the end.
int	end	The final axis to count to (exclusive). Negative values count from the end.

Returns

Type	Description
int	The product of dimensions in the range [start, end).

Remarks

This method calculates the product of the dimensions from the start axis up to, but not including, the end axis. Negative axis values count backwards from the innermost dimension. If the range is out of bounds or empty, returns 1.

Examples

Calculate the number of elements within a range of axes

var shape = new TensorShape(2, 3, 4, 5);
shape.Length(1, 3);   // Returns 12 (3 * 4)
shape.Length(-2, -1); // Returns 4
shape.Length(1, 1);   // Returns 1

Ones(int)

Creates a TensorShape with all dimensions equal to 1.

Declaration

public static TensorShape Ones(int rank)

Parameters

Type	Name	Description
int	rank	The number of dimensions in the shape. Must be between 0 and 8.

Returns

Type	Description
TensorShape	A new TensorShape with all dimensions equal to 1.

Remarks

This static method creates a new TensorShape with the specified rank where every dimension is 1. The resulting shape has a length of 1. The maximum rank is 8.

Examples

Create a `TensorShape` with all dimensions equal to `1`

var ones = TensorShape.Ones(3);
// Result: (1, 1, 1)

Reduce(int, bool)

Reduces a TensorShape's dimension along axis.

Declaration

public TensorShape Reduce(int axis, bool keepDim = true)

Parameters

Type	Name	Description
int	axis	The axis along which to reduce. Negative values count from the end.
bool	keepDim	When true, the reduced dimension becomes 1. When false, the dimension is removed.

Returns

Type	Description
TensorShape	A new TensorShape with the dimension axis reduced.

Remarks

This method returns a new TensorShape that represents the result of a reduction operation along the specified axis. If keepDim is true, the dimension is replaced with 1. If keepDim is false, the dimension is removed entirely.

For scalar tensors (rank 0), returns the same shape if keepDim is true.

This method does not allow reducing over dimensions equal to 0 when keepDim is false.

Examples

Reduce a dimension along a specified axis

var shape = new TensorShape(2, 3, 4, 5);
var reduced1 = shape.Reduce(1, keepDim: true);
// Result: (2, 1, 4, 5)
var reduced2 = shape.Reduce(1, keepDim: false);
// Result: (2, 4, 5)
var reduced3 = shape.Reduce(-1, keepDim: true);
// Result: (2, 3, 4, 1) - reduced last dimension

Squeeze()

Removes all dimensions equal to 1 from a TensorShape.

Declaration

public TensorShape Squeeze()

Returns

Type	Description
TensorShape	A new TensorShape with all dimensions 1 removed.

Remarks

This method returns a new TensorShape with all dimensions 1 removed. The original shape is not modified.

This method cannot be called on scalar tensors (rank 0).

Examples

Remove all dimensions equal to `1` from a `TensorShape`

var shape = new TensorShape(5, 1, 3, 1);
var squeezed = shape.Squeeze();
// Result: (5, 3)

Squeeze(int)

Removes a specific dimension, equal to 1, from a TensorShape.

Declaration

public TensorShape Squeeze(int axis)

Parameters

Type	Name	Description
int	axis	The axis to remove. Must be a dimension equal to 1 Negative values count from the end.

Returns

Type	Description
TensorShape	A new TensorShape with the specified dimension removed.

Remarks

This method returns a new TensorShape with the specified axis removed. The axis must have size 1. Negative axis values count backwards from the last dimension. The original shape is not modified.

This method cannot be called on scalar tensors (rank 0).

Examples

Remove a dimension equal to `1` from a `TensorShape`

var shape = new TensorShape(5, 1, 3, 1);
var squeezed1 = shape.Squeeze(1);
// Result: (5, 3, 1)
var squeezed2 = shape.Squeeze(-1);
// Result: (5, 1, 3)

ToArray()

Returns the TensorShape as an array of integers.

Declaration

public int[] ToArray()

Returns

Type	Description
int[]	An integer array where each element is the corresponding dimension.

Remarks

This method creates a new integer array representing the TensorShape.

Examples

Get a representation of a `TensorShape` as an array of integers

var shape = new TensorShape(2, 3, 4);
int[] array = shape.ToArray();
// array is [2, 3, 4]

ToString()

Returns a string representation of the TensorShape.

Declaration

public override string ToString()

Returns

Type	Description
string	A string showing all dimensions in the format "(d0, d1, ..., dn)".

Overrides

ValueType.ToString()

Remarks

The string format displays all dimensions in parentheses, separated by commas.

Examples

Get a string representation of a `TensorShape`

var shape = new TensorShape(2, 3, 4);
shape.ToString();  // Returns "(2, 3, 4)"

Unsqueeze(int)

Inserts a dimension 1 in a TensorShape at a specified axis.

Declaration

public TensorShape Unsqueeze(int axis)

Parameters

Type	Name	Description
int	axis	The position to insert the new dimension. Negative values count from the end in the new rank.

Returns

Type	Description
TensorShape	A new TensorShape with an additional dimension 1.

Remarks

This method returns a new TensorShape with a dimension 1 inserted at the specified axis. Negative axis values are interpreted in the context of the new, expanded rank.

The maximum rank is 8, so this method cannot be called on a tensor of rank 8.

Examples

Insert a dimension of `1` at a specified axis

var shape = new TensorShape(3, 4);
var unsqueezed0 = shape.Unsqueeze(0);
// Result: (1, 3, 4)
var unsqueezed1 = shape.Unsqueeze(-1);
// Result: (3, 4, 1)

Operators

operator ==(TensorShape, TensorShape)

Compares two TensorShapes for equality.

Declaration

public static bool operator ==(TensorShape a, TensorShape b)

Parameters

Type	Name	Description
TensorShape	a	The first TensorShape.
TensorShape	b	The second TensorShape.

Returns

Type	Description
bool	true if both shapes have the same rank and all dimensions are equal; otherwise, false.

Remarks

Two TensorShapes are equal if they have the same rank and all corresponding dimensions are equal. The comparison checks both rank and length first for efficiency before comparing individual dimensions.

Examples

Compare two `TensorShapes`

var shape1 = new TensorShape(2, 3, 4);
var shape2 = new TensorShape(2, 3, 5);
shape1 == shape1;  // Returns true
shape1 == shape2;  // Returns false

operator !=(TensorShape, TensorShape)

Compares two TensorShapes for inequality.

Declaration

public static bool operator !=(TensorShape a, TensorShape b)

Parameters

Type	Name	Description
TensorShape	a	The first TensorShape.
TensorShape	b	The second TensorShape.

Returns

Type	Description
bool	true if the shapes differ in rank or any dimension; otherwise, false.

Remarks

Two TensorShapes are not equal if they have different ranks or any corresponding dimensions differ.

Examples

Compare two `TensorShapes` for inequality

var shape1 = new TensorShape(2, 3, 4);
var shape2 = new TensorShape(2, 3, 5);
shape1 != shape2;  // Returns true
shape1 != shape1;  // Returns false