vecmath.mkdown

title: Vector Math in OpenStructure

[TOC]

# Vector Math in OpenStructure

## Vector Math

OpenStructure has built-in support for vectors in 2,3 and 4 dimension. They are called
'Vec2', 'Vec3' and 'Vec4' respectively. You can use the vector classes like in a math formula:
You can add them together, multiply them by scalar values or calculate the inner and outer
product. This short code snippet gives an idea of how you can use vectors.

    :::python
    a=geom.Vec2(1,0)
    b=geom.Vec2(0,1)
    # print the vectors
    print a,b

Here is another example:

    :::python
    # create a new vector by using components of both a and b.
    # The components of a vector can be accessed by using the 
    # array subscript notation:
    c=geom.Vec2(a[0],b[1])
    # print length of vector a and b
    print geom.Length(a), geom.Length(b)

    # calculate dot (inner) product
    print geom.Dot(a,b)

    # do some fancy calculation
    d = a+2*b
    print '%s+2*%s is %s' % (a,b,d)
   
In the same tokens, you can use 3 and 4-dimensional vectors. If you want to
calculate the angle between two vectors, you can use the properties of the
inner product: Calculating the inner product of two unit-length vectors is
identical to the cosine of the angle between the two vectors. But the 'geom'
library also offers a function to directly compute the Angle between two vectors.
Here are examples of both approaches:

    :::python 
    # the standard python math module defines the pi constant and the acos function
    import math
    angle= math.acos(geom.Normalize(c),geom.Normalize(d))*180.0/math.pi
    # computing the angle using the geom.Angle function
    angle2=geom.Angle(c,d)

## Linear Transforms

Linear transforms, such as scaling and rotation of vectors, can be achieved easily.

### Rotation

Rotations are usually carried out using quaternions or rotation matrices. There
are several helper classes in OpenStructure that encapsulate the logic of rotation.The
'Rotation3' class represents a rotation in 3D space defined by 3 Euler angles. Please
notice that although the class requires to be initialized with radiants, one can use
the Units function to express the value using any homogenous unit (for example, degrees)
and the conversion will be done automatically. The Units function is available in all OpenStructure modules.

    :::python
    # define rotation around x axis by 180 degrees (PI radians)
    rot=geom.Rotation3(math.pi,0,0)
    # define the same rotation explicitly using radiant units
    # this is equivalent to the line above
    rot=geom.Rotation3(math.pi*Units.rad,0,0)
    # define the same rotation using angle units (again equivalent)
    rot=geom.Rotation3(180.0*Units.deg,0,0)
    rot=geom.Rotation3(math.pi)
    # define the same rotation using the Units 
    v=geom.Vec3(0,1,0)
    # rotate v by rot
    print rot.GetRotationMatrix()*v

In two dimensions, the 'Rotate' function can be used to rotate a vector by a certain amount

    :::python
    #rotate by 90 degrees (PI/2 radians)
    print geom.Rotate(geom.Vec2(1,0),math.pi/2)


### Scaling

Uniform vector scaling can be accomplished by multiplication of the vector by a
scalar factor. For non-uniform scaling you can use a 3x3 matrix with all but the
main diagonal elements set to zero.

    :::python
    scale=geom.Mat3(1.0,0.0,0.0,
                    0.0,2.0,0.0,
                    0.0,0.0,4.0)

    print scale*geom.Vec3(1,1,1)