LearningModelBinding.Bind Method

  • Reference

Definition

Namespace:
Windows.AI.MachineLearning

Overloads

Bind(String, Object)

Bind a value to the named feature.
Bind(String, Object, IPropertySet)

Bind a value to the named feature using properties to control the binding.

Bind(String, Object)

Edit

Bind a value to the named feature.

public:
 virtual void Bind(Platform::String ^ name, Platform::Object ^ value) = Bind;
/// [Windows.Foundation.Metadata.Overload("Bind")]
void Bind(winrt::hstring const& name, IInspectable const& value);
[Windows.Foundation.Metadata.Overload("Bind")]
public void Bind(string name, object value);
function bind(name, value)
Public Sub Bind (name As String, value As Object)

Parameters

name
String

Platform::String

winrt::hstring

The name of the feature.

value
Object

Platform::Object

IInspectable

The value to bind.

Attributes
OverloadAttribute

Examples

The following example retrieves the first input and output features, creates an output frame, binds the input and output features, and evaulates.

private async Task EvaluateModelAsync(
    VideoFrame _inputFrame, 
    LearningModelSession _session, 
    IReadOnlyList<ILearningModelFeatureDescriptor> _inputFeatures, 
    IReadOnlyList<ILearningModelFeatureDescriptor> _outputFeatures,
    LearningModel _model)
{
    ImageFeatureDescriptor _inputImageDescription;
    TensorFeatureDescriptor _outputImageDescription;
    LearningModelBinding _binding = null;
    VideoFrame _outputFrame = null;

    try
    {
        // Retrieve the first input feature which is an image
        _inputImageDescription =
            _inputFeatures.FirstOrDefault(feature => feature.Kind == LearningModelFeatureKind.Image)
            as ImageFeatureDescriptor;

        // Retrieve the first output feature which is a tensor
        _outputImageDescription =
            _outputFeatures.FirstOrDefault(feature => feature.Kind == LearningModelFeatureKind.Tensor)
            as TensorFeatureDescriptor;

        // Create output frame based on expected image width and height
        _outputFrame = new VideoFrame(
            BitmapPixelFormat.Bgra8, 
            (int)_inputImageDescription.Width, 
            (int)_inputImageDescription.Height);

        // Create binding and then bind input/output features
        _binding = new LearningModelBinding(_session);

        _binding.Bind(_inputImageDescription.Name, _inputFrame);
        _binding.Bind(_outputImageDescription.Name, _outputFrame);

        // Evaluate and get the results
        var results = await _session.EvaluateAsync(_binding, "test");
    }
    catch (Exception ex)
    {
        StatusBlock.Text = $"error: {ex.Message}";
        _model = null;
    }
}

Remarks

Windows Server

To use this API on Windows Server, you must use Windows Server 2019 with Desktop Experience.

Thread safety

This API is thread-safe.

Applies to

Bind(String, Object, IPropertySet)

Edit

Bind a value to the named feature using properties to control the binding.

public:
 virtual void Bind(Platform::String ^ name, Platform::Object ^ value, IPropertySet ^ props) = Bind;
/// [Windows.Foundation.Metadata.Overload("BindWithProperties")]
void Bind(winrt::hstring const& name, IInspectable const& value, IPropertySet const& props);
[Windows.Foundation.Metadata.Overload("BindWithProperties")]
public void Bind(string name, object value, IPropertySet props);
function bind(name, value, props)
Public Sub Bind (name As String, value As Object, props As IPropertySet)

Parameters

name
String

Platform::String

winrt::hstring

The name of the feature to which to bind.

value
Object

Platform::Object

IInspectable

The value to bind to the feature.

props
IPropertySet

A property map with key-value pairs describing the binding's tensorization and detensorization behavior. For more details, see the Remarks section.

Attributes
OverloadAttribute

Remarks

These are the valid key-value pairs for the props parameter:

Name Value Description
BitmapBounds PropertyType.UInt32Array When binding an input, the BitmapBounds property specifies cropping boundaries. The cropped image will be extracted and used as the input for performing inference.

When binding an output, the BitmapBounds property specifies boundaries for a target output region. The result of inference will be written to the target output region within the bound image.

The BitmapBounds property is specified as a UInt32 array with the values [left, top, width, height].

This property takes effect only when binding an ImageFeatureValue.
BitmapPixelFormat PropertyType.Int32 When binding an input or output, the BitmapPixelFormat property specifies the pixel format intended by the model author for a particular feature value. When the Image.BitmapPixelFormat metadata is missing from the ONNX model's Image metadata, it can be specified at runtime by using this property. Bound images will be automatically converted to the specified pixel format for consumption by the model.

The BitmapPixelFormat must be specified as an Int32 value corresponding to values in the Windows.Graphics.Imaging.BitmapPixelFormat enumeration. Currently the following values are supported:
  • BitmapPixelFormat.Rgba8
  • BitmapPixelFormat.Bgra8
  • BitmapPixelFormat.Gray8
This property takes effect only when binding an ImageFeatureValue.
DisableTensorCpuSync PropertyType.Boolean When binding an output tensor backed by an ID3D12Resource, the DisableTensorCpuSync property can be used to prevent copying the GPU/NPU output back to a CPU tensor. By default, the LearningModelSession.Evaluate API call is a blocking call, and will ensure that inference results are available on the CPU post-completion.

In certain GPU/NPU evaluation scenarios, it's desirable to keep inference results on the GPU/NPU; and copying the results back to the CPU is unnecessary and slower. To avoid that copy, enable the DisableTensorCpuSync property during binding.

This property takes effect only when binding an ITensor or its concrete types (that is, TensorFloat).

This property was introduced in Windows 11, version 21H2 (10.0; Build 22000).
PixelRange PropertyType.Int32 When binding an input or output, the PixelRange property specifies the normalization range intended by the model author for a particular feature value. When the Image.NominalPixelRange metadata is missing from the ONNX model's Image metadata, it can be specified at runtime by using this property. Bound images will be automatically converted to the specified normalized range for consumption by the model.

The PixelRange must be specified as an Int32 value corresponding to values in the Windows.AI.MachineLearning.LearningModelPixelRange enumeration.

This property takes effect only when binding an ImageFeatureValue.

Windows Server

To use this API on Windows Server, you must use Windows Server 2019 with Desktop Experience.

Thread safety

This API is thread-safe.

Applies to