XClip Module¶

New in version 1.2.

The XClip class can set or remove the clipping path of external references or block references.

The clipping boundary determines the portion of an XREF or block instance that is hidden, either outside or inside the boundary (inside = inverted clipping path). The visibility of the clipping boundary is controlled by the $XCLIPFRAME header variable.

The XClip class supports only 2D clippings path and cannot create inverted clipping paths.

There exist two coordinate systems for the clipping path polygon:

BLOCK coordinate system: the BLOCK coordinates are relative to the BLOCK origin

WCS coordinate system: the WCS coordinates are relative to the origin of the of the coodintate system where the block reference (INSERT entity) is inserted

The XClip class provides methods to set and get the clipping path for both variants and returns a ClippingPath object.

The clipping polygon can be set visible/invisible when the header variable $XCLIPFRAME is not 0, otherwise the clipping polygon is always invisible.

Remove the clipping path by the XClip.discard_clipping_path() method, does not raise an exception when no clipping path exist.

See also

example script: clipping_insert.py in the /examples/blocks folder

class ezdxf.xclip.XClip(insert: Insert)¶

Helper class to manage the clipping path of INSERT entities.

Provides a similar functionality as the XCLIP command in CAD applications.

Important

This class handles only 2D clipping paths.

The visibility of the clipping path can be set individually for each block reference, but the HEADER variable $XCLIPFRAME ultimately determines whether the clipping path is displayed or plotted by the application:

0	not displayed	not plotted
1	displayed	not plotted
2	displayed	plotted

The default setting is 2.

property has_clipping_path: bool¶: Returns if the INSERT entity has a clipping path.

property is_clipping_enabled: bool¶: Returns True if block reference clipping is enabled.

property is_inverted_clip: bool¶: Returns True if clipping path is inverted.

disable_clipping() → None¶: Disable block reference clipping.

enable_clipping() → None¶: Enable block reference clipping.

get_spatial_filter() → SpatialFilter | None¶: Returns the underlaying SPATIAL_FILTER entity if the INSERT entity has a clipping path and returns None otherwise.

get_xclip_frame_policy() → int¶

get_block_clipping_path() → ClippingPath¶: Returns the clipping path in block coordinates (relative to the block origin).

get_wcs_clipping_path() → ClippingPath¶: Returns the clipping path in WCS coordinates (relative to the WCS origin) as 2D path projected onto the xy-plane.

set_block_clipping_path(vertices: Iterable[UVec]) → None¶

Set clipping path in block coordinates (relative to block origin).

The clipping path is located in the xy-plane, the z-axis of all vertices will be ignored. The clipping path doesn’t have to be closed (first vertex != last vertex). Two vertices define a rectangle where the sides are parallel to x- and y-axis.

Raises:: DXFValueError – clipping path has less than two vertrices

set_wcs_clipping_path(vertices: Iterable[UVec]) → None¶

Set clipping path in WCS coordinates (relative to WCS origin).

The clipping path is located in the xy-plane, the z-axis of all vertices will be ignored. The clipping path doesn’t have to be closed (first vertex != last vertex). Two vertices define a rectangle where the sides are parallel to x- and y-axis.

Raises:

DXFValueError – clipping path has less than two vertrices
ZeroDivisionError – Block reference transformation matrix is not invertible

discard_clipping_path() → None¶

Delete the clipping path. The clipping path doesn’t have to exist.

This method does not discard the extension dictionary of the base entity, even when its empty.

class ezdxf.xclip.ClippingPath(vertices: Sequence[Vec2] = (), inverted_clip: Sequence[Vec2] = (), inverted_clip_compare: Sequence[Vec2] = (), is_inverted_clip: bool = False)¶

Stores the SPATIAL_FILTER clipping paths in original form that I still don’t fully understand for inverted clipping paths. All boundary paths are simple polygons as a sequence of Vec2.

vertices¶

Contains the boundary polygon for regular clipping paths. Contains the outer boundary path for inverted clippings paths - but not always!