1. Creating Vector and Matrix objects:

Vector objects in the nuke.math module are convenience classes that store a set of attributes (x,y for a Vector2; x,y,z for a Vector3; x,y,z,w for a Vector4) and provide specific methods for each class to perform common vector operations (vector length, normalize, distance between vectors, dot product...)
Matrix objects can be either of the Matrix3 or Matrix4 kind. Matrix3 defines a 3x3 transformation matrix, which can describe a translation, rotation and scale transforms. Matrix4 holds a 4x4 transformation matrix, most commonly used to represent perspective transforms.
First, let's have a look at how to create new objects/instances of those classes. It's a good habit to check the documentation of any new Python class/method we want to use. So, let's pull the help for the Vector3 Class, for example:

help(nuke.math.Vector3)

And look under its constructor method, to see how an instance of the Vector2 class can be initialized (the constructor is the protected method called __init__):

| __init__(...)
|····· __init__( (object)arg1) -> None :
|····· ...
|····· __init__( (object)arg1, (float)arg2, (float)arg3, (float)arg4) -> None :
|····· ...
|····· __init__( (object)arg1, (Vector3)arg2) -> None :
|····· ...

This is telling us there's 3 ways a Vector3 object can be constructed. If you ignore the first argument (object)arg1, which is just the object we're constructing or 'self', we are left with the following three possible syntaxes to create a new a Vector3. I'll use the Vector3 Class as an example to explain the different ways to create one, but the same methods apply to Vector2 and Vector4 classes. They also apply to Matrix classes, with a small exception that will be covered later.

Creating a new Vector3 instance with no arguments:

Syntax: v = nuke.math.Vector3()

This will create a Vector3 object with NON INITIALIZED values. The values/attributes of a Vector3 object are the x,y,z coordinates. Constructing a Vector 3 this way does NOT set x,y and z to 0. The short explanation is that the whole nuke.math is just a hook to the C++ Vector and Matrix Classes, and in C++, a variable that's not been initialized will be assigned a space in memory, but that space will not be set to any given value until the variable is initialized. So, until then, the value will be unpredictable (it will be the value previously stored at that memory position).

Let's see this in a practical example:

1
2
3
4
5

v1 = nuke.math.Vector3()
v2 = nuke.math.Vector3()
print v1, v2
 
# Result: {1.79998e-37, 1.78e-37, 2.73861e-26} {0, 3.7807e-11, 0}

See how both new Vector3 instances have different values assigned to their x,y and z attributes. This is because they were not initialized in the constructor. You could easily fix that by using the 'set' method available for all Vector instances.
Like this:

1
2
3
4
5

v1 = nuke.math.Vector3()
v1.set(1,2,3)
print v1
 
# Result: {1,2,3}

So, generally, make sure you only use this method when you know you're going to need a Vector3, don't know what x, y and z values it needs to have yet, but you will set them yourself later.
Otherwise, if you want to avoid unexpected behaviour from non-initialized attributes, give the initial values yourself when creating a new Vector instance, as explained in the following method.

Creating a new Vector3 instance directly setting its arguments:

Syntax: v = nuke.math.Vector3(float, float, float)

This will create a Vector3 object with its 3 attributes (x, y and z) initialized to the value of our choice.
Example:

1
2
3
4

v1 = nuke.math.Vector3(1, 2, 3)
print v1
 
# Result: {1, 2, 3}

Creating a new Vector3 instance from an existing Vector3:

Syntax: v = nuke.math.Vector3(nuke.math.Vector3)

The following code will create a new Vector3 instance (v2) taking the values from an existing instance of the same class (v1)

1
2
3
4
5

v1 = nuke.math.Vector3(0,0,0)
v2 = nuke.math.Vector2(v1)
print v1, v2
 
#Result: {0, 0, 0} {0, 0, 0}

Why would we want to do this, and not just do v2 = v1?

Well, we could, but then we would have two variables referencing the same Vector3 instance. This is because instances (objects) of the Classes defined in the nuke.math module are mutable objects, and therefore work in a similar way to python lists (which are also a mutable type, unlike numbers, strings or tuples) in that they can be modified 'in place'. Another important implication of this is the way we can copy a Vector or Matrix instance into a new variable/instance.
Because this will become important later on when explaining some of the Vector and Matrix methods, let me open a parenthesis and show some of the differences between mutable and immutable types using some of the Python built-in types as an example. If you are already familiar with these concepts, feel free to skip the following framed section:

1
2
3
4
5
6

a = 3
b = a
a += 1
print a, b
 
#Result: 4, 3

1
2
3
4
5
6

a = [1, 2, 3]
b = a
a.append(4)
print a, b
 
# Result: [1, 2, 3, 4] [1, 2, 3, 4]   #  both a and b are still pointing to the same list

So, the method described above allows us to make a fully independent copy of an existing Vector3. If we had attempted to create v2 with just a simple assignment, here's what would have happened:

1
2
3
4
5
6

v1 = nuke.math.Vector3(0,0,0)
v2 = v1
v2.set(1,2,3)
print v1, v2
 
# Result: {1,2,3} {1,2,3} (v1 and v2 are actually pointing to the same Vector3 instance)

Keep this in mind every time you want to have a copy of your Vector or Matrix objects without altering the original.

Creating Matrix3 and Matrix4 objects:

Creating Matrix objects works the same way as creating Vector objects. The constructor also has the three different variants explained before, except in the case of the Matrix4 class. Matrix4 objects hold the definition of a 4x4 matrix, which is a total of 16 float attributes.
Problem is, the nuke.math module was written using Boost.Python, which has a limit of 15 arguments that can be passed to a function. For that reason, you cannot create a new Matrix4 instance by dirtectly passing it all its values. However, there's ways to work around that. Here's an example on how we can create a Matrix4 with all 16 values, having them stored in a list.

1
2
3
4
5
6
7

matrixValues = [3039.75, 176.404, 0.155272, 0.155268, -124.794, 2800.11, -0.121872, -0.121869, -547.587, -1113.77, -0.980346, -0.980326, 4755.08, 509.823, 8.00838, 8.20822]
myMatrix = nuke.math.Matrix4()
for val in matrixValues:
myMatrix[matrixValues.index(val)] = val
print myMatrix
 
# Result: {3039.75, 176.404, 0.155272, 0.155268, -124.794, 2800.11, -0.121872, -0.121869, -547.587, -1113.77, -0.980346, -0.980326, 4755.08, 509.823, 8.00838, 8.20822}

The code above is creating a new, empy Matrix4 instance (with no initialized values). Then we iterate over each value in our list and assign it to the same index of our Matrix4 instance. Like lists, Matrix4 objects can be treated as an array of values, and we can make assignments to single indices of that array. (ex. myMatrix[3] = 0.0).


Additionally, the nukescripts.snap3d module (Nuke 6.1 only)  offers a very convenient function to create a Matrix4 from the knob values of any camera in Nuke. It takes a camera node object as the only argument (we could use the selected node, or nuke.toNode(nodename) to access a camera by name, or any other function that returns a camera node object). The function returns a Matrix4 object. Here's an example where we can create a Matrix4 object out of a selected camera node in Nuke, and assign it to a variable called myMatrix:

myMatrix = nukescripts.snap3d.cameraProjectionMatrix(nuke.selectedNode())