TRTC – Matrix Transformations – Chapter 4

Compared to the previous chapter this was easier to deal with. In this chapter we could more like just to use the building blocks to create something useful. More like putting the pieces together rather than creating the actual pieces.

Different transformations are represented using different kind of matrices. Our starting point will be the identity matrix of size 4×4. And based on what kind of transformation we are trying to create we modify that identity matrix according to our needs. In this transformations the difference between our tuple if it’s a point (remember the 4th component the w = 1) or a vector (the 4th component aka the w = 0) will be crucial. Depending on the type of the tuple the matrix will affect the tuple differently.

Like in the previous chapter I won’t paste all the source code here. There is 19 different test cases along with all the implementation code so I try to focus on the turning points here. You will find the source code at gitlab.

Translation

Translation is operation that moves a point from one location to another and does that by shifting the x, y, z values. So first thing to do is to create a test case that checks if our translation works properly. There is three test cases for translation and here is the first one. Two other are quite similar.

The difference between vector and point is important here. We can translate point but we cannot translate vector. Since vector doesn’t know where it is in the first place there is no point to translate it somewhere else 🙂

/**
 Chapter 4.
 1st test case.
 */
func testMultipltyPointByTranslationMatrix() {
    // Given
    let transform = newRGTranslationMatrix(x: 5, y: -3, z: 2)
    // And
    let p = newRGPoint(x: -3, y: 4, z: 5)
    
    // When
    let tp = transform * p
    
    // Then
    XCTAssertEqual(tp.isEqualTo(newRGPoint(x: 2, y: 1, z: 7)), true)
}

Transformation matrices are very clear in a visual way and to implement them was very fun. For me it was easier to implement the translation matrix function when I put the skeleton of the matrix in to the comments. It kind of right away shows you what this matrix is all about.

To construct translation matrix we need three different values. One for each coordinate axe. Every value defines how much translation there will be along that coordinate axe. The implementation is simple. I use float3 as an input but I also created an alternative function that takes each value separately as input. That could be found in source code.

/**
 Generates new RGMatrix4x4 translation matrix.
 ````
 |0|1|2|3|   <- Columns
 ____________
 |1|0|0|x|
 |0|1|0|y|
 |0|0|1|z|
 |0|0|0|1|
 ````
 */
public func newRGTranslationMatrix(_ translation: float3) -> RGMatrix4x4 {
    var tM = RGMatrix4x4.identity()
    tM[3] = RGTuple(x: translation.x, y: translation.y, z: translation.z, w: 1.0)
    return tM
}

Scaling

What scaling matrix does it makes things bigger or smaller. And it does so by multiplying it’s targets coordinates along each coordinate axe. When scaling factor is > 1 then things get bigger and when it’s < 1 things get smaller. Scaling is something that applies to vectors as well as to points. Vectors gets longer or shorter when scaled.

Test case for scaling is as short as it was for translation. First we create a transformation and then a point. Then we multiply that point by the transformation to get a new transformed point. Last step is to check if the result is what it should be and the books tells us what to expect. So here is the test case.

/**
 Chapter 4.
 4th test case.
 Test multiplying point by scaling matrix.
 */
func testMultiplyPointByScalingMatrix() {
    // Given
    let transform = newRGScalingMatrix(x: 2, y: 3, z: 4)
    // And
    let p = newRGPoint(x: -4, y: 6, z: 8)
    
    // When
    let tp = transform * p
    
    // Then
    XCTAssertEqual(tp.isEqualTo(newRGPoint(x: -8, y: 18, z: 32)), true)
}

Implementation follows the same form for scaling as it was for translation. Input is three values for scaling like it was for translation. Their position inside the matrix is just different and thats why their effect is also different.

/**
 Generates new RGMatrix4x4 scaling matrix.
 ````
 |0|1|2|3|   <- Columns
 ____________
 |x|0|0|0|
 |0|y|0|0|
 |0|0|z|0|
 |0|0|0|1|
 ````
 Takes scaling farctor for each coordinate axe separately.
 */
public func newRGScalingMatrix(x: Float, y: Float, z: Float) -> RGMatrix4x4 {
    var sM = RGMatrix4x4.identity()
    
    sM[0].x = x
    sM[1].y = y
    sM[2].z = z
    
    return sM
}

Rotation

Rotation does exactly that. Rotates 🙂 Like the book says we are going to deal with the easier cases here the rotations around coordinate axes. We could also rotate around an arbitrary line but that is not covered here. All the rotations follows the same paradigm so I will put the code only for the first one here.

When rotating an object it has something to do with the angle. The angle defines how much we are rotating the object. The most common unit to define an angle is probably the degree where full circle is 360 degrees.

Specially with computers we often use radians as the unit for angels. Where the full circle is defined as 2π. So the degrees and radians are probably the most known units for angels.

Sidenote about angles

As a land surveyor (which was my first profession) I want to point out that there is other units to define an angle than radians and degrees. In landsureying the unit is often gon where the full circle is 400 gon. In military the milliradians are often used. There is different milliradians which slightly differs from each other. There is a NATO mils, Warsaw Pact mils andSwedish “streck” where the full circle is either 6400, 6000 or 6300 respectively.

Around X

Testin rotation includes two test the full quarter and half quarter. Again the test case code is quite clean and straightforward. The implementation in other hand is, well maybe not complicated but something you must be careful.

/**
 Chapter 4.
 8th test case.
 Test rotation around x-axis.
 */
func testRotationAroundX() {
    // Given
    let p = newRGPoint(x: 0, y: 1, z: 0)
    // and
    let halfQuarter = newRGRotationX(Float.pi / 4)
    // and
    let fullQuarter = newRGRotationX(Float.pi / 2)
    
    // When
    let halfRot = halfQuarter * p
    let fullRot = fullQuarter * p
    
    // Then
    XCTAssertEqual(halfRot.isEqualTo(newRGPoint(x: 0, y: Float(2.0).squareRoot()/2.0, z: Float(2.0).squareRoot() / 2.0 )), true)
    XCTAssertEqual(fullRot.isEqualTo(newRGPoint(x: 0, y: 0, z: 1)), true)
}

The implementation is not complicated but to make it work double check is needed. I missed to put minus sign in the right place and the test returned a red box in Xcode.

Around Y- and Z-axes

Rotating around Y and Z axes follows the same method as around X axe so those you can find from the source code. The position where the sin and cos values are places inside the matrix changes and here I show the skeletons.

/*
// Around Y
 |0|1|2|3|   - Columns
 ____________
 |cos(r) |0|sin(r)|0|
 |0      |1|     0|0|
 |-sin(r)|0|cos(r)|0|
 |      0|0|     0|1|
// Around Z
 |0|1|2|3|   - Columns
 ____________
 |cos(r) |-sin(r)|0|0|
 |sin(r) | cos(r)|0|0|
 |      0|      1|  0|
 |      0|      0|  1|
*/

Shearing

A shearing (or skew) transformation has the effect of making straight lines slanted.

Jamis Buck

In a way this is the most complex transformation. Basically because there is six different parameters for the function.

/**
 Chapter 4.
 12th test case.
 Test shearing x in propotion to y.
 */
func testShearingXInPropotionToY() {
    // Given
    let transform = newRGShearing(1, 0, 0, 0, 0, 0)
    
    // and
    let p = newRGPoint(x: 2, y: 3, z: 4)
    
    // When
    let sharedP = transform * p
    
    XCTAssertEqual(sharedP.isEqualTo(newRGPoint(x: 5, y: 3, z: 4)), true)
    
}

/**
 Generates new RGMatrix4x4 rotation matrix arond Y axis.
 ````
 |0 |1 |2 |3|   <- Columns
 ____________
 |1 |Xy|Xz|0|
 |Yz| 1|Yz|0|
 |Zx|Zy| 1|0|
 |0 | 0| 0|1|
 ````
 Takes rotation angle as radians.
 */
public func newRGShearing(_ Xy: Float, _ Xz: Float, _ Yx: Float, _ Yz: Float, _ Zx: Float, _ Zy: Float ) -> RGMatrix4x4 {
    var sherM = RGMatrix4x4.identity()
    
    sherM[0].y = Yx
    sherM[0].z = Zx
    sherM[1].x = Xy
    sherM[1].z = Zy
    sherM[2].x = Xz
    sherM[2].y = Yz
    
    return sherM
}

Chaining Transformations

In the previous post I mentioned that we could concatenate all the matrices by multiplying them together and the use that matrix to multiply our tuple to get the desired result at once. The thing we must be aware of is that the order which the multiplication is done is meaningful.

Note that the order of the multiplications is important! Matrix multiplication is associative, but not commutative.

Jamis Buck

So here is the second off the two tests cases what comes to chaining. This is actually the one that chains the transformations. The other calculates those separately. I think it’s fascinating that we could just calculate all our “transformation goals” together and then multiply the source to get the result. Even now when the test case does quite many things the code is short.

/**
 Chapter 4.
 19th test case.
 Test chained transfomations.
 */
func testChainedTransformations() {
    // Given
    let p = newRGPoint(x: 1, y: 0, z: 1)
    let A = newRGRotationX(Float.pi / 2)
    let B = newRGScalingMatrix(float3(x: 5, y: 5, z: 5))
    let C = newRGTranslationMatrix(x: 10, y: 5, z: 7)
    
    // When
    let T = C * B * A
    let pT = T * p

    // Then
    XCTAssertEqual(pT.isEqualTo(newRGPoint(x: 15, y: 0, z: 7)), true)
}

Putting it together

In this chapters “Putting it together” is cool. We could use all the building blocks created previously and create something…well not complex, but something that shows how practical our code created so far is. The result in this challenge is the image below. Twelve dots representing the twelve hours of clock face.

To produce the image above there is few steps to take but no too many. This is a good example that shows the power or the code created so far. Basically the code includes a creating a canvas. I made the canvas square since the clock face is usually square 🙂 Then there is the color we need for the dots. I choose green. Next step is to create point that represents the center of the canvas. This is a part that we could easily improve so that the canvas could have a method that returns its center, but I leave it for later.

To create 12 dots sounds like a loop so thats what I created. And in every iteration of the loop there is a new a dot created based on the new calculated position for the “base” point. Point is scaled, rotated and scaled to it’s position. The point is put to the canvas using the colour chosen earlier. At the end the canvas is saved to a file. I put the whole code here.

import Cocoa
import RGCore
import simd
/**
 The Ray Tracing Challenge
 Chapter 4 - Putting it together challend at the end of the chapter.
 Here we create clock face using point and transfomation matrices.
 */


// Create the canvas for the clock.
var c = newRGCanvas(width: 400, height: 400)


// I choose to use green as the color for the hours in clock face.
var clr = newRGColor(red: 0, green: 1.0, blue: 0)


// The center of the canvas.
let center = newRGPoint(x: 200, y: 200, z: 0)


// Twelve hours so we need a loop to create twelve points.
for i in 0..<12{
    // Point to start with.
    var p = newRGPoint(x: 0, y: 1, z: 0)

    // This moves the point to center.
    let T = newRGTranslationMatrix(x: center.x, y: center.y, z: center.z)
    
    // Scales the clock.
    let S = newRGScalingMatrix(float3(x: 100, y: 100, z: 0))
    
    // Size of the rotation per hour.
    let hourStep = Float.pi / Float(6)
    
    // This rotates the hours around the clock face.
    let R = newRGRotationZ(Float(i) * hourStep )
    
    // Calculates the position of the current hour on clock face.
    p = T * S * R * p
    
    // Gets the 2D position for canvas.
    let pos = p.getRGPosition()
    let pixelPosition = RGPosition(pos.x, pos.y)
    
    // Print the values so its easier to see what actually happens under cover.
    print(pixelPosition.description)
    
    // When we got the positon we write it into canvas.
    c.writePixelAt(pixelPosition, color: clr)
}


// Generates the ppm ASCII file string.
let ppmFile = canvasToPPMString(c)

// Write the clock face into the canvas.
let home = URL(fileURLWithPath: NSHomeDirectory())
let url = home.appendingPathComponent("Desktop/TRTC_Chapter4_Clock.ppm")
print(url)
do {
    try ppmFile.write(to: url, atomically: false, encoding: .utf8)
} catch {
    print(error)
}

For me this chapter was fun to do. So thank you Jamis for this journey so far 🙂 Next chapter opening says that “You’re all done with the foundational work,…” so I guess something new and interesting is to come.