Poisson Surface Reconstruction: 3D point cloud

Import a point cloud file and perform poisson 3D surface reconstruction algorithm, integrated with third-party libraries like open3d and pymeshlab

Dependencies

• python 3 <= 3.8.x

  Recommended: Use pyenv to install and manage Python versions

• numpy >= 1.20
• open3d >= 0.12
• pymeshlab >= 0.2

Development dependencies

• setuptools: For installation via setup.py
• setuptools-scm: To generate version numbers from git tags
• wheel: Built packages .whl to install packages with PIP
• twine: Publish packages to https://pypi.org
• tqdm: CLI progressbar when publish a package

Development guide

For local installation and develop new features for this package, follow the steps below:

Windows

Run unassigned powershell scripts on Windows requires change your execution policy with Set-ExecutionPolicy to AllSigned, or Bypass -Scope Process.

See: Execution Policies

Run the script setup.ps1 with powershell

# Default virtualenv folder is "venv"
.\setup.ps1

# Optionally, pass a custom virtualenv folder
.\setup.ps1 -VirtualEnvFolder myenv

If you wish run just an specific function from setup.ps1 (e.g. Install-Python), execute:

powershell -command "& { . .\setup.ps1 'venv' -Execute 0; Install-Python }"

Unix systems (Comming soon)

# Default virtualenv folder is "venv"
./setup.sh

# Optionally, pass a custom virtual enviroment folder
./setup.sh --virtual-env-folder myenv

For more detailed installation, see the Wiki pages in: Installation Development

Install this package

Quick way:

pip install surface_reconstruction

Or clone this repository and build the .whl file from the project root:

cd [your-project-root]

# Build the .whl package file
python -m build --sdist --wheel .

# Install locally from the .whl file
# Where: x.x.x is the generated version from git tag
pip install dist/surface_reconstruction-x.x.x-py3-none-any.whl

For more detailed, see the Wiki pages in: Generate package

Run the unit tests

# Run all tests of the module "surface_reconstruction_test`
python -m unittest tests/surface_reconstruction_test.py

Usage

Import a .ply file with point cloud vertices, and generate the mesh file

from surface_reconstruction import SurfaceReconstruction
import os

# Pass a method/library that contains a Poisson algorithm implementation
surface = SurfaceReconstruction(
  method_type='open3d',
  point_cloud_file=os.path.join('files', 'point_cloud.ply'),
  output_file=os.path.join('files', 'terrain_mesh.ply')
)

# Call the method from the specific library, and export a mesh file
surface.poisson_mesh()

You can pass custom filters/parameters for the specific library. This is important because poisson algorithm requires some pre-filters before to be applied (e.g estimate normals in the point cloud)

# ...
parameters = {
  'estimate_normals': {
    'fast_normal_computation': False,
    'normals': (1, 3)
  }
}

# Unpack the dictionary "parameters" as a **kwargs
surface.poisson_mesh(**{'filters': parameters})

PS: See the unittests inside tests folder for more usage examples

Extending: Add new libraries

Is possible create and register custom strategies to allow others libraries (Python, C++ bindings...)

from surface_reconstruction import SurfaceStrategy, SurfaceReconstruction 

# Create a class that inherit from "SurfaceStrategy"
class MyCustomSurface(SurfaceStrategy):
  
      def __init__(self, my_custom_param: dict):
        """
        Custom constructor with custom parameters
        """
        super().__init__()
  
      def load_file(self, file_path: str):
        """
        Custom load point cloud file implementation here
        """
        pass

    def poisson_mesh(self, save_file=True, **params: {}):
      """
      Generate the mesh file with faces/triangles here
      """
      pass

# Register your custom strategy here
SurfaceReconstruction.register_type(MyCustomSurface)


# Pass a method/library that contains a Poisson algorithm implementation
surface = SurfaceReconstruction(
  method_type='mycustom', # Don't pass the "surface" suffix
  my_custom_param={'extra_config': 'some_value'},
)

# Call the method from the specific library, and export a mesh file
surface.poisson_mesh()