Selection Tools

The ezdxf.select module provides entity selection capabilities, allowing users to select entities based on various shapes such as windows, points, circles, polygons, and fences.

The selection functions bbox_inside() and bbox_outside() work similarly to the inside and outside selection tools in CAD applications but the selection is based on the bounding box of the DXF entities rather than their actual geometry.

The bbox_overlap() function works similarly to crossing selection in CAD applications. Entities that are outside the selection shape but whose bounding box overlapps the selection shape are included in the selection. This is not the case with crossing selection in CAD applications.

The selection functions accept any iterable of DXF entities as input and return an ezdxf.query.EntityQuery container, that provides further selection tools based on entity type and DXF attributes.

Usage

Select all entities from the modelspace inside a window defined by two opposite vertices:

import ezdxf
from ezdxf import select

doc = ezdxf.readfile("your.dxf")
msp = doc.modelspace()

# Define a window for selection
window = select.Window((0, 0), (10, 10))

# Select entities inside the window from modelspace
selected_entities = select.bbox_inside(window, msp)

# Iterate over selected entities
for entity in selected_entities:
    print(entity)

See also

Selection Functions

The following selection functions are implemented:

ezdxf.select.bbox_inside(shape: SelectionShape, entities: Iterable[DXFEntity], *, cache: Cache | None = None) → EntityQuery

Selects entities whose bounding box lies withing the selection shape.

Parameters:

  • shape – seclection shape

  • entities – iterable of DXFEntities

  • cache – optional ezdxf.bbox.Cache instance

ezdxf.select.bbox_outside(shape: SelectionShape, entities: Iterable[DXFEntity], *, cache: Cache | None = None) → EntityQuery

Selects entities whose bounding box is completely outside the selection shape.

Parameters:

  • shape – seclection shape

  • entities – iterable of DXFEntities

  • cache – optional ezdxf.bbox.Cache instance

ezdxf.select.bbox_overlap(shape: SelectionShape, entities: Iterable[DXFEntity], *, cache: Cache | None = None) → EntityQuery

Selects entities whose bounding box overlaps the selection shape.

Parameters:

  • shape – seclection shape

  • entities – iterable of DXFEntities

  • cache – optional ezdxf.bbox.Cache instance

ezdxf.select.bbox_chained(start: DXFEntity, entities: Iterable[DXFEntity], *, cache: Cache | None = None) → EntityQuery

Selects elements that are directly or indirectly connected to each other by overlapping bounding boxes. The selection begins at the specified starting element.

Warning: the current implementation has a complexity of O(n²).

Parameters:

  • start – first entity of selection

  • entities – iterable of DXFEntities

  • cache – optional ezdxf.bbox.Cache instance

ezdxf.select.bbox_crosses_fence(vertices: Iterable[UVec], entities: Iterable[DXFEntity], *, cache: Cache | None = None) → EntityQuery

Selects entities whose bounding box intersects an open polyline.

All entities are projected on the xy-plane.

A single point can not be selected by a fence polyline by definition.

Parameters:

  • vertices – vertices of the selection polyline

  • entities – iterable of DXFEntities

  • cache – optional ezdxf.bbox.Cache instance

ezdxf.select.point_in_bbox(location: UVec, entities: Iterable[DXFEntity], *, cache: Cache | None = None) → EntityQuery

Selects entities where the selection point lies within the bounding box. All entities are projected on the xy-plane.

Parameters:

  • point – selection point

  • entities – iterable of DXFEntities

  • cache – optional ezdxf.bbox.Cache instance

Selection Shapes

The following selection shapes are implemented:

class ezdxf.select.Window(p1: UVec, p2: UVec)

This selection shape tests entities against a rectangular and axis-aligned 2D window. All entities are projected on the xy-plane.

Parameters:

  • p1 – first corner of the window

  • p2 – second corner of the window

class ezdxf.select.Circle(center: UVec, radius: float)

This selection shape tests entities against a circle. All entities are projected on the xy-plane.

Parameters:

  • center – center of the circle

  • radius – radius of the circle

class ezdxf.select.Polygon(vertices: Iterable[UVec])

This selection shape tests entities against an arbitrary closed polygon. All entities are projected on the xy-plane. Complex concave polygons may not work as expected.

Planar Search Index

Added in version 1.4.

class ezdxf.select.PlanarSearchIndex(entities: Iterable[DXFEntity], cache: Cache | None = None, max_node_size=5)

Spatial Search Index for DXF Entities

This class implements a spatial search index for DXF entities based on their bounding boxes except for POINT and LINE. It operates strictly within the two-dimensional (2D) space of the xy-plane. The index is built once and cannot be extended afterward.

The index can be used to pre-select DXF entities from a certain area to reduce the search space for other selection tools of this module.

Functionality

  • The index relies on the bounding boxes of DXF entities, and only the corner vertices of these bounding boxes are indexed except for POINT and LINE.

  • It can only find DXF entities that have at least one bounding box vertex located within the search area. Entities whose bounding boxes overlap the search area but have no vertices inside it will not be found (e.g., a circle whose center point is inside the search area but none of its bounding box vertices will not be included).

  • The detection behavior can be customized by overriding the detection_points() method.

Recommendations

Since this index is intended to be used in conjunction with other selection tools within this module, it’s recommended to maintain a bounding box cache to avoid the computational cost of recalculating them frequently. This class creates a new bounding box cache if none is specified. This cache can be accessed through the public attribute cache.

detection_point_in_circle(center: UVec, radius: float) → Sequence[DXFEntity]

Returns all DXF entities that have at least one detection point located around center with a max. distance of radius.

detection_point_in_rect(p1: UVec, p2: UVec) → Sequence[DXFEntity]

Returns all DXF entities that have at least one detection point located inside or at the border of the rectangle defined by the two given corner points.

detection_points(entity: DXFEntity) → Sequence[Vec2]

Returns the detection points for a given DXF entity.

The detection points must be 2D points projected onto the xy-plane (ignore z-axis). This implementation returns the corner vertices of the entity bounding box.

Override this method to return more sophisticated detection points (e.g., the vertices of LWPOLYLINE and POLYLINE or equally spaced raster points for block references).