Working with Shapely Geometries
A practical guide for exporting Shapely geometries (Polygon, MultiPolygon, LineString, etc.) to DXF format using ezdxf.
This guide focuses on data conversion implementation - how to transform your existing Shapely geometry objects into DXF files that can be opened in CAD software.
Related Documentation
- ezdxf Practical Guide - Complete ezdxf reference guide
- Polygons, Holes, and Fills - DXF polygon representation methods
- Common Pitfalls and Solutions - General DXF implementation considerations
1. Introduction
Target Audience
This guide is designed for users who:
- Already work with Shapely for geometric operations
- Need to export their Shapely geometries to DXF format
- Want practical, ready-to-use code examples
- Prefer implementation details over mathematical theory
What You'll Learn
- How to convert Shapely
Polygonobjects to DXFLWPOLYLINEentities - How to handle polygons with holes using DXF
HATCHentities - How to export
MultiPolygon,LineString, andLinearRingobjects - Coordinate system handling for 2D data (spoiler: it's simpler than you think!)
- Best practices and common pitfalls
Prerequisites
- Basic knowledge of Shapely
- Python 3.10 or higher
- Installed packages:
ezdxfandshapely
2. Installation and Dependencies
Installing Required Packages
# Install ezdxf
pip install ezdxf
# Install Shapely (if not already installed)
pip install shapelyVersion Compatibility
- ezdxf: Version 1.0.0 or higher recommended
- Shapely: Version 2.0.0 or higher recommended
- Python: 3.10 or higher
3. Basic Conversion: Polygon to LWPOLYLINE
The most common use case: converting a Shapely Polygon to a DXF lightweight polyline (LWPOLYLINE).
Simple Polygon (No Holes)
Shapely's Polygon.exterior.coords provides coordinates as a tuple sequence, which can be directly passed to ezdxf.
import ezdxf
from shapely.geometry import Polygon
# Create a Shapely polygon (triangle example)
poly = Polygon([(0, 0), (10, 0), (5, 10), (0, 0)])
def export_shapely_polygon(msp, polygon, layer="0", closed=True):
"""Export Shapely Polygon to DXF LWPOLYLINE
Args:
msp: Model space from ezdxf document
polygon: Shapely Polygon object
layer: Layer name (default: "0")
closed: Whether to close the polyline (default: True)
"""
# Get exterior coordinates
# Note: Shapely's coords includes the closing point, so we remove it
# for LWPOLYLINE (ezdxf handles closing via the 'closed' parameter)
points = list(polygon.exterior.coords[:-1]) # Remove duplicate last point
# Add as LWPOLYLINE
msp.add_lwpolyline(
points,
dxfattribs={
'layer': layer,
'closed': closed
}
)
# Usage example
doc = ezdxf.new('R2010')
msp = doc.modelspace()
export_shapely_polygon(msp, poly, layer="Polygons")
doc.saveas("shapely_export.dxf")Key Points:
- Shapely's
coordsreturns tuples(x, y)which ezdxf accepts directly - Use
closed=Trueto automatically connect the last point to the first - Remove the duplicate closing point from Shapely's coordinate sequence
Handling Coordinate Systems
Good News for 2D Users: If you're working with 2D data (which is typical for Shapely), you don't need to worry about complex coordinate system transformations (WCS/OCS). Simply pass your coordinates as tuples (x, y) and ezdxf handles the rest.
# 2D coordinates - just use tuples directly
points = [(0, 0), (10, 0), (10, 10), (0, 10)]
msp.add_lwpolyline(points) # That's it!
# No need for complex transformations unless you're working with 3D dataCoordinate System Note
For 3D operations, see Coordinate Systems (WCS/OCS/AAA) and the ezdxf Practical Guide. For 2D Shapely data, you can ignore these complexities.
4. Polygons with Holes: Using HATCH
When your Shapely Polygon has holes (interiors), you'll want to use DXF HATCH entities instead of LWPOLYLINE to properly represent filled areas.
Basic HATCH Export
import ezdxf
from shapely.geometry import Polygon
def export_polygon_as_hatch(msp, polygon, layer="0", color=1, pattern="SOLID"):
"""Export Shapely Polygon with holes as DXF HATCH
Args:
msp: Model space from ezdxf document
polygon: Shapely Polygon object (may have holes)
layer: Layer name (default: "0")
color: ACI color code (default: 1 = red)
pattern: Hatch pattern name (default: "SOLID" for solid fill)
"""
# Create HATCH entity
hatch = msp.add_hatch(color=color)
hatch.dxf.layer = layer
hatch.set_pattern_fill(name=pattern, scale=1.0)
# Add exterior boundary (outer loop)
# Remove duplicate closing point
ext_coords = list(polygon.exterior.coords[:-1])
hatch.paths.add_polyline_path(ext_coords, is_closed=True)
# Add interior boundaries (holes)
for interior in polygon.interiors:
int_coords = list(interior.coords[:-1]) # Remove duplicate closing point
hatch.paths.add_polyline_path(int_coords, is_closed=True)
return hatch
# Example: Polygon with a hole
hole_poly = Polygon(
[(0, 0), (10, 0), (10, 10), (0, 10)], # Exterior (outer boundary)
[[(2, 2), (8, 2), (8, 8), (2, 8)]] # Interior (hole)
)
doc = ezdxf.new('R2010')
msp = doc.modelspace()
export_polygon_as_hatch(msp, hole_poly, layer="HatchedPolygons", color=2)
doc.saveas("hatch_export.dxf")HATCH Pattern Options
# Solid fill (most common)
hatch.set_pattern_fill(name="SOLID", scale=1.0)
# Patterned fills (examples)
hatch.set_pattern_fill(name="ANSI31", scale=1.0) # Diagonal lines
hatch.set_pattern_fill(name="ANSI37", scale=1.0) # CrosshatchHATCH vs LWPOLYLINE
- LWPOLYLINE: Use for outline only (no fill). Good for CNC machines, laser cutters.
- HATCH: Use for filled areas. Good for visual representation, CAD drawings.
See Polygons, Holes, and Fills for detailed comparison.
5. MultiPolygon Export
Shapely MultiPolygon objects contain multiple polygons. Export each polygon separately.
import ezdxf
from shapely.geometry import MultiPolygon, Polygon
def export_multipolygon(msp, multipolygon, layer="0", use_hatch=False):
"""Export Shapely MultiPolygon to DXF
Args:
msp: Model space from ezdxf document
multipolygon: Shapely MultiPolygon object
layer: Layer name (default: "0")
use_hatch: If True, use HATCH for polygons with holes (default: False)
"""
for polygon in multipolygon.geoms:
if use_hatch and len(polygon.interiors) > 0:
# Use HATCH for polygons with holes
export_polygon_as_hatch(msp, polygon, layer=layer)
else:
# Use LWPOLYLINE for simple polygons
export_shapely_polygon(msp, polygon, layer=layer)
# Example
poly1 = Polygon([(0, 0), (5, 0), (5, 5), (0, 5)])
poly2 = Polygon([(10, 10), (15, 10), (15, 15), (10, 15)])
multipoly = MultiPolygon([poly1, poly2])
doc = ezdxf.new('R2010')
msp = doc.modelspace()
export_multipolygon(msp, multipoly, layer="MultiPolygons")
doc.saveas("multipolygon_export.dxf")6. LineString and LinearRing Export
LineString Export
import ezdxf
from shapely.geometry import LineString
def export_linestring(msp, linestring, layer="0", closed=False):
"""Export Shapely LineString to DXF LWPOLYLINE
Args:
msp: Model space from ezdxf document
linestring: Shapely LineString object
layer: Layer name (default: "0")
closed: Whether to close the polyline (default: False)
"""
points = list(linestring.coords)
msp.add_lwpolyline(
points,
dxfattribs={
'layer': layer,
'closed': closed
}
)
# Example
line = LineString([(0, 0), (5, 10), (10, 5), (15, 15)])
doc = ezdxf.new('R2010')
msp = doc.modelspace()
export_linestring(msp, line, layer="Lines")
doc.saveas("linestring_export.dxf")LinearRing Export
LinearRing is automatically closed, so set closed=True:
from shapely.geometry import LinearRing
def export_linearring(msp, linearring, layer="0"):
"""Export Shapely LinearRing to DXF LWPOLYLINE"""
points = list(linearring.coords[:-1]) # Remove duplicate closing point
msp.add_lwpolyline(
points,
dxfattribs={
'layer': layer,
'closed': True
}
)7. Complete Export Function
Here's a comprehensive function that handles all Shapely geometry types:
import ezdxf
from shapely.geometry import (
Polygon, MultiPolygon, LineString, LinearRing,
Point, GeometryCollection
)
def export_shapely_geometry(msp, geometry, layer="0", use_hatch_for_holes=True):
"""Export any Shapely geometry to DXF
Args:
msp: Model space from ezdxf document
geometry: Shapely geometry object
layer: Layer name (default: "0")
use_hatch_for_holes: Use HATCH for polygons with holes (default: True)
"""
if isinstance(geometry, Polygon):
if use_hatch_for_holes and len(geometry.interiors) > 0:
export_polygon_as_hatch(msp, geometry, layer=layer)
else:
export_shapely_polygon(msp, geometry, layer=layer)
elif isinstance(geometry, MultiPolygon):
for polygon in geometry.geoms:
export_shapely_geometry(msp, polygon, layer=layer, use_hatch_for_holes=use_hatch_for_holes)
elif isinstance(geometry, LineString):
export_linestring(msp, geometry, layer=layer)
elif isinstance(geometry, LinearRing):
export_linearring(msp, geometry, layer=layer)
elif isinstance(geometry, Point):
# Points can be exported as small circles or text
msp.add_circle(
(geometry.x, geometry.y),
radius=0.1, # Small circle
dxfattribs={'layer': layer}
)
elif isinstance(geometry, GeometryCollection):
# Recursively export each geometry in the collection
for geom in geometry.geoms:
export_shapely_geometry(msp, geom, layer=layer, use_hatch_for_holes=use_hatch_for_holes)
else:
raise ValueError(f"Unsupported geometry type: {type(geometry)}")
# Usage example
from shapely.geometry import Polygon, MultiPolygon
poly1 = Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])
poly2 = Polygon(
[(20, 20), (30, 20), (30, 30), (20, 30)],
[[(22, 22), (28, 22), (28, 28), (22, 28)]]
)
multipoly = MultiPolygon([poly1, poly2])
doc = ezdxf.new('R2010')
msp = doc.modelspace()
export_shapely_geometry(msp, multipoly, layer="ExportedGeometries")
doc.saveas("complete_export.dxf")8. Advanced Topics
Setting Attributes (Color, Linetype, Lineweight)
def export_polygon_with_attributes(msp, polygon, layer="0", color=1, linetype="CONTINUOUS", lineweight=25):
"""Export Polygon with custom attributes"""
points = list(polygon.exterior.coords[:-1])
# Ensure layer exists
doc = msp.doc
if layer not in doc.layers:
doc.layers.new(layer, dxfattribs={'color': color})
# Create linetype if needed
if linetype not in doc.linetypes and linetype != "CONTINUOUS":
doc.linetypes.new(linetype, dxfattribs={
'description': 'Custom linetype',
'length': 1.0,
'pattern': [0.5, -0.5] # Example pattern
})
msp.add_lwpolyline(
points,
dxfattribs={
'layer': layer,
'color': color,
'linetype': linetype,
'lineweight': lineweight, # 0.25mm
'closed': True
}
)Batch Export with Layer Organization
def export_shapely_collection(msp, geometries, layer_prefix="Layer"):
"""Export multiple geometries, organizing by type"""
layer_map = {
'Polygon': f"{layer_prefix}_Polygons",
'LineString': f"{layer_prefix}_Lines",
'MultiPolygon': f"{layer_prefix}_MultiPolygons"
}
for geom in geometries:
geom_type = type(geom).__name__
layer = layer_map.get(geom_type, layer_prefix)
export_shapely_geometry(msp, geom, layer=layer)9. Common Pitfalls and Solutions
Pitfall 1: Duplicate Closing Point
Problem: Shapely's coords includes the closing point, but ezdxf's closed=True handles this automatically.
Solution: Remove the last point when converting:
# ✅ Correct
points = list(polygon.exterior.coords[:-1]) # Remove duplicate
msp.add_lwpolyline(points, dxfattribs={'closed': True})
# ❌ Incorrect (creates duplicate point)
points = list(polygon.exterior.coords) # Includes closing point
msp.add_lwpolyline(points, dxfattribs={'closed': True})Pitfall 2: Coordinate System Confusion
Problem: Worrying about WCS/OCS transformations for 2D data.
Solution: For 2D Shapely data, just use tuples directly:
# ✅ Correct for 2D
points = [(x, y) for x, y in polygon.exterior.coords[:-1]]
msp.add_lwpolyline(points)
# ❌ Unnecessary complexity
# No need for OCS transformations unless working with 3D dataPitfall 3: Holes Not Showing
Problem: Using LWPOLYLINE for polygons with holes doesn't show the fill.
Solution: Use HATCH for polygons with interiors:
# ✅ Correct for polygons with holes
if len(polygon.interiors) > 0:
export_polygon_as_hatch(msp, polygon)
else:
export_shapely_polygon(msp, polygon)Pitfall 4: Layer Not Found Error
Problem: Referencing a layer that doesn't exist.
Solution: Always ensure layers exist before use:
def ensure_layer(doc, layer_name, color=7):
"""Ensure layer exists, create if it doesn't"""
if layer_name not in doc.layers:
doc.layers.new(layer_name, dxfattribs={'color': color})
return doc.layers.get(layer_name)
# Usage
doc = ezdxf.new('R2010')
ensure_layer(doc, "MyLayer", color=1)
msp = doc.modelspace()
# Now safe to use "MyLayer"10. Best Practices
Choose the Right Entity Type
- Use
LWPOLYLINEfor outlines (CNC machines, laser cutters) - Use
HATCHfor filled areas (visual representation)
- Use
Handle Coordinate Sequences Correctly
- Always remove duplicate closing points:
coords[:-1] - Use
closed=Trueparameter instead of manually closing
- Always remove duplicate closing points:
Organize with Layers
- Create meaningful layer names
- Group related geometries on the same layer
Validate Input
- Check if geometry is valid:
geometry.is_valid - Handle empty geometries gracefully
- Check if geometry is valid:
Error Handling
- Wrap file operations in try-except blocks
- Validate file paths before saving
11. Complete Example: Real-World Use Case
Here's a complete example that demonstrates a typical workflow:
import ezdxf
from shapely.geometry import Polygon, MultiPolygon
from pathlib import Path
def export_shapely_to_dxf(geometries, output_path, layer_name="ShapelyExport"):
"""Complete export function with error handling"""
try:
# Create DXF document
doc = ezdxf.new('R2010')
msp = doc.modelspace()
# Ensure layer exists
if layer_name not in doc.layers:
doc.layers.new(layer_name, dxfattribs={'color': 2}) # Yellow
# Export each geometry
for geom in geometries:
if isinstance(geom, Polygon):
if len(geom.interiors) > 0:
# Use HATCH for polygons with holes
export_polygon_as_hatch(msp, geom, layer=layer_name, color=2)
else:
# Use LWPOLYLINE for simple polygons
export_shapely_polygon(msp, geom, layer=layer_name)
elif isinstance(geom, MultiPolygon):
for poly in geom.geoms:
export_shapely_geometry(msp, poly, layer=layer_name)
# Save file
output_path = Path(output_path)
output_path.parent.mkdir(parents=True, exist_ok=True)
doc.saveas(str(output_path))
print(f"Successfully exported {len(geometries)} geometries to {output_path}")
except Exception as e:
print(f"Error exporting to DXF: {e}")
raise
# Usage
poly1 = Polygon([(0, 0), (10, 0), (10, 10), (0, 10)])
poly2 = Polygon(
[(20, 20), (30, 20), (30, 30), (20, 30)],
[[(22, 22), (28, 22), (28, 28), (22, 28)]]
)
geometries = [poly1, poly2]
export_shapely_to_dxf(geometries, "output/shapely_export.dxf", layer_name="MyPolygons")Summary
This guide covered the essential techniques for exporting Shapely geometries to DXF:
- Polygon → LWPOLYLINE: Simple conversion using
exterior.coords - Polygon with holes → HATCH: Use
HATCHentities for filled areas - MultiPolygon: Export each polygon separately
- LineString/LinearRing: Direct coordinate conversion
- 2D Coordinates: No complex transformations needed - just use tuples!
Key Takeaways:
- Shapely's coordinate tuples work directly with ezdxf
- Use
HATCHfor polygons with holes - Remove duplicate closing points:
coords[:-1] - For 2D data, coordinate system transformations are unnecessary
For more advanced topics (3D transformations, complex splines, etc.), refer to the ezdxf Practical Guide.
Related: ezdxf Practical Guide | Polygons, Holes, and Fills | Common Pitfalls