picometer.shapes
================

.. py:module:: picometer.shapes


Attributes
----------

.. autoapisummary::

   picometer.shapes.logger
   picometer.shapes.Vector3
   picometer.shapes.Versor3
   picometer.shapes.zero3


Classes
-------

.. autoapisummary::

   picometer.shapes.AtomSet
   picometer.shapes.Shape
   picometer.shapes.ExplicitShape
   picometer.shapes.Line
   picometer.shapes.Plane


Functions
---------

.. autoapisummary::

   picometer.shapes.are_parallel
   picometer.shapes.are_synparallel
   picometer.shapes.are_antiparallel
   picometer.shapes.are_perpendicular
   picometer.shapes.versorize
   picometer.shapes.degrees_between


Module Contents
---------------

.. py:data:: logger

.. py:data:: Vector3

.. py:data:: Versor3

.. py:data:: zero3
   :type:  Vector3

.. py:class:: AtomSet

   Bases: :py:obj:`Protocol`


   Base class for protocol classes.

   Protocol classes are defined as::

       class Proto(Protocol):
           def meth(self) -> int:
               ...

   Such classes are primarily used with static type checkers that recognize
   structural subtyping (static duck-typing), for example::

       class C:
           def meth(self) -> int:
               return 0

       def func(x: Proto) -> int:
           return x.meth()

       func(C())  # Passes static type check

   See PEP 544 for details. Protocol classes decorated with
   @typing.runtime_checkable act as simple-minded runtime protocols that check
   only the presence of given attributes, ignoring their type signatures.
   Protocol classes can be generic, they are defined as::

       class GenProto(Protocol[T]):
           def meth(self) -> T:
               ...


   .. py:attribute:: cart_xyz
      :type:  numpy.ndarray


.. py:function:: are_parallel(v: Vector3, w: Vector3) -> bool

   Check if input vectors point along the same line in any direction


.. py:function:: are_synparallel(v: Vector3, w: Vector3) -> bool

   Check if input vectors point along the same line in the same direction


.. py:function:: are_antiparallel(v: Vector3, w: Vector3) -> bool

   Check if input vectors point along the same line in opposite directions


.. py:function:: are_perpendicular(v: Vector3, w: Vector3) -> bool

   Check in input vectors are perpendicular


.. py:function:: versorize(v: Vector3) -> Versor3

   Normalize and choose lexicographically-larger of antiparallel v and -v


.. py:function:: degrees_between(v: Vector3, w: Vector3, normalize: bool = False) -> float

   Calculate angle between two vectors in degrees


.. py:class:: Shape

   .. py:class:: Kind

      Bases: :py:obj:`enum.Enum`


      Generic enumeration.

      Derive from this class to define new enumerations.


      .. py:attribute:: axial
         :value: 1



      .. py:attribute:: planar
         :value: 2



      .. py:attribute:: spatial
         :value: 3




   .. py:attribute:: kind
      :type:  Shape.Kind


   .. py:attribute:: direction
      :type:  Versor3


   .. py:attribute:: origin
      :type:  Vector3


   .. py:method:: __repr__()


   .. py:method:: at(origin: Vector3) -> Shape

      Return a copy of self with centroid at new origin



   .. py:method:: _distance(other: Shape) -> float
      :abstractmethod:



   .. py:method:: distance(other: Shape) -> float

      Delegated to a concrete implementation.
      Since self.kind >= other.kind, concrete implementations need only
      to handle shapes of equal of lower kind.



   .. py:method:: _angle(other: Shape) -> float
      :abstractmethod:



   .. py:method:: angle(*others: Shape) -> float

      Delegated to a concrete implementation.
      For Explicit shape, accept two parameters; for AtomSets, any size.



.. py:class:: ExplicitShape(direction: Vector3, origin: Vector3 = zero3)

   Bases: :py:obj:`Shape`, :py:obj:`abc.ABC`


   Helper class that provides a standard way to create an ABC using
   inheritance.


   .. py:property:: direction
      :type: Versor3



   .. py:attribute:: origin


   .. py:method:: _angle(*others: Shape) -> float


.. py:class:: Line(direction: Vector3, origin: Vector3 = zero3)

   Bases: :py:obj:`ExplicitShape`


   Helper class that provides a standard way to create an ABC using
   inheritance.


   .. py:attribute:: kind


   .. py:method:: _distance(other: Line)


.. py:class:: Plane(direction: Vector3, origin: Vector3 = zero3)

   Bases: :py:obj:`ExplicitShape`


   Helper class that provides a standard way to create an ABC using
   inheritance.


   .. py:attribute:: kind


   .. py:method:: _distance(other: Union[Line, Plane]) -> float