libigl Python Bindings

Common errors

• ModuleNotFoundError: No module named 'igl'

  cause The `libigl` Python package is not installed in the current Python environment or the environment is not correctly activated.
  fix Ensure `libigl` is installed by running `pip install libigl`. Verify the correct Python environment is active if using virtual environments.

• NameError: name 'plot' is not defined (or similar plotting errors like 'display is undefined')

  cause The `libigl` library itself does not include plotting functionality. Visualization in tutorials often relies on external libraries like `meshplot`.
  fix Install `meshplot` (or another visualization library like `matplotlib`, `vedo`, etc.) separately: `pip install meshplot`. Ensure it's imported correctly: `from meshplot import plot`.

• Failed to clone repository: 'https://github.com/libigl/libigl.git/' (or similar CMake/Git errors during installation)

  cause This error typically occurs when attempting to install `libigl` from source (e.g., `pip install .` in a cloned repo) and the build process fails to clone the underlying C++ `libigl` library or its dependencies, often due to network issues, firewall restrictions, or missing Git/CMake.
  fix For standard usage, install the pre-compiled wheels via `pip install libigl` rather than building from source. If building from source is necessary, ensure Git and CMake are installed and accessible, and check network connectivity to GitHub.

Warnings

• breaking Major breaking changes were introduced in versions 2.5.4.dev0, carrying forward into 2.6.0 and later. These versions involved a complete rewrite of the Python bindings source code and the build system (transitioning to nanobind). Code written for pre-2.5.4.dev0 versions will likely require significant updates.
  Fix: Review the official GitHub repository and tutorials for updated API usage. Many functions or their signatures may have changed.
• deprecated The `igl.__version__` attribute was removed in version 2.5.4.dev0. Directly accessing this attribute will raise an `AttributeError`.
  Fix: To programmatically get the installed package version, use `importlib.metadata.version('libigl')`.
• gotcha The official Python binding documentation is noted as 'perennially out of date' and may be removed or changed. Users should prioritize the GitHub repository's README, examples, and the C++ libigl documentation for the most accurate and up-to-date information.
  Fix: Refer to the `libigl-python-bindings` GitHub repository's `tutorial` and `tests` directories for current usage patterns and examples, and the core C++ `libigl` documentation for function details.

Install

• pip install libigl Install via pip

Imports

• igl

  import igl

  All libigl functions are exposed directly under the 'igl' module.
• read_triangle_mesh

  import igl
  V, F = igl.read_triangle_mesh('path/to/mesh.obj')

  Functions are direct attributes of the 'igl' module.

Quickstart

This quickstart demonstrates how to create a simple mesh, save it to a file using `igl.write_triangle_mesh`, and then load it back using `igl.read_triangle_mesh`. It uses NumPy arrays for vertex coordinates and face connectivity. For interactive visualization, additional libraries like `meshplot` (not included here) are often used.

import igl
import numpy as np
import os

# Create a simple mesh (triangle on the XY plane)
V = np.array([
    [0.0, 0.0, 0.0],
    [1.0, 0.0, 0.0],
    [0.0, 1.0, 0.0]
], dtype=np.float64)
F = np.array([
    [0, 1, 2]
], dtype=np.int32)

# Define a path for saving/loading
output_dir = os.environ.get('LIBIGL_OUTPUT_DIR', '.')
output_mesh_path = os.path.join(output_dir, 'example_triangle.obj')

# Save the mesh
success = igl.write_triangle_mesh(output_mesh_path, V, F)
print(f"Mesh saved successfully: {success} to {output_mesh_path}")

# Load the mesh back
V_loaded, F_loaded = igl.read_triangle_mesh(output_mesh_path)
print(f"Loaded Vertices shape: {V_loaded.shape}, Faces shape: {F_loaded.shape}")

# Example: Calculate edge lengths (requires a function like igl.edge_lengths)
# This is illustrative; actual function name might vary and require more imports.
# If igl.edge_lengths existed, it might look like:
# L = igl.edge_lengths(V, F)
# print(f"Edge lengths: {L}")

# Cleanup (optional)
# os.remove(output_mesh_path)