EntropyDrop/SKING_DDJ_Dataset

SKING_DDJ Public Generation & Preference Dataset

This repository contains data from public skin-generation tasks performed on EntropyDrop (entropydrop_website) with models in the SKING_DDJ series (e.g., SKING_DDJ_v54, SKING_DDJ_v61, SKING_DDJ_v61b, SKING_DDJ_v66).

The imported records are strictly scoped to public generations from this model family; private generations, platform manual in-browser edits, manual user uploads, and unrelated model families are excluded. Annotation-time repairs created by this repository’s editor are stored separately as {id}_perfect.png, preserving the imported candidate images.

In addition to source inputs, intermediate edited images, and final 64×64 RGBA skin textures, this dataset includes multi-version comparative candidate results (e.g. v101, v103, v104, v105) and human preference annotations (_best.txt, _perfect.txt, _all_rejected.txt). This makes the dataset suitable for:

• Supervised Fine-Tuning (SFT) for 2D-to-UV and Text-to-Skin models;
• Reward Modeling (RM) and Direct Preference Optimization (DPO / RLHF);
• Error diagnosis, UV alignment verification, and generation pipeline benchmarking.

---

📂 Repository Structure

SKING_DDJ_Dataset/
├── README.md                           # Dataset documentation and specifications
├── sync.sh                             # Production data synchronization script
├── find_results_without_source.py      # Scan & detect orphan result images lacking source images
├── results_without_source.txt          # Scan report generated by find_results_without_source.py
├── best_annotator/                     # Lightweight web annotation & preference ranking tool
│   ├── README.md                       # Annotator user manual & keyboard shortcuts
│   ├── app.py                          # Python 3.10+ standard-library HTTP server
│   ├── index.html                      # Vite source entry
│   ├── package.json / package-lock.json # Frontend dependencies and scripts
│   ├── vite.config.js                  # Build output and development API proxy
│   ├── src/                            # React UI and ported skin editor
│   ├── public/vendor/                  # Bundled skinview3d source assets
│   ├── static/                         # Production build served by Python (assets/ and vendor/)
│   ├── test_perfect.py                 # Perfect labels, repaired PNGs and rollback tests
│   ├── test_app.py                     # Unittest suite for annotator backend
│   └── test_ui.cjs                     # E2E UI flow test suite (via JSDOM)
└── entropydrop_website_generations/
    ├── SKING_DDJ_v54/                  # Generations & evaluations under model version v54
    ├── SKING_DDJ_v61/                  # Generations & evaluations under model version v61
    ├── SKING_DDJ_v61b/                 # Generations & evaluations under model version v61b
    └── SKING_DDJ_v66/                  # Generations & evaluations under model version v66

Sample File Hierarchy

Each generation task is identified by a unique, stable <generation_id>. Within each <model_version> directory, files are organized as follows:

entropydrop_website_generations/<model_version>/
├── <generation_id>_source.png              # Original user input image
├── <generation_id>_edited.png              # Intermediate edited figure image
├── <generation_id>_result.png              # Primary / baseline generated 64x64 skin
├── <generation_id>_result_<version>.png    # Multi-checkpoint comparative result (e.g. _result_v104.png)
├── <generation_id>_prompt.txt              # User prompt text (omitted when empty)
├── <generation_id>_best.txt                # Human preference: selected best candidate filename
├── <generation_id>_perfect.txt             # Perfect label: original candidate filename, same as best
├── <generation_id>_perfect.png             # Optional annotation-time repaired 64x64 skin
├── <generation_id>_all_rejected.txt        # Human preference: rejection label and rationale
├── <generation_id>_result_<ver>.uv_review.json # UV texel alignment & quality audit report
├── <generation_id>_source_err.png          # Input image associated with a failed generation
├── <generation_id>_edited_err.png          # Intermediate image associated with a failed generation
└── <generation_id>_result_err.png          # Result image associated with a failed generation

Image files use .png, .jpg, .jpeg, or .webp matching their original stored format (skin results are always RGBA PNGs).

---

🏷️ File Suffixes & Schema

Suffix / Pattern	Type	Description	Example / Content
_source	Image	Original input image supplied to the generation task.	2L4DPU434KNC82YY_source.png
_edited	Image	Intermediate figure image cropped, segmented, or preprocessed between pipeline stages.	2L4DPU434KNC82YY_edited.png
_result	Image	Primary / baseline generated 64×64 Minecraft skin UV texture.	2L4DPU434KNC82YY_result.png
_result_<version>	Image	Candidate skin texture generated by an alternative model checkpoint or UV parser version (e.g. v101, v103, v104, v105).	2L4DPU434KNC82YY_result_v104.png
_prompt.txt	Text	Text prompt associated with the generation task (UTF-8, omitted if empty).	"cyberpunk knight with glowing visor"
_best.txt	Label	Filename of the human-annotated best skin result among available candidates.	2L4DPU434KNC82YY_result_v104.png\n
_perfect.txt	Label	Perfect-quality annotation; records the original candidate filename, identical to best.	2L4DPU434KNC82YY_result_v104.png\n
_perfect.png	Image	Optional repaired 64×64 PNG saved by the annotation editor; does not replace the original result.	Present only after repair submission.
_all_rejected.txt	Label	Rejection annotation when no candidate is satisfactory. Contains the primary failure reason.	result_unsatisfied or edited_unsatisfied
_result_<ver>.uv_review.json	JSON	Diagnostic audit report covering UV symmetry, hair/beard masks, and texel mismatch counts.	JSON metadata
_source_err	Image	Input image from a task that failed validation checks (e.g., non-compliant viewing angle).	NORESULT_source_err.jpg
_edited_err	Image	Intermediate image from a failed validation task.	ABC_edited_err.png
_result_err	Image	Result image from a failed validation task.	ABC_result_err.png

Not every entry contains every optional file. For example, text-to-skin pipelines may lack _source images, intermediate stages may be bypassed, or prompts may have been left blank. A missing optional file does not indicate corruption.

---

🎯 Human Preference & Rejection Annotations

The dataset incorporates fine-grained human feedback collected via best_annotator:

1. Best Choice (_best.txt)

When annotators identify a clearly superior skin result among candidates (e.g. comparing baseline _result.png against _result_v101.png, _result_v104.png, etc.), {id}_best.txt is written. It contains solely the filename of the selected result:

2L4DPU434KNC82YY_result_v104.png

2. All Rejected (_all_rejected.txt)

When all candidate skin results fail quality expectations, annotators mark the entry as rejected, categorizing the root cause into {id}_all_rejected.txt:

Rejection Label	Meaning
result_unsatisfied	The input and intermediate edited images are acceptable, but all generated skin UV maps exhibit severe flaws, poor color mapping, artifacts, or broken layouts.
edited_unsatisfied	The failure originates earlier in the pipeline: the intermediate image (_edited.png) is poorly segmented, truncated, distorted, or hallucinated, preventing valid skin synthesis downstream.

3. Perfect Labels and Repaired Skins

“Select as best (perfect)” writes both {id}_best.txt and {id}_perfect.txt, each containing the original selected candidate filename followed by a newline. It does not create a new image.

“Repair and select as best (perfect)” opens the React skin editor with the intermediate edited image as a reference. Submission additionally writes {id}_perfect.png; the TXT files still identify the original candidate, not the repaired PNG. Original candidates remain unchanged. Opening the same perfect candidate again resumes its saved repair.

Saved state	_best.txt	_perfect.txt	_perfect.png	_all_rejected.txt
Unannotated / cleared	Absent	Absent	Absent	Absent
Best	Candidate filename	Absent	Absent	Absent
Perfect, without repair	Candidate filename	Same as best	Absent	Absent
Perfect, with repair	Candidate filename	Same as best	Repaired skin	Absent
Rejected	Absent	Absent	Absent	Rejection reason

Files are grouped by directory and generation ID. For a valid perfect annotation matching best with no rejection conflict, use the repaired PNG when present; otherwise use the original candidate named in best. A standalone perfect PNG is not sufficient evidence of a valid annotation. _edited remains the pipeline intermediate image and must not be confused with _perfect.png.

See the annotator file structure and state table for the source/build directory layout and scanner rules.

4. Mutual Exclusivity & Integrity

• _best.txt and _all_rejected.txt are strictly mutually exclusive: selecting a best candidate removes any prior _all_rejected.txt, and rejecting all candidates removes any prior _best.txt.
• Choosing ordinary best, rejecting, or clearing removes the previous perfect TXT and PNG. Choosing perfect without repair removes any previous repaired PNG. Repeated repair submission replaces the current repaired PNG.
• Individual files use temporary files and atomic replacement; revision checks cover best, rejected, perfect, and repaired-image contents. I/O failures trigger an attempt to restore prior files. This is not a cross-process or power-loss transaction; use one server instance per dataset directory.
• Skipping changes no files, including existing annotations.

---

🛠️ Tooling & Utilities

1. DDJ Best-Result Annotator (best_annotator/)

A self-contained web application for rapid side-by-side preference annotation.

• Features:
  • Zero external dependencies: runs on Python 3.10+ standard library.
  • Bundled 3D Minecraft skin renderer using skinview3d 3.4.2 (no CDN or Node required at runtime).
  • Side-by-side synchronized 3D preview and 2D UV layout for multiple candidate versions.
  • Keyboard shortcuts: 1–9 to pick the best result, S to skip temporarily, ← / → for navigation.
  • Completed-item subfilters for perfect, best (including perfect), best without perfect, and each rejection reason; progress follows the selected directory.
  • React skin editor with larger tool buttons and an edited-image reference panel.
• Usage:

  cd best_annotator
  python3 app.py --root ../entropydrop_website_generations --host 0.0.0.0 --port 8765
  

  Open http://localhost:8765 in a browser. See best_annotator/README.md for full details.
• Testing:

  python3 -m unittest discover -p "test_*.py"
  npm ci
  npm test
  

2. Orphan Result Scanner (find_results_without_source.py)

Scans directories recursively for generated skin results that have no matching {id}_source.png input image:

python3 find_results_without_source.py
# Or check a specific model version:
python3 find_results_without_source.py --version v104 --output missing_v104.txt

The scan results are published atomically to results_without_source.txt.

3. Production Data Synchronization (sync.sh)

Synchronizes public generations and assets from the production PostgreSQL database and S3 storage using entropydrop_backend/tools/download_public_skins.py:

bash sync.sh

---

⚠️ Error Samples (_err)

Generations that failed automated validation (e.g. failing camera angle, face orientation, or figure geometry checks) are deliberately preserved with the _err suffix.

• The _err designation applies to the task validation outcome.
• A _source_err file represents the original input for a failed task; it does not necessarily imply that the user's source image was corrupt, but rather that the pipeline failed to satisfy output constraints with it.
• These samples provide valuable negative examples for out-of-distribution detection, input sanitization, and classifier training.

---

📄 License

This dataset is distributed under the AGPL-3.0 license. See the LICENSE file for details.

---

🇨🇳 中文说明 (Chinese Documentation)

概述

本仓库收录来自 EntropyDrop 平台使用 SKING_DDJ 系列模型（如 SKING_DDJ_v54、SKING_DDJ_v61、SKING_DDJ_v61b、SKING_DDJ_v66 等）执行的公开皮肤生成任务数据。

导入记录仅包含该系列模型的公开生成，不含私人生成、平台网页端手动绘制编辑、用户手动上传皮肤以及非 DDJ 系列模型数据。在本仓库标注时产生的手工修复图另存为 {id}_perfect.png，保留导入的原候选图片。

除了原图、中间图、生成皮肤 UV 贴图与提示词外，数据集还包含多模型版本对照结果（如 v101、v103、v104、v105）以及人工偏好标注（_best.txt、_perfect.txt 与 _all_rejected.txt），可用于：

• 2D 图片到皮肤 UV 与 Prompt-to-Skin 模型的监督微调（SFT）；
• 奖励模型（Reward Model）训练与直接偏好优化（DPO / RLHF）；
• 皮肤 UV 贴图对称性分析、管线效果对比与消融实验。

文件后缀与规范

后缀 / 命名	类型	说明	示例 / 内容
_source	图片	用户上传的原始参考图。	2L4DPU434KNC82YY_source.png
_edited	图片	管线各阶段间生成或处理的中间身形图。	2L4DPU434KNC82YY_edited.png
_result	图片	基础版/默认生成的 64×64 Minecraft 皮肤 UV 贴图。	2L4DPU434KNC82YY_result.png
_result_<version>	图片	由不同模型或 UV 解析器 Checkpoint 生成的对比候选贴图（如 v101、v104、v105）。	2L4DPU434KNC82YY_result_v104.png
_prompt.txt	文本	任务附带的文本提示词（UTF-8，为空时省略）。	文本字符串
_best.txt	标注	人工选定的同组最佳候选结果文件名。	2L4DPU434KNC82YY_result_v104.png\n
_perfect.txt	标注	完美标注，内容与 best 相同，记录原候选文件名加换行。	2L4DPU434KNC82YY_result_v104.png\n
_perfect.png	图片	标注编辑器提交的 64×64 修复皮肤，不覆盖原 result。	仅修复提交后存在
_all_rejected.txt	标注	当所有候选均不满意时的不满意原因。	result_unsatisfied 或 edited_unsatisfied
_result_<ver>.uv_review.json	JSON	UV 像素对齐审计、对称性与胡须/发型检测报告。	JSON 详情
_source_err	图片	校验未通过任务的原图（如视角/姿态不符）。	ABC_source_err.jpg
_edited_err	图片	校验未通过任务的中间图。	ABC_edited_err.png
_result_err	图片	校验未通过任务的生成结果图。	ABC_result_err.png

人工偏好标注说明

• **最佳结果 (_best.txt)**：文件内容为所选的最佳结果图片文件名加换行符。
• **完美标注 (_perfect.txt)**：同时保留 _best.txt，两个文件均记录原候选文件名。
• **修复后完美 (_perfect.png)**：提交编辑器时另存修复图，两个 TXT 仍记录原候选名，不写 _perfect.png。有效完美标注存在修复图时，最终皮肤应读取修复图，否则读取 best 指向的原候选。_edited 始终是管线中间参考图。
• 状态切换：普通最佳、不满意、撤销都会清除旧 perfect TXT/PNG；直接选完美会清除旧修复图；暂时忽略不修改文件。
• 目录规则：同目录、同 ID 的图片与标注关联，不跨目录合并；代码与生产构建目录说明、状态文件对照表见 标注工具 README。
• **都不满意 (_all_rejected.txt)**：
  • result_unsatisfied：原图与中间图均正常，但生成的皮肤贴图质量差、产生噪点或破面；
  • edited_unsatisfied：中间身形图本身存在严重残缺、分割错误或形变，导致后续生成无意义。
• 互斥规则：最佳结果与不满意标记严格互斥，重选最佳会自动删除旧的 _all_rejected.txt，标记不满意会自动删除旧的 _best.txt。

工具集

1. best_annotator/ 最佳结果标注工具：
   • 基于 React + Vite、Python 3.10+ 标准库与内嵌 skinview3d 的 Web 标注系统，附带独立移植的皮肤编辑器；生产运行无需 Node；
   • 支持多版本 3D 皮肤与 2D UV 同步对比，数字键 1–9 快速选优，支持忽略跳过与撤销；
   • 运行方式：cd best_annotator && python3 app.py --root ../entropydrop_website_generations --port 8765。
2. find_results_without_source.py 孤立结果检测工具：
   • 递归扫描缺少对应 _source 原图的 _result 图片，原子写入 results_without_source.txt。
3. sync.sh 数据同步脚本：
   • 配合后端脚本通过 SSH 堡垒机从生产数据库与 S3 增量下载公开数据。