Image Source

Loads a still image file and outputs it as a GPU texture in Caddis's linear-light working format.

Category: Source Menu path: Source > Image Source

Ports

Port	Type	Direction	Description
out (Image)	imageRgba16f	output	The loaded image, placed into the composition canvas

Parameters

Param	Type	Default	Description
path	string	""	Absolute path to the image file. Accepts PNG, JPEG, TIFF, WebP, BMP, GIF, and EXR / HDR. 16-bit and float sources (EXR, 16-bit PNG/TIFF) decode at full precision — high-dynamic-range values above 1.0 are preserved, not clamped.
colorSpace	enum	Auto	How to interpret the file's bytes before upload. Auto picks based on extension (.exr / .hdr → Linear, everything else → sRGB). sRGB applies the sRGB→linear gamma curve. Linear skips the curve — use for already-linear sources to avoid double-decoding.

How It Works

ImageSource decodes the image file from disk, converts it into Caddis's linear-light working format (Rgba16Float), and places the result centered in the composition canvas at native resolution. The image retains its original pixel dimensions regardless of the composition size.

Color space handling. Compositing happens in linear light, but most image files (PNG, JPEG, etc.) store their pixels with the sRGB gamma curve applied. ImageSource undoes that curve via a lookup table during upload so the working values are physically correct. EXR / HDR files are already linear and the curve would double-decode them — set colorSpace to Linear (or use Auto, which detects from extension) to skip the conversion.

The decoded image is cached by (file path, mtime, colorSpace). Editing the file on disk or switching color space invalidates the cache on the next render. A separate resolution-independent decode cache means quality level changes (Draft / Preview / Full) and overscan shifts reuse the decoded pixels without re-reading from disk.

Usage Examples

Basic: Import a photo

1. Drag an image file from the Assets panel into the node graph, or add an Image Source node from the context menu
2. Set the path parameter (use the file picker or drag from Assets)
3. Connect out to a Transform2D node to position it, then to Output

A typical image layer chain looks like: Image Source → Transform2D → Output.

EXR / HDR footage

Set colorSpace to Linear (or leave at Auto — .exr is detected automatically). The source values pass through unchanged into the linear working buffer, so any downstream color grade operates on true scene values instead of a gamma-mangled approximation.

Compositing multiple images

Add several image layers, each with its own Image Source → Transform2D → Output chain. Use the layer stack and blend modes on each Output node to composite them together. Adjust Transform2D position and scale to arrange images within the composition.

Tips

• Dragging an image from the Assets panel onto the timeline creates a new layer with the Image Source → Transform2D → Output chain already wired up.
• An empty path produces no output (transparent). The node is effectively a no-op until a valid file path is set.
• The image is always centered in the composition. Use Transform2D for all positioning and cropping.
• File modification time is tracked — if you update the image on disk in an external editor, Caddis picks up the change automatically.
• colorSpace is a metadata setting, not a conversion: switching sRGB ↔ Linear re-interprets the same source bytes, so the displayed image will look different (correctly so).
• ImageSource has no time dependency. The same image is output on every frame, which caches efficiently and costs nearly nothing after the first decode.

Related Nodes

• VideoSource — time-varying video frame extraction
• ImageSequenceSource — play a folder of numbered frames as one time-based source
• VectorSource — load an SVG as native shape geometry instead of pixels
• Transform2D — positions the image in the composition
• LayerSource — references another layer's rendered output instead of a file