Glossary

Glossary

Relevant source files

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

• README.md
• clarity/cli.py
• clarity/ffxiv/init.py
• clarity/ffxiv/mtrl.py
• clarity/ffxiv/texdecode.py
• clarity/jsonio.py
• clarity/manifest.py
• clarity/packaging/release.py
• clarity/processing/engine.py
• tests/test_manifest_requeue.py
• tests/test_single_sources.py

Purpose and Scope

This page defines the domain-specific terminology, file formats, architecture concepts, and data structures used throughout the XIVUpscaler (clarity) codebase. Each entry details its technical definition, role in the pipeline, and points to the relevant implementation files and functions.

---

Core Architecture & Storage Terms

sqpack

The proprietary archive format used by FINAL FANTASY XIV to store game assets across .index and .dat files (categorized by indices such as 0x01 for bgcommon, 0x02 for bg, 0x04 for chara, etc.). The codebase reads raw game files directly from these archives without external extraction tools.

• Code Pointers: [clarity/ffxiv/sqpack.py:1-120](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/sqpack.py?plain=1#L1-L120), [clarity/ffxiv/__init__.py:36-55](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/__init__.py?plain=1#L36-L55)
• Sources: [clarity/ffxiv/sqpack.py:1-120](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/sqpack.py?plain=1#L1-L120), [clarity/ffxiv/__init__.py:36-55](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/__init__.py?plain=1#L36-L55)

manifest.sqlite

The SQLite database acting as the single source of truth for the pipeline. It tracks every enumerated vanilla texture, its classification (family, role, dimensions, format), current processing status (planned, done, failed, skipped), output tiers, and content hashes.

• Code Pointers: [clarity/manifest.py:102-130](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L102-L130), [clarity/cli.py:22-42](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L22-L42)
• Sources: [clarity/manifest.py:102-130](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L102-L130), [clarity/cli.py:22-42](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L22-L42)

scratch dir

A dedicated temporary directory used during texture encoding (texio). It receives uncompressed RGBA DDS staging files before they are fed into texconv. Pointing this to a RAM disk or high-speed SSD avoids excessive write wear on system drives during massive multi-day batch runs.

• Code Pointers: [README.md:66-74](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L66-L74), [clarity/texio.py:1-50](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/texio.py?plain=1#L1-L50)
• Sources: [README.md:66-74](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L66-L74), [clarity/texio.py:1-50](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/texio.py?plain=1#L1-L50)

ResLogger pathlist

A compressed plain-text list of game paths captured during runtime via ResLogger (CurrentPathList*.gz). Used during manifest planning to discover asset paths (especially in bg/, bgcommon/, and ui/uld/) that cannot be fully enumerated via static metadata alone.

• Code Pointers: [README.md:41-68](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L41-L68), [clarity/manifest.py:9-11](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L9-L11)
• Sources: [README.md:41-68](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L41-L68), [clarity/manifest.py:9-11](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L9-L11)

fingerprint / srchash

A cryptographic content hash (SHA-256) of the source texture (.tex) recorded in the manifest table (srchash) along with snapshots (fpsnap). Used by fingerprint --check to detect game patch modifications and dynamically compute re-queue sets rather than relying on manual guesses.

• Code Pointers: [README.md:93-99](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L93-L99), [clarity/manifest.py:113-128](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L113-L128), [tests/test_manifest_requeue.py:77-88](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/tests/test_manifest_requeue.py?plain=1#L77-L88)
• Sources: [README.md:93-99](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L93-L99), [clarity/manifest.py:113-128](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L113-L128), [tests/test_manifest_requeue.py:77-88](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/tests/test_manifest_requeue.py?plain=1#L77-L88)

requeue

A maintenance operation that resets row statuses in manifest.sqlite back to planned (filtered by failure status, skipped status, or old recipes) while selectively preserving patch-delta markers such as changed at <version>.

• Code Pointers: [clarity/manifest.py:1-168](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L1-L168), [tests/test_manifest_requeue.py:35-55](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/tests/test_manifest_requeue.py?plain=1#L35-L55)
• Sources: [clarity/manifest.py:1-168](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L1-L168), [tests/test_manifest_requeue.py:35-55](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/tests/test_manifest_requeue.py?plain=1#L35-L55)

preview release

An immutable versioned export designation (e.g., 7.56.0-preview.1) generated during release packaging. It allows validation of specific build profiles before marking a release as stable.

• Code Pointers: [clarity/packaging/release.py:60-78](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L60-L78), [clarity/packaging/release.py:140-156](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L140-L156)
• Sources: [clarity/packaging/release.py:60-78](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L60-L78), [clarity/packaging/release.py:140-156](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L140-L156)

---

Game Formats & Data Structures

.tex, .mtrl, .mdl, .imc

Core FFXIV binary file types read and manipulated by the codebase:

• .tex: Texture container with headers, dimensions, mip counts, and surface offsets ([clarity/ffxiv/tex.py:1-80](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/tex.py?plain=1#L1-L80), [clarity/ffxiv/texdecode.py:1-96](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/texdecode.py?plain=1#L1-L96)).
• .mtrl: Material configuration containing shader package references, texture lists, samplers, and colour tables ([clarity/ffxiv/mtrl.py:1-107](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/mtrl.py?plain=1#L1-L107)).
• .mdl: Model geometry container whose internal string tables are patched when scaling or redirecting paths ([clarity/ffxiv/mdlstrings.py:1-50](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/mdlstrings.py?plain=1#L1-L50), [clarity/ffxiv/mdlpatch.py:1-40](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/mdlpatch.py?plain=1#L1-L40)).
• .imc: Variant index tables mapping equipment pieces to material variants ([clarity/ffxiv/imcfile.py:1-60](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/imcfile.py?plain=1#L1-L60)).
• Sources: [clarity/ffxiv/tex.py:1-80](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/tex.py?plain=1#L1-L80), [clarity/ffxiv/mtrl.py:1-107](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/mtrl.py?plain=1#L1-L107), [clarity/ffxiv/mdlstrings.py:1-50](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/mdlstrings.py?plain=1#L1-L50), [clarity/ffxiv/imcfile.py:1-60](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/imcfile.py?plain=1#L1-L60)

mip

A mipmap level within a texture file. Mip 0 represents the full resolution image, while higher mip indices represent progressively halved downscaled versions. The pipeline decodes, upscales, and re-encodes mip 0, then derives smaller mips via box filtering.

• Code Pointers: [clarity/ffxiv/tex.py:1-60](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/tex.py?plain=1#L1-L60), [clarity/ffxiv/texdecode.py:86-97](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/texdecode.py?plain=1#L86-L97)
• Sources: [clarity/ffxiv/tex.py:1-60](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/tex.py?plain=1#L1-L60), [clarity/ffxiv/texdecode.py:86-97](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/texdecode.py?plain=1#L86-L97)

BC1-BC7

Block Compression texture formats used by DirectX and FFXIV. BC1 (DXT1) uses 8-byte blocks for RGB with 1-bit alpha; BC3 (DXT5) uses 16-byte blocks with explicit interpolated alpha; BC7 uses 16-byte blocks for high-quality PBR textures. Decoded via texture2ddecoder or pure-Python fallbacks.

• Code Pointers: [README.md:36-38](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L36-L38), [clarity/ffxiv/texdecode.py:18-147](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/texdecode.py?plain=1#L18-L147), [clarity/ffxiv/bc7enc.py:1-100](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/bc7enc.py?plain=1#L1-L100)
• Sources: [README.md:36-38](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L36-L38), [clarity/ffxiv/texdecode.py:18-147](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/texdecode.py?plain=1#L18-L147), [clarity/ffxiv/bc7enc.py:1-100](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/bc7enc.py?plain=1#L1-L100)

BGRA8

An uncompressed 32-bit pixel format (8 bits per channel for Blue, Green, Red, Alpha) used as the intermediate working format in memory before neural network upscaling and subsequent re-compression to BC7 or BC1.

• Code Pointers: [clarity/cli.py:68-68](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L68-L68), [clarity/ffxiv/texdecode.py:115-117](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/texdecode.py?plain=1#L115-L117)
• Sources: [clarity/cli.py:68-68](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L68-L68), [clarity/ffxiv/texdecode.py:115-117](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/texdecode.py?plain=1#L115-L117)

Dawntrail shader

The modern character.shpk material shader introduced in the 7.0 expansion. The codebase includes automated migration logic to upgrade legacy materials (characterlegacy.shpk) by swapping shader packages, stripping obsolete keys/constants, and retaining colour table parameters.

• Code Pointers: [clarity/ffxiv/mtrl.py:1-54](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/mtrl.py?plain=1#L1-L54), [clarity/ffxiv/mtrl.py:100-112](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/mtrl.py?plain=1#L100-L112)
• Sources: [clarity/ffxiv/mtrl.py:1-54](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/mtrl.py?plain=1#L1-L54), [clarity/ffxiv/mtrl.py:100-112](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/mtrl.py?plain=1#L100-L112)

icon twins

Paired UI icon asset handling where high-resolution or alternate UI variants are processed in tandem to maintain visual consistency across inventory and hotbar grids.

• Code Pointers: [clarity/uldparts.py:1-40](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/uldparts.py?plain=1#L1-L40), [clarity/cli.py:15-15](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L15-L15)
• Sources: [clarity/uldparts.py:1-40](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/uldparts.py?plain=1#L1-L40), [clarity/cli.py:15-15](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L15-L15)

---

Pipeline Classification & Processing

family

A high-level asset categorization grouping game paths into logical processing domains (e.g., equipment, accessory, weapon, monster, human-face, bg, ui-icon). Families determine policy rules, target output tiers, and Penumbra mod folder structures.

• Code Pointers: [clarity/manifest.py:30-65](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L30-L65), [clarity/packaging/release.py:17-56](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L17-L56)
• Sources: [clarity/manifest.py:30-65](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L30-L65), [clarity/packaging/release.py:17-56](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L17-L56)

role

The functional category assigned to a texture (id, normal, mask, color, icon, ui, skip). The role dictates which neural network model slot is invoked and what post-processing rules apply (e.g., normal maps must preserve unit length; mask channels must remain independent scalars).

• Code Pointers: [clarity/manifest.py:12-22](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L12-L22), [clarity/manifest.py:66-86](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L66-L86), [clarity/processing/roles.py:1-50](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/roles.py?plain=1#L1-L50)
• Sources: [clarity/manifest.py:12-22](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L12-L22), [clarity/manifest.py:66-86](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L66-L86), [clarity/processing/roles.py:1-50](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/roles.py?plain=1#L1-L50)

tier

The resolution scaling factor applied during upscaling and packaging (native, 2x, 4x). Each family and role combination has a policy-defined ceiling (MAX_EDGE_OUT) restricting maximum output dimensions.

• Code Pointers: [clarity/cli.py:65-71](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L65-L71), [clarity/packaging/release.py:94-108](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L94-L108)
• Sources: [clarity/cli.py:65-71](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L65-L71), [clarity/packaging/release.py:94-108](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L94-L108)

model slot

An identifier mapping a processing category (bc1clean, normal, color, face, skin, hair, ui) to a specific neural network weight file (.pth or .safetensors) configured in registry.json.

• Code Pointers: [clarity/processing/engine.py:5-48](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/engine.py?plain=1#L5-L48), [clarity/processing/engine.py:91-127](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/engine.py?plain=1#L91-L127)
• Sources: [clarity/processing/engine.py:5-48](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/engine.py?plain=1#L5-L48), [clarity/processing/engine.py:91-127](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/engine.py?plain=1#L91-L127)

spandrel

An external Python library used by the Engine class to load and execute neural network architectures (such as ESRGAN, DAT, and RealPLKSR) on PyTorch-compatible GPUs.

• Code Pointers: [clarity/processing/engine.py:1-4](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/engine.py?plain=1#L1-L4), [clarity/processing/engine.py:120-128](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/engine.py?plain=1#L120-L128)
• Sources: [clarity/processing/engine.py:1-4](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/engine.py?plain=1#L1-L4), [clarity/processing/engine.py:120-128](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/engine.py?plain=1#L120-L128)

texconv

Microsoft's DirectXTex command-line utility (texconv.exe) used for high-performance GPU-accelerated texture compression (DirectCompute BC7/BC6H encoding). The pipeline probes texconv at startup to ensure it runs on the GPU rather than falling back to an unoptimized CPU codec.

• Code Pointers: [README.md:36-38](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L36-L38), [clarity/cli.py:95-123](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L95-L123), [clarity/texio.py:1-80](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/texio.py?plain=1#L1-L80)
• Sources: [README.md:36-38](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L36-L38), [clarity/cli.py:95-123](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L95-L123), [clarity/texio.py:1-80](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/texio.py?plain=1#L1-L80)

policy version

A version string (e.g., everyday-1) embedded in export manifests to track rules governing generation tiers, profile restrictions, and fallback exceptions.

• Code Pointers: [clarity/packaging/release.py:57-58](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L57-L58), [clarity/packaging/release.py:165-172](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L165-L172)
• Sources: [clarity/packaging/release.py:57-58](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L57-L58), [clarity/packaging/release.py:165-172](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L165-L172)

profile

A release generation preset (everyday, legacy, native, 2x, 4x) determining how target tiers are selected for families and materials during packaging and release export.

• Code Pointers: [clarity/packaging/release.py:81-93](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L81-L93), [clarity/packaging/release.py:177-183](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L177-L183)
• Sources: [clarity/packaging/release.py:81-93](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L81-L93), [clarity/packaging/release.py:177-183](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L177-L183)

---

Packaging & Distribution

Penumbra

The external FFXIV mod framework utilized as the target output structure. The pipeline compiles upscaled textures, metadata, and option groups into Penumbra-compatible mod directories.

• Code Pointers: [README.md:3-4](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L3-L4), [clarity/packaging/penumbra.py:1-60](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/penumbra.py?plain=1#L1-L60)
• Sources: [README.md:3-4](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/README.md?plain=1#L3-L4), [clarity/packaging/penumbra.py:1-60](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/penumbra.py?plain=1#L1-L60)

.pmp

A Penumbra Packed Mod archive format created by the packaging stage to bundle mod folders into a single distributable archive file.

• Code Pointers: [clarity/packaging/penumbra.py:100-150](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/penumbra.py?plain=1#L100-L150)
• Sources: [clarity/packaging/penumbra.py:100-150](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/penumbra.py?plain=1#L100-L150)

sort_order.json

A configuration file utilized by Penumbra collection merging and mod precedence resolution to ensure proper layering of upscaled asset categories.

• Code Pointers: [clarity/packaging/penumbra.py:70-95](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/penumbra.py?plain=1#L70-L95)
• Sources: [clarity/packaging/penumbra.py:70-95](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/penumbra.py?plain=1#L70-L95)

reserved paths

A set of mandatory placeholder and dummy asset paths (such as common/graphics/texture/dummy.tex) shared across families that are excluded from mod generation to prevent overwriting core engine fallbacks.

• Code Pointers: [clarity/packaging/penumbra.py:20-35](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/penumbra.py?plain=1#L20-L35), [clarity/packaging/release.py:135-138](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L135-L138), [tests/test_single_sources.py:17-19](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/tests/test_single_sources.py?plain=1#L17-L19)
• Sources: [clarity/packaging/penumbra.py:20-35](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/penumbra.py?plain=1#L20-L35), [clarity/packaging/release.py:135-138](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/packaging/release.py?plain=1#L135-L138), [tests/test_single_sources.py:17-19](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/tests/test_single_sources.py?plain=1#L17-L19)

---

Architectural Mapping Diagrams

Diagram 1: Pipeline Classification & State Mapping

This diagram bridges natural language concepts (manifest.sqlite, family, role, tier, requeue) directly to their underlying code entities and functions in manifest.sqlite and cli.py.

graph TD
    subgraph "Natural Language Space"
        NL_DB["Manifest Database"]
        NL_FAM["Asset Family"]
        NL_ROLE["Processing Role"]
        NL_TIER["Output Tier"]
        NL_REQ["Requeue Operation"]
    end

    subgraph "Code Entity Space"
        CE_DB["clarity/manifest.py:SCHEMA"]
        CE_ADD["clarity/manifest.py:Manifest.add()"]
        CE_CLASS["clarity/manifest.py:classify()"]
        CE_ROLES["clarity/processing/roles.py:POLICY"]
        CE_TOP["clarity/processing/roles.py:top_tier()"]
        CE_REQ["clarity/manifest.py:Manifest.requeue()"]
    end

    NL_DB --> CE_DB
    NL_DB --> CE_ADD
    NL_FAM --> CE_CLASS
    NL_ROLE --> CE_CLASS
    NL_ROLE --> CE_ROLES
    NL_TIER --> CE_TOP
    NL_REQ --> CE_REQ

Loading

Sources: [clarity/manifest.py:30-130](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/manifest.py?plain=1#L30-L130), [clarity/processing/roles.py:1-50](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/roles.py?plain=1#L1-L50), [clarity/cli.py:22-42](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/cli.py?plain=1#L22-L42)

Diagram 2: Inference Engine & Texture Encoding

This diagram bridges natural language upscaling concepts (model slot, spandrel, texconv, scratch dir, BC1-BC7) to the engine and texture I/O classes.

graph TD
    subgraph "Natural Language Space"
        NL_SLOT["Model Slot"]
        NL_SPAN["Spandrel Loader"]
        NL_CONV["Texconv Tool"]
        NL_SCRATCH["Scratch Directory"]
        NL_FMT["Block Compression (BC1-BC7)"]
    end

    subgraph "Code Entity Space"
        CE_REG["clarity/processing/engine.py:DEFAULT_REGISTRY"]
        CE_ENG["clarity/processing/engine.py:Engine.model()"]
        CE_TEXCONV["clarity/texio.py:use_texconv()"]
        CE_SCRATCH_VAR["clarity/paths.py:SCRATCH"]
        CE_DEC["clarity/ffxiv/texdecode.py:decode_raw()"]
    end

    NL_SLOT --> CE_REG
    NL_SPAN --> CE_ENG
    NL_CONV --> CE_TEXCONV
    NL_SCRATCH --> CE_SCRATCH_VAR
    NL_FMT --> CE_DEC

Loading

Sources: [clarity/processing/engine.py:1-128](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/processing/engine.py?plain=1#L1-L128), [clarity/texio.py:1-80](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/texio.py?plain=1#L1-L80), [clarity/ffxiv/texdecode.py:18-147](https://github.com/off-cmd/XIVUpscaler/blob/5c9360ae/clarity/ffxiv/texdecode.py?plain=1#L18-L147)