psdparse 0.3.0__tar.gz → 0.5.0__tar.gz

{psdparse-0.3.0 → psdparse-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: psdparse
-Version: 0.3.0
+Version: 0.5.0
 Summary: Fast PSD (Photoshop) reader/writer — C++17 core with pybind11 bindings
 Keywords: psd,photoshop,parser,image,graphics
 Author-Email: wamsoft <wtnbgo@gmail.com>
@@ -133,6 +133,11 @@ p.save(r"out.psd")              # byte-identical round-trip
 
 Full API reference: [docs/PYTHON_API.md](docs/PYTHON_API.md).
 
+## PSD feature coverage
+
+What psdparse can and cannot read, at a glance:
+[docs/SUPPORT.md](docs/SUPPORT.md) (対応状況マトリクス).
+
 ## Tests
 
 Tests live under `tests/` and use [pytest](https://docs.pytest.org/). They need sample PSDs placed at the repo root or `tests/data/` (not committed — listed in `.gitignore`); without them the tests skip rather than fail.

{psdparse-0.3.0 → psdparse-0.5.0}/README.md

@@ -92,6 +92,11 @@ p.save(r"out.psd")              # byte-identical round-trip
 
 Full API reference: [docs/PYTHON_API.md](docs/PYTHON_API.md).
 
+## PSD feature coverage
+
+What psdparse can and cannot read, at a glance:
+[docs/SUPPORT.md](docs/SUPPORT.md) (対応状況マトリクス).
+
 ## Tests
 
 Tests live under `tests/` and use [pytest](https://docs.pytest.org/). They need sample PSDs placed at the repo root or `tests/data/` (not committed — listed in `.gitignore`); without them the tests skip rather than fail.

{psdparse-0.3.0 → psdparse-0.5.0}/docs/PYTHON_API.md

@@ -105,6 +105,9 @@ Read-only view of one layer.
 | `text` | `dict` \| `None` | text-layer content & style (`None` for non-text layers) — see below |
 | `mask` | `dict` \| `None` | layer mask geometry & flags (`None` when the layer has no mask) — see below |
 | `blending_ranges` | `dict` \| `None` | "Blend If" ranges (`None` when absent) — see below |
+| `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) |
+| `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 |
 | `obsolete` | `bool` | flag bit 2 |
@@ -223,6 +226,34 @@ p.layer_comps   # list[dict]: [{"id","name","comment","record_visibility","recor
 p.color_table   # dict|None : {"colors":[(r,g,b,a)], "valid_count", "transparency_index"} for indexed-color PSDs
 ```
 
+### Image resources (raw)
+
+Most image resources are exposed as their raw on-disk bytes; decoding (EXIF
+tags, rendering the thumbnail, parsing the ICC profile) is left to the caller.
+
+```python
+p.image_resource_ids     # list[int]  : IDs of every resource present
+p.image_resource(id)     # bytes|None : raw bytes of the resource with that ID
+p.icc_profile            # bytes|None : ICC profile (resource 1039)
+p.exif                   # bytes|None : EXIF block (1058)
+p.xmp                    # str|None   : XMP packet (1060), UTF-8 XML
+p.thumbnail              # dict|None  : {"format","width","height","bits","resource_id","data"}
+```
+
+- **`thumbnail`** — resource 1036 (RGB) or legacy 1033 (BGR). When
+  `format == "jpeg"`, `data` is JFIF JPEG bytes ready for `PIL.Image.open`:
+
+  ```python
+  import io
+  from PIL import Image
+  th = p.thumbnail
+  if th and th["format"] == "jpeg":
+      Image.open(io.BytesIO(th["data"])).save("thumb.png")
+  ```
+
+- **`xmp`** decodes as UTF-8 `str`; if a file's packet is not valid UTF-8, read
+  the raw bytes with `p.image_resource(1060)` instead.
+
 - **`guides`** — grid spacing (in 1/32 px) and each guide's `location` (1/32 px
   from origin) and `direction` (`"vertical"` / `"horizontal"`).
 - **`slices`** — Photoshop slices (v6). Each slice has `id`, `name`, bbox
@@ -231,6 +262,55 @@ p.color_table   # dict|None : {"colors":[(r,g,b,a)], "valid_count", "transparenc
 - **`color_table`** — only present for `COLOR_MODE_INDEXED` PSDs; `colors` is the
   palette and `transparency_index` is `-1` when there is no transparent entry.
 
+## Descriptor blocks
+
+Photoshop stores layer **effects**, **fill-layer** content and many other
+tagged blocks as its generic *descriptor* tree (the same OSType structure used
+throughout PSD). These accessors decode a block into nested Python
+dicts/lists so they can be read without a decoder per feature.
+
+```python
+layer.effects   # dict|None : object-based effects ('lfx2')
+layer.fill      # dict|None : {"type": "solid"|"gradient"|"pattern", "data": {...}}
+layer.info_keys # list[str] : every additional-info 4cc key present on the layer
+layer.descriptor(key, skip=-1)  # dict|None : parse an arbitrary key as a descriptor
+```
+
+**Value mapping** (descriptor item → Python):
+
+| Descriptor type | Python |
+|---|---|
+| Integer / Double | `int` / `float` |
+| Boolean | `bool` |
+| String / Alias / Class | `str` |
+| UnitFloat | `{"value": float, "unit": str}` (unit: `percent`, `angle`, `pixels`, …) |
+| Enumerated | `{"type": str, "value": str}` |
+| Descriptor (nested) | `dict` (keys are raw 4cc, **may end in a space**, e.g. `"Scl "`) |
+| List | `list` |
+| RawData (`tdta`) | `bytes` |
+| Reference / unknown | `None` |
+
+```python
+fx = layer.effects
+if fx:
+    print("effects on:", fx.get("masterFXSwitch"))
+    po = fx.get("patternFill")           # a nested descriptor dict
+    if po:
+        print("pattern overlay opacity:", po["Opct"]["value"])   # -> 100.0
+```
+
+Notes:
+- Keys are the **raw 4cc** as stored (trailing spaces preserved) — index with
+  the exact string, e.g. `fx["Scl "]`, `color["Rd  "]`.
+- `layer.effects` is `lfx2` (object-based, Photoshop 6+). The older binary
+  `lrFX` block is **not** a descriptor and returns `None` via `descriptor()`.
+- `descriptor(key, skip)` is the generic escape hatch: `skip` is the number of
+  version-prefix bytes before the descriptor (`-1` auto-detects for `lfx2` = 8
+  and `SoCo`/`GdFl`/`PtFl` = 4, otherwise 0). Use `info_keys` to discover which
+  blocks a layer carries.
+- Decoding is **lazy** — the descriptor is parsed from the block's raw bytes on
+  each access, so cache the result if you read it repeatedly.
+
 ## Enums
 
 ```python

{psdparse-0.3.0 → psdparse-0.5.0}/docs/ROADMAP.md

@@ -1,5 +1,8 @@
 # psdparse Roadmap
 
+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-06-12)
 
 - ✅ Pure C++17 parser (no Boost)
@@ -78,7 +81,9 @@ This is mostly a constructor that fills `Data` with a minimal-but-valid skeleton
   - **Warp text** — lives in the `TySh` *warp* descriptor (currently skipped, not in EngineData); needs samples with each warp style + non-zero bend/distortion.
   - **Area (paragraph) vs point text / text box bounds** and **text-on-path** — need samples.
   - **Leading / faux bold-italic / underline / strikethrough / paragraph indent+spacing** — keys exist in EngineData but are default-valued in the current sample, so per-run extraction can't be verified yet; needs a sample authored with non-default values.
-- ✅ **Tier-1 reference metadata exposed to Python.** *Done 2026-08-02 (0.3.0).* Data the C++ core already parsed but Python couldn't reach is now bound: `layer.parent_index` (folder hierarchy), `layer.mask` (bbox / flags / real-mask dict), `layer.blending_ranges`, and document-level `PSDFile.guides` / `.slices` / `.layer_comps` / `.color_table`. All dict-shaped, matching the existing `layer.text` style. Validated against `config.psd` / `system.psd` (hierarchy, blend ranges, guides, slices) and a psd-tools-synthesized `masktest.psd` (mask bbox/flags cross-checked) — see `tests/test_metadata.py`. **Next (Tier 2, highest leverage):** a generic `Descriptor → dict` bridge that routes the currently-skipped `lfx2` (layer effects), `SoCo`/`GdFl`/`PtFl` (fill layers) and `SoLd` (smart-object transform) raw bytes through the existing complete descriptor parser — unlocks effects/fill/smart-object metadata cheaply without per-feature decoders.
+- ✅ **Tier-1 reference metadata exposed to Python.** *Done 2026-08-02 (0.3.0).* Data the C++ core already parsed but Python couldn't reach is now bound: `layer.parent_index` (folder hierarchy), `layer.mask` (bbox / flags / real-mask dict), `layer.blending_ranges`, and document-level `PSDFile.guides` / `.slices` / `.layer_comps` / `.color_table`. All dict-shaped, matching the existing `layer.text` style. Validated against `config.psd` / `system.psd` (hierarchy, blend ranges, guides, slices) and a psd-tools-synthesized `masktest.psd` (mask bbox/flags cross-checked) — see `tests/test_metadata.py`.
+- ✅ **Tier-2 generic Descriptor → dict bridge.** *Done 2026-08-02 (0.4.0).* `layer.effects` (`lfx2`), `layer.fill` (`SoCo`/`GdFl`/`PtFl`), `layer.info_keys`, and a generic `layer.descriptor(key, skip)` escape hatch route previously-skipped tagged blocks through the existing complete descriptor parser (`psddesc.*`). A `Descriptor → py::dict` converter in the binding (dynamic_cast dispatch; UnitFloat→`{value,unit}`, Enumerated→`{type,value}`, nested Descriptor→dict, List→list, tdta→bytes) means no per-feature decoders were needed. Decoding is lazy: each access clones the block's reader (`clone()`+`init()`) and re-parses, so `save()` round-trips remain byte-identical. Cross-checked value-for-value against psd-tools 1.17 on `config.psd`'s PatternOverlay (opacity/scale/angle/blend/pattern-name all matched) — see `tests/test_descriptors.py`. **Deferred:** typed high-level effect/fill objects, smart-object `SoLd`/`lnkD` (embedded-file extraction), and binary adjustment layers (`levl`/`curv`) all still need work — the raw descriptor dict is the current interface.
+- ✅ **Image-resource raw bytes exposed.** *Done 2026-08-02 (0.5.0).* `PSDFile.image_resource(id)` / `.image_resource_ids` plus typed shortcuts `.icc_profile` (1039), `.exif` (1058), `.xmp` (1060, UTF-8 str) and `.thumbnail` (1036/1033 → dict with JPEG bytes + dimensions). Raw bytes only — decoding EXIF tags / rendering the thumbnail is left to the caller. EXIF and ICC bytes cross-checked byte-identical against psd-tools 1.17; thumbnail JPEG verified decodable with Pillow — see `tests/test_resources.py`. **Still raw-only / unexposed:** higher-level decode of these (parsed EXIF, ICC transform) and the structured `GlobalLayerMaskInfo`.
 - 16-bit (`Lr16`) and 32-bit-float (`Lr32`) layer data: currently captured in `layerAndMaskTrailing` for round-trip but not exposed as decoded pixels.
 - Layer mask: density / feather decoding (the `has_parameters` flag is exposed but the `MaskParameters` values are not read yet), plus re-emission for masks > 20 bytes.
 - Image resources: most are currently passed through as raw bytes. Higher-level accessors for ICC profile, EXIF, thumbnail, version info, etc. would be nice for tools.

psdparse-0.5.0/docs/SUPPORT.md

@@ -0,0 +1,160 @@
+# psdparse PSD 対応状況 (Support Matrix)
+
+psdparse が PSD のどの機能を、どの水準で扱えるかの一覧です。psdparse は
+**参照 (読み取り) + ラウンドトリップ保存** に重点を置いた実装で、編集保存や
+高度な再合成は対象外です。
+
+対応状況の凡例:
+
+| 記号 | 意味 |
+|:---:|---|
+| ✅ | 対応済み — 構造化して取得できる |
+| 🟡 | 部分対応 — 一部の値のみ / 生 descriptor 経由 |
+| 📦 | 生バイトのみ保持 (ラウンドトリップ用。Python へは未公開) |
+| ❌ | 未対応 — パースしていない |
+
+最終更新: 2026-08-02 (v0.4.0)。詳細な今後の計画は [ROADMAP.md](ROADMAP.md)、
+Python API の使い方は [PYTHON_API.md](PYTHON_API.md) を参照。
+
+---
+
+## ファイル全体
+
+| 機能 | 状況 | 備考 |
+|---|:---:|---|
+| ヘッダ (幅/高さ/チャンネル/深度/モード/版) | ✅ | `PSDFile.header` |
+| 解像度 (dpi, image resource 1005) | ✅ | `header.hres` / `header.vres` |
+| PSB (large document, version 2) | ❌ | `version` は読めるが、PSB 特有の 8 byte 長フィールドの分岐が無く未対応 |
+| ラウンドトリップ保存 (byte-identical) | ✅ | `load(a) -> save(b)` が完全一致 |
+| 編集して保存 (レイヤ追加/削除/差し替え) | ❌ | ROADMAP Phase 4b–4e。RLE エンコーダ未実装 |
+
+## 圧縮 / ビット深度
+
+| 項目 | 状況 | 備考 |
+|---|:---:|---|
+| Raw / RLE(PackBits) / ZIP(±prediction) | ✅ | 展開対応 |
+| ビット深度 1 / 8 / 16 / 32 | ✅ | それ以外は非対応 |
+
+## カラーモード (ピクセル展開: `merged_image` / `layer_image`)
+
+| モード | 状況 | 備考 |
+|---|:---:|---|
+| Bitmap (1bit) | ✅ | |
+| Grayscale (8/16/32) | ✅ | |
+| RGB (8/16/32) | ✅ | |
+| Indexed (8bit) | ✅ | パレットは `PSDFile.color_table` |
+| CMYK (8/16/32) | ✅ | RGB へ変換して出力 |
+| Multichannel | ❌ | `getLayerImage` 未対応 |
+| Duotone | ❌ | 同上 |
+| Lab | ❌ | 同上 |
+
+出力は常に **BGRA インターリーブ** (4 byte/px)。ICC を用いた色変換は行いません。
+
+## 画像取得
+
+| 機能 | 状況 | 備考 |
+|---|:---:|---|
+| 合成画像 (merged/composite) | ✅ | `merged_image()` — PSD 保存済みの合成を返す |
+| レイヤ画像 (mask 込み/無し/mask のみ) | ✅ | `layer_image(i, "masked"/"image"/"mask")` |
+| 効果・調整を適用した再合成 (`composite()` 相当) | ❌ | 保存済み合成の取得のみ。再描画はしない |
+
+---
+
+## レイヤ属性
+
+| 属性 | 状況 | API |
+|---|:---:|---|
+| 位置/サイズ (bbox, width, height) | ✅ | `top/left/bottom/right`, `width`, `height` |
+| ブレンドモード | ✅ | `blend_mode` (enum), `blend_mode_key` |
+| 不透明度 / 塗り不透明度 | ✅ | `opacity`, `fill_opacity` |
+| クリッピング | ✅ | `clipping` |
+| 可視/ロック等フラグ | ✅ | `visible`, `transparency_protected`, `obsolete`, `pixel_data_irrelevant` |
+| レイヤ名 (raw / Unicode) | ✅ | `name`, `name_unicode` |
+| レイヤ ID | ✅ | `layer_id` |
+| レイヤ種別 | ✅ | `layer_type` (NORMAL/HIDDEN/FOLDER/ADJUST/FILL/TEXT) |
+| **フォルダ階層 (親子)** | ✅ | `parent_index` (v0.3.0) |
+| チャンネル構成 (id/length) | ✅ | `channels[]` |
+| シートカラー (レイヤパネルの色ラベル, `lclr`) | ❌ | 未デコード |
+
+## レイヤマスク / ブレンド範囲
+
+| 機能 | 状況 | API |
+|---|:---:|---|
+| マスク矩形/フラグ/既定色 | ✅ | `layer.mask` (v0.3.0) |
+| real/user mask (>20byte) | ✅ | `layer.mask["real"]` |
+| density / feather | 🟡 | `has_parameters` フラグのみ公開。値 (MaskParameters) は未デコード |
+| ベクタマスク / パス (`vmsk`/`vsms`) | ❌ | 未対応 |
+| ブレンディングレンジ ("Blend If") | ✅ | `layer.blending_ranges` (raw 32bit packed) |
+
+## テキストレイヤ
+
+| 機能 | 状況 | 備考 |
+|---|:---:|---|
+| 本文 / 縦横 / 変換行列 | ✅ | `layer.text` (`text`/`orientation`/`transform`) |
+| ラン単位スタイル (font/size/color/tracking/kerning) | ✅ | `text["runs"]` |
+| 段落別の行揃え | ✅ | `text["paragraphs"]` (v0.2.2) |
+| ワープ (warp) | ❌ | TySh warp descriptor 未処理 |
+| 非 RGB の FillColor | ❌ | `/Type 1` (RGB) のみ |
+| leading / 疑似ボールド / 下線 等 | 🟡 | EngineData にキーはあるが既定値サンプルのみで未検証 |
+
+## Descriptor ブロック (v0.4.0)
+
+Photoshop の汎用ディスクリプタで格納されるブロックを dict 化して取得。
+
+| 機能 | 状況 | API |
+|---|:---:|---|
+| レイヤー効果 (`lfx2`, object-based) | ✅ | `layer.effects` (nested descriptor dict) |
+| 旧レイヤー効果 (`lrFX`, binary) | ❌ | descriptor でないため未対応 |
+| 塗りつぶしレイヤ (`SoCo`/`GdFl`/`PtFl`) | ✅ | `layer.fill` (`{type, data}`) |
+| 任意キーの descriptor 取得 | ✅ | `layer.descriptor(key, skip)` / `layer.info_keys` |
+
+`effects` / `fill` は **生 descriptor を辞書化したもの** で、効果ごとの型付き
+アクセサ (drop shadow の angle/distance を名前で、等) はまだありません。値の
+マッピング規則は [PYTHON_API.md](PYTHON_API.md#descriptor-blocks) を参照。
+
+## 調整レイヤ / 塗りつぶし / スマートオブジェクト / シェイプ
+
+| 機能 | 状況 | 備考 |
+|---|:---:|---|
+| 調整レイヤの種別判定 | ✅ | `layer_type == ADJUST` |
+| 調整レイヤのパラメータ (levels/curves 等, binary) | ❌ | 未デコード。descriptor 形式のもの (`CgEd` 等) は `descriptor()` で取得可 |
+| スマートオブジェクト変換 (`SoLd`/`PlLd`) | 🟡 | `descriptor()` で試行可 (未検証、既定 skip 要調整) |
+| スマートオブジェクト埋め込みデータ抽出 (`lnkD`) | ❌ | 未対応 |
+| ベクタストローク/シェイプ (`vstk`/`vscg`) | 🟡 | `descriptor()` 経由で取得可 (未検証) |
+| ライブシェイプ情報 (origination) | ❌ | 未対応 |
+
+---
+
+## Image Resources / 文書メタデータ
+
+| リソース | 状況 | API |
+|---|:---:|---|
+| 解像度 (1005) | ✅ | `header.hres/vres` |
+| グリッド & ガイド (1032) | ✅ | `PSDFile.guides` (v0.3.0) |
+| スライス (1050 v6) | ✅ | `PSDFile.slices` (v0.3.0) |
+| スライス (1050 v7/v8, descriptor) | ❌ | 未格納 |
+| レイヤーカンプ (1065) | ✅ | `PSDFile.layer_comps` (v0.3.0) |
+| インデックスカラーパレット (色/count/透明index) | ✅ | `PSDFile.color_table` (v0.3.0) |
+| ICC プロファイル (1039) | ✅ | `PSDFile.icc_profile` (生バイト, v0.5.0) |
+| EXIF (1058) | ✅ | `PSDFile.exif` (生バイト, v0.5.0) |
+| XMP メタデータ (1060) | ✅ | `PSDFile.xmp` (UTF-8 str, v0.5.0) |
+| サムネイル (1036/1033) | ✅ | `PSDFile.thumbnail` (JPEG bytes + 寸法, v0.5.0) |
+| 任意リソースの生バイト | ✅ | `PSDFile.image_resource(id)` / `image_resource_ids` (v0.5.0) |
+| 上記の内容デコード (EXIF タグ解析等) | ❌ | 生バイトを返すのみ。解析は利用側 (Pillow 等) で |
+| バージョン情報 / アルファチャンネル名 / その他 | 📦→✅ | `image_resource(id)` で生バイト取得可 |
+| Global layer mask info | 📦 | 構造体フィールドは未充填、生バイトのみ |
+
+---
+
+## まとめ (一言で)
+
+- **得意**: レイヤ列挙 + 属性 + 階層、RGB/CMYK/Gray/Indexed のピクセル取得、
+  テキストのラン単位スタイル、レイヤー効果/塗りの descriptor、文書メタデータ
+  (ガイド/スライス/カンプ) と image resource の生バイト (ICC/EXIF/XMP/サムネイル)、
+  そして **byte-identical なラウンドトリップ**。
+- **未対応/限定的**: Lab/Duotone/Multichannel ピクセル、調整レイヤの数値
+  パラメータ、ベクタパス、スマートオブジェクト実体、効果込みの再合成、
+  そして編集して保存。
+- image resource の**中身の解釈** (EXIF タグ, サムネイル描画等) は行わず生バイトを
+  返すのみ。残る 📦 (global layer mask info の構造化) は「公開するだけ」で対応可
+  (ROADMAP 参照)。

{psdparse-0.3.0 → psdparse-0.5.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "psdparse"
-version = "0.3.0"
+version = "0.5.0"
 description = "Fast PSD (Photoshop) reader/writer — C++17 core with pybind11 bindings"
 readme = "README.md"
 requires-python = ">=3.9"

{psdparse-0.3.0 → psdparse-0.5.0}/python/psdparse_module.cpp

@@ -9,6 +9,7 @@
 
 #include "psdfile.h"
 #include "psdparse.h"
+#include "psddesc.h"
 
 #include <fstream>
 #include <memory>
@@ -212,6 +213,215 @@ py::object psdColorTable(psd::PSDFile &self) {
   return std::move(d);
 }
 
+// -------------------------------------------------------------------------
+// Generic Descriptor -> Python bridge (Tier 2).
+//
+// Photoshop stores layer effects (lfx2), fill layers (SoCo/GdFl/PtFl) and
+// several other tagged blocks as its generic OSType "descriptor" tree. The
+// C++ core already has a complete descriptor parser (psddesc.*); these helpers
+// convert a parsed Descriptor into nested Python dicts/lists so the previously
+// skipped blocks become readable without per-feature decoders.
+// -------------------------------------------------------------------------
+
+const char *descUnitName(psd::DescriptorUnit u) {
+  switch (u) {
+  case psd::UNIT_POINTS:      return "points";
+  case psd::UNIT_MILLIMETERS: return "millimeters";
+  case psd::UNIT_ANGLE:       return "angle";
+  case psd::UNIT_DENSITY:     return "density";
+  case psd::UNIT_DISTANCE:    return "distance";
+  case psd::UNIT_NONE:        return "none";
+  case psd::UNIT_PERCENT:     return "percent";
+  case psd::UNIT_PIXELS:      return "pixels";
+  default:                    return "unknown";
+  }
+}
+
+py::dict descToPy(psd::Descriptor *d);
+
+// Dispatch a single descriptor item to a Python value. Uses dynamic_cast
+// rather than the `type` field because DescriptorReference and
+// DescriptorRawData share the same type tag ('tdta').
+py::object descItemToPy(psd::DescriptorItem *it) {
+  if (!it) return py::none();
+  if (auto *x = dynamic_cast<psd::DescriptorInteger*>(it))  return py::cast(x->val);
+  if (auto *x = dynamic_cast<psd::DescriptorDouble*>(it))   return py::cast(x->val);
+  if (auto *x = dynamic_cast<psd::DescriptorBoolean*>(it))  return py::cast(x->val);
+  if (auto *x = dynamic_cast<psd::DescriptorString*>(it))   return py::cast(x->val); // u16str -> str
+  if (auto *x = dynamic_cast<psd::DescriptorUnitFloat*>(it)) {
+    py::dict u; u["value"] = x->val; u["unit"] = descUnitName(x->unit);
+    return std::move(u);
+  }
+  if (auto *x = dynamic_cast<psd::DescriptorEnumerated*>(it)) {
+    py::dict e; e["type"] = x->typeId; e["value"] = x->enumId;
+    return std::move(e);
+  }
+  if (auto *x = dynamic_cast<psd::DescriptorList*>(it)) {
+    py::list out;
+    for (auto *item : x->items) out.append(descItemToPy(item));
+    return std::move(out);
+  }
+  if (auto *x = dynamic_cast<psd::Descriptor*>(it))        return descToPy(x);
+  if (auto *x = dynamic_cast<psd::DescriptorRawData*>(it)) return py::bytes(x->bytes);
+  if (auto *x = dynamic_cast<psd::DescriptorClass*>(it))   return py::cast(x->classId);
+  if (auto *x = dynamic_cast<psd::DescriptorAlias*>(it))   return py::cast(x->alias);
+  // DescriptorReference and anything unrecognized -> None.
+  return py::none();
+}
+
+py::dict descToPy(psd::Descriptor *d) {
+  py::dict out;
+  for (const auto &kv : d->itemMap)          // keys are raw 4cc (may end in space)
+    out[py::str(kv.first)] = descItemToPy(kv.second);
+  return out;
+}
+
+// Locate an additional-layer-info entry by 4cc key, parse its bytes as a
+// descriptor (after skipping `skip` version-prefix bytes) and return a dict,
+// or None when the key is absent / unparseable.
+py::object keyDescriptor(const psd::LayerInfo &l, int key, int skip) {
+  for (const auto &a : l.extraData.additionalLayers) {
+    if (a.key != key || !a.data) continue;
+    psd::IteratorBase *rd = a.data->clone();
+    rd->init();                    // rewind to the start of this key's data
+    if (skip > 0) rd->advance(skip);
+    psd::Descriptor desc;
+    desc.load(rd);                 // partial parse still leaves valid items
+    delete rd;
+    if (desc.itemMap.empty()) return py::none();
+    return descToPy(&desc);
+  }
+  return py::none();
+}
+
+// Object-based layer effects ('lfx2'): objVer(4) + descVer(4) then descriptor.
+py::object layerEffects(const psd::LayerInfo &l) {
+  return keyDescriptor(l, 'lfx2', 8);
+}
+
+// Fill-layer content ('SoCo' solid / 'GdFl' gradient / 'PtFl' pattern):
+// version(4) then descriptor. Returns {"type": ..., "data": {...}} or None.
+py::object layerFill(const psd::LayerInfo &l) {
+  const struct { int key; const char *type; } tbl[] = {
+    {'SoCo', "solid"}, {'GdFl', "gradient"}, {'PtFl', "pattern"},
+  };
+  for (const auto &e : tbl) {
+    py::object d = keyDescriptor(l, e.key, 4);
+    if (!d.is_none()) {
+      py::dict out;
+      out["type"] = e.type;
+      out["data"] = d;
+      return std::move(out);
+    }
+  }
+  return py::none();
+}
+
+// List the 4cc keys of all additional-layer-info blocks present on a layer.
+py::list layerInfoKeys(const psd::LayerInfo &l) {
+  py::list out;
+  for (const auto &a : l.extraData.additionalLayers) {
+    char s[4] = { (char)((a.key >> 24) & 0xff), (char)((a.key >> 16) & 0xff),
+                  (char)((a.key >> 8) & 0xff),  (char)(a.key & 0xff) };
+    out.append(py::str(s, 4));
+  }
+  return out;
+}
+
+// Generic escape hatch: parse an arbitrary additional-info key as a descriptor.
+// `skip` defaults (-1) to the known version-prefix length for well-known keys,
+// or 0 otherwise.
+py::object layerDescriptor(const psd::LayerInfo &l, const std::string &keyStr, int skip) {
+  if (keyStr.size() != 4)
+    throw std::invalid_argument("key must be a 4-character string");
+  int key = ((int)(uint8_t)keyStr[0] << 24) | ((int)(uint8_t)keyStr[1] << 16) |
+            ((int)(uint8_t)keyStr[2] << 8)  |  (int)(uint8_t)keyStr[3];
+  if (skip < 0) {
+    switch (key) {
+    case 'lfx2':                             skip = 8; break;
+    case 'SoCo': case 'GdFl': case 'PtFl':   skip = 4; break;
+    default:                                 skip = 0; break;
+    }
+  }
+  return keyDescriptor(l, key, skip);
+}
+
+// -------------------------------------------------------------------------
+// Image resource raw-bytes access.
+//
+// Most image resources are kept as raw bytes internally (imageResourceList)
+// but were never reachable from Python. These helpers expose them: a generic
+// by-ID accessor plus typed shortcuts for the common ones (ICC / EXIF / XMP /
+// thumbnail). Decoding (parsing EXIF tags, rendering the thumbnail) is left to
+// the caller with e.g. Pillow.
+// -------------------------------------------------------------------------
+
+std::string resourceBytes(const psd::ImageResourceInfo &res) {
+  std::string buf((size_t)(res.size > 0 ? res.size : 0), '\0');
+  if (res.size > 0 && res.data) {
+    psd::IteratorBase *rd = res.data->clone();
+    rd->init();                       // rewind to the start of this resource
+    rd->getData(&buf[0], res.size);
+    delete rd;
+  }
+  return buf;
+}
+
+const psd::ImageResourceInfo *findResource(const psd::PSDFile &self, int id) {
+  for (const auto &res : self.imageResourceList)
+    if (res.id == id) return &res;
+  return nullptr;
+}
+
+py::list imageResourceIds(psd::PSDFile &self) {
+  py::list out;
+  for (const auto &res : self.imageResourceList) out.append((int)res.id);
+  return out;
+}
+
+py::object imageResource(psd::PSDFile &self, int id) {
+  const psd::ImageResourceInfo *res = findResource(self, id);
+  return res ? py::object(py::bytes(resourceBytes(*res))) : py::none();
+}
+
+py::object iccProfile(psd::PSDFile &self) { return imageResource(self, 1039); }
+py::object exifData(psd::PSDFile &self)   { return imageResource(self, 1058); }
+
+// XMP packet (resource 1060) is UTF-8 XML. Returned as str; use
+// image_resource(1060) for the raw bytes if the packet is not valid UTF-8.
+py::object xmpMetadata(psd::PSDFile &self) {
+  const psd::ImageResourceInfo *res = findResource(self, 1060);
+  if (!res) return py::none();
+  return py::str(resourceBytes(*res));
+}
+
+// Embedded thumbnail (resource 1036 = RGB / legacy 1033 = BGR). Header is 28
+// bytes; for format==1 the payload is a JFIF JPEG. Returns a dict with the
+// header fields and the raw payload, or None.
+py::object thumbnail(psd::PSDFile &self) {
+  const psd::ImageResourceInfo *res = findResource(self, 1036);
+  if (!res) res = findResource(self, 1033);
+  if (!res) return py::none();
+  std::string raw = resourceBytes(*res);
+  if (raw.size() < 28) return py::none();
+  auto be32 = [&](size_t o) {
+    return (uint32_t)(((uint8_t)raw[o] << 24) | ((uint8_t)raw[o+1] << 16) |
+                      ((uint8_t)raw[o+2] << 8) | (uint8_t)raw[o+3]);
+  };
+  auto be16 = [&](size_t o) {
+    return (uint16_t)(((uint8_t)raw[o] << 8) | (uint8_t)raw[o+1]);
+  };
+  py::dict d;
+  uint32_t fmt = be32(0);
+  d["format"]      = (fmt == 1) ? "jpeg" : "raw";
+  d["width"]       = be32(4);
+  d["height"]      = be32(8);
+  d["bits"]        = be16(24);
+  d["resource_id"] = (int)res->id;   // 1036 = RGB order, 1033 = BGR order
+  d["data"]        = py::bytes(raw.data() + 28, raw.size() - 28);
+  return std::move(d);
+}
+
 py::bytes layerImage(psd::PSDFile &self, int index, const std::string &mode) {
   if (!self.isLoaded) throw std::runtime_error("PSD not loaded");
   if (index < 0 || index >= (int)self.layerList.size())
@@ -321,6 +531,19 @@ PYBIND11_MODULE(psdparse, m) {
         "or None when the layer has no mask.")
     .def_property_readonly("blending_ranges", &layerBlendingRanges,
         "Layer blending ranges as a dict (gray, channels[]), or None.")
+    .def_property_readonly("effects", &layerEffects,
+        "Object-based layer effects ('lfx2') as a nested descriptor dict "
+        "(drop shadow / glow / overlay / stroke / bevel ...), or None.")
+    .def_property_readonly("fill", &layerFill,
+        "Fill-layer content as {'type': 'solid'|'gradient'|'pattern', "
+        "'data': {...}} from SoCo/GdFl/PtFl, or None.")
+    .def_property_readonly("info_keys", &layerInfoKeys,
+        "List of the 4cc keys of every additional-layer-info block present.")
+    .def("descriptor", &layerDescriptor,
+        py::arg("key"), py::arg("skip") = -1,
+        "Parse an arbitrary additional-info `key` (4-char str) as a Photoshop "
+        "descriptor dict. `skip` = version-prefix bytes before the descriptor "
+        "(-1 = auto for known keys, else 0). Returns None if absent/unparseable.")
     .def_property_readonly("visible",                [](const psd::LayerInfo &l){ return l.isVisible(); })
     .def_property_readonly("transparency_protected", [](const psd::LayerInfo &l){ return l.isTransparencyProtected(); })
     .def_property_readonly("obsolete",               [](const psd::LayerInfo &l){ return l.isObsolete(); })
@@ -390,7 +613,22 @@ PYBIND11_MODULE(psdparse, m) {
          "(id, name, comment, record_*). Empty list when there are none.")
     .def_property_readonly("color_table", &psdColorTable,
          "Indexed-color palette as a dict (colors[], valid_count, "
-         "transparency_index), or None for non-indexed PSDs.");
+         "transparency_index), or None for non-indexed PSDs.")
+    .def_property_readonly("image_resource_ids", &imageResourceIds,
+         "List of the integer IDs of every image resource present.")
+    .def("image_resource", &imageResource, py::arg("id"),
+         "Raw bytes of the image resource with the given integer ID, or None.")
+    .def_property_readonly("icc_profile", &iccProfile,
+         "ICC profile (resource 1039) as raw bytes, or None.")
+    .def_property_readonly("exif", &exifData,
+         "EXIF block (resource 1058) as raw bytes, or None.")
+    .def_property_readonly("xmp", &xmpMetadata,
+         "XMP metadata (resource 1060) as a UTF-8 str, or None. Use "
+         "image_resource(1060) for raw bytes if not valid UTF-8.")
+    .def_property_readonly("thumbnail", &thumbnail,
+         "Embedded thumbnail (resource 1036/1033) as a dict "
+         "(format, width, height, bits, resource_id, data), or None. "
+         "For format=='jpeg', data is JFIF JPEG bytes.");
 
   // Enum-like ints exposed as module attributes for convenience
   m.attr("LAYER_TYPE_NORMAL") = (int)psd::LAYER_TYPE_NORMAL;

psdparse-0.5.0/tests/test_descriptors.py

@@ -0,0 +1,103 @@
+"""Tests for the Tier-2 generic descriptor bridge (0.4.0):
+
+layer.effects (lfx2), layer.fill (SoCo/GdFl/PtFl), layer.info_keys and the
+generic layer.descriptor(key) escape hatch.
+
+The group sample (config.psd) carries a layer with an 'lfx2' PatternOverlay;
+values here were cross-checked against psd-tools 1.17 reading the same file.
+"""
+import psdparse
+import pytest
+
+
+def _effects_layers(psd):
+    return [l for l in psd.layers if l.effects is not None]
+
+
+def test_effects_extraction(psd_group):
+    hits = _effects_layers(psd_group)
+    if not hits:
+        pytest.skip("sample has no layer effects")
+    e = hits[0].effects
+    assert isinstance(e, dict)
+    # master switch is a plain bool
+    assert e.get("masterFXSwitch") in (True, False)
+
+
+def test_unit_float_shape(psd_group):
+    hits = _effects_layers(psd_group)
+    if not hits:
+        pytest.skip("sample has no layer effects")
+    e = hits[0].effects
+    scl = e.get("Scl ")  # a UnitFloat
+    if scl is not None:
+        assert set(scl.keys()) == {"value", "unit"}
+        assert isinstance(scl["value"], float)
+        assert isinstance(scl["unit"], str)
+
+
+def test_descriptor_value_types(psd_group):
+    """Every converted value is a JSON-ish Python type (recursively)."""
+    hits = _effects_layers(psd_group)
+    if not hits:
+        pytest.skip("sample has no layer effects")
+
+    def check(v):
+        assert isinstance(v, (int, float, bool, str, bytes, dict, list, type(None)))
+        if isinstance(v, dict):
+            for x in v.values():
+                check(x)
+        elif isinstance(v, list):
+            for x in v:
+                check(x)
+
+    check(hits[0].effects)
+
+
+def test_pattern_overlay_values(psd_group):
+    """Cross-checked against psd-tools: PatternOverlay opacity=100, scale=50%."""
+    hits = _effects_layers(psd_group)
+    if not hits:
+        pytest.skip("sample has no layer effects")
+    pf = hits[0].effects.get("patternFill")
+    if not isinstance(pf, dict):
+        pytest.skip("sample effect is not a pattern overlay")
+    assert pf.get("enab") is True
+    assert pf["Opct"]["value"] == pytest.approx(100.0)
+
+
+def test_generic_descriptor_matches_effects(psd_group):
+    hits = _effects_layers(psd_group)
+    if not hits:
+        pytest.skip("sample has no layer effects")
+    l = hits[0]
+    assert l.descriptor("lfx2").keys() == l.effects.keys()
+
+
+def test_binary_key_returns_none(psd_group):
+    """lrFX is a binary (non-descriptor) block -> None, must not crash."""
+    for l in psd_group.layers:
+        if "lrFX" in l.info_keys:
+            assert l.descriptor("lrFX") is None
+            return
+    pytest.skip("sample has no lrFX block")
+
+
+def test_descriptor_bad_key_raises(psd_group):
+    with pytest.raises(ValueError):
+        psd_group.layers[0].descriptor("ab")
+
+
+def test_info_keys_are_4cc(psd_group):
+    for l in psd_group.layers:
+        keys = l.info_keys
+        assert isinstance(keys, list)
+        for k in keys:
+            assert isinstance(k, str) and len(k) == 4
+
+
+def test_fill_none_for_non_fill(psd_group):
+    # config/system samples contain no fill layers.
+    for l in psd_group.layers:
+        if l.layer_type != psdparse.LayerType.FILL:
+            assert l.fill is None

psdparse-0.5.0/tests/test_resources.py

@@ -0,0 +1,69 @@
+"""Tests for image-resource raw-bytes access (0.5.0):
+
+PSDFile.image_resource_ids / image_resource(id) and the typed shortcuts
+icc_profile / exif / xmp / thumbnail. EXIF and ICC bytes here were verified
+byte-identical against psd-tools 1.17.
+"""
+import psdparse
+import pytest
+
+
+def test_resource_ids_are_ints(psd_group):
+    ids = psd_group.image_resource_ids
+    assert isinstance(ids, list)
+    assert all(isinstance(i, int) for i in ids)
+    assert len(ids) > 0
+
+
+def test_generic_matches_typed(psd_group):
+    # image_resource(1058) is the same bytes as the exif shortcut.
+    assert psd_group.image_resource(1058) == psd_group.exif
+
+
+def test_absent_resource_is_none(psd_group):
+    # 9999 is not a real Photoshop resource id.
+    assert psd_group.image_resource(9999) is None
+
+
+def test_exif_present(psd_group):
+    exif = psd_group.exif
+    if exif is None:
+        pytest.skip("sample has no EXIF resource")
+    assert isinstance(exif, bytes) and len(exif) > 0
+
+
+def test_xmp_is_xml(psd_group):
+    xmp = psd_group.xmp
+    if xmp is None:
+        pytest.skip("sample has no XMP resource")
+    assert isinstance(xmp, str)
+    assert "xpacket" in xmp or "xmpmeta" in xmp
+
+
+def test_icc_profile(psd_text):
+    # fontsample.psd carries an ICC profile.
+    icc = psd_text.icc_profile
+    if icc is None:
+        pytest.skip("sample has no ICC profile")
+    assert isinstance(icc, bytes) and len(icc) > 0
+
+
+def test_thumbnail_header(psd_group):
+    th = psd_group.thumbnail
+    if th is None:
+        pytest.skip("sample has no thumbnail")
+    assert th["width"] > 0 and th["height"] > 0
+    assert th["format"] in ("jpeg", "raw")
+    assert isinstance(th["data"], bytes)
+    if th["format"] == "jpeg":
+        assert th["data"][:2] == b"\xff\xd8"  # JFIF/JPEG SOI marker
+
+
+def test_thumbnail_decodes(psd_group):
+    Image = pytest.importorskip("PIL.Image")
+    th = psd_group.thumbnail
+    if th is None or th["format"] != "jpeg":
+        pytest.skip("sample has no JPEG thumbnail")
+    import io
+    img = Image.open(io.BytesIO(th["data"]))
+    assert (img.width, img.height) == (th["width"], th["height"])