From 0514b2af82bf9c328c3aa6fe2ee1a5c81a225bed Mon Sep 17 00:00:00 2001 From: mozman Date: Sun, 14 Jan 2024 07:48:07 +0100 Subject: [PATCH] add docs for the ezdxf.xclip module --- docs/source/dxfobjects/index.rst | 1 + docs/source/dxfobjects/spatial_filter.rst | 36 ++++++++++++++++++ .../tools/gfx/cropped-block-reference.png | Bin 0 -> 10590 bytes docs/source/tools/xclip.rst | 35 ++++++++++++++++- examples/blocks/clipping_insert.py | 2 +- 5 files changed, 71 insertions(+), 3 deletions(-) create mode 100644 docs/source/dxfobjects/spatial_filter.rst create mode 100644 docs/source/tools/gfx/cropped-block-reference.png diff --git a/docs/source/dxfobjects/index.rst b/docs/source/dxfobjects/index.rst index 11d451a7e..c20fe47cb 100644 --- a/docs/source/dxfobjects/index.rst +++ b/docs/source/dxfobjects/index.rst @@ -32,6 +32,7 @@ to meet the specific needs of different industries and applications. mleaderstyle placeholder plotsettings + spatial_filter sun underlaydef xrecord diff --git a/docs/source/dxfobjects/spatial_filter.rst b/docs/source/dxfobjects/spatial_filter.rst new file mode 100644 index 000000000..30720b48d --- /dev/null +++ b/docs/source/dxfobjects/spatial_filter.rst @@ -0,0 +1,36 @@ +SpatialFilter +============= + +.. module:: ezdxf.entities + :noindex: + +The `SPATIAL_FILTER`_ object stores the clipping path for external references and block +references. For more information about getting, setting and removing clippings paths +read the docs for the :class:`ezdxf.xclip.XClip` class. + +.. seealso:: + + - :mod:`ezdxf.xclip` + - Knowledge Graph: https://ezdxf.mozman.at/notes/#/page/spatial_filter + +======================== ============================================================= +Subclass of :class:`ezdxf.entities.DXFObject` +DXF type ``'SPATIAL_FILTER'`` +Factory function internal data structure +======================== ============================================================= + +.. class:: SpatialFilter + + .. autoproperty:: boundary_vertices + + .. autoproperty:: inverse_insert_matrix + + .. autoproperty:: transform_matrix + + .. automethod:: set_boundary_vertices + + .. automethod:: set_inverse_insert_matrix + + .. automethod:: set_transform_matrix + +.. _SPATIAL_FILTER: https://help.autodesk.com/view/OARX/2018/ENU/?guid=GUID-34F179D8-2030-47E4-8D49-F87B6538A05A diff --git a/docs/source/tools/gfx/cropped-block-reference.png b/docs/source/tools/gfx/cropped-block-reference.png new file mode 100644 index 0000000000000000000000000000000000000000..eac86cbbb1776f565a99826e1e780b2f334f49aa GIT binary patch literal 10590 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 literal 0 HcmV?d00001 diff --git a/docs/source/tools/xclip.rst b/docs/source/tools/xclip.rst index ef38b6692..98bc66988 100644 --- a/docs/source/tools/xclip.rst +++ b/docs/source/tools/xclip.rst @@ -7,8 +7,37 @@ XClip Module .. versionadded:: 1.2 +The :class:`XClip` class can set or remove the clipping path of external references or +block references. -TODO +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 :class:`XClip` class supports only 2D clippings path and cannot create inverted +clipping paths. + +.. figure:: gfx/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 :class:`XClip` class provides methods to set and get the +clipping path for both variants and returns a :class:`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 :meth:`XClip.discard_clipping_path` method, does not +raise an exception when no clipping path exist. + +.. seealso:: + + example script: `clipping_insert.py`_ in the ``/examples/blocks`` folder .. autoclass:: XClip @@ -37,4 +66,6 @@ TODO .. automethod:: discard_clipping_path -.. autoclass:: ClippingPath \ No newline at end of file +.. autoclass:: ClippingPath + +.. _clipping_insert.py: https://github.com/mozman/ezdxf/blob/master/examples/blocks/clipping_insert.py \ No newline at end of file diff --git a/examples/blocks/clipping_insert.py b/examples/blocks/clipping_insert.py index 62b742100..567c613b8 100644 --- a/examples/blocks/clipping_insert.py +++ b/examples/blocks/clipping_insert.py @@ -100,7 +100,7 @@ def add_inverted_clipping_path(): clipper.set_block_clipping_path([(2.5, 4), (1, 1), (4, 1)]) # invert the clipping path - the content of the triangle is invisible - clipper.invert_clipping_path() + clipper.invert_clipping_path(ignore_acad_compatibility=True) # Adding a rectangular clipping path defined by 2 vertices: insert1 = msp.add_blockref(name, (20, 10))