Patch Flux Kontext True 3D PE

Patch Flux Kontext True 3D PE is the most surgical node in this pack: it monkey-patches a Flux model's forward pass to change how Kontext reference images get their positional encoding. One MODEL in, one MODEL out, and the author's own description warns you to use it with caution. This is not a node for beginners, and honestly not a node most people should reach for - but it's a fascinating look at what a deeply technical pack author will publish for themselves.

The background: Kontext (FLUX.1 Kontext) is Black Forest Labs' 12B instruction-based editor, which consumes reference images in-context rather than through a separate adapter. In the released dev model, those reference images are positioned using the same 2D positional encoding as the main image. That's fine for a single context image, but it breaks down with multiple references - each one reuses the same positions instead of getting its own place in space. This patch replaces the encoding so each context image gets its own true 3D positional slot (positional encoding that spans the batch/context dimension), which is what the name means.

How it works

The node grabs your Flux model and swaps in a patched forward function that: processes the main image and any ref_latents (the Kontext references), gives each reference its own positional index (h_offset=0, w_offset=0, index i+1), concatenates them with the main tokens, runs the transformer, then slices back to just the main image's tokens and reconstructs the spatial layout. The key architectural consequence: with true 3D PE, a model trained on it can correctly distinguish which pixels belong to which reference image - which matters for character consistency when you're feeding a model multiple character references at once.

One input, model (MODEL). One output, model. It verifies the model is actually Flux before patching (anything else raises a clear error), then patches it in place.

Install

The pack standard:

cd ComfyUI/custom_nodes
git clone https://github.com/Duanyll/duanyll_nodepack
cd duanyll_nodepack && pip install -r requirements.txt

or ComfyUI Manager → "Duanyll Nodepack" → install → restart.

The caution, stated plainly

The author's own description is a warning: for the currently released FLUX.1 Kontext dev model, this patch "will cause it not working ideally with multiple context images." That's because the released weights were trained with the 2D-style encoding - this patch makes it behave as if trained for true 3D PE, which the released model isn't. So in practice, this node is a speculative patch: it's the scaffolding for future models trained with true 3D PE, and applying it to today's dev checkpoint is an experiment, not a fix. If you're happily using Kontext today, skip it. If you're poking at multi-reference workflows and want to see whether the positional encoding is the bottleneck, this is a one-wire experiment that takes seconds to try.