vcti-array-display 1.1.0__py3-none-any.whl

vcti/arraydisplay/__init__.py

@@ -0,0 +1,19 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""vcti.arraydisplay — Presentation layer for NumPy structured arrays."""
+
+from importlib.metadata import version
+
+from ._exclusion import FILLER_COLUMNS, LENGTH_COLUMNS, VOID_COLUMNS, ColumnExclusion
+from .array_display import ArrayDisplay
+
+__version__ = version("vcti-array-display")
+
+__all__ = [
+    "__version__",
+    "ArrayDisplay",
+    "ColumnExclusion",
+    "FILLER_COLUMNS",
+    "LENGTH_COLUMNS",
+    "VOID_COLUMNS",
+]

vcti/arraydisplay/_exclusion.py

@@ -0,0 +1,60 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Column exclusion rules and pre-built patterns.
+
+Provides the generic exclusion mechanism used by ArrayDisplay to filter
+columns by name, regex, or a callable predicate that receives both the
+column name and its dtype.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable, Sequence
+
+import numpy as np
+
+ColumnExclusion = str | re.Pattern[str] | Callable[[str, np.dtype], bool]
+"""A single exclusion rule:
+
+- ``str`` — exact column name match.
+- ``re.Pattern`` — regex matched against the column name.
+- ``callable(name: str, dtype: np.dtype) -> bool`` — predicate receiving
+  the column name *and* its dtype, for filtering based on type, shape,
+  or any combination.
+"""
+
+FILLER_COLUMNS: re.Pattern[str] = re.compile(r"^f\d+$")
+"""Matches C++ memory-alignment filler fields by name (f0, f3, f123, …)."""
+
+LENGTH_COLUMNS: re.Pattern[str] = re.compile(r"_len$")
+"""Matches internal string-length columns by name (label_len, name_len, …)."""
+
+
+def VOID_COLUMNS(name: str, dtype: np.dtype) -> bool:
+    """Exclude all void-dtype fields (C++ alignment padding by dtype)."""
+    return dtype.kind == "V"
+
+
+def is_excluded(name: str, dtype: np.dtype, rules: Sequence[ColumnExclusion]) -> bool:
+    """Test whether a column name/dtype matches any exclusion rule.
+
+    Args:
+        name: Column name to test.
+        dtype: Column's dtype.
+        rules: Sequence of exclusion rules.
+
+    Returns:
+        True if the column should be excluded.
+    """
+    for rule in rules:
+        if isinstance(rule, str):
+            if name == rule:
+                return True
+        elif isinstance(rule, re.Pattern):
+            if rule.search(name) is not None:
+                return True
+        elif callable(rule):
+            if rule(name, dtype):
+                return True
+    return False

vcti/arraydisplay/_flattening.py

@@ -0,0 +1,46 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Dtype flattening helpers.
+
+Maps original multi-component fields to their flattened scalar column names
+after ``flatten_record_dtype`` has expanded vector/matrix fields.
+"""
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+
+def build_field_components(
+    original_dtype: np.dtype,
+    flattened_dtype: np.dtype,
+) -> dict[str, list[str]]:
+    """Map original multi-component fields to their flattened column names.
+
+    Walks both dtypes positionally: scalar fields consume one slot,
+    vector/matrix fields consume ``prod(shape)`` slots.
+
+    Args:
+        original_dtype: Dtype before flattening.
+        flattened_dtype: Dtype after flattening.
+
+    Returns:
+        Dict mapping original field name to list of flattened column names.
+        Only includes fields that were actually expanded (shape != ()).
+    """
+    if flattened_dtype.names is None:
+        raise TypeError("flattened_dtype must be a structured dtype with named fields")
+    if original_dtype.names is None:
+        raise TypeError("original_dtype must be a structured dtype with named fields")
+    flat_names = list(flattened_dtype.names)
+    result: dict[str, list[str]] = {}
+    idx = 0
+    for name in original_dtype.names:
+        shape = original_dtype[name].shape
+        n_components = max(math.prod(shape), 1)
+        if n_components > 1:
+            result[name] = flat_names[idx : idx + n_components]
+        idx += n_components
+    return result

vcti/arraydisplay/_formatting.py

@@ -0,0 +1,45 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""Value formatting and pandas import helpers for adapters."""
+
+from __future__ import annotations
+
+import types
+from typing import Any
+
+import numpy as np
+
+
+def format_value(value: Any) -> str:
+    """Format a single array value for text display.
+
+    Handles floats (6 significant digits), integers, bytes, and strings.
+    """
+    if isinstance(value, (np.floating, float)):
+        if np.isnan(value):
+            return "NaN"
+        return f"{value:.6g}"
+    if isinstance(value, (np.integer, int)):
+        return str(int(value))
+    if isinstance(value, (bytes, np.bytes_)):
+        return value.decode(errors="replace")
+    return str(value)
+
+
+def import_pandas() -> types.ModuleType:
+    """Import pandas or raise a helpful error.
+
+    Returns:
+        The pandas module.
+
+    Raises:
+        ImportError: If pandas is not installed.
+    """
+    try:
+        import pandas as pd
+    except ImportError:
+        raise ImportError(
+            "pandas is required for this method. "
+            "Install with: pip install vcti-array-display[pandas]"
+        ) from None
+    return pd

vcti/arraydisplay/array_display.py

@@ -0,0 +1,624 @@
+# Copyright Visual Collaboration Technologies Inc. All Rights Reserved.
+# See LICENSE for details.
+"""ArrayDisplay — presentation layer for NumPy structured arrays.
+
+Provides five capabilities over raw structured arrays:
+
+1. **Column filtering** — hide columns by name, regex, or predicate.
+2. **Dtype flattening** — expand vector/matrix fields into scalar columns
+   with user-controllable component names.
+3. **Enum mapping** — lazily map integer ID columns to human-readable names.
+4. **Array slicing** — create lightweight index arrays for bounded access.
+5. **Adapters** — render as text table or pandas DataFrame on bounded slices.
+"""
+
+from __future__ import annotations
+
+import copy
+from collections.abc import Sequence
+from types import MappingProxyType
+from typing import Any
+
+import numpy as np
+from vcti.nputils import flatten_record_dtype, join_struct_arrays
+
+from ._exclusion import ColumnExclusion, is_excluded
+from ._flattening import build_field_components
+from ._formatting import format_value, import_pandas
+
+
+class ArrayDisplay:
+    """Presentation layer for NumPy structured arrays.
+
+    Wraps a structured array reference (no copy) and records how it should
+    be presented:
+
+    1. **Column filtering** — ``exclude_columns`` hides fields by name,
+       regex, or callable.  Pre-built patterns ``FILLER_COLUMNS`` and
+       ``LENGTH_COLUMNS`` cover common C++ interop noise.
+    2. **Dtype flattening** — ``flatten_dtype`` expands vector/matrix fields
+       into scalar columns.  ``set_component_names()`` lets you replace
+       the default numeric suffixes (``_0``, ``_1``) with meaningful labels
+       (``_x``, ``_y``, ``_z``).
+    3. **Enum mapping** — ``add_name_columns()`` stores a recipe mapping
+       integer IDs to strings.  Resolution is lazy — applied only when
+       a bounded slice is presented.
+    4. **Array slicing** — ``to_slice()`` returns a lightweight index array
+       for bounded access without copying the full data.
+    5. **Adapters** — ``to_table()`` (pure numpy) and ``to_dataframe()``
+       (optional pandas) render bounded slices with all mappings applied.
+
+    Attributes:
+        array: The underlying structured array (reference, not copy).
+        original_dtype: Dtype before any flattening.
+        view_columns: Ordered list of user-visible column names (read-only copy).
+        name_columns: Enum mapping recipes (read-only view).
+        field_components: Flattened field grouping (read-only view).
+    """
+
+    def __init__(
+        self,
+        src_obj: np.ndarray | None = None,
+        column_list: list[str] | None = None,
+        flatten_dtype: bool = False,
+        exclude_columns: Sequence[ColumnExclusion] | None = None,
+        component_names: dict[str, list[str]] | None = None,
+    ) -> None:
+        """Initialize an ArrayDisplay.
+
+        Args:
+            src_obj: NumPy structured array, or None for empty.
+            column_list: Explicit columns to show.  If None, all columns
+                minus those matching *exclude_columns*.
+            flatten_dtype: Expand vector/matrix fields into scalar columns.
+            exclude_columns: Rules for hiding columns — each element is a
+                ``str`` (exact), ``re.Pattern`` (regex), or callable.
+            component_names: Custom suffixes for flattened fields, e.g.
+                ``{'position': ['x', 'y', 'z']}`` renames ``position_0``
+                through ``position_2`` to ``position_x`` through ``position_z``.
+                Only meaningful when *flatten_dtype* is True.
+        """
+        self.array: np.ndarray | None = None
+        self.original_dtype: np.dtype | None = None
+        self._view_columns: list[str] = []
+        self._name_columns: dict[str, tuple[str, dict[int, str]]] = {}
+        self._field_components: dict[str, list[str]] = {}
+        # Maps display names to actual dtype column names, used when
+        # set_component_names() renames flattened columns.  Survives
+        # multiple renames (e.g. x→lat) by always tracking back to
+        # the original dtype column.
+        self._column_aliases: dict[str, str] = {}
+
+        if isinstance(src_obj, np.ndarray):
+            self.set_array(src_obj, column_list, flatten_dtype, exclude_columns, component_names)
+        elif src_obj is not None:
+            raise TypeError(f"Expected np.ndarray or None, got {type(src_obj).__name__}")
+
+    # -- Read-only properties ---------------------------------------------------
+
+    @property
+    def view_columns(self) -> list[str]:
+        """Ordered list of user-visible column names (defensive copy)."""
+        return list(self._view_columns)
+
+    @property
+    def name_columns(self) -> MappingProxyType[str, tuple[str, dict[int, str]]]:
+        """Enum mapping recipes ``{name: (id_col, {int: str})}`` (read-only view)."""
+        return MappingProxyType(self._name_columns)
+
+    @property
+    def field_components(self) -> MappingProxyType[str, list[str]]:
+        """Flattened field grouping ``{field: [col, ...]}`` (read-only view)."""
+        return MappingProxyType(self._field_components)
+
+    # -- 1. Column filtering ----------------------------------------------------
+
+    def set_view_columns(
+        self,
+        column_list: list[str] | None = None,
+        exclude_columns: Sequence[ColumnExclusion] | None = None,
+    ) -> None:
+        """Configure which columns are visible.
+
+        Args:
+            column_list: Explicit columns.  If None, use all array columns
+                minus those matching *exclude_columns*.
+            exclude_columns: Rules for hiding columns.
+        """
+        if self.array is None:
+            self._view_columns = []
+            return
+
+        if column_list is not None:
+            self._view_columns = list(column_list)
+            return
+
+        if self.array.dtype.names is None:
+            raise TypeError("Array has no named fields")
+        cols = list(self.array.dtype.names)
+
+        if exclude_columns:
+            dt = self.array.dtype
+            cols = [c for c in cols if not is_excluded(c, dt[c], exclude_columns)]
+
+        self._view_columns = cols
+
+    def include_view_columns(self, column_list: list[str]) -> None:
+        """Add columns to the current view."""
+        self._view_columns.extend(column_list)
+
+    def exclude_view_columns(self, column_list: list[str]) -> None:
+        """Remove columns from the current view."""
+        exclude = set(column_list)
+        self._view_columns = [c for c in self._view_columns if c not in exclude]
+
+    def replace_view_columns(self, mapping: dict[str, str]) -> None:
+        """Replace column names in the view.
+
+        Args:
+            mapping: Dict mapping old_name -> new_name.
+        """
+        for i, col in enumerate(self._view_columns):
+            if col in mapping:
+                self._view_columns[i] = mapping[col]
+
+    # -- 2. Dtype flattening ----------------------------------------------------
+
+    def set_array(
+        self,
+        src_array: np.ndarray,
+        column_list: list[str] | None = None,
+        flatten_dtype: bool = False,
+        exclude_columns: Sequence[ColumnExclusion] | None = None,
+        component_names: dict[str, list[str]] | None = None,
+    ) -> None:
+        """Set or replace the internal array.
+
+        Args:
+            src_array: NumPy structured array with named fields.
+            column_list: Explicit columns to show.
+            flatten_dtype: Expand vector/matrix fields into scalar columns.
+            exclude_columns: Rules for hiding columns.
+            component_names: Custom suffixes for flattened fields.
+
+        Raises:
+            TypeError: If *src_array* is not a structured array.
+        """
+        if src_array.dtype.names is None:
+            raise TypeError(
+                f"Expected a structured array with named fields, got dtype {src_array.dtype}"
+            )
+
+        self.original_dtype = src_array.dtype
+        self._field_components = {}
+        self._name_columns = {}
+        self._column_aliases = {}
+
+        if flatten_dtype and src_array.ndim == 1:
+            flattened_dt, _ = flatten_record_dtype(src_array.dtype)
+            self.array = src_array.view(flattened_dt)
+            self._field_components = build_field_components(src_array.dtype, flattened_dt)
+        else:
+            self.array = src_array
+
+        self.set_view_columns(column_list, exclude_columns)
+
+        if component_names:
+            for field, names in component_names.items():
+                self.set_component_names(field, names)
+
+    def set_component_names(self, field: str, names: list[str]) -> None:
+        """Rename flattened component columns for a multi-component field.
+
+        After dtype flattening, a field like ``position(3,)`` becomes
+        ``position_0, position_1, position_2``.  This method renames them
+        to ``position_x, position_y, position_z`` (given ``names=['x','y','z']``).
+
+        Args:
+            field: Original field name (before flattening).
+            names: New suffixes — one per component.
+
+        Raises:
+            ValueError: If *field* is not in ``field_components`` or the
+                number of names doesn't match the component count.
+        """
+        if field not in self._field_components:
+            raise ValueError(
+                f"Field '{field}' has no flattened components. "
+                f"Available: {list(self._field_components)}"
+            )
+
+        current = self._field_components[field]
+        if len(names) != len(current):
+            raise ValueError(
+                f"Field '{field}' has {len(current)} components, got {len(names)} names"
+            )
+
+        rename = {}
+        new_cols = []
+        for old_col, suffix in zip(current, names):
+            new_col = f"{field}_{suffix}"
+            rename[old_col] = new_col
+            new_cols.append(new_col)
+            # Track the actual dtype column name for data access
+            dtype_col = self._column_aliases.get(old_col, old_col)
+            self._column_aliases[new_col] = dtype_col
+            self._column_aliases.pop(old_col, None)
+
+        self.replace_view_columns(rename)
+        self._field_components[field] = new_cols
+
+    # -- 3. Enum mapping --------------------------------------------------------
+
+    def add_name_columns(self, name_columns: dict[str, tuple[str, dict[int, str]]]) -> None:
+        """Register enum ID -> name mappings (lazy — resolved at presentation).
+
+        Stores a recipe for each mapping.  The actual resolution happens
+        only when ``to_table()`` or ``to_dataframe()`` processes a bounded
+        slice.  Automatically replaces ID columns with name columns in
+        ``view_columns``.
+
+        Args:
+            name_columns: ``{name_column: (id_column, {int: str})}``.
+
+        Example:
+            >>> view.add_name_columns({
+            ...     'element_type_name': ('element_type', {1: 'QUAD', 2: 'HEX'}),
+            ... })
+        """
+        self._name_columns.update(name_columns)
+        replacement_map = {v[0]: k for k, v in name_columns.items()}
+        self.replace_view_columns(replacement_map)
+
+    def _resolve_column_values(self, col: str, indices: np.ndarray) -> np.ndarray:
+        """Resolve column values for a bounded set of row indices.
+
+        Regular columns return values directly.  Name columns map integer
+        IDs to strings via the stored recipe.  Uses a plain list
+        comprehension — faster than ``np.vectorize`` for the small slices
+        that presentation methods operate on.
+        """
+        if self.array is None:
+            raise ValueError("No array set")
+        if col in self._name_columns:
+            id_col, mapping = self._name_columns[col]
+            id_values = self.array[id_col][indices]
+            return np.array([mapping.get(int(x), str(x)) for x in id_values])
+        dtype_col = self._column_aliases.get(col, col)
+        return self.array[dtype_col][indices]
+
+    # -- 4. Array slicing -------------------------------------------------------
+
+    def to_slice(
+        self,
+        *,
+        head: int | None = None,
+        tail: int | None = None,
+        mask: np.ndarray | None = None,
+        indices: np.ndarray | None = None,
+    ) -> np.ndarray:
+        """Create an index array for bounded access.
+
+        Returns a lightweight integer index array suitable for fancy
+        indexing: ``view.array[view.to_slice(head=20)]``.
+
+        Exactly one slicing strategy should be provided.  Priority when
+        multiple are given: *indices* > *mask* > *head*/*tail*.
+
+        Args:
+            head: Number of rows from the start.
+            tail: Number of rows from the end.
+            mask: Boolean mask array.
+            indices: Explicit integer index array (returned as-is).
+
+        Returns:
+            Integer index array (dtype ``np.intp``).
+
+        Raises:
+            ValueError: If no array is set, or if conflicting parameters
+                are provided (e.g. *mask* with *head*/*tail*).
+        """
+        if self.array is None:
+            raise ValueError("No array set")
+
+        n = len(self.array)
+
+        # Validate parameter combinations
+        has_head_tail = head is not None or tail is not None
+        if indices is not None and (mask is not None or has_head_tail):
+            raise ValueError("Cannot combine 'indices' with other slicing parameters")
+        if mask is not None and has_head_tail:
+            raise ValueError("Cannot combine 'mask' with 'head'/'tail'")
+
+        if indices is not None:
+            return indices
+
+        if mask is not None:
+            return np.where(mask)[0]
+
+        if head is not None and tail is not None:
+            h = np.arange(min(head, n))
+            t = np.arange(max(0, n - tail), n)
+            return np.unique(np.concatenate([h, t]))
+
+        if head is not None:
+            return np.arange(min(head, n))
+
+        if tail is not None:
+            return np.arange(max(0, n - tail), n)
+
+        return np.arange(n)
+
+    # -- 5. Adapters ------------------------------------------------------------
+
+    def to_table(
+        self,
+        *,
+        head: int = 20,
+        tail: int = 5,
+        max_col_width: int = 30,
+        indices: np.ndarray | None = None,
+    ) -> str:
+        """Render a text table from a bounded slice (pure numpy).
+
+        Resolves enum name columns and formats the output as an aligned
+        plain-text table.  Only the requested rows are processed.
+
+        Args:
+            head: Rows from the start (ignored if *indices* given).
+            tail: Rows from the end (ignored if *indices* given).
+            max_col_width: Maximum column display width in characters.
+            indices: Explicit row indices (overrides head/tail).
+
+        Returns:
+            Formatted text table string.
+        """
+        if self.array is None or not self._view_columns:
+            return repr(self)
+
+        n = len(self.array)
+        cols = self._view_columns
+
+        # Determine row blocks and whether to show an ellipsis separator
+        if indices is not None:
+            blocks: list[np.ndarray | None] = [indices]
+        elif n > head + tail:
+            blocks = [
+                np.arange(min(head, n)),
+                None,  # ellipsis marker
+                np.arange(max(0, n - tail), n),
+            ]
+        else:
+            blocks = [np.arange(n)]
+
+        # Resolve column values per block and convert to strings
+        str_rows: list[list[str] | None] = []
+        for block in blocks:
+            if block is None:
+                str_rows.append(None)
+                continue
+            col_values = {col: self._resolve_column_values(col, block) for col in cols}
+            for i in range(len(block)):
+                str_rows.append([format_value(col_values[col][i]) for col in cols])
+
+        # Calculate column widths
+        col_widths: list[int] = []
+        for ci, col in enumerate(cols):
+            max_val = max(
+                (len(row[ci]) for row in str_rows if row is not None),
+                default=0,
+            )
+            col_widths.append(min(max(len(col), max_val), max_col_width))
+
+        # Determine numeric alignment per column
+        dt = self.array.dtype
+        dtype_names = set(dt.names or ())
+
+        def _is_numeric(col: str) -> bool:
+            if col in self._name_columns:
+                return False
+            actual = self._column_aliases.get(col, col)
+            return actual in dtype_names and np.issubdtype(dt[actual], np.number)
+
+        col_numeric = [_is_numeric(col) for col in cols]
+
+        def fmt(val: str, ci: int) -> str:
+            w = col_widths[ci]
+            if len(val) > w:
+                val = val[: w - 1] + "\u2026"
+            return val.rjust(w) if col_numeric[ci] else val.ljust(w)
+
+        sep = " | "
+        lines: list[str] = []
+
+        # Header
+        lines.append(
+            sep.join(col.ljust(col_widths[ci])[: col_widths[ci]] for ci, col in enumerate(cols))
+        )
+        lines.append("-+-".join("-" * w for w in col_widths))
+
+        # Data rows
+        for row in str_rows:
+            if row is None:
+                lines.append(sep.join("...".center(col_widths[ci]) for ci in range(len(cols))))
+            else:
+                lines.append(sep.join(fmt(row[ci], ci) for ci in range(len(cols))))
+
+        lines.append(f"\n[{n} rows x {len(cols)} columns]")
+        return "\n".join(lines)
+
+    def to_dataframe(
+        self,
+        *,
+        indices: np.ndarray | None = None,
+        head: int | None = None,
+        tail: int | None = None,
+        resolve_names: bool = True,
+    ) -> Any:
+        """Convert a bounded slice to a pandas DataFrame.
+
+        Enum name columns are materialized using ``pd.Categorical`` for
+        memory efficiency.
+
+        Args:
+            indices: Explicit row indices.
+            head: Rows from the start.
+            tail: Rows from the end.
+            resolve_names: If True, materialize enum name columns.
+                If False, show raw ID columns instead.
+
+        Returns:
+            pandas DataFrame with the configured view columns.
+
+        Raises:
+            ImportError: If pandas is not installed.
+        """
+        pd = import_pandas()
+
+        if self.array is None:
+            return pd.DataFrame()
+
+        if indices is None and (head is not None or tail is not None):
+            indices = self.to_slice(head=head, tail=tail)
+
+        arr = self.array if indices is None else self.array[indices]
+        df = pd.DataFrame(arr)
+
+        cols = self._view_columns
+
+        # Rename aliased columns (from set_component_names) in the DataFrame
+        if self._column_aliases:
+            reverse = {v: k for k, v in self._column_aliases.items() if k in cols}
+            if reverse:
+                df = df.rename(columns=reverse)
+
+        if resolve_names:
+            for name_col, (id_col, mapping) in self._name_columns.items():
+                if name_col in cols:
+                    df[name_col] = pd.Categorical(df[id_col].map(mapping))
+            return df[cols]
+
+        # resolve_names=False: swap name columns back to source ID columns
+        select = [self._name_columns[c][0] if c in self._name_columns else c for c in cols]
+        return df[select]
+
+    def _repr_html_(self) -> str | None:
+        """Rich HTML display for Jupyter notebooks."""
+        if self.array is None or not self._view_columns:
+            return None
+
+        try:
+            pd = import_pandas()
+        except ImportError:
+            return f"<pre>{self.to_table()}</pre>"
+
+        n = len(self.array)
+        max_rows = pd.get_option("display.max_rows")
+        if max_rows is None:
+            max_rows = 60
+
+        if n <= max_rows:
+            df = self.to_dataframe()
+        else:
+            half = max_rows // 2
+            head_df = self.to_dataframe(head=half)
+            tail_df = self.to_dataframe(tail=half)
+            ellipsis_data = {col: ["\u22ee"] for col in self._view_columns}
+            ellipsis_df = pd.DataFrame(ellipsis_data)
+            df = pd.concat([head_df, ellipsis_df, tail_df], ignore_index=True)
+
+        html = df.to_html(index=False, na_rep="NaN")
+        return f"{html}\n<p>{n} rows \u00d7 {len(self._view_columns)} columns</p>"
+
+    # -- Misc -------------------------------------------------------------------
+
+    def append_columns(
+        self, columns: list[np.ndarray] | tuple[np.ndarray, ...] | np.ndarray
+    ) -> None:
+        """Append additional structured columns to the array.
+
+        Joins the existing array with new structured column(s) using
+        ``vcti.nputils.join_struct_arrays``.  The resulting dtype is the
+        union of all field names.  Field names must not overlap — duplicate
+        names will raise an error from the underlying join function.
+
+        The new columns are added to the underlying array but **not**
+        automatically added to ``view_columns``.  Call
+        ``include_view_columns()`` afterwards if they should be visible.
+
+        Can be called on an empty ArrayDisplay (no array set) — the
+        provided columns become the array.
+
+        Args:
+            columns: Structured array(s) to join.  All arrays must have
+                the same number of rows as the existing array.
+        """
+        arrays: list[np.ndarray] = []
+        if self.array is not None:
+            arrays.append(self.array)
+
+        if isinstance(columns, (list, tuple)):
+            arrays.extend(columns)
+        elif isinstance(columns, np.ndarray):
+            arrays.append(columns)
+        else:
+            raise TypeError(f"Expected list, tuple, or np.ndarray, got {type(columns).__name__}")
+
+        self.array = join_struct_arrays(arrays)
+
+    def copy(self) -> ArrayDisplay:
+        """Create a shallow copy of this ArrayDisplay.
+
+        The underlying array is shared (not copied), but all configuration
+        state (view columns, name columns, field components, aliases) is
+        independently mutable.
+
+        Returns:
+            A new ArrayDisplay with the same array reference and a copy
+            of all configuration state.
+        """
+        new = ArrayDisplay.__new__(ArrayDisplay)
+        new.array = self.array
+        new.original_dtype = self.original_dtype
+        new._view_columns = list(self._view_columns)
+        new._name_columns = copy.deepcopy(self._name_columns)
+        new._field_components = copy.deepcopy(self._field_components)
+        new._column_aliases = dict(self._column_aliases)
+        return new
+
+    def __len__(self) -> int:
+        """Return the number of rows in the array (0 if no array set)."""
+        if self.array is None:
+            return 0
+        return len(self.array)
+
+    def __repr__(self) -> str:
+        n_rows = len(self)
+        n_cols = len(self._view_columns)
+        parts = [f"rows={n_rows}", f"cols={n_cols}"]
+        if self._field_components:
+            parts.append(f"flattened={len(self._field_components)}")
+        if self._name_columns:
+            parts.append(f"enums={len(self._name_columns)}")
+        return f"ArrayDisplay({', '.join(parts)})"
+
+    def __str__(self) -> str:
+        parts = ["ArrayDisplay:"]
+
+        if self.array is not None:
+            parts.append(f"  Shape: {self.array.shape}")
+            parts.append(f"  Dtype: {self.array.dtype}")
+            parts.append(f"  View columns ({len(self._view_columns)}):")
+            for col in self._view_columns[:10]:
+                parts.append(f"    - {col}")
+            if len(self._view_columns) > 10:
+                parts.append(f"    ... and {len(self._view_columns) - 10} more")
+        else:
+            parts.append("  Array: None")
+
+        if self._field_components:
+            parts.append(f"  Flattened fields: {len(self._field_components)}")
+        if self._name_columns:
+            parts.append(f"  Enum mappings: {len(self._name_columns)}")
+
+        return "\n".join(parts)

vcti/arraydisplay/array_display.pyi

@@ -0,0 +1,92 @@
+"""Type stubs for array_display module — improved IDE support."""
+
+from collections.abc import Sequence
+from types import MappingProxyType
+
+import numpy as np
+import pandas as pd
+
+from ._exclusion import ColumnExclusion
+
+class ArrayDisplay:
+    array: np.ndarray | None
+    original_dtype: np.dtype | None
+
+    def __init__(
+        self,
+        src_obj: np.ndarray | None = ...,
+        column_list: list[str] | None = ...,
+        flatten_dtype: bool = ...,
+        exclude_columns: Sequence[ColumnExclusion] | None = ...,
+        component_names: dict[str, list[str]] | None = ...,
+    ) -> None: ...
+
+    # Read-only properties
+    @property
+    def view_columns(self) -> list[str]: ...
+    @property
+    def name_columns(self) -> MappingProxyType[str, tuple[str, dict[int, str]]]: ...
+    @property
+    def field_components(self) -> MappingProxyType[str, list[str]]: ...
+
+    # 1. Column filtering
+    def set_view_columns(
+        self,
+        column_list: list[str] | None = ...,
+        exclude_columns: Sequence[ColumnExclusion] | None = ...,
+    ) -> None: ...
+    def include_view_columns(self, column_list: list[str]) -> None: ...
+    def exclude_view_columns(self, column_list: list[str]) -> None: ...
+    def replace_view_columns(self, mapping: dict[str, str]) -> None: ...
+
+    # 2. Dtype flattening
+    def set_array(
+        self,
+        src_array: np.ndarray,
+        column_list: list[str] | None = ...,
+        flatten_dtype: bool = ...,
+        exclude_columns: Sequence[ColumnExclusion] | None = ...,
+        component_names: dict[str, list[str]] | None = ...,
+    ) -> None: ...
+    def set_component_names(self, field: str, names: list[str]) -> None: ...
+
+    # 3. Enum mapping
+    def add_name_columns(self, name_columns: dict[str, tuple[str, dict[int, str]]]) -> None: ...
+
+    # 4. Array slicing
+    def to_slice(
+        self,
+        *,
+        head: int | None = ...,
+        tail: int | None = ...,
+        mask: np.ndarray | None = ...,
+        indices: np.ndarray | None = ...,
+    ) -> np.ndarray: ...
+
+    # 5. Adapters
+    def to_table(
+        self,
+        *,
+        head: int = ...,
+        tail: int = ...,
+        max_col_width: int = ...,
+        indices: np.ndarray | None = ...,
+    ) -> str: ...
+    def to_dataframe(
+        self,
+        *,
+        indices: np.ndarray | None = ...,
+        head: int | None = ...,
+        tail: int | None = ...,
+        resolve_names: bool = ...,
+    ) -> pd.DataFrame: ...
+    def _repr_html_(self) -> str | None: ...
+
+    # Misc
+    def append_columns(
+        self, columns: list[np.ndarray] | tuple[np.ndarray, ...] | np.ndarray
+    ) -> None: ...
+    def copy(self) -> ArrayDisplay: ...
+    def __len__(self) -> int: ...
+    def __repr__(self) -> str: ...
+    def __str__(self) -> str: ...

vcti_array_display-1.1.0.dist-info/METADATA

@@ -0,0 +1,222 @@
+Metadata-Version: 2.4
+Name: vcti-array-display
+Version: 1.1.0
+Summary: Presentation layer for NumPy structured arrays — column filtering, dtype flattening, enum mapping, array slicing, and adapters
+Author: Visual Collaboration Technologies Inc.
+Requires-Python: <3.15,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: vcti-nputils>=1.0.0
+Provides-Extra: pandas
+Requires-Dist: pandas>=2.0; extra == "pandas"
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: pandas>=2.0; extra == "test"
+Provides-Extra: lint
+Requires-Dist: ruff; extra == "lint"
+Provides-Extra: typecheck
+Requires-Dist: mypy; extra == "typecheck"
+Requires-Dist: pandas-stubs; extra == "typecheck"
+Dynamic: license-file
+
+# Array Display
+
+Presentation layer for NumPy structured arrays.
+
+ArrayDisplay wraps a structured NumPy array reference (no copy) and provides
+five capabilities for controlling how the data is presented:
+
+1. **Column filtering** — hide columns by name, regex, or predicate
+2. **Dtype flattening** — expand vector/matrix fields into scalar columns with custom component names
+3. **Enum mapping** — lazily map integer ID columns to human-readable names
+4. **Array slicing** — create lightweight index arrays for bounded access
+5. **Adapters** — render as text table or pandas DataFrame on bounded slices
+
+## Installation
+
+```bash
+pip install vcti-array-display>=1.1.0
+```
+
+With pandas support (optional):
+
+```bash
+pip install vcti-array-display[pandas]>=1.1.0
+```
+
+---
+
+## 1. Column Filtering
+
+Hide unwanted columns using any combination of exact names, regex patterns,
+and callable predicates.
+
+```python
+import re
+import numpy as np
+from vcti.arraydisplay import ArrayDisplay, FILLER_COLUMNS, LENGTH_COLUMNS, VOID_COLUMNS
+
+dt = np.dtype([
+    ('id', 'i4'), ('f0', 'V4'), ('label', 'U20'),
+    ('label_len', 'i4'), ('value', 'f8'), ('f3', 'V8'),
+])
+arr = np.zeros(10, dtype=dt)
+
+# Pre-built patterns for C++ interop noise
+view = ArrayDisplay(arr, exclude_columns=[FILLER_COLUMNS, LENGTH_COLUMNS])
+view.view_columns  # ['id', 'label', 'value']
+
+# Or exclude by dtype — catches all void padding regardless of name
+view = ArrayDisplay(arr, exclude_columns=[VOID_COLUMNS, LENGTH_COLUMNS])
+
+# Mix exact names, regex, and callables
+view = ArrayDisplay(arr, exclude_columns=[
+    FILLER_COLUMNS,                        # regex: ^f\d+$
+    LENGTH_COLUMNS,                        # regex: _len$
+    "debug_flag",                          # exact name
+    re.compile(r"^tmp_"),                  # custom regex
+    lambda name, dtype: dtype.kind == 'V', # by dtype
+])
+```
+
+No magic defaults — `ArrayDisplay(arr)` shows all columns.  Pre-built patterns
+`FILLER_COLUMNS`, `LENGTH_COLUMNS`, and `VOID_COLUMNS` are opt-in.
+Callables receive `(name, dtype)` for filtering by type, shape, or both.
+
+## 2. Dtype Flattening
+
+Expand vector and matrix fields into individual scalar columns, with
+optional user-defined component names.
+
+```python
+dt = np.dtype([('id', 'i4'), ('position', 'f8', (3,))])
+arr = np.zeros(5, dtype=dt)
+
+# Default numeric suffixes
+view = ArrayDisplay(arr, flatten_dtype=True)
+view.view_columns  # ['id', 'position_0', 'position_1', 'position_2']
+
+# Custom component names
+view = ArrayDisplay(arr, flatten_dtype=True,
+                 component_names={'position': ['x', 'y', 'z']})
+view.view_columns  # ['id', 'position_x', 'position_y', 'position_z']
+
+# Component grouping is tracked for consumers (e.g., header spanning)
+view.field_components
+# {'position': ['position_x', 'position_y', 'position_z']}
+
+# Rename after construction
+view.set_component_names('position', ['lat', 'lon', 'alt'])
+```
+
+> **Note:** Default flattened names (e.g., `position_0`) are generated by
+> `vcti-nputils` and may truncate long field names.  Use `component_names`
+> to ensure predictable, readable column names regardless of the defaults.
+
+## 3. Enum Mapping
+
+Map integer ID columns to human-readable names.  The mapping is stored as
+a recipe and resolved lazily — only when presenting a bounded slice.
+
+```python
+dt = np.dtype([('id', 'i4'), ('element_type', 'i4'), ('value', 'f8')])
+arr = np.array([(1, 1, 10.5), (2, 2, 20.3), (3, 1, 15.0)], dtype=dt)
+view = ArrayDisplay(arr)
+
+view.add_name_columns({
+    'element_type_name': ('element_type', {1: 'QUAD', 2: 'HEX'}),
+})
+view.view_columns  # ['id', 'element_type_name', 'value']
+
+# The mapping is NOT materialized yet — it's a recipe:
+view.name_columns
+# {'element_type_name': ('element_type', {1: 'QUAD', 2: 'HEX'})}
+```
+
+## 4. Array Slicing
+
+Create lightweight index arrays for bounded access.  The index array is
+tiny regardless of the underlying array size.
+
+```python
+idx = view.to_slice(head=20)                       # first 20 rows
+idx = view.to_slice(tail=10)                       # last 10 rows
+idx = view.to_slice(head=10, tail=5)               # first 10 + last 5
+idx = view.to_slice(mask=arr['value'] > 50)        # boolean filter
+idx = view.to_slice(indices=np.array([0, 100, 999]))  # explicit
+
+view.array[idx]                                    # sliced data
+```
+
+## 5. Adapters
+
+### Text table (pure numpy — no extra dependencies)
+
+```python
+print(view.to_table(head=10, tail=5))
+# id | element_type_name | value
+# ---+-------------------+------
+#  1 | QUAD              |  10.5
+#  2 | HEX               |  20.3
+# ...
+# [1000 rows x 3 columns]
+```
+
+### pandas DataFrame (optional dependency)
+
+```python
+df = view.to_dataframe()                   # full array
+df = view.to_dataframe(head=100)           # first 100 rows
+df = view.to_dataframe(resolve_names=False)  # raw ID columns
+```
+
+Enum names are materialized using `pd.Categorical` for memory efficiency.
+
+### Jupyter notebooks
+
+ArrayDisplay provides `_repr_html_()` — displays a bounded row window with
+enum names resolved automatically.
+
+---
+
+## Performance
+
+Designed for large CAE arrays (millions of rows, GBs of data):
+
+- **No array copy** — wraps a reference to the original numpy array
+- **Lazy enum resolution** — resolved only on the displayed slice
+- **Index arrays** — `to_slice()` returns kilobytes regardless of array size
+- **Bounded presentation** — `to_table()` and `to_dataframe(head=N)` never touch the full array
+- **`pd.Categorical`** — ~100x less memory than string columns for enum values
+
+---
+
+## API Summary
+
+| Method | Pillar | Description |
+|--------|--------|-------------|
+| `set_view_columns(...)` | Filtering | Configure visible columns |
+| `include_view_columns(cols)` | Filtering | Add columns to the view |
+| `exclude_view_columns(cols)` | Filtering | Remove columns from the view |
+| `replace_view_columns(mapping)` | Filtering | Rename columns in the view |
+| `set_array(arr, ...)` | Flattening | Set array with optional flattening |
+| `set_component_names(field, names)` | Flattening | Rename flattened components |
+| `add_name_columns(mappings)` | Enum mapping | Register lazy enum mappings |
+| `to_slice(...)` | Slicing | Create index array for bounded access |
+| `to_table(...)` | Adapter | Render text table (pure numpy) |
+| `to_dataframe(...)` | Adapter | Convert to pandas DataFrame |
+| `copy()` | Misc | Shallow copy with independent config |
+| `append_columns(cols)` | Misc | Join additional structured columns |
+
+## Examples
+
+See [examples/full_pipeline.py](examples/full_pipeline.py) for a complete
+end-to-end script demonstrating all five pillars.
+
+## Dependencies
+
+- [numpy](https://numpy.org/) (>=1.24) — required
+- [vcti-nputils](https://pypi.org/project/vcti-nputils/) (>=1.0.0) — required
+- [pandas](https://pandas.pydata.org/) (>=2.0) — optional, for `to_dataframe()` and Jupyter display

vcti_array_display-1.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+vcti/arraydisplay/__init__.py,sha256=w9Mh7ILQwDwXlH7TJrzsuWpktxfL3rU2_Jvc6-nYBAM,528
+vcti/arraydisplay/_exclusion.py,sha256=VC6kzVEQivmI8c-EcT7thX4OvcCzzSXuOuF-lxFXDes,1930
+vcti/arraydisplay/_flattening.py,sha256=IwqNxCKEO8Z0FyrZT-VVS_KbDJewzkq-hhlyDt7z5f0,1555
+vcti/arraydisplay/_formatting.py,sha256=qJp9atqMHNCcWEtue0Tt-873V-mttlOWdrL-xWaXlSA,1191
+vcti/arraydisplay/array_display.py,sha256=XFqtpyV84JNhEEjkarup5pg-Zi4NV5XbquQvVOB11Ks,23977
+vcti/arraydisplay/array_display.pyi,sha256=fa_NkQ8chC0s_Uii2oYN6-V9lK4FI3a5-1raZNp-4Ss,2783
+vcti/arraydisplay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vcti_array_display-1.1.0.dist-info/licenses/LICENSE,sha256=gqRj-E4YRsT7mZ52W76LG6aTTFv6iEOK9QR_fV5EdrI,369
+vcti_array_display-1.1.0.dist-info/METADATA,sha256=pQ-dNbBYaObnx41BXMYzc2u-x5nACi_HVYW18bV6P9Y,7707
+vcti_array_display-1.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+vcti_array_display-1.1.0.dist-info/top_level.txt,sha256=Jl6AIAI3Xhru_BFQAhD_13VeXLmZQd9BqBNUaAKNgKs,5
+vcti_array_display-1.1.0.dist-info/zip-safe,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+vcti_array_display-1.1.0.dist-info/RECORD,,

vcti_array_display-1.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

vcti_array_display-1.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,8 @@
+Copyright (c) 2018-2026 Visual Collaboration Technologies Inc.
+All Rights Reserved.
+
+This software is proprietary and confidential. Unauthorized copying,
+distribution, or use of this software, via any medium, is strictly
+prohibited. Access is granted only to authorized VCollab developers
+and individuals explicitly authorized by Visual Collaboration
+Technologies Inc.

vcti_array_display-1.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+vcti

vcti_array_display-1.1.0.dist-info/zip-safe

@@ -0,0 +1 @@
+