VTKio 0.1.0.dev2__py3-none-any.whl

vtkio/utilities.py

@@ -0,0 +1,222 @@
+#!/usr/bin/env python
+"""
+Module for generic helper functions used in VTKio.
+
+This module contains the following functions:
+
+
+Functions
+---------
+get_recursively()
+    Search a dictionary recursively.
+
+"""
+
+__author__ = 'J.P. Morrissey'
+__copyright__ = 'Copyright 2022-2025'
+__maintainer__ = 'J.P. Morrissey'
+__email__ = 'morrissey.jp@gmail.com'
+__status__ = 'Development'
+
+# Standard Library
+from collections.abc import MutableMapping
+
+
+def is_numeric_array(obj):
+    """
+    Check if the provided object behaves like a numeric array.
+
+    This function determines if the given object has specific attributes that are generally associated with numeric
+    array-like objects. The attributes checked include addition, subtraction, multiplication, division, and power
+    operations. Objects lacking these attributes are not considered numeric arrays.
+
+    Parameters
+    ----------
+    obj : object
+        The object to check for numeric array-like behavior.
+
+    Returns
+    -------
+    bool
+        Returns True if the object meets the required criteria for being
+        a numeric array-like object; otherwise, it returns False.
+    """
+    attrs = ['__add__', '__sub__', '__mul__', '__truediv__', '__pow__']
+    return all(hasattr(obj, attr) for attr in attrs)
+
+
+def flatten(dictionary, parent_key='', separator='_'):
+    """
+    Flattens a nested dictionary into a single-depth dictionary.
+
+    The function takes a nested dictionary and transforms it into a flattened dictionary
+    with a single level. Each key in the resulting dictionary is a concatenation of the
+    hierarchical keys from the original dictionary, separated by the provided separator.
+    This is particularly useful for simplifying nested structures for certain operations,
+    such as data serialization or storage.
+
+    Parameters
+    ----------
+    dictionary : dict
+        A dictionary that may contain nested dictionaries as values.
+    parent_key : str, optional
+        A string to prefix the keys of the flattened dictionary with. Defaults to an
+        empty string, meaning no prefix is added.
+    separator : str, optional
+        A string used to separate concatenated keys in the flattened dictionary. Defaults
+        to an underscore ('_').
+
+    Returns
+    -------
+    dict
+        A flattened dictionary where all keys are made unique by combining their
+        hierarchical keys using the specified separator.
+    """
+    items = []
+    for key, value in dictionary.items():
+        new_key = parent_key + separator + key if parent_key else key
+        if isinstance(value, MutableMapping):
+            items.extend(flatten(value, new_key, separator=separator).items())
+        else:
+            items.append((new_key, value))
+    return dict(items)
+
+
+def dict_extract_generator(key, var):
+    """
+    Generate values from a nested dictionary or list structure that match the specified key.
+
+    This generator function recursively traverses dictionaries and lists in search of values
+    associated with a specified key. The function yields these values when the matching key
+    is found.
+
+    Parameters
+    ----------
+    key : str
+        The key to search for in the nested structure.
+    var : dict or list
+        The nested dictionary or list structure to traverse.
+
+    Yields
+    ------
+    Any
+        Values associated with the specified key in the nested structure. The type of
+        the yielded value depends on the contents of the input structure.
+    """
+    if hasattr(var,'items'):
+        for k, v in var.items():
+            if k == key:
+                yield v
+            if isinstance(v, dict):
+                for result in dict_extract_generator(key, v):
+                    yield result
+            elif isinstance(v, list):
+                for d in v:
+                    for result in dict_extract_generator(key, d):
+                        yield result
+
+
+def get_recursively(search_dict, field):
+    """
+    Search a dictionary recursively.
+
+    Takes a dictionary with nested lists and dictionaries, and searches all dictionaries for a key of the field provided.
+
+    Parameters
+    ----------
+    search_dict : Dict [Any, Any]
+        Dictionary to be searched. It can contain nested dictionaries and lists as well as basic types such as strings, ints and floats.
+    field : key [Any]
+        Dictionary key to be searched for. Typically, a string, integer or float.
+
+    Returns
+    -------
+    result : List[Any]
+        The values associated with the key provided. If the key is not found, an empty list is returned.
+
+
+    Examples
+    --------
+    >>> d = {'a': 1, 'b': 2, 'c': {'da': 4, 'db': 5, 'dc': {'dda': 8, 'ddb': 9}}}
+    >>> get_recursively(d, 'da')
+    [4]
+    >>> get_recursively(d, 'ddb')
+    [9]
+    >>> get_recursively(d, 'missing_key')
+    []
+
+    """
+    fields_found = []
+
+    for key, value in search_dict.items():
+
+        if key == field:
+            fields_found.append(value)
+
+        elif isinstance(value, dict):
+            results = get_recursively(value, field)
+            for result in results:
+                fields_found.append(result)
+
+        elif isinstance(value, list):
+            for item in value:
+                if isinstance(item, dict):
+                    more_results = get_recursively(item, field)
+                    for another_result in more_results:
+                        fields_found.append(another_result)
+
+    return fields_found
+
+
+def flatten_list(nested_list):
+    """
+    Flattens a nested list into a single list.
+
+    The function takes a nested list of arbitrary depth and recursively flattens
+    it into a single list containing all the elements. Any nested sub-lists are
+    converted into their constituent elements and appended to the resulting list.
+
+    Parameters
+    ----------
+    nested_list : list
+        A possibly nested list of elements to be flattened. The input can consist
+        of multiple levels of lists.
+
+    Returns
+    -------
+    list
+        A flattened list containing all elements from the input `nested_list`,
+        including elements from any nested sub-lists.
+    """
+    def flatten_helper(sublist, result):
+        for item in sublist:
+            if isinstance(item, list):  # Improved type checking
+                flatten_helper(item, result)  # Recursive call
+            else:
+                result.append(item)
+        return result
+
+    return flatten_helper(nested_list, [])  # Extracted recursive logic into helper
+
+
+def first_key(dict):
+    """
+    Retrieve the first key from a given dictionary.
+
+    This function iterates over a dictionary and retrieves the first key it
+    encounters. If the dictionary is empty, it returns None.
+
+    Parameters
+    ----------
+    dict : dict
+        The dictionary from which the first key will be retrieved.
+
+    Returns
+    -------
+    Hashable or None
+        The first key encountered in the dictionary. If the dictionary is empty,
+        returns None.
+    """
+    for key in dict:
+        return key
+    return None

vtkio/version.py

@@ -0,0 +1,78 @@
+#!/usr/bin/env python
+"""
+This `version` module contains the version information for the VTKio package.
+
+Created at 12:47, 23 Feb, 2025
+"""
+
+__author__ = 'J.P. Morrissey'
+__copyright__ = 'Copyright 2022-2025'
+__maintainer__ = 'J.P. Morrissey'
+__email__ = 'morrissey.jp@gmail.com'
+__status__ = 'Development'
+
+# Standard Library
+
+
+# Imports
+
+
+# Local Sources
+
+
+__all__ = ['VERSION', 'version_info', 'version_short']
+
+VERSION = '0.1.0.dev2'
+"""The version of VTKio."""
+
+def version_short() -> str:
+    """Return the `major.minor` part of package version.
+
+    It returns '0.2' if VTKio version is '0.2.2'.
+    """
+    return '.'.join(VERSION.split('.')[:2])
+
+
+def version_info() -> str:
+    """Return complete version information for VTKio and its dependencies."""
+    import importlib.metadata as importlib_metadata
+    import os
+    import platform
+    import sys
+    from pathlib import Path
+
+    # Local Sources
+    import _git as git
+
+    import vtkio as vtkio
+
+
+    # get data about packages that are closely related to or are used by VTKio
+    package_names = {
+        'h5py',
+        'xmltodict',
+        'numpy',
+        'pybase64',
+    }
+    related_packages = []
+
+    for dist in importlib_metadata.distributions():
+        name = dist.metadata['Name']
+        if name in package_names:
+            related_packages.append(f'{name}-{dist.version}')
+
+    vtkio_dir = os.path.abspath(os.path.dirname(os.path.dirname(__file__)))
+    most_recent_commit = (
+        git.git_revision(vtkio_dir) if git.is_git_repo(vtkio_dir) and git.have_git() else 'unknown'
+    )
+
+    info = {
+        'vtkio version': VERSION,
+        'vtkio-core build': getattr(vtkio, 'build_info', None) or vtkio.build_profile,
+        'install path': Path(__file__).resolve().parent,
+        'python version': sys.version,
+        'platform': platform.platform(),
+        'related packages': ' '.join(related_packages),
+        'commit': most_recent_commit,
+    }
+    return '\n'.join('{:>30} {}'.format(k + ':', str(v).replace('\n', ' ')) for k, v in info.items())

vtkio/vtk_cell_types.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python
+"""
+VTKWriter Class for creating VTK's XML based format.
+
+Supports ASCII, Base64 and Appended Raw encoding of data.
+
+Created at 13:01, 24 Feb, 2022
+"""
+
+__author__ = 'J.P. Morrissey'
+__copyright__ = 'Copyright 2022-2025'
+__maintainer__ = 'J.P. Morrissey'
+__email__ = 'morrissey.jp@gmail.com'
+__status__ = 'Development'
+
+# Standard Library
+from dataclasses import dataclass
+
+
+@dataclass
+class VTK_CellType:
+    """Generic Class for storing the various different vtk cell types."""
+
+    name: str
+    type_id: int
+    num_points: int
+    dimensionality: int
+    structure: str
+    interpolation: str
+
+    def set_num_points(self, num_points: int):
+        """
+        Set the number of points for the cell type.
+
+        This is used for the PolyLine, Polygon and PolyVertex cell types.
+        The number of points is set to the number of points in the cell.
+
+        Parameters
+        ----------
+        num_points : int
+            The number of points in the cell.
+        """
+        if self.name in ["PolyLine", "Polygon", "PolyVertex"]:
+            self.num_points = num_points
+        else:
+            raise ValueError(f"Cannot set number of points for {self.name} cell type.")
+
+        return self
+
+    def set_num_triangles(self, num_triangles: int):
+        """
+        Set the number of triangles and points for the Triangle Strip cell type.
+
+        Parameters
+        ----------
+        num_triangles : int
+            The number of triangles in the cell.
+
+        """
+        if self.name == "TriangleStrip":
+            # The number of points in a triangle strip is the number of triangles + 2
+            self.num_points = num_triangles + 2
+        else:
+            raise ValueError(f"Cannot set number of triangles for {self.name} cell type.")
+
+        return self
+
+
+VTK_Vertex = VTK_CellType("Vertex", 1, 1, 0, "Primary", "Linear")
+VTK_PolyVertex = VTK_CellType("PolyVertex", 1, "n", 0, "Composite", "Linear")
+VTK_Line = VTK_CellType("Line", 3, 2, 1, "Primary", "Linear")
+VTK_PolyLine = VTK_CellType("PolyLine", 4, "n", 1, "Composite", "Linear")
+VTK_Triangle = VTK_CellType("Triangle", 5, 3, 2, "Primary", "Linear")
+VTK_TriangleStrip = VTK_CellType("TriangleStrip", 6, "n+2", 2, "Composite", "Linear")
+VTK_Polygon = VTK_CellType("Polygon", 7, "n", 2, "Primary", "Linear")
+VTK_Pixel = VTK_CellType("Pixel", 8, 4, 2, "Primary", "Linear")
+VTK_Quad = VTK_CellType("Quad", 9, 4, 3, "Primary", "Linear")
+VTK_Tetra = VTK_CellType("Tetra", 10, 4, 3, "Primary", "Linear")
+VTK_Voxel = VTK_CellType("Voxel", 11, 8, 3, "Primary", "Linear")
+VTK_Hexahedron = VTK_CellType("Hexahedron", 12, 8, 3, "Primary", "Linear")
+VTK_Wedge = VTK_CellType("Wedge", 13, 6, 3, "Primary", "Linear")
+VTK_Pyramid = VTK_CellType("Pyramid", 14, 5, 3, "Primary", "Linear")
+VTK_Pentagonal_Prism = VTK_CellType("Pentagonal_Prism", 15, 10, 3, "Primary", "Linear")
+VTK_Hexagonal_Prism = VTK_CellType("Hexagonal_Prism", 16, 12, 3, "Primary", "Linear")
+VTK_Quadratic_Edge = VTK_CellType("Quadratic_Edge", 21, 3, 1, "Primary", "NonLinear")
+VTK_Quadratic_Triangle = VTK_CellType("Quadratic_Triangle", 22, 6, 2, "Primary", "NonLinear")
+VTK_Quadratic_Quad = VTK_CellType("Quadratic_Quad", 23, 8, 2, "Primary", "NonLinear")
+VTK_Quadratic_Tetra = VTK_CellType("Quadratic_Tetra", 24, 10, 3, "Primary", "NonLinear")
+VTK_Quadratic_Hexahedron = VTK_CellType("Quadratic_Hexahedron", 25, 20, 3, "Primary", "NonLinear")
+VTK_Quadratic_Wedge = VTK_CellType("Quadratic_Wedge", 26, 12, 3, "Primary", "NonLinear")
+VTK_Quadratic_Pyramid = VTK_CellType("Quadratic_Pyramid", 27, 13, 3, "Primary", "NonLinear")
+VTK_BiQuadratic_Quad = VTK_CellType("BiQuadratic_Quad", 28, 9, 2, "Primary", "NonLinear")
+VTK_TriQuadratic_Hexahedron = VTK_CellType("TriQuadratic_Hexahedron", 29, 27, 3, "Primary", "NonLinear")
+VTK_Quadratic_Linear_Quad = VTK_CellType("Quadratic_Linear_Quad", 30, 6, 3, "Primary", "NonLinear")
+VTK_Quadratic_Linear_Wedge = VTK_CellType("Quadratic_Linear_Wedge", 31, 12, 3, "Primary", "NonLinear")
+VTK_BiQuadratic_Quadratic_Wedge= VTK_CellType("BiQuadratic_Quadratic_Wedge", 32, 18, 3, "Primary", "NonLinear")
+VTK_BiQuadratic_Quadratic_Hexahedron = VTK_CellType("BiQuadratic_Quadratic_Hexahedron", 33, 24, 3, "Primary", "NonLinear")
+VTK_BiQuadratic_Triangle = VTK_CellType("BiQuadratic_Triangle", 34, 7, 2, "Primary", "NonLinear")

vtkio/vtk_structures.py

@@ -0,0 +1,306 @@
+#!/usr/bin/env python
+"""
+Module documentation goes here.
+
+Created at 17:27, 22 Jul, 2024
+"""
+
+__author__ = 'J.P. Morrissey'
+__copyright__ = 'Copyright 2022-2025'
+__maintainer__ = 'J.P. Morrissey'
+__email__ = 'morrissey.jp@gmail.com'
+__status__ = 'Development'
+
+# Standard Library
+from dataclasses import astuple, dataclass
+
+# Imports
+import numpy as np
+
+# Local Sources
+from .writer.writers import write_vti, write_vtp, write_vtr, write_vts, write_vtu
+
+
+def compare_exact(first, second):
+    """Return whether two dicts of arrays are exactly equal."""
+    if first.keys() != second.keys():
+        return False
+    return all(np.array_equal(first[key], second[key]) for key in first)
+
+
+def compare_approximate(first, second):
+    """
+    Return whether two dicts of arrays are roughly equal.
+
+    This is used otherwise comparing floats would return `False`.
+    """
+    if first.keys() != second.keys():
+        return False
+    return all(np.allclose(first[key], second[key]) for key in first)
+
+
+def array_safe_eq(a, b) -> bool:
+    """Check if a and b are equal, even if they are numpy arrays."""
+    if a is b:
+        return True
+
+    if isinstance(a, np.ndarray) and isinstance(b, np.ndarray):
+        # return np.array_equal(a, b)
+        return np.allclose(a, b)
+
+    if isinstance(a, dict) and isinstance(b, dict):
+        return compare_approximate(a, b)
+
+    if isinstance(a, list) and isinstance(b, list):
+        pass
+
+    if isinstance(a, tuple) and isinstance(b, tuple):
+        return all((a == b).all() for a, b in zip(a, b))
+
+    try:
+        return a == b
+    except TypeError:
+        return NotImplemented
+
+
+def dataclass_equality_check(dc1, dc2) -> bool:
+    """Checks if two dataclasses which hold numpy arrays are equal."""
+    if dc1 is dc2:
+        return True
+
+    if dc1.__class__ is not dc2.__class__:
+        return NotImplemented  # better than False
+
+    t1 = astuple(dc1)
+    t2 = astuple(dc2)
+
+    if len(t1) != len(t2):
+        return False
+    else:
+        return all(array_safe_eq(a1, a2) for a1, a2 in zip(t1, t2))
+
+
+@dataclass
+class VTKData:
+    point_data: dict
+    cell_data: dict
+    field_data: dict
+
+
+@dataclass
+class Cell:
+    connectivity: np.ndarray
+    offsets: np.ndarray
+    types: np.ndarray
+
+
+@dataclass
+class PolyDataTopology:
+    connectivity: np.ndarray
+    offsets: np.ndarray
+
+
+@dataclass
+class VTKDataArray:
+    Scalars: dict
+    Vectors: dict
+    Tensors: dict
+    Normals: dict
+    TCoords: dict
+
+
+@dataclass
+class Grid:
+    whole_extents: np.ndarray
+    origin: np.ndarray
+    spacing: np.ndarray
+    direction: np.ndarray
+
+    def __post_init__(self):
+        _cells = np.array([self.whole_extents[1] - self.whole_extents[0],
+                                  self.whole_extents[3] - self.whole_extents[2],
+                                  self.whole_extents[5] - self.whole_extents[4]])
+        self.num_cells = np.prod(_cells)
+        self.num_points = np.prod(_cells + 1)
+
+
+@dataclass
+class GridCoordinates:
+    x: np.ndarray
+    y: np.ndarray
+    z: np.ndarray
+    whole_extents: np.ndarray
+
+    def __post_init__(self):
+        self.num_points = np.prod([self.x.size, self.y.size, self.z.size])
+        self.num_cells = np.prod([self.x.size - 1, self.y.size - 1, self.z.size - 1])
+
+
+@dataclass
+class ImageData(VTKData):
+    grid: Grid
+
+    def __eq__(self, other):
+        return dataclass_equality_check(self, other)
+
+    def write(self, filepath, file_format='xml', xml_encoding='appended'):
+        """
+
+        Parameters
+        ----------
+        filepath : str
+        file_format : {'xml', 'vtkhdf'}, default 'xml'
+        xml_encoding : {'ascii', 'binary', 'appended'}, default='appended'
+            Encoding of XML files can be ascii, binary or appended. The default formatting is 'appended'.
+
+        """
+        if file_format in ['xml','vtkhdf', 'hdf', 'hdf5', 'vtk hdf']:
+            write_vti(filepath, whole_extent=self.grid.whole_extents, piece_extent=self.grid.whole_extents,
+                     spacing=self.grid.spacing, origin=self.grid.origin, direction=self.grid.direction,
+                     point_data=self.point_data, cell_data=self.cell_data, field_data=self.field_data,
+                     encoding=xml_encoding, file_format=file_format)
+
+        else:
+            raise NotImplementedError("This is not a supported file type")
+
+
+@dataclass
+class RectilinearData(VTKData):
+    coordinates: GridCoordinates
+
+    def __eq__(self, other):
+        return dataclass_equality_check(self, other)
+
+    def write(self, filepath, file_format='xml', xml_encoding='appended'):
+        """
+
+        Parameters
+        ----------
+        filepath : str
+        file_format : {'xml', 'vtkhdf'}, default 'xml'
+        xml_encoding : {'ascii', 'binary', 'appended'}, default='appended'
+            Encoding of XML files can be ascii, binary or appended. The default formatting is 'appended'.
+
+        """
+        if file_format in ['xml','vtkhdf', 'hdf', 'hdf5', 'vtk hdf']:
+            write_vtr(filepath, self.coordinates.x, self.coordinates.y, self.coordinates.z,
+                     whole_extent=self.coordinates.whole_extents, piece_extent=self.coordinates.whole_extents,
+                     point_data=self.point_data, cell_data=self.cell_data, field_data=self.field_data,
+                     encoding=xml_encoding, file_format=file_format)
+
+        else:
+            raise NotImplementedError("This is not a supported file type")
+
+
+@dataclass
+class StructuredData(VTKData):
+    points: np.ndarray
+    whole_extents: np.ndarray
+
+    def __post_init__(self):
+        self.num_points = self.points.shape[0]
+        self.num_cells = np.prod([self.whole_extents[1] - self.whole_extents[0],
+                                  self.whole_extents[3] - self.whole_extents[2],
+                                  self.whole_extents[5] - self.whole_extents[4]])
+
+    def __eq__(self, other):
+        return dataclass_equality_check(self, other)
+
+    def write(self, filepath, file_format='xml', xml_encoding='appended'):
+        """
+        Write the data to a file.
+
+        This function writes the data to a file in either XML or HDF5 format.
+        The file format is determined by the `file_format` parameter.
+
+        
+        Parameters
+        ----------
+        filepath : str
+        file_format : {'xml', 'vtkhdf'}, default 'xml'
+        xml_encoding : {'ascii', 'binary', 'appended'}, default='appended'
+            Encoding of XML files can be ascii, binary or appended. The default formatting is 'appended'.
+
+        """
+        if file_format in ['xml','vtkhdf', 'hdf', 'hdf5', 'vtk hdf']:
+            write_vts(filepath, self.points, whole_extent=self.whole_extents, piece_extent=self.whole_extents,
+                     point_data=self.point_data, cell_data=self.cell_data, field_data=self.field_data,
+                     encoding=xml_encoding, file_format=file_format)
+
+        else:
+            raise NotImplementedError("This is not a supported file type")
+
+
+@dataclass
+class UnstructuredGrid(VTKData):
+    points: np.ndarray
+    cells: Cell
+
+    def __eq__(self, other):
+        return dataclass_equality_check(self, other)
+
+    def write(self, filepath, file_format='xml', xml_encoding='appended'):
+        """
+
+        Parameters
+        ----------
+        filepath : str
+        file_format : {'xml', 'vtkhdf'}, default 'xml'
+        xml_encoding : {'ascii', 'binary', 'appended'}, default='appended'
+            Encoding of XML files can be ascii, binary or appended. The default formatting is 'appended'.
+
+        """
+        if file_format in ['xml','vtkhdf', 'hdf', 'hdf5', 'vtk hdf']:
+            write_vtu(filepath, nodes=self.points, cell_type=self.cells.types, connectivity=self.cells.connectivity,
+                     offsets=self.cells.offsets, point_data=self.point_data, cell_data=self.cell_data,
+                     field_data=self.field_data, encoding=xml_encoding, file_format=file_format)
+
+        else:
+            raise NotImplementedError("This is not a supported file type")
+
+
+@dataclass
+class PolyData(VTKData):
+    points: np.ndarray
+    verts: PolyDataTopology
+    lines: PolyDataTopology
+    strips: PolyDataTopology
+    polys: PolyDataTopology
+
+    def __eq__(self, other):
+        return dataclass_equality_check(self, other)
+
+    def write(self, filepath, file_format='xml', xml_encoding='appended'):
+        """
+
+        Parameters
+        ----------
+        filepath : str
+        file_format : {'xml', 'vtkhdf'}, default 'xml'
+        xml_encoding : {'ascii', 'binary', 'appended'}, default='appended'
+            Encoding of XML files can be ascii, binary or appended. The default formatting is 'appended'.
+
+        """
+        lines = None
+        verts = None
+        strips = None
+        polys = None
+
+        # check for none
+        if self.lines:
+            lines = astuple(self.lines)
+        if self.strips:
+            strips = astuple(self.strips)
+        if self.polys:
+            polys = astuple(self.polys)
+        if self.verts:
+            verts = astuple(self.verts)
+
+        if file_format in ['xml','vtkhdf', 'hdf', 'hdf5', 'vtk hdf']:
+
+            write_vtp(filepath, points=self.points, verts=verts, lines=lines, strips=strips, polys=polys,
+                     point_data=self.point_data, cell_data=self.cell_data, field_data=self.field_data,
+                     encoding=xml_encoding, file_format=file_format,)
+
+        else:
+            raise NotImplementedError("This is not a supported file type")