Forsaken Apex Wiki
Bundle OKF 0.1 · 15 conceitos · Codiosityy/ForsakenApex
Open source Repository Open in the app JSON README (API)
About
# Forsaken Apex Wiki
Documentation for the KLA 2026 Image Restoration Competition entry.
## Getting Started
- [Quick Start Guide](quickstart.md) - Project overview, installation, and usage
## Architecture
- [Architecture Overview](architecture/overview.md) - System design and data flow
- [RestorationNet Model](architecture/restoration_net.md) - Main model architecture
- [DenseBlock Module](architecture/dense_block.md) - Dense connectivity block
- [RRDB Module](architecture/rrdb.md) - Residual in Residual Dense Block
- [PixelShuffleUpsample](architecture/pixel_shuffle_upsample.md) - Upsampling module
## Training
- [Training Overview](training/overview.md) - Training strategy and pipeline
- [Training Configuration](training/configuration.md) - Hyperparameters and settings
- [Data Handling](training/data_handling.md) - Data loading and augmentation
## Inference
- [Inference Guide](inference/overview.md) - How to run inference
- [Model Loading](inference/loading_models.md) - Loadi
Details
- Kind
- OKF bundles
- Topic
- Productivity
- Publisher
- codiosityy
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Last push
- 2026-08-19T15:56:33Z
- Repository state
- ativo
- Language
- Python
- Added
- 2026-09-08 22:08:51
- Updated
- 2026-09-08 22:08:51
- Origin id
Codiosityy/ForsakenApex:openwiki/index.md
README
# AI-Based Restoration of Degraded Images : Forsaken Apex
RRDB-based single-image restoration network (5.997M parameters) that upscales and denoises degraded grayscale inputs by 2x.
## Wiki
Detailed documentation is available in the [Wiki](https://github.com/Codiosityy/ForsakenApex/wiki):
| Section | Pages |
|---------|-------|
| **Architecture** | [Overview](https://github.com/Codiosityy/ForsakenApex/wiki/overview) · [RestorationNet](https://github.com/Codiosityy/ForsakenApex/wiki/restoration_net) · [DenseBlock](https://github.com/Codiosityy/ForsakenApex/wiki/dense_block) · [RRDB](https://github.com/Codiosityy/ForsakenApex/wiki/rrdb) · [PixelShuffle](https://github.com/Codiosityy/ForsakenApex/wiki/pixel_shuffle_upsample) |
| **Training** | [Configuration](https://github.com/Codiosityy/ForsakenApex/wiki/configuration) · [Data Handling](https://github.com/Codiosityy/ForsakenApex/wiki/data_handling) |
| **Inference** | [Guide](https://github.com/Codiosityy/ForsakenApex/wiki/loading_models) |
| **Evaluation** | [Metrics](https://github.com/Codiosityy/ForsakenApex/wiki/metrics) · [Results](https://github.com/Codiosityy/ForsakenApex/wiki/results) |
| **Reference** | [Model Files](https://github.com/Codiosityy/ForsakenApex/wiki/available_models) · [Dev Setup](https://github.com/Codiosityy/ForsakenApex/wiki/environment_setup) · [Quick Start](https://github.com/Codiosityy/ForsakenApex/wiki/quickstart) |
## Results
### Performance
| Metric | Value |
|--------|-------|
| PSNR (dB) | 28.47 |
| SSIM | 0.767 |
| LPIPS | 0.164 |
| Sharpness | 50.5% of GT |
Evaluated on 320 full-resolution validation images.
### Inference Throughput
| Batch Size | ms/image | images/sec |
|------------|----------|------------|
| 1 | 9.80 | 102.0 |
| 4 | 5.74 | 174.3 |
### Benchmark Comparison
RestorationNet vs. bicubic and standard AI baseline across PSNR, SSIM, and throughput:
### PSNR Comparison
Higher PSNR indicates better image reconstruction quality:
### Result Examples
**Success Case** : clean texture recovery, minimal artifacts:
**Failure Case** : some over-smoothing in high-frequency detail regions:
## Architecture
### Enhancement Process
```mermaid
flowchart LR
A[Noisy Input] --> B[Feature Extraction] --> C[8x RRDB] --> D[PixelShuffle 2x] --> E[Residual] --> F[Clean Output]
```
### Model Architecture
```mermaid
flowchart TD
A[Input] --> B[Head Conv2d]
B --> C[8x RRDB Blocks]
C --> D[Body Tail + Global Residual]
D --> E[PixelShuffle 2x]
D --> F[Noise Head]
E --> G[HR Conv + LeakyReLU]
G --> H[Output Conv]
H --> I[Add Bicubic Residual]
I --> J[Clamp 0-1]
J --> K[Output 2x Resolution]
```
| Parameter | Value |
|-----------|-------|
| Parameters | 5.997M |
| Input | 1-ch grayscale, arbitrary size |
| Output | 1-ch grayscale, 2x resolution |
| RRDB blocks | 8 |
| DenseBlock growth | gc=32, base nf=64 |
| Upsample | PixelShuffle 2x |
| Output | Global residual on bicubic interpolation |
## Training
### Technical Validation Workflow
Our training pipeline uses a gated fine-tuning approach with accept/reject gates:
### Base Training (100 epochs)
- **Loss:** Composite : Charbonnier (w=1.0) + Gradient (w=0.1) + Physics Consistency (w=0.1) + SSIM (w=0.2) + LPIPS (w=0.05) + Blind Spot (w=0.05)
- **Optimizer:** AdamW (lr=2e-4, betas=(0.9, 0.99), weight_decay=1e-4)
- **Scheduler:** CosineAnnealingLR (T_max=100)
- **Batch size:** 16 effective (4 x 4 gradient accumulation)
- **Mixed precision:** AMP with GradScaler, gradient clipping (max_norm=5.0)
- **Data:** 50% real pairs + 50% synthetic degradation (speckle noise, Gaussian readout)
- **Seeds:** torch/random = 42
### Refinement Pipeline
| Stage | Epochs | Change | PSNR | Decision |
|-------|--------|--------|------|----------|
| Base | 100 | : | 28.58 dB | Baseline |
| Exp 1 | 15 | clip=False in degradation | 28.60 dB | Accepted |
| Exp 2 | 7 | w_grad=0.4, w_lpips=0.25 | ~26.7 dB | Rejected |
| Exp 2b (final) | 9 | w_grad=0.2, w_lpips=0.12 | 28.47 dB | Accepted |
**Final checkpoint:** `best_refined.pt` (epoch 9 of Exp 2b)
Exp 2b traded -0.13 dB PSNR for +2.87 points of sharpness (~22x the noise floor), with improved LPIPS (0.181 to 0.164).
## Setup
```bash
pip install -r requirements.txt
```
Place the trained checkpoint at:
```
models/restoration_best.pt
```
## Usage
```bash
python run.py <input-dir> <output-dir>
```
- `<input-dir>` : directory containing `.npy` degraded images (grayscale, float `[0,1]` or uint8 `[0,255]`)
- `<output-dir>` : directory where restored `.npy` files are written
Output images are saved as float32 `.npy` files with values in `[0, 1]`, shape `(H, W)` where `H = 2 * input_h` and `W = 2 * input_w`.
## Environment
- Python >= 3.10
- CUDA-capable GPU (NVIDIA, tested with CUDA 12.x)
- No internet access required at inference time