{"id":2583,"library":"mapbox-earcut","title":"Mapbox Earcut Python Bindings","description":"mapbox-earcut provides Python bindings for the high-performance Mapbox Earcut C++ polygon triangulation library. It is currently at version 2.0.0 and sees active maintenance with releases addressing new Python versions and build system improvements.","status":"active","version":"2.0.0","language":"en","source_language":"en","source_url":"https://github.com/skogler/mapbox_earcut_python","tags":["gis","geometry","triangulation","earcut","mapbox"],"install":[{"cmd":"pip install mapbox-earcut","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"symbol":"earcut","correct":"from mapbox_earcut import earcut"}],"quickstart":{"code":"import numpy as np\nfrom mapbox_earcut import earcut\n\n# Define a polygon with an outer ring and an inner hole\n# Vertices are flat: [x0, y0, x1, y1, ...]\n# Outer ring (0-3): [10,0], [0,50], [60,60], [70,10]\n# Hole (4-7): [30,10], [30,30], [20,20], [20,10]\n# The hole_indices array specifies where each hole's vertices start in the `data` array.\ndata = np.array([\n    [10,0], [0,50], [60,60], [70,10],\n    [30,10], [30,30], [20,20], [20,10]\n]).flatten() # Earcut expects a flat array of coordinates\n\n# hole_indices tells earcut where each hole polygon starts in the data array.\n# In this example, the hole starts at index 4 (since it's a flat array, this is the 5th vertex pair, or 8th element).\n# No, the example from github passes non-flattened array, and `[4]` refers to the 4th *point* index.\n# So, data should *not* be flattened prior to passing, it seems the C++ binding does that.\n\ndata_points = np.array([\n    [10,0], [0,50], [60,60], [70,10],\n    [30,10], [30,30], [20,20], [20,10]\n])\n\n# `data_points` is a (N, 2) array.\n# `hole_indices` is an array of indices where holes start in `data_points`.\n# `dimensions` is the number of dimensions per point (e.g., 2 for x,y).\nresult_indices = earcut(data_points, [4], 2)\n\n# The result is a flat array of vertex indices forming triangles.\n# For example, [0, 1, 2, 0, 2, 3, ...] means triangle 0 is (data_points[0], data_points[1], data_points[2]).\ntriangles = result_indices.reshape(-1, 3)\n\nprint(f\"Input points:\\n{data_points}\")\nprint(f\"Resulting triangle indices (flat):\\n{result_indices}\")\nprint(f\"Resulting triangles (reshaped):\\n{triangles}\")","lang":"python","description":"This example demonstrates how to triangulate a polygon with a hole using `mapbox_earcut.earcut`. The input is a NumPy array of 2D points, an array indicating the starting index of any holes, and the number of dimensions per point (typically 2)."},"warnings":[{"fix":"Ensure you are using a version of `mapbox-earcut` that provides wheels for your specific Python major version. If pre-built wheels are not available, you may need to compile from source or upgrade/downgrade your Python environment.","message":"Starting with v2.0.0, support for the Python Limited API was removed. This means wheels are no longer binary compatible across different major Python versions, and new wheels will be required for each new Python release (e.g., Python 3.12, 3.13).","severity":"breaking","affected_versions":">=2.0.0"},{"fix":"Upgrade your Python environment to 3.9 or higher. If on 32-bit Linux, consider using an older version or compiling from source (which may be challenging due to NumPy dependencies).","message":"Version 1.0.2 introduced Python 3.9 as the minimum required version. It also dropped support for 32-bit Linux systems, aligning with NumPy's reduced wheel support for such platforms.","severity":"breaking","affected_versions":">=1.0.2, <2.0.0"},{"fix":"Ensure your input `data` is a 2D NumPy array (e.g., `np.array([[x0,y0],[x1,y1],...])`). Correctly identify the starting point (index) for each hole within this array for the `hole_indices` parameter.","message":"The `earcut` function expects input `data` as a NumPy array of shape `(N, D)` where N is the number of vertices and D is the dimension (e.g., 2 for (x,y)). The `hole_indices` argument is an array of integer indices specifying where each hole polygon begins within the `data` array.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}