flatpoints 0.1.0__py3-none-any.whl

flatpoints/__init__.py

@@ -0,0 +1,8 @@
+"""Flatten a point cloud into square images: one pixel per point, neighbour pixels hold neighbour points."""
+from .datasets import datasets, load
+from .examples import exemple_compression, exemple_flat, exemple_sampler
+from .main import Compressor, Flat, Resampler
+
+__all__ = ["Flat", "Resampler", "Compressor", "load", "datasets",
+           "exemple_flat", "exemple_sampler", "exemple_compression"]
+__version__ = "0.1.0"

flatpoints/compressor.py

@@ -0,0 +1,139 @@
+"""Compression of the images of a `Flat`: three methods, used by `main.Compressor`.
+
+Each method takes the images A (m, n, n), m = n_faces x channels, and a budget in bits, and
+returns (code, reconstructed A, bits): what would be stored, what it decodes to, its size.
+
+- svd: truncated SVD of each image, U, S, Vt stored as float32.
+- dct: 2D DCT of each image, uniformly quantized, entropy coded per frequency band (as JPEG,
+  with one transform over the whole image).
+- wavelet: 2D wavelet transform (biorthogonal 4.4, as JPEG2000), uniformly quantized,
+  entropy coded per subband. Needs PyWavelets (`pip install "flatpoints[compress]"`).
+
+dct and wavelet use the step of the quantization to fit the budget. Their size is the one of
+an ideal entropy coder per band (zeroth-order entropy): a theoretical bound, a real arithmetic
+coder is a few percent larger.
+
+`to_jp2` / `from_jp2` write and read a real file instead: the images in JPEG2000 (16 bits),
+a standard format that any JPEG2000 reader opens. Needs Pillow.
+"""
+import io
+import json
+from importlib.util import find_spec
+
+import numpy as np
+from scipy.fft import dctn, idctn
+
+FLOAT = 32   # bits of a stored float (svd, quantization step)
+BANDS = 12   # dct: number of frequency bands, each with its own entropy coder
+
+
+def svd(A, budget):
+    """Keep the k largest singular values of each image, k (2n + 1) floats per image."""
+    m, n = A.shape[:2]
+    k = int(np.clip(budget // (FLOAT * m * (2 * n + 1)), 1, n))
+    U, S, Vt = np.linalg.svd(A, full_matrices=False)
+    code = {"U": U[..., :k], "S": S[..., :k], "Vt": Vt[..., :k, :]}
+    rec = (code["U"] * code["S"][..., None, :]) @ code["Vt"]
+    return code, rec, FLOAT * m * k * (2 * n + 1)
+
+
+def dct(A, budget):
+    """Quantized 2D DCT, the frequencies grouped in bands of u + v."""
+    n = A.shape[1]
+    u, v = np.meshgrid(np.arange(n), np.arange(n), indexing="ij")
+    bands = np.minimum((u + v) * BANDS // (2 * n - 1), BANDS - 1)
+    C = dctn(A, axes=(1, 2), norm="ortho")
+    q, step, bits = _quantize(C, [bands == b for b in range(BANDS)], budget)
+    code = {"coefficients": q, "step": step}
+    return code, idctn(q * step, axes=(1, 2), norm="ortho"), bits
+
+
+def wavelet(A, budget, name="bior4.4"):
+    """Quantized 2D wavelet transform (periodic), one entropy coder per subband."""
+    import pywt
+    n = A.shape[1]
+    level = min(4, pywt.dwt_max_level(n, pywt.Wavelet(name).dec_len))
+    arrays = [pywt.coeffs_to_array(pywt.wavedec2(a, name, mode="periodization", level=level))
+              for a in A]
+    C, slices = np.stack([a for a, _ in arrays]), arrays[0][1]
+    bands = [np.zeros(C.shape[1:], bool) for _ in range(1 + 3 * level)]
+    bands[0][slices[0]] = True
+    for j, details in enumerate(slices[1:]):
+        for i, key in enumerate(("ad", "da", "dd")):
+            bands[1 + 3 * j + i][details[key]] = True
+    q, step, bits = _quantize(C, bands, budget)
+
+    def inverse(c):
+        coeffs = pywt.array_to_coeffs(c, slices, output_format="wavedec2")
+        return pywt.waverec2(coeffs, name, mode="periodization")[:n, :n]
+
+    code = {"coefficients": q, "step": step, "wavelet": name, "level": level}
+    return code, np.stack([inverse(c) for c in q * step]), bits
+
+
+METHODS = {"svd": svd, "dct": dct, "wavelet": wavelet}
+
+
+def available():
+    """The methods that can run here: wavelet only if PyWavelets is installed."""
+    return list(METHODS) if find_spec("pywt") else ["svd", "dct"]
+
+
+# === Quantization ===
+
+def _entropy(q):
+    """Bits of an ideal entropy coder (zeroth order) for the integers q."""
+    _, counts = np.unique(q, return_counts=True)
+    return -(counts * np.log2(counts / counts.sum())).sum()
+
+
+def _quantize(C, bands, budget):
+    """(q, step, bits): C / step rounded, with the finest step whose size fits the
+    budget (bisection on log(step)); each band of coefficients is coded on its own."""
+    def size(step):
+        q = np.round(C / step)
+        return q, FLOAT + sum(_entropy(q[:, b]) for b in bands)
+
+    lo, hi = np.log(np.abs(C).max() * 1e-7 + 1e-30), np.log(np.abs(C).max() * 2 + 1e-30)
+    for _ in range(40):
+        mid = (lo + hi) / 2
+        lo, hi = (lo, mid) if size(np.exp(mid))[1] <= budget else (mid, hi)
+    q, bits = size(np.exp(hi))
+    return q.astype(np.int32), float(np.exp(hi)), bits
+
+
+# === JPEG2000 file ===
+
+def to_jp2(images, padding, budget):
+    """Bytes of a JPEG2000 file of the xyz images (n_faces, n, n, 3), at most `budget` bits.
+
+    The images are quantized to 16 bits within their bounding box and laid out in one
+    grayscale image: one row of images per face, x, y and z side by side. A JSON comment in
+    the file holds what the decoder needs: the number of faces, the bounding box and the
+    flat indices of the `padding` pixels (copies of other points, dropped when reading).
+    """
+    from PIL import Image
+    faces, n = images.shape[:2]
+    lo, hi = images.reshape(-1, 3).min(0), images.reshape(-1, 3).max(0)
+    q = np.round((images - lo) / np.maximum(hi - lo, 1e-30) * 65535).astype(np.uint16)
+    mosaic = q.transpose(0, 1, 3, 2).reshape(faces * n, 3 * n)  # face rows, x | y | z
+    header = json.dumps({"faces": faces, "lo": lo.tolist(), "hi": hi.tolist(),
+                         "padding": np.sort(padding).tolist()}, separators=(",", ":")).encode()
+    rate = 16 * mosaic.size / max(budget - 8 * len(header), 1)  # compression ratio asked
+    buffer = io.BytesIO()
+    Image.fromarray(mosaic).save(buffer, "JPEG2000", quality_mode="rates", irreversible=True,
+                                 quality_layers=[max(rate, 1.0)], comment=header)
+    return buffer.getvalue()
+
+
+def from_jp2(data):
+    """(N, 3) points of a file written by `to_jp2`, in the order of the pixels."""
+    from PIL import Image
+    image = Image.open(io.BytesIO(data))
+    header = json.loads(image.info["comment"])
+    faces = header["faces"]
+    n = image.size[1] // faces
+    q = np.asarray(image, float).reshape(faces, n, 3, n).transpose(0, 1, 3, 2)
+    lo, hi = np.array(header["lo"]), np.array(header["hi"])
+    points = (q / 65535 * (hi - lo) + lo).reshape(-1, 3)
+    return np.delete(points, header["padding"], axis=0)

flatpoints/core.py

@@ -0,0 +1,36 @@
+"""Core of flatpoints: the image of one face (a chart of the cut surface).
+
+    1. rectangular conformal map of the mesh of the face onto the unit square (`conformal_uv`);
+    2. the image: the points sorted on an n x n grid by their conformal uv (`image_cells`).
+"""
+import numpy as np
+
+from .rcm import boundary_loop, rectangular_conformal_map
+from .utils import grid_sort
+
+
+# === Conformal uv and image ===
+
+def conformal_uv(V, F, ab):
+    """(nv, 2) conformal map of the disk mesh (V, F) onto the unit square.
+
+    Args:
+        ab: (nv, 2) horizontal and up coordinates of the vertices: the corners of the
+            square go to the boundary vertices closest to the corners of the silhouette.
+    """
+    loop = boundary_loop(F)
+    x = (ab[loop] - ab[loop].mean(0)) / np.maximum(ab[loop].std(0), 1e-12)
+    corner = [np.argmax(sa * x[:, 0] + sb * x[:, 1])  # position on the loop
+              for sa, sb in ((-1, -1), (1, -1), (1, 1), (-1, 1))]
+    # the corners must follow each other along the loop, in one direction or the other
+    turn = np.argsort((np.array(corner) - corner[0]) % len(loop))
+    ordered = np.array_equal(turn, [0, 1, 2, 3]) or np.array_equal(turn, [0, 3, 2, 1])
+    if not ordered or len(set(corner)) < 4:
+        corner = corner[0] + np.arange(4) * len(loop) // 4  # odd silhouette: quarters
+    return rectangular_conformal_map(V, F, loop[np.mod(corner, len(loop))])
+
+
+def image_cells(uv, n, verbose=False):
+    """(n, n) index of the point of each pixel (-1: empty), from the uv of the points.
+    Image layout: u along the columns, v up the rows."""
+    return grid_sort(uv, n, verbose).reshape(n, n).T[::-1]

flatpoints/datasets.py

@@ -0,0 +1,100 @@
+"""Example point clouds, downloaded on demand from the GitHub repository of flatpoints.
+
+The clouds are derived from third-party 3D models and are NOT covered by the licence of
+flatpoints: they are not shipped in the package, but fetched from
+https://github.com/neighborhood-grid/flatpoints/tree/main/data the first time they are
+used, then cached on disk. Each one keeps the terms of its original model (see `MODELS`,
+or data/README.md in the repository): check them before any use, and credit the sources.
+
+    points = fp.load("bunny")   # (10000, 3) float32
+    fp.datasets()               # names, sources and terms
+"""
+import hashlib
+import os
+import urllib.request
+from pathlib import Path
+
+import numpy as np
+
+URL = "https://raw.githubusercontent.com/neighborhood-grid/flatpoints/main/data/{}_points.npy"
+
+_STANFORD = "Stanford 3D Scanning Repository terms: research use, no commercial use without permission"
+_RESEARCH = "research and non-commercial use, copyright of the creator"
+_AIMATSHAPE = ("AIM@SHAPE licence: research and non-commercial use; credit \"Elephant model is "
+               "provided courtesy of INRIA by the AIM@SHAPE Shape Repository\"")
+
+# name: (sha256 of the .npy, source, terms)
+MODELS = {
+    "airplane": ("3e2f639783dfbe25f20eb8efdab8dad71cf1a49c2c8f8ad7236d024638e18f1f",
+                 "PLY format sample file, shipped with PyVista", "origin and licence not documented"),
+    "armadillo": ("ce922b4a83772bbe3ecc903acf5dfcec1a567923cc42d6ac748e5d4376cfac9b",
+                  "Stanford Computer Graphics Laboratory", _STANFORD),
+    "bunny": ("aa3cdba2c957156b197d8e0937587a98281dbd87bd542f601dc06c5973d09a84",
+              "Stanford Computer Graphics Laboratory", _STANFORD),
+    "cow": ("5cfd15b81d98813ce5e5bab9ccbdc57da31d6f3f03fc4e4d9aea18a47a537dcf",
+            "Viewpoint Animation Engineering / Sun Microsystems", _RESEARCH),
+    "dragon": ("427a14245f5340a73cad43e85d9133ff0d3fb60e98bac989352bad306670e13d",
+               "Stanford Computer Graphics Laboratory", _STANFORD),
+    "elephant": ("24649adc1293b018faa4c3cdb2a20b7b7c5fa272280924954dcbb73eacc826d6",
+                 "INRIA, via the AIM@SHAPE Shape Repository", _AIMATSHAPE),
+    "everest": ("cc9dec8654673f60cef75490d493bb600eeb967f5695e7a2e45d145ce99ea97c",
+                "Copernicus DEM GLO-90 (ESA)",
+                "free licence; credit \"produced using Copernicus WorldDEM-90 (c) DLR e.V. 2010-2014 and "
+                "(c) Airbus Defence and Space GmbH 2014-2018 provided under COPERNICUS by the "
+                "European Union and ESA; all rights reserved\""),
+    "horse": ("bb760ad2ed22ca8639c81ce121abf87791ffa50d78af5dec7c311526287f523f",
+              "Cyberware, Georgia Tech Large Geometric Models Archive", _RESEARCH),
+    "max_planck": ("2cae575f579f426656c25ae8bbb01535a7848d829e684d87e638a03e0ca81f5b",
+                   "Max-Planck-Institut für Informatik", _RESEARCH),
+    "spot": ("3f0a01a5c628cf112799db085dd0e279ce2c52b7e78a8843514087d689626d2f",
+             "Keenan Crane", "CC0 1.0 (public domain)"),
+}
+
+
+def cache_dir():
+    """Where the downloaded clouds are kept: $FLATPOINTS_DATA, else the user cache."""
+    if os.environ.get("FLATPOINTS_DATA"):
+        return Path(os.environ["FLATPOINTS_DATA"])
+    if os.name == "nt":
+        base = Path(os.environ.get("LOCALAPPDATA", Path.home() / "AppData" / "Local"))
+    else:
+        base = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache"))
+    return base / "flatpoints"
+
+
+def datasets():
+    """{name: (source, terms)} of the example point clouds."""
+    return {name: (source, terms) for name, (_, source, terms) in MODELS.items()}
+
+
+def load(name, verbose=True):
+    """(N, 3) float32 example point cloud `name` (see `datasets()`), downloaded on first use.
+
+    The cloud is derived from a third-party model and keeps its terms, which are printed
+    at download: they are not those of flatpoints.
+    """
+    if name not in MODELS:
+        raise ValueError(f"unknown point cloud {name!r}, available: {', '.join(MODELS)}")
+    sha, source, terms = MODELS[name]
+    path = cache_dir() / f"{name}_points.npy"
+    if not path.exists() or _sha256(path.read_bytes()) != sha:
+        url = URL.format(name)
+        if verbose:
+            print(f"flatpoints: downloading {name} from {url}\n"
+                  f"  source: {source}\n  terms: {terms} (not the flatpoints licence)")
+        with urllib.request.urlopen(url, timeout=60) as response:
+            data = response.read()
+        if _sha256(data) != sha:
+            raise OSError(f"{url}: checksum mismatch, the file may have changed upstream")
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(".part")
+        tmp.write_bytes(data)
+        tmp.replace(path)
+    return np.load(path)
+
+
+def _sha256(data):
+    return hashlib.sha256(data).hexdigest()
+
+
+__all__ = ["load", "datasets", "cache_dir"]

flatpoints/examples.py

@@ -0,0 +1,171 @@
+"""Ready-to-run examples on the point clouds of `fp.datasets()`, straight from the package:
+
+    import flatpoints as fp
+    flat = fp.exemple_flat("bunny")             # flattening: surface and images
+    sampler = fp.exemple_sampler("bunny")       # resampling with a hyperuniform seed
+    comp = fp.exemple_compression("bunny")      # compression of the xyz images
+
+Each one prints what it computes, shows its figure (needs `flatpoints[viz]`,
+`flatpoints[compress]` for the compression) and returns its result. `save="plots"`
+also writes the figure in that folder (plots/, plots/resampling/, plots/compression/), and
+`exemple_flat(..., animate=True)` the animation in plots/animation/.
+"""
+import tempfile
+from pathlib import Path
+
+import numpy as np
+
+from .datasets import load
+from .main import Compressor, Flat
+
+
+def flatten(model):
+    """`Flat` of the example point cloud `model`. A closed object (cow, bunny...) is cut in two
+    faces, left and right, across the normal axis x. A terrain (everest) is an open surface:
+    a single face, seen from above (normal axis z)."""
+    points = load(model)
+    everest = model == "everest"
+    return Flat(points, single_face=everest, normal_axis="z" if everest else "x")
+
+
+def exemple_flat(model="bunny", save=None, show=True, animate=False):
+    """Flatten `model` and plot the surface in 3D with its images; with `animate`, also the
+    animation of the images folding into the surface (saved as save/animation/<model>.webp
+    if `save`). Returns the `Flat`."""
+    flat = flatten(model)
+    points = flat.points
+    print("points  ", points.shape)               # (N, 3)
+    print("pixels  ", flat.pixels.shape)          # (N, 3) (face, row, col), face 0 if single face
+    print("images  ", (flat.n_faces, flat.n, flat.n))
+    print("padding ", flat.corners.idxs.shape)    # (Npadding,) points repeated in the empty pixels
+    if flat.faces is not None:
+        print("faces   ", {f: len(i) for f, i in flat.faces.items()})
+
+    # The point cloud as an image: (n_faces, n, n, 3), n_faces = 2 (left, right) or 1
+    image = np.zeros((flat.n_faces, flat.n, flat.n, 3))
+    image[tuple(flat.pixels.T)] = points                              # each point on its pixel
+    image[tuple(flat.corners.pixels.T)] = points[flat.corners.idxs]   # fill the empty pixels
+    assert np.array_equal(image, flat.to_image(points))               # the same, in one call
+
+    # The flattening at a glance: the surface in 3D and its images, RGB and checkerboard
+    fig = flat.plot()
+    _finish(fig, save, f"{model}.png", show)
+    # Any per-point data (N, *C) as images: flat.imshow(points[:, 2])
+
+    # The same, animated: the images fold into the surface in 3D, and back
+    if animate:
+        path = None
+        if save:
+            path = Path(save) / "animation" / f"{model}.webp"
+            path.parent.mkdir(parents=True, exist_ok=True)
+        anim = flat.imshow(animate=path or True)  # resolution="high": cleaner, slower
+        if path:
+            print("saved    ", path)
+        if show:
+            import matplotlib.pyplot as plt
+            plt.show()
+        del anim
+    return flat
+
+
+def exemple_sampler(model="bunny", n_points=512, save=None, show=True):
+    """Resample `model` with `n_points` new points, transported from a window of the
+    hyperuniform seed. Returns the `Resampler`."""
+    flat = flatten(model)
+    sampler = flat.resample(n_points=n_points)
+    print("flat     ", flat.n_faces, "faces of", flat.n, "x", flat.n)
+    print("points   ", sampler.points.shape)   # (n_points, 3) the new points
+    print("faces    ", sampler.faces.shape)    # (n_points,)   face of each new point
+    print("pixels   ", sampler.pixels.shape)   # (n_points, 3) float (face, row, col)
+    # Another, independent resampling, without recomputing the flat: flat.resample(n_points, seed=1)
+
+    # The new points (discs) on the mesh of the full cloud (quads of the flat)
+    fig = sampler.plot()
+    _finish(fig, save and Path(save) / "resampling", f"{model}_resampled.png", show)
+    return sampler
+
+
+def exemple_compression(model="bunny", factor=0.8, save=None, show=True):
+    """Compress `model`, compare the methods, and write / read a JPEG2000 file.
+    Returns the `Compressor` of `factor`."""
+    import matplotlib.pyplot as plt
+    from scipy.spatial import cKDTree
+
+    from .compressor import available
+    from .viz import camera
+
+    flat = flatten(model)
+    points = flat.points
+
+    # `factor` of the storage saved (against float32 points), the most accurate method
+    comp = flat.compress(factor=factor)
+    print("method   ", comp.method)              # "dct", "wavelet" or "svd"
+    print("saved    ", f"{comp.ratio:.1%}", f"({comp.bits / len(points):.1f} bits per point)")
+    print("code     ", {k: getattr(v, "shape", v) for k, v in comp.code.items()})
+    print("points   ", comp.points.shape)        # (N, 3) reconstructed, same order as points
+
+    # Error of each point, in point spacings (mean distance to the nearest neighbour)
+    spacing = cKDTree(points).query(points, k=2)[0][:, 1].mean()
+    for method in available():
+        c = flat.compress(factor, method=method)
+        print(f"{method:8s} {factor:.0%}: RMS error {c.error / spacing:.3f} spacings")
+
+    # Strong compressions (default method), coloured by the error of each point; then the
+    # RMS error of each method against the storage saved
+    factors = [0.9, 0.95, 0.98, 0.99]
+    comps = [flat.compress(f) for f in factors]
+    errors = [np.linalg.norm(c.points - points, axis=1) / spacing for c in comps]
+    proj = camera(flat.normal_axis)
+    fig, axs = plt.subplots(1, len(factors) + 2, figsize=(4 * (len(factors) + 2), 4),
+                            layout="constrained")
+    vmax = np.percentile(errors[-1], 95)
+    panels = [("original", points, None)] + [
+        (f"{c.ratio:.0%} saved, {c.method}", c.points, e) for c, e in zip(comps, errors)]
+    for ax, (title, xyz, err) in zip(axs, panels):
+        p = xyz @ proj.T
+        order = np.argsort(p[:, 2])  # far first
+        if err is None:
+            ax.scatter(p[order, 0], p[order, 1], s=1, c="0.4")
+        else:
+            sc = ax.scatter(p[order, 0], p[order, 1], s=1, c=err[order], cmap="magma_r",
+                            vmin=0, vmax=vmax)
+        ax.set_title(title)
+        ax.set_aspect("equal")
+        ax.axis("off")
+    fig.colorbar(sc, ax=axs[-2], label="error (point spacings)")
+    grid = np.linspace(0.5, 0.995, 30)
+    for method in available():
+        curve = [flat.compress(f, method=method) for f in grid]
+        axs[-1].plot([100 * c.ratio for c in curve], [c.error / spacing for c in curve],
+                     label=method)
+    axs[-1].set_xlabel("storage saved (%)")
+    axs[-1].set_ylabel("RMS error (point spacings)")
+    axs[-1].set_yscale("log")
+    axs[-1].set_xlim(50, 100)
+    axs[-1].grid(alpha=0.3)
+    axs[-1].legend()
+
+    # A real file: the points in JPEG2000 (any JPEG2000 reader opens it), and back
+    with tempfile.TemporaryDirectory() as tmp:
+        path = Path(tmp) / f"{model}.jp2"
+        size = comp.save(path)
+        print("file     ", f"{path.name}: {size} bytes ({8 * size / len(points):.1f} bits per point)")
+        print("read     ", Compressor.read(path).shape)  # (N, 3)
+
+    _finish(fig, save and Path(save) / "compression", f"{model}.png", show, dpi=100)
+    return comp
+
+
+def _finish(fig, folder, name, show, **kwargs):
+    """Save `fig` as folder/name if `folder`, then show it if `show`."""
+    import matplotlib.pyplot as plt
+
+    if folder:
+        Path(folder).mkdir(parents=True, exist_ok=True)
+        fig.savefig(Path(folder) / name, **kwargs)
+        print("saved    ", Path(folder) / name)
+    if show:
+        plt.show()
+
+
+__all__ = ["exemple_flat", "exemple_sampler", "exemple_compression"]