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
Official implementation of "A Unified Objective for Novel Class Discovery", ICCV2021 (Oral)

A Unified Objective for Novel Class Discovery This is the official repository for the paper: A Unified Objective for Novel Class Discovery Enrico Fini

Enrico Fini 118 Dec 26, 2022
Neural-PIL: Neural Pre-Integrated Lighting for Reflectance Decomposition - NeurIPS2021

Neural-PIL: Neural Pre-Integrated Lighting for Reflectance Decomposition Project Page | Video | Paper Implementation for Neural-PIL. A novel method wh

Computergraphics (University of Tübingen) 64 Dec 29, 2022
基于深度强化学习的原神自动钓鱼AI

原神自动钓鱼AI由YOLOX, DQN两部分模型组成。使用迁移学习,半监督学习进行训练。 模型也包含一些使用opencv等传统数字图像处理方法实现的不可学习部分。

4.2k Jan 01, 2023
Haze Removal can remove slight to extreme cases of haze affecting an image

Haze Removal can remove slight to extreme cases of haze affecting an image. Its most typical use is for landscape photography where the haze causes low contrast and low saturation, but it can also be

Grace Ugochi Nneji 3 Feb 15, 2022
Replication attempt for the Protein Folding Model

RGN2-Replica (WIP) To eventually become an unofficial working Pytorch implementation of RGN2, an state of the art model for MSA-less Protein Folding f

Eric Alcaide 36 Nov 29, 2022
A scanpy extension to analyse single-cell TCR and BCR data.

Scirpy: A Scanpy extension for analyzing single-cell immune-cell receptor sequencing data Scirpy is a scalable python-toolkit to analyse T cell recept

ICBI 145 Jan 03, 2023
The object detection pipeline is based on Ultralytics YOLOv5

AYOLOv2 The main goal of this repository is to rewrite the object detection pipeline with a better code structure for better portability and adaptabil

153 Dec 22, 2022
Voxel-based Network for Shape Completion by Leveraging Edge Generation (ICCV 2021, oral)

Voxel-based Network for Shape Completion by Leveraging Edge Generation This is the PyTorch implementation for the paper "Voxel-based Network for Shape

10 Dec 04, 2022
[NeurIPS'20] Self-supervised Co-Training for Video Representation Learning. Tengda Han, Weidi Xie, Andrew Zisserman.

CoCLR: Self-supervised Co-Training for Video Representation Learning This repository contains the implementation of: InfoNCE (MoCo on videos) UberNCE

Tengda Han 271 Jan 02, 2023
Multilingual Image Captioning

Multilingual Image Captioning Authors: Bhavitvya Malik, Gunjan Chhablani Demo Link: https://huggingface.co/spaces/flax-community/multilingual-image-ca

Gunjan Chhablani 32 Nov 25, 2022
Code for our paper "MG-GAN: A Multi-Generator Model Preventing Out-of-Distribution Samples in Pedestrian Trajectory Prediction" published at ICCV 2021.

MG-GAN: A Multi-Generator Model Preventing Out-of-Distribution Samples in Pedestrian Trajectory Prediction This repository contains the code for the p

Sven 30 Jan 05, 2023
A mini library for Policy Gradients with Parameter-based Exploration, with reference implementation of the ClipUp optimizer from NNAISENSE.

PGPElib A mini library for Policy Gradients with Parameter-based Exploration [1] and friends. This library serves as a clean re-implementation of the

NNAISENSE 56 Jan 01, 2023
CVPR 2021 Challenge on Super-Resolution Space

Learning the Super-Resolution Space Challenge NTIRE 2021 at CVPR Learning the Super-Resolution Space challenge is held as a part of the 6th edition of

andreas 104 Oct 26, 2022
Eth brownie struct encoding example

eth-brownie struct encoding example Overview This repository contains an example of encoding a struct, so that it can be used in a function call, usin

Ittai Svidler 2 Mar 04, 2022
Part-Aware Data Augmentation for 3D Object Detection in Point Cloud

Part-Aware Data Augmentation for 3D Object Detection in Point Cloud This repository contains a reference implementation of our Part-Aware Data Augment

Jaeseok Choi 62 Jan 03, 2023
Hysterese plugin with two temperature offset areas

craftbeerpi4 plugin OffsetHysterese Temperatur-Steuerungs-Plugin mit zwei tempereaturbereich abhängigen Offsets. Installation sudo pip3 install https:

HappyHibo 1 Dec 21, 2021
The official codes of our CVPR2022 paper: A Differentiable Two-stage Alignment Scheme for Burst Image Reconstruction with Large Shift

TwoStageAlign The official codes of our CVPR2022 paper: A Differentiable Two-stage Alignment Scheme for Burst Image Reconstruction with Large Shift Pa

Shi Guo 32 Dec 15, 2022
Python scripts performing class agnostic object localization using the Object Localization Network model in ONNX.

ONNX Object Localization Network Python scripts performing class agnostic object localization using the Object Localization Network model in ONNX. Ori

Ibai Gorordo 15 Oct 14, 2022
ADB-IP-ROTATION - Use your mobile phone to gain a temporary IP address using ADB and data tethering

ADB IP ROTATE This an Python script based on Android Debug Bridge (adb) shell sc

Dor Bismuth 2 Jul 12, 2022
Official PyTorch implementation of MX-Font (Multiple Heads are Better than One: Few-shot Font Generation with Multiple Localized Experts)

Introduction Pytorch implementation of Multiple Heads are Better than One: Few-shot Font Generation with Multiple Localized Expert. | paper Song Park1

Clova AI Research 97 Dec 23, 2022