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
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
naked is a Python tool which allows you to strip a model and only keep what matters for making predictions.

naked is a Python tool which allows you to strip a model and only keep what matters for making predictions. The result is a pure Python function with no third-party dependencies that you can simply c

Max Halford 24 Dec 20, 2022
An implementation of the Contrast Predictive Coding (CPC) method to train audio features in an unsupervised fashion.

CPC_audio This code implements the Contrast Predictive Coding algorithm on audio data, as described in the paper Unsupervised Pretraining Transfers we

Meta Research 283 Dec 30, 2022
SW components and demos for visual kinship recognition. An emphasis is put on the FIW dataset-- data loaders, benchmarks, results in summary.

FIW Data Development Kit Table of Contents Introduction Families In the Wild Database Publications Organization To Do License Getting Involved Introdu

Joseph P. Robinson 12 Jun 04, 2022
This is the codebase for the ICLR 2021 paper Trajectory Prediction using Equivariant Continuous Convolution

Trajectory Prediction using Equivariant Continuous Convolution (ECCO) This is the codebase for the ICLR 2021 paper Trajectory Prediction using Equivar

Spatiotemporal Machine Learning 45 Jul 22, 2022
Network Enhancement implementation in pytorch

network_enahncement_pytorch Network Enhancement implementation in pytorch Research paper Network Enhancement: a general method to denoise weighted bio

Yen 1 Nov 12, 2021
Automatic Data-Regularized Actor-Critic (Auto-DrAC)

Auto-DrAC: Automatic Data-Regularized Actor-Critic This is a PyTorch implementation of the methods proposed in Automatic Data Augmentation for General

89 Dec 13, 2022
Human POSEitioning System (HPS): 3D Human Pose Estimation and Self-localization in Large Scenes from Body-Mounted Sensors, CVPR 2021

Human POSEitioning System (HPS): 3D Human Pose Estimation and Self-localization in Large Scenes from Body-Mounted Sensors Human POSEitioning System (H

Aymen Mir 66 Dec 21, 2022
L-Verse: Bidirectional Generation Between Image and Text

Far beyond learning long-range interactions of natural language, transformers are becoming the de-facto standard for many vision tasks with their power and scalabilty

Kim, Taehoon 102 Dec 21, 2022
an implementation of softmax splatting for differentiable forward warping using PyTorch

softmax-splatting This is a reference implementation of the softmax splatting operator, which has been proposed in Softmax Splatting for Video Frame I

Simon Niklaus 338 Dec 28, 2022
Yolov5-opencv-cpp-python - Example of using ultralytics YOLO V5 with OpenCV 4.5.4, C++ and Python

yolov5-opencv-cpp-python Example of performing inference with ultralytics YOLO V

183 Jan 09, 2023
Contrastive Feature Loss for Image Prediction

Contrastive Feature Loss for Image Prediction We provide a PyTorch implementation of our contrastive feature loss presented in: Contrastive Feature Lo

Alex Andonian 44 Oct 05, 2022
Bot developed in Python that automates races in pegaxy.

español | português About it: This is a fork from pega-racing-bot. This bot, developed in Python, is to automate races in pegaxy. The game developers

4 Apr 08, 2022
Unified tracking framework with a single appearance model

Paper: Do different tracking tasks require different appearance model? [ArXiv] (comming soon) [Project Page] (comming soon) UniTrack is a simple and U

ZhongdaoWang 300 Dec 24, 2022
Official Code Release for "TIP-Adapter: Training-free clIP-Adapter for Better Vision-Language Modeling"

Official Code Release for "TIP-Adapter: Training-free clIP-Adapter for Better Vision-Language Modeling" Pipeline of Tip-Adapter Tip-Adapter can provid

peng gao 187 Dec 28, 2022
PyTorchCV: A PyTorch-Based Framework for Deep Learning in Computer Vision.

PyTorchCV: A PyTorch-Based Framework for Deep Learning in Computer Vision @misc{CV2018, author = {Donny You ( Donny You 40 Sep 14, 2022

Link prediction using Multiple Order Local Information (MOLI)

Understanding the network formation pattern for better link prediction Authors: [e

Wu Lab 0 Oct 18, 2021
Codes for CIKM'21 paper 'Self-Supervised Graph Co-Training for Session-based Recommendation'.

COTREC Codes for CIKM'21 paper 'Self-Supervised Graph Co-Training for Session-based Recommendation'. Requirements: Python 3.7, Pytorch 1.6.0 Best Hype

Xin Xia 42 Dec 09, 2022
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