#7: Image Graph Transformations
===============================

Image Graph Transformations
***************************

The Image Graph provides transformations to further customize the image
projection in the plot widget. These options can be accessed by the following
actions:

1. Go to design mode
2. Right-click the image widget
3. Hover "Image Graph: Properties"
4. Select "Transformations"

The transformation dialog will then appear:

.. figure:: images/transforms_dialog.png
   :align: center
   :alt: Transformations Dialog
   :figclass: align-center

   Transformations Dialog


The following values can be set:

1. **Scale** - dictates the ratio of the pixel dimensions to its plotted value.
2. **Offset** - sets the starting value of the image for each axis
3. **Aspect Ratio** - describes the width and height proportion of the image.

   - "None" will auto-fit the image in the given space

     .. figure:: images/transforms_aspect_none.png
        :align: center
        :alt: Aspect Ratio: None
        :figclass: align-center

        Aspect Ratio: None

   - "Pixel-dependent" will respect the image dimensions.

     This is the most common aspect ratio as it does not modify the appearance
     of the received image data.

     For instance, a ``100 x 150`` image will still have ``1:1.5`` ratio
     regardless of input scale.

     .. figure:: images/transforms_aspect_pixel.png
        :align: center
        :alt: Aspect Ratio: Pixel-dependent
        :figclass: align-center

        Aspect Ratio: Pixel-dependent

   - "Scale-dependent" will apply the ratio on the image.

     This is a more advanced aspect ratio as it modifies the appearance of the
     image heavily with the input scale.

     For instance, a ``100 x 150`` image will be stretched to satisfy the
     input scale of  ``1:3``.

     .. figure:: images/transforms_aspect_scale.png
        :align: center
        :alt: Aspect Ratio: Scale-dependent
        :figclass: align-center

        Aspect Ratio: Scale-dependent


The default value is ``1:1`` scale with no offsets and uses the pixel-dependent
aspect ratio. The scale legend can also be toggled from the dialog.


Use Case: Changing y-axis to mm-scale
*************************************

A user wants to change the **y-axis** of an image to **mm-scale**,
with a **1 pixel : 3 mm ratio**. He also wants to **adjust the image
proportions to the new scale**. Then the following can be done:


**1. Rename the axis to units of interest (in this case, mm)**

a. Go to design mode
b. Right-click the image widget
c. Hover "Image Graph: Properties"
d. Select "Axes Labels"

.. figure:: images/transforms_usecase_1.png
   :align: center
   :alt: Changing y-axis units
   :figclass: align-center


**2. Set the transformation factor.**

a. Open the "Transformations" dialog.
b. Set the y-axis scale to ``3``
c. Set the aspect ratio to ``Scale-dependent``. This is to adjust the image
   proportions.

.. figure:: images/transforms_usecase_2.png
   :align: center
   :alt: Setting the image transformations
   :figclass: align-center


The following image widget is now:

.. figure:: images/transforms_usecase_3.png
   :align: center
   :alt: The resulting image widget
   :figclass: align-center