crgutils 0.1.0__tar.gz

crgutils-0.1.0/PKG-INFO

@@ -0,0 +1,173 @@
+Metadata-Version: 2.3
+Name: crgutils
+Version: 0.1.0
+Summary: Add your description here
+Author: coder
+Author-email: coder <coder@timeintegral.ai>
+Requires-Dist: numpy>=1.26
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# crgutils
+
+`crgutils` is a Python library for loading, validating, and evaluating ASAM OpenCRG road surface files.
+
+Supported formats and capabilities:
+
+- ASCII `.crg` inputs in `LRFI` and `LDFI` formats
+- Binary `.crg` inputs in `KRBI` and `KDBI` formats
+- Road-space queries `(u, v) → z`, `(u, v) → (x, y)`, `(u, v) → (phi, kappa)`
+- World-space queries `(x, y) → z`, `(x, y) → (u, v)`, `(x, y) → (phi, kappa)`
+- All five border modes: `NONE`, `EX_ZERO`, `EX_KEEP`, `REPEAT`, `REFLECT`
+- Header-defined evaluation options and pending runtime modifiers
+
+## Install
+
+Core package:
+
+```bash
+uv sync
+```
+
+Core package with test dependencies:
+
+```bash
+uv sync --extra dev
+```
+
+If you also want the demo workspace members, especially the visualizer's extra dependencies:
+
+```bash
+uv sync --all-packages
+```
+
+Python 3.11+ is required.
+
+## Quick Start
+
+```python
+import crgutils
+
+ds = crgutils.read("samples/crg-txt/handmade_straight.crg")  # load + validate + apply modifiers
+cp = ds.create_contact_point()                                 # default options
+
+z = cp.eval_uv_to_z(10.0, 0.0)            # elevation at road (u=10, v=0)
+x, y = cp.eval_uv_to_xy(10.0, 0.5)        # road → world coords
+u, v = cp.eval_xy_to_uv(x, y)             # world → road coords
+phi, kappa = cp.eval_uv_to_pk(10.0, 0.0)  # heading and curvature
+```
+
+Override evaluation options when creating the contact point:
+
+```python
+cp = ds.create_contact_point(border_mode_u=crgutils.BorderMode.REPEAT)
+```
+
+## API Surface
+
+| Symbol | Purpose |
+|---|---|
+| `crgutils.read(path, **kwargs)` | Load, validate, and prepare a `.crg` file; returns `CRGDataset` |
+| `dataset.create_contact_point(**options)` | Create a `ContactPoint` evaluation context |
+| `crgutils.ContactPoint(dataset, **options)` | Stateful evaluation context (direct constructor) |
+
+Exported types:
+
+| Type | Description |
+|---|---|
+| `CRGDataset` | Parsed road surface (arrays + metadata) |
+| `EvalOptions` | Frozen dataclass for evaluation parameters |
+| `BorderMode` | `NONE / EX_ZERO / EX_KEEP / REPEAT / REFLECT` |
+| `RefLineContinue` | `EXTRAPOLATE / CLOSE_TRACK` |
+| `CurvMode` | `LATERAL / REF_LINE` |
+| `GridNaNMode` | `KEEP / SET_ZERO / KEEP_LAST` |
+
+### `ContactPoint` evaluation methods
+
+```python
+cp.eval_uv_to_z(u, v)       → float            # elevation from road coords
+cp.eval_xy_to_z(x, y)       → float            # elevation from world coords
+cp.eval_uv_to_xy(u, v)      → (float, float)   # road → world
+cp.eval_xy_to_uv(x, y)      → (float, float)   # world → road
+cp.eval_uv_to_pk(u, v)      → (float, float)   # heading, curvature
+cp.eval_xy_to_pk(x, y)      → (float, float)   # heading, curvature
+cp.eval_uv_to_z_grid(u, v)  → np.ndarray       # vectorised elevation
+cp.eval_xy_to_z_grid(x, y)  → np.ndarray       # vectorised elevation
+cp.with_options(**overrides) → ContactPoint     # new context, shared dataset
+```
+
+## Sample Data
+
+Bundled sample files live in:
+
+```text
+samples/crg-txt/    ASCII CRG files (straight, curved, banked, sloped, circle, …)
+samples/crg-bin/    Binary CRG files (Belgian block cobblestone, country road, …)
+```
+
+Both the demo scripts and the test suite load from these directories.
+
+## Demos
+
+The repository has two demo areas:
+
+- `demo/c-api/` contains Python ports of the upstream OpenCRG C API demos
+- `demo/viz/` contains interactive visualization tools with their own dependencies
+
+### C-API Demo Ports
+
+```bash
+uv run python demo/c-api/simple.py                        # xy→z on a 2D grid
+uv run python demo/c-api/reader.py                        # header / channel / road info
+uv run python demo/c-api/curvature.py                     # curvature profile
+uv run python demo/c-api/eval_z.py                        # uv→z, round-trip z, pk
+uv run python demo/c-api/eval_xy_uv.py                    # uv→xy→uv round-trips
+uv run python demo/c-api/eval_options.py                  # 29 option/modifier tests
+```
+
+Each script defaults to a file in `samples/crg-txt/` and accepts an explicit path:
+
+```bash
+uv run python demo/c-api/reader.py samples/crg-bin/belgian_block.crg
+uv run python demo/c-api/eval_xy_uv.py samples/crg-txt/handmade_curved.crg
+uv run python demo/c-api/eval_options.py -t 5   # run only test 5
+```
+
+Pass `--help` to any script for usage details.
+
+### Visualizer
+
+The visualizer lives in the `viz` workspace member and includes both a marimo app and a notebook:
+
+```bash
+uv sync --package viz
+uv run --package viz marimo edit demo/viz/crg_viz.py
+uv run --package viz jupyter notebook demo/viz/render.ipynb
+```
+
+The marimo app lets you browse bundled sample files or point it at any local `.crg` file.
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+The test suite covers the loader, all evaluation functions, all five border modes,
+modifiers, `check()`, `ContactPoint` option inheritance, and round-trip accuracy.
+
+## Repository Layout
+
+```text
+src/crgutils/   library source
+samples/        bundled CRG sample files (crg-txt/ and crg-bin/)
+demo/c-api/     Python ports of the OpenCRG C API demos
+demo/viz/       visualization app and notebook
+tests/          pytest test suite
+```
+
+## Notes
+
+- The binary Belgian-block sample contains all-NaN edge channels that produce expected
+  `RuntimeWarning`s from NumPy when computing array summaries; the file still loads and
+  is fully covered by tests.

crgutils-0.1.0/README.md

@@ -0,0 +1,163 @@
+# crgutils
+
+`crgutils` is a Python library for loading, validating, and evaluating ASAM OpenCRG road surface files.
+
+Supported formats and capabilities:
+
+- ASCII `.crg` inputs in `LRFI` and `LDFI` formats
+- Binary `.crg` inputs in `KRBI` and `KDBI` formats
+- Road-space queries `(u, v) → z`, `(u, v) → (x, y)`, `(u, v) → (phi, kappa)`
+- World-space queries `(x, y) → z`, `(x, y) → (u, v)`, `(x, y) → (phi, kappa)`
+- All five border modes: `NONE`, `EX_ZERO`, `EX_KEEP`, `REPEAT`, `REFLECT`
+- Header-defined evaluation options and pending runtime modifiers
+
+## Install
+
+Core package:
+
+```bash
+uv sync
+```
+
+Core package with test dependencies:
+
+```bash
+uv sync --extra dev
+```
+
+If you also want the demo workspace members, especially the visualizer's extra dependencies:
+
+```bash
+uv sync --all-packages
+```
+
+Python 3.11+ is required.
+
+## Quick Start
+
+```python
+import crgutils
+
+ds = crgutils.read("samples/crg-txt/handmade_straight.crg")  # load + validate + apply modifiers
+cp = ds.create_contact_point()                                 # default options
+
+z = cp.eval_uv_to_z(10.0, 0.0)            # elevation at road (u=10, v=0)
+x, y = cp.eval_uv_to_xy(10.0, 0.5)        # road → world coords
+u, v = cp.eval_xy_to_uv(x, y)             # world → road coords
+phi, kappa = cp.eval_uv_to_pk(10.0, 0.0)  # heading and curvature
+```
+
+Override evaluation options when creating the contact point:
+
+```python
+cp = ds.create_contact_point(border_mode_u=crgutils.BorderMode.REPEAT)
+```
+
+## API Surface
+
+| Symbol | Purpose |
+|---|---|
+| `crgutils.read(path, **kwargs)` | Load, validate, and prepare a `.crg` file; returns `CRGDataset` |
+| `dataset.create_contact_point(**options)` | Create a `ContactPoint` evaluation context |
+| `crgutils.ContactPoint(dataset, **options)` | Stateful evaluation context (direct constructor) |
+
+Exported types:
+
+| Type | Description |
+|---|---|
+| `CRGDataset` | Parsed road surface (arrays + metadata) |
+| `EvalOptions` | Frozen dataclass for evaluation parameters |
+| `BorderMode` | `NONE / EX_ZERO / EX_KEEP / REPEAT / REFLECT` |
+| `RefLineContinue` | `EXTRAPOLATE / CLOSE_TRACK` |
+| `CurvMode` | `LATERAL / REF_LINE` |
+| `GridNaNMode` | `KEEP / SET_ZERO / KEEP_LAST` |
+
+### `ContactPoint` evaluation methods
+
+```python
+cp.eval_uv_to_z(u, v)       → float            # elevation from road coords
+cp.eval_xy_to_z(x, y)       → float            # elevation from world coords
+cp.eval_uv_to_xy(u, v)      → (float, float)   # road → world
+cp.eval_xy_to_uv(x, y)      → (float, float)   # world → road
+cp.eval_uv_to_pk(u, v)      → (float, float)   # heading, curvature
+cp.eval_xy_to_pk(x, y)      → (float, float)   # heading, curvature
+cp.eval_uv_to_z_grid(u, v)  → np.ndarray       # vectorised elevation
+cp.eval_xy_to_z_grid(x, y)  → np.ndarray       # vectorised elevation
+cp.with_options(**overrides) → ContactPoint     # new context, shared dataset
+```
+
+## Sample Data
+
+Bundled sample files live in:
+
+```text
+samples/crg-txt/    ASCII CRG files (straight, curved, banked, sloped, circle, …)
+samples/crg-bin/    Binary CRG files (Belgian block cobblestone, country road, …)
+```
+
+Both the demo scripts and the test suite load from these directories.
+
+## Demos
+
+The repository has two demo areas:
+
+- `demo/c-api/` contains Python ports of the upstream OpenCRG C API demos
+- `demo/viz/` contains interactive visualization tools with their own dependencies
+
+### C-API Demo Ports
+
+```bash
+uv run python demo/c-api/simple.py                        # xy→z on a 2D grid
+uv run python demo/c-api/reader.py                        # header / channel / road info
+uv run python demo/c-api/curvature.py                     # curvature profile
+uv run python demo/c-api/eval_z.py                        # uv→z, round-trip z, pk
+uv run python demo/c-api/eval_xy_uv.py                    # uv→xy→uv round-trips
+uv run python demo/c-api/eval_options.py                  # 29 option/modifier tests
+```
+
+Each script defaults to a file in `samples/crg-txt/` and accepts an explicit path:
+
+```bash
+uv run python demo/c-api/reader.py samples/crg-bin/belgian_block.crg
+uv run python demo/c-api/eval_xy_uv.py samples/crg-txt/handmade_curved.crg
+uv run python demo/c-api/eval_options.py -t 5   # run only test 5
+```
+
+Pass `--help` to any script for usage details.
+
+### Visualizer
+
+The visualizer lives in the `viz` workspace member and includes both a marimo app and a notebook:
+
+```bash
+uv sync --package viz
+uv run --package viz marimo edit demo/viz/crg_viz.py
+uv run --package viz jupyter notebook demo/viz/render.ipynb
+```
+
+The marimo app lets you browse bundled sample files or point it at any local `.crg` file.
+
+## Tests
+
+```bash
+uv run pytest
+```
+
+The test suite covers the loader, all evaluation functions, all five border modes,
+modifiers, `check()`, `ContactPoint` option inheritance, and round-trip accuracy.
+
+## Repository Layout
+
+```text
+src/crgutils/   library source
+samples/        bundled CRG sample files (crg-txt/ and crg-bin/)
+demo/c-api/     Python ports of the OpenCRG C API demos
+demo/viz/       visualization app and notebook
+tests/          pytest test suite
+```
+
+## Notes
+
+- The binary Belgian-block sample contains all-NaN edge channels that produce expected
+  `RuntimeWarning`s from NumPy when computing array summaries; the file still loads and
+  is fully covered by tests.

crgutils-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "crgutils"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+authors = [
+    { name = "coder", email = "coder@timeintegral.ai" }
+]
+requires-python = ">=3.11"
+dependencies = ["numpy>=1.26"]
+
+[dependency-groups]
+dev = [
+    "bump-my-version>=1.3.0",
+    "pytest>=8.0",
+    "pytest-cov",
+    "ruff>=0.15.10",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.2,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.workspace]
+members = [
+    "demo/viz",
+    "demo/c-api",
+    ".",
+]
+
+[tool.uv]
+default-groups = ["dev"]

crgutils-0.1.0/src/crgutils/__init__.py

@@ -0,0 +1,38 @@
+"""crgutils — Python library for reading and evaluating OpenCRG road surface files.
+
+Quick start
+-----------
+>>> import crgutils
+>>> ds = crgutils.read("road.crg")         # load + validate + apply modifiers
+>>> cp = ds.create_contact_point()
+>>> z = cp.eval_uv_to_z(10.0, 0.0)        # elevation at (u=10, v=0)
+>>> x, y = cp.eval_uv_to_xy(10.0, 0.5)   # road → world coords
+>>> u, v = cp.eval_xy_to_uv(x, y)         # world → road coords
+"""
+
+from ._convenience import read
+from ._dataset import CRGDataset
+from ._contact_point import ContactPoint
+from ._types import BorderMode, RefLineContinue, CurvMode, GridNaNMode, EvalOptions
+
+# Lower-level building blocks — available for advanced use but not part of the
+# primary public API.
+from ._loader import load  # noqa: F401
+from ._check import check  # noqa: F401
+from ._modifiers import apply_modifiers  # noqa: F401
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # High-level interface
+    "read",
+    "CRGDataset",
+    "ContactPoint",
+    # Types / enums
+    "BorderMode",
+    "RefLineContinue",
+    "CurvMode",
+    "GridNaNMode",
+    "EvalOptions",
+    "__version__",
+]

crgutils-0.1.0/src/crgutils/_check.py

@@ -0,0 +1,102 @@
+"""Validate a CRGDataset for consistency and accuracy.
+
+Port of ``crgCheck()`` / ``crgCheckOpts()`` / ``crgCheckData()`` from
+crgLoader.c / crgMgr.c.
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+
+import numpy as np
+
+from ._dataset import CRGDataset
+
+
+def check(dataset: CRGDataset, *, raise_on_error: bool = False) -> bool:
+    """Validate *dataset* for internal consistency.
+
+    Parameters
+    ----------
+    dataset:
+        The dataset to validate.
+    raise_on_error:
+        If True, raise a ``ValueError`` instead of returning False.
+
+    Returns
+    -------
+    bool
+        ``True`` if all checks pass.
+    """
+    errors: list[str] = []
+    warnings_: list[str] = []
+
+    # --- basic shape checks ---
+    if dataset.n_u < 2:
+        errors.append(f"u axis has fewer than 2 points ({dataset.n_u})")
+    if dataset.n_v < 1:
+        errors.append(f"v axis has no points ({dataset.n_v})")
+    if dataset.z.shape != (dataset.n_v, dataset.n_u):
+        errors.append(
+            f"z shape {dataset.z.shape} does not match (n_v={dataset.n_v}, n_u={dataset.n_u})"
+        )
+
+    # --- u increment consistency ---
+    if dataset.n_u >= 2:
+        computed_inc = (dataset.u_max - dataset.u_min) / (dataset.n_u - 1)
+        if abs(computed_inc - dataset.u_inc) > 1e-6 * max(1.0, abs(dataset.u_inc)):
+            warnings_.append(
+                f"u_inc mismatch: stored={dataset.u_inc:.6f}, computed={computed_inc:.6f}"
+            )
+
+    # --- v monotonicity ---
+    if dataset.n_v >= 2:
+        diffs = np.diff(dataset.v.astype(float))
+        if not np.all(diffs > 0):
+            errors.append("v array is not strictly increasing")
+
+    # --- phi continuity (warn on large jumps) ---
+    if dataset.n_u >= 2:
+        phi_unwrapped = np.unwrap(dataset.phi.astype(float))
+        dphi = np.abs(np.diff(phi_unwrapped))
+        max_dphi = float(dphi.max()) if len(dphi) else 0.0
+        if max_dphi > math.pi / 2:
+            warnings_.append(
+                f"Large heading jump detected: max |Δphi| = {math.degrees(max_dphi):.1f}°"
+            )
+
+    # --- NaN fraction in z grid ---
+    nan_count = int(np.isnan(dataset.z.astype(float)).sum())
+    total = dataset.z.size
+    if nan_count > 0:
+        frac = nan_count / total
+        if frac > 0.5:
+            errors.append(f"More than 50% of z values are NaN ({nan_count}/{total})")
+        elif frac > 0.1:
+            warnings_.append(f"{nan_count}/{total} z values are NaN ({100*frac:.1f}%)")
+
+    # --- reference line x/y length vs u length ---
+    if dataset.n_u >= 2:
+        dx = np.diff(dataset.x.astype(float))
+        dy = np.diff(dataset.y.astype(float))
+        seg_lengths = np.sqrt(dx ** 2 + dy ** 2)
+        total_xy = float(seg_lengths.sum())
+        total_u  = dataset.u_max - dataset.u_min
+        if total_u > 0 and abs(total_xy - total_u) / total_u > 0.05:
+            warnings_.append(
+                f"Reference line arc length {total_xy:.3f} m differs from "
+                f"u range {total_u:.3f} m by more than 5%"
+            )
+
+    for w in warnings_:
+        warnings.warn(f"CRGDataset check: {w}", UserWarning, stacklevel=2)
+
+    if errors:
+        msg = "CRGDataset validation failed:\n" + "\n".join(f"  - {e}" for e in errors)
+        if raise_on_error:
+            raise ValueError(msg)
+        warnings.warn(msg, UserWarning, stacklevel=2)
+        return False
+
+    return True

crgutils-0.1.0/src/crgutils/_contact_point.py

@@ -0,0 +1,167 @@
+"""ContactPoint: stateful evaluation context for a CRGDataset."""
+
+from __future__ import annotations
+
+from collections import deque
+from typing import Any
+
+import numpy as np
+
+from ._dataset import CRGDataset
+from ._types import EvalOptions
+from ._eval import (
+    _eval_uv_to_z,
+    _eval_uv_to_xy,
+    _xy_to_uv,
+    _eval_uv_to_pk,
+)
+
+
+class ContactPoint:
+    """Evaluation context for a :class:`CRGDataset`.
+
+    A ``ContactPoint`` binds a dataset to a set of :class:`EvalOptions` and
+    maintains a small history deque that accelerates successive nearby queries
+    (warm start for the xy→uv search).
+
+    Multiple ``ContactPoint`` instances on the same dataset are safe to use
+    independently (each has its own history and options).
+
+    Parameters
+    ----------
+    dataset:
+        The CRG dataset to evaluate against.
+    **options:
+        Keyword arguments that override :class:`EvalOptions` defaults.
+        Keys must be valid :class:`EvalOptions` field names.
+
+    Examples
+    --------
+    >>> import crgutils
+    >>> ds = crgutils.load("road.crg")
+    >>> cp = crgutils.ContactPoint(ds)
+    >>> z = cp.eval_uv_to_z(5.0, 0.0)
+    >>> x, y = cp.eval_uv_to_xy(5.0, 0.5)
+    >>> u, v = cp.eval_xy_to_uv(x, y)
+    """
+
+    def __init__(self, dataset: CRGDataset, **options: Any) -> None:
+        self._ds = dataset
+        # Merge dataset-level default options with caller overrides
+        merged = {**dataset.default_options, **options}
+        self._options = EvalOptions(**merged)
+        self._history: deque[tuple[float, float, int]] = deque(
+            maxlen=self._options.history_size
+        )
+
+        # Pre-seed history if ref_line_search_u is set
+        if self._options.ref_line_search_u is not None:
+            su = self._options.ref_line_search_u
+            idx = int((su - dataset.u_min) / dataset.u_inc)
+            idx = max(1, min(idx, dataset.n_u - 1))
+            x_seed, y_seed = _eval_uv_to_xy(dataset, self._options, su, 0.0)
+            self._history.appendleft((x_seed, y_seed, idx))
+
+    # ------------------------------------------------------------------
+    # Factory
+    # ------------------------------------------------------------------
+
+    def with_options(self, **overrides: Any) -> "ContactPoint":
+        """Return a new ``ContactPoint`` with option overrides applied.
+
+        The new instance shares the same dataset but gets a fresh history.
+        """
+        from dataclasses import asdict
+        current = asdict(self._options)
+        current.update(overrides)
+        return ContactPoint(self._ds, **current)
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def options(self) -> EvalOptions:
+        return self._options
+
+    @property
+    def dataset(self) -> CRGDataset:
+        return self._ds
+
+    # ------------------------------------------------------------------
+    # Primary evaluation methods
+    # ------------------------------------------------------------------
+
+    def eval_uv_to_z(self, u: float, v: float) -> float:
+        """Bilinear elevation at road coordinate (u, v) [m]."""
+        return _eval_uv_to_z(self._ds, self._options, u, v)
+
+    def eval_xy_to_z(self, x: float, y: float) -> float:
+        """Elevation at Cartesian position (x, y) [m]."""
+        u, v = _xy_to_uv(self._ds, self._options, x, y, self._history)
+        return _eval_uv_to_z(self._ds, self._options, u, v)
+
+    def eval_uv_to_xy(self, u: float, v: float) -> tuple[float, float]:
+        """Convert road (u, v) to Cartesian (x, y) [m]."""
+        return _eval_uv_to_xy(self._ds, self._options, u, v)
+
+    def eval_xy_to_uv(self, x: float, y: float) -> tuple[float, float]:
+        """Convert Cartesian (x, y) to road (u, v) [m]."""
+        return _xy_to_uv(self._ds, self._options, x, y, self._history)
+
+    def eval_uv_to_pk(self, u: float, v: float) -> tuple[float, float]:
+        """Heading [rad] and curvature [1/m] at road (u, v)."""
+        return _eval_uv_to_pk(self._ds, self._options, u, v)
+
+    def eval_xy_to_pk(self, x: float, y: float) -> tuple[float, float]:
+        """Heading [rad] and curvature [1/m] at Cartesian (x, y)."""
+        u, v = _xy_to_uv(self._ds, self._options, x, y, self._history)
+        return _eval_uv_to_pk(self._ds, self._options, u, v)
+
+    # ------------------------------------------------------------------
+    # Vectorised convenience methods
+    # ------------------------------------------------------------------
+
+    def eval_uv_to_z_grid(
+        self,
+        u: "np.ndarray",
+        v: "np.ndarray",
+    ) -> "np.ndarray":
+        """Vectorised elevation evaluation over arrays of (u, v) pairs.
+
+        Parameters
+        ----------
+        u, v:
+            1-D arrays of matching length or broadcastable shapes.
+
+        Returns
+        -------
+        np.ndarray
+            Elevation values, same shape as broadcast(u, v).
+        """
+        u_arr = np.asarray(u, dtype=float).ravel()
+        v_arr = np.asarray(v, dtype=float).ravel()
+        z_arr = np.empty(len(u_arr), dtype=float)
+        for i in range(len(u_arr)):
+            z_arr[i] = _eval_uv_to_z(self._ds, self._options, float(u_arr[i]), float(v_arr[i]))
+        return z_arr
+
+    def eval_xy_to_z_grid(
+        self,
+        x: "np.ndarray",
+        y: "np.ndarray",
+    ) -> "np.ndarray":
+        """Vectorised elevation evaluation over arrays of (x, y) pairs."""
+        x_arr = np.asarray(x, dtype=float).ravel()
+        y_arr = np.asarray(y, dtype=float).ravel()
+        z_arr = np.empty(len(x_arr), dtype=float)
+        for i in range(len(x_arr)):
+            z_arr[i] = self.eval_xy_to_z(float(x_arr[i]), float(y_arr[i]))
+        return z_arr
+
+    def __repr__(self) -> str:
+        return (
+            f"ContactPoint(dataset={self._ds.source_file!r}, "
+            f"border_mode_u={self._options.border_mode_u.name}, "
+            f"border_mode_v={self._options.border_mode_v.name})"
+        )