XClip Module

Added 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.

../_images/cropped-block-reference.png

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!

Type:

Sequence[ezdxf.math._vector.Vec2]

inverted_clip

Contains the inner boundary for inverted clipping paths - but not always!

Type:

Sequence[ezdxf.math._vector.Vec2]

inverted_clip_compare

Contains the combined inner- and the outer boundaries for inverted clipping paths - but not always!

Type:

Sequence[ezdxf.math._vector.Vec2]

is_inverted_clip

True for inverted clipping paths

Type:

bool