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
Source code and notebooks to reproduce experiments and benchmarks on Bias Faces in the Wild (BFW).

Face Recognition: Too Bias, or Not Too Bias? Robinson, Joseph P., Gennady Livitz, Yann Henon, Can Qin, Yun Fu, and Samson Timoner. "Face recognition:

Joseph P. Robinson 41 Dec 12, 2022
A check for whether the dependency jobs are all green.

alls-green A check for whether the dependency jobs are all green. Why? Do you have more than one job in your GitHub Actions CI/CD workflows setup? Do

Re:actors 33 Jan 03, 2023
A quantum game modeling of pandemic (QHack 2022)

Contributors: @JongheumJung, @YoonjaeChung, @GyunghunKim Abstract In the regime of a global pandemic, leaders around the world need to consider variou

Yoonjae Chung 8 Apr 03, 2022
This repo is customed for VisDrone.

Object Detection for VisDrone(无人机航拍图像目标检测) My environment 1、Windows10 (Linux available) 2、tensorflow = 1.12.0 3、python3.6 (anaconda) 4、cv2 5、ensemble

53 Jul 17, 2022
A PyTorch Implementation of Gated Graph Sequence Neural Networks (GGNN)

A PyTorch Implementation of GGNN This is a PyTorch implementation of the Gated Graph Sequence Neural Networks (GGNN) as described in the paper Gated G

Ching-Yao Chuang 427 Dec 13, 2022
NAS-Bench-x11 and the Power of Learning Curves

NAS-Bench-x11 NAS-Bench-x11 and the Power of Learning Curves Shen Yan, Colin White, Yash Savani, Frank Hutter. NeurIPS 2021. Surrogate NAS benchmarks

AutoML-Freiburg-Hannover 13 Nov 18, 2022
Minecraft agent to farm resources using reinforcement learning

BarnyardBot CS 175 group project using Malmo download BarnyardBot.py into the python examples directory and run 'python BarnyardBot.py' in the console

0 Jul 26, 2022
Neural Scene Flow Fields for Space-Time View Synthesis of Dynamic Scenes

Neural Scene Flow Fields PyTorch implementation of paper "Neural Scene Flow Fields for Space-Time View Synthesis of Dynamic Scenes", CVPR 2021 [Projec

Zhengqi Li 583 Dec 30, 2022
Usable Implementation of "Bootstrap Your Own Latent" self-supervised learning, from Deepmind, in Pytorch

Bootstrap Your Own Latent (BYOL), in Pytorch Practical implementation of an astoundingly simple method for self-supervised learning that achieves a ne

Phil Wang 1.4k Dec 29, 2022
This program creates a formatted excel file which highlights the undervalued stock according to Graham's number.

Over-and-Undervalued-Stocks Of Nepse Using Graham's Number Scrap the latest data using different websites and creates a formatted excel file that high

6 May 03, 2022
Large scale and asynchronous Hyperparameter Optimization at your fingertip.

Syne Tune This package provides state-of-the-art distributed hyperparameter optimizers (HPO) where trials can be evaluated with several backend option

Amazon Web Services - Labs 236 Jan 01, 2023
An implementation of DeepMind's Relational Recurrent Neural Networks in PyTorch.

relational-rnn-pytorch An implementation of DeepMind's Relational Recurrent Neural Networks (Santoro et al. 2018) in PyTorch. Relational Memory Core (

Sang-gil Lee 241 Nov 18, 2022
[ICCV-2021] An Empirical Study of the Collapsing Problem in Semi-Supervised 2D Human Pose Estimation

An Empirical Study of the Collapsing Problem in Semi-Supervised 2D Human Pose Estimation (ICCV 2021) Introduction This is an official pytorch implemen

rongchangxie 42 Jan 04, 2023
Semi-supervised Learning for Sentiment Analysis

Neural-Semi-supervised-Learning-for-Text-Classification-Under-Large-Scale-Pretraining Code, models and Datasets for《Neural Semi-supervised Learning fo

47 Jan 01, 2023
MatryODShka: Real-time 6DoF Video View Synthesis using Multi-Sphere Images

Main repo for ECCV 2020 paper MatryODShka: Real-time 6DoF Video View Synthesis using Multi-Sphere Images. visual.cs.brown.edu/matryodshka

Brown University Visual Computing Group 75 Dec 13, 2022
TensorFlow implementation of Elastic Weight Consolidation

Elastic weight consolidation Introduction A TensorFlow implementation of elastic weight consolidation as presented in Overcoming catastrophic forgetti

James Stokes 67 Oct 11, 2022
A module for solving and visualizing Schrödinger equation.

qmsolve This is an attempt at making a solid, easy to use solver, capable of solving and visualize the Schrödinger equation for multiple particles, an

506 Dec 28, 2022
Semi-supervised Representation Learning for Remote Sensing Image Classification Based on Generative Adversarial Networks

SSRL-for-image-classification Semi-supervised Representation Learning for Remote Sensing Image Classification Based on Generative Adversarial Networks

Feng 2 Nov 19, 2021
Code For TDEER: An Efficient Translating Decoding Schema for Joint Extraction of Entities and Relations (EMNLP2021)

TDEER (WIP) Code For TDEER: An Efficient Translating Decoding Schema for Joint Extraction of Entities and Relations (EMNLP2021) Overview TDEER is an e

Alipay 6 Dec 17, 2022
Readings for "A Unified View of Relational Deep Learning for Polypharmacy Side Effect, Combination Therapy, and Drug-Drug Interaction Prediction."

Polypharmacy - DDI - Synergy Survey The Survey Paper This repository accompanies our survey paper A Unified View of Relational Deep Learning for Polyp

AstraZeneca 79 Jan 05, 2023