[Bug or By-Design?] Vector3D.transformBy and Vector2D.transformBy ignore translation part of the transformation matrix

[nnikbin]

It seems that the Vector3D.transformBy and Vector2D.transformBy methods are not taking into account the translation component of the transformation matrix.

For example, I expected that by running the following code, the vector2D would become [10, 20], and the vector3D would become [10, 20, 30]. However, they actually become [10, 0] and [10, 20, 0] respectively (please view the image).

import adsk.core, traceback

def run(context):
    ui = None
    try:
        app = adsk.core.Application.get()
        ui  = app.userInterface
        
        #----- 2D -----
        
        vector2D = adsk.core.Vector2D.create(10, 0)
        translation2D = adsk.core.Vector2D.create(0, 20)
        
        matrix2D = adsk.core.Matrix2D.create()
        matrix2D.translation = translation2D

        success = vector2D.transformBy(matrix2D)
        ui.messageBox(f"Vector2D x: {vector2D.x}, y: {vector2D.y}, Success: {success}")

        #----- 3D -----

        vector3D = adsk.core.Vector3D.create(10, 20, 0)
        translation3D = adsk.core.Vector3D.create(0, 0, 30)
        
        matrix3D = adsk.core.Matrix3D.create()
        matrix3D.translation = translation3D

        success = vector3D.transformBy(matrix3D)
        ui.messageBox(f"Vector3D x: {vector3D.x}, y: {vector3D.y}, z: {vector3D.z}, Success: {success}")

    except:
        if ui:
            ui.messageBox('Failed:\n{}'.format(traceback.format_exc()))

Is this behaviour a bug or by-design? It is interesting that the  Autodesk Inventor API behaves the same way.

If it is by-design, I think it would be a good practice to have the documentation inform users about it.

[BrianEkins · Accepted solution]

This is correct. A vector doesn't have a position but only defines a direction and magnitude. As a result, transforming it with a matrix that only defines a translation doesn't result in any change. If that transform defined a rotation or scale, you would see a different vector because you're changing the direction and magnitude.

Think of a vector as defining a delta change. For example, the vector (1, 2, 3) defines moving something 1 unit in the X, 2 units in the Y, and 3 units in the Z. It doesn't matter where the thing you're moving exists in space; the vector defines a relative change from its current position.

[nnikbin]

Thank you @BrianEkins for your reply.

As you know, we can also define a vector by its endpoint. By this definition, we can consider transforming the vector as transforming its endpoint. I believe this is the most popular approach when defining transformations for vectors in 3D graphics. I can't recall any other APIs, except for Fusion 360 and Inventor, that provide a transformation operation for vectors while ignoring the translation component.

Perhaps one advantage of this approach is that we can consider the transformation as a pure [4x4] matrix multiplication.

I think that when we have "asPoint", "add" and "subtract" methods for the vector data structure, it would be more consistent to also take into account the translation part of the transformation matrix. Otherwise, to avoid any confusion, it's better to clearly explain this behavior in the documentation.

[BrianEkins]

There isn't a way to define a vector by an endpoint because a vector doesn't have the concept of a point or position; it only defines a direction and magnitude. Maybe you're thinking of the vectorTo method of the Point object. That creates a vector that defines the direction and distance between two points, but it doesn't have a position. 

There is another concept of a "ray," which is the combination of a point and a vector. The API doesn't have an object type for a ray. You can see an example of this in the findBRepUsingRay method that takes in a point and vector.

[nnikbin]

Thank you @BrianEkins for your reply.

I know a vector do not have the concept of a point or position. And by "we can also define a vector by its endpoint" I do not refer to the context of Fusion 360 API. I mean in general there is a one-to-one relationship between 2d and 3d points and 2d and 3d vectors because we can define both as xi + yj (+ zk). And in general 2d and 3d point sets can be considered as sets in 2d and 3d vector spaces.

I think it is the reason that even in some other programs (like 3ds Max) vectors and points are interchangable and there is no extra data structure for a vector.

From 3ds Max API documentation:

// Multiplying a Vector by a Matrix

// One thing that can be done is to multiply a vector (Point3) by a matrix (Matrix3).
// This results in a new vector as a result.
// This is often used to transform vectors from one coordinate space to another.
// There is a global function in the SDK that does this.

Point3 VectorTransform(constMatrix3& M, const Point3& V);
// Transform the vector (Point3) with the specified matrix.

I believe some users, like me, expect the results of the following lines to be the same.

vector3D.asPoint.transformBy(matrix3D)
vector3D.transformBy(matrix3D).asPoint

[nnikbin]

I think ultimately, this subject comes back to our definition of a transformation on a vector and answering the question that the translation of a vector is "meaningless" or is "identity transformation" or is "addition transformation". 

If we want to define a transformation according to an affine transformation in vector space, I think we can take into account the translation component.

[BrianEkins · Accepted solution]

You can see here that there is also disagreement in the math world about vectors and points.

https://math.stackexchange.com/questions/645672/what-is-the-difference-between-a-point-and-a-vector

For me, it's much clearer to visualize them as two different things that have different purposes. A point is a position in space, and a vector defines a displacement in space. 

[nnikbin]

Thank you, @BrianEkins , for providing the informative link and expressing your opinion.

Personally, I prefer to consider a point as a vector in 3D space, and I believe if the API treats them the same and provides affine transformations for vectors, it makes life easier by eliminating the need for conversion back and forth between them.

[nnikbin]

Perhaps because of this controversy and the way some other programs, such as 3ds Max, treat vectors, it would be beneficial to include additional details about vector transformation in API documents.

Personally, it took me some time to corner a bug in my program and discover that the misbehavior of my program was due to the fact that when transforming a vector with a matrix in Fusion 360 API, the translation part is ignored.

[BrianEkins]

If you transform a point, the translation portion of the matrix will be applied to the point. That makes sense because the point has a position and can be moved. A vector doesn't have a position, so translation has no effect.

[nnikbin]

Dear @BrianEkins , I completely understand your point.

The confusing aspect for me is that we use the term "transformation" with two different implementations in the API.

For points, we can consider transformation as a [4x4]*[4x1] matrix multiplication which is something we are familiar with.

But for vectors, we either use [3x3] matrix multiplication with [3x1] vectors while passing a [4x4] matrix to the transformBy method, or we use [4x4] # [4x1], where '#' is not multiplication but it is an operator that does not obey some properties of linear algebra. For example if A # b is equal to b for every vector b, we can not conclude that A is identity matrix.

Or perhaps we can consider vectors as [4x1] vectors with the last element equal to 0 (instead of 1) which nullifies the effect of the translation component.

So I believe that it deserves some clarification in the documents.