anime-core-lib-portrait-tool 0.1.0__tar.gz

anime_core_lib_portrait_tool-0.1.0/.gitignore

@@ -0,0 +1,224 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+*.lcov
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# uv
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi/*
+!.pixi/config.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule*
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs/Zensical documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore that
+#   can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, you
+#   could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+# Local example assets and generated DDS files
+/examples/images/
+/examples/output/

anime_core_lib_portrait_tool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cwlm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

anime_core_lib_portrait_tool-0.1.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.5
+Name: anime-core-lib-portrait-tool
+Version: 0.1.0
+Summary: Automatic and manual portrait composition and DDS export for Anime Core Lib
+Project-URL: Repository, https://github.com/cwlm/anime_core_lib_portrait_tool
+Author: cwlm
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: pillow>=13.0.0
+Provides-Extra: auto
+Requires-Dist: dghs-imgutils>=0.19.0; extra == 'auto'
+Requires-Dist: onnxruntime>=1.31.1; extra == 'auto'
+Provides-Extra: gpu
+Requires-Dist: dghs-imgutils>=0.19.0; extra == 'gpu'
+Requires-Dist: onnxruntime-gpu>=1.31.1; extra == 'gpu'
+Provides-Extra: gui
+Requires-Dist: pyside6-essentials>=6.12.0; extra == 'gui'
+Description-Content-Type: text/markdown
+
+# 透明立绘转 DDS
+
+单图自动／手动处理工具，每次调用处理一张图片。默认输出 1024×1024（可配置）、直通 Alpha、单层 BC3／DXT5 DDS。
+
+## 安装
+
+项目使用 pyproject.toml 和 Hatchling 管理依赖与打包，需要 Python 3.12 或更新版本。Windows 上完整自动处理目前使用 Python 3.12：自动检测库依赖 NumPy 1.x，暂不能在更新的 Python 上安装。
+
+在项目目录按需安装，pip 默认选择稳定版：
+
+```powershell
+# 自动处理（CPU）和手动界面
+python -m pip install --upgrade ".[auto,gui]"
+
+# NVIDIA GPU 自动处理和手动界面
+python -m pip install --upgrade ".[gpu,gui]"
+
+# 仅图片读取、渲染和编码接口
+python -m pip install --upgrade .
+```
+
+auto 和 gpu 二选一，避免同时安装 CPU 和 GPU 版 ONNX Runtime。开发时可加 -e 使用可编辑安装。
+
+NVTT 或 texconv 自行安装，调用时必须传入名称和可执行文件路径。
+
+```powershell
+portrait auto --input source.png --output result.dds --encoder nvtt --encoder-path 'C:/Tools/nvtt_export.exe' --model-cache ./models
+portrait manual --input source.png --output result.dds --encoder texconv --encoder-path 'C:/Tools/texconv.exe'
+```
+
+手动窗口：左键拖动／滚轮调整图片；Ctrl+滚轮缩放查看，中键或右键平移视图。“查看完整画布”重置视图，查看操作不改变输出构图。右侧可以输入缩放百分比及左上角 X／Y，“立绘居中”重置排版。白框是输出画布，橙框是脸部参考，青框是原图边界，紫框是可见内容边界；辅助框不写入 DDS。点击保存或 Ctrl+S 导出，取消不写文件；默认禁止覆盖，--overwrite 允许覆盖。
+
+命令行默认离线。--model-cache 指定 Hugging Face 缓存；需要下载模型时自行设置 HF_HUB_OFFLINE=0。
+
+命令行退出码：0 已保存，2 需手动处理或已取消，1 处理错误。
+
+## 画布与构图配置
+
+默认画布为 1024×1024。自动和手动入口都支持 --layout，使用同一套画布、脸部参考及活动范围。配置示例见 examples/layout.json：
+
+```powershell
+portrait manual --input source.png --output result.dds --encoder nvtt --encoder-path 'C:/Tools/nvtt_export.exe' --layout examples/layout.json
+```
+
+修改 canvas 时，一并设置 anchor、face_size、anchor_x 和 anchor_y；坐标单位均为输出像素。margin 是内容边距，alpha_core 和 face_threshold 分别控制自动取景的 Alpha 阈值与主脸置信度。
+
+Python 接口使用 load_layout(path) 或 Layout(...)；将 layout 传给 prepare、estimate_transform 和 render 即可。
+
+## Python 接口
+
+auto.prepare(input_path, output_path, ...) 自动构图并导出，成功返回 True，无可靠主脸时返回 False。无脸、低分、大小相近的多脸和空透明图都可能需要手动构图。
+
+manual.prepare(input_path, output_path, ...) 打开手动构图窗口，保存返回 True，取消返回 False。两个入口都接受 encoder、encoder_path、layout 和 overwrite 参数；默认禁止覆盖已有输出，处理错误会抛出异常。
+
+```python
+from anime_core_lib_portrait_tool.auto import prepare
+from anime_core_lib_portrait_tool import read_image, estimate_transform, render, write_dds
+
+prepare("source.png", "result.dds",
+        encoder="texconv", encoder_path="C:/Tools/texconv.exe")
+
+image = read_image("source.png")
+placement = estimate_transform(image)  # 无可靠主脸时返回 None
+if placement is not None:
+    candidate = render(image, placement)
+    write_dds("other.dds", candidate,
+              encoder="nvtt", encoder_path="C:/Tools/nvtt_export.exe")
+```
+
+数值接口使用 Placement(scale, x, y)，坐标为 EXIF 转正后的原图坐标：输出 = 原图 × scale + 偏移。自动构图使用动漫人脸模型和 Alpha 内容边界；装饰面积较大的图片可能把人物缩得更小。

anime_core_lib_portrait_tool-0.1.0/README.md

@@ -0,0 +1,70 @@
+# 透明立绘转 DDS
+
+单图自动／手动处理工具，每次调用处理一张图片。默认输出 1024×1024（可配置）、直通 Alpha、单层 BC3／DXT5 DDS。
+
+## 安装
+
+项目使用 pyproject.toml 和 Hatchling 管理依赖与打包，需要 Python 3.12 或更新版本。Windows 上完整自动处理目前使用 Python 3.12：自动检测库依赖 NumPy 1.x，暂不能在更新的 Python 上安装。
+
+在项目目录按需安装，pip 默认选择稳定版：
+
+```powershell
+# 自动处理（CPU）和手动界面
+python -m pip install --upgrade ".[auto,gui]"
+
+# NVIDIA GPU 自动处理和手动界面
+python -m pip install --upgrade ".[gpu,gui]"
+
+# 仅图片读取、渲染和编码接口
+python -m pip install --upgrade .
+```
+
+auto 和 gpu 二选一，避免同时安装 CPU 和 GPU 版 ONNX Runtime。开发时可加 -e 使用可编辑安装。
+
+NVTT 或 texconv 自行安装，调用时必须传入名称和可执行文件路径。
+
+```powershell
+portrait auto --input source.png --output result.dds --encoder nvtt --encoder-path 'C:/Tools/nvtt_export.exe' --model-cache ./models
+portrait manual --input source.png --output result.dds --encoder texconv --encoder-path 'C:/Tools/texconv.exe'
+```
+
+手动窗口：左键拖动／滚轮调整图片；Ctrl+滚轮缩放查看，中键或右键平移视图。“查看完整画布”重置视图，查看操作不改变输出构图。右侧可以输入缩放百分比及左上角 X／Y，“立绘居中”重置排版。白框是输出画布，橙框是脸部参考，青框是原图边界，紫框是可见内容边界；辅助框不写入 DDS。点击保存或 Ctrl+S 导出，取消不写文件；默认禁止覆盖，--overwrite 允许覆盖。
+
+命令行默认离线。--model-cache 指定 Hugging Face 缓存；需要下载模型时自行设置 HF_HUB_OFFLINE=0。
+
+命令行退出码：0 已保存，2 需手动处理或已取消，1 处理错误。
+
+## 画布与构图配置
+
+默认画布为 1024×1024。自动和手动入口都支持 --layout，使用同一套画布、脸部参考及活动范围。配置示例见 examples/layout.json：
+
+```powershell
+portrait manual --input source.png --output result.dds --encoder nvtt --encoder-path 'C:/Tools/nvtt_export.exe' --layout examples/layout.json
+```
+
+修改 canvas 时，一并设置 anchor、face_size、anchor_x 和 anchor_y；坐标单位均为输出像素。margin 是内容边距，alpha_core 和 face_threshold 分别控制自动取景的 Alpha 阈值与主脸置信度。
+
+Python 接口使用 load_layout(path) 或 Layout(...)；将 layout 传给 prepare、estimate_transform 和 render 即可。
+
+## Python 接口
+
+auto.prepare(input_path, output_path, ...) 自动构图并导出，成功返回 True，无可靠主脸时返回 False。无脸、低分、大小相近的多脸和空透明图都可能需要手动构图。
+
+manual.prepare(input_path, output_path, ...) 打开手动构图窗口，保存返回 True，取消返回 False。两个入口都接受 encoder、encoder_path、layout 和 overwrite 参数；默认禁止覆盖已有输出，处理错误会抛出异常。
+
+```python
+from anime_core_lib_portrait_tool.auto import prepare
+from anime_core_lib_portrait_tool import read_image, estimate_transform, render, write_dds
+
+prepare("source.png", "result.dds",
+        encoder="texconv", encoder_path="C:/Tools/texconv.exe")
+
+image = read_image("source.png")
+placement = estimate_transform(image)  # 无可靠主脸时返回 None
+if placement is not None:
+    candidate = render(image, placement)
+    write_dds("other.dds", candidate,
+              encoder="nvtt", encoder_path="C:/Tools/nvtt_export.exe")
+```
+
+数值接口使用 Placement(scale, x, y)，坐标为 EXIF 转正后的原图坐标：输出 = 原图 × scale + 偏移。自动构图使用动漫人脸模型和 Alpha 内容边界；装饰面积较大的图片可能把人物缩得更小。

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/__init__.py

@@ -0,0 +1,4 @@
+"""Portrait composition and DDS encoding."""
+from .transform import Placement, read_image, render, estimate_transform
+from .dds import write_dds
+from .config import Layout, load_layout

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/auto.py

@@ -0,0 +1,17 @@
+"""Single-image automatic processing; False means manual composition is needed."""
+from pathlib import Path
+from .dds import write_dds
+from .config import Layout
+from .transform import read_image, estimate_transform, render
+
+
+def prepare(input_path, output_path, *, encoder, encoder_path, layout=Layout(), overwrite=False):
+    if Path(input_path).resolve() == Path(output_path).resolve():
+        raise ValueError("输入和输出不能相同")
+    image = read_image(input_path)
+    placement = estimate_transform(image,layout=layout)
+    if placement is None:
+        return False
+    write_dds(output_path, render(image,placement,layout=layout), encoder=encoder,
+              encoder_path=encoder_path, overwrite=overwrite)
+    return True

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/cli.py

@@ -0,0 +1,38 @@
+"""Arguments for single-image processing."""
+import argparse
+import os
+from pathlib import Path
+from .config import load_layout
+
+
+def arguments(argv=None):
+    parser = argparse.ArgumentParser()
+    parser.add_argument("mode", choices=("auto", "manual"))
+    parser.add_argument("--input", required=True, type=Path)
+    parser.add_argument("--output", required=True, type=Path)
+    parser.add_argument("--encoder", required=True, choices=("nvtt", "texconv"))
+    parser.add_argument("--encoder-path", required=True, type=Path)
+    parser.add_argument("--overwrite", action="store_true")
+    parser.add_argument("--model-cache", type=Path)
+    parser.add_argument("--layout", type=Path, help="JSON canvas and composition settings")
+    args = parser.parse_args(argv)
+    if args.model_cache:
+        os.environ["HF_HUB_CACHE"] = str(args.model_cache.resolve())
+    os.environ.setdefault("HF_HUB_OFFLINE", "1")
+    return args
+
+
+def main(argv=None):
+    args = arguments(argv=argv)
+    if args.mode == "auto":
+        from .auto import prepare
+    else:
+        from .manual import prepare
+    try:
+        saved = prepare(args.input, args.output, encoder=args.encoder,
+                        encoder_path=args.encoder_path, layout=load_layout(args.layout), overwrite=args.overwrite)
+        print("已保存" if saved else "需手动处理或已取消")
+        return 0 if saved else 2
+    except Exception as exc:
+        print(f"失败：{exc}")
+        return 1

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/config.py

@@ -0,0 +1,34 @@
+"""Canvas and composition settings shared by automatic and manual processing."""
+from dataclasses import dataclass
+import json
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class Layout:
+    canvas: tuple = (1024, 1024)
+    anchor: tuple = (512, 175)
+    face_size: tuple = (95, 92)
+    anchor_x: tuple = (492, 546)
+    anchor_y: tuple = (125, 258)
+    margin: float = 2
+    alpha_core: int = 16
+    face_threshold: float = 0.55
+
+    def __post_init__(self):
+        for name in ("canvas","anchor","face_size","anchor_x","anchor_y"):
+            value = tuple(getattr(self,name))
+            if len(value) != 2:
+                raise ValueError(f"{name} must contain two values")
+            object.__setattr__(self,name,value)
+        if any(not isinstance(v, int) or v <= 2*self.margin for v in self.canvas) or self.margin < 0:
+            raise ValueError("画布宽高必须为正整数，且大于两侧边距")
+        if min(self.face_size) <= 0 or not 1 <= self.alpha_core <= 255 or not 0 <= self.face_threshold <= 1:
+            raise ValueError("脸部尺寸、Alpha 阈值或置信度无效")
+        for size, anchor, (lo, hi) in zip(self.canvas, self.anchor, (self.anchor_x, self.anchor_y)):
+            if not self.margin <= lo <= anchor <= hi <= size-self.margin or hi <= self.margin or lo >= size-self.margin:
+                raise ValueError("锚点和活动范围必须位于画布内，并为两侧留出空间")
+
+
+def load_layout(path=None):
+    return Layout(**json.loads(Path(path).read_text(encoding="utf-8-sig"))) if path else Layout()

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/dds.py

@@ -0,0 +1,26 @@
+"""Encode via an explicitly supplied executable, then replace the destination."""
+from pathlib import Path
+import tempfile
+from .encoders import ENCODERS
+
+
+def write_dds(path, image, *, encoder, encoder_path, overwrite=False):
+    path, executable = Path(path), Path(encoder_path).resolve()
+    if encoder not in ENCODERS:
+        raise ValueError("encoder 必须是 nvtt 或 texconv")
+    if not executable.is_file():
+        raise FileNotFoundError(executable)
+    if path.suffix.lower() != ".dds":
+        raise ValueError("输出必须是 .dds")
+    if path.exists() and not overwrite:
+        raise FileExistsError(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(dir=path.parent, prefix=".dds-") as folder:
+        folder = Path(folder)
+        source, output = folder / "image.png", folder / "image.dds"
+        image.save(source, format="PNG")
+        ENCODERS[encoder](source, output, executable=executable)
+        if not output.is_file():
+            raise RuntimeError("编码器没有生成 DDS")
+        # Commit only after encoding succeeds; failed encoding leaves the old DDS.
+        output.replace(path)

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/encoders/__init__.py

@@ -0,0 +1,6 @@
+"""Small adapters for external DDS encoders; no executable discovery."""
+
+from . import nvtt, texconv
+
+
+ENCODERS = {"nvtt": nvtt.encode, "texconv": texconv.encode}

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/encoders/nvtt.py

@@ -0,0 +1,14 @@
+"""NVIDIA Texture Tools adapter for straight-alpha, single-level BC3."""
+
+import os
+import subprocess
+
+
+def encode(source_png, output_dds, *, executable):
+    command = [str(executable), str(source_png), "--format", "bc3", "--quality", "production",
+               "--no-mips", "--max-mip-count", "1", "--output", str(output_dds)]
+    result = subprocess.run(command, capture_output=True, timeout=120,
+                            creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0)
+    if result.returncode:
+        message = (result.stdout + result.stderr).decode("utf-8", errors="replace")
+        raise OSError(f"nvtt 编码失败（退出码 {result.returncode}）：{message[-2000:]}")

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/encoders/texconv.py

@@ -0,0 +1,19 @@
+"""DirectXTex adapter for legacy-header, single-level BC3."""
+
+import os
+from pathlib import Path
+import subprocess
+
+
+def encode(source_png, output_dds, *, executable):
+    source_png, output_dds = Path(source_png), Path(output_dds)
+    command = [str(executable), "-nologo", "-f", "BC3_UNORM", "-m", "1", "-dx9", "-y",
+               "-o", str(output_dds.parent), str(source_png)]
+    result = subprocess.run(command, capture_output=True, timeout=120,
+                            creationflags=subprocess.CREATE_NO_WINDOW if os.name == "nt" else 0)
+    if result.returncode:
+        message = (result.stdout + result.stderr).decode("utf-8", errors="replace")
+        raise OSError(f"texconv 编码失败（退出码 {result.returncode}）：{message[-2000:]}")
+    generated = output_dds.parent / (source_png.stem + ".dds")
+    if generated != output_dds:
+        generated.replace(output_dds)

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/manual.py

@@ -0,0 +1,199 @@
+"""Manual composition with numeric placement, view navigation and guides."""
+from pathlib import Path
+from PIL.ImageQt import ImageQt
+from PySide6.QtCore import QRectF, Qt, Signal
+from PySide6.QtGui import QColor, QKeySequence, QPainter, QPen, QPixmap, QShortcut
+from PySide6.QtWidgets import (QApplication, QCheckBox, QDialog, QDoubleSpinBox,
+    QFormLayout, QGraphicsItem, QGraphicsPixmapItem, QGraphicsRectItem, QGraphicsScene,
+    QGraphicsView, QHBoxLayout, QLabel, QMessageBox, QPushButton, QVBoxLayout)
+from .config import Layout
+from .dds import write_dds
+from .transform import Placement, centered, read_image, render
+
+
+class PortraitView(QGraphicsView):
+    placement_changed = Signal(object)
+
+    def __init__(self, image, *, layout=Layout(), parent=None):
+        super().__init__(parent)
+        self.config = layout
+        self._pan, self._view_changed = None, False
+        self.setScene(QGraphicsScene(self))
+        extent = max(*image.size, *layout.canvas) * 4
+        self.setSceneRect(-extent, -extent, extent*3, extent*3)
+        self.setBackgroundBrush(QColor("#444444"))
+        self.setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff)
+        self.setVerticalScrollBarPolicy(Qt.ScrollBarPolicy.ScrollBarAlwaysOff)
+        self.setTransformationAnchor(QGraphicsView.ViewportAnchor.NoAnchor)
+        self.setRenderHint(QPainter.RenderHint.SmoothPixmapTransform)
+        self.item = QGraphicsPixmapItem(QPixmap.fromImage(ImageQt(image)))
+        self.item.setTransformationMode(Qt.TransformationMode.SmoothTransformation)
+        self.item.setFlag(QGraphicsItem.GraphicsItemFlag.ItemIsMovable)
+        self.scene().addItem(self.item)
+        self.outline(QRectF(0,0,*layout.canvas), "white")
+        ax, ay = layout.anchor
+        fw, fh = layout.face_size
+        left, top, right, bottom = image.getchannel("A").getbbox() or (0,0,*image.size)
+        self.guides = [
+            self.outline(QRectF(ax-fw/2,ay-fh/2,fw,fh), "#e89b16"),
+            self.outline(QRectF(0,0,*image.size), "#45c9ed", self.item),
+            self.outline(QRectF(left,top,right-left,bottom-top), "#b58aee", self.item),
+        ]
+        self.set_placement(centered(image, layout=layout))
+
+    def outline(self, rect, color, parent=None):
+        item = QGraphicsRectItem(rect, parent)
+        pen = QPen(QColor(color))
+        pen.setCosmetic(True)
+        item.setPen(pen)
+        item.setAcceptedMouseButtons(Qt.MouseButton.NoButton)
+        if parent is None:
+            self.scene().addItem(item)
+        item.setZValue(1)
+        return item
+
+    def fit_view(self):
+        self.fitInView(QRectF(0,0,*self.config.canvas).adjusted(-20,-20,20,20),
+                       Qt.AspectRatioMode.KeepAspectRatio)
+        self._view_changed = False
+
+    def resizeEvent(self, event):
+        super().resizeEvent(event)
+        if not self._view_changed:
+            self.fit_view()
+
+    def wheelEvent(self, event):
+        point = self.mapToScene(event.position().toPoint())
+        factor = 1.12 ** max(-5, min(5, event.angleDelta().y()/120))
+        if event.modifiers() & Qt.KeyboardModifier.ControlModifier:
+            old = self.transform().m11()
+            factor = max(0.02,min(32,old*factor))/old
+            self.scale(factor,factor)
+            moved = self.mapToScene(event.position().toPoint())
+            self.translate(moved.x()-point.x(),moved.y()-point.y())
+            self._view_changed = True
+        else:
+            p = self.placement()
+            scale = max(0.00001,min(10000,p.scale*factor))
+            self.set_placement(Placement(scale,point.x()+(p.x-point.x())*scale/p.scale,
+                                         point.y()+(p.y-point.y())*scale/p.scale))
+        event.accept()
+
+    def mousePressEvent(self, event):
+        if event.button() in (Qt.MouseButton.MiddleButton,Qt.MouseButton.RightButton):
+            self._pan = event.position().toPoint()
+            self.setCursor(Qt.CursorShape.ClosedHandCursor)
+            event.accept()
+        else:
+            super().mousePressEvent(event)
+
+    def mouseMoveEvent(self, event):
+        if self._pan is not None:
+            current = event.position().toPoint()
+            delta = current-self._pan
+            self.horizontalScrollBar().setValue(self.horizontalScrollBar().value()-delta.x())
+            self.verticalScrollBar().setValue(self.verticalScrollBar().value()-delta.y())
+            self._pan, self._view_changed = current, True
+            event.accept()
+        else:
+            super().mouseMoveEvent(event)
+            self.placement_changed.emit(self.placement())
+
+    def mouseReleaseEvent(self, event):
+        if self._pan is not None and event.button() in (Qt.MouseButton.MiddleButton,Qt.MouseButton.RightButton):
+            self._pan = None
+            self.unsetCursor()
+            event.accept()
+        else:
+            super().mouseReleaseEvent(event)
+
+    def set_placement(self, placement):
+        self.item.setScale(placement.scale)
+        self.item.setPos(placement.x,placement.y)
+        self.placement_changed.emit(placement)
+
+    def placement(self):
+        return Placement(self.item.scale(),self.item.x(),self.item.y())
+
+
+class PortraitEditor(QDialog):
+    def __init__(self, image, output, *, encoder, encoder_path, layout=Layout(), overwrite=False):
+        super().__init__()
+        self.image, self.output, self.config = image, output, layout
+        self.encoder, self.encoder_path, self.overwrite = encoder, encoder_path, overwrite
+        self.saved = False
+        self.setWindowTitle("立绘排版")
+        self.resize(1000,820)
+        window = QVBoxLayout(self)
+        body = QHBoxLayout()
+        window.addLayout(body)
+        self.view = PortraitView(image,layout=layout)
+        body.addWidget(self.view,1)
+        side = QVBoxLayout()
+        body.addLayout(side)
+        side.addWidget(QLabel(f"输出 {layout.canvas[0]} × {layout.canvas[1]}\n"
+                             "左键拖动／滚轮缩放图片\nCtrl+滚轮缩放查看\n中键／右键移动视图"))
+        form = QFormLayout()
+        side.addLayout(form)
+        self.scale_box, self.x_box, self.y_box = QDoubleSpinBox(),QDoubleSpinBox(),QDoubleSpinBox()
+        for title, field, limits, suffix in (
+            ("缩放",self.scale_box,(0.001,1000000)," %"),
+            ("左上角 X",self.x_box,(-10000000,10000000)," px"),
+            ("左上角 Y",self.y_box,(-10000000,10000000)," px")):
+            field.setRange(*limits)
+            field.setDecimals(3)
+            field.setSuffix(suffix)
+            field.setKeyboardTracking(False)
+            field.valueChanged.connect(self.edit_transform)
+            form.addRow(title,field)
+        self.view.placement_changed.connect(self.sync_controls)
+        self.sync_controls(self.view.placement())
+        guides = QCheckBox("显示辅助框")
+        guides.setChecked(True)
+        guides.toggled.connect(lambda visible: [item.setVisible(visible) for item in self.view.guides])
+        side.addWidget(guides)
+        side.addWidget(QLabel("白：输出画布\n橙：脸部参考\n青：原图边界\n紫：可见内容边界\n画布外内容会被裁切"))
+        for title, action in (
+            ("查看完整画布",self.view.fit_view),
+            ("立绘居中",lambda: self.view.set_placement(centered(image,layout=layout))),
+            ("保存 DDS",self.save),("取消",self.reject)):
+            button = QPushButton(title)
+            button.setAutoDefault(False)
+            button.clicked.connect(action)
+            side.addWidget(button)
+        side.addStretch()
+        shortcut = QShortcut(QKeySequence.StandardKey.Save,self)
+        shortcut.activated.connect(self.save)
+
+    def sync_controls(self, placement):
+        for field, value in ((self.scale_box,placement.scale*100),
+                             (self.x_box,placement.x),(self.y_box,placement.y)):
+            field.blockSignals(True)
+            field.setValue(value)
+            field.blockSignals(False)
+
+    def edit_transform(self):
+        self.view.set_placement(Placement(self.scale_box.value()/100,self.x_box.value(),self.y_box.value()))
+
+    def save(self):
+        try:
+            write_dds(self.output,render(self.image,self.view.placement(),layout=self.config),
+                      encoder=self.encoder,encoder_path=self.encoder_path,overwrite=self.overwrite)
+        except Exception as exc:
+            QMessageBox.warning(self,"保存失败",str(exc))
+            return
+        self.saved = True
+        self.accept()
+
+
+def prepare(input_path, output_path, *, encoder, encoder_path, layout=Layout(), overwrite=False):
+    if Path(input_path).resolve() == Path(output_path).resolve():
+        raise ValueError("输入和输出不能相同")
+    if Path(output_path).exists() and not overwrite:
+        raise FileExistsError(output_path)
+    image = read_image(input_path)
+    app = QApplication.instance() or QApplication([])
+    editor = PortraitEditor(image,output_path,encoder=encoder,encoder_path=encoder_path,
+                            layout=layout,overwrite=overwrite)
+    editor.exec()
+    return editor.saved

anime_core_lib_portrait_tool-0.1.0/anime_core_lib_portrait_tool/transform.py

@@ -0,0 +1,77 @@
+"""Read, compose and render a portrait on a configured canvas."""
+from dataclasses import dataclass
+import math
+from PIL import Image, ImageOps
+
+from .config import Layout
+
+
+@dataclass(frozen=True)
+class Placement:
+    scale: float
+    x: float
+    y: float
+
+
+def read_image(path):
+    with Image.open(path) as image:
+        return ImageOps.exif_transpose(image).convert("RGBA")
+
+
+def centered(image, *, layout=Layout()):
+    width, height = layout.canvas
+    margin = layout.margin
+    left, top, right, bottom = image.getchannel("A").getbbox() or (0, 0, *image.size)
+    scale = min((width-2*margin)/(right-left),(height-2*margin)/(bottom-top))
+    return Placement(scale,width/2-(left+right)*scale/2,height/2-(top+bottom)*scale/2)
+
+
+def render(image, placement, *, layout=Layout()):
+    s, x, y = placement.scale, placement.x, placement.y
+    if s <= 0 or not all(map(math.isfinite, (s, x, y))):
+        raise ValueError("缩放必须为正数，位置必须为有限数值")
+    return image.convert("RGBa").transform(
+        layout.canvas, Image.Transform.AFFINE, (1/s, 0, -x/s, 0, 1/s, -y/s),
+        resample=Image.Resampling.BICUBIC, fillcolor=(0, 0, 0, 0)).convert("RGBA")
+
+
+def detect_faces(image):
+    # Import the runtime first so imgutils cannot silently install it.
+    import onnxruntime as ort
+    if "CUDAExecutionProvider" in ort.get_available_providers() and hasattr(ort, "preload_dlls"):
+        ort.preload_dlls()
+    from imgutils.detect import detect_faces as detect
+    return detect(image, model_name="face_detect_v1.4_s", conf_threshold=0.25, iou_threshold=0.7)
+
+
+def estimate_transform(image, *, layout=Layout()):
+    """Return a placement, or None when the image needs manual composition."""
+    bounds = image.getchannel("A").point(lambda a: 255 if a >= layout.alpha_core else 0).getbbox()
+    if bounds is None:
+        return None
+    rgb = Image.alpha_composite(Image.new("RGBA", image.size, "white"), image).convert("RGB")
+    faces = detect_faces(rgb)
+    if not faces:
+        return None
+    def area(face):
+        x0, y0, x1, y1 = face[0]
+        return (x1 - x0) * (y1 - y0)
+    candidates = [f for f in faces if f[2] >= 0.5] or faces
+    face = max(candidates, key=lambda f: f[2] * math.sqrt(area(f)))
+    if face[2] < layout.face_threshold or any(f is not face and f[2] >= 0.6 and area(f) >= area(face)*0.5 for f in faces):
+        return None
+    x0, y0, x1, y1 = face[0]
+    cx, cy = (x0+x1)/2, (y0+y1)/2
+    left, top, right, bottom = bounds
+    xr, yr = layout.anchor_x, layout.anchor_y
+    width, height = layout.canvas
+    margin = layout.margin
+    limits = [math.sqrt(math.prod(layout.face_size)/area(face)), (width-2*margin)/(right-left), (height-2*margin)/(bottom-top)]
+    for distance, room in ((cx-left, xr[1]-margin), (right-cx, width-margin-xr[0]),
+                           (cy-top, yr[1]-margin), (bottom-cy, height-margin-yr[0])):
+        if distance > 0:
+            limits.append(room/distance)
+    scale = min(limits)
+    ax = min(max(layout.anchor[0], xr[0], margin+(cx-left)*scale), xr[1], width-margin-(right-cx)*scale)
+    ay = min(max(layout.anchor[1], yr[0], margin+(cy-top)*scale), yr[1], height-margin-(bottom-cy)*scale)
+    return Placement(scale, ax-cx*scale, ay-cy*scale)

anime_core_lib_portrait_tool-0.1.0/examples/batch.py

@@ -0,0 +1,60 @@
+import csv
+import os
+from pathlib import Path
+import sys
+
+# 直接从源码运行时使用本机项目路径，按需修改。
+sys.path.insert(0, r"E:\Modding\anime_core_lib_portrait_tool")
+from anime_core_lib_portrait_tool.auto import prepare as automatic
+from anime_core_lib_portrait_tool import load_layout
+
+CSV = Path(r"E:\Modding\anime_core_lib_portrait_tool\examples\jobs.csv")
+# 两种处理方式共用布局；布局文件在上述 CSV 旁，编码器路径按本机安装位置修改。
+OPTIONS = dict(layout=load_layout(CSV.with_name("layout.json")), encoder="nvtt",
+               encoder_path=r"C:\Program Files\NVIDIA Corporation\NVIDIA Texture Tools\nvtt_export.exe")
+
+
+def run_batch(csv_path=CSV):
+    csv_path = Path(csv_path)
+    # CSV 可带 UTF-8 BOM，列名为 input、output；路径相对 CSV 所在目录。
+    # 例如：images/source.png,output/result.dds
+    with csv_path.open(encoding="utf-8-sig", newline="") as stream:
+        jobs = [(csv_path.parent / row["input"], csv_path.parent / row["output"])
+                for row in csv.DictReader(stream)]
+    pending, complete = [], True
+    for source, output in jobs:
+        # 重跑时只处理尚未生成输出的任务。
+        if output.exists():
+            print(f"跳过：{output}")
+            continue
+        try:
+            # 无可靠主脸时加入人工队列，等全部自动任务结束后再处理。
+            if not automatic(source, output, **OPTIONS):
+                pending.append((source, output))
+            else:
+                print(f"完成：{output}")
+        except Exception as exc:
+            # 读取、模型或编码异常只记录失败，不转入人工队列。
+            print(f"失败：{source}：{exc}")
+            complete = False
+    for source, output in pending:
+        # 只有需要人工处理时才加载 GUI 依赖。
+        from anime_core_lib_portrait_tool.manual import prepare as manual
+        try:
+            if not manual(source, output, **OPTIONS):
+                # 用户取消时停止后续人工任务。
+                return False
+            print(f"完成：{output}")
+        except Exception as exc:
+            print(f"失败：{source}：{exc}")
+            complete = False
+    return complete
+
+
+if __name__ == "__main__":
+    # 在项目目录执行 python -X utf8 examples/batch.py。
+    # 使用本机模型缓存；需要下载模型时将 HF_HUB_OFFLINE 改为 "0"。
+    os.environ["HF_HUB_CACHE"] = r"E:\Modding\portraits\models"
+    os.environ["HF_HUB_OFFLINE"] = "1"
+    # 退出码：0 全部完成，1 有错误或取消。
+    raise SystemExit(0 if run_batch() else 1)

anime_core_lib_portrait_tool-0.1.0/examples/jobs.csv

@@ -0,0 +1,2 @@
+input,output
+images/source.png,output/result.dds

anime_core_lib_portrait_tool-0.1.0/examples/layout.json

@@ -0,0 +1,23 @@
+{
+  "canvas": [
+    1024,
+    1024
+  ],
+  "anchor": [
+    512,
+    175
+  ],
+  "face_size": [
+    95,
+    92
+  ],
+  "anchor_x": [
+    492,
+    546
+  ],
+  "anchor_y": [
+    125,
+    258
+  ],
+  "margin": 2
+}

anime_core_lib_portrait_tool-0.1.0/portrait.py

@@ -0,0 +1,6 @@
+"""Single-image script: python portrait.py auto|manual --help."""
+
+from anime_core_lib_portrait_tool.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

anime_core_lib_portrait_tool-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling>=1.33.0"]
+build-backend = "hatchling.build"
+
+[project]
+name = "anime-core-lib-portrait-tool"
+version = "0.1.0"
+description = "Automatic and manual portrait composition and DDS export for Anime Core Lib"
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "cwlm"}]
+dependencies = ["Pillow>=13.0.0"]
+
+[project.optional-dependencies]
+auto = ["dghs-imgutils>=0.19.0", "onnxruntime>=1.31.1"]
+gpu = ["dghs-imgutils>=0.19.0", "onnxruntime-gpu>=1.31.1"]
+gui = ["PySide6-Essentials>=6.12.0"]
+
+[project.scripts]
+portrait = "anime_core_lib_portrait_tool.cli:main"
+
+[project.urls]
+Repository = "https://github.com/cwlm/anime_core_lib_portrait_tool"
+
+[tool.hatch.build.targets.wheel]
+packages = ["anime_core_lib_portrait_tool"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/anime_core_lib_portrait_tool", "/examples", "/portrait.py", "/pyproject.toml", "/README.md", "/LICENSE"]