Added code for simplified and fused assembly export to STEP (#1261)

* Added code for simplified and fused assembly export to STEP

* Changed toFused to use OCCT history API instead of the cut method

* Black fix

* Handle a null label due to a deleted face from the fuse

* Handle generated faces

* Allow a face to be null because of something other than IsDeleted

* Added assembly STEP export doucmentation

* Handle assemblies that have only one shape in them

* Better check before getting a null label and commented out generated face addition for now

* Appended CAF to new toSimplified and toFused method names for export

* Removed unneeded __iter__ call

* Trying to figure out mypy Literal for STEP export mode

* Switched to using literals for the export mode

* Switching to built-in CQ method for creating a compound

* Added glue and fuzzy tolerance settings for fused assembly

* Use the built-in assembly name, otherwise a UUID

* Pulled latest master and fixed black errors

* Started using location of assembly parent part object for compound

* Handle nested assemblies

* Added nested assembly export tests

* mypy apparently could not handle the one-liner inside toShapeList

* Attempting to fix remaining mypy errors

* Added single part fused export, fuzzy_tol and glue setting tests

* Removed simplified STEP export method and addressed some comments on the PR

* Fixed export mode literal typing omission

* Fix black error

* Fixing mypy error

* Added ability to handle a top level shape passed during Assembly initialization

* Simplified assembly handling while still keeping top level assembly objects

* Attempting to round out tests

* Update cadquery/assembly.py

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

* Update cadquery/occ_impl/assembly.py

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

* Simplification for latest OCP

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

* Fixed tests for typing change

* Use f string in exception

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

* Capitalization and f string suggestions

* Fix black check

* Simplified code by using traverse to walk the assembly structure

* Removed toShapeList

* Trying to avoid an error that only seems to be happening in CI

* Needed to put the check if a face was deleted on the fuse op

* Investigate the failures on appveyor

* Reworked and simplified adding of modified and generated faces

* Added null checks for labels after trying to add a subshape

* Fixed color handling for some faces during fuse

* Comment out on_finish

* Apply locations to shapes

* Fix failing tests

* Better testcase

* Copy explicitly

* Fix single shape export

* Mypy fix

* Add (initial) test of fused STEP export mode colors

* toFusedCAF - handle single compound special case, use existing assembly name, add more tests

* Removed performance statement in assembly exporter docstring

* Updated docstring for glue

As suggested by @lorenzncode

* Doc tweaks

* More assembly export mode doc tweaks
* Correct the export mode keyword arg name in example
* Include example of exporters.export opt dict

* Changed the name exportMode to mode

---------

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

Author: 3 people

.gitignore

@@ -32,3 +32,4 @@ nested.stl
 out1.3mf
 out2.3mf
 out3.3mf
+orig.dxf

appveyor.yml

@@ -38,3 +38,8 @@ test_script:
 
 on_success:
     - codecov
+
+#on_finish:
+#    - ps: $blockRdp = $true; iex ((new-object net.webclient).DownloadString('https://raw.githubusercontent.com/appveyor/ci/master/scripts/enable-rdp.ps1'))
+#   - sh: export APPVEYOR_SSH_BLOCK=true
+#   - sh: curl -sflL 'https://raw.githubusercontent.com/appveyor/ci/master/scripts/enable-ssh.sh' | bash -e -

cadquery/assembly.py

@@ -1,5 +1,16 @@
 from functools import reduce
-from typing import Union, Optional, List, Dict, Any, overload, Tuple, Iterator, cast
+from typing import (
+    Union,
+    Optional,
+    List,
+    Dict,
+    Any,
+    overload,
+    Tuple,
+    Iterator,
+    cast,
+    get_args,
+)
 from typing_extensions import Literal
 from typish import instance_of
 from uuid import uuid1 as uuid
@@ -21,6 +32,8 @@
     exportVTKJS,
     exportVRML,
     exportGLTF,
+    STEPExportModeLiterals,
+    ExportModes,
 )
 
 from .selectors import _expression_grammar as _selector_grammar
@@ -436,6 +449,7 @@ def save(
         self,
         path: str,
         exportType: Optional[ExportLiterals] = None,
+        mode: STEPExportModeLiterals = "default",
         tolerance: float = 0.1,
         angularTolerance: float = 0.1,
         **kwargs,
@@ -451,6 +465,10 @@ def save(
             See :meth:`~cadquery.occ_impl.exporters.assembly.exportAssembly`.
         """
 
+        # Make sure the export mode setting is correct
+        if mode not in get_args(STEPExportModeLiterals):
+            raise ValueError(f"Unknown assembly export mode {mode} for STEP")
+
         if exportType is None:
             t = path.split(".")[-1].upper()
             if t in ("STEP", "XML", "VRML", "VTKJS", "GLTF", "STL"):
@@ -459,7 +477,7 @@ def save(
                 raise ValueError("Unknown extension, specify export type explicitly")
 
         if exportType == "STEP":
-            exportAssembly(self, path, **kwargs)
+            exportAssembly(self, path, mode, **kwargs)
         elif exportType == "XML":
             exportCAF(self, path)
         elif exportType == "VRML":

cadquery/occ_impl/assembly.py

@@ -1,15 +1,19 @@
-from typing import Union, Iterable, Tuple, Dict, overload, Optional, Any, List
+from typing import Union, Iterable, Tuple, Dict, overload, Optional, Any, List, cast
 from typing_extensions import Protocol
 from math import degrees
 
 from OCP.TDocStd import TDocStd_Document
 from OCP.TCollection import TCollection_ExtendedString
-from OCP.XCAFDoc import XCAFDoc_DocumentTool, XCAFDoc_ColorType
+from OCP.XCAFDoc import XCAFDoc_DocumentTool, XCAFDoc_ColorType, XCAFDoc_ColorGen
 from OCP.XCAFApp import XCAFApp_Application
 from OCP.TDataStd import TDataStd_Name
 from OCP.TDF import TDF_Label
 from OCP.TopLoc import TopLoc_Location
 from OCP.Quantity import Quantity_ColorRGBA
+from OCP.BRepAlgoAPI import BRepAlgoAPI_Fuse
+from OCP.TopTools import TopTools_ListOfShape
+from OCP.BOPAlgo import BOPAlgo_GlueEnum
+from OCP.TopoDS import TopoDS_Shape
 
 from vtkmodules.vtkRenderingCore import (
     vtkActor,
@@ -112,6 +116,10 @@ def parent(self) -> Optional["AssemblyProtocol"]:
     def color(self) -> Optional[Color]:
         ...
 
+    @property
+    def obj(self) -> AssemblyObjects:
+        ...
+
     @property
     def shapes(self) -> Iterable[Shape]:
         ...
@@ -289,3 +297,117 @@ def toJSON(
         rv.extend(toJSON(child, loc, color, tolerance))
 
     return rv
+
+
+def toFusedCAF(
+    assy: AssemblyProtocol, glue: bool = False, tol: Optional[float] = None,
+) -> Tuple[TDF_Label, TDocStd_Document]:
+    """
+    Converts the assembly to a fused compound and saves that within the document
+    to be exported in a way that preserves the face colors. Because of the use of
+    boolean operations in this method, performance may be slow in some cases.
+
+    :param assy: Assembly that is being converted to a fused compound for the document.
+    """
+
+    # Prepare the document
+    app = XCAFApp_Application.GetApplication_s()
+    doc = TDocStd_Document(TCollection_ExtendedString("XmlOcaf"))
+    app.InitDocument(doc)
+
+    # Shape and color tools
+    shape_tool = XCAFDoc_DocumentTool.ShapeTool_s(doc.Main())
+    color_tool = XCAFDoc_DocumentTool.ColorTool_s(doc.Main())
+
+    # To fuse the parts of the assembly together
+    fuse_op = BRepAlgoAPI_Fuse()
+    args = TopTools_ListOfShape()
+    tools = TopTools_ListOfShape()
+
+    # If there is only one solid, there is no reason to fuse, and it will likely cause problems anyway
+    top_level_shape = None
+
+    # Walk the entire assembly, collecting the located shapes and colors
+    shapes: List[Shape] = []
+    colors = []
+
+    def extract_shapes(assy, parent_loc=None, parent_color=None):
+
+        loc = parent_loc * assy.loc if parent_loc else assy.loc
+        color = assy.color if assy.color else parent_color
+
+        for shape in assy.shapes:
+            shapes.append(shape.moved(loc).copy())
+            colors.append(color)
+
+        for ch in assy.children:
+            extract_shapes(ch, loc, color)
+
+    extract_shapes(assy)
+
+    # Initialize with a dummy value for mypy
+    top_level_shape = cast(TopoDS_Shape, None)
+
+    # If the tools are empty, it means we only had a single shape and do not need to fuse
+    if not shapes:
+        raise Exception(f"Error: Assembly {assy.name} has no shapes.")
+    elif len(shapes) == 1:
+        # There is only one shape and we only need to make sure it is a Compound
+        # This seems to be needed to be able to add subshapes (i.e. faces) correctly
+        sh = shapes[0]
+        if sh.ShapeType() != "Compound":
+            top_level_shape = Compound.makeCompound((sh,)).wrapped
+        elif sh.ShapeType() == "Compound":
+            sh = sh.fuse(glue=glue, tol=tol)
+            top_level_shape = Compound.makeCompound((sh,)).wrapped
+            shapes = [sh]
+    else:
+        # Set the shape lists up so that the fuse operation can be performed
+        args.Append(shapes[0].wrapped)
+
+        for shape in shapes[1:]:
+            tools.Append(shape.wrapped)
+
+        # Allow the caller to configure the fuzzy and glue settings
+        if tol:
+            fuse_op.SetFuzzyValue(tol)
+        if glue:
+            fuse_op.SetGlue(BOPAlgo_GlueEnum.BOPAlgo_GlueShift)
+
+        fuse_op.SetArguments(args)
+        fuse_op.SetTools(tools)
+        fuse_op.Build()
+
+        top_level_shape = fuse_op.Shape()
+
+    # Add the fused shape as the top level object in the document
+    top_level_lbl = shape_tool.AddShape(top_level_shape, False)
+    TDataStd_Name.Set_s(top_level_lbl, TCollection_ExtendedString(assy.name))
+
+    # Walk the assembly->part->shape->face hierarchy and add subshapes for all the faces
+    for color, shape in zip(colors, shapes):
+        for face in shape.Faces():
+            # See if the face can be treated as-is
+            cur_lbl = shape_tool.AddSubShape(top_level_lbl, face.wrapped)
+            if color and not cur_lbl.IsNull() and not fuse_op.IsDeleted(face.wrapped):
+                color_tool.SetColor(cur_lbl, color.wrapped, XCAFDoc_ColorGen)
+
+            # Handle any modified faces
+            modded_list = fuse_op.Modified(face.wrapped)
+
+            for mod in modded_list:
+                # Add the face as a subshape and set its color to match the parent assembly component
+                cur_lbl = shape_tool.AddSubShape(top_level_lbl, mod)
+                if color and not cur_lbl.IsNull() and not fuse_op.IsDeleted(mod):
+                    color_tool.SetColor(cur_lbl, color.wrapped, XCAFDoc_ColorGen)
+
+            # Handle any generated faces
+            gen_list = fuse_op.Generated(face.wrapped)
+
+            for gen in gen_list:
+                # Add the face as a subshape and set its color to match the parent assembly component
+                cur_lbl = shape_tool.AddSubShape(top_level_lbl, gen)
+                if color and not cur_lbl.IsNull():
+                    color_tool.SetColor(cur_lbl, color.wrapped, XCAFDoc_ColorGen)
+
+    return top_level_lbl, doc

cadquery/occ_impl/exporters/assembly.py

@@ -1,8 +1,10 @@
 import os.path
+import uuid
 
 from tempfile import TemporaryDirectory
 from shutil import make_archive
 from itertools import chain
+from typing_extensions import Literal
 
 from vtkmodules.vtkIOExport import vtkJSONSceneExporter, vtkVRMLExporter
 from vtkmodules.vtkRenderingCore import vtkRenderer, vtkRenderWindow
@@ -23,20 +25,41 @@
 from OCP.Message import Message_ProgressRange
 from OCP.Interface import Interface_Static
 
-from ..assembly import AssemblyProtocol, toCAF, toVTK
+from ..assembly import AssemblyProtocol, toCAF, toVTK, toFusedCAF
 from ..geom import Location
 
 
-def exportAssembly(assy: AssemblyProtocol, path: str, **kwargs) -> bool:
+class ExportModes:
+    DEFAULT = "default"
+    FUSED = "fused"
+
+
+STEPExportModeLiterals = Literal["default", "fused"]
+
+
+def exportAssembly(
+    assy: AssemblyProtocol,
+    path: str,
+    mode: STEPExportModeLiterals = "default",
+    **kwargs
+) -> bool:
     """
     Export an assembly to a STEP file.
 
     kwargs is used to provide optional keyword arguments to configure the exporter.
 
     :param assy: assembly
     :param path: Path and filename for writing
+    :param mode: STEP export mode. The options are "default", and "fused" (a single fused compound).
+        It is possible that fused mode may exhibit low performance.
+    :param fuzzy_tol: OCCT fuse operation tolerance setting used only for fused assembly export.
+    :type fuzzy_tol: float
+    :param glue: Enable gluing mode for improved performance during fused assembly export.
+        This option should only be used for non-intersecting shapes or those that are only touching or partially overlapping.
+        Note that when glue is enabled, the resulting fused shape may be invalid if shapes are intersecting in an incompatible way.
+        Defaults to False.
+    :type glue: bool
     :param write_pcurves: Enable or disable writing parametric curves to the STEP file. Default True.
-
         If False, writes STEP file without pcurves. This decreases the size of the resulting STEP file.
     :type write_pcurves: bool
     :param precision_mode: Controls the uncertainty value for STEP entities. Specify -1, 0, or 1. Default 0.
@@ -49,8 +72,17 @@ def exportAssembly(assy: AssemblyProtocol, path: str, **kwargs) -> bool:
     if "write_pcurves" in kwargs and not kwargs["write_pcurves"]:
         pcurves = 0
     precision_mode = kwargs["precision_mode"] if "precision_mode" in kwargs else 0
+    fuzzy_tol = kwargs["fuzzy_tol"] if "fuzzy_tol" in kwargs else None
+    glue = kwargs["glue"] if "glue" in kwargs else False
+
+    # Use the assembly name if the user set it
+    assembly_name = assy.name if assy.name else str(uuid.uuid1())
 
-    _, doc = toCAF(assy, True)
+    # Handle the doc differently based on which mode we are using
+    if mode == "fused":
+        _, doc = toFusedCAF(assy, glue, fuzzy_tol)
+    else:  # Includes "default"
+        _, doc = toCAF(assy, True)
 
     session = XSControl_WorkSession()
     writer = STEPCAFControl_Writer(session, False)