add docs for the ezdxf.xclip module

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

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

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
+.. autoclass:: ClippingPath
+
+.. _clipping_insert.py: https://github.com/mozman/ezdxf/blob/master/examples/blocks/clipping_insert.py

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))