Scripts and CI

Relevant source files

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

Purpose and Scope

This page covers the auxiliary helper scripts, benchmarking utilities, packaging conventions, and continuous integration (CI) workflows defined in the clarity repository. These components ensure cross-platform consistency, reproducible performance benchmarking for neural upscaling models and texture conversion tools, and automated validation via GitHub Actions and uv.

Sources: /.github/workflows/ci.yml:1-84, /scripts/generate_corpus.py:1-83

1. GitHub Actions CI Workflow and Environment

The project's continuous integration pipeline is defined in /.github/workflows/ci.yml:1-84 and relies on uv for dependency management and execution speed. The pipeline enforces a strict frozen-lockfile policy (UV_FROZEN: "1") to guarantee exact environment reproducibility across developer setups and remote runners /.github/workflows/ci.yml:16-20.

The workflow consists of three sequential and matrixed jobs:

lint: Runs on ubuntu-latest using Python 3.12. It executes ruff check, ruff format --check, and the type-checking utility ty check /.github/workflows/ci.yml:22-38.
test: Runs a test matrix over Python 3.11 and 3.12 (texture2ddecoder imposes a ceiling below Python 3.13) /.github/workflows/ci.yml:39-46. It executes pytest --cov with coverage reporting (coverage.xml) /.github/workflows/ci.yml:54-60.
build: Depends on lint and test. It creates source distributions and wheels via uv build, validates package metadata using twine check, installs the resulting wheel into an isolated virtual environment (/tmp/clean), verifies runtime package imports, and executes the CLI dispatch command clarity where /.github/workflows/ci.yml:62-84.

graph TD
    A["Push / Pull Request"] --> B["Job: lint (ruff + ty)"]
    A --> C["Job: test (pytest Python 3.11 & 3.12)"]
    B --> D["Job: build (sdist + wheel)"]
    C --> D
    D --> E["Clean Environment Smoke Test (clarity where)"]

    subgraph "CI Pipeline Actions"
        B
        C
        D
    end
    
    style A fill:#none
    style E fill:#none

Sources: /.github/workflows/ci.yml:1-84

2. Repository Conventions: Git Ignore and Git Attributes

To maintain clean source control while handling heavy game assets, build outputs, and platform-specific artifacts, the repository enforces strict ignore and attribute policies.

Git Ignore (`.gitignore`)

The ignore file prevents local build artifacts, temporary scratch directories, virtual environments, and proprietary game binaries from entering source control /.gitignore:1-40. Key patterns include:

Python Caches: __pycache__/, .ruff_cache/, .pytest_cache/, and coverage outputs /.gitignore:1-16.
Binary Game Formats: *.tex, *.dds, *.mtrl, *.shpk, *.png, *.tga, *.db, *.pmp /.gitignore:21-32.
Bulk Data & Tool Roots: build-output/, analysis-specimens/, temp-scratch/, vendor-tools/, hash-manifests/, benchmarks/ /.gitignore:34-40.

Git Attributes (`.gitattributes`)

The attribute file normalizes line endings and protects binary files from translation corruption /.gitattributes:1-12:

Line Ending Normalization: * text=auto eol=lf forces checkout to Unix LF globally, preventing platform-specific diff pollution between Windows development machines and Linux CI runners /.gitattributes:1-3.
Binary Protection: Explicitly marks weights, archives, and texture binaries as binary (*.pth, *.safetensors, *.tex, *.dds, *.pmp, *.7z, *.zip) /.gitattributes:5-12.

Sources: /.gitignore:1-40, /.gitattributes:1-12

3. Benchmark and Corpus Generation Scripts

Evaluating neural upscaling quality requires reproducible texture selections and automated inference testing against baseline images.

Corpus Generation (`scripts/generate_corpus.py`)

generate_corpus.py queries manifest.sqlite to build a deterministic, stratified evaluation corpus stored at benchmarks/color/corpus.json scripts/generate_corpus.py:1-83.

Stratification Strategy: Queries textures grouped by surface family prefix and source format (fmt), targeting categories such as equipment_BC1, monster_BC7, human-face_BC1, and bg_BC7 scripts/generate_corpus.py:25-50.
Deterministic Selection: Avoids random sampling in favor of ordered traversal (ORDER BY path) with calculated step sizes (len(all_paths) / PER_STRATUM), ensuring identical texture specimens are selected across benchmark runs scripts/generate_corpus.py:22-72.

Model Benchmarking (`scripts/benchmark_models.py`)

benchmark_models.py executes comparative A/B inference runs over the generated corpus scripts/benchmark_models.py:1-194.

Model Loading: Utilizes Spandrel via ModelLoader to load models such as 4x-PBRify_RPLKSRd_V3.pth, 4x-PBRify_UpscalerV4.pth, and the BC1 cleaning filter 1x_BC1-smooth2.pth into CUDA or CPU memory scripts/benchmark_models.py:95-122.
Inference and Cropping: Pulls raw textures via clarity.ffxiv.sqpack, routes tensors through engine.Engine._tiled(), extracts 512x512 center crops (crop_center), and serializes metadata alongside PNG outputs into benchmarks/color/results/ scripts/benchmark_models.py:64-190.

graph TD
    A["manifest.sqlite"] -->|"generate_corpus.py"| B["corpus.json"]
    B -->|"benchmark_models.py"| C["clarity.ffxiv.sqpack (GameData)"]
    C -->|"texio.read()"| D["Raw Texture Tensors"]
    D -->|"engine.Engine._tiled()"| E["Spandrel Models (RPLKSRd / UpscalerV4)"]
    E -->|"crop_center() & Image.save()"| F["benchmarks/color/results/"]

    subgraph "Corpus and Benchmark Flow"
        A
        B
        C
        D
        E
        F
    end

    style A fill:#none
    style F fill:#none

Sources: scripts/generate_corpus.py:1-83, scripts/benchmark_models.py:1-194.

4. Benchmark Visualization and Testing Scripts

Viewer Generation (`scripts/generate_viewer.py`)

generate_viewer.py parses the directory structure produced by benchmark_models.py and compiles a standalone HTML file (viewer.html) inside the results directory scripts/generate_viewer.py:1-142.

HTML Generation: Scans category folders and specimen subdirectories, injecting image tags for 1:1 center crops (*_crop.png) and full resolutions (*.png), alongside parsed metadata.json attributes scripts/generate_viewer.py:11-142.
Interactive UI: Embeds CSS styling, category tabs, modal image inspection, and a floating action button (exportVotes()) to aggregate human preference votes into clarity_votes.json scripts/generate_viewer.py:25-61.

Performance Benchmarking (`bench_texconv.py`)

Though focused on raw subsystem throughput rather than model accuracy, scripts like bench_texconv.py evaluate the execution speed and conversion fidelity of external DirectX texture compression utilities (texconv) against pure-Python fallbacks (bc7enc.py).

Sources: scripts/generate_viewer.py:1-142, clarity/ffxiv/README.md:1-21.

Home · Repository · Migrated from DeepWiki