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.
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.acc.vector.Vec2]
- inverted_clip¶
Contains the inner boundary for inverted clipping paths - but not always!
- Type:
Sequence[ezdxf.acc.vector.Vec2]
- inverted_clip_compare¶
Contains the combined inner- and the outer boundaries for inverted clipping paths - but not always!
- Type:
Sequence[ezdxf.acc.vector.Vec2]
- is_inverted_clip¶
True
for inverted clipping paths- Type:
bool