Public Member Functions
def	alignTo3Points (self, p1, p2, p3, offset=0)

def	alignToCurve (self, shape, offset=0)

def	alignToEdges (self, edges)

def	alignToFace (self, shape, offset=0)

def	alignToPointAndAxis (self, point, axis, offset=0, upvec=None)

def	alignToPointAndAxis_SVG (self, point, axis, offset=0)

def	alignToSelection (self, offset=0)

def	copy (self)

def	getClosestAxis (self, point)

def	getDeviation (self)

def	getGlobalCoords (self, point)

def	getGlobalRot (self, point)

def	getLocalCoords (self, point)

def	getLocalRot (self, point)

def	getNormal (self)

def	getPlacement (self, rotated=False)

def	getRotation (self)

def	inverse (self)

def	isGlobal (self)

def	isOrtho (self)

def	offsetToPoint (self, p, direction=None)

def	projectPoint (self, p, direction=None)

def	projectPointOld (self, p, direction=None)

def	reset (self)

def	restore (self)

def	save (self)

def	setFromPlacement (self, pl, rebase=False)

def	setFront (self)

def	setSide (self)

def	setTop (self)

def	setup (self, direction=None, point=None, upvec=None, force=False)

Public Attributes
	axis

	doc

	position

	stored

	u

	v

	weak

Detailed Description

A WorkPlane object.

Parameters
----------
u: Base::Vector3, optional
    An axis (vector) that helps define the working plane.
    It defaults to `(1, 0, 0)`, or the +X axis.

v: Base::Vector3, optional
    An axis (vector) that helps define the working plane.
    It defaults to `(0, 1, 0)`, or the +Y axis.

w: Base::Vector3, optional
    An axis that is supposed to be perpendicular to `u` and `v`;
    it is redundant.
    It defaults to `(0, 0, 1)`, or the +Z axis.

pos: Base::Vector3, optional
    A point through which the plane goes through.
    It defaults to the origin `(0, 0, 0)`.

Attributes
----------
doc: App::Document
    The active document. Reset view when `doc` changes.

weak: bool
    It is `True` if the plane has been defined by `setup()`
    or has been reset. A weak plane can be changed
    (it is the "auto" mode), while a strong plane will keep
    its position until weakened (it is "locked")

u: Base::Vector3
    An axis (vector) that helps define the working plane.

v: Base::Vector3
    An axis (vector) that helps define the working plane.

axis: Base::Vector3
    A vector that is supposed to be perpendicular to `u` and `v`;
    it is helpful although redundant.

position: Base::Vector3
    A point, which the plane goes through,
    that helps define the working plane.

stored: bool
    A placeholder for a stored state.

Member Function Documentation

◆ alignTo3Points()

def WorkingPlane.Plane.alignTo3Points	(	self,
		p1,
		p2,
		p3,
		offset = `0`
	)

Align the plane to three points.

It makes a closed quadrilateral face with the three points,
and then calls `alignToFace(shape, offset)`.

Parameter
---------
p1 : Base::Vector3
    The first point.
p2 : Base::Vector3
    The second point.
p3 : Base::Vector3
    The third point.

offset : float
    Defaults to zero. A value which will be used to offset
    the plane in the direction of its `axis`.

Returns
-------
bool
    `True` if the operation was successful, and `False` otherwise.

References WorkingPlane.Plane.alignToFace().

◆ alignToCurve()

def WorkingPlane.Plane.alignToCurve	(	self,
		shape,
		offset = `0`
	)

Align plane to curve. NOT YET IMPLEMENTED.

Parameters
----------
shape : Part.Shape
    A curve that will serve to align the plane.
    It can be an `'Edge'` or `'Wire'`.
offset : float
    Defaults to zero. A value which will be used to offset
    the plane in the direction of its `axis`.

Returns
-------
False
    Returns `False` if the shape is null.
    Currently it always returns `False`.

Referenced by WorkingPlane.Plane.alignToSelection().

◆ alignToEdges()

def WorkingPlane.Plane.alignToEdges	(	self,
		edges
	)

Align plane to two edges.

Uses the two points of the first edge to define the direction
of the unit vector `u`, the other two points of the other edge
to define the other unit vector `v`, and then the cross product
of `u` with `v` to define the `axis`.

Parameters
----------
edges : list
    A list of two edges.

Returns
-------
False
    Return `False` if `edges` is a list of more than 2 elements.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

◆ alignToFace()

def WorkingPlane.Plane.alignToFace	(	self,
		shape,
		offset = `0`
	)

Align the plane to a face.

It uses the center of mass of the face as `position`,
and its normal in the center of the face as `axis`,
then calls `alignToPointAndAxis(position, axis, offset)`.

If the face is a quadrilateral, then it adjusts the position
of the plane according to its reported X direction and Y direction.

Also set `weak` to `False`.

Parameter
--------
shape : Part.Face
    A shape of type `'Face'`.

offset : float
    Defaults to zero. A value which will be used to offset
    the plane in the direction of its `axis`.

Returns
-------
bool
    `True` if the operation was successful, and `False` if the shape
    is not a `'Face'`.

See Also
--------
alignToPointAndAxis, DraftGeomUtils.getQuad

References WorkingPlane.Plane.alignToPointAndAxis(), WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, DraftVecUtils.equals(), WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< Rotation >.v, Base::vec_traits< SbColor >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, draftguitools.gui_trackers.rectangleTracker.v, and WorkingPlane.Plane.weak.

Referenced by WorkingPlane.Plane.alignTo3Points(), and WorkingPlane.Plane.alignToSelection().

◆ alignToPointAndAxis()

def WorkingPlane.Plane.alignToPointAndAxis	(	self,
		point,
		axis,
		offset = `0`,
		upvec = `None`
	)

Align the working plane to a point and an axis (vector).

Set `v` as the cross product of `axis` with `(1, 0, 0)` or `+X`,
and `u` as `v` rotated -90 degrees around the `axis`.
Also set `weak` to `False`.

Parameters
----------
point : Base::Vector3
    The new `position` of the plane, adjusted by
    the `offset`.
axis : Base::Vector3
    A vector whose unit vector will be used as the new `axis`
    of the plane.
    If it is very close to the `X` or `-X` axes,
    it will use this axis exactly, and will adjust `u` and `v`
    to `+Y` and `+Z`, or `-Y` and `+Z`, respectively.
offset : float, optional
    Defaults to zero. A value which will be used to offset
    the plane in the direction of its `axis`.
upvec : Base::Vector3, optional
    Defaults to `None`.
    If it exists, its unit vector will be used as `v`,
    and will set `u` as the cross product of `v` with `axis`.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, drafttests.test_pivy.DraftPivy.doc, drafttests.test_dxf.DraftDXF.doc, drafttests.test_modification.DraftModification.doc, drafttests.test_oca.DraftOCA.doc, drafttests.test_airfoildat.DraftAirfoilDAT.doc, drafttests.test_svg.DraftSVG.doc, drafttests.test_dwg.DraftDWG.doc, drafttests.test_creation.DraftCreation.doc, Gui::GraphvizView.doc, draftguitools.gui_annotationstyleeditor.AnnotationStyleEditor.doc, draftguitools.gui_base.GuiCommandSimplest.doc, ExpressionCompleterModel::Info.doc, WorkingPlane.Plane.doc, App::RelabelDocumentExpressionVisitor.doc, draftguitools.gui_base_original.DraftTool.doc, App::DynamicProperty::PropData.doc, draftguitools.gui_base.GuiCommandBase.doc, App::LinkBaseExtension::PropInfo.doc, ItemInfo.doc, ItemInfo2.doc, importIFClegacy.IfcEntity.doc, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, Gui::NavigationStyle.position, DraftVecUtils.rotate(), WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, draftguitools.gui_trackers.rectangleTracker.v, and WorkingPlane.Plane.weak.

Referenced by WorkingPlane.Plane.alignToFace(), WorkingPlane.Plane.setFront(), WorkingPlane.Plane.setSide(), WorkingPlane.Plane.setTop(), and WorkingPlane.Plane.setup().

◆ alignToPointAndAxis_SVG()

def WorkingPlane.Plane.alignToPointAndAxis_SVG	(	self,
		point,
		axis,
		offset = `0`
	)

Align the working plane to a point and an axis (vector).

It aligns `u` and `v` based on the magnitude of the components
of `axis`.
Also set `weak` to `False`.

Parameters
----------
point : Base::Vector3
    The new `position` of the plane, adjusted by
    the `offset`.
axis : Base::Vector3
    A vector whose unit vector will be used as the new `axis`
    of the plane.
    The magnitudes of the `x`, `y`, `z` components of the axis
    determine the orientation of `u` and `v` of the plane.
offset : float, optional
    Defaults to zero. A value which will be used to offset
    the plane in the direction of its `axis`.

Cases
-----
The `u` and `v` are always calculated the same

    * `u` is the cross product of the positive or negative of `axis`
      with a `reference vector`.
      ::
  u = [+1|-1] axis.cross(ref_vec)
    * `v` is `u` rotated 90 degrees around `axis`.

Whether the `axis` is positive or negative, and which reference
vector is used, depends on the absolute values of the `x`, `y`, `z`
components of the `axis` unit vector.

 #. If `x > y`, and `y > z`
     The reference vector is +Z
     ::
 u = -1 axis.cross(+Z)
 #. If `y > z`, and `z >= x`
     The reference vector is +X.
     ::
 u = -1 axis.cross(+X)
 #. If `y >= x`, and `x > z`
     The reference vector is +Z.
     ::
 u = +1 axis.cross(+Z)
 #. If `x > z`, and `z >= y`
     The reference vector is +Y.
     ::
 u = +1 axis.cross(+Y)
 #. If `z >= y`, and `y > x`
     The reference vector is +X.
     ::
 u = +1 axis.cross(+X)
 #. otherwise
     The reference vector is +Y.
     ::
 u = -1 axis.cross(+Y)

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, drafttests.test_pivy.DraftPivy.doc, drafttests.test_dxf.DraftDXF.doc, drafttests.test_modification.DraftModification.doc, drafttests.test_oca.DraftOCA.doc, drafttests.test_airfoildat.DraftAirfoilDAT.doc, drafttests.test_svg.DraftSVG.doc, drafttests.test_dwg.DraftDWG.doc, drafttests.test_creation.DraftCreation.doc, Gui::GraphvizView.doc, draftguitools.gui_annotationstyleeditor.AnnotationStyleEditor.doc, draftguitools.gui_base.GuiCommandSimplest.doc, ExpressionCompleterModel::Info.doc, WorkingPlane.Plane.doc, App::RelabelDocumentExpressionVisitor.doc, draftguitools.gui_base_original.DraftTool.doc, App::DynamicProperty::PropData.doc, draftguitools.gui_base.GuiCommandBase.doc, App::LinkBaseExtension::PropInfo.doc, ItemInfo.doc, ItemInfo2.doc, importIFClegacy.IfcEntity.doc, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, Gui::NavigationStyle.position, DraftVecUtils.rotate(), WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, draftguitools.gui_trackers.rectangleTracker.v, and WorkingPlane.Plane.weak.

◆ alignToSelection()

def WorkingPlane.Plane.alignToSelection	(	self,
		offset = `0`
	)

Align the plane to a selection if it defines a plane.

If the selection uniquely defines a plane it will be used.
Currently it only works with one object selected, a `'Face'`.
It extracts the shape of the object or subobject
and then calls `alignToFace(shape, offset)`.

This method only works when `FreeCAD.GuiUp` is `True`,
that is, when the graphical interface is loaded.

Parameter
---------
offset : float
    Defaults to zero. A value which will be used to offset
    the plane in the direction of its `axis`.

Returns
-------
bool
    `True` if the operation was successful, and `False` otherwise.
    It returns `False` if the selection has no elements,
    or if it has more than one element,
    or if the object is not derived from `'Part::Feature'`
    or if the object doesn't have a `Shape`.

To do
-----
The method returns `False` if the selection list has more than
one element.
The method should search the list for objects like faces, points,
edges, wires, etc., and call the appropriate aligning submethod.

The method could work for curves (`'Edge'`  or `'Wire'`) but
`alignToCurve()` isn't fully implemented.

When the interface is not loaded it should fail and print
a message, `FreeCAD.Console.PrintError()`.

See Also
--------
alignToFace, alignToCurve

References WorkingPlane.Plane.alignToCurve(), and WorkingPlane.Plane.alignToFace().

◆ copy()

def WorkingPlane.Plane.copy ( self )

Return a new plane that is a copy of the present object.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.plane, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, Gui::NavigationStyle.position, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

◆ getClosestAxis()

def WorkingPlane.Plane.getClosestAxis	(	self,
		point
	)

Return the closest axis of the plane to the given point (vector).

It tests the angle that the `point` vector makes with the unit vectors
`u`, `v`, and `axis`, as well their negatives.
The smallest angle indicates the closest axis.

Parameters
----------
point : Base::Vector3
    The external point to test.

Returns
-------
str
    * It is `'x'` if the closest axis is `u` or `-u`.
    * It is `'y'` if the closest axis is `v` or `-v`.
    * It is `'z'` if the closest axis is `axis` or `-axis`.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

◆ getDeviation()

def WorkingPlane.Plane.getDeviation ( self )

Return the angle between the u axis and the horizontal plane.

It defines a projection of `u` on the horizontal plane
(without a Z component), and then measures the angle between
this projection and `u`.

It also considers the cross product of the projection
and `u` to determine the sign of the angle.

Returns
-------
float
    Angle between the `u` vector, and a projected vector
    on the global horizontal plane.

See Also
--------
DraftVecUtils.angle

References DraftVecUtils.angle(), WorkingPlane.Plane.u, uvPtStruct.u, and draftguitools.gui_trackers.rectangleTracker.u.

◆ getGlobalCoords()

def WorkingPlane.Plane.getGlobalCoords	(	self,
		point
	)

Return the coordinates of the given point, added to the plane.

If the `point` was constructed using the plane as origin,
return the absolute coordinates from the `point`
to the global origin.

The `u`, `v`, and `axis` vectors scale the components of `point`,
and the result is added to the planes `position`.

Parameters
----------
point : Base::Vector3
    The external point.

Returns
-------
Base::Vector3
    The coordinates of the point from the absolute origin.

See Also
--------
getLocalCoords, getLocalRot, getGlobalRot

Notes
-----
The following graphic explains the coordinates.
::
                  g GlobalCoords (1, 11)
                  |
                  |
                  |
              (n) p point (1, 6)
                  | LocalCoords (1, 1)
                  |
    ----plane--------c-------- position (0, 5)

In the graphic

    * `p` is an arbitrary point, external to the plane
    * `c` is the plane's `position`
    * `g` is the global coordinates of `p` when added to the plane
    * `n` is the relative coordinates of `p` when referred to the plane

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, Gui::NavigationStyle.position, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

Referenced by WorkingPlane.Plane.projectPoint().

◆ getGlobalRot()

def WorkingPlane.Plane.getGlobalRot	(	self,
		point
	)

Like getGlobalCoords, but doesn't use the plane's position.

If the `point` was constructed using the plane as origin,
return the absolute coordinates from the `point`
to the global origin.
However, in this case, the plane is assumed to have its `position`
at the global origin, therefore, the returned coordinates
will only consider the orientation of the plane.

The `u`, `v`, and `axis` vectors scale the components of `point`.

Parameters
----------
point : Base::Vector3
    The external point.

Returns
-------
Base::Vector3
    The coordinates of the point from the absolute origin.

See Also
--------
getGlobalCoords, getLocalCoords, getLocalRot

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

Referenced by WorkingPlane.Plane.projectPoint().

◆ getLocalCoords()

def WorkingPlane.Plane.getLocalCoords	(	self,
		point
	)

Return the coordinates of the given point, from the plane.

If the `point` was constructed using the plane as origin,
return the relative coordinates from the `point` to the plane.

A vector is calculated from the plane's `position`
to the external `point`, and this vector is projected onto
each of the `u`, `v` and `axis` of the plane to determine
the local, relative vector.

Parameters
----------
point : Base::Vector3
    The point external to the plane.

Returns
-------
Base::Vector3
    The relative coordinates of the point from the plane.

See Also
--------
getGlobalCoords, getLocalRot, getGlobalRot

Notes
-----
The following graphic explains the coordinates.
::
                  g GlobalCoords (1, 11)
                  |
                  |
                  |
              (n) p point (1, 6)
                  | LocalCoords (1, 1)
                  |
    ----plane--------c-------- position (0, 5)

In the graphic

    * `p` is an arbitrary point, external to the plane
    * `c` is the plane's `position`
    * `g` is the global coordinates of `p` when added to the plane
    * `n` is the relative coordinates of `p` when referred to the plane

To do
-----
Maybe a better name would be getRelativeCoords?

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, Gui::NavigationStyle.position, DraftVecUtils.project(), WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< Rotation >.v, Base::vec_traits< SbColor >.v, Base::Vector2dPy.v, Base::vec_traits< App::Color >.v, WorkingPlane.Plane.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

Referenced by WorkingPlane.Plane.projectPoint().

◆ getLocalRot()

def WorkingPlane.Plane.getLocalRot	(	self,
		point
	)

Like getLocalCoords, but doesn't use the plane's position.

If the `point` was constructed using the plane as origin,
return the relative coordinates from the `point` to the plane.
However, in this case, the plane is assumed to have its `position`
at the global origin, therefore, the returned coordinates
will only consider the orientation of the plane.

The external `point` is a vector, which is projected onto
each of the `u`, `v` and `axis` of the plane to determine
the local, relative vector.

Parameters
----------
point : Base::Vector3
    The point external to the plane.

Returns
-------
Base::Vector3
    The relative coordinates of the point from the plane,
    if the plane had its `position` at the global origin.

See Also
--------
getLocalCoords, getGlobalCoords, getGlobalRot

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, DraftVecUtils.project(), WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

Referenced by WorkingPlane.Plane.projectPoint().

◆ getNormal()

def WorkingPlane.Plane.getNormal ( self )

Return the normal vector of the plane (axis).

Returns
-------
Base::Vector3
    The `axis` attribute of the plane.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, and Base::CoordinateSystem.axis.

◆ getPlacement()

def WorkingPlane.Plane.getPlacement	(	self,
		rotated = `False`
	)

Return the placement of the plane.

Parameters
----------
rotated : bool, optional
    It defaults to `False`. If it is `True`, it switches `axis`
    with `-v` to produce a rotated placement.

Returns
-------
Base::Placement
    A placement, comprised of a `Base` (`Base::Vector3`),
    and a `Rotation` (`Base::Rotation`).

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, Gui::NavigationStyle.position, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

◆ getRotation()

def WorkingPlane.Plane.getRotation ( self )

Return a placement describing the plane orientation only.

If `FreeCAD.GuiUp` is `True`, that is, if the graphical interface
is loaded, it will test if the active object is an `Arch` container
and will calculate the placement accordingly.

Returns
-------
Base::Placement
    A placement, comprised of a `Base` (`Base::Vector3`),
    and a `Rotation` (`Base::Rotation`).

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, DraftVecUtils.getPlaneRotation(), WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

◆ inverse()

def WorkingPlane.Plane.inverse ( self )

Invert the direction of the plane.

It inverts the `u` and `axis` vectors.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.u, uvPtStruct.u, and draftguitools.gui_trackers.rectangleTracker.u.

◆ isGlobal()

def WorkingPlane.Plane.isGlobal ( self )

Return True if the plane axes are equal to the global axes.

Return `False` if any of `u`, `v`, or `axis` does not correspond
to `+X`, `+Y`, or `+Z`, respectively.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

◆ isOrtho()

def WorkingPlane.Plane.isOrtho ( self )

Return True if the plane axes are orthogonal with the global axes.

Orthogonal means that the angle between `u` and the global axis `+Y`
is a multiple of 90 degrees, meaning 0, -90, 90, -180, 180,
-270, 270, or 360 degrees.
And similarly for `v` and `axis`.
All three axes should be orthogonal to the `+Y` axis.

Due to rounding errors, the angle difference is rounded
to 6 decimal digits to do the test.

Returns
-------
bool
    Returns `True` if all three `u`, `v`, and `axis`
    are orthogonal with the global axis `+Y`.
    Otherwise it returns `False`.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

◆ offsetToPoint()

def WorkingPlane.Plane.offsetToPoint	(	self,
		p,
		direction = `None`
	)

Return the signed distance from a point to the plane.

Parameters
----------
p : Base::Vector3
    The external point to consider.

direction : Base::Vector3, optional
    The unit vector that indicates the direction of the distance.

    It defaults to `None`, which then uses the `plane.axis` (normal)
    value, meaning that the measured distance is perpendicular
    to the plane.

Returns
-------
float
    The distance from the point to the plane.

Notes
-----
The signed distance `d`, from `p` to the plane, is such that
::
    x = p + d*direction,

where `x` is a point that lies on the plane.

The `direction` is a unit vector that specifies the direction
in which the distance is measured.
It defaults to `plane.axis`,
meaning that it is the perpendicular distance.

A picture will help explain the computation
::
                            p
                          //|
                        / / |
                    d /  /  | axis
                    /   /   |
                  /    /    |
    -------- plane -----x-----c-----a--------

The points are as follows

 * `p` is an arbitrary point outside the plane.
 * `c` is a known point on the plane,
   for example, `plane.position`.
 * `x` is the intercept on the plane from `p` in
   the desired `direction`.
 * `a` is the perpendicular intercept on the plane,
   i.e. along `plane.axis`.

The distance is calculated through the dot product
of the vector `pc` (going from point `p` to point `c`,
both of which are known) with the unit vector `direction`
(which is provided or defaults to `plane.axis`).
::
    d = pc . direction
    d = (c - p) . direction

**Warning:** this implementation doesn't calculate the entire
distance `|xp|`, only the distance `|pc|` projected onto `|xp|`.

Trigonometric relationships
---------------------------
In 2D the distances can be calculated by trigonometric relationships
::
    |ap| = |cp| cos(apc) = |xp| cos(apx)

Then the desired distance is `d = |xp|`
::
    |xp| = |cp| cos(apc) / cos(apx)

The cosines can be obtained from the definition of the dot product
::
    A . B = |A||B| cos(angleAB)

If one vector is a unit vector
::
    A . uB = |A| cos(angleAB)
    cp . axis = |cp| cos(apc)

and if both vectors are unit vectors
::
    uA . uB = cos(angleAB).
    direction . axis = cos(apx)

Then
::
    d = (cp . axis) / (direction . axis)

**Note:** for 2D these trigonometric operations
produce the full `|xp|` distance.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, and Gui::NavigationStyle.position.

Referenced by WorkingPlane.Plane.projectPointOld().

◆ projectPoint()

def WorkingPlane.Plane.projectPoint	(	self,
		p,
		direction = `None`
	)

Project a point onto the plane, by default orthogonally.

Parameters
----------
p : Base::Vector3
    The point to project.
direction : Base::Vector3, optional
    The unit vector that indicates the direction of projection.

    It defaults to `None`, which then uses the `plane.axis` (normal)
    value, meaning that the point is projected perpendicularly
    to the plane.

Returns
-------
Base::Vector3
    The projected vector, scaled to the appropriate distance.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.getGlobalCoords(), WorkingPlane.Plane.getGlobalRot(), WorkingPlane.Plane.getLocalCoords(), WorkingPlane.Plane.getLocalRot(), and DraftVecUtils.scaleTo().

◆ projectPointOld()

def WorkingPlane.Plane.projectPointOld	(	self,
		p,
		direction = `None`
	)

Project a point onto the plane. OBSOLETE.

Parameters
----------
p : Base::Vector3
    The point to project.
direction : Base::Vector3, optional
    The unit vector that indicates the direction of projection.

    It defaults to `None`, which then uses the `plane.axis` (normal)
    value, meaning that the point is projected perpendicularly
    to the plane.

Returns
-------
Base::Vector3
    The projected point,
    or the original point if the angle between the `direction`
    and the `plane.axis` is 90 degrees.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.offsetToPoint(), and DraftVecUtils.precision().

◆ reset()

def WorkingPlane.Plane.reset ( self )

Reset the plane.

Set the `doc` attribute to `None`, and `weak` to `True`.

References drafttests.test_pivy.DraftPivy.doc, drafttests.test_airfoildat.DraftAirfoilDAT.doc, drafttests.test_dxf.DraftDXF.doc, drafttests.test_modification.DraftModification.doc, drafttests.test_oca.DraftOCA.doc, drafttests.test_svg.DraftSVG.doc, drafttests.test_dwg.DraftDWG.doc, drafttests.test_creation.DraftCreation.doc, Gui::GraphvizView.doc, draftguitools.gui_annotationstyleeditor.AnnotationStyleEditor.doc, draftguitools.gui_base.GuiCommandSimplest.doc, ExpressionCompleterModel::Info.doc, WorkingPlane.Plane.doc, App::RelabelDocumentExpressionVisitor.doc, draftguitools.gui_base_original.DraftTool.doc, App::DynamicProperty::PropData.doc, draftguitools.gui_base.GuiCommandBase.doc, App::LinkBaseExtension::PropInfo.doc, ItemInfo.doc, ItemInfo2.doc, importIFClegacy.IfcEntity.doc, and WorkingPlane.Plane.weak.

◆ restore()

def WorkingPlane.Plane.restore ( self )

Restore the plane attributes that were saved.

Restores the attributes `u`, `v`, `axis`, `position` and `weak`
from `stored`, and set `stored` to `None`.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, Gui::NavigationStyle.position, WorkingPlane.Plane.stored, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< Rotation >.v, Base::vec_traits< SbColor >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, draftguitools.gui_trackers.rectangleTracker.v, and WorkingPlane.Plane.weak.

◆ save()

def WorkingPlane.Plane.save ( self )

Store the plane attributes.

Store `u`, `v`, `axis`, `position` and `weak`
in a list in `stored`.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, Gui::NavigationStyle.position, WorkingPlane.Plane.stored, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< Rotation >.v, Base::vec_traits< SbColor >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, draftguitools.gui_trackers.rectangleTracker.v, and WorkingPlane.Plane.weak.

Referenced by shipGZ.TaskPanel.TaskPanel.accept(), shipAreasCurve.TaskPanel.TaskPanel.accept(), shipHydrostatics.TaskPanel.TaskPanel.accept(), Mod.Show.mTempoVis.TempoVis.modify(), Mod.Show.mTempoVis.TempoVis.modifyVPProperty(), and Mod.Show.mTempoVis.TempoVis.saveCamera().

◆ setFromPlacement()

def WorkingPlane.Plane.setFromPlacement	(	self,
		pl,
		rebase = `False`
	)

Set the plane from a placement.

It normally uses only the rotation, unless `rebase` is `True`.

Parameters
----------
pl : Base::Placement or Base::Matrix4D
    A placement, comprised of a `Base` (`Base::Vector3`),
    and a `Rotation` (`Base::Rotation`),
    or a `Base::Matrix4D` that defines a placement.
rebase : bool, optional
    It defaults to `False`.
    If `True`, it will use `pl.Base` as the new `position`
    of the plane. Otherwise it will only consider `pl.Rotation`.

To do
-----
If `pl` is a `Base::Matrix4D`, it shouldn't try to use `pl.Base`
because a matrix has no `Base`.

References WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, WorkingPlane.Plane.position, Gui::FlagLayout::ItemWrapper.position, Gui::NavigationStyle.position, WorkingPlane.Plane.u, uvPtStruct.u, draftguitools.gui_trackers.rectangleTracker.u, Base::vec_traits< SbVec3f >.v, Base::vec_traits< SbVec3d >.v, Base::vec_traits< Vector3f >.v, Base::vec_traits< Vector3d >.v, Base::vec_traits< SbRotation >.v, Base::vec_traits< SbColor >.v, Base::vec_traits< Rotation >.v, Base::Vector2dPy.v, WorkingPlane.Plane.v, Base::vec_traits< App::Color >.v, Gui::ViewProviderIndex.v, uvPtStruct.v, and draftguitools.gui_trackers.rectangleTracker.v.

◆ setFront()

def WorkingPlane.Plane.setFront ( self )

sets the WP to front position and updates the GUI

References WorkingPlane.Plane.alignToPointAndAxis().

◆ setSide()

def WorkingPlane.Plane.setSide ( self )

sets the WP to top position and updates the GUI

References WorkingPlane.Plane.alignToPointAndAxis().

◆ setTop()

def WorkingPlane.Plane.setTop ( self )

sets the WP to top position and updates the GUI

References WorkingPlane.Plane.alignToPointAndAxis().

◆ setup()

def WorkingPlane.Plane.setup	(	self,
		direction = `None`,
		point = `None`,
		upvec = `None`,
		force = `False`
	)

Set up the working plane if it exists but is undefined.

If `direction` and `point` are present,
it calls `alignToPointAndAxis(point, direction, 0, upvec)`.

Otherwise, it gets the camera orientation to define
a working plane that is perpendicular to the current view,
centered at the origin, and with `v` pointing up on the screen.

This method only works when the `weak` attribute is `True`.
This method also sets `weak` to `True`.

This method only works when `FreeCAD.GuiUp` is `True`,
that is, when the graphical interface is loaded.
Otherwise it fails silently.

Parameters
----------
direction : Base::Vector3, optional
    It defaults to `None`. It is the new `axis` of the plane.
point : Base::Vector3, optional
    It defaults to `None`. It is the new `position` of the plane.
upvec : Base::Vector3, optional
    It defaults to `None`. It is the new `v` orientation of the plane.
force : Bool
    If True, it sets the plane even if the plane is not in weak mode

To do
-----
When the interface is not loaded it should fail and print
a message, `FreeCAD.Console.PrintError()`.

References WorkingPlane.Plane.alignToPointAndAxis(), WorkingPlane.Plane.axis, drafttaskpanels.task_circulararray.TaskPanelCircularArray.axis, Base::CoordinateSystem.axis, and WorkingPlane.Plane.weak.

Referenced by PathScripts.PathDressupHoldingTags.ObjectTagDressup.doExecute(), PathScripts.PathDressupDogbone.ObjectDressup.execute(), PathScripts.PathDressupHoldingTags.ObjectTagDressup.generateTags(), PathScripts.PathDressupHoldingTags.ObjectTagDressup.pointAtBottom(), PathScripts.PathDressupHoldingTags.ObjectTagDressup.pointIsOnPath(), PathScripts.PathDressupHoldingTags.ObjectTagDressup.setXyEnabled(), and PathScripts.PathDressupHoldingTags.ObjectTagDressup.supportsTagGeneration().

Member Data Documentation

◆ axis

WorkingPlane.Plane.axis

◆ doc

WorkingPlane.Plane.doc

◆ position

WorkingPlane.Plane.position

Referenced by WorkingPlane.Plane.alignToPointAndAxis(), WorkingPlane.Plane.alignToPointAndAxis_SVG(), WorkingPlane.Plane.copy(), ifc2x3.ifcsweptsurface.dim(), ifc2x3.ifcelementarysurface.dim(), WorkingPlane.Plane.getGlobalCoords(), WorkingPlane.Plane.getLocalCoords(), WorkingPlane.Plane.getPlacement(), WorkingPlane.Plane.offsetToPoint(), WorkingPlane.Plane.restore(), WorkingPlane.Plane.save(), and WorkingPlane.Plane.setFromPlacement().

◆ stored

WorkingPlane.Plane.stored

Referenced by WorkingPlane.Plane.restore(), and WorkingPlane.Plane.save().

◆ u

WorkingPlane.Plane.u

◆ v

WorkingPlane.Plane.v

◆ weak

WorkingPlane.Plane.weak

Referenced by WorkingPlane.Plane.alignToFace(), WorkingPlane.Plane.alignToPointAndAxis(), WorkingPlane.Plane.alignToPointAndAxis_SVG(), WorkingPlane.Plane.reset(), WorkingPlane.Plane.restore(), WorkingPlane.Plane.save(), and WorkingPlane.Plane.setup().

The documentation for this class was generated from the following file:

src/Mod/Draft/WorkingPlane.py

Public Member Functions

Public Attributes

Detailed Description

Member Function Documentation

◆ alignTo3Points()

◆ alignToCurve()

◆ alignToEdges()

◆ alignToFace()

◆ alignToPointAndAxis()

◆ alignToPointAndAxis_SVG()

◆ alignToSelection()

◆ copy()

◆ getClosestAxis()

◆ getDeviation()

◆ getGlobalCoords()

◆ getGlobalRot()

◆ getLocalCoords()

◆ getLocalRot()

◆ getNormal()

◆ getPlacement()

◆ getRotation()

◆ inverse()

◆ isGlobal()

◆ isOrtho()

◆ offsetToPoint()

◆ projectPoint()

◆ projectPointOld()

◆ reset()

◆ restore()

◆ save()

◆ setFromPlacement()

◆ setFront()

◆ setSide()

◆ setTop()

◆ setup()

Member Data Documentation

◆ axis

◆ doc

◆ position

◆ stored

◆ u

◆ v

◆ weak