BF: OBJ, legacy VTK, VTK XML and Nastran correctness

docs/formats/nastran.rst

@@ -80,6 +80,7 @@ Quirks worth knowing
   here - a numeric table whose first row happens to read ``SOL 1.0 2.0`` does not.
   ``px.read("model.dat", fmt=".bdf")`` still forces the issue, and writing to ``.dat`` needs
   ``fmt=".bdf"`` because an output file has no content to inspect.
+- A real field is written in whichever legal spelling fits it: the plain form first, then the implicit-exponent shorthand the format allows (``1.234-10`` for ``1.234E-10``, ``1.2346+7`` for ``1.2346E+07``), which buys two or three significant digits in an eight-column field. A value below one drops its leading zero when that column is a significant digit, since bulk data reads ``.5`` as ``0.5``. A spelling that reads back as the value itself is always preferred to a longer one that does not, so ``1e7`` goes out as ``1.E+07`` rather than as seven nines. A value that would round up past the largest double is stepped one digit toward zero instead of being refused, so no finite coordinate fails to write.
 - Property ids become element tags, so the deck's grouping is preserved.
 
 .. seealso::

docs/formats/obj.rst

@@ -60,8 +60,14 @@ Quirks worth knowing
 .. rst-class:: px-quirks
 
 - Negative (relative) indices are resolved against the vertex count at the point the face appears, not the final count.
+- An index naming a record the file has not declared raises ``CodecError`` naming the line, rather than wrapping around into another vertex.
 - Faces with more than four vertices are kept as polygons rather than being silently triangulated.
 - Material and group keywords are read as element tags; ``.mtl`` files are not parsed.
+- ``vt`` and ``vn`` are indexed per face corner, so a file may hold more of either than it holds vertices. polyxios stores one value per vertex in ``vertex_attrs['texcoords']`` and ``vertex_attrs['normals']``: a corner assigns to its vertex, and a vertex given two different values keeps the last and warns. Records nothing indexes are kept only when there is exactly one per vertex.
+- Records that cannot be lined up with the vertices leave the attribute out entirely, on write as well as on read: an attribute that does not hold one row per vertex is warned about and left out, rather than written as faces indexing records that are not in the file. A vertex no face names carries NaN in the array and is written back as zero, since ``vt nan nan`` is not a record another OBJ reader takes.
+- A face belonging to no group is written after a bare ``g``, so it does not inherit the group of the face above it; a bare ``g`` on read clears the active groups rather than inventing a ``default`` tag.
+- A ``v``, ``vn`` or ``vt`` record that does not carry the components its directive needs, or carries something that is not a number, raises ``CodecError`` naming the line. A ``vt`` may carry a third component - the depth of a volumetric texture - and ``texcoords`` keeps the two a surface uses.
+- ``element_attrs['material']`` is written as ``usemtl`` only when it holds one value per face; a shorter attribute is warned about and left out, the way an ill-fitting vertex attribute is.
 
 .. seealso::
 

docs/formats/vti.rst

@@ -67,10 +67,13 @@ Quirks worth knowing
 
 .. rst-class:: px-quirks
 
+- Multi-component attributes are cut into tuples with ``NumberOfComponents``, so an ``(n, 3)`` vector reads back with its shape rather than as ``3n`` rows.
 - Both the coordinates and the connectivity are materialised on read. A file of a few hundred bytes can expand to a large in-memory mesh, because the extent is all it takes to describe one.
 - ``Origin`` defaults to ``0 0 0`` and ``Spacing`` to ``1 1 1`` when the attributes are absent.
 - A ``<Piece>`` may restate a sub-extent of ``WholeExtent``; the piece's own extent is what gets expanded.
 - ``lazy=True`` raises :class:`~polyxios.exceptions.LazyReadError`.
+- Attributes are written in the type their array is held in, so an integer identifier keeps every digit rather than being rounded through a double.
+- An extent flat along an axis - an image one voxel deep - is a sheet of quads, and one flat along two axes is a run of lines. Only a fully three-dimensional extent expands to hexahedra; reading a flat one as a grid of no cells leaves every ``CellData`` array belonging to nothing.
 
 .. seealso::
 

docs/formats/vtk.rst

@@ -24,11 +24,11 @@ Specification at a glance
    * - data mode
      - ASCII or BINARY (binary payload is big-endian)
    * - dataset types
-     - STRUCTURED_POINTS, STRUCTURED_GRID, RECTILINEAR_GRID, POLYDATA, UNSTRUCTURED_GRID
+     - STRUCTURED_POINTS, STRUCTURED_GRID, RECTILINEAR_GRID, POLYDATA, UNSTRUCTURED_GRID, FIELD
    * - connectivity
      - CELLS <n> <size> followed by CELL_TYPES <n> integer codes
    * - attributes
-     - POINT_DATA / CELL_DATA with SCALARS, VECTORS, NORMALS, FIELD
+     - POINT_DATA / CELL_DATA with SCALARS, COLOR_SCALARS, VECTORS, NORMALS, TENSORS, TEXTURE_COORDINATES, FIELD
 
 .. rst-class:: px-speclink
 
@@ -80,6 +80,23 @@ Quirks worth knowing
 - Binary files can be memory-mapped with ``lazy=True``; ASCII files must be parsed end to end before any value is available.
 - Cell type codes are mapped to polyxios element types, so a file mixing triangles, quads and tetrahedra keeps every group separate.
 - Point and cell data arrays are carried through as named vertex and element attributes rather than being dropped on read.
+- ``SCALARS``, ``VECTORS``, ``NORMALS``, ``TENSORS``, ``COLOR_SCALARS``, ``TEXTURE_COORDINATES`` and ``FIELD`` sections are all read, in every dataset type - unstructured, polydata, structured points, structured grid and rectilinear grid alike. A ``LOOKUP_TABLE`` definition is a palette rather than a value per point, so it becomes no attribute, but it is counted past so the arrays after it are still found. A keyword outside that set stops the scan, and says so. ``COLOR_SCALARS`` is the one attribute whose type its own line does not name: one unsigned char per component in a binary file, a float in 0..1 in an ASCII one. The byte is scaled onto 0..1, so the same colour reads back the same from either flavour.
+- An attribute section that declares more values than the file holds raises ``CodecError`` naming the array, rather than an ``IndexError`` naming nothing in ASCII or a reshape failure naming nothing in binary.
+- ``STRUCTURED_POINTS`` keeps ``DIMENSIONS``, ``ORIGIN`` and ``SPACING`` in ``global_attrs`` (``vtk_dimensions``, ``vtk_origin``, ``vtk_spacing``); ``STRUCTURED_GRID`` and ``RECTILINEAR_GRID`` keep ``DIMENSIONS``. The points are expanded into an explicit array, so without those the grid behind them would be lost.
+- Those ``vtk_*`` entries are read-only: ``write`` always emits an ``UNSTRUCTURED_GRID`` and does not consume them.
+- ``CELL_DATA`` is read from the structured datasets as well as the unstructured ones. An array whose declared length matches neither the points nor the cells of the grid the header describes is dropped with a warning naming it, rather than reaching ``PolyData`` as a validation error about lengths.
+- A structured grid extends along whichever axes its ``DIMENSIONS`` declare: ``3 1 3`` is a sheet of quads in the x-z plane, not a run of lines, and a column along ``y`` or ``z`` is indexed with its own stride.
+- VTK 5.1 cells - the default since VTK 9.0 - are read wherever they appear: ``CELLS`` in an unstructured grid and ``POLYGONS``, ``LINES``, ``VERTICES`` or ``TRIANGLE_STRIPS`` in polydata. The two numbers on such a line are the length of the ``OFFSETS`` array and the length of ``CONNECTIVITY``, so the mesh holds one cell fewer than the first of them; the offsets are counted up to the ``CONNECTIVITY`` keyword, so a file spelling that line either way is read. ``write(..., vtk_version="5.1")`` declares the offsets length, which is what VTK's own reader expects.
+- A ``METADATA`` block - component names and information keys, written after every array by VTK 4.2 and later - is stepped over rather than read as an array. It is text even in a binary file, and it appears between the entries of a ``FIELD`` block as well as after a section.
+- A ``METADATA`` block also sits inside a v5.1 ``CELLS`` section, between its offsets and its connectivity, and is stepped over there too.
+- A ``DATASET FIELD`` file carries field arrays and no geometry. It reads as an empty :class:`~polyxios.PolyData` whose ``global_attrs`` hold the arrays, with a warning saying so.
+- Which cell spelling a v5.1 ``CELLS`` section uses is decided by what follows the header, not by the version in the first line, so a file declaring a version this reader has never heard of is still read by what it holds.
+- A ``RECTILINEAR_GRID`` takes its grid from its coordinate arrays: the points are their outer product, so a ``DIMENSIONS`` header that disagrees with them is warned about and ignored.
+- A ``STRUCTURED_GRID`` carries an explicit ``POINTS`` array, which its ``DIMENSIONS`` cannot be reconciled against the way a rectilinear grid's coordinates can. When the two disagree the points are handed back without cells, with a warning naming both counts: the cells the header describes would index points the file does not hold.
+- An attribute section is read by the count its own header declares, which is the only thing that says where one array ends and the next begins. An array that then covers no point or cell of the mesh is dropped with a warning naming it.
+- The ``LOOKUP_TABLE`` line after a ``SCALARS`` section is optional, and a binary file without one is read as such rather than losing the head of its payload.
+- A header missing a field, or spelling a count as something that is not a number, raises ``CodecError`` naming the line it is on - the byte offset, in a binary file. This covers the geometry headers - ``POINTS``, ``CELLS``, ``CELL_TYPES``, ``DIMENSIONS``, ``ORIGIN``, ``SPACING``, the coordinate arrays - as well as the attribute ones.
+- A binary block is read as the type its header names, ``POINTS`` included: an integer point array is not read at the width of a float. A type name with no numpy equivalent raises ``CodecError`` naming it rather than being guessed at, since a guessed width reads numbers the file never held. An ASCII payload is text whatever its header calls it, so it is read either way.
 
 .. seealso::
 

docs/formats/vtp.rst

@@ -61,6 +61,10 @@ Quirks worth knowing
 
 - Triangle strips are expanded into individual triangles on read; writing emits polygons rather than re-striping.
 - Each cell container becomes its own element group, so lines and polygons in one file stay distinguishable.
+- A piece that declares points and does not deliver them raises :class:`~polyxios.exceptions.CodecError`; its cells would index points that are not there, and every later piece would be shifted by the count that never arrived.
+- A point or cell array carried by only some of the pieces is dropped with a warning: joined short, its rows would sit against the wrong points from the second piece on.
+- A ``Points`` array of a type that holds no numbers - ``type="String"``, or any type this reader does not know - raises :class:`~polyxios.exceptions.CodecError` naming the type.
+- Attributes are written in the type their array is held in, so an integer identifier keeps every digit rather than being rounded through a double.
 
 .. seealso::
 

docs/formats/vtr.rst

@@ -61,6 +61,9 @@ Quirks worth knowing
 
 - The implied point grid is expanded to explicit vertices on read, so a rectilinear file behaves like any other mesh downstream.
 - Appended and base64 payloads are decoded eagerly - the XML container has no seekable layout for mmap, so ``lazy=True`` has no effect.
+- Multi-component attributes declare and honour ``NumberOfComponents``, so an ``(n, 3)`` vector survives a round trip rather than coming back as ``3n`` rows.
+- Binary arrays are written in the type their ``<DataArray>`` declares, so an integer attribute stays an integer one.
+- An extent flat along an axis - an image one voxel deep - is a sheet of quads, and one flat along two axes is a run of lines. Only a fully three-dimensional extent expands to hexahedra; reading a flat one as a grid of no cells leaves every ``CellData`` array belonging to nothing.
 
 .. seealso::
 

docs/formats/vts.rst

@@ -67,10 +67,13 @@ Quirks worth knowing
 
 .. rst-class:: px-quirks
 
-- The implicit grid is expanded to explicit hexahedral connectivity on read, so the resulting :class:`~polyxios.PolyData` carries real elements rather than an extent.
+- Multi-component attributes are cut into tuples with ``NumberOfComponents``, so an ``(n, 3)`` vector reads back with its shape rather than as ``3n`` rows.
+- The implicit grid is expanded to explicit connectivity on read, so the resulting :class:`~polyxios.PolyData` carries real elements rather than an extent.
 - That expansion is what makes a structured file cost the same as an unstructured one in memory; a large extent expands to a large connectivity array.
 - ``lazy=True`` raises :class:`~polyxios.exceptions.LazyReadError`.
 - Header counts are validated against the file size before any array is allocated.
+- Attributes are written in the type their array is held in, so an integer identifier keeps every digit rather than being rounded through a double.
+- An extent flat along an axis - an image one voxel deep - is a sheet of quads, and one flat along two axes is a run of lines. Only a fully three-dimensional extent expands to hexahedra; reading a flat one as a grid of no cells leaves every ``CellData`` array belonging to nothing.
 
 .. seealso::
 

docs/formats/vtu.rst

@@ -70,7 +70,11 @@ Quirks worth knowing
 .. rst-class:: px-quirks
 
 - Multiple ``<Piece>`` elements are concatenated into one :class:`~polyxios.PolyData`, with each piece's connectivity shifted by the running vertex count.
+- A piece that declares points and does not deliver them raises :class:`~polyxios.exceptions.CodecError`; its cells would index points that are not there, and every later piece would be shifted by the count that never arrived.
+- A point or cell array carried by only some of the pieces is dropped with a warning: joined short, its rows would sit against the wrong points from the second piece on.
+- A ``Points`` array of a type that holds no numbers - ``type="String"``, or any type this reader does not know - raises :class:`~polyxios.exceptions.CodecError` naming the type.
 - VTK cell type codes with no polyxios equivalent are dropped rather than guessed at.
+- Attributes are written in the type their array is held in, so an integer identifier keeps every digit rather than being rounded through a double.
 - ``lazy=True`` raises :class:`~polyxios.exceptions.LazyReadError`; the payload may be compressed or base64-encoded, neither of which can be memory-mapped.
 - Header counts are validated against the file size before any array is allocated.