=======================
Point (hwx.common.math)
=======================

A mathematical representation of a point in 3D space.

--------------
Public Methods
--------------

  +----------------------------------------------------+
  | static planeFromPoints_ (pt1, pt2, pt3)            |
  +----------------------------------------------------+
  | along_ (self, towards, distance)                   |
  +----------------------------------------------------+
  | distance_ (self, x, y=None, z=None)                |
  +----------------------------------------------------+
  | distanceTo_ (self, x, y=None, z=None)              |
  +----------------------------------------------------+
  | distanceToPlane_ (self, a, b=None, c=None, d=None) |
  +----------------------------------------------------+
  | midpt_ (self, x, y=None, z=None)                   |
  +----------------------------------------------------+

--------------
Method Details
--------------

.. _planeFromPoints:
.. staticmethod:: planeFromPoints(pt1, pt2, pt3)

Computes the plane defined by the three points.

:param pt1: The first point.
:type pt1: Point
:param pt2: The second point.
:type pt2: Point
:param pt3: The third point.
:type pt3: Point

:returns: The constants of the a parametric plane equation.
:rtype: tuple


.. _along:
.. method:: along(self, towards, distance)

Computes the point along the line segment.

Defined by self and 'towards', at 'distance' from self.

:param towards: The end point.
:type towards: Point
:param distance: The distance from the Point defined in self.
:type distance: float

:returns: The newly created point.
:rtype: Point


.. _distance:
.. method:: distance(self, x, y=None, z=None)

Computes the distance to the point defined by x, y, z.

If y is None, x is assumed to be a point (or list).

:param x: The x coordinate or a point.
:type x: Union[float, list[float], Point]
:param y: The y coordinate.
:type y: float
:param z: The z coordinate.
:type z: float

:returns: The distance.
:rtype: float


.. _distanceTo:
.. method:: distanceTo(self, x, y=None, z=None)

Computes the distance to the point defined by x, y, z.

If y is None, x is assumed to be a point (or list).

:param x: The x coordinate or a point.
:type x: Union[float, list[float], Point]
:param y: The y coordinate.
:type y: float
:param z: The z coordinate.
:type z: float

:returns: The distance.
:rtype: float


.. _distanceToPlane:
.. method:: distanceToPlane(self, a, b=None, c=None, d=None)

Computes the distance to the parametric plane.

The parametric plane is given by the equation is ax + by + cz + d = 0.

If b is None, a is assumed to be a list.

:param a: The constant 'a' or a list of all constants.
:type a: Union[float, list, list[float]]
:param b: The constant 'b'.
:type b: float
:param c: The constant 'c'.
:type c: float
:param d: The constant 'd'.
:type d: float

:returns: The distance.
:rtype: float


.. _midpt:
.. method:: midpt(self, x, y=None, z=None)

Computes the middle point of the line segment between self and the point
defined by x, y, z.

If y is None, x is assumed to be a Point (or list).

:param x: The x coordinate or a Point.
:type x: Union[float, Point, list[float]]
:param y: The y coordinate.
:type y: float
:param z: The z coordinate.
:type z: float

:returns: The middle point.
:rtype: Point