README.md

---
license: other
license_name: krea-2-community-license
license_link: https://krea.ai/krea-2-licensing
base_model: krea/Krea-2-Turbo
library_name: diffusers
pipeline_tag: image-to-image
tags:
  - krea-2
  - lora
  - outpainting
  - image-editing
  - diffusers
---

# Krea 2 Registered Outpaint

> **Important:** The Hugging Face auto-generated Diffusers snippet and ordinary
> LoRA importers are not compatible with this functional adapter. Use the
> included `example.py`, `pipeline.py`, and `outpaint.py` instead.

This rank-32 LoRA extends an image into a larger canvas while preserving its
known pixels and registering the source image at an explicit canvas location.
It was trained against Krea 2 Raw and is intended for distilled 8-step inference
with Krea 2 Turbo.

Unlike a plain image-reference adapter, the source latent tokens receive rotary
coordinates derived from their destination bounding box. The denoiser can
therefore reason about where the known image belongs in the target canvas. The
included pipeline is based on
[ostris/Krea2OstrisEdit](https://huggingface.co/ostris/Krea2OstrisEdit) and adds
the registered `reference_placements` input used by this adapter.

## Files

```text
krea2_outpaint_rank32.safetensors  LoRA weights
pipeline.py                        Krea 2 edit pipeline with registered references
outpaint.py                        Canvas preparation and seam compositing helpers
example.py                         Minimal local example
LICENSE.pdf                        Krea 2 Community License
PIPELINE_LICENSE                   Apache-2.0 license for pipeline/helper code
NOTICE                             attribution and derivative-work notice
SHA256SUMS                         release artifact hashes
showcase/                          fully synthetic source/output examples
```

## Tested capabilities

This release has been tested across photorealistic, watercolor, and
stylized 3D scenes, with the known source placed on different parts of the
canvas:

- left-anchored source with generation extending to the right;
- top-anchored source with generation extending downward;
- centered source with generation extending across both horizontal sides;
- square-to-landscape and square-to-portrait canvas changes;
- coherent continuation of perspective, lighting, texture, and repeated scene
  structure.

Every source shown below was generated from the unmodified Krea 2 base model.
The corresponding result then uses this Outpaint LoRA. No external image,
real-person likeness, artist name, or existing character IP was used.
Each source and result is the first 8-step output from its preselected prompt,
placement, and fixed seed (`17072033` through `17072038`); all three planned
groups are shown and no rerolls were removed.

### Photorealistic interior: extend right

| Base-model source | Outpaint result |
|:---:|:---:|
| ![Synthetic photorealistic source](showcase/photo_source.webp) | ![Photorealistic right extension](showcase/photo_extend_right.webp) |

### Watercolor village: extend down

| Base-model source | Outpaint result |
|:---:|:---:|
| ![Synthetic watercolor source](showcase/watercolor_source.webp) | ![Watercolor downward extension](showcase/watercolor_extend_down.webp) |

### Stylized 3D night market: extend both sides

| Base-model source | Outpaint result |
|:---:|:---:|
| ![Synthetic stylized 3D source](showcase/3d_source.webp) | ![Stylized 3D two-sided extension](showcase/3d_extend_both_sides.webp) |

## Input contract

The model takes:

- one RGB source image;
- an output canvas whose width and height are multiples of 16;
- a source bounding box `(x0, y0, x1, y1)` in output pixels;
- a prompt describing the complete output image.

The bounding box must stay inside the canvas and preserve the source aspect
ratio. The helper resizes the source to that exact box. Conditioning is encoded
at a maximum edge of 384 pixels; the original resized pixels are restored after
generation with a 32-pixel inward feather.

For a single pass, the source box should span the full canvas width or height.
`outpaint.py` also provides a two-pass plan for arbitrary interior boxes. It
chooses the smaller intermediate blank region first.

## Recommended settings

| Setting | Value |
|---|---:|
| Base | `krea/Krea-2-Turbo` |
| Steps | 8 |
| Guidance scale | 0.0 |
| LoRA scale | 1.0 |
| Reference maximum edge | 384 px |
| Seam feather | 32 px |
| Reference VLM encoding | disabled |
| Reference K/V cache | enabled |

The adapter uses isolated reference attention, so `kv_cache=True` and
`encode_reference_in_prompt=False` are part of the model contract rather than
optional speed tweaks.

## Usage

Install a current PyTorch build for your GPU, then install the dependencies:

```bash
pip install diffusers transformers accelerate safetensors huggingface_hub pillow
```

Run the included example after downloading this repository:

```bash
python example.py \
  --source input.png \
  --output output.png \
  --width 1024 \
  --height 1536 \
  --bbox 0 0 1024 1024 \
  --prompt "a polished digital illustration, full composition"
```

The example defaults to BF16. Quantized Krea 2 runtimes may also load the LoRA,
but quantization setup is runtime-specific and is not bundled here.

## How it works

The noisy target follows normal Krea 2 flow-matching inference. The clean source
is VAE-encoded as a separate token sequence. For a normalized source box
`(x0, y0, x1, y1)`, source token coordinates are mapped into the target latent
grid before rotary position encoding. Reference K/V is computed once and reused
through all denoising steps. Finally, exact source pixels are composited back
into the known region with a short inward feather to retain detail while hiding
small decode differences at the boundary.

## Responsible use

Use and deployments must comply with the Krea 2 Community License and
Acceptable Use Policy. Deployments must implement content moderation
appropriate to their use case and disclose AI-generated content where
required.

## Limitations

- Very large missing regions can introduce a second subject or unrelated scene.
- Interior placement uses two generations and can accumulate changes between
  passes.
- The model handles rectangular outpainting, not arbitrary inpainting masks.
- Prompt wording and source composition affect how aggressively content is
  extended.
- The 384-pixel conditioning budget prioritizes speed and structure over exact
  recovery of tiny source details; final compositing preserves the known pixels.
- The included BF16 example is provided as a portable reference path; the
  reported performance measurements below are from the tested INT8 runtime.

## Training summary

The adapter was trained at rank/alpha 32/32 on rectangular crops registered to
their location in complete target images. Targets were at most 1024 pixels on
their longest edge and source conditions at most 384 pixels. The final candidate
is the 12,000-step checkpoint. Training data and training infrastructure are not
distributed.

In the tested INT8 ConvRot Krea 2 Turbo runtime on an RTX 5090, one 8-step pass
took approximately 3.6-4.2 seconds at the evaluated native resolutions, with
prompt encoding around 0.1 seconds. These measurements are implementation- and
hardware-specific and are not BF16 benchmark claims.

## License

The LoRA weights are a derivative of Krea 2 and are released under the Krea 2
Community License in `LICENSE.pdf`. Pipeline and helper code are distributed
under Apache-2.0 in `PIPELINE_LICENSE`. This is an unofficial community release
and is not endorsed by Krea or Ostris. Use, modification, and distribution of
the model weights are subject to the included Krea 2 Community License
Agreement.