Package com.luciad.panorama.transformation

Class TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder

java.lang.Object
com.luciad.panorama.transformation.TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder
Enclosing class:
TLcdPanoramicTransformationFactory
public static class TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder extends 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[]).

pinhole
Since:
2020.1

  • Constructor Details

    • PerspectiveTransformationBuilder

      public PerspectiveTransformationBuilder()

  • Method Details

    • build

      public ILcdModelModelTransformation build()
      Build the perspective transformation with this builder's current parameters.
      Returns:
      a new transformation for this builder's current parameters
      Throws:
      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.
 
      
 
      
   pinhole pose
 
      
 
      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.

      principal point

      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.

      horizontal fov

      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.

      vertical fov

      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.

      aspect ratio

      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.

      image parameters

      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