Forge Neo KREA2 Style Reference

Experimental training-free reference-image style transfer for KREA2 in Forge Neo.

Current release: v0.1.0-alpha.8. This is an experimental alpha; read the compatibility boundaries before using it in an important workflow.

The extension runs the KREA2 transformer on a target/reference cross-batch and applies the Untwisting RoPE frequency-control method to the reference attention keys. No LoRA, ControlNet model, second text encoder, or additional Python package is required.

AI-assisted development transparency

Forge Neo KREA2 Style Reference is created and maintained by vibecodingtoolmaker with substantial AI-assisted development support from OpenAI Codex. Code, documentation, reviews, and test ideas have been developed and refined through this collaborative workflow — also known, with some affection, as vibecoding.

The project direction, feature decisions, hands-on Forge testing, final review, and release responsibility remain with the human maintainer. Codex is a development tool, not a runtime dependency: the installed extension does not contact OpenAI or send prompts, reference images, model information, or other user data to Codex. This project is not affiliated with or endorsed by OpenAI.

What it transfers

• palette, texture, lighting, and rendering character;
• optional color/contrast statistics through AdaIN;
• optional soft composition influence.

The composition control is not a Depth ControlNet. It does not extract a depth map or guarantee geometric correspondence. It keeps more of the reference's spatial-frequency contribution, which can make the generated layout resemble the reference. Keep it at 0 for style-first generation in which the prompt controls composition.

Real depth control

A genuine KREA2 depth path is technically feasible, but it is a separate model-assisted feature rather than another setting of the training-free style method. A public KREA2 Depth ControlNet-LoRA uses a depth latent concatenated with the noisy image latent, an expanded input projection, and LoRA weights across the transformer blocks. The accompanying ComfyUI integration also requires depth preprocessing and dedicated model loading.

This alpha therefore does not download or silently load an additional control model. True depth control is planned as an optional second adapter after the training-free style path has passed live Forge generation tests. The soft composition slider remains useful for exploratory layout similarity, but must not be presented as geometric control.

Installation

Clone the repository into Forge Neo's extensions directory, then restart Forge:

cd path\to\sd-webui-forge-neo\extensions
git clone https://github.com/vibecodingtoolmaker/ForgeNeo-Krea2-image-to-style-reference.git Forge-Neo-Style-Reference

To update an existing installation:

git -C Forge-Neo-Style-Reference pull --ff-only

The extension uses only Python and packages already supplied by Forge Neo. Do not add or upgrade Torch, Gradio, NumPy, or Pillow separately.

Developer checks can be run with Forge's Python:

venv\Scripts\python.exe -m unittest discover -s extensions\Forge-Neo-Style-Reference\tests -v
venv\Scripts\python.exe extensions\Forge-Neo-Style-Reference\tests\forge_bootstrap_check.py

First test

1. Load KREA2 Turbo and its normal KREA2 VAE/text encoder stack.
2. Open KREA2 Style Reference (experimental) in txt2img.
3. Enable it and upload one style image.
4. Use 8 steps, CFG 1, and batch size 1.
5. Describe a subject and composition that differ clearly from the reference.
6. Raise only one effect control at a time for the first comparison.

Recommended starting values:

Control	Baseline	First useful sweep
Style strength	0	0-1 in 0.25 steps
Color / texture match	0	0-0.6 in 0.15 steps
Composition influence	0	0-0.8 in 0.1 steps
Composition step window	1-final step	use 1-5 first at 8 steps
Frequency curve beta	2.25	leave unchanged first
Transformer blocks	7-27	leave unchanged first

All three effect controls at 0 are a true no-op: the reference is not VAE-encoded and no transformer patch is installed. This makes the zero cell suitable as an exact baseline. The technical beta and block controls are not effect strengths, so their defaults remain at valid working values rather than zero.

Use a reference with the same aspect ratio as the output when testing composition. The image is center-cropped to the output ratio before VAE encoding.

Control guide

Style strength: 0 to 2

Style strength controls the low-frequency reference-key channels. Those channels carry broad semantic appearance such as palette, material, illumination, brush or render character.

• 0: style attention is off. If the other two effect controls are also zero, the extension performs no work.
• 0.25-0.75: usually the useful subtle range.
• 1: strong reference style; the low-frequency reference keys reach their normal amplitude late in denoising.
• 1-2: amplified experimental range. Increasing it can overpower prompt semantics, create malformed detail, or collapse the image. 2 is now the hard UI and XYZ limit.

This is not a conventional linear opacity control. A change from 0.8 to 1.2 may be much more visible than the numeric difference suggests because it changes attention probabilities inside every selected transformer block.

Color / texture match: 0 to 1

This control applies Adaptive Instance Normalization (AdaIN) to internal image-token features. It aligns the generated feature mean and variance with the reference; it does not sample literal reference pixels.

• 0: AdaIN is off.
• 0.1-0.4: mild palette, exposure, contrast, and texture-statistics alignment.
• 0.5-0.75: strong alignment that can noticeably override prompt colors or flatten local contrast.
• 1: complete AdaIN statistics replacement inside every selected block; use mainly for diagnosis.

Color/texture match can be used by itself. In that mode the target does not attend to reference K/V tokens; only the internal feature statistics are aligned.

Composition influence: 0 to 10

Composition influence controls the high-frequency reference-key channels that are most sensitive to spatial alignment.

• 0: high-frequency reference layout is suppressed; use this for style-first generation.
• 0.25-0.75: soft pose, silhouette, or layout hints may appear.
• 0.8-0.95: transition zone; source structure and prompt structure can begin competing.
• around 0.95-1: visible source-image overlap or copying may begin, as observed in live testing;
• 1-5: high-risk diagnostic range with increasingly dominant reference composition;
• 5-10: near-reconstruction/takeover range. Expect the generated image to rebuild the reference composition almost exactly while still expressing prompt- or model-driven style changes. Doubled structures and prompt/reference conflict remain possible.

This control is not a depth map, pose estimator, or geometric constraint. If the prompt and reference demand incompatible layouts, blended or doubled structures are an expected failure mode rather than a depth-consistent result.

Composition start/end step: 1 to 150

These two controls define the inclusive, 1-based sampling-step window in which Composition influence is allowed to inject reference attention. They do not change the number of generation steps. The extension reads the sampler's real sigma schedule, so the window follows actual steps rather than estimating them from a percentage.

For an 8-step generation:

• 1-8: Composition influence is active for the entire generation, matching the previous behavior.
• 1-5: allows early and middle composition guidance but prevents it during the final three steps. This is the first useful test for the observed late reference takeover.
• 5-8: isolates the late phase in which takeover was observed.
• 6-6: applies Composition influence during one step only, useful for locating the exact transition.

The start and end values are automatically clamped to the generation's real step count and reversed input such as 7-3 is normalized to 3-7. Outside the window, only Composition influence is bypassed: Style strength and Color / texture match remain active if configured. With both of those at 0, the extension skips reference attention entirely outside the window instead of merely multiplying it by zero.

Frequency curve beta: 0.25 to 5

Beta determines how quickly modulation transitions from composition-sensitive high frequencies to style-sensitive low frequencies.

• lower values spread the style scale into more middle-frequency channels, which can make transfer broader and less separated;
• higher values leave more middle frequencies near the composition scale and concentrate style amplification toward the lowest-frequency channels;
• 2.25 is the current working default. Tune it only after finding approximate style and composition strengths.

First and last transformer block: 0 to 27

KREA2 contains 28 single-stream transformer blocks. The extension patches the inclusive selected interval.

• beginning earlier can strengthen global structure and content transfer;
• later blocks emphasize refinement and appearance more than the earliest layout decisions;
• using more blocks increases runtime and attention-memory cost;
• 7-27 is the conservative starting interval.

X/Y/Z Plot sweeps

After restarting Forge, X/Y/Z Plot exposes these axes:

• [KREA2 Style] Enabled
• [KREA2 Style] Style strength
• [KREA2 Style] Color / texture match
• [KREA2 Style] Composition influence
• [KREA2 Style] Composition start step
• [KREA2 Style] Composition end step
• [KREA2 Style] Frequency curve beta
• [KREA2 Style] First transformer block
• [KREA2 Style] Last transformer block

Enable the Style Reference accordion and select a reference image before starting a numeric sweep. The XYZ value is applied to a private copy of the Forge processing object for each cell, so values cannot leak into following cells or generations.

Useful Forge XYZ expressions:

Style strength:        0-2(+0.25)
Color / texture match: 0-1(+0.1)
Composition influence: 0-10(+0.5)
Composition start step: 1-8(+1)
Composition end step:   1-8(+1)

Start with a one-dimensional sweep at a fixed seed. For a two-dimensional sweet-spot grid, use Style strength on X and Color / texture match on Y while leaving Composition at 0. Test Composition separately because values near 1 can change the subject layout rather than only its visual style. To locate a late takeover in an 8-step run, keep the start at 1 and sweep Composition end step from 1-8(+1); then use a narrow fixed window around the first changing step. The Enabled axis with False, True can additionally compare a configured effect against a fully disabled generation.

VRAM

The reference adds a second transformer batch and extra reference K/V attention. VRAM use is therefore substantially higher than ordinary KREA2 generation. Start at 1024x1024, batch size 1, CFG 1, and avoid compiled/AOT transformer blocks during early tests.

Compatibility boundaries

• KREA2 only.
• The extension temporarily disables Forge's native [Krea2] Enable Reference option for its own request. That native path is intended for image-grounded edit/identity workflows and is a different technique.
• AOT-compiled KREA2 transformer blocks are not currently supported because this extension installs eager runtime attention wrappers.
• Live Forge generation is required to judge style strength, content leakage, and VRAM behavior; isolated tests cannot prove visual quality.

Roadmap

1. Validate style-only generation at composition 0, including VRAM and content leakage.
2. Tune the KREA2 block range and defaults from paired visual comparisons.
3. Add an explicitly enabled depth adapter with a user-selected local ControlNet-LoRA, depth preprocessing, and expanded input projection.
4. Validate style and depth separately before allowing both paths in the same request.

Credits

Based on Untwisting RoPE: Frequency Control for Shared Attention in DiTs, the original ComfyUI implementation, and the public KREA2 diffusers port.

License

AGPL-3.0-only. See LICENSE for the full license text.