SKING_DDJ_v104/README.md

# SKING_DDJ_v104

Production v104 render-to-UV release, published on 2026-09-08. It converts a square combined front/back Minecraft character render into a 64×64 RGBA skin with inner and outer layers. The left view is `front_left` and the right view is `back_left`, following the Sking edited-render layout. This is the UV parsing stage; creating the edited character render is a separate upstream stage.

The parser, trained foreground model, pipeline settings, and included runtime Python files are byte-identical to the deployed release based on source commit `43e676d8231fd3417d86721edb4ef4cef3dda40d`. The portable launcher overrides the checkpoint's machine-specific UV mappings path in memory. It does not rewrite weights or change model predictions.

## Contents

| Path | Purpose |
| --- | --- |
| `parser.pt` | v104 dense UV parser and trained semantic components |
| `foreground.pt` | Trained Minecraft foreground model |
| `pipeline.json` | Pinned foreground, semantic routing and final material fitting configuration |
| `foreground_base/` | BiRefNet base model and implementation |
| `hf_cache/` | Pinned SigLIP2 model and tokenizer for offline inference |
| `runtime/` | Matching inference/source code snapshot |
| `mappings_256x512/` | UV mapping tensors used by production |
| `infer.py` | Portable foreground + parser + final inpainting launcher |
| `release.json` | SHA-256 checksums and production artifact identities |
| `tested_environments.json` | Dependency versions used for verification |

Download the entire directory, approximately 2.58 GB. `parser.pt` alone is insufficient to reproduce the full pipeline. Older v54/v61/v66 files elsewhere in this repository remain available for their corresponding runtimes.

## Download

```python
from huggingface_hub import snapshot_download

snapshot_download(
    repo_id="EntropyDrop/Sking",
    allow_patterns=["SKING_DDJ_v104/*"],
    local_dir="./Sking",
)
```

For repeatable deployments, pass the release commit hash as `revision` instead of following the repository's moving default branch.

## Run

Use Linux with an NVIDIA CUDA GPU and Python 3.12. Verification used PyTorch 2.8.0 with CUDA 12.8, Transformers 5.0.0, and the package versions in `tested_environments.json`. The parser and foreground stage were tested in separate existing environments; that JSON records their versions, rather than claiming a newly created environment has been tested.

The parser environment needs PyTorch/torchvision, NumPy, Pillow, Transformers, timm, einops, SciPy, OpenCV, SentencePiece, safetensors and accelerate. The foreground environment also uses kornia. Install a CUDA-compatible PyTorch build before the remaining dependencies. Supply the appropriate interpreters below; both options may point to the same interpreter if its dependencies are compatible.

```bash
python ./Sking/SKING_DDJ_v104/infer.py --verify-only

/path/to/parser-env/bin/python ./Sking/SKING_DDJ_v104/infer.py \
  --parser-python /path/to/parser-env/bin/python \
  --foreground-python /path/to/foreground-env/bin/python \
  --input ./character_edited.png \
  --output ./character_result_v104.png
```

Input must be an even square image between 256 and 4096 pixels wide, containing the two expected views side by side. The launcher verifies the bundle, runs the trained foreground model, executes the pinned parser and postprocessing pipeline, validates output provenance, and writes the final 64×64 RGBA PNG. Model inference uses the included Hugging Face cache with offline mode enabled. Runtime paths can be relocated without recreating the training server's directory layout.

`pipeline.json` retains historical development/cache metadata to preserve its production checksum. The launcher supplies foreground predictions explicitly, so those historical paths are not used for its inference. `release.json` uses the portable `sking-hf-bundle-v1` format; it is separate from the private, machine-specific manifest used to configure the production worker.

## Validation and limits

Publication validation compares independent-directory outputs with existing production v104 references for eye, hair and beard cases. Alpha must match exactly; visible RGB channel differences must be at most 1/255. The release is not guaranteed to produce identical PNG file hashes across processes or GPUs. Semantic errors can still occur, and the model assumes the expected edited-render layout.

This package does not include user input images, deployment credentials, server configuration backups, or historical regression image galleries.

## License and upstream components

Sking is licensed under AGPL-3.0; see `LICENSE`. BiRefNet and SigLIP2 retain their own licenses and attribution. See `THIRD_PARTY_NOTICES.md` and the included `licenses/` directory for their exact pinned model revisions and license texts.