NL Nodes Artist Guide

Artist path

Quick Start

1

Set shot context

Open NL Workflow, fill the project, shot or asset, resolution, frame range, FPS, and project path, then use Apply & Close. This context feeds helper nodes and output naming.

2

Read the plate or reference

Use NL Read for stills, sequences, videos, masks, or uploaded inputs. Keep color inputs in the intended source colorspace, then preview through the selected workflow view.

3

Preview and edit

Use NL Preview for managed viewing and NL Edit when a quick paint or mask touch-up is faster than leaving ComfyUI.

4

Write the result

Use NL Write for versioned EXR output, optional PNG previews, movies, and comparison renders. The workflow context keeps paths and names consistent.

Context first

Workflow Context

NL Workflow panel with project, episode, scene, shot, task, resolution, frame range, project path, OCIO, and recent context controls. — The NL Workflow panel stores the current shot context for this graph.

Artists should start here. The panel is not a graph node; it is workflow-level state that NL helper nodes and IO nodes read when they execute.

Project, scene, shot/asset, task: production identity used by helpers, ledger rows, and output metadata.
Width, height, FPS, start, end: the render format and timeline range used by context helper nodes.
Project path: the root used by NL Write. Point it at the shot Comfy folder when possible.
Color Management: project OCIO config, display, view, and input policy for managed IO and previews.
Recent contexts: quick access to recently used shots or assets.

Daily graph work

Read, Preview, Write

ComfyUI canvas with NL Read, NL Preview, NL Write, NL Edit, NL Merge, NL Shuffle, and NL Constant Color nodes. — Core NL nodes shown in a clean ComfyUI canvas for reference.

The core loop is usually NL Read into your graph, NL Preview when you need a managed viewer, and NL Write at the end.

NL Read accepts stills, sequences, videos, masks, and uploaded inputs. It can sample, trim, reverse, resize, and preview without changing the emitted tensor unless the controls say so.
NL Preview is a display/output node. It is useful for color, mask, RGBA, A/B comparison, and comparison reveal views.
NL Write is EXR-first by default, with optional PNG previews, MP4/MOV sequence outputs, comparison frames, and metadata sidecars.

Color and comp

Color And Compositing

NL color tools are meant to keep artist previews readable while preserving predictable working-space data through the graph.

Managed previews

Use preview_colorspace to choose how an image is displayed. A preview transform is for viewing; it should not be treated as the final tensor unless a transform node says so.

Explicit transforms

Use NL OCIO Convert, NL Linear To Log, and NL Log To Linear when the graph really needs converted image data.

Nuke-style channel work

NL Merge and NL Shuffle provide familiar A/B image operations, masks, mattes, channel routing, and image-info metadata pass-through.

Paint and mask

Editing

NL Edit modal with mask and RGB layers, combined/RGB/mask views, brush and erase tools, brush size, undo, redo, clear, cancel, and save. — NL Edit is a focused paint and mask modal for quick fixes inside ComfyUI.

NL Edit is for quick comp notes, rough masks, fixes, and hand-painted guide data. Fetch upstream input first when possible, then open the editor.

Layer: choose whether strokes affect the RGB layer or mask layer.
View: switch between combined, RGB, and mask previews.
Tool: brush adds strokes; erase removes them from the selected layer.
Export to NL Read: turns the saved edit output into a new readable source node.

Top-bar panels

Top-Bar Tools

NL Tools menu listing NL Model Manager, NL Templates, NL Subgraphs, NL Cost Ledger, Copy Workflow, and Configuration. — NL Tools groups the main NL panels and utility actions.

NL Configuration panel showing username, UI text size, automatic ShotGrid login status, and dependency status. — Configuration stores the username and shared UI/dependency settings.

NL Model Manager panel showing workflow model scan, local and network availability, cache size, auto-prune, and localization actions. — Model Manager compares network models against local cache.

NL Templates panel with tag filters, template cards, poster images, load buttons, versions, and sorting controls. — Templates is the shared workflow library for starting points and reusable setups.

NL Subgraphs panel with filters, blueprint library, inspector, inputs, outputs, controls, and add-to-canvas action. — Subgraphs inserts reusable blueprint blocks into the active graph.

NL Cost Ledger panel showing source toggle, date filters, project filters, cost summary, and ledger rows. — Cost Ledger tracks API usage by project, shot or asset, user, and model.

Reference

Node Reference

The cards below cover the registered NL Nodes in this repository. Input and output names were checked against the loaded ComfyUI object info during this documentation pass.

NOLABEL / IO

NL Read

NOLABEL/IO

Reads stills, image sequences, videos, masks, and uploaded inputs. Use it when media enters the graph.

Artist controls: source, frame sampling, range, mask mode, reverse, resize, input colorspace, preview colorspace.
Outputs: image, mask, inverted_mask, frame_count, resolved_path, image_info_json.

NL Write

NOLABEL/IO

Writes final images or sequences using workflow context. Use it at the end of an artist graph.

Artist controls: single or sequence mode, base name, output colorspace, preview mode, save mode, frame range, MP4/MOV options.
Inputs: images, mask, comparison_images, image_info_json.

NL Image Info Debug

NOLABEL/IO

Pretty-prints image metadata from NL Read. Use it when color interpretation or source metadata looks wrong.

Input: image_info_json.
Outputs: source_path, detected_color_space, working_color_space, is_data, pretty_json.

NOLABEL / Workflow

NL Resolution

NOLABEL/Workflow

Outputs the width and height stored in NL Workflow. Use it to drive generators, resizes, or utility nodes.

NL FPS

NOLABEL/Workflow

Outputs workflow FPS as float and integer values. Use it for sequence, video, or timing nodes.

NL Frame Range

NOLABEL/Workflow

Outputs start frame, end frame, and frame count from the active workflow context.

NL Project Path

NOLABEL/Workflow

Outputs the project path saved in the workflow panel. Use it when custom nodes need the shot folder.

NL Workflow Color Context

NOLABEL/Workflow

Outputs the resolved OCIO config, working space, display, view, input policy, and status JSON.

NL Context Debug

NOLABEL/Workflow

Outputs the cached workflow context JSON. Use it for diagnosis, not normal artist graphs.

NOLABEL / Color

NL Preview

NOLABEL/Color

Managed viewer/output node for images, masks, RGBA, comparisons, and comparison reveal.

Inputs: image, mask, comparison_images, image_info_json.
Outputs: image, mask, image_info_json.

NL OCIO Convert

NOLABEL/Color

Converts image tensors between explicit OCIO colorspaces and updates image_info_json.

NL Linear To Log

NOLABEL/Color

Converts scene-linear image data into the configured compositing log role.

NL Log To Linear

NOLABEL/Color

Converts compositing log data back into the configured scene-linear role.

NL Merge

NOLABEL/Color

Nuke-inspired A/B image merge with optional A/B mattes, effect mask, canvas behavior, invert mask, and mix.

NL Shuffle

NOLABEL/Color

Routes RGB and alpha/mask channels from A, B, black, or white into a new image and mask.

Deprecated: NL To Model Space

NOLABEL/Color/Deprecated

Legacy model-space conversion node kept for old workflows. Prefer explicit OCIO/color nodes in new setups.

Deprecated: NL From Model Space

NOLABEL/Color/Deprecated

Legacy conversion from model output space. Keep it only when maintaining older graphs that already use it.

NOLABEL / Utilities

NL Constant Color

NOLABEL/Utilities

Creates a solid image and mask at workflow or custom resolution. Useful for mattes, slates, and test inputs.

NL Edit

NOLABEL/Utilities

Built-in paint and mask editor node. Fetch upstream inputs, draw RGB or mask edits, save, then reuse or export.

WanVideoWrapper

NL WanVideo ImageToVideo Encode v2 (multi-ref)

WanVideoWrapper

Reference-image encoder utility for WanVideo workflows, including multi-reference frame placement, temporal masks, control embeds, and tiled VAE options.

Popups

Modals And Dialogs

Template detail and create modals

Use detail modals to inspect versions, load a template, update metadata, update from graph, upload poster images, and manage stack confirmations.

Subgraph publish and description dialogs

Publishing and description edits are intentional actions. Check the selected local or shared variant before saving changes.

Ledger row detail modal

Click a ledger row to inspect prompt id, model/provider, credits, USD, wallet state, captured context, and raw JSON.

Shared confirmations

Destructive or shared-library actions use confirm dialogs. Read the target path and item name before confirming.

When something feels wrong

Troubleshooting

Models show as missing locally

Open NL Model Manager, scan the workflow, and localize the missing model from the network side. Do not delete or upload unless you mean to change shared/local storage.

Writes go to an unexpected folder

Check Project Path in NL Workflow and the name field on NL Write. NL Write uses workflow context for versioned output paths.

Preview color looks wrong

Check NL Workflow color management, NL Read input_colorspace, and Preview preview_colorspace. Use NL Image Info Debug when metadata needs inspection.

Templates or subgraphs are empty

Check shared paths in extra_model_paths.yaml. Templates require shared template roots; subgraphs use the first available shared subgraph key.

Username warnings appear

Open NL Tools > Configuration. Templates and Ledger need a valid username for authorship and cost tracking.

Setup reference

Installation Video

The existing installation video remains available here for local setup context.