public static class TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder extends Object
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[])
.
Constructor and Description |
---|
PerspectiveTransformationBuilder() |
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.
|
public ILcdModelModelTransformation build()
rotation
is optional.IllegalArgumentException
- if the mandatory parameters are not presentpublic TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder rotation(double[] aRotation)
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 posePerspective 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 bothYou 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 };
aRotation
- the 3 x 3 rotation matrix as array of doubles, ordered row-majorpublic TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder principalPoint(double aX, double aY)
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).
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)public TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder fov(double aHorizontalFov, double aVerticalFov)
horizontalFov(double)
and verticalFov(double)
.aHorizontalFov
- the horizontal field of view, in degreesaVerticalFov
- the vertical field of view, in degreespublic TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder horizontalFov(double aHorizontalFov)
This property has no default value and must be set either directly, or via the
aspect ratio or the image properties. See also build()
.
aHorizontalFov
- the horizontal field of view, in degreespublic TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder verticalFov(double aVerticalFov)
This property has no default value and must be set either directly, or via the
aspect ratio or the image properties. See also build()
.
aVerticalFov
- the vertical field of view, in degreespublic TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder aspectRatio(double aAspectRatio)
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()
.
aAspectRatio
- the aspect ratiopublic TLcdPanoramicTransformationFactory.PerspectiveTransformationBuilder fromImage(double aFocalLength, int aImageWidth, int aImageHeight, double aPixelWidth, double aPixelHeight)
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.
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)