Introduction¶

Python package for fitting polynomials to mesh surface patches. Under the hood the implementation uses CGAL’s Local Differential Properties Estimation via Monge Jet Fitting.

Quick Start¶

Python Package¶

import meshio
from surface_poly_fit import PolyhedralSurface, MongeJetFitter

# Read in the mesh
mesh = meshio.read("my_mesh.ply")

# Create the polyhedral surface mesh data structure.
faces = sum(list(np.asanyarray(cells.data).tolist() for cells in mesh.cells), list())
polyhedral_surface = PolyhedralSurface(vertices=mesh.points, faces=faces)

# Create the object which performs the polynomial fitting to surface patches.
degree_poly_fit = 2  # Degree of fitting polynomial
degree_monge = 2  # Degree of Monge polynomial
fitter = MongeJetFitter(polyhedral_surface, degree_poly_fit, degree_monge)

# Fit a polynomial to the vertices in the 4-ring neighbourhood of a single vertex.
# Number of rings (num_rings) is the number of mesh-edge-hops,
# the more rings, the larger the surface patch.
result_array_vtx = fitter.fit_at_vertex(polyhedral_surface.num_vertices // 2, num_rings=4)

# Fit a polynomial in the 4-ring neighbourhood of each vertex.
result_array = fitter.fit_all(num_rings=4)

# Principle curvatures for all vertices of the surface-mesh:
result_array["k"]

# Write polyhedral-surface and polynomial-fitting-results as point-data in VTK .vtu file
meshio.write("my_mesh_surface_poly_fit_results.vtu", fitter.to_meshio_mesh(result_array))

Command Line¶

Perform polynomial fitting at all vertices of mesh for different neighbourhood sizes (num_rings=2,4,8,16):

$ surface_poly_fit                           \
    --degree_poly_fit=2                      \
    --degree_monge=2                         \
    --num_rings=2,4,8,16                     \
    --output_file=my_mesh_surf_poly_fit.npz  \
    my_mesh.ply

The output file my_mesh_surf_poly_fit.npz is a numpy .npz file containing entries: "surface_poly_fit_result", "vertices", "faces" and "vertex_normals".

The output my_mesh_surf_poly_fit.npz file can be converted to a VTK unstructured grid (.vtu) file (e.g. for visualization using Paraview) using:

$ surface_poly_fit_r2m my_mesh_surf_poly_fit.npz

which will write a series of files (one file per --num_rings option): my_mesh_surf_poly_fit_nr002.vtu, my_mesh_surf_poly_fit_nr004.vtu, my_mesh_surf_poly_fit_nr008.vtu and my_mesh_surf_poly_fit_nr016.vtu.

Parallelism¶

Polynomial fitting (surface_poly_fit) uses OpenMP threads for coarse parallelism (each thread runs a chunk of vertex fitting). The number of threads is controlled with the OMP_NUM_THREADS environment variable, a maximum number of threads (depends on execution environment) is used by default.

Installation¶

Install from latest github source:

$ python -m pip install --user git+https://github.com/Shane-J-Latham/surface_poly_fit.git#egg=surface_poly_fit

or from source directory:

$ git clone git@github.com/Shane-J-Latham/surface_poly_fit.git
$ cd surface_poly_fit
$ python -m pip install --user .

If you’re on windows, you can use vcpkg to manage non-python dependencies (can also be used on Linux and MacOS):

PS > git clone https://github.com/microsoft/vcpkg
PS > .\vcpkg\bootstrap-vcpkg.bat
PS > $Env:VCPKG_ROOT=$(Resolve-Path ./vcpkg)
PS > git clone git@github.com/Shane-J-Latham/surface_poly_fit.git
PS > cd surface_poly_fit
PS > python -m pip install --user .

You also still need to have build tools installed (some kind of C/C++ compiler). One way to achieve this is to install Visual Studio Build tools. Visual studio build tools likely require the installation of visual studio community edition first. This link should (hopefully) get you started:

https://visualstudio.microsoft.com/downloads/

Requirements¶

Build requires:

Runtime requires:

Unit-tests additionally require:

Testing¶

Run unit-tests:

$ python -m surface_poly_fit.tests

Latest source code¶

Source at github:

https://github.com/Shane-J-Latham/surface_poly_fit

Documentation¶

Documentation at surface_poly_fit read-the-docs.

Generate sphinx docs from the source tree using sphinx_build directly:

$ sphinx_build -j 4 docs/source docs/_build/html

and browse at docs/_build/html/index.html.

Documentation build requires:

mistune<1 (version < 1 required for m2r)
m2r
sphinx_rtd_theme
sphinx-argparse
myst_parser

License information¶

See the file LICENSE for terms & conditions, for usage and a DISCLAIMER OF ALL WARRANTIES.