README.md

---
license: apache-2.0
library_name: coreai
pipeline_tag: image-to-image
base_model: Kim2091/ClearRealityV1
tags:
  - coreai
  - coreai-aimodel
  - core-ai
  - apple-core-ai
  - aimodel
  - on-device
  - apple-silicon
  - ios
  - macos
  - super-resolution
  - image-upscaling
  - image-enhancement
  - upscaler
  - 4x-upscaler
  - span
---

# ClearRealityV1 4× — Apple Core AI Port

Apple Core AI (`.aimodel`) port of **Kim2091's ClearRealityV1** 4× super-resolution model.

> **Original model:** [Kim2091/ClearRealityV1](https://huggingface.co/Kim2091/ClearRealityV1)  
> **Original author:** Kim2091  
> **Architecture:** SPAN  
> **Scale:** 4×  
> **Port / conversion:** enginil  
> **Format:** Apple Core AI `.aimodel`  
> **License:** Apache-2.0, matching the current upstream model repository

This repository does **not** claim authorship of the original ClearRealityV1 model.  
The model was trained and released by **Kim2091**. This repository contains a
conversion of the original weights to Apple's **Core AI** format plus conversion,
inference, and validation scripts.

## Model file

The converted model is:

```text
ClearRealityV1_4x_CoreAI.aimodel
```

Source checkpoint used for the conversion:

```text
Kim2091/ClearRealityV1
4x-ClearRealityV1.safetensors
SHA256: 83a9c8e279e3d07548e2b0d736dc2c73c1736a07072a748ed4fafbba99b44693
```

## Requirements

Running Core AI models requires current Apple Core AI platform support:

- Apple Silicon
- macOS 27+
- iOS 27+
- Python 3.11+ for the included Python inference script (macOS only)
- coreai-core for the included macOS Python inference script

Install the small runtime environment:

```bash
uv venv -p 3.11 .venv
source .venv/bin/activate
uv pip install -r requirements-inference.txt
```

You can also use ordinary `pip`:

```bash
python3.11 -m venv .venv
source .venv/bin/activate
pip install -r requirements-inference.txt
```

## Inference

The included `03_inference_coreai.py` performs full-image 4× upscaling with a
fixed Core AI input tile of 512×512, 64-pixel overlap, and midpoint-discard
stitching.

### PNG output

```bash
python3.11 03_inference_coreai.py \
  --model "ClearRealityV1_4x_CoreAI.aimodel" \
  --input "/path/to/input.jpg" \
  --output "/path/to/output.png"
```

PNG output is lossless.

### JPEG output

```bash
python3.11 03_inference_coreai.py \
  --model "ClearRealityV1_4x_CoreAI.aimodel" \
  --input "/path/to/input.jpg" \
  --output "/path/to/output.jpg"
```

Default inference parameters:

```text
model tile:     512  (fixed by the .aimodel input signature)
overlap:         64  (adjustable)
output-scale:     4  (default; optional final 2× mode available)
```

The model itself is always the original native 4× ClearRealityV1 model with a
static `1×3×512×512` RGB input and `1×3×2048×2048` output. Therefore the tile
size is **not user-configurable** for this exported `.aimodel`; only the overlap
is adjustable. The inference script tiles larger images automatically.

### Optional 2× final output

For cases where 4× is unnecessary, the same native 4× model can produce a
smaller final 2× image:

```bash
python3.11 03_inference_coreai.py   --model "ClearRealityV1_4x_CoreAI.aimodel"   --input "/path/to/input.jpg"   --output "/path/to/output_2x.png"   --output-scale 2
```

This is **not a separately trained native 2× model**. Core AI still runs the
original 4× network, stitches the full 4× float output, and then performs one
high-quality Lanczos downsample to the final 2× resolution. The default remains
the original native 4× output.

## Conversion method

The original SPAN implementation in Spandrel performs eval-time
reparameterization inside its Conv3XC-style modules. Exporting the raw Spandrel
object directly with `torch.export` therefore mutates module state during graph
capture.

The conversion used here does **not** reimplement SPAN or manually derive fused
weights. Instead it:

1. loads the original checkpoint through Spandrel;
2. lets Spandrel's own `update_params()` implementation materialize its exact
   eval-time fused convolutions;
3. freezes those exact `eval_conv` modules into a static inference graph;
4. verifies the frozen graph against fresh real Spandrel output;
5. exports the verified static graph with `torch.export`;
6. applies the Core AI decomposition table;
7. converts with `coreai_torch.TorchConverter`;
8. optimizes and saves the resulting `.aimodel`;
9. validates the saved Core AI model against the original Spandrel runtime.

The conversion path is therefore:

```text
ClearRealityV1.safetensors
        ↓
Spandrel SPAN
        ↓
Spandrel's own eval-time reparameterization
        ↓
static verified PyTorch graph
        ↓
torch.export
        ↓
Core AI decompositions
        ↓
coreai-torch
        ↓
optimize()
        ↓
ClearRealityV1_4x_CoreAI.aimodel
```

## Validation

The conversion was validated at multiple levels.

### 1. Real Spandrel vs frozen export-safe graph

```text
max_abs_diff : 0
mean_abs_diff: 0
RMSE         : 0
cosine       : 1
```

### 2. Real Spandrel vs `torch.export.ExportedProgram`

```text
max_abs_diff : 0
mean_abs_diff: 0
RMSE         : 0
cosine       : 1
```

### 3. FP32 Spandrel vs saved Core AI model

```text
max_abs_diff : 0.0023136139
mean_abs_diff: 0.000000906632
RMSE         : 0.000005862728
cosine       : 0.999999999935
```

### 4. Full-image end-to-end validation

Input:

```text
854 × 1280
```

Output:

```text
3416 × 5120
```

Both paths used the same 512/64 tile geometry and midpoint-discard stitching:

```text
Spandrel MPS FP16 ↔ Core AI

max_abs_diff : 0.0095030665
mean_abs_diff: 0.0002444417
RMSE         : 0.0003341608
cosine       : 0.99999985751

mean_abs ×255: 0.06233263
RMSE ×255    : 0.08521101
max_abs ×255 : 2.42328197
```

The numerical metrics are calculated on raw float outputs before JPEG encoding.

To reproduce the full-image comparison:

```bash
python3.11 04_compare_full_image.py \
  --weights "/path/to/4x-ClearRealityV1.safetensors" \
  --aimodel "ClearRealityV1_4x_CoreAI.aimodel" \
  --image "/path/to/input.jpg" \
  --output-dir "./validation_output" \
  --tile 512 \
  --overlap 64 \
  --visual-format jpg
```

This writes:

```text
spandrel_mps_fp16.jpg
coreai.jpg
difference_x20.png
```

## Files

```text
ClearRealityV1_4x_CoreAI.aimodel   converted model
03_inference_coreai.py             standalone Core AI inference
04_compare_full_image.py           full-image parity validation
02_validate_real_crop.py           real-image crop validation
01_convert_coreai.py               Core AI conversion
00_probe_freeze_and_export.py      pre-conversion parity gate
spandrel_source.py                 exact Spandrel loading/freezing helpers
tiling.py                          shared tiling/stitching implementation
requirements-inference.txt         minimal runtime dependencies
requirements-conversion.txt        conversion/validation dependencies
ATTRIBUTION.md                     upstream attribution and conversion notice
LICENSE                            Apache License 2.0
```

## Original model notes

Kim2091 describes ClearRealityV1 as a 4× SPAN model intended for realistic
imagery, including faces, hair, foliage, trees, and buildings, with a softer,
more natural target and reduced artifacts.

The upstream author also notes that depth-of-field / bokeh regions can still
produce artifacts. That limitation is inherited by this port; conversion to
Core AI does not change the learned behavior of the original model.

## License and attribution

The current upstream Hugging Face repository declares **Apache-2.0**.

Original model:

- **ClearRealityV1**
- **Author:** Kim2091
- **Upstream:** https://huggingface.co/Kim2091/ClearRealityV1

Core AI conversion:

- **Port:** enginil
- No additional training was performed.
- The converted artifact remains derived from the original ClearRealityV1 model.

See `ATTRIBUTION.md` and `LICENSE`.


## Seam-resistant tiled inference

The release runner now uses **balanced tile placement** plus **weighted overlap
blending**. No `.aimodel` reconversion is required.

```text
model tile:   512×512 (fixed by this converted model)
min overlap:  64 px (configurable)
placement:    balanced
blend:        cosine (configurable)
```

For a 1024-pixel axis, the default planner uses starts `[0, 256, 512]`,
so the two actual overlaps are both 256 pixels. The old asymmetric
`[0, 448, 512]` placement is no longer used.

The recommended default is `--blend cosine`. `linear` and `uniform` are
available for comparison.