NatML
Search…
MLArrayFeature
class NatSuite.ML.Features.MLArrayFeature<T> : MLFeature, IMLEdgeFeature, IMLCloudFeature where T : unmanaged
This is a multidimensional array feature, a.k.a a tensor. Most models which accept tensors will accept an array feature in NatML.

Creating the Feature

The array feature can be created from a managed array (T[]), native array (NativeArray<T>), or native buffer (T*):

From a Managed Array

1
/// <summary>
2
/// Create an array feature.
3
/// </summary>
4
/// <param name="data">Feature data.</param>
5
MLArrayFeature (T[] data);
Copied!
An array feature can be created from a single array. When the feature is created with this constructor, its type will not have any shape information.
When a shapeless array feature is used for prediction with an MLModel, NatML will assume that its shape exactly matches what the model expects.
1
/// <summary>
2
/// Create an array feature.
3
/// </summary>
4
/// <param name="data">Feature data.</param>
5
/// <param name="shape">Feature shape.</param>
6
MLArrayFeature (T[] data, int[] shape);
Copied!
An array feature can be created with the feature data along with a corresponding shape. When this constructor is used, the element type of the feature is inferred from the generic type parameter T.
1
/// <summary>
2
/// Create an array feature.
3
/// </summary>
4
/// <param name="data">Feature data.</param>
5
/// <param name="type">Feature type.</param>
6
MLArrayFeature (T[] data, MLArrayType type);
Copied!
In rare cases where it is useful to fully specify the feature type, the constructor above can be used.

From a Native Array

The array feature provides variants of the managed array constructors where the data argument is a NativeArray<T>. This can be useful for working with certain performance-critical Unity API's like Burst:
1
/// <summary>
2
/// Create an array feature.
3
/// </summary>
4
/// <param name="data">Feature data.</param>
5
MLArrayFeature (NativeArray<T> data);
6
7
/// <summary>
8
/// Create an array feature.
9
/// </summary>
10
/// <param name="data">Feature data.</param>
11
/// <param name="shape">Feature shape.</param>
12
MLArrayFeature (NativeArray<T> data, int[] shape);
13
14
/// <summary>
15
/// Create an array feature.
16
/// </summary>
17
/// <param name="data">Feature data.</param>
18
/// <param name="type">Feature type.</param>
19
MLArrayFeature (NativeArray<T> data, MLArrayType type);
Copied!
These constructors create a view of the native array, resulting in no allocations.

From a Native Buffer

The array feature provides variants of the managed array constructors where the data argument is a typed native buffer. These can be useful for making predictions on arrays from native code or external libraries like OpenCV:
1
/// <summary>
2
/// Create an array feature.
3
/// </summary>
4
/// <param name="data">Feature data.</param>
5
MLArrayFeature (T* data);
6
7
/// <summary>
8
/// Create an array feature.
9
/// </summary>
10
/// <param name="data">Feature data.</param>
11
/// <param name="shape">Feature shape.</param>
12
MLArrayFeature (T* data, int[] shape);
13
14
/// <summary>
15
/// Create an array feature.
16
/// </summary>
17
/// <param name="data">Feature data.</param>
18
/// <param name="type">Feature type.</param>
19
MLArrayFeature (T* data, MLArrayType type);
Copied!
The native buffer type T must be unmanaged.
These constructors create a view of the native buffer, resulting in no allocations.

From an Edge Feature

1
/// <summary>
2
/// Create an array feature from an Edge ML feature.
3
/// Note that this does NOT take ownership of the Edge ML feature.
4
/// As such the Edge ML feature must be explicitly disposed by the client.
5
/// </summary>
6
/// <param name="feature">Edge ML feature. This MUST be an array feature.</param>
7
MLArrayFeature (MLEdgeFeature feature);
Copied!
An array feature can be created from an MLEdgeFeature. This constructor is useful for working with output prediction data from an MLEdgeModel when authoring a predictor:
1
// Make an Edge prediction
2
MLEdgeModel model = ...;
3
MLEdgeFeature outputFeature = model.Predict(...)[0];
4
// Create an array feature from an Edge array feature
5
var arrayFeature = new MLArrayFeature<float>(outputFeature);
Copied!
This constructor creates a view of the Edge feature data, resulting in no allocations.
The Edge ML feature MUST be an array feature.

From a Cloud Feature

1
/// <summary>
2
/// Create an array feature from a Cloud ML feature.
3
/// </summary>
4
/// <param name="feature">Cloud ML feature. This MUST be an array feature.</param>
5
MLArrayFeature (MLCloudFeature feature);
Copied!
An array feature can be created from an MLCloudFeature. This constructor is useful for working with output prediction data from an MLCloudModel when authoring a predictor:
1
// Make a Cloud prediction
2
MLCloudModel model = ...;
3
MLCloudFeature outputFeature = model.Predict(...)[0];
4
// Create an array feature from a Hub array feature
5
var arrayFeature = new MLArrayFeature<float>(outputFeature);
Copied!
This constructor deserializes and/or decodes the Cloud feature data.
The Cloud feature MUST be an array feature.

Inspecting the Feature

The array feature provides information about its shape.

Feature Type

1
/// <summary>
2
/// Feature type.
3
/// </summary>
4
MLFeatureType type { get; }
Copied!
Refer to the Inspecting the Feature section of the MLFeature class for more information.
The type is always an MLArrayType.

Feature Shape

1
/// <summary>
2
/// Feature shape.
3
/// </summary>
4
int[] shape { get; }
Copied!
The feature shape is a convenience property which provides the shape from the feature type.
The shape can be null if the feature was created with no shape.

Element Count

1
/// <summary>
2
/// Feature element count.
3
/// </summary>
4
int elementCount { get; }
Copied!
The element count is a convenience property which provides the element count from the feature type.
The elementCount will be zero when the feature does not have a shape.

Accessing Feature Data

The array feature provides accessors for reading and writing feature data.

Multi-Indexing

1
/// <summary>
2
/// Get or set a value at a specified multi-index.
3
/// </summary>
4
/// <param name="idx">Multi-index.</param>
5
T this [params int[] idx] { get; set; }
Copied!
The array feature provides support for multi-indexing. This is a common pattern for working with tensors in machine learning:
1
// With an array feature
2
var feature = new MLArrayFeature<float>(...);
3
// You can index across multiple dimensions
4
var logit = feature[0,12,29,1];
Copied!
Multiple indexing requires the array feature to have a valid shape.
The array feature does not perform bounds checking for performance, so make sure not to index incorrectly.
The array feature also supports linear indexing, in which case it accesses the elements of the feature assuming a flat shape:
1
// You can also index linearly, disregarding the shape
2
var logit = feature[392];
Copied!

Copying

1
/// <summary>
2
/// Copy feature data to an array.
3
/// </summary>
4
/// <param name="array">Destination array.</param>
5
/// <param name="startIndex">Start index to copy into destination array.</param>
6
/// <param name="length">Number of elements to copy. Pass `0` to use destination array length.</param>
7
void CopyTo (T[] array, int startIndex = 0, int length = 0);
Copied!
The array feature can copy its data to a buffer of the same type. There is also an overload that takes a NativeArray<T>:
1
/// <summary>
2
/// Copy feature data to a native array.
3
/// </summary>
4
/// <param name="array">Destination native array.</param>
5
/// <param name="startIndex">Start index to copy into destination array.</param>
6
/// <param name="length">Number of elements to copy. Pass `0` to use destination array length.</param>
7
void CopyTo (NativeArray<T> array, int startIndex = 0, int length = 0);
Copied!
Finally, there is an overload that accepts a raw pointer when working with native buffers:
1
/// <summary>
2
/// Copy feature data to a buffer.
3
/// </summary>
4
/// <param name="buffer">Destination buffer.</param>
5
/// <param name="length">Number of elements to copy.</param>
6
void CopyTo (T* buffer, int length);
Copied!
This method does not respect any permutations that have been applied to the array feature.

Converting to Array

1
/// <summary>
2
/// Convert the array feature to a flattened array.
3
/// </summary>
4
/// <returns>Result array.</returns>
5
T[] ToArray ();
Copied!
The array feature can copy its data into an array and return the array.
This method does not respect any permutations that have been applied to the array feature.

Viewing Operations

The array feature supports viewing operations. Each of these operations do not allocate any memory; they simply return a shallow feature that has the proper shape.

Permute

1
/// <summary>
2
/// Permute the dimensions of this array feature.
3
/// This operation is a generalization of the transpose operation.
4
/// </summary>
5
/// <param name="dims">Permuted dimensions.</param>
6
/// <returns>Array feature with permuted dimensions.</returns>
7
MLArrayFeature<T> Permute (params int[] dims);
Copied!
The array feature's dimensions can be permuted, allowing different dimensions to be swapped (like transposing):
1
// Create an array feature with shape (3,5)
2
var feature = new MLArrayFeature<float>(..., new [] { 3, 5 });
3
Debug.Log(feature.shape); // (3,5)
4
// Transpose it by permuting dimensions
5
var transposedFeature = feature.Permute(1, 0);
6
Debug.Log(transposedFeature.shape); // (5,3)
Copied!

View

1
/// <summary>
2
/// Create a view of this array feature with a different shape.
3
/// The element count of the new shape MUST match that of the feature.
4
/// </summary>
5
/// <param name="shape">New shape.</param>
6
/// <returns>Array feature with new shape.</returns>
7
MLArrayFeature<T> View (params int[] shape);
Copied!
The array feature supports creating a view of the feature data with a different shape:
1
// Create an array feature
2
var feature = new MLArrayFeature<float>(..., new [] { 5, 30 });
3
Debug.Log(feature.shape); // (5,30)
4
// View the feature with a different shape
5
var viewedFeature = feature.View(5, 10, 3);
6
Debug.Log(viewedFeature.shape); // (5,10,3)
Copied!
The element count of the view shape must match the element count of the feature.

Creating Edge Features

1
/// <summary>
2
/// Create an Edge ML feature that is ready for prediction with Edge ML models.
3
/// </summary>
4
/// <param name="featureType">Feature type used to create the Edge ML feature.</param>
5
/// <returns>Edge ML feature.</returns>
6
MLEdgeFeature IMLEdgeFeature.Create (in MLFeatureType type);
Copied!
INCOMPLETE.

Creating Cloud Features

1
/// <summary>
2
/// Create a Cloud ML feature that is ready for prediction with Cloud ML models.
3
/// </summary>
4
/// <param name="featureType">Optional feature type used to create the Cloud ML feature.</param>
5
/// <returns>Cloud ML feature.</returns>
6
MLCloudFeature IMLCloudFeature.Create (in MLFeatureType featureType = default);
Copied!
INCOMPLETE.