pyfmaps 1.2.0__tar.gz → 1.3.0__tar.gz

pyfmaps-1.3.0/.github/workflows/documentation.yml

@@ -0,0 +1,63 @@
+name: Documentation
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+  workflow_dispatch:
+  release:
+
+jobs:
+  build_documentation:
+    name: Build Documentation
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0 # setuptools_scm needs tags to compute the version
+
+    # VTK's rendering libraries link against libGL at import time, and the
+    # gallery renders PyVista scenes off-screen. Since VTK 9.5 the stock wheel
+    # does headless rendering through EGL, so libegl1 is enough and no Xvfb is
+    # needed. NB: libgl1-mesa-glx does not exist on ubuntu-24.04 (what
+    # ubuntu-latest now resolves to) -- it is libgl1 + libglx-mesa0.
+    - name: Install VTK runtime libraries
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y --no-install-recommends \
+          libgl1 libegl1 libglx-mesa0 libxrender1
+
+    - uses: astral-sh/setup-uv@v5
+      with:
+        enable-cache: true
+
+    # dev + docs come from [tool.uv] default-groups; viz via pyfmaps[viz].
+    - name: Install dependencies from the lockfile
+      run: uv sync --locked
+
+    # -d keeps Sphinx's doctree cache out of the published directory. It defaults
+    # to <outdir>/.doctrees, which means it gets deployed to the website: 12 MB of
+    # build artifacts (61% of the push) plus an environment.pickle containing
+    # absolute build paths.
+    - name: Build HTML
+      run: uv run sphinx-build -d docs/_build/doctrees -b html docs/source/ docs/_build/html
+
+    - name: upload artifact
+      uses: actions/upload-artifact@v4
+      with:
+        path:
+          docs/_build/html/
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v4
+      if: github.ref == 'refs/heads/master'
+      with:
+        publish_branch: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: docs/_build/html
+        force_orphan: true

{pyfmaps-1.2.0 → pyfmaps-1.3.0}/.github/workflows/test_and_deploy.yml

@@ -20,7 +20,7 @@ jobs:
     strategy:
       matrix:
         platform: [windows-latest, ubuntu-latest, macos-latest]
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
 
     steps:
       - uses: actions/checkout@v4

{pyfmaps-1.2.0 → pyfmaps-1.3.0}/.gitignore

@@ -3,6 +3,11 @@ docs/source/generated/*
 docs/make.bat
 docs/Makefile
 
+# sphinx-gallery output (regenerated on every build)
+docs/source/auto_examples/
+docs/source/gen_modules/
+docs/source/sg_execution_times.rst
+
 # Byte-compiled / optimized / DLL files
 __pycache__/
 *.py[cod]
@@ -82,6 +87,7 @@ target/
 # Pycharm and VSCode
 .idea/
 venv/
+.venv/
 .vscode/
 
 # IPython Notebook
@@ -102,3 +108,6 @@ small_test.ipynb
 # Dask
 dask-worker-space/
 
+
+# research scratch, not part of the package
+studies/

{pyfmaps-1.2.0 → pyfmaps-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyfmaps
-Version: 1.2.0
+Version: 1.3.0
 Summary: Python bindings for functional maps
 Author: Robin Magnet
 License: MIT License
@@ -35,13 +35,12 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.8
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.8
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy
@@ -50,21 +49,9 @@ Requires-Dist: potpourri3d>=1.3
 Requires-Dist: robust_laplacian
 Requires-Dist: tqdm
 Requires-Dist: scikit-learn
-Provides-Extra: dev
-Requires-Dist: ruff; extra == "dev"
-Requires-Dist: pre-commit; extra == "dev"
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Requires-Dist: build; extra == "dev"
-Provides-Extra: docs
-Requires-Dist: furo; extra == "docs"
-Requires-Dist: myst_parser>=0.13; extra == "docs"
-Requires-Dist: sphinx>=4.0; extra == "docs"
-Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
-Requires-Dist: sphinx-copybutton; extra == "docs"
-Requires-Dist: sphinx-design; extra == "docs"
-Requires-Dist: sphinx-gallery; extra == "docs"
-Requires-Dist: sphinx-math-dollar; extra == "docs"
+Provides-Extra: viz
+Requires-Dist: pyvista[jupyter]>=0.44; extra == "viz"
+Requires-Dist: matplotlib; extra == "viz"
 Dynamic: license-file
 
 # pyFM - Python Functional Maps Library
@@ -73,11 +60,15 @@ Dynamic: license-file
   <img src="doc/zoomout.gif" alt="animated" />
 </p>
 
-[![](https://github.com/RobinMagnet/pyFM/actions/workflows/documentation.yml/badge.svg)](https://robinmagnet.github.io/pyFM/)
+[![PyPI version](https://img.shields.io/pypi/v/pyfmaps.svg)](https://pypi.org/project/pyfmaps/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyfmaps.svg)](https://pypi.org/project/pyfmaps/)
+[![License: MIT](https://img.shields.io/pypi/l/pyfmaps.svg)](https://github.com/RobinMagnet/pyFM/blob/master/LICENSE)
+[![Tests](https://github.com/RobinMagnet/pyFM/actions/workflows/test_and_deploy.yml/badge.svg)](https://github.com/RobinMagnet/pyFM/actions/workflows/test_and_deploy.yml)
+[![Documentation](https://github.com/RobinMagnet/pyFM/actions/workflows/documentation.yml/badge.svg)](https://robinmagnet.github.io/pyFM/)
 
-**NEW** API Documentation is available [here](https://robinmagnet.github.io/pyFM/)
+This package contains a comprehensive Python implementation for shape correspondence using functional maps, featuring code from [multiple papers](#implemented-papers).
 
-This package contains a comprehensive Python implementation for shape correspondence using functional maps, featuring code from [multiple papers](#implemented-papers)
+Full [API documentation](https://robinmagnet.github.io/pyFM/) is available online.
 
 ## Core Features
 - Complete TriMesh class with geometric measures (geodesics, normals, LBO projections, differential operators)
@@ -90,13 +81,44 @@ This package contains a comprehensive Python implementation for shape correspond
 ## Installation
 ```bash
 pip install pyfmaps
-```
 
-Please check the PyPi page to ensure the latest version is uploaded.
+# with the optional PyVista-based plotting helpers used in the gallery
+pip install 'pyfmaps[viz]'
+```
 
 ### Key Dependencies
-- Required: numpy, scipy, tqdm, scikit-learn
-- Optional: [`potpourri3d`](https://github.com/nmwsharp/potpourri3d) (geodesics), [`robust_laplacian`](https://github.com/nmwsharp/robust-laplacians-py) (Delaunay/tufted Laplacian)
+Requires Python 3.10+ and: numpy, scipy, tqdm, scikit-learn,
+[`potpourri3d`](https://github.com/nmwsharp/potpourri3d) (geodesic distances via the heat
+and fast-marching methods), and
+[`robust_laplacian`](https://github.com/nmwsharp/robust-laplacians-py) (Delaunay/tufted
+Laplacian). All are installed automatically.
+
+## Quickstart
+```python
+from pyFM.mesh import TriMesh
+from pyFM.functional import FunctionalMapping
+
+# Load a source and a target mesh
+mesh1 = TriMesh.load("cat.off", area_normalize=True, center=True)
+mesh2 = TriMesh.load("lion.off", area_normalize=True, center=True)
+
+# Compute the LBO spectrum + descriptors, then fit a functional map.
+# Keep w_orient above 0: descriptors alone cannot tell left from right,
+# and w_orient=0 (the default) usually returns a symmetry-flipped map.
+model = FunctionalMapping(mesh1, mesh2)
+model.preprocess(descr_type="WKS", subsample_step=2, verbose=True)
+model.fit(K=30, w_descr=1e0, w_lap=1e-1, w_dcomm=1e0, w_orient=1e0, verbose=True)
+
+# Convert the functional map to a point-to-point map (mesh2 -> mesh1)
+p2p_21 = model.get_p2p()
+
+# Refine the map -- this is where most of the accuracy comes from
+FM_zo = model.zoomout_refine(nit=16, step=5)
+p2p_21_zo = model.get_p2p(FM_zo)
+```
+
+See the [example gallery](https://robinmagnet.github.io/pyFM/auto_examples/index.html) for
+complete, runnable workflows with interactive 3D figures.
 
 ## Design Philosophy
 This codebase prioritizes readability and adaptability over rigid modularity.
@@ -125,7 +147,7 @@ I selected this approach from my personal experience with research codebases and
 
 ## Documentation & Examples
 - [API Documentation](https://robinmagnet.github.io/pyFM/)
-- [Example Notebooks](https://github.com/RobinMagnet/pyFM/tree/master/examples)
+- [Example Gallery](https://robinmagnet.github.io/pyFM/auto_examples/index.html)
 
 ## Implemented Papers
 This library implements methods from several key papers in shape correspondence, including:

{pyfmaps-1.2.0 → pyfmaps-1.3.0}/README.md

@@ -4,11 +4,15 @@
   <img src="doc/zoomout.gif" alt="animated" />
 </p>
 
-[![](https://github.com/RobinMagnet/pyFM/actions/workflows/documentation.yml/badge.svg)](https://robinmagnet.github.io/pyFM/)
+[![PyPI version](https://img.shields.io/pypi/v/pyfmaps.svg)](https://pypi.org/project/pyfmaps/)
+[![Python versions](https://img.shields.io/pypi/pyversions/pyfmaps.svg)](https://pypi.org/project/pyfmaps/)
+[![License: MIT](https://img.shields.io/pypi/l/pyfmaps.svg)](https://github.com/RobinMagnet/pyFM/blob/master/LICENSE)
+[![Tests](https://github.com/RobinMagnet/pyFM/actions/workflows/test_and_deploy.yml/badge.svg)](https://github.com/RobinMagnet/pyFM/actions/workflows/test_and_deploy.yml)
+[![Documentation](https://github.com/RobinMagnet/pyFM/actions/workflows/documentation.yml/badge.svg)](https://robinmagnet.github.io/pyFM/)
 
-**NEW** API Documentation is available [here](https://robinmagnet.github.io/pyFM/)
+This package contains a comprehensive Python implementation for shape correspondence using functional maps, featuring code from [multiple papers](#implemented-papers).
 
-This package contains a comprehensive Python implementation for shape correspondence using functional maps, featuring code from [multiple papers](#implemented-papers)
+Full [API documentation](https://robinmagnet.github.io/pyFM/) is available online.
 
 ## Core Features
 - Complete TriMesh class with geometric measures (geodesics, normals, LBO projections, differential operators)
@@ -21,13 +25,44 @@ This package contains a comprehensive Python implementation for shape correspond
 ## Installation
 ```bash
 pip install pyfmaps
-```
 
-Please check the PyPi page to ensure the latest version is uploaded.
+# with the optional PyVista-based plotting helpers used in the gallery
+pip install 'pyfmaps[viz]'
+```
 
 ### Key Dependencies
-- Required: numpy, scipy, tqdm, scikit-learn
-- Optional: [`potpourri3d`](https://github.com/nmwsharp/potpourri3d) (geodesics), [`robust_laplacian`](https://github.com/nmwsharp/robust-laplacians-py) (Delaunay/tufted Laplacian)
+Requires Python 3.10+ and: numpy, scipy, tqdm, scikit-learn,
+[`potpourri3d`](https://github.com/nmwsharp/potpourri3d) (geodesic distances via the heat
+and fast-marching methods), and
+[`robust_laplacian`](https://github.com/nmwsharp/robust-laplacians-py) (Delaunay/tufted
+Laplacian). All are installed automatically.
+
+## Quickstart
+```python
+from pyFM.mesh import TriMesh
+from pyFM.functional import FunctionalMapping
+
+# Load a source and a target mesh
+mesh1 = TriMesh.load("cat.off", area_normalize=True, center=True)
+mesh2 = TriMesh.load("lion.off", area_normalize=True, center=True)
+
+# Compute the LBO spectrum + descriptors, then fit a functional map.
+# Keep w_orient above 0: descriptors alone cannot tell left from right,
+# and w_orient=0 (the default) usually returns a symmetry-flipped map.
+model = FunctionalMapping(mesh1, mesh2)
+model.preprocess(descr_type="WKS", subsample_step=2, verbose=True)
+model.fit(K=30, w_descr=1e0, w_lap=1e-1, w_dcomm=1e0, w_orient=1e0, verbose=True)
+
+# Convert the functional map to a point-to-point map (mesh2 -> mesh1)
+p2p_21 = model.get_p2p()
+
+# Refine the map -- this is where most of the accuracy comes from
+FM_zo = model.zoomout_refine(nit=16, step=5)
+p2p_21_zo = model.get_p2p(FM_zo)
+```
+
+See the [example gallery](https://robinmagnet.github.io/pyFM/auto_examples/index.html) for
+complete, runnable workflows with interactive 3D figures.
 
 ## Design Philosophy
 This codebase prioritizes readability and adaptability over rigid modularity.
@@ -56,7 +91,7 @@ I selected this approach from my personal experience with research codebases and
 
 ## Documentation & Examples
 - [API Documentation](https://robinmagnet.github.io/pyFM/)
-- [Example Notebooks](https://github.com/RobinMagnet/pyFM/tree/master/examples)
+- [Example Gallery](https://robinmagnet.github.io/pyFM/auto_examples/index.html)
 
 ## Implemented Papers
 This library implements methods from several key papers in shape correspondence, including:

pyfmaps-1.3.0/docs/source/_static/pyfm.css

@@ -0,0 +1,24 @@
+/* PyVista interactive scenes (sphinx-gallery + pyvista.ext.viewer_directive).
+ *
+ * The viewer directive hardcodes width='100%%' (a literal double percent, see
+ * pyvista/ext/viewer_directive.py). Browsers reject that as an invalid length
+ * and fall back to the default iframe width, so the scene renders in a narrow
+ * box. Force a sane size here rather than patching PyVista.
+ */
+iframe[src*="static_viewer.html"] {
+  width: 100%;
+  min-height: 400px;
+  border: 1px solid var(--color-background-border);
+  border-radius: 4px;
+  background: #ffffff;
+}
+
+/* Keep the Static/Interactive tab panes from collapsing around the iframe. */
+.sd-tab-content:has(> iframe[src*="static_viewer.html"]) {
+  padding: 0;
+}
+
+/* Wide outputs (arrays, timing tables) scroll instead of pushing the page. */
+.sphx-glr-script-out pre {
+  overflow-x: auto;
+}

pyfmaps-1.3.0/docs/source/_templates/autosummary/base.rst

@@ -0,0 +1,8 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}
+
+.. minigallery:: {{ module }}.{{ objname }}
+   :add-heading: Examples using ``{{ objname }}``

{pyfmaps-1.2.0 → pyfmaps-1.3.0}/docs/source/_templates/autosummary/class.rst

@@ -6,3 +6,6 @@
    :members:
    :show-inheritance:
    :member-order: bysource
+
+.. minigallery:: {{ module }}.{{ objname }}
+   :add-heading: Examples using ``{{ objname }}``

{pyfmaps-1.2.0 → pyfmaps-1.3.0}/docs/source/api.rst

@@ -91,6 +91,18 @@ Laplacians, and mesh file readers/writers.
    pyFM.mesh.laplacian
    pyFM.mesh.file_utils
 
+Visualization
+-------------
+
+PyVista-based plotting helpers for meshes, point clouds and vector fields.
+Requires the ``viz`` extra (``pip install 'pyfmaps[viz]'``).
+
+.. autosummary::
+   :toctree: generated
+   :recursive:
+
+   pyFM.viz
+
 Optimization internals
 ----------------------
 

pyfmaps-1.3.0/docs/source/conf.py

@@ -0,0 +1,137 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+
+import importlib.metadata
+import os
+import pathlib
+import re
+import sys
+
+sys.path.insert(0, pathlib.Path(__file__).parents[2].resolve().as_posix())
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = "pyfmaps"
+copyright = "2024, Robin Magnet"
+author = "Robin Magnet"
+try:
+    release = importlib.metadata.version("pyfmaps")
+except importlib.metadata.PackageNotFoundError:
+    release = "0.0.0"
+
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = [
+    "sphinx.ext.duration",
+    "sphinx.ext.doctest",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.intersphinx",
+    "sphinx_autodoc_typehints",  # merge type hints into descriptions (after napoleon)
+    "sphinx_math_dollar",
+    "sphinx.ext.mathjax",
+    "sphinx_copybutton",  # copy button on code blocks
+    "myst_parser",
+    "sphinx_design",
+    "sphinx_gallery.gen_gallery",
+    "pyvista.ext.viewer_directive",  # renders the .vtksz scenes the scraper emits
+]
+
+
+# -- Example gallery (sphinx-gallery + PyVista) ------------------------------
+# The gallery executes examples/gallery/plot_*.py at build time and scrapes the
+# scenes their pl.show() calls produce.
+
+import pyvista as pv  # noqa: E402
+from pyvista.plotting.utilities.sphinx_gallery import DynamicScraper  # noqa: E402
+
+pv.BUILDING_GALLERY = True
+pv.OFF_SCREEN = True
+pv.set_plot_theme("document")
+pv.global_theme.window_size = [1024, 768]
+
+
+def reset_pyvista(gallery_conf, fname):
+    """Keep one example's theme/plotter state from leaking into the next."""
+    pv.close_all()
+    pv.set_plot_theme("document")
+    pv.global_theme.window_size = [1024, 768]
+
+
+sphinx_gallery_conf = {
+    "examples_dirs": "../../examples/gallery",
+    "gallery_dirs": "auto_examples",
+    # Only plot_*.py are executed. os.sep keeps this working on Windows.
+    "filename_pattern": re.escape(os.sep) + r"plot_",
+    # The default ("NumberOfCodeLinesSortKey") orders the gallery by script length.
+    # Sorting by file name lets the file names encode the reading order instead.
+    "within_subsection_order": "FileNameSortKey",
+    "image_scrapers": (DynamicScraper(), "matplotlib"),
+    "doc_module": ("pyFM",),
+    # Rendered by the ``minigallery`` directive in _templates/autosummary/.
+    "backreferences_dir": "gen_modules/backreferences",
+    # The default is ("matplotlib", "seaborn") -- keep matplotlib's reset, since
+    # setting this key replaces the list rather than extending it.
+    "reset_modules": ("matplotlib", reset_pyvista),
+    "reset_modules_order": "both",
+    "remove_config_comments": True,
+}
+
+# sphinx_gallery_conf holds a scraper instance and a reset callback, so Sphinx
+# cannot pickle it into the config cache. Harmless, but noisy on every build.
+suppress_warnings = ["config.cache"]
+
+# Resolve :class:/:meth: roles pointing at our dependencies. A short timeout keeps
+# an unreachable inventory to a warning rather than a stalled build.
+intersphinx_mapping = {
+    "python": ("https://docs.python.org/3", None),
+    "numpy": ("https://numpy.org/doc/stable", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy", None),
+    "matplotlib": ("https://matplotlib.org/stable", None),
+    "pyvista": ("https://docs.pyvista.org", None),
+}
+intersphinx_timeout = 10
+
+# Napoleon (numpydoc parsing)
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = True
+napoleon_use_rtype = True
+
+# Members are documented on their own per-object pages (numpy-style), so module
+# and class pages only render the module/class docstring + summary tables.
+autodoc_default_options = {"member-order": "bysource"}
+autosummary_generate = True
+# Honour each module's __all__ so only intended public names are documented
+# (default True *ignores* __all__, which would leak imported numpy/tqdm/sklearn names).
+autosummary_ignore_module_all = False
+
+templates_path = ["_templates"]
+exclude_patterns = []
+
+source_suffix = [".rst", ".md"]
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = "furo"
+html_static_path = ["_static"]
+html_css_files = ["pyfm.css"]
+
+
+from sphinx.ext.autodoc import between
+
+
+def setup(app):
+    # Register a sphinx.ext.autodoc.between listener to ignore everything
+    # between lines that contain the word IGNORE
+    app.connect("autodoc-process-docstring", between("^.*IGNORE.*$", exclude=True))
+    return {"parallel_read_safe": True}

pyfmaps-1.3.0/docs/source/getting_started.md

@@ -0,0 +1,105 @@
+Getting Started
+===============
+
+This short tutorial computes a functional map between two meshes and converts it
+to a point-to-point correspondence. It is the condensed version of
+[Computing a map without a correspondence](auto_examples/plot_05_maps_without_correspondence),
+which explains every step and shows what each one buys.
+
+Loading meshes
+--------------
+
+A `TriMesh` is read from a file with `TriMesh.load`, or built directly from raw vertex/face arrays:
+
+```python
+from pyFM.mesh import TriMesh
+
+mesh1 = TriMesh.load("cat-00.off", area_normalize=True, center=True)
+mesh2 = TriMesh.load("lion-00.off", area_normalize=True, center=True)
+```
+
+Computing a functional map
+--------------------------
+
+`FunctionalMapping` drives the standard workflow: compute the Laplace-Beltrami
+spectrum and descriptors with `preprocess`, then optimize the map with `fit`.
+
+```python
+from pyFM.functional import FunctionalMapping
+
+model = FunctionalMapping(mesh1, mesh2)
+
+# Spectrum + descriptors
+model.preprocess(
+    descr_type="WKS",    # "WKS" or "HKS"
+    subsample_step=2,    # keep every 2nd descriptor
+    verbose=True,
+)
+
+# Optimize the functional map
+model.fit(
+    K=30,           # eigenvectors kept on each shape
+    w_descr=1e0,    # descriptor preservation
+    w_lap=1e-1,     # Laplacian commutativity
+    w_dcomm=1e0,    # descriptor commutativity
+    w_orient=1e0,   # orientation term
+    verbose=True,
+)
+```
+
+Keep `w_orient` above zero. Descriptors alone cannot tell the left side of a shape
+from its right, so with `w_orient=0` the optimization typically returns a
+symmetry-flipped map that refinement will not fix.
+
+Getting a point-to-point map
+----------------------------
+
+`get_p2p` converts the functional map `model.FM_12` into a vertex-to-vertex map
+`p2p_21` (for each vertex of mesh2, the index of its match on mesh1):
+
+```python
+p2p_21 = model.get_p2p()
+```
+
+Refinement
+----------
+
+The output of `fit` is a starting point, not an answer — refinement is where most
+of the accuracy comes from. ICP and ZoomOut both return a new functional map
+rather than overwriting `model.FM_12`:
+
+```python
+FM_icp = model.icp_refine(verbose=True)
+p2p_21_icp = model.get_p2p(FM_icp)
+
+FM_zo = model.zoomout_refine(nit=16, step=5, verbose=True)
+p2p_21_zo = model.get_p2p(FM_zo)
+```
+
+ZoomOut grows the map by `step` at each of its `nit` iterations, so `K = 30` ends
+at `30 + 16 * 5 = 110`.
+
+Evaluating accuracy
+-------------------
+
+Given an (approximate) ground-truth map and a geodesic distance matrix on the
+source mesh, `pyFM.eval.accuracy` reports the mean geodesic error:
+
+```python
+import numpy as np
+import pyFM.eval
+
+A_geod = mesh1.geodesic_matrix()
+gt_p2p = np.loadtxt("lion2cat", dtype=int)
+
+for name, p2p in [("fit", p2p_21), ("ICP", p2p_21_icp), ("ZoomOut", p2p_21_zo)]:
+    acc = pyFM.eval.accuracy(p2p, gt_p2p, A_geod, sqrt_area=mesh1.sqrt_area)
+    print(f"{name:8s}: {1e2 * acc:.2f}")
+```
+
+On this pair that prints roughly `23.85`, `7.39` and `8.53`, in percent of
+$\sqrt{\text{area}}$: the raw fit is coarse, and refinement is what makes it usable.
+
+A few matched landmarks, passed to `preprocess` as `landmarks=`, cut the error
+further still — see
+[Computing a map without a correspondence](auto_examples/plot_05_maps_without_correspondence).

{pyfmaps-1.2.0 → pyfmaps-1.3.0}/docs/source/index.rst

@@ -43,7 +43,8 @@ Whether you are an academic researcher exploring functional map theory or an ind
 What’s Next?
 ------------
 
-To get started with `pyFM`, check out the example notebook for a quick overview of the package’s capabilities.
+To get started with `pyFM`, work through :doc:`getting_started`, then browse the :ref:`gallery` for runnable
+examples with interactive 3D figures.
 
 .. To get started with `pyFM`, check out the [Installation Guide](#installation) and the [Quickstart Tutorial](#getting-started) for a hands-on introduction. For a deeper dive, explore the [API Reference](#detailed-api-reference) and [Tutorials](#tutorials) to learn more about advanced features and workflows.
 
@@ -57,7 +58,7 @@ Table of Contents
 
    install.md
    getting_started.md
-   examples.md
+   auto_examples/index
 
 .. toctree::
    :maxdepth: 2

{pyfmaps-1.2.0 → pyfmaps-1.3.0}/docs/source/install.md

@@ -2,7 +2,7 @@ Installation
 ============
 
 This package is pretty minimal and should run on all machines. It supports
-Python 3.8+.
+Python 3.10+.
 
 With pip
 --------
@@ -11,6 +11,16 @@ With pip
 pip install pyfmaps
 ```
 
+Plotting
+--------
+
+The plotting helpers in {mod}`pyFM.viz`, used throughout the
+[example gallery](auto_examples/index), are optional and pull in PyVista:
+
+```bash
+pip install 'pyfmaps[viz]'
+```
+
 From source
 -----------