Image Sample

Converts a GPU texture into sampleable fields (scalar / vector / color) for field-based workflows. The bridge from raster content into the procedural field system.

Category: Fields Menu path: Fields > ImageSample

Ports

Port	Type	Direction	Description
image_in	imageRgba16f	input	Source image to sample
uv_in	vectorField	input	Optional per-sample lookup positions. When connected, replaces the per-sample coordinate with this field's output before sampling the image.
out	imageRgba16f	output	Pass-through of image_in (textures upstream are not modified — ImageSample is a read-only tap)
colorField	colorField	output	RGBA sampled per position
scalarField	scalarField	output	Single channel (luminance by default) sampled per position
vectorField	vectorField	output	Sobel gradient of the selected channel

Parameters

Param	Type	Default	Description
channel	enum	Luminance	Which channel drives scalarField / vectorField. Options: Luminance, Red, Green, Blue, Alpha.
filterMode	enum	Bilinear	Raster sampling filter. Bilinear = smooth, Nearest = blocky / pixel-accurate.
coordinateSpace	enum	Local	How consumer positions map to image coordinates. Local = origin-centered comp pixels (default). Comp = comp-space pixel coords (also origin-centered — (0,0) is the comp center, per the field coordinate convention). Normalized = [0, 1] UV. Ignored when uv_in is connected.
sampleResolution	scalar	1	Readback downscale factor. 1 = full-res, 4 = quarter-res per axis. Higher values cost less CPU per frame at the expense of sampling detail.

How It Works

ImageSample reads its input texture back to CPU once per frame (cached by an upstream-param hash, so it only re-reads when the content changes) and exposes the data as three field outputs. Consumers evaluate these fields at their own sample positions — so you can pipe an image into PointAttributes, ShapeAttributes, DistanceField compositions, etc.

The vectorField output is a Sobel gradient of the chosen channel — it points in the direction of steepest luminance increase, useful for edge-following flow.

uv_in override

When a vectorField is connected to uv_in, the field outputs sample the image at the positions provided by that vectorField rather than at the consumer's own position. This unlocks:

• Stained glass from an image: Voronoi.cellPosition → ImageSample.uv_in flattens each Voronoi cell to a single color pulled from the image at that cell's feature point.
• Texture warping / distortion: any vectorField can provide displaced lookup positions.
• Remapped projection: hand-crafted position fields (from Math / VectorMath nodes) can drive arbitrary UV layouts.

The vectorField is expected to output positions in the same coordinate space the ImageSample consumes (see coordinateSpace). Voronoi's cellPosition is designed for this — it emits origin-centered comp-pixel coords, matching coordinateSpace = Local.

Usage Examples

Basic: Image luminance as a field

Use any image, route ImageSample.scalarField into PointAttributes (target = Scale) on a Grid of points. Points scale based on the image's luminance at each grid position — an image-driven dot matrix.

Creative: Stained glass from image

Voronoi.cellPosition → ImageSample.uv_in; ImageSample.colorField → Output. Each Voronoi region takes on the image's color at that region's feature point.

Creative: Edge-following flow

ImageSample.vectorField → PointAdvect. Particles drift along luminance gradients — they accumulate at bright regions and flow around dark ones.

Tips

• sampleResolution is the main performance lever. Crank it up (4 or 8) if you're only driving sparse consumers like PointAttributes on a few hundred points.
• The out port is a pure passthrough of image_in — useful when you want to read an image AND keep it in the texture chain without duplicating the source.
• When uv_in is connected, coordinateSpace is bypassed — the upstream field fully determines sample positions.
• Changing the image upstream will invalidate downstream field caches (SimulationCache / SampleCache) automatically via content hashing.
• Field readbacks are budgeted at 128MB: on very large canvases (big comp × overscan) the raster is downsampled on the GPU before the CPU readback. Coordinate mapping accounts for the smaller raster, so sampling stays spatially correct.

Related Nodes

• Voronoi — provides cellPosition for per-cell image sampling
• DistanceField — shape → field (the geometry analog of image → field)
• PointAttributes — apply field data per-point
• UVRemap — texture-based distortion (GPU equivalent for fullscreen warps)