enginil/ClearRealityV1-CoreAI

ClearRealityV1 4× — Apple Core AI Port

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

Original model: 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:

ClearRealityV1_4x_CoreAI.aimodel

Source checkpoint used for the conversion:

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:

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

You can also use ordinary pip:

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

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

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

Default inference parameters:

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:

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:

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

max_abs_diff : 0
mean_abs_diff: 0
RMSE         : 0
cosine       : 1

2. Real Spandrel vs torch.export.ExportedProgram

max_abs_diff : 0
mean_abs_diff: 0
RMSE         : 0
cosine       : 1

3. FP32 Spandrel vs saved Core AI model

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

4. Full-image end-to-end validation

Input:

854 × 1280

Output:

3416 × 5120

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

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:

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:

spandrel_mps_fp16.jpg
coreai.jpg
difference_x20.png

Files

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.

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.