flatpoints 0.1.0__py3-none-any.whl

flatpoints/main.py

@@ -0,0 +1,290 @@
+"""User-facing classes: `Flat` (point cloud -> images), `Resampler` (images -> new points
+on the surface) and `Compressor` (image compression of the points, see compressor.py).
+`Viz` adds the plots to `Flat`.
+"""
+from functools import cached_property
+
+import numpy as np
+from scipy.ndimage import gaussian_filter, map_coordinates
+from scipy.spatial import cKDTree
+
+from .core import conformal_uv, image_cells
+from .mesh import TRIM, closest_on_mesh, disk_cut, hemisphere_cut, poisson_mesh, submesh
+from .utils import axes, fill_empty, Chart, Corners, Mesh, _window, _seeds, ON_SURFACE
+
+
+class Viz:
+    """Plots of a `Flat`, as its methods: `flat.plot()` and `flat.imshow(data)`.
+
+    Needs matplotlib (`pip install "flatpoints[viz]"`), imported only when a plot is drawn.
+    The drawing itself is in `viz.py`."""
+
+    def plot(self, squares=8, point_size=1.0):
+        """The surface in 3D and its images, coloured by RGB = xyz and by a checkerboard
+        of `squares` pixels: smooth colours and regular squares mean a good flattening.
+        """
+        from .viz import plot
+        return plot(self, squares, point_size)
+
+    def imshow(self, data=None, sigma=0.5, cmap="viridis", animate=False, resolution="low"):
+        """`data` on the images: per-point (N, *C) or images (n_faces, n, n, *C),
+        default the xyz of the points. See `viz.imshow` for the colouring, `viz.morph` for
+        `animate` (True, or a .webp path) and `resolution` ("low" or "high").
+        """
+        from .viz import imshow, morph
+        data = self.points if data is None else np.asarray(data)
+        if len(data) != len(self.points):
+            if data.shape[:3] != (self.n_faces, self.n, self.n):
+                raise ValueError(f"data must be per point ({len(self.points)}, *C) or images "
+                                 f"({self.n_faces}, {self.n}, {self.n}, *C), got {data.shape}")
+        else:
+            data = self.to_image(data)
+        if animate is not False:
+            return morph(data, self.to_image(self.points), self.normal_axis, sigma, cmap,
+                         path=None if animate is True else animate, resolution=resolution)
+        return imshow(data, sigma, cmap)
+
+
+class Flat(Viz):
+    """Flatten a 3D point cloud into one or two square images, one pixel per point.
+
+    Neighbour pixels hold neighbour points, so per-point data (N, *C) becomes images
+    (n_faces, n, n, *C). See Method.md for how.
+
+    Args:
+        points: (N, 3) points sampled on a surface.
+        single_face: True for an open surface (one image), False for a closed one (two
+            images, the surface cut in left and right halves).
+        normal_axis: "x", "y" or "z". Orients the images (rows follow z, or y if
+            normal_axis is "z") and, for a closed surface, sets the direction of the cut.
+        verbose: print progress.
+
+    Attributes:
+        n, n_faces: side and number of the images.
+        pixels: (N, 3) (face, row, col) of each point.
+        faces: {"left": idx, "right": idx}, None if single_face.
+        corners: the points copied into the empty pixels (see `to_image`).
+        _mesh, _charts, _uv_conformal: intermediate steps, for inspection.
+
+    Example:
+        flat = Flat(points)
+        image = flat.to_image(points)       # (2, n, n, 3)
+        face, row, col = flat.pixels[42]
+        new = flat.resample(512).points     # (512, 3)
+    """
+
+    def __init__(self, points, single_face=False, normal_axis="x", verbose=False):
+        self.points = P = np.asarray(points, float)
+        self.normal_axis, self.single_face = normal_axis, single_face
+        normal, horiz, vert = axes(normal_axis)
+
+        # 1. Mesh, cut into charts
+        if single_face:
+            V, F = poisson_mesh(P, trim=TRIM)
+            side = disk_cut(V, F)
+        else:
+            V, F = poisson_mesh(P)
+            side = hemisphere_cut(V, F, normal, np.median(P[:, normal]))
+        self._mesh = Mesh(V, F, side)
+        if verbose:
+            print(f"mesh: {len(V)} vertices, {len(F)} triangles, "
+                  f"{(side < 0).sum()} in no face")
+        in_face = np.flatnonzero(side >= 0)
+        tri, bary = closest_on_mesh(V, F[in_face], P)  # each point projected on the mesh
+        tri = in_face[tri]
+        face_of = side[tri]
+
+        names = ("main",) if single_face else ("left", "right")
+        self.n_faces = len(names)
+        self.n = n = int(np.ceil(np.sqrt(np.bincount(face_of).max())))
+        self.faces = None if single_face else {}
+        self._charts = []
+        self._uv_conformal = np.zeros((len(P), 2))
+        self.pixels = np.zeros((len(P), 3), int)
+        pad_idxs, pad_pixels = [], []
+
+        for f, name in enumerate(names):
+            idx = np.flatnonzero(face_of == f)
+            if verbose:
+                print(f"face {name}: {len(idx)} points on {n} x {n}")
+            if not single_face:
+                self.faces[name] = idx
+
+            # 2. Conformal uv of the chart, interpolated at the points
+            mine = side == f
+            Ff, vertices = submesh(F, mine)
+            Vf = V[vertices]
+            uv = conformal_uv(Vf, Ff, Vf[:, [horiz, vert]])
+            self._charts.append(Chart(vertices, Ff, uv))
+            around = Ff[(np.cumsum(mine) - 1)[tri[idx]]]  # chart vertices around each point
+            self._uv_conformal[idx] = np.einsum("nk,nkd->nd", bary[idx], uv[around])
+
+            # 3. Image, from the conformal uv
+            cells = image_cells(self._uv_conformal[idx], n, verbose)  # (n, n), -1: empty
+            rows, cols = np.nonzero(cells >= 0)
+            self.pixels[idx[cells[rows, cols]]] = np.c_[np.full(len(rows), f), rows, cols]
+            rows, cols = np.nonzero(cells < 0)
+            pad_idxs.append(idx[fill_empty(cells)[rows, cols]])
+            pad_pixels.append(np.c_[np.full(len(rows), f), rows, cols])
+
+        self.corners = Corners(np.concatenate(pad_idxs), np.concatenate(pad_pixels))
+
+    def resample(self, n_points=512, seed=42, sigma=0.0):
+        """`n_points` new points evenly spread on the surface, see `Resampler`."""
+        return Resampler(self, n_points, seed, sigma)
+
+    def compress(self, factor=0.8, method="auto"):
+        """Compress the points, `factor` (e.g. 0.8) of the storage saved, with `method`
+        ("auto": the most accurate), see `Compressor`."""
+        return Compressor(self, factor, method)
+
+    @cached_property
+    def _lifting(self):
+        """Cached for `Resampler`: xyz images, mask of real pixels, k-d tree and local
+        spacing of the points.
+        """
+        image = self.to_image(self.points)  # (n_faces, n, n, 3)
+        valid = np.ones(image.shape[:3], bool)
+        valid[tuple(self.corners.pixels.T)] = False
+        tree = cKDTree(self.points)
+        spacing = tree.query(self.points, k=7)[0][:, 1:].mean(1)
+        return image, valid, tree, spacing
+
+    def to_image(self, values):
+        """Per-point `values` (N, ...) as images (n_faces, n, n, ...), empty pixels
+        filled from `corners`. E.g. `to_image(points)`: the xyz images.
+        """
+        values = np.asarray(values)
+        image = np.empty((self.n_faces, self.n, self.n) + values.shape[1:], values.dtype)
+        image[tuple(self.pixels.T)] = values
+        image[tuple(self.corners.pixels.T)] = values[self.corners.idxs]
+        return image
+
+
+class Resampler:
+    """`n_points` new points evenly spread on the surface of a `Flat`
+    (`flat.resample(n_points)`).
+
+    A 2D seed is placed on the images and lifted to 3D by bilinear interpolation of the xyz
+    images; points that fall off the surface (across a tear) are replaced by the next ones.
+
+    Args:
+        n_points: split evenly between the faces.
+        seed: int (shift of the default hyperuniform seed), (M, 2) points in [0, 1)^2, or
+            {face name: (M, 2)}.
+        sigma: Gaussian smoothing of the images before lifting, in pixels.
+
+    Attributes:
+        points: (n_points, 3); faces: (n_points,); pixels: (n_points, 3) float
+        (face, row, col).
+    """
+
+    def __init__(self, flat, n_points=512, seed=42, sigma=0.0):
+        self.flat, self.n_points, self.sigma = flat, n_points, sigma
+        names = ("main",) if flat.single_face else ("left", "right")
+        if n_points < len(names):
+            raise ValueError(f"n_points must be at least {len(names)}, one per face")
+        seeds = _seeds(seed, names)
+        counts = np.full(len(names), n_points // len(names))
+        if n_points % len(names):  # odd: one face, drawn from the seed, gets one more
+            rng = np.random.default_rng(seed if isinstance(seed, (int, np.integer)) else 0)
+            counts[rng.integers(len(names))] += 1
+
+        image, valid, tree, spacing = flat._lifting
+        m = flat.n
+        points, pixels = [], []
+        for f, (name, n) in enumerate(zip(names, counts)):
+            smooth = gaussian_filter(image[f], (sigma, sigma, 0), mode="nearest")
+            lift = lambda rc: np.stack([map_coordinates(smooth[..., c], rc.T, order=1,  # noqa: E731
+                                                        mode="nearest") for c in range(3)], -1)
+
+            def keep(rc, f=f, lift=lift):
+                """Not on a padding pixel, and on the surface (not in the air)."""
+                pixel = valid[f][tuple(np.clip(np.rint(rc).astype(int), 0, m - 1).T)]
+                d, i = tree.query(lift(rc))
+                return pixel & (d <= ON_SURFACE * spacing[i])
+
+            rc = _window(seeds[name], n, m, keep)
+            points.append(lift(rc))
+            pixels.append(np.c_[np.full(n, f), rc])
+        self.points = np.concatenate(points)
+        self.pixels = np.concatenate(pixels)
+        self.faces = self.pixels[:, 0].astype(int)
+
+    def plot(self, ax=None, point_size=1.0, **kwargs):
+        """Before (input cloud, left) / after (new points on its mesh, right), in 3D.
+        With `ax`, only the after view, drawn in `ax`. See `viz.plot_resampler`."""
+        from .viz import plot_resampler
+        return plot_resampler(self, ax=ax, point_size=point_size, **kwargs)
+
+
+
+class Compressor:
+    """Compress the points of a `Flat` through its xyz images (`flat.compress(factor)`).
+
+    The images are smooth (neighbour pixels hold neighbour points), so image compression
+    applies. Methods (see `compressor.py`): "svd" (truncated SVD), "dct" (quantized DCT,
+    as JPEG) and "wavelet" (quantized wavelets, as JPEG2000, needs PyWavelets); "auto"
+    runs the available ones and keeps the most accurate.
+
+    Args:
+        factor: fraction of the storage saved, in [0, 1), against the points in float32
+            (96 bits per point): 0.8 keeps 20%, about 19 bits per point.
+        method: "auto", "svd", "dct" or "wavelet".
+
+    Attributes:
+        method: the method used.
+        code: what is stored, arrays (n_faces, 3, ...): {"U", "S", "Vt"} for svd,
+            {"coefficients", "step", ...} for dct and wavelet (integers, times step).
+        bits: size of the code; ratio: storage actually saved, 1 - bits / (96 N).
+        images: (n_faces, n, n, 3) the reconstructed xyz images.
+        points: (N, 3) the reconstructed points, in the order of `flat.points`.
+        error: RMS distance between the points and their reconstruction.
+
+    `bits` is a theoretical bound for dct and wavelet (ideal entropy coder). `save` writes a
+    real file, in JPEG2000, and `Compressor.read` reads it back.
+    """
+
+    def __init__(self, flat, factor=0.8, method="auto"):
+        from . import compressor
+        if not 0 <= factor < 1:
+            raise ValueError("factor must be in [0, 1), e.g. 0.8 to save 80% of the storage")
+        methods = compressor.available() if method == "auto" else [method]
+        if method != "auto" and method not in compressor.METHODS:
+            raise ValueError(f"method must be 'auto' or one of {list(compressor.METHODS)}")
+        self.flat, self.factor = flat, factor
+        raw = 32 * flat.points.size
+        A = np.moveaxis(flat.to_image(flat.points), -1, 1)  # (n_faces, 3, n, n)
+        shape = A.shape
+        best = None
+        for name in methods:
+            code, rec, bits = compressor.METHODS[name](A.reshape(-1, *shape[2:]), (1 - factor) * raw)
+            images = np.moveaxis(rec.reshape(shape), 1, -1)
+            points = images[tuple(flat.pixels.T)]
+            error = np.sqrt(((points - flat.points) ** 2).sum(1).mean())
+            code = {k: v.reshape(shape[:2] + v.shape[1:]) if np.ndim(v) else v
+                    for k, v in code.items()}  # per face and coordinate
+            if best is None or error < best[-1]:
+                best = (name, code, bits, images, points, error)
+        self.method, self.code, self.bits, self.images, self.points, self.error = best
+        self.ratio = 1 - self.bits / raw
+
+    def save(self, path):
+        """Write the points to `path` as a JPEG2000 file (16 bits, any JPEG2000 reader opens
+        it), within the size budget of `factor`. The file holds the points, not their order.
+        Returns its size in bytes."""
+        from .compressor import to_jp2
+        flat = self.flat
+        n = flat.n
+        padding = (flat.corners.pixels * [n * n, n, 1]).sum(1)
+        data = to_jp2(flat.to_image(flat.points), padding, (1 - self.factor) * 32 * flat.points.size)
+        with open(path, "wb") as file:
+            file.write(data)
+        return len(data)
+
+    @staticmethod
+    def read(path):
+        """(N, 3) points of a file written by `save`, in the order of its pixels."""
+        from .compressor import from_jp2
+        with open(path, "rb") as file:
+            return from_jp2(file.read())

flatpoints/mesh.py

@@ -0,0 +1,172 @@
+"""Meshes: Poisson reconstruction, cut into disks, projection of the points."""
+import heapq
+
+import numpy as np
+from scipy.sparse import coo_matrix
+from scipy.sparse.csgraph import dijkstra
+from scipy.spatial import cKDTree
+
+POISSON_DEPTH = 8  # octree depth of the Poisson reconstruction
+KNN_NORMALS = 16   # neighbours used to estimate and orient the normals
+TRIM = 2.0         # open surface: mesh kept within TRIM x the point spacing of the cloud
+
+
+# === Reconstruction ===
+
+def poisson_mesh(points, depth=POISSON_DEPTH, trim=None):
+    """(V, F) mesh of the surface sampled by `points`, screened Poisson: its largest piece.
+
+    Poisson always returns a closed surface. For an open surface, `trim` removes what it
+    invents away from the samples: the vertices farther from the cloud than `trim` times
+    the local point spacing.
+    """
+    import open3d as o3d
+    cloud = o3d.geometry.PointCloud(o3d.utility.Vector3dVector(points))
+    cloud.estimate_normals(o3d.geometry.KDTreeSearchParamKNN(KNN_NORMALS))
+    try:
+        cloud.orient_normals_consistent_tangent_plane(KNN_NORMALS)
+    except RuntimeError:  # exactly planar cloud: its Delaunay (qhull) is degenerate
+        jitter = 1e-6 * np.ptp(points, 0).max() * np.random.default_rng(0).standard_normal(points.shape)
+        shaken = o3d.geometry.PointCloud(o3d.utility.Vector3dVector(points + jitter))
+        shaken.normals = cloud.normals
+        shaken.orient_normals_consistent_tangent_plane(KNN_NORMALS)
+        cloud.normals = shaken.normals
+    mesh, _ = o3d.geometry.TriangleMesh.create_from_point_cloud_poisson(cloud, depth=depth)
+    if trim is not None:
+        tree = cKDTree(points)
+        spacing = tree.query(points, k=7)[0][:, 1:].mean(1)
+        d, i = tree.query(np.asarray(mesh.vertices))
+        mesh.remove_vertices_by_mask(d > trim * spacing[i])
+    mesh.remove_degenerate_triangles()
+    mesh.remove_non_manifold_edges()
+    piece, sizes, _ = mesh.cluster_connected_triangles()
+    mesh.remove_triangles_by_mask(np.asarray(piece) != np.argmax(sizes))
+    mesh.remove_unreferenced_vertices()
+    return np.asarray(mesh.vertices), np.asarray(mesh.triangles)
+
+
+# === Cuts ===
+
+def disk_cut(V, F):
+    """Cut the open mesh (V, F) into one disk: (F,) 0 for the triangles of the disk, -1
+    for the others.
+
+    The disk grows from the triangle farthest from the boundary (along the edges of the
+    mesh), the closest triangles first; handles and holes are left open (see `grow`).
+    """
+    E = np.unique(np.sort(F[:, [0, 1, 1, 2, 2, 0]].reshape(-1, 2), 1), axis=0)
+    graph = coo_matrix((np.linalg.norm(V[E[:, 0]] - V[E[:, 1]], axis=1), E.T),
+                       shape=(len(V),) * 2).tocsr()
+    nbr = neighbours(F)
+    border = np.unique(F[nbr < 0])
+    depth = dijkstra(graph, directed=False, indices=border, min_only=True)
+    seed = np.argmax(depth[F].min(1))
+    d = dijkstra(graph, directed=False, indices=F[seed], min_only=True)[F].mean(1)
+    side = np.full(len(F), -1)
+    side[seed] = 0
+    side = grow(F, nbr, side, [d, d], [np.ones(len(F), bool), np.zeros(len(F), bool)])
+    return drop_ears(nbr, side)
+
+
+def hemisphere_cut(V, F, normal, threshold):
+    """(F,) 0 (left), 1 (right) or -1 (out) for each triangle of the closed mesh:
+    two disks, either side of `threshold` on the axis `normal`. Each grows from its extreme
+    triangle (see `grow`); triangles of a handle stay out of both.
+    """
+    x = V[F, normal].mean(1)
+    nbr = neighbours(F)
+    side = np.full(len(F), -1)
+    side[np.argmin(x)], side[np.argmax(x)] = 0, 1
+    right = x > threshold
+    side = grow(F, nbr, side, [x, -x], [~right, right])
+    d = np.abs(x - threshold)
+    side = grow(F, nbr, side, [d, d], [side < 0, side < 0])
+    return drop_ears(nbr, side)
+
+
+def grow(F, nbr, side, keys, allowed):
+    """Grow faces 0 and 1 from `side` (-1: free), keeping each a topological disk.
+
+    A free triangle joins face s if it shares two edges with it, or one edge and a third
+    vertex not yet in it. Candidates come in increasing `keys[s]`, among `allowed[s]`.
+    Returns the new `side`.
+    """
+    side = side.copy()
+    Fl, nbl, sl = F.tolist(), nbr.tolist(), side.tolist()
+    inside = [np.zeros(F.max() + 1, bool) for _ in (0, 1)]
+    for s in (0, 1):
+        inside[s][F[side == s]] = True
+    inside = [m.tolist() for m in inside]
+    keys = [k.tolist() for k in keys]
+    allowed = [a.tolist() for a in allowed]
+
+    queue = []
+    for s in (0, 1):  # the free neighbours of each face
+        for t in np.flatnonzero(side == s).tolist():
+            queue += [(keys[s][u], s, u) for u in nbl[t] if u >= 0 and allowed[s][u]]
+    heapq.heapify(queue)
+    while queue:
+        _, s, t = heapq.heappop(queue)
+        if sl[t] >= 0:
+            continue
+        shared = [k for k, u in enumerate(nbl[t]) if u >= 0 and sl[u] == s]
+        if len(shared) == 1:
+            if inside[s][Fl[t][(shared[0] + 2) % 3]]:  # third vertex already in the face
+                continue
+        elif len(shared) != 2:
+            continue
+        sl[t] = s
+        for v in Fl[t]:
+            inside[s][v] = True
+        for u in nbl[t]:
+            if u >= 0 and sl[u] < 0 and allowed[s][u]:
+                heapq.heappush(queue, (keys[s][u], s, u))
+    return np.array(sl)
+
+
+def drop_ears(nbr, side):
+    """Free the triangles with two or three edges on the boundary of their face (their
+    tip would be a boundary vertex of a single triangle, which the rectangular conformal
+    map does not allow), until there is none."""
+    side = side.copy()
+    while True:
+        across = np.where(nbr >= 0, side[nbr], -2)
+        ear = (side >= 0) & ((across != side[:, None]).sum(1) >= 2)
+        if not ear.any():
+            return side
+        side[ear] = -1
+
+
+def neighbours(F):
+    """(nF, 3) the triangle across each edge (k, k+1) of each triangle, -1 on a border."""
+    he = np.stack([F, np.roll(F, -1, axis=1)], -1).reshape(-1, 2).astype(np.int64)
+    n = he.max() + 1
+    key, twin = he[:, 0] * n + he[:, 1], he[:, 1] * n + he[:, 0]
+    order = np.argsort(key)
+    pos = np.minimum(np.searchsorted(key[order], twin), len(key) - 1)
+    found = key[order][pos] == twin
+    return np.where(found, order[pos] // 3, -1).reshape(-1, 3)
+
+
+# === Points on the mesh ===
+
+def closest_on_mesh(V, F, X):
+    """For each point of X, the triangle of its closest point on (V, F) and the
+    barycentric coordinates of that closest point, (M,) and (M, 3)."""
+    import open3d as o3d
+    mesh = o3d.t.geometry.TriangleMesh()
+    mesh.vertex.positions = o3d.core.Tensor(V.astype(np.float32))
+    mesh.triangle.indices = o3d.core.Tensor(F.astype(np.int32))
+    scene = o3d.t.geometry.RaycastingScene()
+    scene.add_triangles(mesh)
+    hit = scene.compute_closest_points(o3d.core.Tensor(X.astype(np.float32)))
+    w = hit["primitive_uvs"].numpy().astype(float)
+    bary = np.clip(np.c_[1 - w.sum(1), w], 0, 1)  # float32 round-off
+    return hit["primitive_ids"].numpy().astype(int), bary / bary.sum(1, keepdims=True)
+
+
+def submesh(F, keep):
+    """(F', vertices) the triangles F[keep] renumbered on their own vertices, and the
+    index of these vertices in the full mesh."""
+    vertices, Fk = np.unique(F[keep], return_inverse=True)
+    return Fk.reshape(-1, 3), vertices

flatpoints/rcm.py

@@ -0,0 +1,171 @@
+"""Rectangular conformal map of a disk-like triangle mesh.
+
+Python port of the MATLAB code https://github.com/garyptchoi/rectangular-conformal-map,
+Copyright (c) 2015-2024 Gary Pui-Tung Choi, licensed under the Apache License 2.0 (see
+LICENSE-rectangular-conformal-map). Modified from the original: translated to
+Python/NumPy/SciPy, vectorised, Tutte fallback also used when the harmonic map folds, and
+the optimal height (step 3) left out, since flatpoints rescales the rectangle to the unit
+square anyway.
+
+Reference:
+    T. W. Meng, G. P.-T. Choi and L. M. Lui, "TEMPO: Feature-Endowed Teichmüller Extremal
+    Mappings of Point Clouds", SIAM Journal on Imaging Sciences, 9(4), 1922-1962, 2016.
+
+Steps:
+    1. Disk: harmonic map (cotangent Laplacian) of the mesh onto the unit disk, the
+       boundary placed by arc length.
+    2. Square: generalised Laplace equation built from the Beltrami coefficient of the
+       disk map, with x = 0 / 1 on the left / right sides and y = 0 / 1 on the bottom / top
+       sides, the sides being the boundary arcs between the four corners.
+"""
+import numpy as np
+from scipy.sparse import coo_matrix, diags
+from scipy.sparse.linalg import factorized
+
+
+def rectangular_conformal_map(v, f, corners):
+    """(nv, 2) conformal map of the disk mesh (v, f) onto the unit square.
+
+    Args:
+        v: (nv, 3) vertices.
+        f: (nf, 3) triangles of a mesh with the topology of a disk (one boundary loop, no
+            boundary vertex in a single triangle).
+        corners: 4 boundary vertices sent to (0, 0), (1, 0), (1, 1), (0, 1).
+    """
+    loop = boundary_loop(f)
+    where = np.full(len(v), -1)
+    where[loop] = np.arange(len(loop))
+    if (where[corners] < 0).any():
+        raise ValueError("the corners must lie on the boundary")
+    loop = np.roll(loop, -where[corners[0]])
+    where[loop] = np.arange(len(loop))
+    i1, i2, i3 = where[corners[1:]]
+    if not i1 < i2 < i3:  # the corners turn the other way round: reverse the loop
+        loop = np.r_[loop[0], loop[:0:-1]]
+        where[loop] = np.arange(len(loop))
+        i1, i2, i3 = where[corners[1:]]
+
+    disk = disk_map(v, f, loop)
+
+    # Square: bottom = loop[0..i1], right = loop[i1..i2], top = loop[i2..i3], left = rest
+    A = generalized_laplacian(disk, f, beltrami_coefficient(disk, f, v))
+    left_right = np.r_[loop[i3:], loop[0], loop[i1:i2 + 1]]
+    bottom_top = np.r_[loop[:i1 + 1], loop[i2:i3 + 1]]
+    x = _dirichlet(A, left_right, loop[i1:i2 + 1], len(v))()
+    y = _dirichlet(A, bottom_top, loop[i2:i3 + 1], len(v))()
+    return np.c_[x, y]
+
+
+def disk_map(v, f, loop):
+    """(nv, 2) harmonic map onto the unit disk, the boundary `loop` placed by arc length.
+    Falls back to the Tutte map (always bijective) if the harmonic map folds."""
+    arc = np.linalg.norm(v[loop] - v[np.roll(loop, -1)], axis=1)
+    theta = 2 * np.pi * np.r_[0, np.cumsum(arc)[:-1]] / arc.sum()
+    target = np.c_[np.cos(theta), np.sin(theta)]
+    for laplacian in (cotangent_laplacian(v, f), tutte_laplacian(len(v), f)):
+        disk = _dirichlet(laplacian, loop, None, len(v))(target)
+        if np.isfinite(disk).all() and _orientation_consistent(disk, f):
+            break
+    return disk
+
+
+def boundary_loop(f):
+    """Vertices of the boundary of a disk mesh, in order. Raises ValueError if the boundary
+    is not a single simple loop."""
+    he = np.r_[f[:, [0, 1]], f[:, [1, 2]], f[:, [2, 0]]].astype(np.int64)
+    n = he.max() + 1
+    bd = he[~np.isin(he[:, 0] * n + he[:, 1], he[:, 1] * n + he[:, 0])]
+    if len(bd) == 0:
+        raise ValueError("the mesh has no boundary")
+    nxt = np.full(n, -1)
+    nxt[bd[:, 0]] = bd[:, 1]
+    if len(np.unique(bd[:, 0])) != len(bd):
+        raise ValueError("pinched boundary (a vertex is met twice)")
+    loop = [bd[0, 0]]
+    for _ in range(len(bd) - 1):
+        loop.append(nxt[loop[-1]])
+    if nxt[loop[-1]] != loop[0] or len(set(loop)) != len(bd):
+        raise ValueError("the boundary has several loops")
+    return np.array(loop)
+
+
+def cotangent_laplacian(v, f):
+    """(nv, nv) cotangent Laplacian (negative semi-definite)."""
+    n = len(v)
+    L = 0
+    for a, b, c in ((0, 1, 2), (1, 2, 0), (2, 0, 1)):
+        # cotangent of the angle at c, weight of the edge (a, b)
+        e1, e2 = v[f[:, a]] - v[f[:, c]], v[f[:, b]] - v[f[:, c]]
+        cot = (e1 * e2).sum(1) / np.maximum(np.linalg.norm(np.cross(e1, e2), axis=1), 1e-30)
+        L = L + coo_matrix((cot / 2, (f[:, a], f[:, b])), shape=(n, n))
+    L = L + L.T
+    return (L - diags(np.asarray(L.sum(1)).ravel())).tocsr()
+
+
+def tutte_laplacian(n, f):
+    """(n, n) graph Laplacian of the mesh edges, uniform weights."""
+    e = np.r_[f[:, [0, 1]], f[:, [1, 2]], f[:, [2, 0]]]
+    W = coo_matrix((np.ones(len(e)), (e[:, 0], e[:, 1])), shape=(n, n)).tocsr()
+    W = ((W + W.T) > 0).astype(float)
+    return W - diags(np.asarray(W.sum(1)).ravel())
+
+
+def beltrami_coefficient(domain, f, image):
+    """(nf,) complex Beltrami coefficient of the map domain (2D) -> image (2D or 3D),
+    piecewise linear on the triangles."""
+    p = domain[f]  # (nf, 3, 2)
+    e = p[:, [2, 0, 1]] - p[:, [1, 2, 0]]  # edge opposite to each vertex
+    area2 = e[:, 0, 0] * e[:, 1, 1] - e[:, 0, 1] * e[:, 1, 0]
+    # gradient of the hat function of each vertex: rot90(opposite edge) / (2 area)
+    gx, gy = e[..., 1] / area2[:, None], -e[..., 0] / area2[:, None]  # (nf, 3)
+    q = image[f]  # (nf, 3, d)
+    du, dv = np.einsum("fk,fkd->fd", gx, q), np.einsum("fk,fkd->fd", gy, q)
+    E, G, F = (du * du).sum(1), (dv * dv).sum(1), (du * dv).sum(1)
+    return (E - G + 2j * F) / (E + G + 2 * np.sqrt(np.maximum(E * G - F ** 2, 0)))
+
+
+def generalized_laplacian(v, f, mu):
+    """(nv, nv) Laplacian of the metric of Beltrami coefficient `mu` on the 2D mesh v."""
+    mu = np.where(np.abs(mu) < 0.999, mu, 0.999 * mu / np.abs(mu))  # keep it invertible
+    m2 = np.abs(mu) ** 2
+    a = (1 - 2 * mu.real + m2) / (1 - m2)
+    b = -2 * mu.imag / (1 - m2)
+    g = (1 + 2 * mu.real + m2) / (1 - m2)
+    p = v[f]
+    rot = p[:, [2, 0, 1]] - p[:, [1, 2, 0]]  # opposite edges, (nf, 3, 2)
+    ux, uy = rot[..., 1], -rot[..., 0]  # rotated by 90 degrees
+    area2 = np.abs(rot[:, 0, 0] * rot[:, 1, 1] - rot[:, 0, 1] * rot[:, 1, 0])
+    n = len(v)
+    A = 0
+    for i in range(3):
+        for j in range(3):
+            w = (a * ux[:, i] * ux[:, j] + b * (ux[:, i] * uy[:, j] + ux[:, j] * uy[:, i])
+                 + g * uy[:, i] * uy[:, j]) / area2
+            A = A + coo_matrix((-w, (f[:, i], f[:, j])), shape=(n, n))
+    return A.tocsr()
+
+
+def _dirichlet(M, fixed, ones, n):
+    """Solver of M x = b with x fixed on the vertices `fixed`. With `ones`, the returned
+    function takes no argument and solves for x = 1 on `ones`, 0 on the rest of `fixed`;
+    otherwise it takes the values on `fixed` (k, d) and returns x (n, d)."""
+    free = np.ones(n)
+    free[fixed] = 0
+    solve = factorized((diags(free) @ M + diags(1 - free)).tocsc())
+    if ones is not None:
+        b = np.zeros(n)
+        b[ones] = 1
+        return lambda: solve(b)
+
+    def run(values):
+        b = np.zeros((n, values.shape[1]))
+        b[fixed] = values
+        return np.stack([solve(c) for c in b.T], 1)
+    return run
+
+
+def _orientation_consistent(uv, f):
+    """True if no triangle of the 2D map is flipped or degenerate."""
+    d1, d2 = uv[f[:, 1]] - uv[f[:, 0]], uv[f[:, 2]] - uv[f[:, 0]]
+    s = d1[:, 0] * d2[:, 1] - d1[:, 1] * d2[:, 0]
+    return (s > 0).all() or (s < 0).all()