iorec 1.1.0__py3-none-any.whl

iorec/__init__.py

@@ -0,0 +1,21 @@
+"""IO for .rec meshes in 3D or 2D.
+
+Matthieu Perez (2023)
+"""
+
+from iorec._validation import RecFormatError
+from iorec.rec_2d import load_2d_rec, load_2d_rec_with_metadata, save_2d_rec
+from iorec.rec_3d import load_rec, load_rec_with_metadata, save_rec
+from iorec.rec_appendix import load_rec_appendix, write_rec_appendix
+
+__all__ = (
+    "RecFormatError",
+    "load_2d_rec",
+    "load_2d_rec_with_metadata",
+    "load_rec",
+    "load_rec_appendix",
+    "load_rec_with_metadata",
+    "save_2d_rec",
+    "save_rec",
+    "write_rec_appendix",
+)

iorec/_utils.py

@@ -0,0 +1,139 @@
+"""Shared helpers for .rec/.arec files, used by both the 2D and 3D readers."""
+
+from __future__ import annotations
+
+import warnings
+from pathlib import Path
+from typing import Any, Callable, TextIO
+
+import numpy as np
+from numpy.typing import NDArray
+
+from iorec._validation import RecFormatError, _parse_count
+from iorec.rec_appendix import _iorec_version, write_rec_appendix
+
+
+def _resolve_rec_path(filename: str | Path) -> Path:
+    filename = Path(filename).resolve()
+    if not filename.exists():
+        error = f"{filename} not found."
+        raise FileNotFoundError(error)
+    if filename.suffix not in (".rec", ".arec"):
+        error = f"{filename} is not a .rec or .arec file."
+        raise ValueError(error)
+    return filename
+
+
+def _is_binary_bytes(data: bytes, chunk_size: int = 64) -> bool:
+    return b"\x00" in data[:chunk_size]
+
+
+def _is_binary(file_name: Path, chunk_size: int = 64) -> bool:
+    with Path.open(file_name, "rb") as f:
+        return _is_binary_bytes(f.read(chunk_size), chunk_size)
+
+
+def _write_geometry_with_appendix(
+    filename: str | Path,
+    write_geometry: Callable[[], None],
+    metadata: dict[str, Any] | None,
+    written_by: str | None = None,
+) -> None:
+    """Write geometry, then an optional trailing metadata appendix.
+
+    `write_geometry` must write the full geometry file at `filename` (binary or text
+    mode); the appendix, if any, is appended afterwards so it stays trailing.
+
+    `written_by` names the program that produced the mesh. When `None`, iorec's own
+    version is stamped instead, unchanged from before this parameter existed. When
+    given, iorec's own version is stamped on a separate `writer_library` line instead,
+    so both facts survive.
+    """
+    appendix_bytes = None
+    if metadata is not None:
+        if written_by is None:
+            appendix_bytes = write_rec_appendix(metadata, written_by=_iorec_version())
+        else:
+            appendix_bytes = write_rec_appendix(
+                metadata,
+                written_by=written_by,
+                writer_library=f"iorec {_iorec_version()}",
+            )
+
+    write_geometry()
+
+    if appendix_bytes is not None:
+        with Path(filename).open("ab") as file:
+            file.write(appendix_bytes)
+
+
+def _read_text_count(
+    f: TextIO,
+    filename: Path | str,
+    what: str,
+    *,
+    validate: bool,
+) -> int:
+    """Read one count line of a text .rec file."""
+    line = f.readline()
+    if validate:
+        return _parse_count(filename, line, what)
+    return int(line.strip())
+
+
+def _read_text_rows(
+    f: TextIO,
+    count: int,
+    dtype: type[np.float64] | type[np.int64],
+    columns: int,
+    filename: Path | str,
+    what: str,
+    *,
+    validate: bool,
+) -> NDArray[Any]:
+    """Read `count` rows of a text .rec block, stopping exactly after the last one.
+
+    Without `validate`, behaviour is unchanged from earlier versions: `np.loadtxt`
+    errors propagate as they are, and a short block is returned short. With
+    `validate`, parse errors become `RecFormatError` and the caller checks the shape.
+    """
+    if count <= 0:
+        return np.empty((0, columns), dtype=dtype)
+    if not validate:
+        return np.loadtxt(f, max_rows=count, dtype=dtype, ndmin=2)
+    try:
+        with warnings.catch_warnings():
+            # An empty block is reported by the shape check, with the file name.
+            warnings.simplefilter("ignore", UserWarning)
+            return np.loadtxt(f, max_rows=count, dtype=dtype, ndmin=2)
+    except ValueError as exc:
+        error = f"{filename}: invalid {what} block: {exc}"
+        raise RecFormatError(error) from exc
+
+
+def _format_text_rec(
+    points: NDArray[Any],
+    cells: NDArray[Any],
+    labels: NDArray[Any],
+    dimension: int,
+) -> str:
+    """Return the text of a .rec file: counts, one row per point and per cell.
+
+    Each value is written with `repr` (the shortest text that reads back to the same
+    float64, or the integer's digits), exactly as formatting each NumPy scalar in an
+    f-string did in earlier versions; `tolist()` turns the scalars into Python numbers
+    without changing their values. Each block is built with one `%` operation instead
+    of a Python loop over rows.
+    """
+    points = np.asarray(points)[:, :dimension]
+    records = np.empty((len(cells), dimension + 2), dtype=object)
+    records[:, :dimension] = np.asarray(cells)[:, :dimension]
+    records[:, dimension:] = np.asarray(labels)[:, :2]
+    point_row = " ".join(["%r"] * dimension) + "\n"
+    record_row = " ".join(["%r"] * (dimension + 2)) + "\n"
+    return (
+        f"{len(points)}\n"
+        + (point_row * len(points)) % tuple(points.reshape(-1).tolist())
+        + f"{len(records)}\n"
+        + (record_row * len(records)) % tuple(records.reshape(-1).tolist())
+    )

iorec/_validation.py

@@ -0,0 +1,153 @@
+"""Opt-in structural checks for .rec/.arec files, run by the readers on `validate=True`.
+
+Without `validate=True` the readers keep their historical, permissive behaviour: a
+truncated file, a 2D file read as 3D, or out-of-range indices are returned as they come.
+With it, any such problem raises `RecFormatError`, a `ValueError` subclass, naming the
+file and the first offending record.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+from numpy.typing import NDArray
+
+from iorec.rec_appendix import _appendix_marker
+
+
+class RecFormatError(ValueError):
+    """Raised by the readers, with `validate=True`, for a malformed .rec/.arec file."""
+
+
+def _binary_geometry_size(
+    number_of_points: int,
+    number_of_cells: int,
+    dimension: int,
+    record_itemsize: int,
+) -> int:
+    """Return the exact byte size of a binary geometry block (without appendix)."""
+    return 8 + 8 * dimension * number_of_points + 8 + record_itemsize * number_of_cells
+
+
+def _check_binary_room(
+    filename: Path | str,
+    available: int,
+    required: int,
+    what: str,
+) -> None:
+    """Raise if fewer than `required` bytes are available for the block `what`."""
+    if required > available:
+        error = (
+            f"{filename}: truncated binary {what} "
+            f"({available} bytes available, {required} needed)."
+        )
+        raise RecFormatError(error)
+
+
+def _check_binary_tail(filename: Path | str, tail: bytes) -> None:
+    """Raise unless the bytes after the geometry are empty or a metadata appendix."""
+    if tail and not tail.startswith(_appendix_marker()):
+        error = (
+            f"{filename}: {len(tail)} unexpected trailing bytes after the binary "
+            "geometry (not a rec-appendix block)."
+        )
+        raise RecFormatError(error)
+
+
+def _check_text_tail(filename: Path | str, tail: str) -> None:
+    """Raise unless the text after the geometry is blank or a metadata appendix."""
+    stripped = tail.lstrip()
+    if stripped and not stripped.startswith(_appendix_marker().decode("ascii")):
+        error = (
+            f"{filename}: unexpected content after the last record "
+            "(not a rec-appendix block)."
+        )
+        raise RecFormatError(error)
+
+
+def _parse_count(filename: Path | str, line: str, what: str) -> int:
+    """Parse a text count line strictly."""
+    try:
+        value = int(line.strip())
+    except ValueError as exc:
+        error = f"{filename}: invalid {what} count {line.strip()!r}."
+        raise RecFormatError(error) from exc
+    if value < 0:
+        error = f"{filename}: {what} count must be non-negative, got {value}."
+        raise RecFormatError(error)
+    return value
+
+
+def _check_mesh(
+    filename: Path | str,
+    points: NDArray[np.float64],
+    cells: NDArray[np.int64],
+    labels: NDArray[np.int64],
+    dimension: int,
+    counts: tuple[int, int],
+) -> None:
+    """Check shapes, coordinates, indices and labels of a parsed mesh.
+
+    Args:
+        filename: used in error messages only.
+        points: parsed points, expected shape `(counts[0], dimension)`.
+        cells: parsed triangles (3D) or segments (2D), expected shape
+            `(counts[1], dimension)`.
+        labels: parsed labels, expected shape `(counts[1], 2)`.
+        dimension: 3 for triangle meshes, 2 for segment meshes.
+        counts: the point and cell counts declared in the file.
+
+    Raises:
+        RecFormatError: on the first violated condition.
+    """
+    number_of_points, number_of_cells = counts
+    cell_name = "triangle" if dimension == 3 else "segment"
+    expected = {
+        "points": (points, (number_of_points, dimension)),
+        f"{cell_name}s": (cells, (number_of_cells, dimension)),
+        "labels": (labels, (number_of_cells, 2)),
+    }
+    for name, (array, shape) in expected.items():
+        if array.shape != shape:
+            error = (
+                f"{filename}: {name} have shape {array.shape}, expected {shape} "
+                f"(file declares {number_of_points} points and {number_of_cells} "
+                f"{cell_name}s in {dimension}D)."
+            )
+            raise RecFormatError(error)
+
+    not_finite = np.flatnonzero(~np.isfinite(points).all(axis=1))
+    if not_finite.size:
+        error = f"{filename}: point {not_finite[0]} has a non-finite coordinate."
+        raise RecFormatError(error)
+
+    if number_of_cells:
+        out_of_range = np.flatnonzero(
+            ((cells < 0) | (cells >= number_of_points)).any(axis=1),
+        )
+        if out_of_range.size:
+            first = out_of_range[0]
+            error = (
+                f"{filename}: {cell_name} {first} has a vertex index outside "
+                f"[0, {number_of_points}): {cells[first].tolist()}."
+            )
+            raise RecFormatError(error)
+
+        negative = np.flatnonzero((labels < 0).any(axis=1))
+        if negative.size:
+            first = negative[0]
+            error = (
+                f"{filename}: {cell_name} {first} has a negative label: "
+                f"{labels[first].tolist()}."
+            )
+            raise RecFormatError(error)
+
+        same = np.flatnonzero(labels[:, 0] == labels[:, 1])
+        if same.size:
+            first = same[0]
+            error = (
+                f"{filename}: {cell_name} {first} separates label "
+                f"{labels[first, 0]} from itself."
+            )
+            raise RecFormatError(error)

iorec/rec_2d.py

@@ -0,0 +1,390 @@
+"""IO for 2D .rec meshes."""
+
+from __future__ import annotations
+
+import io
+import struct
+from pathlib import Path
+from typing import Any, TextIO
+
+import numpy as np
+from numpy.typing import NDArray
+
+from iorec._utils import (
+    _format_text_rec,
+    _is_binary,
+    _is_binary_bytes,
+    _read_text_count,
+    _read_text_rows,
+    _resolve_rec_path,
+    _write_geometry_with_appendix,
+)
+from iorec._validation import (
+    RecFormatError,
+    _binary_geometry_size,
+    _check_binary_room,
+    _check_binary_tail,
+    _check_mesh,
+    _check_text_tail,
+)
+from iorec.rec_appendix import _appendix_marker, _split_rec_bytes
+
+
+def load_2d_rec(
+    filename: str | Path,
+    *,
+    validate: bool = False,
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64]]:
+    """Read a 2D rec mesh file.
+
+    Args:
+        filename (str | Path): The path to the file on disk.
+        validate (bool, optional): Check the file's structure and content, as
+            `load_rec` does with `validate=True`, for segments instead of triangles.
+            Defaults to False.
+
+    Raises:
+        ValueError: If the path given is not a .rec or .arec file.
+        FileNotFoundError: If the file doesn't exist.
+        RecFormatError: With `validate=True`, if the file is malformed (a
+            `ValueError` subclass).
+
+    Returns:
+        tuple[np.array, np.array, np.array]: (points, segments, labels), with:
+        - points: np.array of shape (num_points, 2) (float64)
+        - segments: np.array of shape (num_segments, 2) (int64)
+        - labels: np.array of shape (num_segments, 2) (int64)
+    """
+    filename = _resolve_rec_path(filename)
+    return _load_2d_rec_file(filename, validate=validate)
+
+
+def load_2d_rec_with_metadata(
+    filename: str | Path,
+    *,
+    validate: bool = False,
+) -> tuple[
+    NDArray[np.float64],
+    NDArray[np.int64],
+    NDArray[np.int64],
+    dict[str, Any] | None,
+]:
+    """Read a 2D rec mesh file together with its metadata appendix, if any.
+
+    Reads the file once and splits geometry from metadata in memory -- unlike calling
+    `load_2d_rec` and `load_rec_appendix` separately, which would each read the whole
+    file on their own.
+
+    Args:
+        filename (str | Path): The path to the file on disk.
+        validate (bool, optional): Check the geometry as `load_2d_rec` does with
+            `validate=True`. Defaults to False.
+
+    Raises:
+        ValueError: If the path given is not a .rec or .arec file.
+        FileNotFoundError: If the file doesn't exist.
+        RecFormatError: With `validate=True`, if the file is malformed (a
+            `ValueError` subclass).
+
+    Returns:
+        tuple[np.array, np.array, np.array, dict | None]: (points, segments, labels,
+        metadata), with points/segments/labels as in `load_2d_rec`, and metadata as in
+        `load_rec_appendix` (`None` if the file has no appendix).
+    """
+    filename = _resolve_rec_path(filename)
+    geometry_bytes, metadata = _split_rec_bytes(filename.read_bytes())
+
+    if _is_binary_bytes(geometry_bytes):
+        points, segments, labels = _parse_2d_binary_rec_bytes(
+            geometry_bytes,
+            validate=validate,
+            filename=filename,
+        )
+    else:
+        points, segments, labels = _parse_2d_text_rec_bytes(
+            geometry_bytes,
+            validate=validate,
+            filename=filename,
+        )
+
+    return points, segments, labels, metadata
+
+
+# On-disk layout of binary files: little-endian whatever the machine. Existing files
+# come from little-endian machines (x86-64, arm64), where this changes nothing; on a
+# big-endian machine, files stay readable and portable instead of byte-swapped.
+_DTYPE_SEGMENTS_AND_LABELS = np.dtype(
+    [("segments", "<i8", (2,)), ("labels", "<i4", (2,))],
+)
+_DTYPE_POINTS = np.dtype("<f8")
+
+
+def _load_2d_rec_file(
+    filename: Path,
+    *,
+    validate: bool = False,
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64]]:
+    if _is_binary(filename):
+        return _load_2d_binary_rec_file(filename, validate=validate)
+    else:
+        return _load_2d_text_rec_file(filename, validate=validate)
+
+
+def _load_2d_binary_rec_file(
+    filename: Path,
+    *,
+    validate: bool = False,
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64]]:
+    size = filename.stat().st_size if validate else 0
+    with Path.open(filename, "rb") as f:
+        # First we read the number of vertices
+        header = f.read(8)
+        if validate:
+            _check_binary_room(filename, len(header), 8, "point count")
+        (number_of_points,) = struct.unpack("<Q", header)
+        if validate:
+            _check_binary_room(filename, size - 8, 16 * number_of_points + 8, "points")
+        # Then we read the vertices : they are in a 2D space
+        points = (
+            np.fromfile(f, count=2 * number_of_points, dtype=_DTYPE_POINTS)
+            .reshape((number_of_points, 2))
+            .astype(np.float64, copy=False)
+        )
+
+        # Number of segments
+        (number_of_segments,) = struct.unpack("<Q", f.read(8))
+        geometry_size = _binary_geometry_size(
+            number_of_points,
+            number_of_segments,
+            2,
+            _DTYPE_SEGMENTS_AND_LABELS.itemsize,
+        )
+        if validate:
+            _check_binary_room(filename, size, geometry_size, "segments")
+        # Each line defines a segment and 2 regions labels
+        segments_and_labels = np.fromfile(
+            f,
+            count=number_of_segments,
+            dtype=_DTYPE_SEGMENTS_AND_LABELS,
+        )
+        if validate:
+            _check_binary_tail(filename, f.read(len(_appendix_marker())))
+
+    segments = segments_and_labels["segments"].astype(np.int64)
+    labels = segments_and_labels["labels"].astype(np.int64)
+    if validate:
+        counts = (number_of_points, number_of_segments)
+        _check_mesh(filename, points, segments, labels, 2, counts)
+    return points, segments, labels
+
+
+def _load_2d_text_rec_file(
+    filename: Path,
+    *,
+    validate: bool = False,
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64]]:
+    with Path.open(filename) as f:
+        return _read_2d_text_rec(f, filename, validate=validate)
+
+
+def _read_2d_text_rec(
+    f: TextIO,
+    filename: Path | str,
+    *,
+    validate: bool,
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64]]:
+    """Read 2D text-mode geometry from an open stream (a file or a buffer)."""
+    # First we read the number of vertices
+    number_of_points = _read_text_count(f, filename, "point", validate=validate)
+    # Then we read the vertices : they are in a 2D space
+    points = _read_text_rows(
+        f,
+        number_of_points,
+        np.float64,
+        2,
+        filename,
+        "point",
+        validate=validate,
+    )
+
+    # Number of segments
+    number_of_segments = _read_text_count(f, filename, "segment", validate=validate)
+    # Each line defines a segment and 2 regions labels
+    segments_and_labels = _read_text_rows(
+        f,
+        number_of_segments,
+        np.int64,
+        4,
+        filename,
+        "segment",
+        validate=validate,
+    )
+    segments = segments_and_labels[:, 0:2]
+    labels = segments_and_labels[:, 2:4]
+
+    if validate:
+        if segments_and_labels.shape[1:] != (4,):
+            error = (
+                f"{filename}: segment records have {segments_and_labels.shape[1]} "
+                "columns, expected 4 (two vertex indices and two labels)."
+            )
+            raise RecFormatError(error)
+        _check_text_tail(filename, f.read())
+        counts = (number_of_points, number_of_segments)
+        _check_mesh(filename, points, segments, labels, 2, counts)
+    return points, segments, labels
+
+
+def _parse_2d_binary_rec_bytes(
+    data: bytes,
+    *,
+    validate: bool = False,
+    filename: Path | str = "<buffer>",
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64]]:
+    """Parse geometry from an in-memory buffer.
+
+    E.g. the geometry half of a buffer already split by
+    `iorec.rec_appendix._split_rec_bytes`.
+
+    Kept separate from `_load_2d_binary_rec_file` (which streams from disk with
+    `np.fromfile`) rather than unifying the two: unifying would make plain
+    `load_2d_rec` hold the whole file in memory as `bytes` *and* as the parsed array at
+    once, which for very large files is a real peak-memory regression that
+    `load_2d_rec` shouldn't pay just so `load_2d_rec_with_metadata` can avoid a second
+    read.
+    """
+    if validate:
+        _check_binary_room(filename, len(data), 8, "point count")
+    (number_of_points,) = struct.unpack_from("<Q", data)
+    offset = 8
+    points_count = 2 * number_of_points
+    if validate:
+        _check_binary_room(filename, len(data) - 8, 8 * points_count + 8, "points")
+    points = (
+        np.frombuffer(data, dtype=_DTYPE_POINTS, count=points_count, offset=offset)
+        .reshape((number_of_points, 2))
+        .astype(np.float64)  # a native-endian copy, not a view on `data`
+    )
+    offset += points_count * 8
+
+    (number_of_segments,) = struct.unpack_from("<Q", data, offset)
+    offset += 8
+    if validate:
+        geometry_size = _binary_geometry_size(
+            number_of_points,
+            number_of_segments,
+            2,
+            _DTYPE_SEGMENTS_AND_LABELS.itemsize,
+        )
+        _check_binary_room(filename, len(data), geometry_size, "segments")
+        _check_binary_tail(filename, data[geometry_size:])
+    segments_and_labels = np.frombuffer(
+        data,
+        dtype=_DTYPE_SEGMENTS_AND_LABELS,
+        count=number_of_segments,
+        offset=offset,
+    )
+
+    segments = segments_and_labels["segments"].astype(np.int64)
+    labels = segments_and_labels["labels"].astype(np.int64)
+    if validate:
+        counts = (number_of_points, number_of_segments)
+        _check_mesh(filename, points, segments, labels, 2, counts)
+    return points, segments, labels
+
+
+def _parse_2d_text_rec_bytes(
+    data: bytes,
+    *,
+    validate: bool = False,
+    filename: Path | str = "<buffer>",
+) -> tuple[NDArray[np.float64], NDArray[np.int64], NDArray[np.int64]]:
+    """Parse geometry from an in-memory buffer.
+
+    Shares `_read_2d_text_rec` with `_load_2d_text_rec_file`: text parsing reads line
+    by line from a stream in both cases, so there is no peak-memory reason to keep two
+    copies.
+    """
+    with io.StringIO(data.decode()) as f:
+        return _read_2d_text_rec(f, filename, validate=validate)
+
+
+def save_2d_rec(
+    filename: str | Path,
+    points: NDArray[np.float64],
+    segments: NDArray[np.int64],
+    labels: NDArray[np.int64],
+    binary_mode: bool = False,
+    *,
+    metadata: dict[str, Any] | None = None,
+    written_by: str | None = None,
+) -> None:
+    """Save a 2D rec mesh file at filename. Binary or text mode are available.
+
+    Binary mode is more compact but might not be universally understood.
+
+    Both modes store every value exactly. Binary mode writes float64 coordinates,
+    int64 indices and int32 labels, little-endian on every machine, converting arrays
+    of other dtypes. Text mode writes each value with `repr`, the shortest text that
+    reads back to the same float64.
+
+    Args:
+        filename (str | Path): where to save the mesh file.
+        points (NDArray[np.float64]): Mesh points.
+        segments (NDArray[np.int64]): Mesh segments (topology).
+        labels (NDArray[np.int64]): Segments multimaterial labels.
+        binary_mode (bool, optional): Choose binary mode. Defaults to False.
+        metadata (dict[str, Any] | None, optional): appendix fields, e.g.
+            `coordinate_frame`, `axis_order`, `spacing`, `spacing_unit`,
+            `source_shape`, `crop_offset`. Defaults to `None`, which writes nothing
+            extra -- byte-for-byte the same file as before this option existed. When
+            supplied, a trailing metadata appendix is appended after the geometry data;
+            see `iorec.rec_appendix.write_rec_appendix`.
+        written_by (str | None, optional): a version string identifying the program
+            that produced the mesh, stamped on the appendix's `written_by` line.
+            Defaults to `None`, which stamps iorec's own version there instead --
+            unchanged from before this parameter existed. When supplied, iorec's own
+            version is stamped on a separate `writer_library` line instead, so both
+            facts survive: what produced the mesh, and what serialised it. Has no
+            effect if `metadata` is `None`, since no appendix is written in that case.
+    """
+
+    def write_geometry() -> None:
+        if binary_mode:
+            _save_2d_rec_binary(filename, points, segments, labels)
+        else:
+            _save_2d_rec_text(filename, points, segments, labels)
+
+    _write_geometry_with_appendix(filename, write_geometry, metadata, written_by)
+
+
+def _save_2d_rec_binary(
+    filename: str | Path,
+    points: NDArray[np.float64],
+    segments: NDArray[np.int64],
+    labels: NDArray[np.int64],
+) -> None:
+    """Save a 2D rec file at filename. Binary only."""
+    records = np.empty(len(segments), dtype=_DTYPE_SEGMENTS_AND_LABELS)
+    records["segments"] = segments
+    records["labels"] = labels
+
+    bytes_content = struct.pack("<Q", len(points))
+    bytes_content += np.ascontiguousarray(points, dtype=_DTYPE_POINTS).tobytes()
+    bytes_content += struct.pack("<Q", len(segments))
+    bytes_content += records.tobytes()
+    with Path(filename).open("wb") as file:
+        file.write(bytes_content)
+
+
+def _save_2d_rec_text(
+    filename: str | Path,
+    points: NDArray[np.float64],
+    segments: NDArray[np.int64],
+    labels: NDArray[np.int64],
+) -> None:
+    """Save a 2D rec file at filename. Text only."""
+    content = _format_text_rec(points, segments, labels, 2)
+
+    with Path(filename).open("w") as file:
+        file.write(content)