LoadImage

Loads an image from file and optionally linearize it. Images with bigger than 32-bit depth per channel are not allowed. The following extensions are supported: jpg, jpeg, png, tif, tiff, exr.

Wrap internally works only with linearized images. It allows to correctly perform math operations, which required by nodes like MergeImage, ExtrapolateImage, TransferTexture. For more info, check the Color Space section below.

Output

Image Loaded image

Parameters

File Name:

a file name to be loaded. Any sequence of # symbols will be replaced with the current file name.

File Color Space:

Autodetect from File: detects color space from file’s extension. If jpg, jpeg, or png, then assumme sRGB color space. If, however, a Linear image is stored in file with such extension, use an File Color Space: Linear explicitly
Linear: assume file is already linear and don’t change pixel values
sRGB: assume file is sRGB, then linearize it. May change the final pixel type of an image, check the section Linearization below

Pixel Type:

Auto: detects exact pixel type from file type. If image gets linerarized, the it has Half pixel type
Other: convert image to exact depth, check the table below

Reload:

resets cache and force reload image from disk

Pixel Types

Pixel Type	Supported Values	Common Name
8 bit integer	0 .. 255	uint8
16 bit integer	0 .. 65_535	uint16
32 bit integer	0 .. 4_294_967_295	uint32
16 bit floating	-65504.0 .. 5.96046448e-08 .. 65504.0, -inf, inf	half
32 bit floating	-3.40282e+38 .. 1.17549e-38 .. 3.40282e+38, -inf, inf	float

The following important notes must be taken into account:

All integer types are present in unsigned variant, so you can’t use or process negative integer values.

All floating types has much wider supported range, but in Wrap’s Viewport2D the only visible range is 0.0 .. 1.0

When converting between different pixel types, image color values will be accordingly scaled, and sometimes clamped to match the destination pixel type value range. See the note below for several examples.

Note

For example, converting originally float (32 bit floating) image into uchar (8 bit integer) will scale all the values in the range 0.0 .. 1.0 to the range 0 .. 255 and clamped all the values out of this range. For example, an original pixel with red value 1.5 (average white), will be seted just to 255, which is usual white. Correspontently, all originally negative values will be just set to black 0.

Note

Converting integer to float image will scale them from 0 .. 255 to 0.0 .. 0.1. Converting between integer types follows this rule as well. For example, white color will be scaled from uint16 65535 to uint32 4294967295, or to uint8 255.

Intermediate convertions may be used in nodes, such as MergeImage to work properly with different typed inputs.

Pixel Types Comparison

Whenever pixel types are compared for their bit-depth, the following rules applied:

Pixel type with lower bit-depth number (specified in the table above) is assumed to be lower

In case of equal bit-depth number, an integer pixel type is assumed to be lower

Note

Theese rules form the next lower-to-highest prior:

uint8 < uint16 < half < uint32 < float

Color Space

There is one case, when color space actually matters. Using any image, which contains values, instead of colors, such as height map or displacement map.

In this case you should:

Load it as usuall, but turn the File Color Space to Linear

In Viewport2D it will appear brighter, then needed.

Turn the Viewport2D Color Space param to the Linear as well, or just press 1.

Now image’s and viewport’s color spaces matches, and image will appear in correct way. It’s processing as well will be corrected.

In all other cases, you can left File Color Space to Autodetect from File

Linearization

Linearizing images on loading only matters, if original file has color space sRGB. Which mostly happen, when on disk it is written as 8-bit image, such as jpg, jpeg, or png. Shortly, sRGB color spaces shifts colors of an image a bit, to store darker values more precise.

As Wrap works with linearized images only, to process regular 8-bit images, it should convert them sRGB → Linear on loading and Linear → sRGB on saving. Due to low precision of 8-bit images, theese two sequential convertions may cause a colors loss, mostly in darker colors.

Note

To prevent precision loss while linearization, Load Image upconverts 8-bit images to half (16 bit floating). Other images (with original depth 16 or more) are not affected.