Package com.luciad.panorama.transformation

Class TLcdPanoramicTransformationFactory.SphericalTransformationBuilder

java.lang.Object
com.luciad.panorama.transformation.TLcdPanoramicTransformationFactory.SphericalTransformationBuilder
Enclosing class:
TLcdPanoramicTransformationFactory
public static class TLcdPanoramicTransformationFactory.SphericalTransformationBuilder extends Object
Builder for a ILcdModelModelTransformations that transform 3D reference CS points to 2D image CS points for spherical camera images ("equirectangular images").

By default, this transformation expects the center of the image to point to east (X) and the top of the image up (Z). You can change this by specifying a rotation(double[]).

spherical
Since:
2020.1

  • Constructor Details

    • SphericalTransformationBuilder

      public SphericalTransformationBuilder()

  • Method Details

    • build

      public ILcdModelModelTransformation build()
      Build the perspective transformation with this builder's current parameters.

      All parameters are optional, defaulting to these values:

      Returns:
      a new transformation for this builder's current parameters

    • rotation

      public TLcdPanoramicTransformationFactory.SphericalTransformationBuilder rotation(double[] aRotation)
      Set the 3 x 3 rotation matrix for the transformation.

      By default, this transformation expects the center of the image to point to east (X) and the top of the image up (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 ]

      spherical pose

      Examples

      You can use this rotation to orient your image in the world. Example 1: input image center is pointing north

      Often, equirectangular/spherical images are defined so that the center of the image is looking north/Y. As this spherical transformation expects the center to look east/Z, you need to apply a rotation.

      You can view this best as swapping the original axes with the desired axes. In this case, mapping X onto -Y, and Y onto X. You can also view this as rotating by 90 degrees counter-clockwise around the Z axis. 

             double[] axisSwapMatrix = new double[] {
           0, -1, 0,
           1,  0, 0,
           0,  0, 1
       };
      Example 2: input image center is pointing to a specific heading

      The center of the image might not be pointing north, but in a specific heading derived from GPS or sensor information.
      If you have heading information in the form an azimuth (degrees, clockwise starting north), you can apply a rotation around Z. 

             Matrix3d headingMatrix = new Matrix3d();
       headingMatrix.rotZ(Math.toRadians(-heading));
      Example 3: 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(headingMatrix);

       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

    • fov

      public TLcdPanoramicTransformationFactory.SphericalTransformationBuilder 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.SphericalTransformationBuilder horizontalFov(double aHorizontalFov)
      Set the horizontal field of view value.

      horizontal fov

      The default value for this property is 360°. See also build().

      Parameters:
      aHorizontalFov - the horizontal field of view, in degrees
      Returns:
      this builder

    • verticalFov

      public TLcdPanoramicTransformationFactory.SphericalTransformationBuilder verticalFov(double aVerticalFov)
      Set the vertical field of view value.

      vertical fov

      The default value for this property is 180°. See also build().

      Parameters:
      aVerticalFov - the vertical field of view, in degrees
      Returns:
      this builder

    • aspectRatio

      public TLcdPanoramicTransformationFactory.SphericalTransformationBuilder 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

    • principalPoint

      public TLcdPanoramicTransformationFactory.SphericalTransformationBuilder principalPoint(double aPrincipalX, double aPrincipalY)
      Set the x and y coordinates of the image's principal point.

      The principal point is the point on the image where the X 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:
      aPrincipalX - the x coordinate of the image's principal point
      aPrincipalY - the y coordinate of the image's principal point
      Returns:
      this builder

    • fromImage

      public TLcdPanoramicTransformationFactory.SphericalTransformationBuilder fromImage(int aImageWidth, int aImageHeight, double aPixelWidth, double aPixelHeight)
      Get the spherical camera parameters from image properties.

      image parameters

      The pixel size parameters are expressed in radians.
      The image size parameters are expressed in number of pixels.

      Parameters:
      aImageWidth - the width of the image (in pixels)
      aImageHeight - the height of the image (in pixels)
      aPixelWidth - the width of a single pixel (in radians)
      aPixelHeight - the height of a single pixel (in radians)
      Returns:
      this builder