pyPolyMesher

Generation of polygonal Mesh
Explore the docs »

View Demo · Report Bug · Request Feature · Citations

Table of Contents

1. About The Project
2. Getting Started
   • Installation
3. Usage
   1. Basic Usage
   2. Internal SDFs
   3. Example Domains
   4. Import Polygon Domain from DXF
   5. Custom Domain: Heart Example
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

pyPolyMesher is a python package for generating unstructured polygonal meshes in arbitrarily defined 2D domains. It allows users to mathematically specify domains using signed distance functions (SDFs) and generates high-quality meshes adapted to the geometry and features of the domain. pyPolyMesher was initially created as a Python version of the MATLAB PolyMesher program but has since been enriched with additional features.

Key capabilities:

• Define 2D domains mathematically using signed distance functions
• Built-in library of SDF primitives (circles, rectangles, ellipses, regular polygons, stars, polygons, etc.) and operations to construct complex domains
• Ability to define custom SDFs for new domain geometries
• Generate unstructured polygonal meshes adapted to domains
• Apply boundary conditions and mark fixed points
• Assess mesh quality metrics like element aspect ratio
• Animate mesh generation process
• Import and mesh polygons from DXF files

By leveraging SDFs to represent domains, pyPolyMesher can capture intricate geometries and generate optimized meshes tailored to them, making it useful for simulations and analysis.

The package provides Lloyd's algorithm for efficient and robust meshing of arbitrary SDF-based domains. Researchers can conveniently translate geometric constructs and concepts into code using the SDF formalism.

Overall, pyPolyMesher simplifies the entire workflow - from domain specification to quality polygonal mesh generation to numerical analysis.

(back to top)

Getting Started

This part explains how to install and use this package.

Installation

You can install this package using pip:

pip install PolyMesher

Please note that pyPolyMesher is published as PolyMesher on PYPI.

(back to top)

Usage

Basic Usage:

pyPolyMesher.PolyMesher(Domain, NElem, MaxIter, P=None, anim=False): Generate polygon mesh on Domain with NElem number of elements. Improve mesh for MaxIter iterations. Can be given an initial point set P.

import pyPolyMesher
from pyPolyMesher.exampleDomains import MichellDomain
MichellDomain.Plot()
Node, Element, Supp, Load, P = pyPolyMesher.PolyMesher(MichellDomain, 50, 100)

Internal SDFs:

from pyPolyMesher import dFunctions as DF

1. DF.dLine(P, x1, y1, x2, y2): Calculate the signed distance from points P to a line segment defined by two endpoints (x1, y1) and (x2, y2).
2. DF.dLineExact(P, x1, y1, x2, y2): Calculate the exact signed distance from points P to a line segment defined by two endpoints (x1, y1) and (x2, y2).
3. DF.dCircle(P, xc, yc, r): Calculate the signed distance from points P to a circle defined by its center (xc, yc) and radius (r).
4. DF.dEllipse(P, xc, yc, a, b, theta=0.0): Calculate the signed distance from points P to an ellipse with semi-axes a and b and optional rotation theta.
5. DF.dRectangle(P, x1, x2, y1, y2): Calculate the signed distance from points P to a rectangle defined by its bottom-left (x1, y1) and top-right (x2, y2) coordinates.
6. DF.dPolygon(P, vertices): Calculate the signed distance from points P to a polygon defined by its vertices.
7. DF.dRegularPolygon(P, xc, yc, r, n, theta=0.0): Calculate the signed distance from points P to a regular polygon.
8. DF.dStar(P, xc, yc, r_outer, r_inner, n, theta=0.0): Calculate the signed distance from points P to a star-shaped polygon.
9. DF.dUnion(d1, d2): Calculate the signed distance field resulting from the union of two distance fields (d1 and d2).
10. DF.dIntersect(d1, d2): Calculate the signed distance field resulting from the intersection of two distance fields (d1 and d2).
11. DF.dDiff(d1, d2): Calculate the signed distance field resulting from the difference of two distance fields (d1 and d2).

Example Domains:

Example Domains

1. pyPolyMesher.exampleDomains.MbbDomain

2. pyPolyMesher.exampleDomains.HornDomain

3. pyPolyMesher.exampleDomains.WrenchDomain

4. pyPolyMesher.exampleDomains.MichellDomain

5. pyPolyMesher.exampleDomains.SuspensionDomain

6. pyPolyMesher.exampleDomains.CookDomain

Import Polygon Domain from DXF:

from pyPolyMesher import PolyMesher, Domain, mesh_assessment
from pyPolyMesher.dxfImporter import dxf_polygon
from pyPolyMesher.dFunctions import dPolygon

dxf_file_path = 'examples/polygon1.dxf'
v = dxf_polygon(dxf_file_path)

SDF = lambda P: dPolygon(P, v)
dxfDomain = Domain("DXF Polygon Domain", [0,100,0,100], SDF)
dxfDomain.Plot()

Node, Element, Supp, Load, P = PolyMesher(dxfDomain, 50, 100)

area = dxfDomain.CalculateArea()
metrics = mesh_assessment(Node, Element, area, verbose = True)

It should be noted that the CalculateArea method calculates the approximate area of the domain using the Monte Carlo method.

The mesh_assessment function calculates the following mesh quality metrics:

• Maximum aspect ratio (AR)
• Average AR
• Average edge length across all elements
• Shortest edge length
• Range of element areas (minimum and maximum)
• Standard deviation of element areas
• Total area error between domain area and total element areas (obviously in case the domain area is provided)

Boundary Accuracy and Non-convex Corners

For domains with sharp or non-convex features (e.g. an L-shape), a few helpers keep the meshed geometry faithful to the original domain:

• reentrant_corner_seeds(corner, e1, e2, delta): returns fixed seeds that capture a re-entrant (concave) corner, following Talischi et al. (2012, Fig. 15). Append the result to a domain's PFix.
• assess_nodes_outside_domain(Node, SDF): reports how many nodes fall outside the domain and by how much (a direct geometric error measure).
• project_nodes_to_domain(Node, SDF, ...): snaps nodes onto the domain boundary.

PolyMesher(..., snap_boundary=True) (default) automatically snaps boundary nodes onto the exact boundary and removes redundant collinear boundary nodes, so the meshed shape matches the domain (near-zero area error). Set snap_boundary=False for the bare MATLAB-equivalent behavior.

Custom Domain: Heart Example

The custom domain build from the SDF definition of heart geometry is available at heart_example.py.

See Examples.py and Example Notebook for more examples.

(back to top)

Roadmap

Section 1 - Current Focus and Issue Resolution

1. Define Domain from dxf files
   • Polygon importer
   • Circle importer
   • Spline importer
   • Automatic SDF for geometries
2. Add mesh quality assessments
   • Aspect Ratio
   • Standard Deviation of Elements Areas

Section 2 - Upcoming Priorities

1. Enhance the README with more detailed information.
2. Publish the package on PYPI and Zenodo for wider distribution.
3. Add some tests.

Section 3 - Vision and Future Prospects

1. Develop a GUI for domain definition to improve user interaction.
2. Plugin for CAD programs.
3. Explore and brainstorm alternative options for domain definition and future possible expansions.

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". We appreciate your interest in pyPolyMesher!. Don't forget to give the project a star! Thanks again!

v1.3 Release Notes

This release makes meshing of sharp / non-convex domains robust and the meshed geometry faithful to the original shape:

• Fixed a centroid/seed misalignment that could make Lloyd's iteration diverge and fling nodes far outside the domain (especially with fixed points); added a stability guard that keeps seed centroids inside the domain.
• Added reentrant_corner_seeds to capture non-convex corners (Talischi et al. 2012).
• Added assess_nodes_outside_domain to detect/quantify nodes outside the domain.
• Added project_nodes_to_domain and PolyMesher(..., snap_boundary=True) to snap boundary nodes onto the exact boundary, removing overshoots and reflection-gap notches (near-zero area error).
• Removed redundant collinear boundary nodes introduced by snapping.
• Expanded the test suite (102 tests) including geometric mesh-quality assertions.

v1.2 Release Notes

This release focuses on reliability, test coverage, and release readiness:

• Added a comprehensive automated test suite covering signed-distance functions, domain abstraction, meshing, example domains, DXF import, and progress utilities
• Added smoke tests for the documented example script and example assets
• Improved meshing behavior and fixed-point plotting handling
• Hardened DXF import handling for testability and portability
• Updated README citations and release metadata

Publications Using pyPolyMesher

This package has been used in the following research:

• S.S. Abedi-Shahri et al. (2025). "NL-SBFEM: A pure SBFEM formulation for geometrically and materially nonlinear problems" Engineering Analysis with Boundary Elements. Link
• R. Dupont (2025). "An arbitrary-order Virtual Element Method for the Helmholtz equation applied to wave field calculation in port" Results in Applied Mathematics. Link

(back to top)

License

This project is licensed under the GPLv3 License - see the LICENSE file for details. Contact

(back to top)

Contact

If you have any questions or feedback, feel free to reach out:

Email: AbediSadjad@gmail.com

GitHub: Sad-Abd