Transform
=========

.. py:module:: rhino3dm

.. py:class:: Transform

   .. py:method:: Transform(diagonalValue)

      Initializes a new transform matrix with a specified value along the diagonal.

      :param float diagonalValue: Value to assign to all diagonal cells except M33 which is set to 1.0.

   .. py:method:: Transform()

      Transform constructor


   .. py:attribute:: IsAffine

      bool: Tests for an affine transformation.
      A transformation is affine if it is valid and its last row is [0, 0, 0, 1].
      An affine transformation can be broken into a linear transformation and a translation.

   .. py:attribute:: IsIdentity

      bool: Return True if this Transform is the identity transform

   .. py:attribute:: IsLinear

      bool: Tests for a linear transformation.
      A transformation is affine if it is valid and its last row is [0, 0, 0, 1].
      If in addition its last column is ( 0, 0, 0, 1)^T then it is linear.
      An affine transformation can be broken into a linear transformation and a translation.

   .. py:attribute:: IsRotation

      bool: Returns True if this is a proper rotation.

   .. py:attribute:: IsValid

      bool: Gets a value indicating whether or not this Transform is a valid matrix.
      A valid transform matrix is not allowed to have any invalid numbers.

   .. py:attribute:: IsZero

      bool: True if matrix is Zero4x4, ZeroTransformation, or some other type of
      zero. The value xform[3][3] can be anything.

   .. py:attribute:: IsZero4x4

      bool: True if all values are 0

   .. py:attribute:: IsZeroTransformation

      bool: True if all values are 0, except for M33 which is 1.

   .. py:attribute:: RigidType

      TransformRigidType: Gets a value indicating whether or not the Transform is rigid.
      A rigid transformation can be broken into  a proper rotation and a translation,
      while an isometry transformation could also include a reflection.

   .. py:attribute:: SimilarityType

      TransformSimilarityType: Gets a value indicating whether or not the Transform maintains similarity.
      The easiest way to think of Similarity is that any circle, when transformed,
      remains a circle. Whereas a non-similarity Transform deforms circles into ellipses.

   .. py:attribute:: M00

      float: Gets or sets this[0,0].

   .. py:attribute:: M01

      float: Gets or sets this[0,1].

   .. py:attribute:: M02

      float: Gets or sets this[0,2].

   .. py:attribute:: M03

      float: Gets or sets this[0,3].

   .. py:attribute:: M10

      float: Gets or sets this[1,0].

   .. py:attribute:: M11

      float: Gets or sets this[1,1].

   .. py:attribute:: M12

      float: Gets or sets this[1,2].

   .. py:attribute:: M13

      float: Gets or sets this[1,3].

   .. py:attribute:: M20

      float: Gets or sets this[2,0].

   .. py:attribute:: M21

      float: Gets or sets this[2,1].

   .. py:attribute:: M22

      float: Gets or sets this[2,2].

   .. py:attribute:: M23

      float: Gets or sets this[2,3].

   .. py:attribute:: M30

      float: Gets or sets this[3,0].

   .. py:attribute:: M31

      float: Gets or sets this[3,1].

   .. py:attribute:: M32

      float: Gets or sets this[3,2].

   .. py:attribute:: M33

      float: Gets or sets this[3,3].

   .. py:staticmethod:: Identity()

      [todo] add documentation

   .. py:staticmethod:: ZeroTransformation()

      [todo] add documentation

   .. py:staticmethod:: Unset()

      [todo] add documentation

   .. py:staticmethod:: Translation(motion)

      Constructs a new translation (move) transformation.

      :param rhino3dm.Vector3d motion: Translation (motion) vector.

      :return: A transform matrix which moves geometry along the motion vector.

      :rtype: Transform

   .. py:staticmethod:: Translation(x, y, z)

      Constructs a new translation (move) transformation.

      :return: A transform matrix which moves geometry along the motion vector.

      :rtype: Transform

   .. py:staticmethod:: Scale(anchor, scaleFactor)

      Constructs a new uniform scaling transformation with a specified scaling anchor point.

      :param rhino3dm.Point3d anchor: Defines the anchor point of the scaling operation.
      :param float scaleFactor: Scaling factor in all directions.

      :return: A transform matrix which scales geometry uniformly around the anchor point.

      :rtype: Transform

   .. py:staticmethod:: Scale(plane, xScaleFactor, yScaleFactor, zScaleFactor)

      Constructs a new uniform scaling transformation with a specified scaling anchor point.

      :return: A transform matrix which scales geometry uniformly around the anchor point.

      :rtype: Transform

   .. py:staticmethod:: Rotation(angleRadians, rotationAxis, rotationCenter)

      Constructs a new rotation transformation with specified angle, rotation center and rotation axis.

      :param float sinAngle: Sine of the rotation angle.
      :param float cosAngle: Cosine of the rotation angle.
      :param rhino3dm.Vector3d rotationAxis: 3D unit axis of rotation.
      :param rhino3dm.Point3d rotationCenter: 3D center of rotation.

      :return: A rotation transformation matrix.

      :rtype: Transform

   .. py:staticmethod:: Rotation(startDirection, endDirection, rotationCenter)

      Constructs a new rotation transformation with specified angle, rotation center and rotation axis.

      :param float sinAngle: Sine of the rotation angle.
      :param float cosAngle: Cosine of the rotation angle.
      :param rhino3dm.Vector3d rotationAxis: 3D unit axis of rotation.
      :param rhino3dm.Point3d rotationCenter: 3D center of rotation.

      :return: A rotation transformation matrix.

      :rtype: Transform

   .. py:staticmethod:: Mirror(pointOnMirrorPlane, normalToMirrorPlane)

      Create mirror transformation matrix
      The mirror transform maps a point Q to
      Q - (2*(Q-P)oN)*N, where
      P = pointOnMirrorPlane and N = normalToMirrorPlane.

      :param rhino3dm.Point3d pointOnMirrorPlane: Point on the mirror plane.
      :param rhino3dm.Vector3d normalToMirrorPlane: Normal vector to the mirror plane.

      :return: A transformation matrix which mirrors geometry in a specified plane.

      :rtype: Transform

   .. py:staticmethod:: Mirror(mirrorPlane)

      Create mirror transformation matrix
      The mirror transform maps a point Q to
      Q - (2*(Q-P)oN)*N, where
      P = pointOnMirrorPlane and N = normalToMirrorPlane.

      :param rhino3dm.Point3d pointOnMirrorPlane: Point on the mirror plane.
      :param rhino3dm.Vector3d normalToMirrorPlane: Normal vector to the mirror plane.

      :return: A transformation matrix which mirrors geometry in a specified plane.

      :rtype: Transform

   .. py:staticmethod:: PlaneToPlane(plane0, plane1)

      Create a rotation transformation that orients plane0 to plane1. If you want to orient objects from
      one plane to another, use this form of transformation.

      :param rhino3dm.Plane plane0: The plane to orient from.
      :param rhino3dm.Plane plane1: the plane to orient to.

      :return: The translation transformation if successful, Transform.Unset on failure.

      :rtype: Transform

   .. py:staticmethod:: Shear(plane, x, y, z)

      Constructs a Shear transformation.

      :param rhino3dm.Plane plane: Base plane for shear.
      :param rhino3dm.Vector3d x: Shearing vector along plane x-axis.
      :param rhino3dm.Vector3d y: Shearing vector along plane y-axis.
      :param rhino3dm.Vector3d z: Shearing vector along plane z-axis.

      :return: A transformation matrix which shear geometry.

      :rtype: Transform

   .. py:staticmethod:: Multiply(a, b)

      Multiplies (combines) two transformations.
      This is the same as the * operator between two transformations.

      :param Transform a: First transformation.
      :param Transform b: Second transformation.

      :return: A transformation matrix that combines the effect of both input transformations. \
         The resulting Transform gives the same result as though you'd first apply B then A.

      :rtype: Transform

   .. py:method:: Determinant()

      [todo] add documentation

   .. py:method:: TryGetInverse()

      Attempts to get the inverse transform of this transform.


      :return: tuple (bool, Transform)

         - True on success. \
           If False is returned and this Transform is Invalid, inserveTransform will be set to this Transform. \
           If False is returned and this Transform is Valid, inverseTransform will be set to a pseudo inverse. \
         - The inverse transform. This out reference will be assigned during this call. \

      :rtype: (bool, Transform)

   .. py:method:: TransformBoundingBox(bbox)

      Computes a new bounding box that is the smallest axis aligned
      bounding box that contains the transformed result of its 8 original corner
      points.

      :return: A new bounding box.

      :rtype: rhino3dm.BoundingBox

   .. py:method:: Transpose()

      Flip row/column values


      :rtype: Transform

   .. py:method:: ToFloatArray()

      Return the matrix as a linear array of 16 float values.

      :param bool rowDominant: If true, returns { M00, M01, M02...}. \
         If false, returns { M00, M10, M20...}.

      :return: An array of 16 floats.

      :rtype: float[]
