rsqsim_api.io.mesh_utils
========================

.. py:module:: rsqsim_api.io.mesh_utils

.. autoapi-nested-parse::

   Utilities for converting between triangulated mesh formats and NumPy arrays.



Attributes
----------

.. autoapisummary::

   rsqsim_api.io.mesh_utils.expected_formats


Functions
---------

.. autoapisummary::

   rsqsim_api.io.mesh_utils.change_mesh_format
   rsqsim_api.io.mesh_utils.mesh_to_array
   rsqsim_api.io.mesh_utils.convert_multi
   rsqsim_api.io.mesh_utils.array_to_mesh
   rsqsim_api.io.mesh_utils.tri_slip_rake_to_mesh
   rsqsim_api.io.mesh_utils.quads_to_vtk


Module Contents
---------------

.. py:data:: expected_formats
   :value: ['stl', 'obj', 'e', 'txt']


.. py:function:: change_mesh_format(in_mesh, out_format, out_mesh = None)

   Convert a mesh file from one format to another.

   Reads the input mesh with meshio and writes it in the requested output
   format.  If ``out_format`` is ``"txt"``, the mesh is converted to a
   flat NumPy array and saved with ``numpy.savetxt``.

   :param in_mesh: Path to the input mesh file (any format supported by meshio).
   :param out_format: Target format.  Must be one of ``"stl"``, ``"obj"``, ``"e"``,
                      or ``"txt"``.
   :param out_mesh: Output file path.  If ``None``, the input file stem is reused
                    with the new extension.

   :raises AssertionError: If ``in_mesh`` does not exist or ``out_format`` is not in the
       allowed list.


.. py:function:: mesh_to_array(mesh)

   Convert a meshio Mesh to a flat NumPy triangle array.

   Expands the indexed triangle representation into a dense array where
   each row contains the (x, y, z) coordinates of all three corner
   vertices of one triangle.

   :param mesh: meshio Mesh object containing at least one set of triangular cells.

   :returns: Each row is ``[x1,y1,z1, x2,y2,z2, x3,y3,z3]``.
   :rtype: numpy.ndarray of shape (n_triangles, 9)

   :raises AssertionError: If the mesh contains no triangular cells.


.. py:function:: convert_multi(search_string, out_format)

   Convert all mesh files matching a glob pattern to a target format.

   :param search_string: Glob pattern used to find input mesh files, e.g.
                         ``"/path/to/meshes/*.stl"``.
   :param out_format: Target format passed to :func:`change_mesh_format`.

   :raises AssertionError: If no files match ``search_string``.


.. py:function:: array_to_mesh(triangle_array)

   Convert a flat triangle array to a meshio Mesh object.

   Deduplicates the vertices across all triangles and builds an indexed
   meshio Mesh with a single set of triangular cells.

   :param triangle_array: Each row contains the (x, y, z) coordinates of the three corner
                          vertices of one triangle: ``[x1,y1,z1, x2,y2,z2, x3,y3,z3]``.
   :type triangle_array: numpy.ndarray of shape (n_triangles, 9)

   :returns: Mesh with unique ``points`` (shape ``(n_unique_verts, 3)``) and
             triangular cells referencing them by index.
   :rtype: meshio.Mesh

   :raises AssertionError: If ``triangle_array`` does not have exactly 9 columns.


.. py:function:: tri_slip_rake_to_mesh(in_array)

   Convert a triangle array with slip and rake columns to a meshio Mesh.

   Builds a mesh from the first 9 columns (vertex coordinates) and
   attaches the slip rate and rake columns as cell data.

   :param in_array: Columns 0–8 are the (x,y,z) coordinates of the three triangle
                    corners (as in :func:`array_to_mesh`).  Column 9 is slip rate
                    in m/s and column 10 is rake in degrees.
   :type in_array: numpy.ndarray of shape (n_triangles, 11)

   :returns: Mesh with triangular cells and ``cell_data`` containing
             ``"slip_rate"`` and ``"rake"`` arrays.
   :rtype: meshio.Mesh

   :raises AssertionError: If ``in_array`` does not have exactly 11 columns.


.. py:function:: quads_to_vtk(quads)

   Convert a list of quadrilateral patches to a meshio Mesh for VTK export.

   Deduplicates vertices across all quads and builds an indexed meshio
   Mesh with quad cells.

   :param quads: Iterable of quadrilateral patches.  Each element should be an
                 array-like of shape (4, 3) giving the four corner (x, y, z)
                 coordinates in NZTM (metres).

   :returns: Mesh with unique ``points`` and ``"quad"`` cells.
   :rtype: meshio.Mesh