Sample a texture file on disk.

File Paths

Multiple tokens for path resolution are supported.

UDIM and other texture-atlas file name patterns are supported:

• filename_<UDIM>.tif
• • Will look for file on disk of the form : filename_1001.tif
• filename_<uvtile>.tif
• • Will look for file on disk of the form : filename_u0_v0.tif

Environment variables in paths are supported:

• ${CURRENT_SHOT_RENDERS}/textures/filename.exr, where ${CURRENT_SHOT_RENDERS} is an environment variable.

Frame number is supported for animation (see frame).

• Use # to include the input frame number. The number of occurences of # determines the amount of padding. For example, file.####.jpg resolves to file.0042.jpg on frame 42.

All of these can be used together, in this example an animated UDIM texture specified with an environment variable.

• ${CURRENT_SHOT}/filename.<UDIM>.####.exr.

The order of operations for resolution is environment variables, then frame resolution, then texture atlases (such as UDIM). This means UDIM or frame tokens can be specified using environment variables.

Sampling behaviors

Sampling UDIM and other texture-atlas formats (here referred to simply as UDIM) have a slightly different behavior from single images. These differences have to do with how out-of-bounds samples work.

Single images use "clamp" style wrapping for out of bounds samples. This means out of bounds pixels will return the closest pixel on the image, giving the appearance that the image's edge pixels are stretched beyond the UV grid.

UDIM patterns are stricter with sampling. A location outside of the [0-1) are considered to belong to other image tiles. Therefore samples that belong to tiles which are missing will return zero values on samples. Note that this means that samples on UDIM images must be within the [0-1) value, samples on 1.0 will be interpreted as belonging to the next tile.

Inputs

filepath

The path to the image file that will be read and sampled.

uvs

The list of uv coordinates where to sample the texture.

file_color_space

The colorspace of the file. If left as the default empty string the node will attempt to determine the colorspace automatically using OpenColorIO. The pixel data will be converted from this colorspace to the scene-referred "working colorspace" (also known as the "rendering colorspace"). Use "raw" to bypass any colorspace conversion.

sampling

The sampling strategy:

• Closest: Closest texel, meaning no pixel values are blended. This can appear pixelated when samples are denser than the image resolution.
• Bilinear: Bilinear interpolation within the texture. This is a linear blend between the four pixels, where a coordinate exactly at the center of the pixel is the pixel value.
• Bicubic: Bicubic interpolation within the texture. This is curved interpolation where pixel values blend between the closest 16 values. This is smoother and sampling at the center of the pixel will not reproduce that exact value.

frame

The frame number of an image sequence to read. If the filepath contains an image sequence token (such as file.####.jpg), the frame number will be substituted there. time.frame may be connected here to drive the frame of an image sequence to read.

Outputs

sampled_data

The sampled data, converted to floating point RGBA values, and stored in a 1D array.

success

Outputs true if the file was read successfully, and false otherwise. Note that this only returns good values for non-UDIM images. If some pixels are out of bounds that still counts as success.

With UDIM images, success is always true, rather tahn searching on disk for any file that might match the pattern.