Rotating, translating, and scaling the coordinate space

Rotate, Translate, and Scale are context instructions that are applied to the vertex instructions, which are displayed in the coordinate space. They could bring unexpected results if we forget that the coordinate space is shared among all widgets, and it occupies the size of the window (actually bigger than that because there is no restriction on the coordinates and we can draw outside the window). First, we are going to understand the behavior of this instruction in this section and, in the next section, we can analyze the problems they bring in a deeper way, and learn techniques to make things easier.

Let's start with the new drawing.kv code:

114. # File name: drawing.kv (Rotate, Translate and Scale)
115. <DrawingSpace>:
116.    pos_hint: {'x':.5, 'y':.5}
117.    canvas:
118.        Rectangle:
119.            source: 'kivy.png'
120.        Rotate:
121.            angle: 90
122.            axis: 0,0,1
123.        Color:
124.            rgb: 1,0,0 # Red color
125.        Rectangle:
126.            source: 'kivy.png'
127.        Translate:
128.             x: -100
129.         Color:
130.             rgb: 0,1,0 # Green color
131.         Rectangle:
132.             source: 'kivy.png'
133.         Translate:
134.             y: -100
135.         Scale:
136.             xyz:(.5,.5,0)
137.         Color:
138.             rgb: 0,0,1 # Blue color
139.         Rectangle:
140.             source: 'kivy.png'

In this code, the first thing we did is position the coordinates (0, 0) of DrawingSpace (RelativeLayout) in the center of the screen (line 116). We created Rectangle with the kivi.png figure, which we had previously modified to indicate the original x axis and y axis.

The result is presented in the top-right of the following screenshot (executed with python drawing.py --size=200x200):

Rotate, Translate and Scale

In the line 120, we applied the Rotate instruction by 90° on the z axis (line 122). The value is (x, y, z), which means we can use any vector in the 3D space. Think of this as nailing a pin to the bottom-left corner of DrawingSpace, which we then rotate in the counter clockwise direction.

Tip

By default, the pin nail of the rotation is always the coordinates (0, 0) but we can alter this behavior with the origin property.

The top-left section of the screenshot ("Rotate, Translate, and Scale") shows the result after the rotation. We drew the same rectangle with red color (using the rgb property instead of the rgba property) to highlight it. After adding a rotation to the coordinate space context, we also modified the relative X-axis and Y-axis. Line 128 considers that the axes are rotated, and in order to translate the coordinate space down (usually Y-axis), it sets -100px to the X-axis. We drew the same Rectangle with green Color in the bottom left corner. Notice that the image still rotates and it will rotate as long as we don't bring the coordinate space context to its original angle.

Tip

Context instructions are persistent until we change them back again. Another way to avoid this is working inside RelativeLayout. If you remember from the previous chapter, it allows us to work with coordinates relative to the widget.

To scale or zoom out the image, we translated the coordinate space context (line 133) to use the bottom-right section of the screenshot. Notice that we use the Y-axis instead of the X-axis, since the context is still rotated. The scaling is done in line 135, where the image will be reduced to half the width and half the height. The Scale instruction reduces towards the (0, 0) coordinate, which initially is at the bottom-left corner. However, after all these modifications of the context, we need to think where this coordinate is. First, we rotated the axis (line 120) so the X-axis is vertical and the Y-axis is horizontal. After translating the coordinate space down (line 127) and then right (line 133), the (0, 0) coordinate is in the bottom-right corner with the X-axis being the vertical one and the Y-axis being the horizontal one.

Note

Scale uses proportions to the current size of the coordinate space context and not the original size. For example, to recover the original size, we should use xyz: (2,2,0) and not just xyz: (1,1,0).

So far, in this chapter, we have discussed that a Canvas instance is a set of instructions that contains context instructions and vertex instructions. The context instructions apply changes (colors or transformation) to the coordinate space context that affects the conditions in which the vertex instructions are displayed in the coordinate space.

We will use some of the knowledge to add Stickman to our project in the next and final section of this chapter. We will introduce two important context instructions to deal with the issues of sharing the same coordinate space between widgets: PushMatrix and PopMatrix.