psdparse 0.7.0__tar.gz → 0.8.1__tar.gz

{psdparse-0.7.0 → psdparse-0.8.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: psdparse
-Version: 0.7.0
+Version: 0.8.1
 Summary: Fast PSD (Photoshop) reader/writer — C++17 core with pybind11 bindings
 Keywords: psd,photoshop,parser,image,graphics
 Author-Email: wamsoft <wtnbgo@gmail.com>
@@ -166,6 +166,24 @@ Tests live under `tests/` and use [pytest](https://docs.pytest.org/). They need
 python -m pytest -v
 ```
 
+## Examples (composite / variations / sprite extraction)
+
+psdparse gives you the pieces (per-layer pixels, position, opacity, masks) but
+does **not** composite or re-render — the Python imaging ecosystem does that
+better. [`examples/`](examples/) shows the recipes:
+
+- **`composite.py`** — composite layers with Pillow (position + opacity + mask,
+  normal blend), and optionally write the result back as the PSD's stored
+  preview via `set_merged_image`.
+- **`variations.py`** — enumerate tachie/expression combinations by treating
+  layer folders as mutually-exclusive option slots.
+- **`extract_layers.py`** — export per-layer PNGs + a manifest, with alpha edge
+  extension (bleed) so sprites stay clean under rotation/scaling.
+
+See [examples/README.md](examples/README.md). On the sample tachie PSDs
+(all normal blend) `composite.py` matches Photoshop's stored composite to ~0.1
+mean level difference.
+
 ## tools/psd_export.py
 
 ```

{psdparse-0.7.0 → psdparse-0.8.1}/README.md

@@ -125,6 +125,24 @@ Tests live under `tests/` and use [pytest](https://docs.pytest.org/). They need
 python -m pytest -v
 ```
 
+## Examples (composite / variations / sprite extraction)
+
+psdparse gives you the pieces (per-layer pixels, position, opacity, masks) but
+does **not** composite or re-render — the Python imaging ecosystem does that
+better. [`examples/`](examples/) shows the recipes:
+
+- **`composite.py`** — composite layers with Pillow (position + opacity + mask,
+  normal blend), and optionally write the result back as the PSD's stored
+  preview via `set_merged_image`.
+- **`variations.py`** — enumerate tachie/expression combinations by treating
+  layer folders as mutually-exclusive option slots.
+- **`extract_layers.py`** — export per-layer PNGs + a manifest, with alpha edge
+  extension (bleed) so sprites stay clean under rotation/scaling.
+
+See [examples/README.md](examples/README.md). On the sample tachie PSDs
+(all normal blend) `composite.py` matches Photoshop's stored composite to ~0.1
+mean level difference.
+
 ## tools/psd_export.py
 
 ```

{psdparse-0.7.0 → psdparse-0.8.1}/docs/PYTHON_API.md

@@ -112,6 +112,7 @@ Read-only view of one layer.
 | `effects` | `dict` \| `None` | layer effects (`lfx2`) as a descriptor dict — see [Descriptor blocks](#descriptor-blocks) |
 | `fill` | `dict` \| `None` | fill-layer content (solid/gradient/pattern) — see [Descriptor blocks](#descriptor-blocks) |
 | `sheet_color` | `dict` \| `None` | layer-panel color label (`lclr`): `{"index", "name"}` — `None` when no `lclr` block |
+| `comp_states` | `dict` | per layer-comp state `{comp_id: {"enabled", "offset_x", "offset_y"}}` (empty if the layer is in no comps). `enabled` says if the layer shows in that comp — see [Layer comps](#layer-comps) |
 | `info_keys` | `list[str]` | 4cc keys of every additional-layer-info block on this layer |
 | `visible` | `bool` | flag bit 1 inverted |
 | `transparency_protected` | `bool` | flag bit 0 |
@@ -258,6 +259,7 @@ Quick map of the API (details in the subsections below):
 | edit text content | `p.set_text(i, str)` |
 | edit a text run's style | `p.set_run_style(i, run, size_px=…, color=…, …)` |
 | build a new PSD | `p.create_blank(w, h)` then `add_layer(...)` |
+| write a composited preview back | `p.set_merged_image(bgra)` |
 
 **8-bit RGB only** for the pixel/mask/new-document operations. The stored
 composite image is **not** re-rendered after edits (see [Saving](#saving)).
@@ -329,6 +331,9 @@ new_i = p.copy_layer_from(src, j, dest_index=-1)  # copy layer j from another PS
 ```
 
 Notes:
+- `duplicate_layer` / `copy_layer_from` assign the copy a **fresh `layer_id`**
+  (max existing lyid + 1, like Photoshop) so layer IDs stay unique within the
+  document; the `lyid` additional-info block is rewritten on save.
 - `delete_layer` / `duplicate_layer` on a single layer are exact. Deleting **one
   half of a group's FOLDER/HIDDEN divider pair unbalances the group** — delete
   whole groups (both dividers + contents) for clean nesting. (Unbalanced results
@@ -433,6 +438,14 @@ p.save("new.psd")
 
 ### Saving
 
+The stored **composite (merged) image** is not re-rendered after edits. If you
+composite the layers yourself (e.g. with Pillow — see [`examples/`](../examples/)),
+write the result back as the PSD's preview with:
+
+```python
+p.set_merged_image(bgra_bytes)   # canvas-sized BGRA (header.width*header.height*4)
+```
+
 `save(path)` returns `True`/`False`. **Do not save over a file that is currently
 loaded** (by this or any live `PSDFile`): `load()` memory-maps the file
 read-only, so the write is refused and `save()` returns `False` (the original is
@@ -460,6 +473,30 @@ p.color_table   # dict|None : {"colors":[(r,g,b,a)], "valid_count", "transparenc
 p.global_layer_mask  # dict|None : {"overlay_color_space", "color":(c1,c2,c3,c4), "opacity", "kind"}
 ```
 
+### Layer comps
+
+`p.layer_comps` lists the document's layer comps (saved layer-state snapshots).
+Which layers each comp shows is on the **layers**: `layer.comp_states` maps a
+comp id to that layer's state in the comp:
+
+```python
+{ comp_id: {"enabled": True, "offset_x": 0, "offset_y": 0}, ... }
+```
+
+`enabled` is whether the layer is visible in that comp; a layer the comp doesn't
+mention isn't in the dict (fall back to its current visibility). To render a comp
+(visibility only — position/appearance overrides aren't applied):
+
+```python
+for comp in p.layer_comps:
+    show = {i for i, l in enumerate(p.layers)
+            if (l.comp_states[comp["id"]]["enabled"]
+                if comp["id"] in l.comp_states else l.visible)}
+    # composite `show` with Pillow — see examples/variations.py (composite_comp)
+```
+
+`examples/variations.py --comps` renders every comp this way.
+
 ### Image resources (raw)
 
 Most image resources are exposed as their raw on-disk bytes; decoding (EXIF

{psdparse-0.7.0 → psdparse-0.8.1}/docs/ROADMAP.md

@@ -3,12 +3,13 @@
 For a feature-by-feature account of what is and isn't supported today, see
 [SUPPORT.md](SUPPORT.md). This file tracks planned work.
 
-## Current state (2026-08-02, v0.7.0)
+## Current state (2026-08-12, v0.8.1)
 
 - ✅ Pure C++17 parser (no Boost)
 - ✅ mmap + StreamReader / Source abstraction
 - ✅ Python bindings (pybind11)
-- ✅ pytest regression suite (121 tests)
+- ✅ pytest regression suite (140 tests)
+- ✅ Python composite recipes (`examples/`) + `set_merged_image`; layer comps exposed (`layer.comp_states`)
 - ✅ Round-trip PSD save (byte-identical)
 - ✅ Edit & save: structure / pixels / mask / parameters / effects / text / new-from-scratch (E1–E6, byte-exact re-serialization)
 - ✅ UTF-8 path I/F (Win32 conversion internal only)
@@ -90,6 +91,20 @@ Editing text content/style means writing the `TySh` block back: re-serializing t
 
 ## Other future work
 
+- ✅ **`duplicate_layer` assigns a fresh `lyid`.** *Done 2026-08-12.* The
+  duplicated layer used to copy the source's `lyid` (layer ID) verbatim, so the
+  output PSD contained duplicate layer IDs — Photoshop itself assigns a *new*
+  ID when duplicating. Downstream tools that use `lyid` as a persistent layer
+  identity (e.g. elements_console's uitool reference resolution) then saw
+  ambiguous matches. Fix (`psdfile.cpp`): `assignFreshLayerId` sets
+  `layerId = max existing lyid + 1` and replaces (or appends) the `lyid`
+  additional-info entry on the copy, flipping `useRawBytes=false` so save
+  re-serializes it; applied in both `duplicateLayer` and `copyLayerFrom` (the
+  latter picks an ID unique within the *destination* document). `add_layer`
+  already picked max+1 — verified. Tests (`tests/test_edit.py`): duplicate →
+  all `layer.layer_id` distinct → save → reload → still distinct; double
+  duplicate cross-checked via psd-tools tagged blocks; `copy_layer_from`
+  uniqueness in the destination.
 - ✅ **Text layer content extraction (`TySh` type-tool additional info).** *Done 2026-07-27.* `lay.text` returns `{"text", "orientation", "justification", "transform", "runs":[{"length","font","size_px","color","tracking","kerning","auto_kerning"}]}` (or `None` for non-text layers). Implementation: `psddesc` now reads `tdta` raw data (length-prefixed), `loadLayerTypeTool` (`psdlayer.cpp`) parses the `TySh` header + text descriptor, and `psdengine.cpp` parses the embedded Adobe *EngineData* mini-language (FontSet / StyleRun / ParagraphRun) into per-run styling. Validated against `tests/data/fontsample.psd` (multi-font/size/color, **vertical**, emoji, tracking) — see `tests/test_text.py`.
 
   **Deferred (need targeted sample PSDs, next turn):**

{psdparse-0.7.0 → psdparse-0.8.1}/docs/SUPPORT.md

@@ -54,7 +54,8 @@ Python API の使い方は [PYTHON_API.md](PYTHON_API.md) を参照。
 | テキストのラン単位スタイル編集 | ✅ | `set_run_style(i, run, size_px=/color=/tracking=/bold=…)` (v0.7.0) |
 | テキストのフォント変更 (FontSet 追加) / ラン再構成 | ❌ | 既存ランの値上書きのみ |
 | マスク幾何の単独編集 (画素なし) | 🟡 | `set_layer_mask_pixels` で画素とセットのみ |
-| 効果込みの合成画像 (composite) 再生成 | ❌ | 編集後は旧合成のまま (開いた Photoshop が再合成) |
+| 合成済み画像 (composite) の入れ替え | ✅ | `set_merged_image(bgra)` — Python で合成した結果を書き戻せる (v0.7.x) |
+| 効果込みの合成 (composite) の自動再生成 | ❌ | psdparse 自身は再描画しない。合成は Python (Pillow 等, `examples/`) で |
 
 ## 圧縮 / ビット深度
 
@@ -163,7 +164,8 @@ Photoshop の汎用ディスクリプタで格納されるブロックを dict
 | グリッド & ガイド (1032) | ✅ | `PSDFile.guides` (v0.3.0) |
 | スライス (1050 v6) | ✅ | `PSDFile.slices` (v0.3.0) |
 | スライス (1050 v7/v8, descriptor) | ❌ | 未格納 |
-| レイヤーカンプ (1065) | ✅ | `PSDFile.layer_comps` (v0.3.0) |
+| レイヤーカンプ (1065, 文書レベル) | ✅ | `PSDFile.layer_comps` (id/name/comment/record_*, v0.3.0) |
+| レイヤーカンプの各レイヤ状態 (可視) | ✅ | `layer.comp_states` = `{comp_id: {enabled, offset_x, offset_y}}` (v0.7.x)。位置/効果の上書きは未適用 |
 | インデックスカラーパレット (色/count/透明index) | ✅ | `PSDFile.color_table` (v0.3.0) |
 | ICC プロファイル (1039) | ✅ | `PSDFile.icc_profile` (生バイト, v0.5.0) |
 | EXIF (1058) | ✅ | `PSDFile.exif` (生バイト, v0.5.0) |

psdparse-0.8.1/examples/README.md

@@ -0,0 +1,84 @@
+# psdparse examples
+
+Recipes that combine **psdparse** (structure + pixel extraction + editing) with
+the Python imaging ecosystem (Pillow / numpy). psdparse deliberately does *not*
+composite or re-render — it hands you the pieces, and these scripts show how to
+put them together.
+
+Install the deps: `pip install psdparse pillow numpy`.
+
+## composite.py — composite layers with Pillow
+
+Composites layers bottom-to-top (position + per-layer opacity + mask), **normal
+blend only**. Layer effects and non-normal blend modes are not re-rendered
+(read `layer.effects` / `layer.blend_mode` and implement them here if needed).
+
+```bash
+python composite.py character.psd out.png
+python composite.py character.psd out.png --write-back preview.psd
+```
+
+`--write-back` writes the composite into a copy of the PSD as its stored preview
+via `PSDFile.set_merged_image(...)` — useful after editing layers, since psdparse
+does not regenerate the composite itself.
+
+```python
+from composite import composite
+img = composite(psd)               # PIL.Image of the visible layers
+img = composite(psd, show={0, 3})  # only these layer indices
+```
+
+On the sample tachie PSDs (all normal blend) this matches Photoshop's stored
+composite to ~0.1 mean level difference.
+
+## variations.py — tachie / expression combinations
+
+Game and VTuber character PSDs group mutually-exclusive parts (eyes, mouth,
+expression, outfit) into **folders**; each folder is a slot where one option
+shows at a time. This enumerates option combinations and composites each.
+
+```bash
+python variations.py character.psd out_dir/               # sweep the first group
+python variations.py character.psd out_dir/ --group 表情   # sweep a named group
+python variations.py doc.psd out_dir/ --comps              # render each Photoshop layer comp
+```
+
+`--comps` renders each of the document's Photoshop **layer comps** using
+`layer.comp_states` (visibility only; position/appearance overrides aren't
+applied). Otherwise it sweeps folder-based option slots.
+
+```python
+from variations import option_groups, composite_choices
+groups = option_groups(psd)                       # {folder_index: [option_index, ...]}
+img = composite_choices(psd, {folder_i: option_i})
+```
+
+It treats each top-level folder as a simple "pick one direct child" slot. Real
+data sometimes nests (a body folder with an always-on base plus arm options) —
+adapt `option_groups` for that.
+
+## extract_layers.py — sprite extraction with alpha bleed
+
+Turns a PSD into per-layer PNGs plus a `manifest.json`, and **extends each
+layer's base colour into its transparent area** (alpha bleed / edge dilation) so
+the alpha edge doesn't leak a halo when the sprite is rotated or scaled with
+bilinear filtering — a standard step when prepping tachie sprites for a game
+engine.
+
+```bash
+python extract_layers.py character.psd out_dir/ --bleed 8
+python extract_layers.py character.psd out_dir/ --no-bleed
+```
+
+The bleed only fills RGB under `alpha == 0`; the alpha channel is left untouched.
+
+```python
+from extract_layers import alpha_bleed
+safe = alpha_bleed(layer_rgba_image, passes=8)
+```
+
+## See also
+
+`tools/psd_export.py` (repo root) dumps `layers.json` + `merged.png` + per-layer
+PNGs in one shot. The examples here are smaller, focused building blocks you can
+copy into your own pipeline.

psdparse-0.8.1/examples/composite.py

@@ -0,0 +1,111 @@
+"""Composite psdparse layers with Pillow.
+
+psdparse gives you each layer's pixels (`layer_image`), position, opacity and
+visibility; the actual compositing is done here in Python with Pillow. This keeps
+the C++ core lean and lets you use the mature imaging ecosystem.
+
+Scope: **normal blend** + per-layer opacity + mask (via ``layer_image(i,
+"masked")``) + position, composited bottom-to-top. Non-normal blend modes and
+layer effects are *not* applied (psdparse does not re-render effects); if you
+need those, read `layer.blend_mode` / `layer.effects` and implement them here.
+
+    python composite.py input.psd output.png [--write-back edited.psd]
+
+As a library:
+
+    from composite import composite
+    img = composite(psd)            # PIL.Image, currently-visible layers
+    img = composite(psd, show={0, 3, 7})   # only these layer indices
+"""
+from __future__ import annotations
+
+import argparse
+
+import psdparse
+from PIL import Image
+
+# Layer types that carry pixels (skip folder/divider markers).
+_PIXEL_TYPES = (
+    psdparse.LayerType.NORMAL,
+    psdparse.LayerType.TEXT,
+    psdparse.LayerType.ADJUST,
+    psdparse.LayerType.FILL,
+)
+
+
+def layer_rgba(psd: psdparse.PSDFile, index: int) -> Image.Image | None:
+    """A layer's masked pixels as an RGBA PIL image (opacity folded into alpha),
+    or None for empty layers."""
+    layer = psd.layers[index]
+    if layer.width <= 0 or layer.height <= 0:
+        return None
+    bgra = psd.layer_image(index, "masked")            # mask applied to alpha
+    img = Image.frombytes("RGBA", (layer.width, layer.height), bgra, "raw", "BGRA")
+    if layer.opacity < 255:
+        alpha = img.getchannel("A").point(lambda v: v * layer.opacity // 255)
+        img.putalpha(alpha)
+    return img
+
+
+def _paste_clipped(canvas: Image.Image, img: Image.Image, x: int, y: int) -> None:
+    """alpha-composite `img` onto `canvas` at (x, y), clipping to the canvas
+    (handles layers that extend past the edges / negative offsets)."""
+    cw, ch = canvas.size
+    w, h = img.size
+    sx0, sy0 = max(0, -x), max(0, -y)
+    sx1, sy1 = min(w, cw - x), min(h, ch - y)
+    if sx1 <= sx0 or sy1 <= sy0:
+        return
+    crop = img.crop((sx0, sy0, sx1, sy1))
+    tmp = Image.new("RGBA", (cw, ch), (0, 0, 0, 0))
+    tmp.paste(crop, (max(0, x), max(0, y)))
+    canvas.alpha_composite(tmp)
+
+
+def composite(psd: psdparse.PSDFile, show: set[int] | None = None) -> Image.Image:
+    """Composite layers bottom-to-top into a canvas-sized RGBA image.
+
+    `show`: set of layer indices to include. Default (None) = every currently
+    **visible** pixel layer. Folder/divider markers are always skipped.
+    """
+    canvas = Image.new("RGBA", (psd.header.width, psd.header.height), (0, 0, 0, 0))
+    for i, layer in enumerate(psd.layers):          # index 0 = bottom-most
+        if layer.layer_type not in _PIXEL_TYPES:
+            continue
+        if show is None:
+            if not layer.visible:
+                continue
+        elif i not in show:
+            continue
+        img = layer_rgba(psd, i)
+        if img is not None:
+            _paste_clipped(canvas, img, layer.left, layer.top)
+    return canvas
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Composite visible layers with Pillow.")
+    ap.add_argument("input")
+    ap.add_argument("output", help="output PNG")
+    ap.add_argument("--write-back", metavar="PSD",
+                    help="also write the composite into a copy of the PSD "
+                         "(as the stored preview) via set_merged_image")
+    args = ap.parse_args()
+
+    psd = psdparse.PSDFile()
+    if not psd.load(args.input):
+        raise SystemExit(f"failed to load {args.input}")
+    img = composite(psd)
+    img.save(args.output)
+    print(f"wrote {args.output} ({img.width}x{img.height})")
+
+    if args.write_back:
+        # set_merged_image wants canvas-sized BGRA
+        bgra = img.convert("RGBA").tobytes("raw", "BGRA")
+        psd.set_merged_image(bgra)
+        psd.save(args.write_back)
+        print(f"wrote {args.write_back} with the composite as its stored preview")
+
+
+if __name__ == "__main__":
+    main()

psdparse-0.8.1/examples/extract_layers.py

@@ -0,0 +1,105 @@
+"""Extract each layer to a PNG, with alpha edge-extension (bleed), + a manifest.
+
+A common step when turning a tachie PSD into game-ready sprites: pull each part
+out as its own image, and **extend the base colour into the transparent area** so
+the alpha edge doesn't leak a dark/transparent halo when the sprite is rotated or
+scaled with bilinear filtering. This writes:
+
+    out_dir/000_<name>.png    ... each pixel layer (RGB bled under the alpha)
+    out_dir/manifest.json     ... index/name/position/size/opacity/blend/parent
+
+    python extract_layers.py character.psd out_dir/ [--bleed 8] [--no-bleed]
+
+Needs numpy (for the bleed). The bleed leaves the alpha channel untouched — it
+only fills RGB in transparent pixels, which is exactly what edge-safe scaling
+wants.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+
+import numpy as np
+import psdparse
+from PIL import Image
+
+from composite import _PIXEL_TYPES, layer_rgba
+
+
+def alpha_bleed(img: Image.Image, passes: int = 8) -> Image.Image:
+    """Extend RGB into transparent pixels by iterative dilation (`passes` px).
+    Alpha is preserved; only the colour under alpha==0 is filled from neighbours."""
+    arr = np.array(img.convert("RGBA"))
+    rgb = arr[..., :3].astype(np.float32)
+    filled = arr[..., 3] > 0
+    for _ in range(passes):
+        if filled.all():
+            break
+        color_sum = np.zeros_like(rgb)
+        count = np.zeros(filled.shape, np.float32)
+        for dy, dx in ((-1, 0), (1, 0), (0, -1), (0, 1)):
+            m = np.roll(filled, (dy, dx), (0, 1))
+            shifted = np.roll(rgb, (dy, dx), (0, 1))
+            if dy == 1:    m[0, :] = False       # kill np.roll wrap-around
+            elif dy == -1: m[-1, :] = False
+            if dx == 1:    m[:, 0] = False
+            elif dx == -1: m[:, -1] = False
+            color_sum += shifted * m[..., None]
+            count += m
+        newly = (~filled) & (count > 0)
+        rgb[newly] = color_sum[newly] / count[newly][..., None]
+        filled |= newly
+    arr[..., :3] = np.clip(rgb, 0, 255).astype(np.uint8)
+    return Image.fromarray(arr, "RGBA")
+
+
+def _blend_key(layer: psdparse.LayerInfo) -> str:
+    k = layer.blend_mode_key
+    return "".join(chr((k >> s) & 0xFF) for s in (24, 16, 8, 0))
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Extract layers to PNGs with alpha bleed.")
+    ap.add_argument("input")
+    ap.add_argument("out_dir")
+    ap.add_argument("--bleed", type=int, default=8, help="edge-extension passes (px)")
+    ap.add_argument("--no-bleed", action="store_true")
+    args = ap.parse_args()
+
+    psd = psdparse.PSDFile()
+    if not psd.load(args.input):
+        raise SystemExit(f"failed to load {args.input}")
+    os.makedirs(args.out_dir, exist_ok=True)
+
+    manifest = {"width": psd.header.width, "height": psd.header.height, "layers": []}
+    for i, layer in enumerate(psd.layers):
+        if layer.layer_type not in _PIXEL_TYPES:
+            continue
+        img = layer_rgba(psd, i)
+        if img is None:
+            continue
+        if not args.no_bleed and args.bleed > 0:
+            img = alpha_bleed(img, args.bleed)
+        try:
+            name = layer.name_unicode
+        except UnicodeDecodeError:
+            name = f"layer{i}"
+        safe = "".join(c if c.isalnum() or c in "._-()（）　 " else "_" for c in name).strip()
+        fname = f"{i:03d}_{safe or 'layer'}.png"
+        img.save(os.path.join(args.out_dir, fname))
+        manifest["layers"].append({
+            "index": i, "name": name, "file": fname,
+            "left": layer.left, "top": layer.top,
+            "width": layer.width, "height": layer.height,
+            "opacity": layer.opacity, "blend": _blend_key(layer),
+            "visible": layer.visible, "parent_index": layer.parent_index,
+        })
+
+    with open(os.path.join(args.out_dir, "manifest.json"), "w", encoding="utf-8") as f:
+        json.dump(manifest, f, ensure_ascii=False, indent=2)
+    print(f"extracted {len(manifest['layers'])} layers to {args.out_dir}")
+
+
+if __name__ == "__main__":
+    main()

psdparse-0.8.1/examples/variations.py

@@ -0,0 +1,153 @@
+"""Generate character (tachie) variations from grouped layers.
+
+Game/VTuber character PSDs put mutually-exclusive parts (eyes, mouth, outfit,
+expression) into layer **folders** — each folder is a "slot" where one option is
+shown at a time. This example enumerates option combinations and composites each
+with Pillow (see composite.py).
+
+    python variations.py character.psd out_dir/            # sweep the first slot
+    python variations.py character.psd out_dir/ --group 表情 --group 目
+
+As a library:
+
+    from variations import option_groups, composite_choices
+    groups = option_groups(psd)                 # {folder_index: [option_index, ...]}
+    img = composite_choices(psd, {folder_i: option_i})   # PIL.Image
+
+Note: this treats each top-level folder as a simple "pick one of its direct
+pixel-layer children" slot. Real PSDs sometimes nest (a body folder with an
+always-on base plus arm options); adapt `option_groups` for those.
+"""
+from __future__ import annotations
+
+import argparse
+import itertools
+import os
+
+import psdparse
+
+from composite import composite, _PIXEL_TYPES
+
+
+def _label(psd: psdparse.PSDFile, index: int) -> str:
+    try:
+        return psd.layers[index].name_unicode
+    except UnicodeDecodeError:
+        return f"layer{index}"
+
+
+def option_groups(psd: psdparse.PSDFile) -> dict[int, list[int]]:
+    """Top-level folders → their direct pixel-layer children (the options)."""
+    groups: dict[int, list[int]] = {}
+    for i, layer in enumerate(psd.layers):
+        if layer.layer_type == psdparse.LayerType.FOLDER and layer.parent_index == -1:
+            options = [j for j, c in enumerate(psd.layers)
+                       if c.parent_index == i and c.layer_type in _PIXEL_TYPES]
+            if options:
+                groups[i] = options
+    return groups
+
+
+def composite_choices(psd: psdparse.PSDFile, choices: dict[int, int]):
+    """Composite with one option chosen per group.
+
+    `choices`: {folder_index: option_index}. For each chosen group the picked
+    option is shown and its siblings hidden; groups not listed keep their
+    currently-visible option; layers outside any group follow their visibility.
+    """
+    show = {i for i, l in enumerate(psd.layers)
+            if l.visible and l.layer_type in _PIXEL_TYPES}
+    groups = option_groups(psd)
+    for folder_index, chosen in choices.items():
+        for opt in groups.get(folder_index, []):
+            show.discard(opt)
+        show.add(chosen)
+    return composite(psd, show)
+
+
+def find_group(psd: psdparse.PSDFile, name: str) -> int | None:
+    for folder_index in option_groups(psd):
+        if _label(psd, folder_index) == name:
+            return folder_index
+    return None
+
+
+def composite_comp(psd: psdparse.PSDFile, comp_id: int):
+    """Composite a document **layer comp** (`comp_id` from psd.layer_comps).
+
+    Each layer's `comp_states[comp_id].enabled` says whether it shows in that
+    comp; layers the comp doesn't mention keep their current visibility. (Comp
+    position/appearance overrides are not applied — visibility only.)
+    """
+    show = set()
+    for i, layer in enumerate(psd.layers):
+        if layer.layer_type not in _PIXEL_TYPES:
+            continue
+        st = layer.comp_states
+        visible = st[comp_id]["enabled"] if comp_id in st else layer.visible
+        if visible:
+            show.add(i)
+    return composite(psd, show)
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="Composite tachie layer-group combinations.")
+    ap.add_argument("input")
+    ap.add_argument("out_dir")
+    ap.add_argument("--group", action="append", default=[],
+                    help="folder name to sweep (repeatable). Default: the first group.")
+    ap.add_argument("--comps", action="store_true",
+                    help="instead of sweeping groups, render each document layer comp")
+    ap.add_argument("--limit", type=int, default=24, help="max images to write")
+    args = ap.parse_args()
+
+    psd = psdparse.PSDFile()
+    if not psd.load(args.input):
+        raise SystemExit(f"failed to load {args.input}")
+
+    if args.comps:
+        comps = psd.layer_comps
+        if not comps:
+            raise SystemExit("this PSD has no document layer comps")
+        os.makedirs(args.out_dir, exist_ok=True)
+        for n, c in enumerate(comps):
+            img = composite_comp(psd, c["id"])
+            safe = "".join(ch if ch.isalnum() else "_" for ch in c["name"]).strip("_")
+            img.save(os.path.join(args.out_dir, f"comp{n:02d}_{safe or c['id']}.png"))
+        print(f"wrote {len(comps)} layer comps to {args.out_dir}")
+        return
+
+    groups = option_groups(psd)
+    if not groups:
+        raise SystemExit("no option groups (top-level folders) found")
+
+    print("option groups:")
+    for folder_index, opts in groups.items():
+        print(f"  {_label(psd, folder_index)!r}: {[_label(psd, o) for o in opts]}")
+
+    # which groups to sweep
+    if args.group:
+        sweep = [find_group(psd, n) for n in args.group]
+        if None in sweep:
+            raise SystemExit(f"group not found among {[_label(psd, g) for g in groups]}")
+    else:
+        sweep = [next(iter(groups))]
+
+    os.makedirs(args.out_dir, exist_ok=True)
+    combos = itertools.product(*[groups[g] for g in sweep])
+    n = 0
+    for combo in combos:
+        if n >= args.limit:
+            print(f"(stopped at --limit {args.limit})")
+            break
+        choices = dict(zip(sweep, combo))
+        img = composite_choices(psd, choices)
+        tag = "_".join(_label(psd, o).split()[0] for o in combo) or f"v{n}"
+        path = os.path.join(args.out_dir, f"{n:03d}_{tag}.png")
+        img.save(path)
+        n += 1
+    print(f"wrote {n} images to {args.out_dir}")
+
+
+if __name__ == "__main__":
+    main()