Limit DXF BSpline Degree (#1226)

* Limit DXF BSpline Degree

Most DXF renderers and processing tools can't handle BSplines with
degree >= 3 (order >= 4). For maximum compatibility, we should
approximate such BSplines using degree-3 splines. This change uses the
OpenCascade facilities to do so, though ezdxf.math also provides some
spline approximation facilities that could be used. Using the
OpenCascade approach allows us to match FreeCAD's parameters which are
presumably tuned on a diversity of real-world designs.

Fixes #1225

* Make DXF BSpline degree limit optional

This adds plumbing through the option infrastructure to make the DXF
approximation optional, and expose the important control parameters to
the user with reasonable defaults. Includes some additional
documentation to ease discovery and explain why that should be
important.

* Black

* Start refactoring

* Add toSplines and toArcs

* Refactor exportDXF and add arc approximation

* Update tests

* Rework opt handling

* Update docs

* Better docstring

* Use C0

* Apply suggestions from code review

Co-authored-by: Jeremy Wright <[email protected]>
Co-authored-by: Lorenz <[email protected]>

* Update docstring

* Code review suggestion

Co-authored-by: Jeremy Wright <[email protected]>

---------

Co-authored-by: AU <[email protected]>
Co-authored-by: Jeremy Wright <[email protected]>
Co-authored-by: Lorenz <[email protected]>

Author: 4 people

.gitignore

@@ -10,6 +10,7 @@ target/*
 MANIFEST
 out.*
 res?.dxf
+limit?.dxf
 .~*
 .*.swp
 assy.wrl

cadquery/occ_impl/exporters/__init__.py

@@ -2,7 +2,7 @@
 import os
 import io as StringIO
 
-from typing import IO, Optional, Union, cast
+from typing import IO, Optional, Union, cast, Dict, Any
 from typing_extensions import Literal
 
 from OCP.VrmlAPI import VrmlAPI
@@ -43,7 +43,7 @@ def export(
     exportType: Optional[ExportLiterals] = None,
     tolerance: float = 0.1,
     angularTolerance: float = 0.1,
-    opt=None,
+    opt: Optional[Dict[str, Any]] = None,
 ):
 
     """
@@ -60,6 +60,9 @@ def export(
     shape: Shape
     f: IO
 
+    if not opt:
+        opt = {}
+
     if isinstance(w, Workplane):
         shape = toCompound(w)
     else:
@@ -98,21 +101,18 @@ def export(
             aw.writeAmf(f)
 
     elif exportType == ExportTypes.THREEMF:
-        tmfw = ThreeMFWriter(shape, tolerance, angularTolerance, **opt or {})
+        tmfw = ThreeMFWriter(shape, tolerance, angularTolerance, **opt)
         with open(fname, "wb") as f:
             tmfw.write3mf(f)
 
     elif exportType == ExportTypes.DXF:
         if isinstance(w, Workplane):
-            exportDXF(w, fname)
+            exportDXF(w, fname, **opt)
         else:
             raise ValueError("Only Workplanes can be exported as DXF")
 
     elif exportType == ExportTypes.STEP:
-        if opt:
-            shape.exportStep(fname, **opt)
-        else:
-            shape.exportStep(fname)
+        shape.exportStep(fname, **opt)
 
     elif exportType == ExportTypes.STL:
         if opt:

cadquery/occ_impl/exporters/dxf.py

@@ -1,17 +1,19 @@
-from ...cq import Workplane, Plane
+from ...cq import Workplane, Plane, Face
 from ...units import RAD2DEG
 from ..shapes import Edge
 from .utils import toCompound
 
 from OCP.gp import gp_Dir
 from OCP.GeomConvert import GeomConvert
 
+from typing import Optional, Literal
+
 import ezdxf
 
 CURVE_TOLERANCE = 1e-9
 
 
-def _dxf_line(e, msp, plane):
+def _dxf_line(e: Edge, msp: ezdxf.layouts.Modelspace, plane: Plane):
 
     msp.add_line(
         e.startPoint().toTuple(), e.endPoint().toTuple(),
@@ -105,12 +107,21 @@ def _dxf_spline(e: Edge, msp: ezdxf.layouts.Modelspace, plane: Plane):
 }
 
 
-def exportDXF(w: Workplane, fname: str):
+def exportDXF(
+    w: Workplane,
+    fname: str,
+    approx: Optional[Literal["spline", "arc"]] = None,
+    tolerance: float = 1e-3,
+):
     """
     Export Workplane content to DXF. Works with 2D sections.
 
     :param w: Workplane to be exported.
-    :param fname: output filename.
+    :param fname: Output filename.
+    :param approx: Approximation strategy. None means no approximation is applied.
+    "spline" results in all splines being approximated as cubic splines. "arc" results
+    in all curves being approximated as arcs and straight segments.
+    :param tolerance: Approximation tolerance.
 
     """
 
@@ -120,7 +131,22 @@ def exportDXF(w: Workplane, fname: str):
     dxf = ezdxf.new()
     msp = dxf.modelspace()
 
-    for e in shape.Edges():
+    if approx == "spline":
+        edges = [
+            e.toSplines() if e.geomType() == "BSPLINE" else e for e in shape.Edges()
+        ]
+
+    elif approx == "arc":
+        edges = []
+
+        # this is needed to handle free wires
+        for el in shape.Wires():
+            edges.extend(Face.makeFromWires(el).toArcs(tolerance).Edges())
+
+    else:
+        edges = shape.Edges()
+
+    for e in edges:
 
         conv = DXF_CONVERTERS.get(e.geomType(), _dxf_spline)
         conv(e, msp, plane)

cadquery/occ_impl/shapes.py

@@ -240,6 +240,10 @@
 
 from OCP.Interface import Interface_Static
 
+from OCP.ShapeCustom import ShapeCustom, ShapeCustom_RestrictionParameters
+
+from OCP.BRepAlgo import BRepAlgo
+
 from math import pi, sqrt, inf
 
 import warnings
@@ -1252,6 +1256,34 @@ def tessellate(
 
         return vertices, triangles
 
+    def toSplines(
+        self: T, degree: int = 3, tolerance: float = 1e-3, nurbs: bool = False
+    ) -> T:
+        """
+        Approximate shape with b-splines of the specified degree.
+
+        :param degree: Maximum degree.
+        :param tolerance: Approximation tolerance.
+        :param nurbs: Use rational splines.
+        """
+
+        params = ShapeCustom_RestrictionParameters()
+
+        result = ShapeCustom.BSplineRestriction_s(
+            self.wrapped,
+            tolerance,  # 3D tolerance
+            tolerance,  # 2D tolerance
+            degree,
+            1,  # dumy value, degree is leading
+            ga.GeomAbs_C0,
+            ga.GeomAbs_C0,
+            True,  # set degree to be leading
+            not nurbs,
+            params,
+        )
+
+        return self.__class__(result)
+
     def toVtkPolyData(
         self,
         tolerance: Optional[float] = None,
@@ -2562,6 +2594,15 @@ def project(self, other: "Face", d: VectorLike) -> "Face":
 
         return self.constructOn(other, outer_p, *inner_p)
 
+    def toArcs(self, tolerance: float = 1e-3) -> "Face":
+        """
+        Approximate planar face with arcs and straight line segments.
+
+        :param tolerance: Approximation tolerance.
+        """
+
+        return self.__class__(BRepAlgo.ConvertFace_s(self.wrapped, tolerance))
+
 
 class Shell(Shape):
     """

doc/importexport.rst

@@ -231,6 +231,24 @@ optimum values that will produce an acceptable mesh.
 
     exporters.export(result, '/path/to/file/mesh.vrml', tolerance=0.01, angularTolerance=0.1)
 
+Exporting DXF
+##############
+
+By default, the DXF exporter will output splines exactly as they are represented by the OpenCascade kernel. Unfortunately some software cannot handle higher-order splines resulting in missing curves after DXF import. To resolve this, specify an approximation strategy controlled by the following options:
+
+* ``approx`` - ``None``, ``"spline"`` or ``"arc"``. ``"spline"`` results in all splines approximated with cubic splines. ``"arc"`` results in all curves approximated with arcs and line segments.
+* ``tolerance``: Acceptable error of the approximation, in the DXF's coordinate system. Defaults to 0.001 (1 thou for inch-scale drawings, 1 µm for mm-scale drawings).
+
+.. code-block:: python
+
+
+    cq.exporters.exportDXF(
+        result,
+        '/path/to/file/object.dxf',
+        approx="spline"
+    )
+
+
 Exporting Other Formats
 ########################
 

tests/test_exporters.py

@@ -8,10 +8,22 @@
 import re
 import sys
 import pytest
+import ezdxf
+
+from pytest import approx
 
 # my modules
-from cadquery import *
-from cadquery import exporters, importers
+from cadquery import (
+    exporters,
+    importers,
+    Workplane,
+    Edge,
+    Vertex,
+    Assembly,
+    Plane,
+    Location,
+    Vector,
+)
 from tests import BaseTest
 from OCP.GeomConvert import GeomConvert
 from OCP.BRepBuilderAPI import BRepBuilderAPI_MakeEdge
@@ -357,3 +369,53 @@ def test_tessellate(box123):
     verts, triangles = box123.val().tessellate(1e-6)
     assert len(verts) == 24
     assert len(triangles) == 12
+
+
+def _dxf_spline_max_degree(fname):
+
+    dxf = ezdxf.readfile(fname)
+    msp = dxf.modelspace()
+
+    rv = 0
+
+    for el in msp:
+        if isinstance(el, ezdxf.entities.Spline):
+            rv = el.dxf.degree if el.dxf.degree > rv else rv
+
+    return rv
+
+
+def _check_dxf_no_spline(fname):
+
+    dxf = ezdxf.readfile(fname)
+    msp = dxf.modelspace()
+
+    for el in msp:
+        if isinstance(el, ezdxf.entities.Spline):
+            return False
+
+    return True
+
+
+def test_dxf_approx():
+
+    pts = [(0, 0), (0, 0.5), (1, 1)]
+    w1 = Workplane().spline(pts).close().extrude(1).edges("|Z").fillet(0.1).section()
+    exporters.exportDXF(w1, "orig.dxf")
+
+    assert _dxf_spline_max_degree("orig.dxf") == 6
+
+    exporters.exportDXF(w1, "limit1.dxf", approx="spline")
+    w1_i1 = importers.importDXF("limit1.dxf")
+
+    assert _dxf_spline_max_degree("limit1.dxf") == 3
+
+    assert w1.val().Area() == approx(w1_i1.val().Area(), 1e-3)
+    assert w1.edges().size() == w1_i1.edges().size()
+
+    exporters.exportDXF(w1, "limit2.dxf", approx="arc")
+    w1_i2 = importers.importDXF("limit2.dxf")
+
+    assert _check_dxf_no_spline("limit2.dxf")
+
+    assert w1.val().Area() == approx(w1_i2.val().Area(), 1e-3)