Python triangle library

20250106 · active · verified Fri Apr 17

The `triangle` library provides Python bindings to Jonathan Shewchuk's robust C library for 2D Delaunay triangulation and constrained Delaunay triangulation, as well as high-quality mesh generation. It processes inputs like sets of points, segments, and holes to generate triangulations and meshes. The current version is 20250106, with a release cadence that appears to be on an as-needed basis, indicated by its date-based versioning.

Common errors

```
KeyError: 'vertices'
```
cause The input dictionary passed to `triangle.triangulate` is missing the required 'vertices' key, or it's misspelled.

fix Ensure your input dictionary explicitly includes a 'vertices' key pointing to your NumPy array of points, e.g., `{'vertices': points_array}`.
```
ValueError: Input array is not 2-dimensional
```
cause The NumPy array provided for 'vertices', 'segments', or 'holes' is not shaped correctly (e.g., it's 1D, or has too many dimensions). Points should be N x 2, segments M x 2.

fix Verify that your NumPy arrays have the correct dimensions. For example, a list of points `[[x1,y1],[x2,y2]]` should be `np.array([[x1,y1],[x2,y2]])`, resulting in a shape of (N, 2).
```
triangle.triangulate() got an unexpected keyword argument 'mesh_quality'
```
cause Attempting to pass triangulation options as keyword arguments. The options must be passed as a single string.

fix Combine all desired options into a single string argument, e.g., `triangle.triangulate(data, 'pq30a0.1')`. Do not use separate keyword arguments for options.

Warnings

gotcha The `triangle.triangulate` function expects input data (vertices, segments, holes) in a specific dictionary format with keys like 'vertices', 'segments', and 'holes'. Misnaming or omitting these keys will lead to errors.
Fix: Always pass a dictionary with the correct keys, e.g., `{'vertices': np_array_of_points, 'segments': np_array_of_segments}`. Refer to the GitHub README for exact required keys.
gotcha The second argument to `triangle.triangulate` is a string of options (e.g., 'pq30a0.1') that directly mirror the command-line flags of the underlying C `triangle` library. Users often expect keyword arguments or separate parameters.
Fix: Consult the official documentation for the original C `triangle` library (or the Python `triangle` README) to understand the meaning and syntax of the option string. Common options like 'p' (PSLG), 'q' (quality), 'a' (area) are typically used.
gotcha The library returns its results (e.g., vertices, triangles, segments) in an output dictionary, which may contain new, refined points or segments compared to the input. The original C `triangle` library has an extensive output format.
Fix: Always access the results by indexing the output dictionary, e.g., `tri['vertices']`, `tri['triangles']`. Be aware that the `vertices` and `segments` in the output might not be identical to your input if refinement was applied.
deprecated The versioning scheme is date-based (YYYYMMDD). While this indicates active development, it means that potentially breaking or significant API changes might occur between two 'newer' versions without a traditional major version increment (e.g., v1.x to v2.x).
Fix: Before upgrading to a newer date-version, review the GitHub commit history or release notes for any changes that might impact your code. Pin specific versions in your `requirements.txt` to avoid unexpected updates.

Install

pip install triangle Install `triangle`

Imports

triangle
```
import triangle
```

Quickstart

This quickstart demonstrates how to create a Delaunay triangulation of a square region with a central hole. It defines the boundary using vertices and segments, specifies the hole's location, and then uses `triangle.triangulate` with quality and area constraints to generate a mesh. The output includes refined vertices, the triangle connectivity, and potentially refined segments.

import triangle
import numpy as np

# Define vertices for a square
points = np.array([
    [0.0, 0.0],
    [1.0, 0.0],
    [1.0, 1.0],
    [0.0, 1.0]
])

# Define segments (edges) connecting the vertices to form the boundary of the square
# Indices refer to the `points` array (0-indexed)
segments = np.array([
    [0, 1],
    [1, 2],
    [2, 3],
    [3, 0]
])

# Define a hole by a point within the region to be excluded from triangulation
holes = np.array([[0.5, 0.5]])

# Triangulate the region.
# The second argument is a string of options for the C library:
# 'p': Planar straight line graph (PSLG) triangulation
# 'q30': Quality mesh generation, minimum angle 30 degrees
# 'a0.01': Maximum triangle area attribute, 0.01
tri = triangle.triangulate({'vertices': points, 'segments': segments, 'holes': holes}, 'pq30a0.01')

print("--- Input ---")
print("Points:\n", points)
print("Segments:\n", segments)
print("Holes:\n", holes)
print("\n--- Output ---")
print("Vertices (may be refined):\n", tri['vertices'])
print("Triangles (indices into output vertices):\n", tri['triangles'])
print("Segments (may be refined):\n", tri['segments'])

view raw JSON →