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"]

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".

Parallelism

OpenMP threads are used 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:

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:

License information

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