psdparse 0.2.2__tar.gz → 0.3.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.2
 Name: psdparse
-Version: 0.2.2
+Version: 0.3.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>

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

@@ -101,7 +101,10 @@ Read-only view of one layer.
 | `channels` | `list[ChannelInfo]` | per-channel id+length |
 | `name` | `str` | raw Pascal-string name (CP932 etc on Japanese PSDs — pybind11 may raise UnicodeDecodeError when read) |
 | `name_unicode` | `str` | UTF-16 Unicode name from `luni` record (preferred) |
+| `parent_index` | `int` | index into `PSDFile.layers` of the enclosing folder, or `-1` for top level — see [Layer hierarchy](#layer-hierarchy) |
 | `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 |
 | `visible` | `bool` | flag bit 1 inverted |
 | `transparency_protected` | `bool` | flag bit 0 |
 | `obsolete` | `bool` | flag bit 2 |
@@ -155,6 +158,79 @@ for layer in p.layers:
     print(t["text"], "→", {r["font"] for r in t["runs"]})
 ```
 
+### `layer.mask` — layer mask geometry & flags
+
+`None` for layers without a mask. When present:
+
+```python
+{
+  "top": 8, "left": 10, "bottom": 40, "right": 50,   # mask bbox on canvas
+  "width": 40, "height": 32,
+  "default_color": 0,        # 0..255, area outside the stored mask rect
+  "flags": 0,                # raw flag byte
+  "relative": False,         # bit0: position relative to layer
+  "disabled": False,         # bit1: mask disabled
+  "inverted": False,         # bit2: invert (obsolete)
+  "from_render": False,      # bit3: mask from rendering other data
+  "has_parameters": False,   # bit4: density/feather present (not decoded yet)
+  "real": None,              # or a nested dict (below) for a real/user mask
+}
+```
+
+When the record carries a *real* (user + vector combined) mask, `real` is a dict
+with `flags`, `background`, and the enclosing `top/left/bottom/right`. The mask
+**pixels** are unchanged from before — fetch them with
+`p.layer_image(i, "mask")`.
+
+### `layer.blending_ranges` — "Blend If" ranges
+
+`None` when absent. `gray` is the composite range; `channels` has one entry per
+channel. Each value is the raw 32-bit packed range (two 16-bit black/white
+sub-ranges — split yourself if you need the individual sliders):
+
+```python
+{
+  "gray": (65535, 65535),                 # (source, dest)
+  "channels": [(0, 65535), (0, 65535), ...],
+}
+```
+
+## Layer hierarchy
+
+Layers are a **flat list in file order**; folder structure is recovered from
+`layer.parent_index` (`-1` = top level, otherwise the index of the enclosing
+`FOLDER` layer). To build a tree:
+
+```python
+children = {i: [] for i in range(len(p.layers))}
+roots = []
+for i, l in enumerate(p.layers):
+    (roots if l.parent_index == -1 else children[l.parent_index]).append(i)
+```
+
+`FOLDER` marks a group's start and the matching `HIDDEN` layer marks its end
+(these are Photoshop's `lsct` section dividers).
+
+## Document resources
+
+Read-only accessors on `PSDFile` for whole-document metadata. Each returns
+`None` (or an empty list) when the PSD lacks that resource.
+
+```python
+p.guides        # dict|None : {"horizontal_grid", "vertical_grid", "guides":[{"location","direction"}]}
+p.slices        # dict|None : {"group_name", "bounding":{...}, "slices":[{...}]}
+p.layer_comps   # list[dict]: [{"id","name","comment","record_visibility","record_position","record_appearance"}]
+p.color_table   # dict|None : {"colors":[(r,g,b,a)], "valid_count", "transparency_index"} for indexed-color PSDs
+```
+
+- **`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
+  (`left/top/right/bottom`), `url`, `target`, `message`, `alt_tag`, `cell_text`,
+  alignment, and an `(r, g, b, a)` `color` tuple.
+- **`color_table`** — only present for `COLOR_MODE_INDEXED` PSDs; `colors` is the
+  palette and `transparency_index` is `-1` when there is no transparent entry.
+
 ## Enums
 
 ```python

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

@@ -78,8 +78,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.
 - 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: parse + re-emission for masks > 20 bytes (real mask, vector mask flag, density / feather).
+- 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.
 - CMYK / Lab / Indexed color extraction in `getLayerImage` — currently optimized for RGB.
 - Linux / macOS testing. mmap path uses POSIX `mmap` but hasn't been built / tested there.

{psdparse-0.2.2 → psdparse-0.3.0}/psdparse/psddata.h

@@ -287,6 +287,8 @@ namespace psd {
 	};
 
 	struct LayerMask {
+    bool present = false;  // マスクブロック (size>0) が存在したか
+    bool hasReal = false;  // real/user mask (size>20) を含むか
     int width;
     int height;
 		int top;
@@ -309,6 +311,7 @@ namespace psd {
 	};
 
 	struct LayerBlendingRange {
+		bool present = false;  // blending range ブロック (size>0) が存在したか
 		int grayBlendSource;
 		int grayBlendDest;
 		std::vector<LayerBlendingChannel> channels;
@@ -477,6 +480,8 @@ namespace psd {
 
     // 親フォルダレイヤ
     LayerInfo *parent;
+    // 親フォルダの layerList インデックス (-1 = トップレベル)。processParsed で設定。
+    int parentIndex = -1;
 
     bool isTransparencyProtected() const { return (flag & (1 << 0)) != 0; }
     bool isVisible()               const { return (flag & (1 << 1)) == 0; }

{psdparse-0.2.2 → psdparse-0.3.0}/psdparse/psdparse.cpp

@@ -290,16 +290,21 @@ Data::processParsed()
 
   // グループ情報をリンク
   std::stack<LayerInfo*> parent;
+  std::stack<int>        parentIdx;
   parent.push(0);
+  parentIdx.push(-1);
   for (int i = (int)layerList.size() - 1; i >= 0; i--) {
     LayerInfo *layer = &layerList[i];
     layer->parent = parent.top();
+    layer->parentIndex = parentIdx.top();
     switch (layer->layerType) {
     case LAYER_TYPE_FOLDER:
       parent.push(layer);
+      parentIdx.push(i);
       break;
     case LAYER_TYPE_HIDDEN:
       parent.pop();
+      if (parentIdx.size() > 1) parentIdx.pop();
       break;
     default:
       break;
@@ -449,6 +454,7 @@ void parseLayerMask(IteratorBase &r, LayerMask &m, int size) {
   // is realFlags; the original grammar consumed a byte before realFlags too.
   (void)r.getCh();
   if (size > 20) {
+    m.hasReal                = true;
     m.realFlags              = r.getCh();
     m.realUserMaskBackground = r.getCh();
     m.enclosingTop           = r.getInt32(true);
@@ -458,9 +464,11 @@ void parseLayerMask(IteratorBase &r, LayerMask &m, int size) {
   }
   m.width  = m.right  - m.left;
   m.height = m.bottom - m.top;
+  m.present = true;
 }
 
 void parseLayerBlendingRange(IteratorBase &r, LayerBlendingRange &b) {
+  b.present = true;
   b.grayBlendSource = r.getInt32(true);
   b.grayBlendDest   = r.getInt32(true);
   while (r.rest() >= 8) {

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

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

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

@@ -74,6 +74,144 @@ py::object layerText(const psd::LayerInfo &l) {
   return std::move(d);
 }
 
+// Layer mask ('layer mask / adjustment layer data') as a dict, or None when
+// the layer carries no mask.
+py::object layerMask(const psd::LayerInfo &l) {
+  const psd::LayerMask &m = l.extraData.layerMask;
+  if (!m.present) return py::none();
+  py::dict d;
+  d["top"]    = m.top;
+  d["left"]   = m.left;
+  d["bottom"] = m.bottom;
+  d["right"]  = m.right;
+  d["width"]  = m.width;
+  d["height"] = m.height;
+  d["default_color"] = m.defaultColor;   // 0..255
+  d["flags"]      = m.flags;              // raw flag byte
+  d["relative"]   = (bool)(m.flags & 1);  // position relative to layer
+  d["disabled"]   = (bool)(m.flags & 2);  // mask disabled
+  d["inverted"]   = (bool)(m.flags & 4);  // invert (obsolete)
+  d["from_render"] = (bool)(m.flags & 8); // mask from rendering other data
+  d["has_parameters"] = (bool)(m.flags & 16); // density/feather present (not decoded yet)
+  if (m.hasReal) {                         // real/user mask (block size > 20)
+    py::dict rd;
+    rd["flags"]      = m.realFlags;
+    rd["background"] = m.realUserMaskBackground;
+    rd["top"]    = m.enclosingTop;
+    rd["left"]   = m.enclosingLeft;
+    rd["bottom"] = m.enclosingBottom;
+    rd["right"]  = m.enclosingRight;
+    d["real"] = rd;
+  } else {
+    d["real"] = py::none();
+  }
+  return std::move(d);
+}
+
+// Layer blending ranges as a dict, or None when absent. source/dest are the
+// raw 32-bit packed values (each holds two 16-bit black/white sub-ranges).
+py::object layerBlendingRanges(const psd::LayerInfo &l) {
+  const psd::LayerBlendingRange &b = l.extraData.layerBlendingRange;
+  if (!b.present) return py::none();
+  py::dict d;
+  d["gray"] = py::make_tuple(b.grayBlendSource, b.grayBlendDest);
+  py::list ch;
+  for (const auto &c : b.channels)
+    ch.append(py::make_tuple(c.source, c.dest));
+  d["channels"] = ch;
+  return std::move(d);
+}
+
+// Grid & guides image resource (1032) as a dict, or None when the PSD has none.
+py::object psdGuides(psd::PSDFile &self) {
+  const psd::GridGuideResource &g = self.gridGuide;
+  if (!g.isEnabled) return py::none();
+  py::dict d;
+  d["horizontal_grid"] = g.horizontalGrid;
+  d["vertical_grid"]   = g.verticalGrid;
+  py::list gl;
+  for (const auto &gi : g.guides) {
+    py::dict gd;
+    gd["location"]  = gi.location;   // 1/32 px from origin
+    gd["direction"] = (gi.direction == psd::GUIDE_DIR_VERTICAL) ? "vertical"
+                                                                : "horizontal";
+    gl.append(gd);
+  }
+  d["guides"] = gl;
+  return std::move(d);
+}
+
+// Slices image resource (1050, v6) as a dict, or None when absent.
+py::object psdSlices(psd::PSDFile &self) {
+  const psd::SliceResource &s = self.slice;
+  if (!s.isEnabled) return py::none();
+  py::dict d;
+  d["group_name"] = py::cast(s.groupName);
+  py::dict bb;
+  bb["left"]   = s.boundingLeft;
+  bb["top"]    = s.boundingTop;
+  bb["right"]  = s.boundingRight;
+  bb["bottom"] = s.boundingBottom;
+  d["bounding"] = bb;
+  py::list items;
+  for (const auto &it : s.slices) {
+    py::dict id;
+    id["id"]       = it.id;
+    id["group_id"] = it.groupId;
+    id["origin"]   = it.origin;
+    id["associated_layer_id"] = it.associatedLayerId;
+    id["name"]     = py::cast(it.name);
+    id["type"]     = it.type;
+    id["left"]     = it.left;
+    id["top"]      = it.top;
+    id["right"]    = it.right;
+    id["bottom"]   = it.bottom;
+    id["url"]      = py::cast(it.url);
+    id["target"]   = py::cast(it.target);
+    id["message"]  = py::cast(it.message);
+    id["alt_tag"]  = py::cast(it.altTag);
+    id["cell_text"] = py::cast(it.cellText);
+    id["is_cell_text_html"] = it.isCellTextHtml;
+    id["horizontal_align"]  = it.horizontalAlign;
+    id["vertical_align"]    = it.verticalAlign;
+    id["color"] = py::make_tuple(it.colorR, it.colorG, it.colorB, it.colorA);
+    items.append(id);
+  }
+  d["slices"] = items;
+  return std::move(d);
+}
+
+// Layer comps image resource (1065) as a list of dicts (empty list if none).
+py::list psdLayerComps(psd::PSDFile &self) {
+  py::list out;
+  for (const auto &c : self.layerComps) {
+    py::dict d;
+    d["id"]      = c.id;
+    d["name"]    = py::cast(c.name);
+    d["comment"] = py::cast(c.comment);
+    d["record_visibility"] = c.isRecordVisibility;
+    d["record_position"]   = c.isRecordPosition;
+    d["record_appearance"] = c.isRecordAppearance;
+    out.append(d);
+  }
+  return out;
+}
+
+// Indexed-color palette (from color mode data) as a dict, or None for
+// non-indexed PSDs.
+py::object psdColorTable(psd::PSDFile &self) {
+  const psd::ColorTable &t = self.colorTable;
+  if (t.colors.empty()) return py::none();
+  py::dict d;
+  d["valid_count"]        = t.validCount;
+  d["transparency_index"] = t.transparencyIndex;
+  py::list cols;
+  for (const auto &c : t.colors)
+    cols.append(py::make_tuple(c.r, c.g, c.b, c.a));
+  d["colors"] = cols;
+  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())
@@ -172,9 +310,17 @@ PYBIND11_MODULE(psdparse, m) {
     .def_property_readonly("name_unicode", [](const psd::LayerInfo &l) {
         return u16ToStr(l.layerNameUnicode);
     })
+    .def_readonly("parent_index", &psd::LayerInfo::parentIndex,
+        "Index into PSDFile.layers of the enclosing folder layer, or -1 for "
+        "top-level layers. Build the layer tree from these.")
     .def_property_readonly("text", &layerText,
         "Text-layer content/style as a dict (keys: text, orientation, "
         "justification, transform, runs[]), or None for non-text layers.")
+    .def_property_readonly("mask", &layerMask,
+        "Layer mask as a dict (bbox, default_color, flags, disabled, real{}), "
+        "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("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(); })
@@ -232,7 +378,19 @@ PYBIND11_MODULE(psdparse, m) {
     .def("layer_image", &layerImage,
          py::arg("index"), py::arg("mode") = "masked",
          "Extract pixels for layer `index` as BGRA bytes. "
-         "mode: 'masked' (default), 'image' (no mask), 'mask' (mask only).");
+         "mode: 'masked' (default), 'image' (no mask), 'mask' (mask only).")
+    .def_property_readonly("guides", &psdGuides,
+         "Grid & guides (image resource 1032) as a dict "
+         "(horizontal_grid, vertical_grid, guides[]), or None.")
+    .def_property_readonly("slices", &psdSlices,
+         "Slices (image resource 1050 v6) as a dict "
+         "(group_name, bounding, slices[]), or None.")
+    .def_property_readonly("layer_comps", &psdLayerComps,
+         "Document layer comps (image resource 1065) as a list of dicts "
+         "(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.");
 
   // Enum-like ints exposed as module attributes for convenience
   m.attr("LAYER_TYPE_NORMAL") = (int)psd::LAYER_TYPE_NORMAL;

{psdparse-0.2.2 → psdparse-0.3.0}/tests/conftest.py

@@ -58,6 +58,18 @@ def sample_text_psd():
     return _find_sample("fontsample.psd")
 
 
+@pytest.fixture(scope="session")
+def sample_group_psd():
+    """A PSD with nested folder groups (for hierarchy / metadata tests)."""
+    return _find_sample("config.psd", "system.psd")
+
+
+@pytest.fixture(scope="session")
+def sample_mask_psd():
+    """A small PSD with a layer mask (synthesized fixture)."""
+    return _find_sample("masktest.psd")
+
+
 @pytest.fixture
 def psd_ui(sample_ui_psd):
     p = psdparse.PSDFile()
@@ -72,6 +84,20 @@ def psd_text(sample_text_psd):
     return p
 
 
+@pytest.fixture
+def psd_group(sample_group_psd):
+    p = psdparse.PSDFile()
+    assert p.load(str(sample_group_psd))
+    return p
+
+
+@pytest.fixture
+def psd_mask(sample_mask_psd):
+    p = psdparse.PSDFile()
+    assert p.load(str(sample_mask_psd))
+    return p
+
+
 @pytest.fixture
 def psd_large(sample_large_psd):
     p = psdparse.PSDFile()

psdparse-0.3.0/tests/test_metadata.py

@@ -0,0 +1,104 @@
+"""Tests for the Tier-1 reference metadata exposed in 0.3.0:
+
+layer hierarchy (parent_index), layer mask, blending ranges, and the
+document-level guides / slices / layer comps / color table accessors.
+"""
+import psdparse
+
+
+# --- layer hierarchy -------------------------------------------------------
+
+def test_parent_index_valid(psd_group):
+    """Every parent_index is either -1 (top level) or points at a FOLDER."""
+    layers = psd_group.layers
+    tops = children = 0
+    for i, l in enumerate(layers):
+        pi = l.parent_index
+        assert pi == -1 or 0 <= pi < len(layers), (i, pi)
+        if pi == -1:
+            tops += 1
+        else:
+            children += 1
+            assert layers[pi].layer_type == psdparse.LayerType.FOLDER, \
+                f"parent of layer {i} (index {pi}) is not a FOLDER"
+    assert tops > 0
+    assert children > 0  # the group sample is nested
+
+
+def test_tree_reconstruction(psd_group):
+    """parent_index lets us rebuild children lists that partition the layers."""
+    layers = psd_group.layers
+    children = {i: [] for i in range(len(layers))}
+    roots = []
+    for i, l in enumerate(layers):
+        (roots if l.parent_index == -1 else children[l.parent_index]).append(i)
+    total = len(roots) + sum(len(v) for v in children.values())
+    assert total == len(layers)
+
+
+# --- layer mask ------------------------------------------------------------
+
+def test_mask_none_when_absent(psd_group):
+    # Most layers in the sample have no mask -> None.
+    assert any(l.mask is None for l in psd_group.layers)
+
+
+def test_mask_dict_shape(psd_mask):
+    masked = [l for l in psd_mask.layers if l.mask is not None]
+    assert len(masked) >= 1
+    m = masked[0].mask
+    # geometry is self-consistent
+    assert m["width"] == m["right"] - m["left"]
+    assert m["height"] == m["bottom"] - m["top"]
+    assert 0 <= m["default_color"] <= 255
+    for k in ("relative", "disabled", "inverted", "from_render", "has_parameters"):
+        assert isinstance(m[k], bool)
+    # synthesized fixture: 40x32 mask at (left=10, top=8), not disabled
+    assert (m["width"], m["height"]) == (40, 32)
+    assert m["disabled"] is False
+
+
+# --- blending ranges -------------------------------------------------------
+
+def test_blending_ranges_shape(psd_group):
+    ranged = [l for l in psd_group.layers if l.blending_ranges is not None]
+    assert len(ranged) > 0
+    br = ranged[0].blending_ranges
+    assert len(br["gray"]) == 2
+    for pair in br["channels"]:
+        assert len(pair) == 2
+
+
+# --- document resources ----------------------------------------------------
+
+def test_guides_accessor(psd_group):
+    g = psd_group.guides
+    if g is None:
+        return  # sample may lack a grid/guides resource
+    assert "horizontal_grid" in g and "vertical_grid" in g
+    for gd in g["guides"]:
+        assert gd["direction"] in ("vertical", "horizontal")
+
+
+def test_slices_accessor(psd_group):
+    s = psd_group.slices
+    if s is None:
+        return
+    assert "bounding" in s and "slices" in s
+    for it in s["slices"]:
+        assert it["right"] >= it["left"]
+        assert it["bottom"] >= it["top"]
+        assert len(it["color"]) == 4
+
+
+def test_layer_comps_is_list(psd_group):
+    comps = psd_group.layer_comps
+    assert isinstance(comps, list)
+    for c in comps:
+        assert "id" in c and "name" in c
+
+
+def test_color_table_none_for_rgb(psd_group):
+    # The group samples are RGB, so there is no indexed palette.
+    assert psd_group.header.mode == psdparse.COLOR_MODE_RGB
+    assert psd_group.color_table is None