Perspective transform🔗

Calculates a coordinate frame (homography) that maps a quadrilateral defined by the corner points points1 into a quadrilateral defined by the corner points points2 in projective geometry.

If we denote the coordinate frame by f$Ff$, a point in points1 as f$P_1f$ (in homogeneous coordinates, f$[x y 0 1]f$), a point in points2 as f$P_2f$ and the perspective projection function by f$p()f$, the following holds: f$P_2 = p(FP_1)f$.

Both point sets are assumed to represent the corners of the same quardilateral seen from two different angles of view. As the points lie on the XY-planes of their coordinate systems, the Z-coordinates are zero.

  • The first point determines the origin.

  • The second point determines the direction of X-axis.

  • The third point determines the corner diagonally opposite to the origin.

  • The fourth point determines the direction of Y-axis.

Since the Y axis usually points downwards, this means that the points should be entered clockwise, starting from the origin.

The usual use case for this tool is to find out the position of a camera with respect to a known rectangular object. This happens by entering the known world coordinates into points1 and the corresponding (X, Y) coordinates in the camera coordinate system to points2. If the camera has not been calibrated and positioned, the (X, Y) coordinates are the same in the default world coordinate system. Note that these are different from pixel coordinates.

The frame output can be connected to ReplaceCoordinateFrameTool to set a new world coordinate system to an image. Since the new coordinate frame is not expressed in the world coordinates of the input image but in its camera coordinate system, the referenceFrame input must be set to Camera. The world coordinate system of the image output will be aligned according to points1, but the pixels of the image will remain the same.

If one needs an actual projected image in analysis, the image output of ReplaceCoordinateFrameTool can be connected to ProjectToVirtualViewTool. If the size output from this tool is used as the size input to the ProjectToVirtualViewTool, the result contains just the specified area, projected to a rectangular image array.


  • points1: Four 2D corner points in the first view. Usually, these are known world coordinates.

  • points2: The corresponding corner points in the second view. Usually, these are coordinates in the camera coordinate system. Outputs

  • frame: A coordinate frame that maps points1 to points2 in projective geometry.

  • size: The size of the area in frame.