Update README.md

README.md

@@ -1,58 +1,67 @@
 ---
-license: apache-2.0
-language:
-- en
-pipeline_tag: image-to-image
 library_name: pytorch
 tags:
 - image-to-image
+- super-resolution
 - diffusion
 - pixel-diffusion-decoder
-- super-resolution
+- vae-decoder
+- restoration
 - denoising
 - pytorch
 - safetensors
-- pie
+pipeline_tag: image-to-image
 ---
 
-# PiEa: Pixel Diffusion Decoder
+# PiEa - Pixel Diffusion Decoder
+
+<p align="center">
+  <img src="eval_comparison_grid.png" alt="PiEa visual preview" width="100%">
+</p>
+
+PiEa is an in-house Pixel Diffusion Decoder developed by **Dl26**. It is designed as an image-to-image decoder that works directly in pixel space. The model receives a degraded visual condition and a noisy image-space input, then predicts the denoising signal used to recover a cleaner high-resolution image.
+
+PiEa is built for restoration-style decoding, image refinement, and high-resolution reconstruction research. It is not a text-to-image model and it is not a wrapper around another released decoder. The checkpoint is a standalone image-to-image component intended for custom visual pipelines.
+
+Unlike latent-only decoders, PiEa treats pixels as the reconstruction target. This makes the model useful for studying learned decoding behavior where the decoder itself performs conditional restoration instead of simply applying a deterministic upsampling stack. The current release focuses on 512px image reconstruction and pixel-space refinement.
+
+## Model Overview
+
+The released checkpoint is a large PiEa decoder with approximately **1.01B parameters**. The architecture is custom and identified in the configuration as `PiEaPixelDiffusionDecoder`. The model uses `input_type: PiE` to mark the intended input family and distinguish it from other pixel decoder formats.
+
+PiEa was expanded from an earlier smaller in-house checkpoint. During expansion, overlapping learned tensor regions were copied into the larger model so previously trained structure could be retained, while newly introduced channels were initialized and trained as additional capacity. This gives the larger checkpoint continuity with the previous training stage without claiming the architecture stayed identical.
+
 
-`PiEa` is a compact image-to-image Pixel Diffusion Decoder. It is trained to reconstruct clean pixels from noisy pixels while conditioning on a degraded version of the same image. The model is designed for decoder-style image restoration, image refinement, and pixel-space reconstruction experiments.
+## Architecture
 
-PiEa is not a text-to-image generator. It is a decoder component: it expects image-like conditioning and produces image-like denoising predictions.
+PiEa uses a convolutional U-Net-style pixel diffusion decoder. The model receives two image-space tensors: a noisy image and a degraded condition image. These tensors are concatenated channel-wise and processed through a downsampling path, residual blocks, a deeper mid-section, and an upsampling path that returns a noise prediction in RGB pixel space.
 
-## Model details
+The decoder is conditioned by a continuous noise or timestep embedding. This embedding modulates the residual blocks and lets the same network learn behavior across different noise levels. The output is trained as an epsilon prediction, allowing a reconstruction pipeline to combine the noisy input and predicted noise into a cleaner image estimate.
 
-| Property | Value |
-| --- | --- |
-| Model name | `PiEa` |
-| Developer | PiEa-ai |
-| Model type | Pixel diffusion decoder |
-| Input type | `PiE` |
-| Architecture | Compact U-Net diffusion decoder |
-| Parameters | 1,010,776,675 |
-| Resolution | 512 x 512 |
-| Base channels | 464 |
-| Channel multipliers | [1, 2, 4, 6] |
-| Dataset used | `['huggan/wikiart', 'huggan/smithsonian_butterflies_subset']` |
-| Optimizer | AdamW |
-| Precision | bfloat16 autocast |
+This design keeps the model centered on direct visual reconstruction. PiEa is not a classifier, language model, text encoder, prompt-following diffusion transformer, or general image generator. It is a dedicated pixel decoder for image-to-image workflows.
 
-## Throughput
+## Data
 
-| Metric | Value |
-| --- | --- |
-| Training steps | 9,141 |
-| Image tokens processed | 2,396,258,304 |
-| Image tokens/sec | 1331229.59 |
-| Target image tokens/sec | 250,000 |
-| Final loss | 0.023287 |
+PiEa was trained on a mixed real-image pool that included WikiArt-style imagery and additional natural-image reconstruction data. The training data was used for reconstruction and restoration behavior, with synthetic degradation and noise applied during training.
 
-Image tokens are counted as processed spatial pixels: `batch_size * height * width` per optimization step.
+The degradation process is intentionally image-space based. Clean images are transformed into lower-detail or noisy conditions, and the model learns to recover structure, color, and high-frequency detail. This makes the checkpoint suitable for studying restoration-like decoding rather than text-conditioned generation.
+
+## Intended Use
+
+PiEa is intended for:
+
+- image-to-image restoration research
+- pixel diffusion decoder experiments
+- super-resolution-style reconstruction systems
+- denoising and refinement pipelines
+- visual decoder prototyping
+- studying pixel-space alternatives to deterministic decoders
+
+PiEa can be useful where a project needs a learned decoder that performs more than direct interpolation. It is especially relevant for experiments where the decoder is expected to recover visual texture and structure from imperfect image-space inputs.
 
 ## Usage
 
-This checkpoint is saved as raw PyTorch/safetensors artifacts. Load the model with the architecture definition used in the training script or port the weights into a compatible pixel decoder implementation.
+This repository contains checkpoint weights and configuration for the PiEa decoder. A compatible implementation should construct `PiEaPixelDiffusionDecoder` using `config.json`, then load `model.safetensors`.
 
 ```python
 from safetensors.torch import load_file
@@ -60,19 +69,38 @@ from safetensors.torch import load_file
 state_dict = load_file("model.safetensors")
 ```
 
+At a high level, a PiEa inference pipeline should:
+
+1. Prepare or receive a degraded image condition.
+2. Prepare a noisy pixel-space input.
+3. Provide a timestep or noise-level value.
+4. Run PiEa to predict image noise.
+5. Convert the predicted noise into a cleaner reconstruction.
+
+The exact scheduler and denoising procedure depend on the surrounding system.
+
+## Scope
+
+PiEa is a component model. It should be treated as one part of a larger image pipeline, not as a complete application. It does not include a user interface, prompt processor, safety filter, text encoder, or production scheduler.
+
+The checkpoint is best suited for researchers and developers who are comfortable integrating raw PyTorch/safetensors weights into custom image systems. It may also be useful as a reference point for experiments around learned pixel decoders, restoration modules, and super-resolution-style reconstruction.
+
 ## Limitations
 
-- PiEa is an pixel decoder, not a full image generation system.
-- It is trained on image reconstruction and denoising, not prompt following.
-- Quality depends on the surrounding pipeline and conditioning signal.
+- PiEa is not a full text-to-image model.
+- PiEa does not follow text prompts.
+- The model requires a compatible custom loader implementation.
+- Output quality depends on the degradation process, noise schedule, and surrounding pipeline.
+- The checkpoint may produce artifacts on image distributions far from its training data.
+- It should be evaluated on target data before deployment.
 
 ## Citation
 
 ```bibtex
-@misc{piea2026pixeldecoder,
-  title={PiEa: Pixel Diffusion Decoder},
-  author={Ill Ness, JasonBruck},
-  year={2026},
-  url={https://huggingface.co/PiEa-ai/PiEa}
+@misc{dl26_2026_piea,
+  title        = {PiEa: Pixel Diffusion Decoder},
+  author       = {Dl26},
+  year         = {2026},
+  url          = {https://huggingface.co/Dl26/PiEa}
 }
-```
+```