--- 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.