com.luciad.panorama.transformation

Advanced Raster ConnectorsClass TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder

java.lang.Object

com.luciad.panorama.transformation.TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder

Enclosing class:

TLcdPanoramicTransformationFactory

public static class TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder
extends java.lang.Object

Builder for a ILcdModelModelTransformations that transform 3D reference CS points to 2D image CS points for perspective camera images ("pinhole images").

By default, this transformation expects that the image axes X and Y map to the world axes X and Y, and that the center of the image points to -Z. You can change this by specifying a rotation(double[]).

Since:

2020.1

Constructor Summary

Constructors

Constructor and Description
PerspectiveTransformationBuilder()

Method Summary

Modifier and Type	Method and Description
TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder	aspectRatio(double aAspectRatio) Set the aspect ratio width:height of the image.
ILcdModelModelTransformation	build() Build the perspective transformation with this builder's current parameters.
TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder	fov(double aHorizontalFov, double aVerticalFov) Set the horizontal and vertical field of view values.
TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder	fromImage(double aFocalLength, int aImageWidth, int aImageHeight, double aPixelWidth, double aPixelHeight) Get the perspective camera parameters from image properties.
TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder	horizontalFov(double aHorizontalFov) Set the horizontal field of view value.
TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder	principalPoint(double aX, double aY) Set the 2D image coordinates of the principal point.
TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder	rotation(double[] aRotation) Set the 3 x 3 rotation matrix for the transformation.
TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder	verticalFov(double aVerticalFov) Set the vertical field of view value.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

PerspectiveTransformationBuilder

public PerspectiveTransformationBuilder()

Method Detail

build

public ILcdModelModelTransformation build()

Build the perspective transformation with this builder's current parameters.

• The parameters that must be set, are either:
  • field of view: horizontal and vertical, or either one of these and aspect ratio
  • image: fromImage(...)
• The rotation is optional.

Returns:

a new transformation for this builder's current parameters

Throws:

java.lang.IllegalArgumentException - if the mandatory parameters are not present

rotation

public TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder rotation(double[] aRotation)

Set the 3 x 3 rotation matrix for the transformation.

By default, this transformation expects that the image axes X and Y map to the world axes X and Y, and that the center of the image points to -Z. As such, the default value for this property is the identity matrix.

The rotation matrix describes how the 3D camera CS is rotated relative to the reference CS. It is provided as a row-major array of doubles:

     [ m11, m12, m13,
       m21, m22, m23,
       m31, m32, m33 ]
   
 

 

   You can use this rotation to orient your image in the world.
 
 

   
 
 
Examples
 

   Example 1: image axes are different from the expected defaults
   

     Often, image formats will use a different axis alignment than what this perspective transformation expects.
     

     The easiest way to rectify this is by swapping the input axes so they map on the expected axes.
     This example keeps X, but maps Y onto Z, and Z onto -Y.
     This is the same as rotating 90 degrees clockwise around X.
   
   
     double[] axisSwapMatrix = new double[] {
        1,  0, 0,
        0,  0, 1,
        0, -1, 0,
     };
   
   Example 2: using a quaternion pose
   

     Perspective image can be taken at any angle in 3D.  Some formats offer these angles as a quaternion.
   
   
       Matrix3d poseMatrix = new Matrix3d();
       poseMatrix.set(new Quat4d(rot));
   
   
Example 3: applying a heading
   

       Sometimes, the center of the image is defined by a heading azimuth (degrees, clockwise starting north).
       This can be applied by rotating around the Z axis.
   
   
       Matrix3d headingMatrix = new Matrix3d();
       headingMatrix.rotZ(Math.toRadians(-heading));
   
   Example 4: combination of both
   

   You can combine the two operations by multiplying the matrices into one.
   
   
       Matrix3d combinedMatrix = new Matrix3d();
       combinedMatrix.setIdentity();
       combinedMatrix.mul(axisSwapMatrix);
       combinedMatrix.mul(poseMatrix);

       double[] combinedMatrixDoubles = new double[]{
           combinedMatrix.m00, combinedMatrix.m01, combinedMatrix.m02,
           combinedMatrix.m10, combinedMatrix.m11, combinedMatrix.m12,
           combinedMatrix.m20, combinedMatrix.m21, combinedMatrix.m22
       };
   
 

Parameters:

aRotation - the 3 x 3 rotation matrix as array of doubles, ordered row-major

Returns:

this builder

principalPoint

public TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder principalPoint(double aX,
                                                                                          double aY)

Set the 2D image coordinates of the principal point.

The principal point is the point on the image that is the closest to the camera's projection center, or in other words, the point where the Z axis of the camera CS intersects the image plane.

Note that the point is expressed in terms of the 2D image CS, in the range (0.0,0.0) to (1.0,1.0). See TLcdPanoramicTransformationFactory.

The default value for this property is (0.5,0.5).

Parameters:

aX - the x coordinate of the principal point in the range (0.0-1.0)

aY - the y coordinate of the principal point in the range (0.0-1.0)

Returns:

this builder

fov

public TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder fov(double aHorizontalFov,
                                                                               double aVerticalFov)

Set the horizontal and vertical field of view values. See horizontalFov(double) and verticalFov(double).

Parameters:

aHorizontalFov - the horizontal field of view, in degrees

aVerticalFov - the vertical field of view, in degrees

Returns:

this builder

horizontalFov

public TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder horizontalFov(double aHorizontalFov)

Set the horizontal field of view value.

This property has no default value and must be set either directly, or via the aspect ratio or the image properties. See also build().

Parameters:

aHorizontalFov - the horizontal field of view, in degrees

Returns:

this builder

verticalFov

public TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder verticalFov(double aVerticalFov)

Set the vertical field of view value.

This property has no default value and must be set either directly, or via the aspect ratio or the image properties. See also build().

Parameters:

aVerticalFov - the vertical field of view, in degrees

Returns:

this builder

aspectRatio

public TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder aspectRatio(double aAspectRatio)

Set the aspect ratio width:height of the image.

This property is used to calculate either the horizontal or vertical field of view value if only one of them is provided. It has no default value. See build().

Parameters:

aAspectRatio - the aspect ratio

Returns:

this builder

fromImage

public TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder fromImage(double aFocalLength,
                                                                                     int aImageWidth,
                                                                                     int aImageHeight,
                                                                                     double aPixelWidth,
                                                                                     double aPixelHeight)

Get the perspective camera parameters from image properties.

The focal length and pixel size parameters are expressed in the reference CS's unit of measurement (most likely, that will be meters).
The image size parameters are expressed in number of pixels.

Parameters:

aFocalLength - the camera's focal length (in the reference CS's unit of measurement)

aImageWidth - the width of the image (in pixels)

aImageHeight - the height of the image (in pixels)

aPixelWidth - the width of a single pixel (in the reference CS's unit of measurement)

aPixelHeight - the height of a single pixel (in the reference CS's unit of measurement)

Returns:

this builder