[API Proposal]: TensorPrimitives: convert Span<Byte> to Span<Float> and back

[vpenades]

Background and motivation

Working with images and tensors, it is fairly common to convert an array of bytes to an array of floats.

Also, in many cases the conversion requires some normalization or scaling, that is, byte values in the range of 0-255 are converted to float values in the range of 0-1

The usual operation is this:

var src = new byte[100];
var dst = new float[100];

for(int i=0; i < dst.Length; ++i)
{
   dst[i] = (float)src[i] / 255f;
}

Now, I don't know if there's faster way of doing this using SIMD, or any other exotic, platform specific mechanism, but if it doesn't exist now, it may exist in the future, so by using a system function, any current application may benefit from future improvements on the API.

Also, I don't know if this conversion already exists somewhere else in the APIs, I've looked for it without success. But certainly, I would expect such conversions to be available in TensorPrimitives.

My needs are limited to byte-float conversions, but certainly, other types may be included.

API Proposal

static class TensorPrimitives
{
   public static void ConvertToSingle(ReadOnlySpan<byte> src, Span<float> dst);
   public static void ConvertToScaledSingle(ReadOnlySpan<byte> src, Span<float> dst);

   public static void ConvertToByte(ReadOnlySpan<float> src, Span<byte> dst);
   public static void ConvertScaledToByte(ReadOnlySpan<float> src, Span<byte> dst);
}

API Usage

namespace System.Numerics.Tensors

var bytes = byte[100];
var floats = float[199];

TensorPrimitives.ConvertToSingle(bytes,floats); // converts bytes to floats in the range 0-255
TensorPrimitives.ConvertToScaledSingle(bytes,floats); // converts bytes to floats in the range 0-1

TensorPrimitives.ConvertToByte(floats, bytes); // converts floats in the range 0-255 to bytes in the range 0-255
TensorPrimitives.ConvertScaledToByte(floats,bytes); // converts floats in the range 0-1 to bytes in the range 0-255

Alternative Designs

No response

Risks

No response

[dotnet-policy-service[bot]]

Tagging subscribers to this area: @dotnet/area-system-numerics-tensors See info in area-owners.md if you want to be subscribed.

[stephentoub]

Converting between two different types is supported via the generic TensorPrimitives.ConvertTruncating, ConvertSaturating, and ConvertChecked methods. There's no built-in operation that currently combines that with the divide, but it can be done with a second call:

ReadOnlySpan<byte> bytes = RandomNumberGenerator.GetBytes(100);
Span<float> floats = new float[bytes.Length];

TensorPrimitives.ConvertTruncating(bytes, floats);
TensorPrimitives.Divide(floats, 255.0f, floats);

[vpenades]

No wonder I could not find these methods.... they're in the Net9 preview packages, is that right?

Anyway, given it's in preview, I would still include a byte to float conversion with divide: it's such a common operation that any future improvement would automatically be used by everybody, that is, imagine that some platform introduces a fast path for this exact operation...

[stephentoub]

they're in the Net9 preview packages, is that right?

Yes

[vpenades]

Looking at the code, I don't see that ConvertTruncating has any kind of vectorial acceleration code to convert byte to float. Right now, is there an advantage of using ConvertTruncating, over a plain loop?

[stephentoub]

Looking at the code, I don't see that ConvertTruncating has any kind of vectorial acceleration code to convert byte to float. Right now, is there an advantage of using ConvertTruncating, over a plain loop?

Not in what's merged, but that's just a matter of adding an additional path for these types, e.g. https://github.com/dotnet/runtime/pull/103820