ai.onnx.GridSample

ai.onnx · standard ONNX operator · ONNX opset ≥ 20

Description

Samples values from input tensor X at positions defined by a flow-field grid, producing output Y with spatial dimensions taken from grid. Grid coordinates are normalized to [-1, 1] over the input spatial extent; positions outside this range are handled according to padding_mode. Supports spatial (rank-4, NCHW) and volumetric (rank-5, NCDHW) inputs with linear, nearest, or cubic interpolation.

See the ONNX GridSample spec for the reference semantics.

Inputs

Outputs

Attributes

Default values (overridable per request):

Type constraints

Implementation variants

One implementation is selected per call from the device capabilities, the request shapes and the dtypes; these notes say what each one covers.

• nchw_rank4_channel_vector — Resolves the sampling coordinate once per pixel and reuses it across four channels, so one thread gathers from four channel planes instead of reading one coalesced. This amortizes the coordinate math across channels, trading a coalesced read for a scattered gather; adapters where scattered gathers are slow use the coalesced variant instead.
• nchw_rank4 — Portable scalar spatial sampling: one thread per output element, so reads stay coalesced within one channel plane. The route for every adapter whose gather throughput the channel vector would spend.
• ncdhw_rank5_channel_vector — Shares volumetric coordinates, padding and interpolation across a vector of channels; uses two lanes for two channels and four lanes otherwise, with masked tails and device-capped workgroups.
• ncdhw_rank5 — Portable scalar volumetric sampling for all interpolation and padding modes.

Files

• metadata.json — kernel metadata (id, digests, per-variant templates, provenance)
• manifest.json — the op contract (source of truth)
• test.json — correctness cases
• bench.json — benchmark cases
• grid-sample.wgsl.jinja
• grid-sample3d.wgsl.jinja

Use with @huggingface/kernels

npm install --save-exact @huggingface/kernels@0.0.1-preview.3

Required output shapes and logical data types are inferred from the supplied inputs and attributes; result tensors are allocated automatically.

The version: 1 option selects the published kernel contract; it is independent of any operator opset, contrib since_version, or model version. It follows the v1 branch as fixes land. To pin exact artifact bytes, pass a 40-character commit revision instead of version.

Replace each *Data placeholder with a typed array containing the corresponding input data.

import { getKernel } from "@huggingface/kernels";

const kernel = await getKernel("webgpu-kernels/ai.onnx.GridSample", { version: 1 });
const { y } = await kernel({
  x: { data: xData, shape: [1, 1, 2, 2] },
  grid: { data: gridData, shape: [1, 1, 3, 2] },
});