Omini Kontext Reference Encoder

Of all the advanced encoder nodes in this pack, this is the one that actually shows you the interesting mechanism. The Omini Kontext Reference Encoder takes a reference image - your character, your object - encodes it to latent tokens, and then applies the position delta to the tokens' image ids before handing them back. That id-shifting is literally how omini-kontext moves your character around the scene. The main Pipeline node does this invisibly; this node lets you do it by hand and see the result.

How it works

It's the same encode_images path as the Image Encoder, with one extra step. After the reference is VAE-encoded and packed, the node clones the image ids and adds your deltas straight into them: delta_x into the first id channel, delta_y into the second, delta_z into the third. Those ids are what the transformer uses to know where in the spatial grid each token belongs, so bumping them is how you tell the model "this reference lives over here now" - no mask, no compositing, just a coordinate tweak before attention runs.

The inputs that matter

• pipeline - the OMINI_KONTEXT_PIPELINE from a loader.
• reference_image - the character/object you're inserting.
• delta_x / delta_y - horizontal and vertical offset, default 0. Negative/positive move the reference around the grid.
• delta_z - the depth axis, default 96. In the author's workflow, 96 is (scene_height + reference_height) / 16, which tells you z is about how the reference's tokens stack in the depth dimension - the integration axis, not a rotation.

Outputs are REF_LATENT (the encoded reference tokens) and REF_IMAGE_IDS (the ids, already nudged). Those feed straight into the Latent Combiner, where they're concatenated with the scene's tokens and ids.

Where it fits

The reference path through the pack is: Reference Encoder → Latent Combiner → Visualizer (to check), and that chain is the manual version of what the Pipeline node's reference_delta_x/y/z fields do in one click. So the honest question is why you'd use it. Two answers: debugging - you can encode a reference and inspect exactly how the delta changed the ids, which is the fastest way to internalize what these values do; and building - if you're composing custom latents outside the main node, this is the piece that gives your reference a position.

One practical note: the delta values here are raw ints applied directly to ids, so they scale differently than you might expect from the Pipeline node's friendly -100..100 guidance. Same math under the hood, but no hand-holding. Start from the defaults (0, 0, 96) and move in small steps.