Merge branch 'master' into adam-nurbs

Author: adam-urbanczyk

.coveragerc

@@ -3,7 +3,9 @@ branch = True
 omit = 
     cadquery/utils.py
     cadquery/cq_directive.py
+    cadquery/__init__.py
     tests/*
+    setup.py
 
 [report]
 exclude_lines =

CITATION.cff

@@ -1,6 +1,6 @@
 cff-version: 1.2.0
 doi: 10.5281/zenodo.10513848
-license: "Apache 2.0"
+license: "Apache-2.0"
 url: https://github.com/CadQuery/cadquery
 title: "CadQuery"
 message: "If you use this software, please cite it using these metadata."

cadquery/__init__.py

@@ -4,7 +4,7 @@
     __version__ = version("cadquery")
 except PackageNotFoundError:
     # package is not installed
-    __version__ = "2.6-dev"
+    __version__ = "2.7-dev"
 
 # these items point to the OCC implementation
 from .occ_impl.geom import Plane, BoundBox, Vector, Matrix, Location

cadquery/assembly.py

@@ -35,14 +35,15 @@
     exportGLTF,
     STEPExportModeLiterals,
 )
-from .occ_impl.importers.assembly import importStep as _importStep
+from .occ_impl.importers.assembly import importStep as _importStep, importXbf, importXml
 
 from .selectors import _expression_grammar as _selector_grammar
 from .utils import deprecate, BiDict
 
 # type definitions
 AssemblyObjects = Union[Shape, Workplane, None]
-ExportLiterals = Literal["STEP", "XML", "GLTF", "VTKJS", "VRML", "STL"]
+ImportLiterals = Literal["STEP", "XML", "XBF"]
+ExportLiterals = Literal["STEP", "XML", "XBF", "GLTF", "VTKJS", "VRML", "STL"]
 
 PATH_DELIM = "/"
 
@@ -226,7 +227,9 @@ def add(self, arg, **kwargs):
             # enforce unique names
             name = kwargs["name"] if kwargs.get("name") else arg.name
             if name in self.objects:
-                raise ValueError("Unique name is required")
+                raise ValueError(
+                    f"Unique name is required. {name} is already in the assembly"
+                )
 
             subassy = arg._copy()
 
@@ -527,38 +530,9 @@ def save(
         :type ascii: bool
         """
 
-        # 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", "GLB", "STL"):
-                exportType = cast(ExportLiterals, t)
-            else:
-                raise ValueError("Unknown extension, specify export type explicitly")
-
-        if exportType == "STEP":
-            exportAssembly(self, path, mode, **kwargs)
-        elif exportType == "XML":
-            exportCAF(self, path)
-        elif exportType == "VRML":
-            exportVRML(self, path, tolerance, angularTolerance)
-        elif exportType == "GLTF" or exportType == "GLB":
-            exportGLTF(self, path, None, tolerance, angularTolerance)
-        elif exportType == "VTKJS":
-            exportVTKJS(self, path)
-        elif exportType == "STL":
-            # Handle the ascii setting for STL export
-            export_ascii = False
-            if "ascii" in kwargs:
-                export_ascii = bool(kwargs.get("ascii"))
-
-            self.toCompound().exportStl(path, tolerance, angularTolerance, export_ascii)
-        else:
-            raise ValueError(f"Unknown format: {exportType}")
-
-        return self
+        return self.export(
+            path, exportType, mode, tolerance, angularTolerance, **kwargs
+        )
 
     def export(
         self,
@@ -589,7 +563,7 @@ def export(
 
         if exportType is None:
             t = path.split(".")[-1].upper()
-            if t in ("STEP", "XML", "VRML", "VTKJS", "GLTF", "GLB", "STL"):
+            if t in ("STEP", "XML", "XBF", "VRML", "VTKJS", "GLTF", "GLB", "STL"):
                 exportType = cast(ExportLiterals, t)
             else:
                 raise ValueError("Unknown extension, specify export type explicitly")
@@ -598,6 +572,8 @@ def export(
             exportAssembly(self, path, mode, **kwargs)
         elif exportType == "XML":
             exportCAF(self, path)
+        elif exportType == "XBF":
+            exportCAF(self, path, binary=True)
         elif exportType == "VRML":
             exportVRML(self, path, tolerance, angularTolerance)
         elif exportType == "GLTF" or exportType == "GLB":
@@ -621,22 +597,35 @@ def importStep(cls, path: str) -> Self:
         """
         Reads an assembly from a STEP file.
 
-        :param path: Path and filename for writing.
+        :param path: Path and filename for reading.
         :return: An Assembly object.
         """
 
-        assy = cls()
-        _importStep(assy, path)
-
-        return assy
+        return cls.load(path, importType="STEP")
 
     @classmethod
-    def load(cls, path: str) -> Self:
+    def load(cls, path: str, importType: Optional[ImportLiterals] = None,) -> Self:
         """
-        Alias of importStep for now.
+        Load step, xbf or xml.
         """
 
-        return cls.importStep(path)
+        if importType is None:
+            t = path.split(".")[-1].upper()
+            if t in ("STEP", "XML", "XBF"):
+                importType = cast(ImportLiterals, t)
+            else:
+                raise ValueError("Unknown extension, specify export type explicitly")
+
+        assy = cls()
+
+        if importType == "STEP":
+            _importStep(assy, path)
+        elif importType == "XML":
+            importXml(assy, path)
+        elif importType == "XBF":
+            importXbf(assy, path)
+
+        return assy
 
     @property
     def shapes(self) -> List[Shape]:

cadquery/cq.py

@@ -1413,8 +1413,10 @@ def _findFromPoint(self, useLocalCoords: bool = False) -> Vector:
             p = obj.endPoint()
         elif isinstance(obj, Vector):
             p = obj
+        elif isinstance(obj, Vertex):
+            p = obj.Center()
         else:
-            raise RuntimeError("Cannot convert object type '%s' to vector " % type(obj))
+            raise ValueError(f"Cannot convert object type {type(obj)} to vector.")
 
         if useLocalCoords:
             return self.plane.toLocalCoords(p)
@@ -2394,6 +2396,7 @@ def consolidateWires(self: T) -> T:
         r = self.newObject(w)
         r.ctx.pendingWires = w
         r.ctx.pendingEdges = []
+        r.ctx.firstPoint = None
 
         return r
 

cadquery/cq_directive.py

@@ -54,6 +54,7 @@
     roll: vtk.Interaction.Manipulators.vtkMouseCameraTrackballRollManipulator.newInstance(),
 };
 
+manips.rot.setUseFocalPointAsCenterOfRotation(true);
 manips.zoom1.setControl(true);
 manips.zoom2.setButton(3);
 manips.roll.setShift(true);

cadquery/occ_impl/assembly.py

@@ -266,6 +266,50 @@ def addSubshape(
     ) -> Self:
         ...
 
+    @overload
+    def add(
+        self,
+        obj: Self,
+        loc: Optional[Location] = None,
+        name: Optional[str] = None,
+        color: Optional[Color] = None,
+    ) -> Self:
+        ...
+
+    @overload
+    def add(
+        self,
+        obj: AssemblyObjects,
+        loc: Optional[Location] = None,
+        name: Optional[str] = None,
+        color: Optional[Color] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> Self:
+        ...
+
+    def add(
+        self,
+        obj: Union[Self, AssemblyObjects],
+        loc: Optional[Location] = None,
+        name: Optional[str] = None,
+        color: Optional[Color] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+        **kwargs: Any,
+    ) -> Self:
+        """
+        Add a subassembly to the current assembly.
+        """
+        ...
+
+    def addSubshape(
+        self,
+        s: Shape,
+        name: Optional[str] = None,
+        color: Optional[Color] = None,
+        layer: Optional[str] = None,
+    ) -> Self:
+        ...
+
     def traverse(self) -> Iterable[Tuple[str, "AssemblyProtocol"]]:
         ...
 
@@ -414,6 +458,7 @@ def _toCAF(el: AssemblyProtocol, ancestor: TDF_Label | None) -> TDF_Label:
         for child in el.children:
             _toCAF(child, subassy)
 
+        # final rv construction
         if ancestor and el.children:
             tool.AddComponent(ancestor, subassy, el.loc.wrapped)
             rv = subassy

cadquery/occ_impl/geom.py

@@ -26,6 +26,8 @@
 from OCP.TopLoc import TopLoc_Location
 from OCP.BinTools import BinTools_LocationSet
 
+from multimethod import multidispatch
+
 from ..types import Real
 from ..utils import multimethod
 
@@ -579,20 +581,17 @@ def bottom(cls, origin=(0, 0, 0), xDir=Vector(1, 0, 0)):
         plane._setPlaneDir(xDir)
         return plane
 
+    # Prefer multidispatch over multimethod, as that supports keyword
+    # arguments. These are in use, since Plane.__init__ has not always
+    # been a multimethod.
+    @multidispatch
     def __init__(
         self,
-        origin: Union[Tuple[float, float, float], Vector],
-        xDir: Optional[Union[Tuple[float, float, float], Vector]] = None,
-        normal: Union[Tuple[float, float, float], Vector] = (0, 0, 1),
+        origin: Union[Tuple[Real, Real, Real], Vector],
+        xDir: Optional[Union[Tuple[Real, Real, Real], Vector]] = None,
+        normal: Union[Tuple[Real, Real, Real], Vector] = (0, 0, 1),
     ):
-        """
-        Create a Plane with an arbitrary orientation
-
-        :param origin: the origin in global coordinates
-        :param xDir: an optional vector representing the xDirection.
-        :param normal: the normal direction for the plane
-        :raises ValueError: if the specified xDir is not orthogonal to the provided normal
-        """
+        """Create a Plane from origin in global coordinates, vector xDir, and normal direction for the plane."""
         zDir = Vector(normal)
         if zDir.Length == 0.0:
             raise ValueError("normal should be non null")
@@ -610,6 +609,50 @@ def __init__(
         self._setPlaneDir(xDir)
         self.origin = Vector(origin)
 
+    @__init__.register
+    def __init__(
+        self, loc: "Location",
+    ):
+        """Create a Plane from Location loc."""
+
+        # Ask location for its information
+        origin, rotations = loc.toTuple()
+
+        # Origin is easy, but the rotational angles of the location need to be
+        # turned into xDir and normal vectors.
+        # This is done by multiplying a standard cooridnate system by the given
+        # angles.
+        # Rotation of vectors is done by a transformation matrix.
+        # The order in which rotational angles are introduced is crucial:
+        # If u is our vector, Rx is rotation around x axis etc, we want the
+        # following:
+        # u' = Rz * Ry * Rx * u = R * u
+        # That way, all rotational angles refer to a global coordinate system,
+        # and e.g. Ry does not refer to a rotation direction, which already
+        # was rotated around Rx.
+        # This definition in the global system is called extrinsic, and it is
+        # how the Location class wants it to be done.
+        # And this is why we introduce the rotations from left to right
+        # and from Z to X.
+        transformation = Matrix()
+        transformation.rotateZ(rotations[2] * pi / 180.0)
+        transformation.rotateY(rotations[1] * pi / 180.0)
+        transformation.rotateX(rotations[0] * pi / 180.0)
+
+        # Apply rotation on vectors of the global plane
+        # These vectors are already unit vectors and require no .normalized()
+        globaldirs = ((1, 0, 0), (0, 0, 1))
+        localdirs = (Vector(*i).transform(transformation) for i in globaldirs)
+
+        # Unpack vectors
+        xDir, normal = localdirs
+
+        # Apply attributes as in other constructor.
+        # Rememeber to set zDir before calling _setPlaneDir.
+        self.zDir = normal
+        self._setPlaneDir(xDir)
+        self.origin = origin
+
     def _eq_iter(self, other):
         """Iterator to successively test equality"""
         cls = type(self)
@@ -1012,15 +1055,22 @@ def __init__(
     ) -> None:
         """Location with translation (x,y,z) and 3 rotation angles."""
 
-        T = gp_Trsf()
+        if any((x, y, z, rx, ry, rz)):
 
-        q = gp_Quaternion()
-        q.SetEulerAngles(gp_Extrinsic_XYZ, radians(rx), radians(ry), radians(rz))
+            T = gp_Trsf()
 
-        T.SetRotation(q)
-        T.SetTranslationPart(Vector(x, y, z).wrapped)
+            q = gp_Quaternion()
+            q.SetEulerAngles(gp_Extrinsic_XYZ, radians(rx), radians(ry), radians(rz))
 
-        self.wrapped = TopLoc_Location(T)
+            T.SetRotation(q)
+            T.SetTranslationPart(Vector(x, y, z).wrapped)
+
+            loc = TopLoc_Location(T)
+        else:
+            # in this case location is flagged as identity
+            loc = TopLoc_Location()
+
+        self.wrapped = loc
 
     @__init__.register
     def __init__(self, t: Plane) -> None:
@@ -1104,6 +1154,11 @@ def toTuple(self) -> Tuple[Tuple[float, float, float], Tuple[float, float, float
 
         return rv_trans, (degrees(rx), degrees(ry), degrees(rz))
 
+    @property
+    def plane(self) -> "Plane":
+
+        return Plane(self)
+
     def __getstate__(self) -> BytesIO:
 
         rv = BytesIO()
@@ -1121,7 +1176,7 @@ def __setstate__(self, data: BytesIO):
         ls = BinTools_LocationSet()
         ls.Read(data)
 
-        if ls.NbLocations() == 0:
-            self.wrapped = TopLoc_Location()
-        else:
+        if ls.NbLocations() > 0:
             self.wrapped = ls.Location(1)
+        else:
+            self.wrapped = TopLoc_Location()  # identity location