replace argument 'flatten' by 'fast' in module ezdxf.bbox

Argument ' flatten' is deprecated and will be removed in v1.0.

The new precise bounding box calculation for Bézier curves
does not require a max flattening distance anymore!

Author: mozman

NEWS.md

@@ -2,7 +2,7 @@
 News
 ====
 
-Version 0.18b6 - dev
+Version 0.18b7 - dev
 --------------------
 
 - Release notes: https://ezdxf.mozman.at/release-v0-18.html
@@ -54,8 +54,9 @@ Version 0.18b6 - dev
 - CHANGE: `recover` module - recovered integer and float values are logged as severe errors
 - CHANGE: method `Path.all_lines_to_curve3` replaced by function `path.lines_to_curve3()`
 - CHANGE: method `Path.all_lines_to_curve4` replaced by function `path.lines_to_curve4()`
-- CHANGE: replaced arguments `flatten` and `segments` by argument `fast` of tool 
+- CHANGE: replaced arguments `flatten` and `segments` by argument `fast` of tool
   function `Path.bbox()` 
+- CHANGE: replaced argument `flatten` argument `fast` in the `ezdxf.bbox` module
 - BUGFIX [#663](https://github.com/mozman/ezdxf/issues/663): 
   improve handling of large coordinates in `Bezier4P` and `Bezier3P` classes
 - BUGFIX [#655](https://github.com/mozman/ezdxf/issues/655): 

examples/addons/drawing/pillow.py

@@ -92,17 +92,11 @@ def main():
     # is optimized for speed.
     print(f"detecting model space extents (fast={args.fast}) ...")
     t0 = perf_counter()
-    flatten = 0.01
-    use_matplotlib = ezdxf.options.use_matplotlib
-    if args.fast:
-        ezdxf.options.use_matplotlib = False
-        flatten = 0
-    extents = bbox.extents(msp, flatten=flatten)
+    extents = bbox.extents(msp, fast=args.fast)
     print(f"... in {perf_counter() - t0:.1f}s")
     print(f"EXTMIN: ({extents.extmin.x:.3f}, {extents.extmin.y:.3f})")
     print(f"EXTMAX: ({extents.extmax.x:.3f}, {extents.extmax.y:.3f})")
     print(f"SIZE: ({extents.size.x:.3f}, {extents.size.y:.3f})")
-    ezdxf.options.use_matplotlib = use_matplotlib
 
     ctx = RenderContext(doc)
     try:

examples/addons/drawing/render_model_space_as_tiles.py

@@ -67,13 +67,13 @@ def main(rows: int, cols: int):
     # module, DXF entities are referenced by handle strings. (multiprocessing!)
     cache = bbox.Cache()
 
-    # The bounding box calculation can take along time for big DXF files!
-    # If flatten=0 the bounding box calculation for curves (SPLINE, ELLIPSE, ...)
+    # The bounding box calculation can take a long time for big DXF files!
+    # If fast=True the bounding box calculation for curves (SPLINE, ELLIPSE, ...)
     # is based on the control points of the Path class, this is less precise but
     # can speed up the calculation and for this task is a precise bounding box
     # not required.
     # This has no impact on this example which uses only straight lines
-    extents = bbox.extents(msp, cache=cache, flatten=0)
+    extents = bbox.extents(msp, cache=cache, fast=True)
 
     ctx = RenderContext(doc)
     for tile, render_area in enumerate(render_areas(extents, (rows, cols))):
@@ -85,10 +85,10 @@ def main(rows: int, cols: int):
         ax.set_xlim(render_area.extmin.x, render_area.extmax.x)
         ax.set_ylim(render_area.extmin.y, render_area.extmax.y)
 
-        # Disable rendering of entities outside of the render area:
+        # Disable rendering of entities outside the render area:
         def is_intersecting_render_area(entity):
             """Returns True if entity should be rendered. """
-            entity_bbox = bbox.extents([entity], cache=cache, flatten=0)
+            entity_bbox = bbox.extents([entity], cache=cache, fast=True)
             return render_area.has_intersection(entity_bbox)
 
         # Finalizing invokes auto-scaling!

profiling/bbox_samples.py

@@ -62,37 +62,29 @@ def print_bbox(box):
 count = 0
 sum_precise = 0.0
 sum_fast = 0.0
-USE_MATPLOTLIB = False
-PRELOAD_CACHE = False
-print(f"preloading matplotlib cache: {PRELOAD_CACHE}")
-print(f"using matplotlib for fast bounding box calculation: {USE_MATPLOTLIB}")
+
 
 for _name in CADKIT_FILES:
-    ezdxf.options.use_matplotlib = True
     count += 1
     filename = os.path.join(EZDXF_TEST_FILES, CADKIT, _name)
     print(f"reading file: {filename}")
     t0 = time.perf_counter()
     doc = ezdxf.readfile(filename)
     msp = doc.modelspace()
     print(f"loading time: {time.perf_counter() - t0:.3f} sec")
-    if PRELOAD_CACHE:
-        print("preloading matplotlib font caches ...")
-        bbox.extents(doc.modelspace(), flatten=0)
-
-    t0 = time.perf_counter()
-    box0 = bbox.extents(doc.modelspace(), flatten=0.01)
-    precise_result = time.perf_counter() - t0
-    sum_precise += precise_result
-    print(f"precise bounding box calculation in {precise_result:.3f} sec")
 
-    ezdxf.options.use_matplotlib = USE_MATPLOTLIB
     t0 = time.perf_counter()
-    box1 = bbox.extents(doc.modelspace(), flatten=0)
+    box1 = bbox.extents(doc.modelspace(), fast=True)
     fast_result = time.perf_counter() - t0
     sum_fast += fast_result
     print(f"fast bounding box calculation in {fast_result:.3f} sec")
 
+    t0 = time.perf_counter()
+    box0 = bbox.extents(doc.modelspace(), fast=False)
+    precise_result = time.perf_counter() - t0
+    sum_precise += precise_result
+    print(f"precise bounding box calculation in {precise_result:.3f} sec")
+
     extents = box0.size
     diff = extents - box1.size
     print(f"bounding box difference:")

src/ezdxf/appsettings.py

@@ -105,7 +105,7 @@ def update_extents(doc: "Drawing") -> BoundingBox:
         - the :mod:`ezdxf.zoom` module
 
     """
-    extents = bbox.extents(doc.modelspace(), flatten=0)
+    extents = bbox.extents(doc.modelspace(), fast=True)
     doc.header[EXTMIN] = extents.extmin
     doc.header[EXTMAX] = extents.extmax
     return extents

src/ezdxf/bbox.py

@@ -1,8 +1,11 @@
 #  Copyright (c) 2021, Manfred Moitzi
 #  License: MIT License
 from typing import TYPE_CHECKING, Iterable, Dict, Optional
+import warnings
+
+import ezdxf
 from ezdxf import disassemble
-from ezdxf.math import BoundingBox, Vec3
+from ezdxf.math import BoundingBox
 
 if TYPE_CHECKING:
     from ezdxf.eztypes import DXFEntity
@@ -82,29 +85,38 @@ def _get_key(self, entity: "DXFEntity") -> Optional[str]:
             return key
 
 
+def _resolve_fast_arg(fast: bool, kwargs) -> bool:
+    if "flatten" in kwargs:
+        warnings.warn(
+            "Argument 'flatten' replaced by argument 'fast', "
+            "'flatten' will be removed in v1.0!",
+            DeprecationWarning,
+        )
+        fast = not bool(kwargs["flatten"])
+    return fast
+
+
 def multi_recursive(
     entities: Iterable["DXFEntity"],
     *,
-    flatten: float = MAX_FLATTENING_DISTANCE,
+    fast=False,
     cache: Cache = None,
+    **kwargs,
 ) -> Iterable[BoundingBox]:
     """Yields all bounding boxes for the given `entities` **or** all bounding
     boxes for their sub entities. If an entity (INSERT) has sub entities, only
     the bounding boxes of these sub entities will be yielded, **not** the
     bounding box of entity (INSERT) itself.
 
-    Calculate bounding boxes from flattened curves, if argument `flatten`
-    is not 0 (max flattening distance), else from control points.
+    If argument `fast` is ``True`` the calculation of Bézier curves is based on
+    their control points, this may return a slightly larger bounding box.
 
-    """
+    .. versionchanged:: 0.18
 
-    def vertices(p: disassemble.Primitive) -> Iterable[Vec3]:
-        if flatten:
-            primitive.max_flattening_distance = abs(flatten)
-            return primitive.vertices()
-        else:
-            return disassemble.to_control_vertices([p])
+        replaced argument `flatten` by argument `fast`
 
+    """
+    fast = _resolve_fast_arg(fast, kwargs)
     flat_entities = disassemble.recursive_decompose(entities)
     primitives = disassemble.to_primitives(flat_entities)
     for primitive in primitives:
@@ -115,11 +127,11 @@ def vertices(p: disassemble.Primitive) -> Iterable[Vec3]:
         if cache is not None:
             box = cache.get(entity)
             if box is None:
-                box = BoundingBox(vertices(primitive))
+                box = primitive.bbox(fast=fast)
                 if box.has_data:
                     cache.store(entity, box)
         else:
-            box = BoundingBox(vertices(primitive))
+            box = primitive.bbox(fast=fast)
 
         if box.has_data:
             yield box
@@ -128,37 +140,63 @@ def vertices(p: disassemble.Primitive) -> Iterable[Vec3]:
 def extents(
     entities: Iterable["DXFEntity"],
     *,
-    flatten: float = MAX_FLATTENING_DISTANCE,
+    fast=False,
     cache: Cache = None,
+    **kwargs,
 ) -> BoundingBox:
     """Returns a single bounding box for all given `entities`.
 
-    Calculate bounding boxes from flattened curves, if argument `flatten`
-    is not 0 (max flattening distance), else from control points.
+    If argument `fast` is ``True`` the calculation of Bézier curves is based on
+    their control points, this may return a slightly larger bounding box.
+    The `fast` mode uses also a simpler and mostly inaccurate text size
+    calculation instead of the more precise but very slow calculation by
+    `matplotlib`.
+
+    .. hint::
+
+        The fast mode is not much faster for non-text based entities, so using
+        the slower default mode is not a big disadvantage if a more precise text
+        size calculation is important.
+
+    .. versionchanged:: 0.18
+
+        added fast mode, replaced argument `flatten` by argument `fast`
 
     """
+    fast = _resolve_fast_arg(fast, kwargs)
+    use_matplotlib = ezdxf.options.use_matplotlib  # save current state
+    if fast:
+        ezdxf.options.use_matplotlib = False
     _extends = BoundingBox()
-    for box in multi_flat(entities, flatten=flatten, cache=cache):
+    for box in multi_flat(entities, fast=fast, cache=cache):
         _extends.extend(box)
+    ezdxf.options.use_matplotlib = use_matplotlib  # restore state
     return _extends
 
 
 def multi_flat(
     entities: Iterable["DXFEntity"],
     *,
-    flatten: float = MAX_FLATTENING_DISTANCE,
+    fast=False,
     cache: Cache = None,
+    **kwargs,
 ) -> Iterable[BoundingBox]:
     """Yields a bounding box for each of the given `entities`.
 
-    Calculate bounding boxes from flattened curves, if argument `flatten`
-    is not 0 (max flattening distance), else from control points.
+    If argument `fast` is ``True`` the calculation of Bézier curves is based on
+    their control points, this may return a slightly larger bounding box.
+
+    .. versionchanged:: 0.18
+
+        replaced argument `flatten` by argument `fast`
 
     """
 
     def extends_(entities_: Iterable["DXFEntity"]) -> BoundingBox:
         _extends = BoundingBox()
-        for _box in multi_recursive(entities_, flatten=flatten, cache=cache):
+        for _box in multi_recursive(
+            entities_, fast=_resolve_fast_arg(fast, kwargs), cache=cache
+        ):
             _extends.extend(_box)
         return _extends
 

src/ezdxf/zoom.py

@@ -41,7 +41,7 @@ def zoom_to_entities(layout: Layout, entities: Iterable[DXFEntity], factor):
         main_viewport = layout.main_viewport()
         if main_viewport is not None:
             entities = (e for e in entities if e is not main_viewport)
-    extents = bbox.extents(entities, flatten=0)
+    extents = bbox.extents(entities, fast=True)
     if extents.has_data:
         center(layout, extents.center, extents.size * factor)
 

tests/test_04_dxf_high_level_structs/test_417_bbox.py

@@ -148,26 +148,16 @@ def circle():
     return lay
 
 
-def test_bbox_from_control_points(circle):
-    box = bbox.extents(circle, flatten=0)
+def test_fast_bounding_box_calculation(circle):
+    box = bbox.extents(circle, fast=True)
     assert box.extmin == (-100, -100)
     assert box.extmax == (+100, +100)
 
 
-def test_bbox_from_rough_flattening(circle):
-    box = bbox.extents(circle, flatten=5)
-    assert box.extmin != (-100, -100), "did not expect a precise result"
-    assert box.extmax != (+100, +100), "did not expect a precise result"
-
-
-def test_bbox_from_precise_flattening(circle):
-    box = bbox.extents(circle, flatten=0.0001)
-    assert box.extmin.isclose(
-        (-100, -100), abs_tol=0.0001
-    ), "expected a very close result"
-    assert box.extmax.isclose(
-        (+100, +100), abs_tol=0.0001
-    ), "expected a very_close result"
+def test_precise_bounding_box_calculation(circle):
+    box = bbox.extents(circle, fast=False)
+    assert box.extmin == (-100, -100)
+    assert box.extmax == (+100, +100)
 
 
 if __name__ == "__main__":

tests/test_08_addons/test_814_text2path.py

@@ -295,7 +295,7 @@ def get_paths_bbox(text):
 
 def get_hatches_bbox(text):
     hatches = text2path.make_hatches_from_entity(text)
-    return bbox.extents(hatches, flatten=0)
+    return bbox.extents(hatches, fast=True)
 
 
 @pytest.fixture(params=[get_path_bbox, get_paths_bbox, get_hatches_bbox])