wodson 1.0.0__py3-none-any.whl

wodson/__init__.py

@@ -0,0 +1,3 @@
+"""wodson — ASAM ODS tools collection. Use ``wodson.atfx`` for the ATFX reader API."""
+
+__version__ = "1.0.0"

wodson/_cli.py

@@ -0,0 +1,36 @@
+"""Top-level command-line interface for wodson.
+
+Usage::
+
+    uv run wodson atfx serve
+    uv run wodson atfx serve --file path/to/file.atfx
+    uv run wodson atfx serve --file path/to/file.atfx --host 0.0.0.0 --port 8080
+"""
+
+from __future__ import annotations
+
+import argparse
+
+import wodson.atfx._cli as _atfx_cli
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="wodson",
+        description="wodson ASAM ODS command-line tools.",
+    )
+    sub = parser.add_subparsers(dest="module", required=True)
+    _atfx_cli.register_atfx_subparser(sub)
+    return parser
+
+
+def main() -> None:
+    """Entry point for the ``wodson`` CLI command."""
+    parser = _build_parser()
+    args = parser.parse_args()
+    if args.module == "atfx":
+        _atfx_cli.dispatch(args)
+
+
+if __name__ == "__main__":
+    main()

wodson/atfx/__init__.py

@@ -0,0 +1,7 @@
+"""wodson.atfx — ATFX reader with in-memory SQLite backend and ODS data-read API."""
+
+from ._atfx_store import AtfxStore
+from ._server import CONTEXT_VAR_ATFX_FILE, AtfxServer
+from ._session import AtfxSession
+
+__all__ = ["AtfxServer", "AtfxSession", "AtfxStore", "CONTEXT_VAR_ATFX_FILE"]

wodson/atfx/_atfx_store.py

@@ -0,0 +1,142 @@
+"""AtfxStore: main public class for loading and querying ATFX files."""
+
+from __future__ import annotations
+
+import logging
+import sqlite3
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+import odsbox.proto.ods_pb2 as ods
+
+from ._base_model import load_base_model
+from ._data_read import data_read
+from ._db import create_schema, load_instances
+from ._instance_parser import parse_instances, resolve_external_component_refs
+from ._model_builder import build_model, detect_ods_version
+from ._xml_utils import _find, _findall, _text
+
+_log = logging.getLogger(__name__)
+
+
+class AtfxStore:
+    """Load an ATFX file into an in-memory SQLite database and provide ODS API access.
+
+    Usage::
+
+        store = AtfxStore("path/to/file.atfx")
+        model = store.model()
+        result = store.data_read(select_statement)
+    """
+
+    def __init__(self, file_path: str | Path, base_model_path: Path | None = None) -> None:
+        """Initialize the store by parsing and loading the ATFX file.
+
+        Args:
+            file_path: Path to the .atfx file.
+            base_model_path: Optional path to the base model JSON. Defaults to shipped version.
+        """
+        self._file_path = Path(file_path).resolve()
+        self._atfx_dir = self._file_path.parent
+        _log.info("Loading ATFX file: %s", self._file_path)
+
+        # Parse XML
+        tree = ET.parse(self._file_path)  # noqa: S314
+        root = tree.getroot()
+        _log.debug("XML parsed successfully")
+
+        # Extract version metadata from the XML
+        self._ods_version: str = detect_ods_version(root)
+        self._base_model_version: str = _text(root, "base_model_version")
+        _log.debug(
+            "ODS version: %s, base model version: %s",
+            self._ods_version or "(not detected)",
+            self._base_model_version or "(not set)",
+        )
+
+        # Load base model
+        self._base_model = load_base_model(base_model_path)
+
+        # Build application model
+        self._model = build_model(root, self._base_model)
+
+        # Parse file map from <files> section
+        self._file_map = self._parse_file_map(root)
+        if self._file_map:
+            _log.debug("%d external file(s) mapped", len(self._file_map))
+
+        # Parse instances
+        instances = parse_instances(root, self._model)
+
+        # Resolve AoExternalComponent references (third value-reference pattern)
+        resolve_external_component_refs(self._model, instances, self._file_map, self._atfx_dir)
+
+        # Create in-memory SQLite DB
+        self._conn = sqlite3.connect(":memory:", check_same_thread=False)
+        create_schema(self._conn, self._model)
+        load_instances(self._conn, self._model, instances, self._file_map)
+        _log.info(
+            "AtfxStore ready: %d entities, %d instance groups",
+            len(self._model.entities),
+            len(instances),
+        )
+
+    def model(self) -> ods.Model:
+        """Return the application model as an ods.Model protobuf."""
+        return self._model
+
+    def data_read(self, select_statement: ods.SelectStatement) -> ods.DataMatrices:
+        """Execute a SelectStatement and return DataMatrices.
+
+        This matches the ASAM ODS HTTP API data-read method semantics.
+
+        Args:
+            select_statement: The ODS SelectStatement protobuf.
+
+        Returns:
+            ods.DataMatrices containing the query results.
+        """
+        return data_read(self._conn, self._model, select_statement)
+
+    def context_read(self) -> ods.ContextVariables:
+        """Return context variables for this ATFX session.
+
+        Populated variables:
+
+        * ``ASAM-ODS-VERSION`` -- ODS schema version extracted from the XML
+          namespace, e.g. ``"6.1.0"``.
+        * ``BASE-MODEL-VERSION`` -- value of ``<base_model_version>`` in the
+          ATFX file, e.g. ``"asam35"``.
+        """
+        ctx = ods.ContextVariables()
+        if self._ods_version:
+            ctx.variables["ASAM-ODS-VERSION"].string_array.values.append(self._ods_version)
+        if self._base_model_version:
+            ctx.variables["BASE-MODEL-VERSION"].string_array.values.append(self._base_model_version)
+        return ctx
+
+    def close(self) -> None:
+        """Close the SQLite connection."""
+        _log.debug("Closing AtfxStore for %s", self._file_path)
+        self._conn.close()
+
+    def __enter__(self) -> AtfxStore:
+        return self
+
+    def __exit__(self, *_args: object) -> None:
+        self.close()
+
+    def _parse_file_map(self, root: ET.Element) -> dict[str, Path]:
+        """Parse the <files> section to build identifier -> file path mapping."""
+        file_map: dict[str, Path] = {}
+        files_el = _find(root, "files")
+        if files_el is None:
+            return file_map
+
+        for comp_el in _findall(files_el, "component"):
+            identifier = _text(comp_el, "identifier")
+            filename = _text(comp_el, "filename")
+            if identifier and filename:
+                file_map[identifier] = self._atfx_dir / filename
+
+        return file_map

wodson/atfx/_base_model.py

@@ -0,0 +1,155 @@
+"""Load the ASAM ODS base model from the shipped JSON file."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+import odsbox.proto.ods_pb2 as ods
+
+_log = logging.getLogger(__name__)
+
+_BASE_MODEL_PATH = Path(__file__).resolve().parent / "base_model" / "ODSBaseModel_asam37.protobuf.json"
+
+
+def load_base_model(path: Path | None = None) -> ods.BaseModel:
+    """Load the ODS base model from a JSON file.
+
+    The JSON structure mirrors the protobuf BaseModel message layout
+    but uses a slightly different naming convention, so we manually
+    parse rather than using ParseDict.
+    """
+    json_path = path if path is not None else _BASE_MODEL_PATH
+    _log.debug("Loading base model from %s", json_path)
+    with open(json_path, encoding="utf-8") as f:
+        data: dict[str, object] = json.load(f)
+
+    base_model = ods.BaseModel()
+    base_model.version = str(data.get("version", ""))
+
+    # Enumerations
+    enums_data = data.get("enumerations")
+    if isinstance(enums_data, dict):
+        for enum_name, enum_obj in enums_data.items():
+            if not isinstance(enum_obj, dict):
+                continue
+            enum_entry = base_model.enumerations[enum_name]
+            enum_entry.name = str(enum_obj.get("name", enum_name))
+            items = enum_obj.get("items")
+            if isinstance(items, dict):
+                for item_name, item_value in items.items():
+                    enum_entry.items[item_name] = int(item_value)
+
+    # Entities
+    entities_data = data.get("entities")
+    if isinstance(entities_data, dict):
+        for entity_name, entity_obj in entities_data.items():
+            if not isinstance(entity_obj, dict):
+                continue
+            entity = base_model.entities[entity_name]
+            entity.name = str(entity_obj.get("name", entity_name))
+            entity.bid = int(entity_obj.get("bid", 0))
+
+            derivation_str = str(entity_obj.get("derivation", "DV_UNRESTRICTED"))
+            derivation_map: dict[str, int] = {
+                "DV_UNRESTRICTED": 0,
+                "DV_SINGLE": 1,
+                "DV_TREE_AT_INSTANCE": 2,
+                "DV_TREE_AT_MODEL": 3,
+            }
+            entity.derivation = derivation_map.get(derivation_str, 0)  # type: ignore[assignment]
+
+            # Attributes
+            attrs_data = entity_obj.get("attributes")
+            if isinstance(attrs_data, dict):
+                for attr_name, attr_obj in attrs_data.items():
+                    if not isinstance(attr_obj, dict):
+                        continue
+                    attr = entity.attributes[attr_name]
+                    attr.name = str(attr_obj.get("name", attr_name))
+                    attr.data_type = _parse_datatype(  # type: ignore[assignment]
+                        str(attr_obj.get("dataType", "DT_UNKNOWN"))
+                    )
+                    attr.mandatory = bool(attr_obj.get("mandatory", False))
+                    attr.obligatory = bool(attr_obj.get("obligatory", False))
+                    attr.autogenerated = bool(attr_obj.get("autogenerated", False))
+                    attr.enumeration = str(attr_obj.get("enumeration", ""))
+
+            # Relations
+            rels_data = entity_obj.get("relations")
+            if isinstance(rels_data, dict):
+                for rel_name, rel_obj in rels_data.items():
+                    if not isinstance(rel_obj, dict):
+                        continue
+                    rel = entity.relations[rel_name]
+                    rel.name = str(rel_obj.get("name", rel_name))
+                    rel.inverse_name = str(rel_obj.get("inverseName", ""))
+                    entity_names = rel_obj.get("entityNames")
+                    if isinstance(entity_names, list) and len(entity_names) > 0:
+                        rel.entity_names.extend([str(n) for n in entity_names])
+                    rel.range_min = int(rel_obj.get("rangeMin", 0))
+                    rel.range_max = int(rel_obj.get("rangeMax", -1))
+                    rel.mandatory = bool(rel_obj.get("mandatory", False))
+                    rel.inverse_range_min = int(rel_obj.get("inverseRangeMin", 0))
+                    rel.inverse_range_max = int(rel_obj.get("inverseRangeMax", -1))
+
+                    relationship_str = str(rel_obj.get("relationship", "RS_INFO_TO"))
+                    relationship_map: dict[str, int] = {
+                        "RS_FATHER": 0,
+                        "RS_CHILD": 1,
+                        "RS_INFO_TO": 2,
+                        "RS_INFO_FROM": 3,
+                        "RS_INFO_REL": 4,
+                        "RS_SUPERTYPE": 5,
+                        "RS_SUBTYPE": 6,
+                        "RS_ALL_REL": 7,
+                    }
+                    rel.relationship = relationship_map.get(relationship_str, 2)  # type: ignore[assignment]
+
+                    relation_type_str = str(rel_obj.get("relationType", "RT_INFO"))
+                    relation_type_map: dict[str, int] = {
+                        "RT_FATHER_CHILD": 0,
+                        "RT_INFO": 1,
+                        "RT_INHERITANCE": 2,
+                    }
+                    rel.relation_type = relation_type_map.get(relation_type_str, 1)  # type: ignore[assignment]
+
+    return base_model
+
+
+def _parse_datatype(dt_str: str) -> int:
+    """Map datatype string to ods.DataTypeEnum int value."""
+    mapping: dict[str, int] = {
+        "DT_UNKNOWN": 0,
+        "DT_STRING": 1,
+        "DT_SHORT": 2,
+        "DT_FLOAT": 3,
+        "DT_BOOLEAN": 4,
+        "DT_BYTE": 5,
+        "DT_LONG": 6,
+        "DT_DOUBLE": 7,
+        "DT_LONGLONG": 8,
+        "DT_DATE": 10,
+        "DT_BYTESTR": 11,
+        "DT_BLOB": 12,
+        "DT_COMPLEX": 13,
+        "DT_DCOMPLEX": 14,
+        "DS_STRING": 15,
+        "DS_SHORT": 16,
+        "DS_FLOAT": 17,
+        "DS_BOOLEAN": 18,
+        "DS_BYTE": 19,
+        "DS_LONG": 20,
+        "DS_DOUBLE": 21,
+        "DS_LONGLONG": 22,
+        "DS_COMPLEX": 23,
+        "DS_DCOMPLEX": 24,
+        "DS_DATE": 26,
+        "DS_BYTESTR": 27,
+        "DT_EXTERNALREFERENCE": 28,
+        "DS_EXTERNALREFERENCE": 29,
+        "DT_ENUM": 30,
+        "DS_ENUM": 31,
+    }
+    return mapping.get(dt_str, 0)

wodson/atfx/_binary_reader.py

@@ -0,0 +1,311 @@
+"""Read external binary .dat files referenced by ATFX local columns."""
+
+from __future__ import annotations
+
+import logging
+import struct
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import odsbox.proto.ods_pb2 as ods
+from numpy.typing import NDArray
+
+from ._instance_parser import ExternalComponentRef, TypedValues
+
+_log = logging.getLogger(__name__)
+
+# Mapping: typespec_enum string -> (numpy dtype, element_size_bytes)
+_TYPESPEC_MAP: dict[str, tuple[str, int]] = {
+    "dt_boolean": ("|b1", 1),
+    "dt_byte": ("|u1", 1),
+    "dt_sbyte": ("|i1", 1),
+    "dt_short": ("<i2", 2),
+    "dt_long": ("<i4", 4),
+    "dt_longlong": ("<i8", 8),
+    "ieeefloat4": ("<f4", 4),
+    "ieeefloat8": ("<f8", 8),
+    "dt_short_beo": (">i2", 2),
+    "dt_long_beo": (">i4", 4),
+    "dt_longlong_beo": (">i8", 8),
+    "ieeefloat4_beo": (">f4", 4),
+    "ieeefloat8_beo": (">f8", 8),
+    "dt_ushort": ("<u2", 2),
+    "dt_ushort_beo": (">u2", 2),
+    "dt_ulong": ("<u4", 4),
+    "dt_ulong_beo": (">u4", 4),
+    "dt_string": ("|S1", 1),
+    "dt_string_utf8": ("|S1", 1),
+    "dt_bytestr_leo": ("|u1", 1),
+    "dt_bytestr_beo": ("|u1", 1),
+    # Bit types — raw-byte fallback; use _read_bit_values for actual decoding
+    "dt_bit_int": ("|u1", 1),
+    "dt_bit_int_beo": ("|u1", 1),
+    "dt_bit_uint": ("|u1", 1),
+    "dt_bit_uint_beo": ("|u1", 1),
+    "dt_bit_ieeefloat": ("|u1", 1),
+    "dt_bit_ieeefloat_beo": ("|u1", 1),
+}
+
+# Mapping: typespec_enum string -> ODS DataTypeEnum (for DT_UNKNOWN columns)
+_TYPESPEC_TO_ODS_DT: dict[str, int] = {
+    "dt_boolean": ods.DataTypeEnum.DT_BOOLEAN,
+    "dt_byte": ods.DataTypeEnum.DT_BYTE,
+    # dt_sbyte: ASAM ODS has no signed-byte type; promote to DT_SHORT
+    "dt_sbyte": ods.DataTypeEnum.DT_SHORT,
+    "dt_short": ods.DataTypeEnum.DT_SHORT,
+    "dt_long": ods.DataTypeEnum.DT_LONG,
+    "dt_longlong": ods.DataTypeEnum.DT_LONGLONG,
+    "ieeefloat4": ods.DataTypeEnum.DT_FLOAT,
+    "ieeefloat8": ods.DataTypeEnum.DT_DOUBLE,
+    "dt_short_beo": ods.DataTypeEnum.DT_SHORT,
+    "dt_long_beo": ods.DataTypeEnum.DT_LONG,
+    "dt_longlong_beo": ods.DataTypeEnum.DT_LONGLONG,
+    "ieeefloat4_beo": ods.DataTypeEnum.DT_FLOAT,
+    "ieeefloat8_beo": ods.DataTypeEnum.DT_DOUBLE,
+    # Unsigned types: promote to signed type that can hold the full value range
+    "dt_ushort": ods.DataTypeEnum.DT_LONG,
+    "dt_ushort_beo": ods.DataTypeEnum.DT_LONG,
+    "dt_ulong": ods.DataTypeEnum.DT_LONGLONG,
+    "dt_ulong_beo": ods.DataTypeEnum.DT_LONGLONG,
+    "dt_string": ods.DataTypeEnum.DT_STRING,
+    "dt_string_utf8": ods.DataTypeEnum.DT_STRING,
+    "dt_bytestr_leo": ods.DataTypeEnum.DT_BYTESTR,
+    "dt_bytestr_beo": ods.DataTypeEnum.DT_BYTESTR,
+    # Bit types are resolved dynamically from bitcount — DT_UNKNOWN is the fallback
+}
+
+# Typespecs that require bit-level extraction
+_BIT_TYPESPECS: frozenset[str] = frozenset(
+    {
+        "dt_bit_int",
+        "dt_bit_int_beo",
+        "dt_bit_uint",
+        "dt_bit_uint_beo",
+        "dt_bit_ieeefloat",
+        "dt_bit_ieeefloat_beo",
+    }
+)
+
+# Typespecs that require specialized string/bytestr parsing
+_STRING_TYPESPECS: frozenset[str] = frozenset({"dt_string", "dt_string_utf8"})
+_BYTESTR_TYPESPECS: frozenset[str] = frozenset({"dt_bytestr_leo", "dt_bytestr_beo"})
+
+
+def _bit_ods_dt(typespec: str, bitcount: int) -> int:
+    """Return the ODS DataTypeEnum for a bit-extraction typespec given its bitcount."""
+    if "ieeefloat" in typespec:
+        return ods.DataTypeEnum.DT_FLOAT if bitcount <= 32 else ods.DataTypeEnum.DT_DOUBLE
+    elif "uint" in typespec:
+        if bitcount <= 8:
+            return ods.DataTypeEnum.DT_BYTE
+        elif bitcount <= 16:
+            return ods.DataTypeEnum.DT_SHORT
+        elif bitcount <= 32:
+            return ods.DataTypeEnum.DT_LONG
+        else:
+            return ods.DataTypeEnum.DT_LONGLONG
+    else:  # signed int
+        if bitcount <= 16:
+            return ods.DataTypeEnum.DT_SHORT
+        elif bitcount <= 32:
+            return ods.DataTypeEnum.DT_LONG
+        else:
+            return ods.DataTypeEnum.DT_LONGLONG
+
+
+def _read_bit_values(
+    data: bytes,
+    ref: ExternalComponentRef,
+    signed: bool,
+    is_float: bool,
+    big_endian: bool,
+) -> list[Any]:
+    """Extract bit-field values from a binary buffer.
+
+    Supports LE/BE, signed/unsigned integers, and IEEE floats of arbitrary
+    bit-width packed at a given bit offset within multi-byte blocks.
+    """
+    count = ref.length
+    bitcount = ref.bitcount
+    bitoffset = ref.bitoffset
+    blocksize = ref.blocksize if ref.blocksize > 0 else (bitoffset + bitcount + 7) // 8
+    valperblock = ref.valperblock if ref.valperblock > 0 else 1
+    inioffset = ref.inioffset
+    byte_offset_in_block = ref.valoffsets[0] if ref.valoffsets else 0
+    mask = (1 << bitcount) - 1
+
+    results: list[Any] = []
+    remaining = count
+    block_num = 0
+
+    while remaining > 0:
+        n = min(valperblock, remaining)
+        block_start = inioffset + block_num * blocksize
+        block = data[block_start : block_start + blocksize]
+
+        for j in range(n):
+            # Absolute bit address within block
+            bit_addr = byte_offset_in_block * 8 + bitoffset + j * bitcount
+            byte_addr = bit_addr // 8
+            local_bit = bit_addr % 8
+            word_bytes_needed = (local_bit + bitcount + 7) // 8
+            word = block[byte_addr : byte_addr + word_bytes_needed]
+
+            if big_endian:
+                # BEO stores bytes in big-endian order; reverse to LE then
+                # apply the same LSB-first bit extraction as the LE case.
+                word = word[::-1]
+            word_int = int.from_bytes(word, "little")
+            value_bits = (word_int >> local_bit) & mask
+
+            if is_float:
+                if bitcount == 32:
+                    (value,) = struct.unpack("f", struct.pack("I", value_bits))
+                elif bitcount == 64:
+                    (value,) = struct.unpack("d", struct.pack("Q", value_bits))
+                else:
+                    value = float(value_bits)
+            elif signed:
+                value = value_bits - (1 << bitcount) if value_bits & (1 << (bitcount - 1)) else value_bits
+            else:
+                value = value_bits
+
+            results.append(value)
+
+        remaining -= n
+        block_num += 1
+
+    return results
+
+
+def _read_null_terminated_strings(data: bytes, offset: int, total_bytes: int) -> list[str]:
+    """Parse null-terminated strings packed sequentially in a byte buffer."""
+    segment = data[offset : offset + total_bytes]
+    results: list[str] = []
+    start = 0
+    while start < len(segment):
+        end = segment.find(b"\x00", start)
+        if end == -1:
+            s = segment[start:].decode("utf-8", errors="replace").rstrip("\x00")
+            if s:
+                results.append(s)
+            break
+        results.append(segment[start:end].decode("utf-8", errors="replace"))
+        start = end + 1
+    return results
+
+
+def _read_bytestr_sequence(data: bytes, offset: int, total_bytes: int, big_endian: bool) -> list[bytes]:
+    """Parse length-prefixed (4-byte) byte strings packed in a byte buffer."""
+    fmt = ">I" if big_endian else "<I"
+    segment = data[offset : offset + total_bytes]
+    results: list[bytes] = []
+    pos = 0
+    while pos + 4 <= len(segment):
+        (length,) = struct.unpack_from(fmt, segment, pos)
+        pos += 4
+        results.append(segment[pos : pos + length])
+        pos += length
+    return results
+
+
+def read_external_component_typed(ref: ExternalComponentRef, file_map: dict[str, Path]) -> TypedValues:
+    """Read binary values and return them with the corresponding ODS DataTypeEnum.
+
+    Handles string and bytestr types that require specialized parsing,
+    in addition to all numeric/boolean types.
+    """
+    typespec = ref.datatype.lower()
+    ods_dt = _TYPESPEC_TO_ODS_DT.get(typespec, ods.DataTypeEnum.DT_UNKNOWN)
+
+    file_path = file_map.get(ref.identifier)
+    if file_path is None:
+        msg = f"External component identifier '{ref.identifier}' not found in file map"
+        raise FileNotFoundError(msg)
+
+    _log.debug(
+        "Reading external component %s (typespec=%s, length=%d)",
+        ref.identifier,
+        typespec,
+        ref.length,
+    )
+    data = file_path.read_bytes()
+
+    if typespec in _BIT_TYPESPECS:
+        is_float = "ieeefloat" in typespec
+        signed = not ("uint" in typespec or is_float)
+        big_endian = typespec.endswith("_beo")
+        ods_dt = _bit_ods_dt(typespec, ref.bitcount)
+        values = _read_bit_values(data, ref, signed, is_float, big_endian)
+        return TypedValues(ods_dt, values)
+
+    if typespec in _STRING_TYPESPECS:
+        strings = _read_null_terminated_strings(data, ref.inioffset, ref.length)
+        return TypedValues(ods_dt, strings)
+
+    if typespec in _BYTESTR_TYPESPECS:
+        big_endian = typespec == "dt_bytestr_beo"
+        bytestrings = _read_bytestr_sequence(data, ref.inioffset, ref.length, big_endian)
+        return TypedValues(ods_dt, bytestrings)
+
+    # Numeric / boolean: use numpy reader
+    arr = read_external_component(ref, file_map)
+    return TypedValues(ods_dt, arr.tolist())
+
+
+def read_external_component(ref: ExternalComponentRef, file_map: dict[str, Path]) -> NDArray[Any]:
+    """Read binary values from an external file using the component reference.
+
+    Args:
+        ref: The external component reference with offset/size metadata.
+        file_map: Mapping from component identifier to resolved file path.
+
+    Returns:
+        Numpy array of decoded values.
+    """
+    file_path = file_map.get(ref.identifier)
+    if file_path is None:
+        msg = f"External component identifier '{ref.identifier}' not found in file map"
+        raise FileNotFoundError(msg)
+
+    typespec = ref.datatype.lower()
+    if typespec not in _TYPESPEC_MAP:
+        # Fallback: read raw bytes
+        dtype_str, elem_size = "|u1", 1
+    else:
+        dtype_str, elem_size = _TYPESPEC_MAP[typespec]
+    dtype = np.dtype(dtype_str)
+
+    count = ref.length
+    if count <= 0:
+        return np.array([], dtype=dtype)
+
+    data = file_path.read_bytes()
+
+    blocksize = ref.blocksize if ref.blocksize > 0 else elem_size
+    valperblock = ref.valperblock if ref.valperblock > 0 else 1
+    inioffset = ref.inioffset
+    valoffset = ref.valoffsets[0] if ref.valoffsets else 0
+
+    if blocksize == elem_size and valperblock == 1 and valoffset == 0:
+        # Simple contiguous case: values packed sequentially from inioffset
+        start = inioffset
+        end = start + count * elem_size
+        return np.frombuffer(data[start:end], dtype=dtype, count=count)
+
+    # General case: values interleaved in blocks
+    values: list[Any] = []
+    offset = inioffset
+    remaining = count
+    while remaining > 0:
+        n = min(valperblock, remaining)
+        for i in range(n):
+            val_start = offset + valoffset + i * elem_size
+            val_end = val_start + elem_size
+            val = np.frombuffer(data[val_start:val_end], dtype=dtype, count=1)[0]
+            values.append(val)
+        remaining -= n
+        offset += blocksize
+
+    return np.array(values, dtype=dtype)