Struct DynamicTensorShape

Represents a tensor shape that can have dynamic dimensions or dynamic rank.

Inherited Members

Namespace: Unity.InferenceEngine

Assembly: Unity.InferenceEngine.dll

Syntax

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

Remarks

DynamicTensorShape describes tensor dimensions where some values may be unknown at compile time. Use it for model inputs with variable batch size, sequence length, or other runtime-determined dimensions. Non-negative dimension values are static. Use -1 for dynamic dimensions. Use DynamicOfRank(int) to create a shape with known rank but all dynamic dimensions. When isRankDynamic is true, the rank is unknown and rank cannot be accessed.

Additional resources

Examples

// Static shape: (1, 3, 224, 224)
var staticShape = new DynamicTensorShape(1, 3, 224, 224);

// Dynamic shape with unknown dimension 0
var dynamicBatch = new DynamicTensorShape(-1, 3, 224, 224);

// All dimensions dynamic with rank 2
var shape = DynamicTensorShape.DynamicOfRank(2);

Constructors

DynamicTensorShape(int)

Initializes and returns an instance of DynamicTensorShape with rank 1.

Declaration

public DynamicTensorShape(int d0)

Parameters

Type	Name	Description
int	d0	The dimension of axis 0.

Remarks

Dimensions with non-negative values are static; use -1 for dynamic dimensions.

Examples

Create a shape of rank 1 (a vector with dynamic length).

var shape = new DynamicTensorShape(-1);

DynamicTensorShape(int, int)

Initializes and returns an instance of DynamicTensorShape with rank 2.

Declaration

public DynamicTensorShape(int d0, int d1)

Parameters

Type	Name	Description
int	d0	The dimension of axis 0.
int	d1	The dimension of axis 1.

Remarks

Dimensions with non-negative values are static; use -1 for dynamic dimensions.

DynamicTensorShape(int, int, int)

Initializes and returns an instance of DynamicTensorShape with rank 3.

Declaration

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

Parameters

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

Remarks

Dimensions with non-negative values are static; use -1 for dynamic dimensions.

DynamicTensorShape(int, int, int, int)

Initializes and returns an instance of DynamicTensorShape with rank 4.

Declaration

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

Parameters

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

Remarks

Dimensions with non-negative values are static; use -1 for dynamic dimensions.

DynamicTensorShape(int, int, int, int, int)

Initializes and returns an instance of DynamicTensorShape with rank 5.

Declaration

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

Parameters

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

Remarks

Dimensions with non-negative values are static; use -1 for dynamic dimensions.

DynamicTensorShape(int, int, int, int, int, int)

Initializes and returns an instance of DynamicTensorShape with rank 6.

Declaration

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

Parameters

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

Remarks

Dimensions with non-negative values are static; use -1 for dynamic dimensions.

DynamicTensorShape(int, int, int, int, int, int, int)

Initializes and returns an instance of DynamicTensorShape with rank 7.

Declaration

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

Parameters

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

Remarks

Dimensions with non-negative values are static; use -1 for dynamic dimensions.

DynamicTensorShape(int, int, int, int, int, int, int, int)

Initializes and returns an instance of DynamicTensorShape with rank 8.

Declaration

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

Parameters

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

Remarks

Dimensions with non-negative values are static; use -1 for dynamic dimensions.

DynamicTensorShape(ReadOnlySpan<int>)

Initializes and returns an instance of DynamicTensorShape from a span of dimension values.

Declaration

public DynamicTensorShape(ReadOnlySpan<int> shape)

Parameters

Type	Name	Description
ReadOnlySpan<int>	shape	The dimensions as a span of integers.

Remarks

Values of -1 represent dynamic dimensions. Non-negative values are static. The span length must not exceed maxRank.

Examples

Create a shape from a span of dimensions (e.g. from an array or stack-allocated buffer).

var dims = new[] { -1, 3, 224, 224 };
var shape = new DynamicTensorShape(dims.AsSpan());

Exceptions

Type	Condition
AssertionException	Thrown when the span length exceeds the maximum rank.

DynamicTensorShape(DynamicTensorShape)

Initializes a shape as a copy of another DynamicTensorShape.

Declaration

public DynamicTensorShape(DynamicTensorShape other)

Parameters

Type	Name	Description
DynamicTensorShape	other	The shape to copy.

Remarks

Copies rank and all dimensions (including dynamic ones) from the source shape.

Examples

var original = new DynamicTensorShape(-1, 3, 224, 224);
var copy = new DynamicTensorShape(original);

DynamicTensorShape(TensorShape)

Initializes a shape from a static TensorShape.

Declaration

public DynamicTensorShape(TensorShape other)

Parameters

Type	Name	Description
TensorShape	other	The static tensor shape to copy.

Remarks

All dimensions from the source shape are copied as static. Use when converting from a fully known TensorShape to a DynamicTensorShape for use with the Functional API.

Examples

Convert a static TensorShape to DynamicTensorShape.

var staticShape = new TensorShape(3, 4, 5, 6);
var dynamicShape = new DynamicTensorShape(staticShape);

Properties

isRankDynamic

Whether the shape has a dynamic rank.

Declaration

public bool isRankDynamic { get; }

Property Value

Type	Description
bool	true if the shape has a dynamic rank. Otherwise false.

Remarks

When true, the number of dimensions is unknown and rank cannot be accessed.

rank

The rank of the shape (number of dimensions). For example, shape (5) has rank 1, and shape (7, 3, 5) has rank 3.

Declaration

public int rank { get; }

Property Value

Type	Description
int	The rank of the shape.

Remarks

Cannot be accessed when isRankDynamic is true. Check isRankDynamic before accessing.

Exceptions

Type	Condition
AssertionException	Thrown when the shape has dynamic rank.

Methods

DynamicOfRank(int)

Creates a shape with the given rank and all dimensions dynamic.

Declaration

public static DynamicTensorShape DynamicOfRank(int rank)

Parameters

Type	Name	Description
int	rank	The rank (number of dimensions). Must be between `0` and maxRank (`8`).

Returns

Type	Description
DynamicTensorShape	The created shape with all dimensions dynamic.

Remarks

Use Set(int, int) or SetDynamic(int) to configure individual dimensions after creation.

Examples

// Create a shape with dynamic batch dimension representing a texture in the NCHW format.
var shape = DynamicTensorShape.DynamicOfRank(4);
shape.Set(0, -1);  // batch
shape.Set(1, 3);   // channels
shape.Set(2, 224); // height
shape.Set(3, 224); // width

Exceptions

Type	Condition
AssertionException	Thrown when rank is out of range.

Equals(object)

Determines whether the specified object is equal to this shape.

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 DynamicTensorShape equal to this shape. Otherwise false.

Overrides

ValueType.Equals(object)

Remarks

Returns false for null or non-DynamicTensorShape types. Uses the same equality logic as operator ==(DynamicTensorShape, DynamicTensorShape).

Examples

var shape = new DynamicTensorShape(2, 3, 4);
bool same = shape.Equals(otherShape);

Get(int)

Returns the dimension at a given axis as an integer.

Declaration

public int Get(int axis)

Parameters

Type	Name	Description
int	axis	The axis index (0-based, or negative for reverse indexing).

Returns

Type	Description
int	The dimension value at the axis, or `-1` for dynamic dimensions.

Remarks

Dynamic dimensions return -1. Supports negative axis indexing (e.g. -1 for the last axis).

Examples

var shape = new DynamicTensorShape(-1, 3, 224);
int batch = shape.Get(0);   // -1 (dynamic)
int channels = shape.Get(1); // 3
int last = shape.Get(-1);    // 224 (last axis)

Exceptions

Type	Condition
AssertionException	Thrown when the axis is out of bounds.

GetHashCode()

Serves as the default hash function.

Declaration

public override int GetHashCode()

Returns

Type	Description
int	The calculated hash code.

Overrides

ValueType.GetHashCode()

Remarks

The hash code is based on rank and all dimension values.

Examples

Use with hash-based collections such as HashSet or Dictionary.

var shape1 = new DynamicTensorShape(1, 3, 224, 224);
var shape2 = new DynamicTensorShape(1, 3, 224, 224);
var seen = new HashSet<DynamicTensorShape> { shape1, shape2 };

IsStatic()

Checks whether the shape is fully static and can be converted to a TensorShape.

Declaration

public bool IsStatic()

Returns

Type	Description
bool	true if the shape has static rank and all dimensions are static. Otherwise false.

Remarks

A shape is static when it has a known rank and every dimension has a known value (no -1 or dynamic dims). Call this before ToTensorShape() to avoid assertion failures.

Examples

var shape = new DynamicTensorShape(1, 3, 224, 224);
if (shape.IsStatic())
    var staticShape = shape.ToTensorShape();

Ones(int)

Creates a shape with the given rank and all dimensions equal to 1.

Declaration

public static DynamicTensorShape Ones(int rank)

Parameters

Type	Name	Description
int	rank	The rank of the shape. The maximum rank is maxRank (`8`).

Returns

Type	Description
DynamicTensorShape	A shape of the form `(1, 1, ..., 1)` with the given rank.

Remarks

Use for broadcasting or as a base shape to modify with Set(int, int). Rank 0 gives a scalar shape. Rank 1 gives (1).

Examples

Create scalar and vector shapes of ones.

var scalarShape = DynamicTensorShape.Ones(0);  // ()
var vectorShape = DynamicTensorShape.Ones(1);  // (1)

Exceptions

Type	Condition
AssertionException	Thrown when rank is out of range.

Set(int, int)

Sets the dimension at a given axis.

Declaration

public void Set(int axis, int dimension)

Parameters

Type	Name	Description
int	axis	The axis index to set.
int	dimension	The dimension value. Use `-1` for a dynamic dimension.

Remarks

Use -1 for a dynamic dimension. Supports negative axis indexing.

Examples

var shape = DynamicTensorShape.DynamicOfRank(3);
shape.Set(0, -1); // dynamic
shape.Set(1, 3);
shape.Set(2, 224);
// shape is (?, 3, 224)

SetDynamic(int)

Sets the dimension at a given axis to be dynamic.

Declaration

public void SetDynamic(int axis)

Parameters

Type	Name	Description
int	axis	The axis index to make dynamic.

Remarks

Equivalent to Set(int, int) with -1. Use when converting a previously static dimension to dynamic.

Examples

var shape = new DynamicTensorShape(-1, 3, 224, 224);
shape.SetDynamic(1); // make dimension 1 dynamic (?, ?, 224, 224)

ToIntArray()

Returns the shape as an integer array.

Declaration

public int[] ToIntArray()

Returns

Type	Description
int[]	The shape as an integer array, or null when the rank is dynamic.

Remarks

Returns null when isRankDynamic is true. Dynamic dimensions are represented as -1 in the array.

Examples

var shape = new DynamicTensorShape(-1, 3, 224, 224);
int[] dims = shape.ToIntArray();
// dims is [-1, 3, 224, 224]

ToString()

Returns a string representation of the shape.

Declaration

public override string ToString()

Returns

Type	Description
string	The string representation, e.g. `(d0, 3, 224, 224)` or `(1, 3, 224, 224)`.

Overrides

ValueType.ToString()

Remarks

Dynamic dimensions are shown as ? followed by a parameter index. Dynamic rank returns ?.

Examples

var shape = new DynamicTensorShape(1, 3, -1, -1);
var string = shape.ToString(); // "(1, 3, ?, ?)"

ToTensorShape()

Converts the shape to a TensorShape.

Declaration

public TensorShape ToTensorShape()

Returns

Type	Description
TensorShape	The converted static tensor shape.

Remarks

Call IsStatic() first to ensure the shape is fully static. Fails when the shape has dynamic rank.

Examples

var dynamicShape = new DynamicTensorShape(-1, 3, 224, 224);
if (dynamicShape.IsStatic())
    TensorShape staticShape = dynamicShape.ToTensorShape();

Exceptions

Type	Condition
AssertionException	Thrown when the shape has dynamic rank.

Operators

operator ==(DynamicTensorShape, DynamicTensorShape)

Returns true if two shapes have the same rank and, for every dimension, the dimensions are either equal or at least one of them is dynamic.

Declaration

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

Parameters

Type	Name	Description
DynamicTensorShape	a	The first shape to compare.
DynamicTensorShape	b	The second shape to compare.

Returns

Type	Description
bool	true if the shapes are equal. Otherwise false.

Remarks

Returns false when either shape has dynamic rank.

Examples

var a = new DynamicTensorShape(-1, 3, 224, 224);
var b = new DynamicTensorShape(1, 3, 224, 224);
bool equal = (a == b); // true

operator !=(DynamicTensorShape, DynamicTensorShape)

Returns true if two shapes are not equal.

Declaration

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

Parameters

Type	Name	Description
DynamicTensorShape	a	The first shape to compare.
DynamicTensorShape	b	The second shape to compare.

Returns

Type	Description
bool	true if the shapes are not equal. Otherwise false.

Remarks

Returns true when either shape has dynamic rank, when ranks differ, or when any dimensions are static and differ.

Examples

var a = new DynamicTensorShape(-1, 3, 224);
var b = new DynamicTensorShape(1, 3, 224);
bool notEqual = (a != b); // false