potpourri3d - An invigorating blend of 3D geometry tools in Python.

Overview

potpourri3d

A Python library of various algorithms and utilities for 3D triangle meshes and point clouds. Managed by Nicholas Sharp, with new tools added lazily as needed. Currently, mainly bindings to C++ tools from geometry-central.

pip install potpourri3d

The blend includes:

  • Mesh and point cloud reading/writing to a few file formats
  • Use heat methods to compute distance, parallel transport, logarithmic maps, and more

Installation

Potpourri3d is on the pypi package index with precompiled binaries for most configuations. Get it like:

pip install potpourri3d

If none of the precompiled binaries match your system, pip will attempt to compile the library from scratch. This requires cmake and a workng C++ compiler toolchain.

Note: Some bound functions invoke sparse linear solvers internally. The precompiled binaries use Eigen's solvers; using Suitesparse's solvers instead may significantly improve performance & robustness. To get them, locally compile the package on a machine with Suitesparse installed using the command below (relevant docs).

python -m pip install potpourri3d --no-binary potpourri3d

Documentation

Input / Output

Read/write meshes and point clouds from some common formats.

  • read_mesh(filename) Reads a mesh from file. Returns numpy matrices V, F, a Nx3 real numpy array of vertices and a Mx3 integer numpy array of 0-based face indices (or Mx4 for a quad mesh, etc).

    • filename the path to read the file from. Currently supports the same file types as geometry-central. The file type is inferred automatically from the path extension.
  • write_mesh(V, F, filename) Write a mesh from file. Returns numpy matrices V, F, a Vx3 real array of vertices and a Fx3 integer array of 0-based face indices (or Fx4 for a quad mesh, etc).

    • V a Nx3 real numpy array of vertices
    • F a Mx3 integer numpy array of faces, with 0-based vertex indices (or Mx4 for a quad mesh, etc).
    • filename the path to write the file to. Currently supports the same file types as geometry-central. The file type is inferred automatically from the path extension.

Mesh Distance

Use the heat method for geodesic distance to compute geodesic distance on surfaces. Repeated solves are fast after initial setup. Uses intrinsic triangulations internally for increased robustness.

import potpourri3d as pp3d

# = Stateful solves (much faster if computing distance many times)
solver = pp3d.MeshHeatMethodDistanceSolver(V,F)
dist = solver.compute_distance(7)
dist = solver.compute_distance_multisource([1,2,3])  

# = One-off versions
dist = pp3d.compute_distance(V,F,7)
dist = pp3d.compute_distance_multisource(V,F,[1,3,4])
  • MeshHeatMethodDistanceSolver(self, V, F, t_coef=1., use_robust=True) construct an instance of the solver class.
    • V a Nx3 real numpy array of vertices
    • F a Mx3 integer numpy array of faces, with 0-based vertex indices (triangle meshes only, but need not be manifold).
    • t_coef set the time used for short-time heat flow. Generally don't change this. If necessary, larger values may make the solution more stable at the cost of smoothing it out.
    • use_robust use intrinsic triangulations for increased robustness. Generaly leave this enabled.
  • MeshHeatMethodDistanceSolver.compute_distance(v_ind) compute distance from a single vertex, given by zero-based index. Returns an array of distances.
  • MeshHeatMethodDistanceSolver.compute_distance_multisource(v_ind_list) compute distance from the nearest of a collection of vertices, given by a list of zero-based indices. Returns an array of distances.
  • compute_distance(V, F, v_ind) Similar to above, but one-off instead of stateful. Returns an array of distances.
  • compute_distance_multisource(V, F, v_ind_list) Similar to above, but one-off instead of stateful. Returns an array of distances.

Mesh Vector Heat

Use the vector heat method to compute various interpolation & vector-based quantities on meshes. Repeated solves are fast after initial setup.

import potpourri3d as pp3d

# = Stateful solves
V, F = # a Nx3 numpy array of points and Mx3 array of triangle face indices
solver = pp3d.MeshVectorHeatSolver(V,F)

# Extend the value `0.` from vertex 12 and `1.` from vertex 17. Any vertex 
# geodesically closer to 12. will take the value 0., and vice versa 
# (plus some slight smoothing)
ext = solver.extend_scalar([12, 17], [0.,1.])

# Get the tangent frames which are used by the solver to define tangent data
# at each vertex
basisX, basisY, basisN = solver.get_tangent_frames()

# Parallel transport a vector along the surface
# (and map it to a vector in 3D)
sourceV = 22
ext = solver.transport_tangent_vector(sourceV, [6., 6.])
ext3D = ext[:,0,np.newaxis] * basisX +  ext[:,1,np.newaxis] * basisY

# Compute the logarithmic map
logmap = solver.compute_log_map(sourceV)
ps_mesh.add_parameterization_quantity("logmap", logmap)
  • MeshVectorHeatSolver(self, V, F, t_coef=1.) construct an instance of the solver class.
    • V a Nx3 real numpy array of vertices
    • F a Mx3 integer numpy array of faces, with 0-based vertex indices (triangle meshes only, should be manifold).
    • t_coef set the time used for short-time heat flow. Generally don't change this. If necessary, larger values may make the solution more stable at the cost of smoothing it out.
  • MeshVectorHeatSolver.extend_scalar(v_inds, values) nearest-geodesic-neighbor interpolate values defined at vertices. Vertices will take the value from the closest source vertex (plus some slight smoothing)
    • v_inds a list of source vertices
    • values a list of scalar values, one for each source vertex
  • MeshVectorHeatSolver.get_tangent_frames() get the coordinate frames used to define tangent data at each vertex. Returned as a tuple of basis-X, basis-Y, and normal axes, each as an Nx3 array. May be necessary for change-of-basis into or out of tangent vector convention.
  • MeshVectorHeatSolver.transport_tangent_vector(v_ind, vector) parallel transports a single vector across a surface
    • v_ind index of the source vertex
    • vector a 2D tangent vector to transport
  • MeshVectorHeatSolver.transport_tangent_vectors(v_inds, vectors) parallel transports a collection of vectors across a surface, such that each vertex takes the vector from its nearest-geodesic-neighbor.
    • v_inds a list of source vertices
    • vectors a list of 2D tangent vectors, one for each source vertex
  • MeshVectorHeatSolver.compute_log_map(v_ind) compute the logarithmic map centered at the given source vertex
    • v_ind index of the source vertex

Point Cloud Distance & Vector Heat

Use the heat method for geodesic distance and vector heat method to compute various interpolation & vector-based quantities on point clouds. Repeated solves are fast after initial setup.

point cloud vector heat examples

import potpourri3d as pp3d

# = Stateful solves
P = # a Nx3 numpy array of points
solver = pp3d.PointCloudHeatSolver(P)

# Compute the geodesic distance to point 4
dists = solver.compute_distance(4)

# Extend the value `0.` from point 12 and `1.` from point 17. Any point 
# geodesically closer to 12. will take the value 0., and vice versa 
# (plus some slight smoothing)
ext = solver.extend_scalar([12, 17], [0.,1.])

# Get the tangent frames which are used by the solver to define tangent data
# at each point
basisX, basisY, basisN = solver.get_tangent_frames()

# Parallel transport a vector along the surface
# (and map it to a vector in 3D)
sourceP = 22
ext = solver.transport_tangent_vector(sourceP, [6., 6.])
ext3D = ext[:,0,np.newaxis] * basisX +  ext[:,1,np.newaxis] * basisY

# Compute the logarithmic map
logmap = solver.compute_log_map(sourceP)
  • PointCloudHeatSolver(self, P, t_coef=1.) construct an instance of the solver class.
    • P a Nx3 real numpy array of points
    • t_coef set the time used for short-time heat flow. Generally don't change this. If necessary, larger values may make the solution more stable at the cost of smoothing it out.
  • PointCloudHeatSolver.extend_scalar(p_inds, values) nearest-geodesic-neighbor interpolate values defined at points. Points will take the value from the closest source point (plus some slight smoothing)
    • v_inds a list of source points
    • values a list of scalar values, one for each source points
  • PointCloudHeatSolver.get_tangent_frames() get the coordinate frames used to define tangent data at each point. Returned as a tuple of basis-X, basis-Y, and normal axes, each as an Nx3 array. May be necessary for change-of-basis into or out of tangent vector convention.
  • PointCloudHeatSolver.transport_tangent_vector(p_ind, vector) parallel transports a single vector across a surface
    • p_ind index of the source point
    • vector a 2D tangent vector to transport
  • PointCloudHeatSolver.transport_tangent_vectors(p_inds, vectors) parallel transports a collection of vectors across a surface, such that each vertex takes the vector from its nearest-geodesic-neighbor.
    • p_inds a list of source points
    • vectors a list of 2D tangent vectors, one for each source point
  • PointCloudHeatSolver.compute_log_map(p_ind) compute the logarithmic map centered at the given source point
    • p_ind index of the source point
Comments
  • Poor geodesic distance accuracy in a simple case

    Poor geodesic distance accuracy in a simple case

    Forgive me if my expectations for accuracy are unreasonable for the HEAT method. I have the following minimal example

    import numpy as np
    from potpourri3d import MeshHeatMethodDistanceSolver
    
    solver = MeshHeatMethodDistanceSolver(np.array([[0, 0, 0], [1, 0, 0], [0, 1, 0]]), np.array([[0, 1, 2]]))
    solver.compute_distance(0) # -> array([0.        , 0.70710654, 0.70710654])
    solver.compute_distance(1) # -> array([0.91430181, 0.        , 1.31933315])
    solver.compute_distance(2) # -> array([0.91430181, 1.31933315, 0.        ])
    

    The fact that the first example is returning distances of sqrt(2)/2 makes it seem like this is a bug rather than a limitation of the method somehow.

    Its worth noting that setting t_coef=0.001 makes the results of the second two cases more accurate, but the first case returns [0. , 0.70710654, 0.70710654] no matter the value of t_coef

    opened by brucedjones 3
  • RuntimeError: vertices lie on disconnected components of the surface

    RuntimeError: vertices lie on disconnected components of the surface

    I load a mesh with triangle faces. Then I try to execute these code lines: ` path_solver = pp3d.EdgeFlipGeodesicSolver(V, F) # shares precomputation for repeated solves

    path_pts = path_solver.find_geodesic_path(v_start=0, v_end=100)`

    But launch "RuntimeError: vertices lie on disconnected components of the surface".

    How to solve this problem??

    opened by facundolazcano 2
  • Geodesic from a predefined path?

    Geodesic from a predefined path?

    Thank you so much for making the python binding! I use mainly use python for geometry stuff, so this is extremely helpful.

    I'm working on some anthropometry, and trying to extract the rise curve, from the navel down the crotch and up to the lower back. I'm trying to use the edge flip solver for this, but the shorter path it found is around the side of the torso. According to the paper, it seems it should be possible to optimize a path through a different direction. Would that be possible to do with the python binding? Screen Shot 2021-05-27 at 10 22 20 AM

    enhancement 
    opened by panangam 2
  • Randomly generated mesh test fails

    Randomly generated mesh test fails

    Hello!

    I've been trying to figure out how to generate a 2D circle mesh for use with potpourri3d, but I keep getting this error: self-edge in face list [x] -- [x]. While investigating, I came across your test functions, generate_verts() and generate_faces(). When I tried to load a mesh using those two, I also got self-edge in face list. However, puzzlingly, I could use the bunny mesh without any errors.

    Other errors I got while trying to make my circle mesh work include vertex [x] appears in more than one boundary loop and duplicate edge in list [i] -- [j].

    I'm confused because polyscope renders the meshes correctly, but potpourri3d has a hard time with the same meshes.

    Thank you!

    image

    import numpy as np
    import polyscope as ps
    import potpourri3d as pp3d
    
    # Initialize polyscope
    ps.init()
    
    def generate_verts(n_pts=999):
        np.random.seed(777)        
        return np.random.rand(n_pts, 3)
    
    def generate_faces(n_pts=999):
        # n_pts should be a multiple of 3 for indexing to work out
        np.random.seed(777)        
        rand_faces = np.random.randint(0, n_pts, size=(2*n_pts,3))
        coverage_faces = np.arange(n_pts).reshape(-1, 3)
        faces = np.vstack((rand_faces, coverage_faces))
        return faces
    
    verts = generate_verts()
    faces = generate_faces()
    solver = pp3d.MeshVectorHeatSolver(verts, faces)
    ps.register_surface_mesh("random mesh", verts, faces, smooth_shade=True)
    
    verts, faces = pp3d.read_mesh("bunny_small.ply")
    solver = pp3d.MeshVectorHeatSolver(verts, faces)
    ps.register_surface_mesh("bunny mesh", verts, faces, smooth_shade=True)
    
    radians = np.linspace(0, 2*np.pi-(2*np.pi/40), 40)
    unit_circle = np.stack((np.cos(radians), np.sin(radians), radians*0), axis=1)
    verts = unit_circle
    faces = []
    for i in range(0, verts.shape[0]):
        if i == verts.shape[0]-1:
            faces.append([i, 0, 0])
        else:
            faces.append([i, i+1, 0])
    faces = np.array(faces)
    solver = pp3d.MeshVectorHeatSolver(verts, faces)
    ps.register_surface_mesh("unit circle mesh", verts, faces, smooth_shade=True)
    
    ps.show()
    
    opened by mhr 2
  • First Step of Gradually Adding Types to the Python Module

    First Step of Gradually Adding Types to the Python Module

    Hey Nicholas,

    Thank you for making an excellent github repository, it has been awesome to use for my research. I have found that the lack of typings to be tough when passing values in and out. In this PR I have begun the process of gradually adding types to the python code so that way users can get typed inputs and outputs to their functions and nice hover support.

    I have added some doc comments but I wanted you to see the general tone of these first couple before I wrote the rest to ensure that they align with what you'd have ideally done. Let me know if you'd like to see any changes.

    opened by jparr721 0
  • Exposing face correspondence for geodesic edges derived from EdgeFlipGeodesicSolver

    Exposing face correspondence for geodesic edges derived from EdgeFlipGeodesicSolver

    Currently we are building a feature that requires us to find which face IDs the edges that connects geodesic point pairs lie on. Currently, we have to solve this in R3 since we have to perform barycentric check on all of the faces, and it gets extremely slow on large meshes. Similar performance is observed when we use trimesh. It would be very useful to have EdgeFlipGeodesicSolver to return geodesic points, geodesic edges, and the face id on which the geodesic edges lie on (instead of just geodesic points) in the case that the mesh is triangular. I hope it would be useful for other users too, especially if they have to propagate linear equations from the derived geodesic path.

    opened by variant-tech 0
  • Geodesic Loop through a Specific Point?

    Geodesic Loop through a Specific Point?

    I am attempting to compute a geodesic loop through a specific point, but when I use either find_geodesic_loop or find_geodesic_path_poly, the returned path does not contain any of the input points. What I would like is to find a loop through a given point, and use the seed path (loop) to determine the isotopy group of the path.

    This image shows what I get currently. The red points are what I input to either find_geodesic_loop or find_geodesic_path_poly. The red line is the result of both of those methods, while the blue line is what I'm hoping for; a loop that starts and ends at the point pointed to in green.

    Is there a way to achieve this?

    geodesic_loop

    opened by deGravity 0
  • On-face point input for MeshHeatMethodDistanceSolver / EdgeFlipGeodesicSolver

    On-face point input for MeshHeatMethodDistanceSolver / EdgeFlipGeodesicSolver

    Hello,

    Thank you for the amazing library! I was wondering if there is planned support for using any point on the mesh's surface (not exclusively vertices) as inputs for MeshHeatMethodDistanceSolver and EdgeFlipGeodesicSolver. From what I gather it's already a feature within geometry-central as SurfacePoint().

    Thanks!

    opened by variant-tech 0
  • Geodesic pairwise distance

    Geodesic pairwise distance

    Hi,

    I would like to get the geodesic pairwise distance of a mesh. I saw that there are some methods to get the distance for a specific each. However, I did not see how to get efficiently the pairwise distance.

    Thanks,

    opened by dhorka 0
  • Feature Request : Connection Laplacian (to project DiffusionNet gradients in spectral basis)

    Feature Request : Connection Laplacian (to project DiffusionNet gradients in spectral basis)

    Thank you for this super useful tool ! At present, we cannot have access to the connection Laplacian operator used for Heat Diffusion on tangent vector fields (defined on vertices). It would be useful to be able to access it from the solver (with point cloud and with mesh if possible), for instance L = solver.connection_laplacian() The idea would be to use this laplacian to write gradients (defined at points) in spectral basis. In this spirit, it could be useful to access gradient operators from within the solver too (since they have to be written in the local complex basis at each point which has to be the same as the one for the laplacian I suppose) for instance G = solver.complex_gradient(). Alternatively, one could use for instance gradients defined in DiffusionNet but they would have to agree with the local basis of the connection Laplacian of the solver.

    I hope this is enough information, thanks again for your huge help !

    opened by nicolasdonati 0
Releases(v0.0.8)
Owner
Nicholas Sharp
Nicholas Sharp
Self-supervised Point Cloud Prediction Using 3D Spatio-temporal Convolutional Networks

Self-supervised Point Cloud Prediction Using 3D Spatio-temporal Convolutional Networks This is a Pytorch-Lightning implementation of the paper "Self-s

Photogrammetry & Robotics Bonn 111 Dec 06, 2022
Pytorch codes for Feature Transfer Learning for Face Recognition with Under-Represented Data

FTLNet_Pytorch Pytorch codes for Feature Transfer Learning for Face Recognition with Under-Represented Data 1. Introduction This repo is an unofficial

1 Nov 04, 2020
ETMO: Evolutionary Transfer Multiobjective Optimization

ETMO: Evolutionary Transfer Multiobjective Optimization To promote the research on ETMO, benchmark problems are of great importance to ETMO algorithm

Songbai Liu 0 Mar 16, 2021
CPF: Learning a Contact Potential Field to Model the Hand-object Interaction

Contact Potential Field This repo contains model, demo, and test codes of our paper: CPF: Learning a Contact Potential Field to Model the Hand-object

Lixin YANG 99 Dec 26, 2022
Extremely simple and fast extreme multi-class and multi-label classifiers.

napkinXC napkinXC is an extremely simple and fast library for extreme multi-class and multi-label classification, that focus of implementing various m

Marek Wydmuch 43 Nov 14, 2022
Reinforcement Learning Theory Book (rus)

Reinforcement Learning Theory Book (rus)

qbrick 206 Nov 27, 2022
CO-PILOT: COllaborative Planning and reInforcement Learning On sub-Task curriculum

CO-PILOT CO-PILOT: COllaborative Planning and reInforcement Learning On sub-Task curriculum, NeurIPS 2021, Shuang Ao, Tianyi Zhou, Guodong Long, Qingh

Shuang Ao 1 Feb 18, 2022
Understanding Convolutional Neural Networks from Theoretical Perspective via Volterra Convolution

nnvolterra Run Code Compile first: make compile Run all codes: make all Test xconv: make npxconv_test MNIST dataset needs to be downloaded, converted

1 May 24, 2022
Code for the SIGIR 2022 paper "Hybrid Transformer with Multi-level Fusion for Multimodal Knowledge Graph Completion"

MKGFormer Code for the SIGIR 2022 paper "Hybrid Transformer with Multi-level Fusion for Multimodal Knowledge Graph Completion" Model Architecture Illu

ZJUNLP 68 Dec 28, 2022
LAVT: Language-Aware Vision Transformer for Referring Image Segmentation

LAVT: Language-Aware Vision Transformer for Referring Image Segmentation Where we are ? 12.27 目前和原论文仍有1%左右得差距,但已经力压很多SOTA了 ckpt__448_epoch_25.pth mIoU

zichengsaber 60 Dec 11, 2022
[ICCV 2021] Released code for Causal Attention for Unbiased Visual Recognition

CaaM This repo contains the codes of training our CaaM on NICO/ImageNet9 dataset. Due to my recent limited bandwidth, this codebase is still messy, wh

Wang Tan 66 Dec 31, 2022
RefineGNN - Iterative refinement graph neural network for antibody sequence-structure co-design (RefineGNN)

Iterative refinement graph neural network for antibody sequence-structure co-des

Wengong Jin 83 Dec 31, 2022
[NeurIPS 2021] Galerkin Transformer: a linear attention without softmax

[NeurIPS 2021] Galerkin Transformer: linear attention without softmax Summary A non-numerical analyst oriented explanation on Toward Data Science abou

Shuhao Cao 159 Dec 20, 2022
[CVPR 2021] Unsupervised Degradation Representation Learning for Blind Super-Resolution

DASR Pytorch implementation of "Unsupervised Degradation Representation Learning for Blind Super-Resolution", CVPR 2021 [arXiv] Overview Requirements

Longguang Wang 318 Dec 24, 2022
Official PyTorch implementation of "Rapid Neural Architecture Search by Learning to Generate Graphs from Datasets" (ICLR 2021)

Rapid Neural Architecture Search by Learning to Generate Graphs from Datasets This is the official PyTorch implementation for the paper Rapid Neural A

48 Dec 26, 2022
Python scripts form performing stereo depth estimation using the HITNET model in Tensorflow Lite.

TFLite-HITNET-Stereo-depth-estimation Python scripts form performing stereo depth estimation using the HITNET model in Tensorflow Lite. Stereo depth e

Ibai Gorordo 22 Oct 20, 2022
Citation Intent Classification in scientific papers using the Scicite dataset an Pytorch

Citation Intent Classification Table of Contents About the Project Built With Installation Usage Acknowledgments About The Project Citation Intent Cla

Federico Nocentini 4 Mar 04, 2022
A Python Package For System Identification Using NARMAX Models

SysIdentPy is a Python module for System Identification using NARMAX models built on top of numpy and is distributed under the 3-Clause BSD license. N

Wilson Rocha 175 Dec 25, 2022
POPPY (Physical Optics Propagation in Python) is a Python package that simulates physical optical propagation including diffraction

POPPY: Physical Optics Propagation in Python POPPY (Physical Optics Propagation in Python) is a Python package that simulates physical optical propaga

Space Telescope Science Institute 132 Dec 15, 2022