Vector math utilities used in Draft workbench. More...

Functions

def DraftVecUtils.angle (u, v=Vector(1, 0, 0), normal=Vector(0, 0, 1))
 
def DraftVecUtils.closest (vector, vlist, return_length=False)
 
def DraftVecUtils.dist (u, v)
 
def DraftVecUtils.equals (u, v)
 
def DraftVecUtils.find (vector, vlist)
 
def DraftVecUtils.getPlaneRotation (u, v, w=None)
 
def DraftVecUtils.getRotation (vector, reference=Vector(1, 0, 0))
 
def DraftVecUtils.isColinear (vlist)
 
def DraftVecUtils.isNull (vector)
 
def DraftVecUtils.neg (u)
 
def DraftVecUtils.precision ()
 
def DraftVecUtils.project (u, v)
 
def DraftVecUtils.removeDoubles (vlist)
 
def DraftVecUtils.rotate (u, angle, axis=Vector(0, 0, 1))
 
def DraftVecUtils.rotate2D (u, angle)
 
def DraftVecUtils.rounded (v, d=None)
 
def DraftVecUtils.scale (u, scalar)
 
def DraftVecUtils.scaleTo (u, l)
 
def DraftVecUtils.toString (u)
 
def DraftVecUtils.tup (u, array=False)
 
def DraftVecUtils.typecheck (args_and_types, name="?")
 

Detailed Description

Vector math utilities used in Draft workbench.

Vector math utilities used primarily in the Draft workbench but which can also be used in other workbenches and in macros.

Function Documentation

◆ angle()

def DraftVecUtils.angle (   u,
  v = Vector(1, 0, 0),
  normal = Vector(0, 0, 1) 
)
Return the angle in radians between the two vectors.

It uses the definition of the dot product
::
    A * B = |A||B| cos(angle)

If only one vector is given, the angle is between that one and the
horizontal (+X).

If a third vector is given, it is the normal used to determine
the sign of the angle.
This normal is used to calculate a `factor` as the dot product
with the cross product of the first two vectors.
::
    C = A x B
    factor = normal * C

If the `factor` is positive the angle is positive, otherwise
it is the opposite sign.

Parameters
----------
u : Base::Vector3
    The first vector.
v : Base::Vector3, optional
    The second vector to test against the first one.
    It defaults to `(1, 0, 0)`, or +X.
normal : Base::Vector3, optional
    The vector indicating the normal.
    It defaults to `(0, 0, 1)`, or +Z.

Returns
-------
float
    The angle in radians between the vectors.
    It is zero if the magnitude of one of the vectors is zero,
    or if they are colinear.

References DraftVecUtils.typecheck().

Referenced by draftguitools.gui_offset.Offset.action(), importDXF.addText(), draftgeoutils.intersections.angleBisection(), importSVG.arcend2center(), DraftGui.DraftToolBar.changeAngleValue(), StdMeshers_Quadrangle_2D.check(), draftgeoutils.circles.circleFrom2LinesRadius(), AdaptivePath::Interpolation.clampAngle(), Path::Voronoi.colorColinear(), draftguitools.gui_labels.Label.create(), exportIFC.createCurve(), Import::ExportOCAF.createNode(), draftguitools.gui_rectangles.Rectangle.createObject(), Part::TopoShapeEdgePy.curveOnSurface(), DraftGui.DraftToolBar.displayPoint(), SketcherGui::ViewProviderSketch.draw(), draftgeoutils.geometry.findDistance(), draftfunctions.svg.format_point(), importIFCHelper.get2DShape(), draftfunctions.svg.get_svg(), SMESH_MesherHelper.GetAngle(), Base::VectorPy.getAngle(), draftguitools.gui_trackers.arcTracker.getAngle(), Base::RotationPy.getAngle(), importDXF.getArcData(), Base::RotationPy.getAxis(), draftgeoutils.cuboids.getCubicDimensions(), WorkingPlane.Plane.getDeviation(), draftfunctions.svgshapes.getDiscretized(), importIFClegacy.getIfcExtrusionData(), Part::Feature.getLocation(), Part::FeatureReference.getLocation(), App::PropertyPlacement.getPyPathValue(), Base::RotationPy.getRawAxis(), exportIFC.getRepresentation(), TechDraw::DrawProjGroupItem.getRotateAngle(), FCSphereSheetProjector.getRotation(), draftgeoutils.geometry.getRotation(), Part::TopoShape.getShapePlacement(), TechDraw::PATLineSpec.getSlope(), importIFClegacy.getTuples(), PartGui.goDimensionAngularNoTask(), draftgeoutils.arcs.isClockwise(), draftmake.make_sketch.make_sketch(), TechDrawGui::QGISectionLine.makeArrowsISO(), TechDrawGui::QGISectionLine.makeArrowsTrad(), TechDraw::DrawGeomHatch.makeEdgeOverlay(), ArchRoof.makeRoof(), TechDrawGui::QGISectionLine.makeSymbolsISO(), TechDrawGui::QGISectionLine.makeSymbolsTrad(), draftobjects.dimension.measure_two_obj_angles(), PathScripts.PathJobGui.TaskPanel.modelSetAxis(), draftgeoutils.edges.orientEdge(), Base::PlacementPy.PyInit(), Base::RotationPy.PyInit(), draftguitools.gui_trimex.Trimex.redraw(), Part::Geometry.rotate(), Base::PlacementPy.rotate(), Part::Geometry2dPy.rotate(), Part::TopoShapePy.rotate(), Import::ExportOCAF.saveShape(), MeshCore::MeshOutput.SaveX3DContent(), Base::RotationPy.setAngle(), Base::RotationPy.setAxis(), Part::TopoShape.setShapePlacement(), Gui::PropertyEditor::PropertyPlacementItem.toolTip(), Gui::PropertyEditor::PropertyPlacementItem.toString(), draftguitools.gui_trimex.Trimex.trimObjects(), draftguitools.gui_edit_draft_objects.DraftCircleGuiTools.update_object_from_edit_points(), Gui::PropertyEditor::PropertyPlacementItem.value(), and Path::PathSegmentWalker.walk().

◆ closest()

def DraftVecUtils.closest (   vector,
  vlist,
  return_length = False 
)
Find the closest point to one point in a list of points (vectors).

The scalar distance between the original point and one point in the list
is calculated. If the distance is smaller than a previously calculated
value, its index is saved, otherwise the next point in the list is tested.

Parameters
----------
vector: Base::Vector3
    The tested point or vector.

vlist: list
    A list of points or vectors.

return_length: bool, optional
    It defaults to `False`.
    If it is `True`, the value of the smallest distance will be returned.

Returns
-------
int
    The index of the list where the closest point is found.

int, float
    If `return_length` is `True`, it returns both the index
    and the length to the closest point.

References DraftVecUtils.typecheck().

Referenced by Base::BoundBox3< _Precision >.ClosestPoint(), draftgeoutils.intersections.connect(), and draftguitools.gui_trimex.Trimex.trimObjects().

◆ dist()

def DraftVecUtils.dist (   u,
  v 
)
Return the distance between two points (or vectors).

Parameters
----------
u : Base::Vector3
    First point, defined by a vector.
v : Base::Vector3
    Second point, defined by a vector.

Returns
-------
float
    The scalar distance from one point to the other.

References DraftVecUtils.typecheck().

Referenced by draftguitools.gui_arcs.Arc.action(), draftguitools.gui_polygons.Polygon.action(), CmdSketcherConstrainAngle.activated(), NETGENPlugin_Mesher.AddIntVerticesInSolids(), CmdSketcherConstrainAngle.applyConstraint(), Drawing::DrawingOutput.asCircle(), Attacher::AttachEngineLine.calculateAttachedPlacement(), CArea.ChangeStartToNearest(), StdMeshers_QuadToTriaAdaptor.CheckIntersection(), SMESH_MesherHelper.CheckNodeU(), SMESH_MesherHelper.CheckNodeUV(), VISCOUS_3D::_LayerEdge.ChooseSmooFunction(), draftgeoutils.circles.circlefrom1Line2Points(), draftgeoutils.circles.circleFrom2PointsRadius(), draftgeoutils.circles.circleFromPointLineRadius(), draftgeoutils.circle_inversion.circleInversion(), StdMeshers_QuadToTriaAdaptor.Compute(), SMESH_Block.ComputeParameters(), StdMeshers_Quadrangle_2D.computeQuadDominant(), ConstraintItem.data(), geoff_geometry.Dist(), triplet.distance_to(), Base::VectorPy.distanceToLine(), Base::Vector3< _Precision >.DistanceToLineSegment(), Base::VectorPy.distanceToPlane(), Base::VectorPy.distanceToPoint(), GCS::ConstraintP2PDistance.error(), GCS::ConstraintP2LDistance.error(), Mesh::SegmentByMesh.execute(), Sketcher::SketchObject.fillet(), TechDraw::DrawDimHelper.findClosestPoint(), SMESH_ElementSearcherImpl.FindClosestTo(), VISCOUS_3D::_LayerEdge.FindIntersection(), MeshCore::MeshKDTree.FindNearest(), draftgeoutils.circles.findRadicalAxis(), SMESH_Block.findUVAround(), TechDraw::GeometryObject.findVertex(), lscmrelax.get_max_distance(), Fem::Constraint.getBasePoint(), MeshCore::CylinderFit.GetBounding(), SMESH_MeshAlgos.GetDistance(), MeshCore::CylinderSurfaceFit.GetDistanceToSurface(), MeshCore::SphereSurfaceFit.GetDistanceToSurface(), GEOMUtils.GetMinDistance(), SMESH_MesherHelper.GetNodeUV(), Gui::AxisOrigin.getPlane(), SandboxGui::SoWidgetShape.getQuad(), SMESH_ElementSearcherImpl.getTolerance(), nlohmann::detail::dtoa_impl.grisu2_digit_gen(), nlohmann::detail::dtoa_impl.grisu2_round(), draftguitools.gui_rotate.Rotate.handle_mouse_move_event(), InspectionGui::ViewProviderInspection.inspectDistance(), TechDraw::Vertex.isEqual(), Fem::Tools.isLinear(), TechDraw::DrawProjectSplit.isOnEdge(), SMESH_MeshAlgos.IsOut(), Fem::Tools.isPlanar(), MeshCore::MeshGeomFacet.IsPointOfSphere(), VISCOUS_3D::_Curvature.lenDeltaByDist(), SMESH_Pattern.Load(), Part::TopoShapeFacePy.makeOffset(), Part::TopoShapeWirePy.makeOffset(), TechDrawGui::QGISectionLine.makeSymbolsISO(), GCS::ConstraintP2PDistance.maxStep(), CArea.NearestPoint(), CCurve.NearestPoint(), MeshCore::MeshNearestIndexToPlane< T >.operator()(), geoff_geometry::Plane.Plane(), cLineSegment.PointAt(), draftgeoutils.circle_inversion.pointInversion(), CCurve.PointToPerim(), AdaptivePath.PopPathWithClosestPoint(), Part::GeometrySurfacePy.projectPoint(), Part::CirclePy.PyInit(), Part::CylinderPy.PyInit(), Part::Circle2dPy.PyInit(), Part::PlanePy.PyInit(), MeshCore::MeshOutput.SaveX3DContent(), SketcherGui::ViewProviderSketch.setEditViewer(), SMESH_MeshEditor.SewFreeBorder(), SMESH_MeshEditor.SewSideElements(), Part::TopoShapePy.slices(), PathScripts.PathUtils.sort_jobs(), and Gui::SoFCDB.writeToX3D().

◆ equals()

def DraftVecUtils.equals (   u,
  v 
)
Check for equality between two vectors.

Due to rounding errors, two vectors will rarely be `equal`.
Therefore, this function checks that the corresponding elements
of the two vectors differ by less than the decimal `precision` established
in the parameter database, accessed through `FreeCAD.ParamGet()`.
::
    x1 - x2 < precision
    y1 - y2 < precision
    z1 - z2 < precision

Parameters
----------
u : Base::Vector3
    The first vector.
v : Base::Vector3
    The second vector.

Returns
-------
bool
    `True` if the vectors are within the precision, `False` otherwise.

References DraftVecUtils.isNull(), and DraftVecUtils.typecheck().

Referenced by WorkingPlane.Plane.alignToFace(), draftguitools.gui_trackers.dimTracker.calc(), draftgeoutils.circles.circleFrom2PointsRadius(), draftgeoutils.circles.circleFrom3LineTangents(), draftgeoutils.circle_inversion.circleInversion(), exportIFC.createCurve(), importDXF.drawLine(), importDXF.drawPolyline(), draftguitools.gui_lines.Line.drawSegment(), draftgeoutils.general.edg(), draftobjects.clone.Clone.execute(), draftobjects.patharray.PathArray.execute(), draftobjects.wire.Wire.execute(), DraftVecUtils.find(), draftgeoutils.edges.findEdge(), draftgeoutils.circles.findHomotheticCenterOfCircles(), draftgeoutils.intersections.findIntersection(), draftgeoutils.circles.findRadicalAxis(), draftgeoutils.wires.findWiresOld2(), draftobjects.patharray.get_parameter_from_v0(), importIFClegacy.getIfcExtrusionData(), PartDesign::SubShapeBinder.getSubObject(), draftgeoutils.wires.isReallyClosed(), draftgeoutils.edges.isSameLine(), draftmake.make_sketch.make_sketch(), ArchFloor.makeFloor(), draftguitools.gui_arcs.Arc.numericRadius(), draftgeoutils.offsets.offsetWire(), draftgeoutils.circle_inversion.pointInversion(), DraftVecUtils.removeDoubles(), and draftguitools.gui_snapper.Snapper.snapToCrossExtensions().

◆ find()

def DraftVecUtils.find (   vector,
  vlist 
)
Find a vector in a list of vectors, and return the index.

Finding a vector tests for `equality` which depends on the `precision`
parameter in the parameter database.

Parameters
----------
vector : Base::Vector3
    The tested vector.
vlist : list
    A list of Base::Vector3 vectors.

Returns
-------
int
    The index of the list where the vector is found,
    or `None` if the vector is not found.

See Also
--------
equals : test for equality between two vectors

References DraftVecUtils.equals(), and DraftVecUtils.typecheck().

Referenced by StdCmdOpen.activated(), Gui::Translator.activateLanguage(), Sketcher::SketchObject.addCopy(), SMESHDS_Mesh.AddHypothesis(), Gui::ViewProviderVRMLObject.addResource(), Sketcher::SketchObject.addSymmetric(), PointsGui::ViewProviderScattered.attach(), PointsGui::ViewProviderStructured.attach(), NETGENPlugin_NETGEN_2D3D.CheckHypothesis(), draftgeoutils.faces.cleanFaces(), TechDraw::DrawViewSpreadsheet.colInList(), MeshCore::MeshTopoAlgorithm.CollapseEdge(), MeshCore::MeshTopoAlgorithm.CollapseVertex(), StdMeshers_Projection_2D.Compute(), StdMeshers_Regular_1D.Compute(), SMESH_ProxyMesh::SubMesh.Contains(), Sketcher::SketchObject.delGeometries(), Gui::Document.detachView(), PartGui::DlgPrimitives.DlgPrimitives(), SketcherGui::ViewProviderSketch.draw(), TechDrawGui::QGIViewClip.drawClip(), KDTree::KDTree< __K, _Val, _Acc, _Dist, _Cmp, _Alloc >.erase(), Drawing::FeatureViewSpreadsheet.execute(), Fem::FemPostScalarClipFilter.execute(), Fem::FemPostWarpVectorFilter.execute(), App::Document.exportGraphviz(), App::PropertyLinkList.find(), App::DocumentP.findAllPathsAt(), StdMeshers_ProjectionUtils.FindFaceAssociation(), Gui::DocumentItem.findItem(), SMESH_HypoFilter::IsMoreLocalThanPredicate.findPreferable(), MeshCore::MeshSurfaceSegment.FindSegment(), MeshCore::MeshPointArray.Get(), Fem::FemMesh.getccxVolumesByFace(), PartDesign::DressUp.getContiniusEdges(), StdMeshers_CompositeSegment_1D.GetFaceSide(), MeshCore::MeshEvalTopology.GetFacetManifolds(), Gui::ExpressionBinding.getIcon(), ExpressionDelegate.getIcon(), Gui::ViewProviderVRMLObject.getLocalResources(), PartDesign::Body.getNextSolidFeature(), App::Document.getPathsByOutList(), PartDesign::Body.getPrevSolidFeature(), importIFClegacy.IfcEntity.getProperties(), importIFClegacy.IfcEntity.getProperty(), TechDraw::DrawViewSpreadsheet.getSheetImage(), DriverMED.GetSMDSType(), Base::Writer.getUniqueFileName(), App::Branding.getUserDefines(), Spreadsheet::PropertyColumnWidths.getValue(), Spreadsheet::PropertyRowHeights.getValue(), App::Origin.hasObject(), Gui::PropertyEditor::PropertyItem.hasProperty(), PartDesign::Body.insertObject(), Part::BodyBase.isAfter(), PartDesignGui.isAnyNonPartDesignLinksTo(), StdMeshers_Prism_3D.IsApplicable(), SMDS_VolumeTool.IsLinked(), Gui::ProgressBarPrivate.isModalDialog(), Gui::WaitCursorP.isModalDialog(), SMESH_Mesh.IsOrderOK(), StdMeshers_ViscousLayers.IsShapeWithLayers(), SMESHDS_Mesh.IsUsedHypothesis(), SMESH_Mesh.IsUsedHypothesis(), SMESH_Block.LoadMeshBlock(), SMESH_ProxyMesh.NbFaces(), SMESH_Mesh.NotifySubMeshesHypothesisModification(), PartDesignGui::TaskBooleanParameters.onSelectionChanged(), PartDesignGui::TaskTransformedParameters.originalSelected(), PathScripts.post.marlin_post.parse(), Points::PlyReader.read(), Points::PcdReader.read(), gzip_utf8.GzipFile.readline(), Gui::Dialog::DocumentRecoveryPrivate.readXmlFile(), PartDesignGui::TaskDressUpParameters.referenceSelected(), PartDesignGui::TaskPipeParameters.referenceSelected(), PartDesignGui::TaskPipeOrientation.referenceSelected(), PartDesignGui::TaskPipeScaling.referenceSelected(), PartDesignGui::TaskShapeBinder.referenceSelected(), GCS::System.removeConstraint(), SMESHDS_Mesh.RemoveHypothesis(), Base::SequencerP.removeInstance(), PartDesign::Body.removeObject(), Gui::PropertyEditor::PropertyEditor.removeProperty(), Gui::PropertyEditor::PropertyItem.removeProperty(), StdMeshers_ViscousLayers2D.RestoreListeners(), MeshCore::MeshOutput.SaveOBJ(), Gui::Document.setActiveWindow(), StdMeshers_ProjectionUtils.SetEventListener(), App::LinkBaseExtension.setLink(), PartGui::DlgFilletEdges.setupFillet(), App::PropertyString.setValue(), Gui::Application.sGetMarkerIndex(), FaceQuadStruct.shift(), PartDesignGui::TaskFeaturePick.slotDeletedObject(), SMESH_Mesh.SortByMeshOrder(), ArchRebar.strprocessOfCustomSpacing(), Gui::SelectionFilter.test(), VISCOUS_3D.ToClearSubWithMain(), App::Origin.unsetupObject(), and SketcherGui::TaskDlgEditSketch.~TaskDlgEditSketch().

◆ getPlaneRotation()

def DraftVecUtils.getPlaneRotation (   u,
  v,
  w = None 
)
Return a rotation matrix defining the (u,v,w) coordinate system.

The rotation matrix uses the elements from each vector.
::
        (u.x  v.x  w.x  0  )
    R = (u.y  v.y  w.y  0  )
        (u.z  v.z  w.z  0  )
        (0    0    0    1.0)

Parameters
----------
u : Base::Vector3
    The first vector.
v : Base::Vector3
    The second vector.
w : Base::Vector3, optional
    The third vector. It defaults to `None`, in which case
    it is calculated as the cross product of `u` and `v`.
    ::
        w = u.cross(v)

Returns
-------
Base::Matrix4D
    The new rotation matrix defining a new coordinate system,
    or `None` if `u`, or `v`, is `None`.

References DraftVecUtils.typecheck().

Referenced by importDXF.drawEllipse(), importIFClegacy.getPlacement(), importIFCHelper.getPlacement(), WorkingPlane.Plane.getRotation(), and draftviewproviders.view_label.ViewProviderLabel.update_arrow().

◆ getRotation()

def DraftVecUtils.getRotation (   vector,
  reference = Vector(1, 0, 0) 
)
Return a quaternion rotation between a vector and a reference.

If the reference is omitted, the +X axis is used.

Parameters
----------
vector : Base::Vector3
    The original vector.
reference : Base::Vector3, optional
    The reference vector. It defaults to `(1, 0, 0)`, the +X axis.

Returns
-------
(x, y, z, Q)
    A tuple with the unit elements (normalized) of the cross product
    between the `vector` and the `reference`, and a `Q` value,
    which is the sum of the products of the magnitudes,
    and of the dot product of those vectors.
    ::
        Q = |A||B| + |A||B| cos(angle)

    It returns `(0, 0, 0, 1.0)`
    if the cross product between the `vector` and the `reference`
    is null.

See Also
--------
rotate2D, rotate

References DraftVecUtils.isNull().

◆ isColinear()

def DraftVecUtils.isColinear (   vlist)
Check if the vectors in the list are colinear.

Colinear vectors are those whose angle between them is zero.

This function tests for colinearity between the difference
of the first two vectors, and the difference of the nth vector with
the first vector.
::
    vlist = [a, b, c, d, ..., n]

    k = b - a
    k2 = c - a
    k3 = d - a
    kn = n - a

Then test
::
    angle(k2, k) == 0
    angle(k3, k) == 0
    angle(kn, k) == 0

Parameters
----------
vlist : list
    List of Base::Vector3 vectors.
    At least three elements must be present.

Returns
-------
bool
    `True` if the vector differences are colinear,
    or if the list only has two vectors.
    `False` otherwise.

Notes
-----
Due to rounding errors, the angle may not be exactly zero;
therefore, it rounds the angle by the number
of decimals specified in the `precision` parameter
in the parameter database, and then compares the value to zero.

References DraftVecUtils.typecheck().

Referenced by importDXF.drawPolyline().

◆ isNull()

def DraftVecUtils.isNull (   vector)
Return False if each of the components of the vector is zero.

Due to rounding errors, an element is probably never going to be
exactly zero. Therefore, it rounds the element by the number
of decimals specified in the `precision` parameter
in the parameter database, accessed through `FreeCAD.ParamGet()`.
It then compares the rounded numbers against zero.

Parameters
----------
vector : Base::Vector3
    The tested vector.

Returns
-------
bool
    `True` if each of the elements is zero within the precision.
    `False` otherwise.

Referenced by draftguitools.gui_arcs.Arc.action(), draftguitools.gui_polygons.Polygon.action(), importDXF.addText(), draftgeoutils.general.areColinear(), ArchWall.areSameWallTypes(), importDXF.calcBulge(), ArchVRM.Renderer.compare(), draftguitools.gui_stretch.Stretch.doStretch(), DraftVecUtils.equals(), draftobjects.shape2dview.Shape2DView.execute(), ArchRoof.find_inters(), draftgeoutils.intersections.findIntersection(), draftfunctions.dxf.get_dxf(), draftgeoutils.circles.getCircleFromSpline(), exportIFC.getRepresentation(), DraftVecUtils.getRotation(), draftguitools.gui_rotate.Rotate.handle_mouse_move_event(), draftgeoutils.arcs.isClockwise(), ArchFrame.makeFrame(), ArchRebar.makeRebar(), draftobjects.array.polar_placements(), ArchWindow.recolorize(), ArchSpace.removeSpaceBoundaries(), draftguitools.gui_snapper.Snapper.snapToExtensions(), draftguitools.gui_snapper.Snapper.snapToPolar(), draftviewproviders.view_label.ViewProviderLabel.update_arrow(), draftviewproviders.view_dimension.ViewProviderAngularDimension.updateData(), and draftviewproviders.view_wire.ViewProviderWire.updateData().

◆ neg()

def DraftVecUtils.neg (   u)
Return the negative of a given vector.

Parameters
----------
u : Base::Vector3
    A FreeCAD.Vector.

Returns
-------
Base::Vector3
    A vector in which each element has the opposite sign of
    the original element.

References DraftVecUtils.typecheck().

Referenced by ArchPanel.PanelView.execute(), importIFClegacy.getIfcBrepFacesData(), exportIFC.getRepresentation(), ArchStairs.makeRailing(), Fem::ConstraintPulley.onChanged(), and Base::Rotation.slerp().

◆ precision()

def DraftVecUtils.precision ( )
Get the number of decimal numbers used for precision.

Returns
-------
int
    Return the number of decimal places set up in the preferences,
    or a standard value (6), if the parameter is missing.

Referenced by ArchVRM.Renderer.getPathData(), and WorkingPlane.Plane.projectPointOld().

◆ project()

def DraftVecUtils.project (   u,
  v 
)
Project the first vector onto the second one.

The projection is just the second vector scaled by a factor.
This factor is the dot product divided by the square
of the second vector's magnitude.
::
    f = A * B / |B|**2 = |A||B| cos(angle) / |B|**2
    f = |A| cos(angle)/|B|

Parameters
----------
u : Base::Vector3
    The first vector.
v : Base::Vector3
    The second vector.

Returns
-------
Base::Vector3
    The new vector, which is the same vector `v` scaled by a factor.
    Return `Vector(0, 0, 0)`, if the magnitude of the second vector
    is zero.

References DraftVecUtils.typecheck().

Referenced by draftguitools.gui_arcs.Arc.action(), draftguitools.gui_dimensions.Dimension.action(), draftguitools.gui_polygons.Polygon.action(), StdCmdMergeProjects.activated(), ArchSectionPlane.closeViewer(), ArchVRM.Renderer.compare(), draftguitools.gui_snapper.Snapper.constrain(), draftguitools.gui_ellipses.Ellipse.createObject(), draftguitools.gui_rectangles.Rectangle.createObject(), draftgeoutils.geometry.findDistance(), draftfunctions.svgshapes.get_proj(), draftguitools.gui_selectplane.Draft_SelectPlane.getCenterPoint(), ArchSectionPlane.getCoinSVG(), ArchCommands.getCutVolume(), StdMeshers_Quadrangle_2D.getEnforcedUV(), WorkingPlane.Plane.getLocalCoords(), WorkingPlane.Plane.getLocalRot(), draftguitools.gui_snapper.Snapper.getPerpendicular(), ArchCurtainWall.CurtainWall.getProjectedLength(), draftguitools.gui_trackers.rectangleTracker.getSize(), draftguitools.gui_rotate.Rotate.handle_mouse_move_event(), draftguitools.gui_trackers.rectangleTracker.isInside(), SMESH_Pattern.Load(), Drawing::Module.Module(), draftfunctions.offset.offset(), ArchBuildingPart.ViewProviderBuildingPart.onChanged(), ArchNesting.Nester.order(), FCSphereSheetProjector.project(), ArchCommands.projectToVector(), ArchWindow.recolorize(), draftguitools.gui_trimex.Trimex.redraw(), draftfunctions.scale.scale(), draftguitools.gui_rotate.Rotate.set_rotation_angle(), SMESH_MeshEditor.Smooth(), draftguitools.gui_trackers.rectangleTracker.update(), draftguitools.gui_edit_arch_objects.ArchWallGuiTools.update_object_from_edit_points(), draftguitools.gui_edit_draft_objects.DraftRectangleGuiTools.update_object_from_edit_points(), draftguitools.gui_edit_draft_objects.DraftCircleGuiTools.update_object_from_edit_points(), draftguitools.gui_edit_part_objects.PartBoxGuiTools.update_object_from_edit_points(), draftguitools.gui_edit_part_objects.PartCylinderGuiTools.update_object_from_edit_points(), draftguitools.gui_edit_part_objects.PartConeGuiTools.update_object_from_edit_points(), and draftguitools.gui_edit_draft_objects.DraftCircleGuiTools.update_preview_object().

◆ removeDoubles()

def DraftVecUtils.removeDoubles (   vlist)
Remove duplicated vectors from a list of vectors.

It removes only the duplicates that are next to each other in the list.

It tests the `i` element, and compares it to the `i+1` element.
If the former one is different from the latter,
the former is added to the new list, otherwise it is skipped.
The last element is always included.
::
    [a, b, b, c, c] -> [a, b, c]
    [a, a, b, a, a, b] -> [a, b, a, b]

Finding duplicated vectors tests for `equality` which depends
on the `precision` parameter in the parameter database.

Parameters
----------
vlist : list of Base::Vector3
    List with vectors.

Returns
-------
list of Base::Vector3
    New list with sequential duplicates removed,
    or the original `vlist` if there is only one element in the list.

See Also
--------
equals : test for equality between two vectors

References DraftVecUtils.equals(), and DraftVecUtils.typecheck().

Referenced by ArchRoof.face_from_points().

◆ rotate()

def DraftVecUtils.rotate (   u,
  angle,
  axis = Vector(0, 0, 1) 
)
Rotate the vector by the specified angle, around the given axis.

If the axis is omitted, the rotation is made around the Z axis
(on the XY plane).

It uses a 3x3 rotation matrix.
::
    u_rot = R u

            (c + x*x*t    xyt - zs     xzt + ys )
    u_rot = (xyt + zs     c + y*y*t    yzt - xs ) * u
            (xzt - ys     yzt + xs     c + z*z*t)

Where `x`, `y`, `z` indicate unit components of the axis;
`c` denotes a cosine of the angle; `t` indicates a complement
of that cosine; `xs`, `ys`, `zs` indicate products of the unit
components and the sine of the angle; and `xyt`, `xzt`, `yzt`
indicate products of two unit components and the complement
of the cosine.

Parameters
----------
u : Base::Vector3
    The vector.
angle : float
    The angle of rotation given in radians.
axis : Base::Vector3, optional
    The vector specifying the axis of rotation.
    It defaults to `(0, 0, 1)`, the +Z axis.

Returns
-------
Base::Vector3
    The new rotated vector.
    If the `angle` is zero, return the original vector `u`.

References DraftVecUtils.typecheck().

Referenced by draftguitools.gui_offset.Offset.action(), WorkingPlane.Plane.alignToPointAndAxis(), WorkingPlane.Plane.alignToPointAndAxis_SVG(), draftgeoutils.intersections.angleBisection(), DraftGui.DraftToolBar.changeAngleValue(), draftgeoutils.circles.circleFrom2LinesRadius(), draftgeoutils.circles.circleFrom3LineTangents(), draftfunctions.svg.format_point(), draftfunctions.svg.get_svg(), draftgeoutils.circles.getCircleFromSpline(), draftguitools.gui_arcs.Arc.numericRadius(), draftfunctions.offset.offset(), ArchWindow.recolorize(), draftguitools.gui_trimex.Trimex.redraw(), draftfunctions.rotate.rotate(), draftfunctions.rotate.rotate_vector_from_center(), draftguitools.gui_snapper.Snapper.snapToPolar(), and ArchPanel.ViewProviderPanelSheet.updateData().

◆ rotate2D()

def DraftVecUtils.rotate2D (   u,
  angle 
)
Rotate the given vector around the Z axis by the specified angle.

The rotation occurs in two dimensions only by means of
a rotation matrix.
::
     u_rot                R                 u
    (x_rot) = (cos(-angle) -sin(-angle)) * (x)
    (y_rot)   (sin(-angle)  cos(-angle))   (y)

Normally the angle is positive, but in this case it is negative.

`"Such non-standard orientations are rarely used in mathematics
but are common in 2D computer graphics, which often have the origin
in the top left corner and the y-axis pointing down."`
W3C Recommendations (2003), Scalable Vector Graphics: the initial
coordinate system.

Parameters
----------
u : Base::Vector3
    The vector.
angle : float
    The angle of rotation given in radians.

Returns
-------
Base::Vector3
    The new rotated vector.

◆ rounded()

def DraftVecUtils.rounded (   v,
  d = None 
)
Return a vector rounded to the `precision` in the parameter database
or to the given decimals value

Each of the components of the vector is rounded to the decimal
precision set in the parameter database.

Parameters
----------
v : Base::Vector3
    The input vector.
d : (Optional) the number of decimals to round to

Returns
-------
Base::Vector3
    The new vector where each element `x`, `y`, `z` has been rounded
    to the number of decimals specified in the `precision` parameter
    in the parameter database.

Referenced by ArchEquipment.createMeshView(), importIFClegacy.getIfcExtrusionData(), and importIFClegacy.getTuples().

◆ scale()

def DraftVecUtils.scale (   u,
  scalar 
)
Scales (multiplies) a vector by a scalar factor.

Parameters
----------
u : Base::Vector3
    The FreeCAD.Vector to scale.
scalar : float
    The scaling factor.

Returns
-------
Base::Vector3
    The new vector with each of its elements multiplied by `scalar`.

References DraftVecUtils.typecheck().

Referenced by ArchStairs.makeRailing(), and ArchWindow.recolorize().

◆ scaleTo()

def DraftVecUtils.scaleTo (   u,
  l 
)
Scale a vector so that its magnitude is equal to a given length.

The magnitude of a vector is
::
    L = sqrt(x**2 + y**2 + z**2)

This function multiplies each coordinate, `x`, `y`, `z`,
by a factor to produce the desired magnitude `L`.
This factor is the ratio of the new magnitude to the old magnitude,
::
    x_scaled = x * (L_new/L_old)

Parameters
----------
u : Base::Vector3
    The vector to scale.
l : int or float
    The new magnitude of the vector in standard units (mm).

Returns
-------
Base::Vector3
    The new vector with each of its elements scaled by a factor.
    Or the same input vector `u`, if it is `(0, 0, 0)`.

References DraftVecUtils.typecheck().

Referenced by ArchPanel.CommandPanelSheet.Activated(), importDXF.addText(), ArchWall.areSameWallTypes(), ArchRebar.CalculatePlacement(), draftgeoutils.circles.circleFromPointLineRadius(), ArchRebar.CustomSpacingPlacement(), draftobjects.wire.Wire.execute(), draftgeoutils.edges.findMidpoint(), draftfunctions.svg.format_point(), draftguitools.gui_selectplane.Draft_SelectPlane.getCenterPoint(), ArchCommands.getCutVolume(), ArchStairs.makeRailing(), ArchRebar.makeRebar(), draftobjects.dimension.measure_one_obj_edge(), draftguitools.gui_arcs.Arc.numericRadius(), draftgeoutils.offsets.offsetWire(), draftobjects.wire.Wire.onChanged(), WorkingPlane.Plane.projectPoint(), ArchCommands.projectToVector(), ArchWindow.recolorize(), draftguitools.gui_trimex.Trimex.redraw(), draftguitools.gui_snapper.Snapper.snapToPerpendicular(), draftguitools.gui_trackers.boxTracker.update(), and importDXF.writeShape().

◆ toString()

def DraftVecUtils.toString (   u)
Return a string with the Python command to recreate this vector.

Parameters
----------
u : list, or Base::Vector3
    A list of FreeCAD.Vectors, or a single vector.

Returns
-------
str
    The string with the code that can be used in the Python console
    to create the same list of vectors, or single vector.

Referenced by draftguitools.gui_offset.Offset.action(), draftguitools.gui_move.Move.build_copy_subelements_command(), draftguitools.gui_rotate.Rotate.build_copy_subelements_command(), draftguitools.gui_scale.Scale.build_copy_subelements_command(), draftguitools.gui_move.Move.build_move_subelements_command(), draftguitools.gui_rotate.Rotate.build_rotate_subelements_command(), draftguitools.gui_scale.Scale.build_scale_subelements_command(), draftguitools.gui_labels.Label.create(), draftguitools.gui_dimensions.Dimension.create_angle_dimension(), draftguitools.gui_dimensions.Dimension.create_linear_dimension(), draftguitools.gui_dimensions.Dimension.create_linear_dimension_obj(), drafttaskpanels.task_circulararray.TaskPanelCircularArray.create_object(), drafttaskpanels.task_orthoarray.TaskPanelOrthoArray.create_object(), drafttaskpanels.task_polararray.TaskPanelPolarArray.create_object(), draftguitools.gui_dimensions.Dimension.create_radial_dimension_obj(), draftguitools.gui_dimensions.Dimension.create_with_app_measure(), draftguitools.gui_ellipses.Ellipse.createObject(), draftguitools.gui_rectangles.Rectangle.createObject(), draftguitools.gui_shapestrings.ShapeString.createObject(), draftguitools.gui_texts.Text.createObject(), drafttaskpanels.task_shapestring.ShapeStringTaskPanel.createObject(), Gui::PropertyEditor::PropertyItem.data(), draftguitools.gui_arcs.Arc.drawArc(), draftguitools.gui_polygons.Polygon.drawPolygon(), Gui::QuantitySpinBox.event(), draftguitools.gui_lines.Line.finish(), TechDrawGui::TaskProjGroup.formatVector(), ArchPanel.CommandPanel.getPoint(), PartGui::DlgExtrusion.getShapesToExtrude(), PartGui::DlgRevolution.getShapesToRevolve(), draftguitools.gui_base_original.DraftTool.getStrings(), draftguitools.gui_mirror.Mirror.mirror(), draftguitools.gui_move.Move.move_object(), draftguitools.gui_offset.Offset.numericRadius(), Gui::QuantitySpinBox.onChange(), Gui::UIntSpinBox.onChange(), ArchStructure.placeAlongEdge(), draftguitools.gui_patharray.PathArray.proceed(), draftguitools.gui_shape2dview.Shape2DView.proceed(), draftguitools.gui_split.Split.proceed(), Gui::QuantitySpinBox.resizeEvent(), Gui::UIntSpinBox.resizeEvent(), Gui::IntSpinBox.resizeEvent(), Gui::DoubleSpinBox.resizeEvent(), Gui::ExpLineEdit.resizeEvent(), draftguitools.gui_rotate.Rotate.rotate_object(), draftguitools.gui_scale.Scale.scale_object(), draftguitools.gui_scale.Scale.scale_with_clone(), Gui::Dialog::DlgSettingsColorGradientImp.setRange(), Gui::PropertyEditor::PropertyIntegerItem.toString(), Gui::PropertyEditor::PropertyIntegerConstraintItem.toString(), and Gui::SoFCOffscreenRenderer.writeToImageFile().

◆ tup()

def DraftVecUtils.tup (   u,
  array = False 
)

◆ typecheck()

def DraftVecUtils.typecheck (   args_and_types,
  name = "?" 
)
Check that the arguments are instances of certain types.

Parameters
----------
args_and_types : list
    A list of tuples. The first element of a tuple is tested as being
    an instance of the second element.
    ::
        args_and_types = [(a, Type), (b, Type2), ...]

    Then
    ::
        isinstance(a, Type)
        isinstance(b, Type2)

    A `Type` can also be a tuple of many types, in which case
    the check is done for any of them.
    ::
        args_and_types = [(a, (Type3, int, float)), ...]

        isinstance(a, (Type3, int, float))

name : str, optional
    Defaults to `'?'`. The name of the check.

Raises
------
TypeError
    If the first element in the tuple is not an instance of the second
    element.

Referenced by DraftVecUtils.angle(), DraftVecUtils.closest(), DraftVecUtils.dist(), DraftVecUtils.equals(), DraftVecUtils.find(), DraftVecUtils.getPlaneRotation(), DraftVecUtils.isColinear(), DraftVecUtils.neg(), DraftVecUtils.project(), DraftVecUtils.removeDoubles(), DraftVecUtils.rotate(), DraftVecUtils.scale(), DraftVecUtils.scaleTo(), and DraftVecUtils.tup().