Home

Overview

Relevant source files

The following files were used as context for generating this wiki page:

XIVUpscaler (also known as clarity) is a manifest-driven, tiered, material-aware pipeline designed to upscale every vanilla FINAL FANTASY XIV texture—including character assets, world environments, and user interface elements—into Penumbra mod packages README.md:1-4.

As a continuation of kartoffels123/ffxiv_7_0_toolbox, the pipeline abandons monolithic batch scripts in favour of a relational SQLite-backed database (manifest.sqlite) README.md:6-18. Every texture is enumerated, classified by family and processing role, and tracked through a robust lifecycle. This architecture allows runs to be interrupted, resumed, selectively re-scoped after classifier updates, or re-queued following a game patch without repeating valid computations README.md:15-18.

graph TD
    A["plan\nEnumerate & Classify"] --> B["run\nGPU Inference & Tiling"]
    B --> C["pack\nPenumbra Mod Folders & .pmp"]
    C --> D["qa\nContamination & Metric Checks"]
    D --> E["release\nImmutable Profiles"]
    
    style A fill:none,stroke:#000,stroke-width:2px
    style B fill:none,stroke:#000,stroke-width:2px
    style C fill:none,stroke:#000,stroke-width:2px
    style D fill:none,stroke:#000,stroke-width:2px
    style E fill:none,stroke:#000,stroke-width:2px

Figure 1: High-level architectural pipeline flow from enumeration to release export. Sources: README.md:20-27, clarity/cli.py:22-42

Architecture Summary

The system is organized into decoupled layers responsible for database state tracking, FFXIV binary parsing, neural network inference, and packaging:

Command Dispatch & Pipeline Loop: Controlled via clarity/cli.py, orchestrating commands such as plan, estimate, run, pack, qa, and release README.md:78-95.
Manifest & SQLite Persistence: Managed by clarity/manifest.py, serving as the single source of truth for all discovered textures, processing states, and patch-delta markers tests/test_manifest_requeue.py:1-4.
Game Data Extraction: Implemented in clarity/ffxiv/, handling sqpack archives, .tex decoding/encoding (texdecode.py, texwrite.py), and material/model metadata (mtrl.py, mdlpatch.py) README.md:39.
Upscaling Engine & Processing: Driven by clarity/processing/engine.py using Spandrel-loaded models, coupled with role-specific post-processing (color.py, normals.py, masks.py, ui.py) README.md:28-30.
Texture I/O & Encoding: Coordinated via clarity/texio.py and texconv integration for fast GPU-accelerated DirectCompute block compression README.md:38.

Child Pages

For detailed documentation on specific subsystems, consult the following child pages:

Getting Started and Configuration — Installation via uv, Python version enforcement (3.11 or 3.12), environment variables (CLARITY_DB, CLARITY_MODELS, CLARITY_TEXCONV, CLARITY_SCRATCH), path resolution routines in clarity/paths.py, model registry specifications (registry.json), and setup diagnostics (clarity where) README.md:32-69.
Pipeline Lifecycle: plan → run → pack → qa → release — End-to-end walkthrough of stateful pipeline stages, database status transitions (planned, done, failed, skipped), and patch-delta tracking README.md:20-27.