lvkit 0.8.1__tar.gz → 0.8.2__tar.gz

{lvkit-0.8.1 → lvkit-0.8.2}/.pre-commit-config.yaml

@@ -26,6 +26,10 @@ repos:
       - id: check-toml
       - id: check-added-large-files
         args: ["--maxkb=500"]
+        # Issue #82's regression fixture embeds a real ~3.6MB photograph (the
+        # bug is an embedded PICTURE decoration), so it can't fit the 500KB cap.
+        # Whitelist just that one file — the cap still guards every other fixture.
+        exclude: ^tests/corpus/issues/82/Pictures And Decorations\.vi$
       - id: check-merge-conflict
       - id: mixed-line-ending
         args: ["--fix=lf"]

{lvkit-0.8.1 → lvkit-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: lvkit
-Version: 0.8.1
+Version: 0.8.2
 Summary: Understand and convert LabVIEW VIs to Python without a LabVIEW license
 Project-URL: Repository, https://github.com/pragmatest-dev/lvkit
 Project-URL: Issues, https://github.com/pragmatest-dev/lvkit/issues

{lvkit-0.8.1 → lvkit-0.8.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "lvkit"
-version = "0.8.1"
+version = "0.8.2"
 description = "Understand and convert LabVIEW VIs to Python without a LabVIEW license"
 readme = "README.md"
 requires-python = ">=3.10"

{lvkit-0.8.1 → lvkit-0.8.2}/src/lvkit/__init__.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-__version__ = "0.8.1"
+__version__ = "0.8.2"
 
 # The public API is exposed LAZILY (PEP 562 module ``__getattr__``): the graph /
 # parser / structure stacks (networkx, pydantic, pylabview, PIL — ~230 ms) load

{lvkit-0.8.1 → lvkit-0.8.2}/src/lvkit/graph/builders/operations.py

@@ -16,6 +16,7 @@ from typing import Any
 from lvkit.models import PropertyDef, Terminal
 from lvkit.parser.node_types import (
     CpdArithNode,
+    EventRegNode,
     InvokeNode,
     PropertyNode,
     SubVINode,
@@ -95,7 +96,7 @@ class PrimitiveBuildHandler(NodeBuildHandler):
             prim_kwargs["prim_index"] = node.prim_index
         if isinstance(node, CpdArithNode):
             prim_kwargs["operation"] = node.operation
-        if isinstance(node, (PropertyNode, InvokeNode)):
+        if isinstance(node, (PropertyNode, InvokeNode, EventRegNode)):
             prim_kwargs["object_name"] = node.object_name
             prim_kwargs["object_method_id"] = node.object_method_id
             if isinstance(node, PropertyNode):
@@ -106,12 +107,18 @@ class PrimitiveBuildHandler(NodeBuildHandler):
                 prim_kwargs["property_value_terminal_ids"] = [
                     ctx.qid(uid) for uid in node.dco_terminal_uids
                 ]
+                prim_kwargs["bound_control_uid"] = node.bound_control_uid
+                prim_kwargs["bound_control_type"] = node.bound_control_type
             elif isinstance(node, InvokeNode):
                 prim_kwargs["method_name"] = node.method_name
                 prim_kwargs["method_code"] = node.method_code
                 prim_kwargs["invoke_row_terminal_ids"] = [
                     ctx.qid(uid) for uid in node.row_terminal_uids
                 ]
+            elif isinstance(node, EventRegNode):
+                prim_kwargs["event_row_terminal_ids"] = [
+                    ctx.qid(uid) for uid in node.event_row_terminal_uids
+                ]
 
         return GraphPrimitiveNode(
             id=q_node_uid,

{lvkit-0.8.1 → lvkit-0.8.2}/src/lvkit/graph/construction.py

@@ -463,6 +463,7 @@ class ConstructionMixin:
                 raw_value=const.value,
                 label=const.label,
                 display_format=const.display_format,
+                collapsed=const.collapsed,
                 terminals=[const_terminal],
             )
             g.add_node(q_const_uid, node=const_node)

{lvkit-0.8.1 → lvkit-0.8.2}/src/lvkit/graph/core.py

@@ -13,7 +13,7 @@ from typing import TYPE_CHECKING
 import networkx as nx
 
 from ..load_mode import LoadMode
-from ..models import ClusterField, LVType, LVTypeKind
+from ..models import ClusterField, LVType, LVTypeKind, WireStyle
 from ..parser.models import ParsedType, ParsedVI
 
 if TYPE_CHECKING:
@@ -330,6 +330,13 @@ class InMemoryVIGraph(
         # Class/typedef fields: codegen queries dep_graph or vilib_resolver
         # by classname/typedef_name. No copies.
 
+        # A class instance carries its OWN wire style (color/width/line style),
+        # resolved from its .lvclass, so the one render lookup draws every class
+        # wire in the class's style with no graph — see LVType.wire_style /
+        # render.style.wire_style.
+        if parsed_type.classname:
+            lv_type.wire_style = self.get_class_wire_style(parsed_type.classname)
+
         return lv_type
 
     def _dep_key_for_ref(
@@ -431,6 +438,37 @@ class InMemoryVIGraph(
                 return parent_fields + own_fields
         return own_fields
 
+    def get_class_wire_style(
+        self,
+        classname: str,
+        caller_vi_key: str | None = None,
+    ) -> WireStyle | None:
+        """A class's own wire style, or None when it (and every ancestor) uses the
+        default/generic look.
+
+        ``classname`` is resolved to its PATH-key node via :meth:`_dep_key_for_ref`
+        (pass the CALLER VI key so a duplicated class name resolves by the
+        caller's edge). A class with no custom pen inherits its parent's (LabVIEW's
+        "use parent's/default design"), so the parent chain is walked by
+        ``parent_key`` (:meth:`_parent_class_key`) until a custom style is found.
+        """
+        node_key = self._dep_key_for_ref(classname, caller_vi_key)
+        if node_key is None or not self._dep_graph.has_node(node_key):
+            return None
+        return self._class_wire_style_by_key(node_key)
+
+    def _class_wire_style_by_key(self, node_key: str) -> WireStyle | None:
+        """This class's own wire style, else the nearest ancestor's — the
+        inherited case. Follows the parent's PATH key by IDENTITY
+        (:meth:`_parent_class_key`), same as :meth:`_class_fields_by_key`."""
+        style: WireStyle | None = self._dep_graph.nodes[node_key].get("wire_style")
+        if style is not None:
+            return style
+        parent_key = self._parent_class_key(node_key)
+        if parent_key is not None:
+            return self._class_wire_style_by_key(parent_key)
+        return None
+
     def get_type_fields(
         self,
         lv_type: LVType,

{lvkit-0.8.1 → lvkit-0.8.2}/src/lvkit/graph/loading.py

@@ -274,6 +274,9 @@ class LoadingMixin:
             iuse_to_qpath: dict[str, str] | None = None,
         ) -> None: ...
         def resolve_dispatch_qnames(self) -> None: ...
+        def _dep_key_for_ref(
+            self, ref: str, caller_vi_key: str | None = None
+        ) -> str | None: ...
 
     def load_vi(
         self,
@@ -718,6 +721,7 @@ class LoadingMixin:
             version=cls.version,
             ancestors=cls.ancestors,
             method_paths=method_paths,
+            wire_style=cls.wire_style,
         )
         self._register_dep_node(cls_key, cls_path_r, cls_name, cls_qname)
         self._stubs.discard(cls_key)
@@ -1588,6 +1592,19 @@ class LoadingMixin:
                     if caller_qname:
                         self._dep_graph.add_edge(caller_qname, found_key)
                     return
+            # Before stubbing: a SIBLING reference may already have resolved this
+            # same file by path (e.g. a type_map's BARE ``typedef_name`` —
+            # ``Parameters.ctl`` — duplicating the VICC-linked, path-resolved
+            # qualified ref ``…lvclass:Parameters.ctl``). Route this ref's edge
+            # onto that resolved node via the caller-scoped resolver instead of
+            # spawning a second, empty bare-name stub node beside it. Caller-
+            # scoped + unique-match (``_dep_key_for_ref``) so it can never point
+            # at a same-leaf file from a different library.
+            existing = self._dep_key_for_ref(qualified_name, caller_qname)
+            if existing is not None and existing not in self._stubs:
+                if caller_qname:
+                    self._dep_graph.add_edge(caller_qname, existing)
+                return
             node_type = (
                 "class"
                 if leaf.endswith(".lvclass")

{lvkit-0.8.1 → lvkit-0.8.2}/src/lvkit/graph/models.py

@@ -140,6 +140,13 @@ class PrimitiveNode(GraphNode):
     # rows 1..N = params [input, output]). Ids match ``terminals[i].id``.
     # See render/nodes.py:_invoke_node_glyph for how rows are built from this.
     invoke_row_terminal_ids: list[str] = []
+    # Register-For-Events node only (task #56): qualified terminal ids from
+    # the parser's dcoList, one per registered event source, in heap order
+    # -- each is a GROWABLE row's own INPUT terminal (the event source
+    # refnum to register on). Same dcoList convention as
+    # ``property_value_terminal_ids``/``invoke_row_terminal_ids``. See
+    # render/nodes.py:_event_reg_node_glyph.
+    event_row_terminal_ids: list[str] = []
     # Property node only: qualified terminal ids from the parser's dcoList,
     # ``properties[i]`` correlates to the terminal whose id is
     # ``property_value_terminal_ids[i]`` -- LabVIEW's real dcoList/permDCOList
@@ -151,6 +158,20 @@ class PrimitiveNode(GraphNode):
     # reference terminal, but this structural id list always can. See
     # ``op_walk.correlate_property_terminals``.
     property_value_terminal_ids: list[str] = []
+    # Property node only: the BOUND front-panel control's own ddo uid (RAW,
+    # unqualified -- not this node's own qualified id) when this property
+    # node is IMPLICIT (permanently tied to a specific control, e.g. GTR's
+    # "Abort" boolean property node) -- "" for an EXPLICIT one (identity from
+    # a wired reference). See ``parser.node_types.PropertyNode``'s class
+    # docstring for the full heap discriminator (a direct ``<ddo>`` child +
+    # a ``<label>`` naming the control, both absent when explicit).
+    bound_control_uid: str = ""
+    # The bound control's reconstructed LVType (``parser.fp_heap_type.
+    # reconstruct_control_lvtype``, resolved at PARSE time against the
+    # front-panel heap -- see ``parser.vi._resolve_property_node_bound_types``).
+    # None for an explicit node, or an implicit one whose control class isn't
+    # modeled by that reconstructor.
+    bound_control_type: LVType | None = None
 
 
 class StructureNode(GraphNode):
@@ -312,6 +333,10 @@ class ConstantNode(GraphNode):
     # (``ParsedConstant.display_format``, e.g. ``%.0x`` for hex), threaded
     # through unchanged — render/nodes.py is where it's interpreted.
     display_format: str | None = None
+    # True when this cluster/array constant is drawn COLLAPSED ("View As Icon",
+    # ``ParsedConstant.collapsed``): render shows a compact icon, not its
+    # members/elements (LabVIEW never shrinks a value's natural height).
+    collapsed: bool = False
 
 
 class LabelNode(GraphNode):

{lvkit-0.8.1 → lvkit-0.8.2}/src/lvkit/graph/op_walk.py

@@ -30,7 +30,7 @@ from ..models import (
     _is_error_cluster,
 )
 from ..num_format import format_numeric_const
-from ..parser.constants import NMUX_BY_NAME_NODE_CLASSES
+from ..parser.constants import NMUX_BY_NAME_NODE_CLASSES, NODE_CLASS_NMUX
 from ..structure import _fields_from_xml, private_data_field_to_cluster_field
 from ..vilib_resolver import get_resolver as _get_vilib_resolver
 from .models import Constant
@@ -125,26 +125,52 @@ def _own_class_private_data_fields(
     return [private_data_field_to_cluster_field(f) for f in fields]
 
 
+def _nmux_index_leaf_only(node_type: str | None, agg: Terminal | None) -> bool:
+    """How a node's flat ``<i>`` field index counts a NESTED cluster's fields.
+
+    FULL depth-first flatten (an intermediate sub-cluster is itself an
+    addressable slot) applies to exactly ONE case: a Bundle/Unbundle By Name
+    (``nMux``) over a plain typedef/cluster aggregate. Class private data —
+    accessed by ``nMux`` OR the IPES cluster border ``decomposeClusterNode`` —
+    and event data index LEAF fields only. Verified: ``nMux`` on
+    ``Parameters.ctl`` uses ``<i>``=40 for the whole ``PWM Config`` sub-cluster
+    (slot 40 of the full flatten; leaf-only has no such slot); ``nMux`` on a
+    class's own private data resolves ``pin_map_id`` (leaf); and a
+    ``decomposeClusterNode`` on ``Daqmx Module runtime`` private data uses
+    7/1/9/3 -> the leaf fields DI Index/AO Task/PWM Freq Index/DO Task. So the
+    private-data (``classname``-bearing) aggregate stays leaf even under
+    ``nMux``."""
+    if node_type != NODE_CLASS_NMUX:
+        return True
+    return not (
+        agg is not None
+        and agg.lv_type is not None
+        and agg.lv_type.classname is None
+    )
+
+
 def _resolve_nmux_field_name(
     field_index: int | None,
     *field_sources: list[ClusterField],
+    leaf_only: bool,
 ) -> str | None:
     """Resolve a field-index's LabVIEW field name, trying each of
     ``field_sources`` (in priority order) in turn — each row resolved
     independently, so one source can cover a row another source misses.
 
-    Each source is flattened LEAF-first (``_flatten_leaf_fields``):
-    LabVIEW's flat ``<i>`` index for a NESTED cluster (e.g. a class
-    private-data cluster whose own fields are themselves sub-clusters) runs
-    over leaves only — an intermediate sub-cluster is never itself an
-    addressable flat slot.
+    ``leaf_only`` picks how each source is flattened for a NESTED cluster (see
+    :func:`_nmux_index_leaf_only`): ``True`` counts LEAF fields only
+    (``_flatten_leaf_fields`` — IPES decompose / event data), ``False`` counts
+    every node depth-first so a whole sub-cluster is its own addressable slot
+    (``_flatten_fields`` — Bundle/Unbundle By Name).
     """
     if field_index is None:
         return None
+    flatten = _flatten_leaf_fields if leaf_only else _flatten_fields
     for fields in field_sources:
         if not fields:
             continue
-        flat = _flatten_leaf_fields(fields)
+        flat = flatten(fields)
         if 0 <= field_index < len(flat):
             name = flat[field_index][1].name
             if name:
@@ -152,6 +178,31 @@ def _resolve_nmux_field_name(
     return None
 
 
+def _resolve_nmux_field_path(
+    field_index: int | None,
+    *field_sources: list[ClusterField],
+    leaf_only: bool,
+) -> str | None:
+    """The full dotted navigation PATH to a NESTED field for a resolved nmux
+    index (e.g. ``Strain Config.strain gage information.poisson ratio``), or
+    None for a top-level field or when nothing resolves. Same flatten/source
+    order as :func:`_resolve_nmux_field_name` (which returns only the leaf) — the
+    flatten already carries the path per slot; this just keeps it for the
+    tooltip. Only a genuinely nested path (more than one segment) is returned."""
+    if field_index is None:
+        return None
+    flatten = _flatten_leaf_fields if leaf_only else _flatten_fields
+    for fields in field_sources:
+        if not fields:
+            continue
+        flat = flatten(fields)
+        if 0 <= field_index < len(flat):
+            path, field = flat[field_index]
+            if field.name and len(path) > 1:
+                return ".".join(path)
+    return None
+
+
 def _nmux_field_sources(
     vi_name: str,
     agg: Terminal | None,
@@ -183,13 +234,15 @@ def _nmux_lane_name(
     agg: Terminal | None,
     vi_name: str,
     graph: InMemoryVIGraph,
+    node_type: str | None,
 ) -> str | None:
     """THE canonical field-name resolution for an nMux/decompose LIST
     terminal, via ``term.nmux_field_index`` into the aggregate's field list
-    (``_nmux_field_sources``, then ``_resolve_nmux_field_name``). Returns
-    None when neither source resolves a name — callers keep their own
-    index/name fallback (a bracketed index or the terminal's own name is
-    display-only, never worth pinning onto ``display_name``)."""
+    (``_nmux_field_sources``, then ``_resolve_nmux_field_name`` — flattened per
+    ``node_type``, see :func:`_nmux_index_leaf_only`). Returns None when neither
+    source resolves a name — callers keep their own index/name fallback (a
+    bracketed index or the terminal's own name is display-only, never worth
+    pinning onto ``display_name``)."""
     # A MeasureData aggregate (waveform / digital data) has no VCTP fields — its
     # component names come from the built-in flavor table, keyed directly by the
     # drawer's field index (no leaf-flatten).
@@ -200,7 +253,17 @@ def _nmux_lane_name(
         if name:
             return name
     own_fields, dep_fields = _nmux_field_sources(vi_name, agg, graph)
-    return _resolve_nmux_field_name(term.nmux_field_index, own_fields, dep_fields)
+    leaf_only = _nmux_index_leaf_only(node_type, agg)
+    name = _resolve_nmux_field_name(
+        term.nmux_field_index, own_fields, dep_fields, leaf_only=leaf_only
+    )
+    if name is not None:
+        # Also keep the full dotted path (nested fields only) for the tooltip —
+        # the glyph shows the terse leaf ``name``.
+        term.field_path = _resolve_nmux_field_path(
+            term.nmux_field_index, own_fields, dep_fields, leaf_only=leaf_only
+        )
+    return name
 
 
 def stamp_nmux_lane_names(graph: InMemoryVIGraph) -> None:
@@ -242,7 +305,7 @@ def stamp_nmux_lane_names(graph: InMemoryVIGraph) -> None:
             for term in node.terminals:
                 if term.nmux_role != "list" or term.display_name is not None:
                     continue
-                name = _nmux_lane_name(term, agg, vi_name, graph)
+                name = _nmux_lane_name(term, agg, vi_name, graph, node.node_type)
                 if name:
                     term.display_name = name
 
@@ -356,6 +419,11 @@ def _format_ranges(ranges: list[SelectorRange], fmt: Callable[[int], str]) -> st
             parts.append(f"{fmt(r.start)}..")
         elif r.is_single:
             parts.append(fmt(r.start))
+        elif r.end == r.start + 1:
+            # Exactly two values — nothing lies between them to elide, so list
+            # both ("a, b"). ".." means the contiguous middle is skipped, which
+            # only applies to a span of three or more values.
+            parts.append(f"{fmt(r.start)}, {fmt(r.end)}")
         else:
             parts.append(f"{fmt(r.start)}..{fmt(r.end)}")
     return ", ".join(parts)

{lvkit-0.8.1 → lvkit-0.8.2}/src/lvkit/models.py

@@ -17,8 +17,8 @@ subclasses are the single source of truth for node structure.
 from __future__ import annotations
 
 import re
-from dataclasses import dataclass
-from enum import Enum
+from dataclasses import dataclass, field
+from enum import Enum, IntEnum
 from typing import Literal
 
 from pydantic import BaseModel
@@ -71,6 +71,12 @@ class LVType:
     # opaque built-in structures with no VCTP children, so their component names
     # come from a built-in table keyed by this flavor (see measure_data.py).
     measure_flavor: str | None = None
+    # This type's OWN wire style, when it has one — read by the one wire lookup
+    # (``render.style.wire_style``) so wire color/style is data-driven, not a
+    # fixed per-family table. None for a type that uses the family default (every
+    # built-in today); a LabVIEW class fills it from its ``.lvclass``.
+    # ``compare=False`` — presentation, never type identity/coercion.
+    wire_style: WireStyle | None = field(default=None, compare=False)
 
     def to_python(self) -> str:
         """Render as Python type annotation string."""
@@ -214,6 +220,43 @@ class LVType:
         return "?"
 
 
+class WireLineStyle(IntEnum):
+    """A wire pen's ``Style`` — Solid/Dash/Dot/DashDot/DashDotDot. ``SOLID`` is
+    the default and the only style built-in wires use; a LabVIEW class can pick
+    another in its ``.lvclass``. ``IntEnum`` so a member equals the raw 0–4 the
+    binary stores, drop-in."""
+
+    SOLID = 0
+    DASH = 1
+    DOT = 2
+    DASH_DOT = 3
+    DASH_DOT_DOT = 4
+
+
+@dataclass(frozen=True)
+class WireStyle:
+    """Everything a wire needs to draw itself — the ONE style object the ONE wire
+    lookup (``render.style.wire_style``) returns and every drawing site renders.
+    A type's OWN style (``LVType.wire_style``) overrides the default per-family
+    color/width there; most types have none (the lookup derives theirs from the
+    family), but a LabVIEW class carries one decoded from its ``.lvclass``.
+
+    ``color``/``width``/``line_style`` describe a flat wire. ``edge_color`` +
+    ``core_width`` add the class two-band look — an outer ``edge_color`` band at
+    ``width`` with a ``color`` center of ``core_width`` on top; both None for a
+    flat wire (``width`` is then the single stroke). New wire styles (e.g. a fill
+    pattern) are added HERE, once, and every site renders them."""
+
+    color: str
+    width: float
+    line_style: WireLineStyle = WireLineStyle.SOLID
+    edge_color: str | None = None
+    core_width: float | None = None
+    # The pen's 8-row fill-pattern bitmap (one byte per row). Non-empty => the
+    # class wire is patterned (drawn as a chain) rather than solid; () => solid.
+    fill_pattern: tuple[int, ...] = ()
+
+
 @dataclass
 class EnumValue:
     """A single value in an enum typedef."""
@@ -322,6 +365,11 @@ class Terminal(BaseModel):
     # this must never change generated code. Used by the renderer's connector-
     # pane hover / tooltip and by describe. See graph/construction.py.
     display_name: str | None = None
+    # Full dotted navigation path to a NESTED Bundle/Unbundle-By-Name field
+    # (e.g. "Strain Config.strain gage information.poisson ratio") — tooltip-only
+    # detail beside the terse leaf ``display_name`` the glyph shows. None for a
+    # top-level or leaf-only field. Set at the ``stamp_nmux_lane_names`` seam.
+    field_path: str | None = None
     lv_type: LVType | None = None
     var_name: str | None = None  # set during codegen
     nmux_role: str | None = None  # "agg" or "list"

{lvkit-0.8.1 → lvkit-0.8.2}/src/lvkit/parser/constants.py

@@ -33,6 +33,7 @@ NODE_CLASS_FEEDBACK_MASTER = "hiddenFBNode"
 NODE_CLASS_FEEDBACK_SLAVE = "slaveFBInputNode"
 NODE_CLASS_PROP_NODE = "propNode"
 NODE_CLASS_INVOKE_NODE = "invokeNode"
+NODE_CLASS_EVENT_REG = "eventRegNode"  # Register For Events (task #56)
 NODE_CLASS_CPD_ARITH = "cpdArith"  # Compound arithmetic (e.g., Or of multiple booleans)
 NODE_CLASS_ARRAY_BUILD = "aBuild"  # Array builder node
 NODE_CLASS_ARRAY_INIT = "aInit"  # Initialize Array (element + sizes -> array)
@@ -103,6 +104,7 @@ OPERATION_NODE_CLASSES = (
     NODE_CLASS_EVENT_STRUCT,
     NODE_CLASS_PROP_NODE,
     NODE_CLASS_INVOKE_NODE,
+    NODE_CLASS_EVENT_REG,
     NODE_CLASS_CPD_ARITH,
     NODE_CLASS_ARRAY_BUILD,
     NODE_CLASS_ARRAY_INIT,

lvkit-0.8.2/src/lvkit/parser/image_resources.py

@@ -0,0 +1,103 @@
+"""Embedded-picture / decoration resource resolution — LabVIEW's PICC
+(picture) and DSIM (dynamic-size image) resource sections.
+
+A heap element's ``<ImageResID>`` (when positive) or ``<ImageInternalsResID>``
+names one of these sections by index. The VI's top-level ``<stem>.xml`` (the
+sibling of ``<stem>_BDHb.xml`` extracted by pylabview) records the index -> file
+mapping::
+
+    <PICC><Section Index="2" File="..._PICC2.bin"/><Section Index="3" .../></PICC>
+    <DSIM><Section Index="4" File="..._DSIM.bin"/></DSIM>
+
+This module resolves that map (``resource_sections``/``resources_for_heap``),
+carves the embedded PNG out of a DSIM section's raw bytes (``carve_png``), and
+decodes a PICC section's absolute endpoint list (``decode_picc_points``). See
+``docs/_internal/design/labview-binary-format.md`` for the verified byte layout
+of both sections (issue #82).
+"""
+
+from __future__ import annotations
+
+import struct
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+Point = tuple[float, float]
+
+_PNG_SIGNATURE = b"\x89PNG\r\n\x1a\n"
+
+# The two resource-section kinds a decoration's ImageResID/ImageInternalsResID
+# can name — a picture (DSIM) or a picture-internals blob (PICC). Any other
+# top-level block in the VI's resource XML is unrelated and ignored.
+_SECTION_BLOCKS = ("PICC", "DSIM")
+
+
+def resource_sections(main_xml: Path) -> dict[int, Path]:
+    """Section Index -> resource file, from a VI's top-level ``<stem>.xml``.
+
+    Missing file or malformed XML -> ``{}`` (no resources), never a crash --
+    most VIs have no picture/decoration content at all.
+    """
+    try:
+        root = ET.parse(main_xml).getroot()
+    except (OSError, ET.ParseError):
+        return {}
+    sections: dict[int, Path] = {}
+    for block_tag in _SECTION_BLOCKS:
+        block = root.find(block_tag)
+        if block is None:
+            continue
+        for sec in block.findall("Section"):
+            idx, file_name = sec.get("Index"), sec.get("File")
+            if idx is None or not file_name:
+                continue
+            try:
+                sections[int(idx)] = main_xml.parent / file_name
+            except ValueError:
+                continue
+    return sections
+
+
+def resources_for_heap(bd_xml: Path) -> dict[int, Path]:
+    """The resource-section map for a ``_BDHb.xml`` heap path's sibling
+    ``<stem>.xml`` (same naming convention as ``layout._icon_for_heap``): ``{}``
+    when that file doesn't exist (the common case)."""
+    main_xml = bd_xml.parent / f"{bd_xml.stem.replace('_BDHb', '')}.xml"
+    return resource_sections(main_xml) if main_xml.exists() else {}
+
+
+def carve_png(data: bytes) -> bytes | None:
+    """The first embedded PNG in a DSIM section's raw bytes, or ``None``.
+
+    A DSIM section stores the picture behind a small binary preamble (size/
+    scaling fields LabVIEW itself uses) — the PNG payload starts at its own
+    signature and ends at the first ``IEND`` chunk's CRC (+8 bytes past the
+    ``IEND`` tag). Verified on the issue #82 repro: the PNG at offset 46,
+    sliced through ``IEND``, reproduces the embedded picture exactly."""
+    start = data.find(_PNG_SIGNATURE)
+    if start < 0:
+        return None
+    iend = data.find(b"IEND", start)
+    if iend < 0:
+        return None
+    return data[start : iend + 8]
+
+
+def decode_picc_points(data: bytes) -> list[Point]:
+    """Absolute ``(x, y)`` endpoints from a PICC section's raw bytes.
+
+    Layout (verified on the issue #82 repro's PICC2/PICC3): a 4-byte header
+    (purpose not yet decoded — see labview-binary-format.md) followed by
+    ``(len(data) - 4) / 4`` points, each two big-endian signed int16 in
+    ``(y, x)`` order. These are the SAME absolute LabVIEW-pixel frame as a heap
+    element's own ``<bounds>`` — callers apply the identical walk offset.
+    Malformed data (not a whole number of points after the header) -> ``[]``.
+    """
+    body = data[4:]
+    if len(body) < 4 or len(body) % 4 != 0:
+        return []
+    points: list[Point] = []
+    for i in range(0, len(body), 4):
+        y, x = struct.unpack_from(">hh", body, i)
+        points.append((float(x), float(y)))
+    return points