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.
exrLayer	string	"" (Auto)	Render Pass — which channel group of a multi-layer EXR to show. Rendered as a dropdown that only appears for EXRs carrying 2+ selectable passes; empty means Auto (the beauty-pass pick).

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.

Layered / multi-part EXR. Files whose channels live inside a named render pass — Blender's "OpenEXR MultiLayer" (ViewLayer.Combined.R), multi-part files, compositor File Output passes — load automatically: Caddis picks bare R/G/B/A channels when present, otherwise the beauty pass (Combined, beauty, rgba), preferring passes that carry alpha, before falling back to the first RGBA-like pass (a status-console note names the pass it used). Luminance-only (Y) EXRs load as grayscale. All EXR compressions are supported, including DWAA/DWAB. A file that can't be decoded at all reports the reason in the status console instead of rendering transparent.

Render Pass selector. When the file carries two or more render passes, a Render Pass dropdown appears in Properties listing every selectable pass — pick Emission, a cryptomatte, an AO pass, anything with RGB or luminance channels (prefix segments shared by every pass, like Blender's ViewLayer., are trimmed from the labels). Auto (the default) uses the beauty-pass pick above; the dropdown names which pass Auto resolves to. The selector hides itself for non-EXR sources and single-pass files. If the file is later re-rendered without the selected pass, Caddis falls back to Auto and says so in the status console.

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