.. meta::
    :description: Code snippets transform StructuredGrid

Getting the transform of a StructuredGrid
=========================================

Representation of transformations as matrix
-------------------------------------------

The location and orientation of a :class:`ORSModel.ors.StructuredGrid`, representing his coordinate system,
are expressed as an affine transformation in an instance of *Matrix4x4*.

The representation of a *Matrix4x4* instance is::

    orsMatrix(v00, v01, v02, v03,
              v10, v11, v12, v13,
              v20, v21, v22, v23,
              v30, v31, v32, v33)

This matrix is used to represent the affine transformation
to go from the coordinate system `A` to the coordinate system `B`
as a 3x3 rotation and scale matrix (identified as ``R_A_to_B``) and a 3x1 translation vector
(identified as ``T_A_to_B``)::

    M_A_to_B = orsMatrix(r00, r01, r02, tx,
                         r10, r11, r12, ty,
                         r20, r21, r22, tz,
                           0,   0,   0,  1)

             = [[.     .      .]   [     .      ]
                [.  R_A_to_B  .]   [  T_A_to_B  ]
                [.     .      .]   [     .      ]

                [0     0      0]   [     1      ]]

A vector ``v_A`` expressed in the coordinate system `A` can be transformed in the coordinate system `B`
by a matrix product of the 3x3 rotation and scale matrix ``R_A_to_B``::

    v_B = R_A_to_B * v_A

        = [r00  r01  r02] [v0]
          [r10  r11  r12] [v1]
          [r20  r21  r22] [v2]

        = [r00*v0 + r01*v1 + r02*v2]
          [r10*v0 + r11*v1 + r12*v2]
          [r20*v0 + r21*v1 + r22*v2]

Similarly, a coordinate ``c_A`` expressed in the coordinate system `A` can be transformed in the coordinate system `B`
by a matrix product of the 3x3 rotation and scale matrix ``R_A_to_B``
and adding the 3x1 translation vector ``T_A_to_B``::

    c_B = R_A_to_B * c_A + T_A_to_B

        = [r00  r01  r02] [c0]   [tx]
          [r10  r11  r12] [c1] + [ty]
          [r20  r21  r22] [c2]   [tz]

        = [r00*c0 + r01*c1 + r02*c2 + tx]
          [r10*c0 + r11*c1 + r12*c2 + ty]
          [r20*c0 + r21*c1 + r22*c2 + tz]

For an instance of *StructuredGrid*, this transformation matrix is contained in a *Box* instance::

    aBox = aStructuredGrid.getBox()

The method :meth:`ORSModel.ors.Box.getWorldTranformation` gives the transformation to go
from the coordinate system of the current box to the world coordinate system::

    transformationMatrixFromLocalToWorld = aBox.getWorldTranformation()

.. _codeSnippetsTransformationConstructedStructuredGrid:

Transformations of a constructed StructuredGrid
-----------------------------------------------

Let's examine the transformation matrix of an instance ROI, being a subclass of StructuredGrid,
as changes in the coordinate system are made::

    from ORSModel import ROI, Matrix4x4, orsColor, orsVect

    aROI = ROI()
    aROI.setTitle('Demo ROI')

    # Setting the size
    aROI.setXSize(100)
    aROI.setYSize(200)
    aROI.setZSize(400)
    aROI.setTSize(1)

    # Observation of the current transformation
    aROI.getBox().getWorldTranformation()
    # orsMatrix(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1)  # Unit matrix

    # Setting the voxel dimensions
    aROI.setXSpacing(0.001)
    aROI.setYSpacing(0.010)
    aROI.setZSpacing(0.100)

    # Observation of the current transformation
    aROI.getBox().getWorldTranformation()
    # orsMatrix(0.001, 0, 0, 0, 0, 0.01, 0, 0, 0, 0, 0.1, 0, 0, 0, 0, 1)  # Notice the scaling factors in r00, r11 and r22

    # Setting the orientation using the Box member of the StructuredGrid
    # The original orientation (aligned with the world) is turned 30 degrees around the y axis.
    rotationAxis = orsVect(0, 1, 0)
    rotationTransform = Matrix4x4()
    rotationTransform.setAsRotation(rotationAxis, 3.1416/6)
    aROIBox = aROI.getBox()
    aROIBox.transform(rotationTransform)
    aROI.setBox(aROIBox)

    # Observation of the current transformation
    aROI.getBox().getWorldTranformation()
    # orsMatrix(0.000866024792, 0, 0.050000106, 0, 0, 0.01, 0, 0, -0.00050000106, 0, 0.0866024792, 0, 0, 0, 0, 1)

    # The origin is put at the world coordinate (2, 0, 0)
    aROI.setOrigin(orsVect(2, 0, 0))

    # Observation of the current transformation
    aROI.getBox().getWorldTranformation()
    # orsMatrix(0.000866024792, 0, 0.050000106, 2, 0, 0.01, 0, 0, -0.00050000106, 0, 0.0866024792, 0, 0, 0, 0, 1)  # Notice tx is now 2.0

    # Setting a color
    aROI.setInitialColor(orsColor(1, 0, 0, 1))

    # Filling the ROI by inverting the empty ROI (to see something in the views)
    aROI.getReversed(aROI)

    # Publish it so that it will be visible in the Object properties list
    aROI.publish()