Package com.irurueta.geometry

Class PinholeCameraIntrinsicParameters

java.lang.Object
com.irurueta.geometry.PinholeCameraIntrinsicParameters
All Implemented Interfaces:
Serializable
public class PinholeCameraIntrinsicParameters extends Object implements Serializable
This class defines intrinsic parameters of a pinhole camera. Extrinsic parameters on a pinhole camera are those external to the camera such as rotation and translation, whereas intrinsic parameters are more related to the inner workings of a camera. Intrinsic parameters are those such as horizontal/vertical focal length, skewness of axes or principal point of an image (which is usually related to lens/sensor slanting).
See Also:

  • Field Details

    • INTRINSIC_MATRIX_ROWS

      public static final int INTRINSIC_MATRIX_ROWS
      Constant defining the required number of rows of an intrinsic parameters matrix.
      See Also:

    • INTRINSIC_MATRIX_COLS

      public static final int INTRINSIC_MATRIX_COLS
      Constant defining the required number of columns of an intrinsic parameters matrix.
      See Also:

    • DEFAULT_VALID_THRESHOLD

      public static final double DEFAULT_VALID_THRESHOLD
      Threshold to determine whether a given intrinsic parameters matrix is valid (is upper triangular).
      See Also:

    • internalMatrix

      private com.irurueta.algebra.Matrix internalMatrix
      Internal matrix defining the intrinsic parameters of a camera.

  • Constructor Details

    • PinholeCameraIntrinsicParameters

      public PinholeCameraIntrinsicParameters()
      Constructor. Creates canonical intrinsic parameters which has no effect on projected 3D points into 2D points.

    • PinholeCameraIntrinsicParameters

      public PinholeCameraIntrinsicParameters(PinholeCameraIntrinsicParameters params)
      Creates a copy of provided intrinsic parameters.
      Parameters:
      params - Intrinsic parameters to be copied.

    • PinholeCameraIntrinsicParameters

      public PinholeCameraIntrinsicParameters(com.irurueta.algebra.Matrix internalMatrix) throws InvalidPinholeCameraIntrinsicParametersException
      Creates a new instance of camera intrinsic parameters using provided matrix. Provided matrix must be 3x3 and upper triangular. Note: this constructor will attempt to normalize provided matrix, hence its values might change after calling this constructor.
      Parameters:
      internalMatrix - Provided 3x3 and upper triangular matrix
      Throws:
      InvalidPinholeCameraIntrinsicParametersException - thrown if provided matrix is not 3x3 or upper triangular.

    • PinholeCameraIntrinsicParameters

      public PinholeCameraIntrinsicParameters(com.irurueta.algebra.Matrix internalMatrix, double threshold) throws InvalidPinholeCameraIntrinsicParametersException
      Creates a new instance of camera intrinsic parameters using provided matrix and provided threshold to determine whether it is a valid matrix. Provided matrix must be 3x3 and upper triangular up to provided threshold Note: this constructor will attempt to normalize provided matrix, hence its values might change after calling this constructor.
      Parameters:
      internalMatrix - Provided 3x3 and upper triangular matrix.
      threshold - Threshold to determine whether provided matrix is upper triangular. Matrix will be considered upper triangular if its lower triangular elements are larger than this threshold in absolute terms.
      Throws:
      InvalidPinholeCameraIntrinsicParametersException - thrown if provided matrix is not 3x3 or upper triangular.
      IllegalArgumentException - thrown if provided threshold is negative.

    • PinholeCameraIntrinsicParameters

      public PinholeCameraIntrinsicParameters(double horizontalFocalLength, double verticalFocalLength, double horizontalPrincipalPoint, double verticalPrincipalPoint, double skewness)
      Creates a new instance of camera intrinsic parameters using provided horizontal/vertical focal length, horizontal/vertical principal point and skewness of axes.
      Parameters:
      horizontalFocalLength - Horizontal focal length of camera. The larger the focal length the larger objects will appear, as focal length determines the amount of "zoom". The relation between horizontal and vertical focal length determines the aspect ratio of images.
      verticalFocalLength - Vertical focal length of camera. The larger the focal length the larger objects will appear, as focal length determines the amount of "zoom". The relation between horizontal and vertical focal length determines the aspect ratio of images.
      horizontalPrincipalPoint - Horizontal principal point of camera. Determines where the origin of coordinates of 2D points will be located horizontally on the retinal plane. This is usually the center of an image. If not specified, then the origin of coordinates on the retinal plane is located at (0, 0).
      verticalPrincipalPoint - Vertical principal point of camera. Determines where the origin of coordinates of 2D points will be located vertically on the retinal plane. This is usually the center of an image. If not specified, then the origin of coordinates on the retinal plane is located at (0, 0).
      skewness - Skewness of axes. This usually zero or a value close to zero. The larger the value in absolute terms the more skewed (i.e. slanted) x-y axes will be on projected images.

  • Method Details

    • getInternalMatrix

      public com.irurueta.algebra.Matrix getInternalMatrix()
      Returns a copy of the internal matrix defining this instance parameters
      Returns:
      A copy of the internal matrix of this instance.

    • setInternalMatrix

      public final void setInternalMatrix(com.irurueta.algebra.Matrix internalMatrix) throws InvalidPinholeCameraIntrinsicParametersException
      Sets internal matrix of this instance. Note: this method will attempt to normalize provided matrix, hence its values might change after calling this method.
      Parameters:
      internalMatrix - Matrix to be set as the internal matrix of this instance. This matrix needs to be 3x3 and upper triangular.
      Throws:
      InvalidPinholeCameraIntrinsicParametersException - thrown if provided matrix is not 3x3 or upper triangular.

    • setInternalMatrix

      public final void setInternalMatrix(com.irurueta.algebra.Matrix internalMatrix, double threshold) throws InvalidPinholeCameraIntrinsicParametersException
      Sets the internal matrix of this instance using provided threshold to determine whether it is upper triangular. Note: this method will attempt to normalize provided matrix, hence its values might change after calling this method.
      Parameters:
      internalMatrix - Matrix to be set as the internal matrix of this instance. This matrix needs to be 3x3 and upper triangular.
      threshold - Threshold to determine whether provided matrix is upper triangular. Matrix will be considered upper triangular if its lower triangular elements are larger than this threshold in absolute terms.
      Throws:
      InvalidPinholeCameraIntrinsicParametersException - thrown if provided matrix is not 3x3 or upper triangular.
      IllegalArgumentException - thrown if provided threshold is negative.

    • getInverseInternalMatrix

      public com.irurueta.algebra.Matrix getInverseInternalMatrix()
      Computes the inverse of internal matrix and returns the result. Calling this method is more efficient than calling. com.irurueta.algebra.Utils.inverse.
      Returns:
      inverse of internal matrix.

    • getInverseInternalMatrix

      public void getInverseInternalMatrix(com.irurueta.algebra.Matrix result)
      Computes the inverse of internal matrix and stores the result into provided matrix. Calling this method is more efficient than calling com.irurueta.algebra.Utils.inverse.
      Parameters:
      result - instance where result will be stored.

    • getHorizontalFocalLength

      public double getHorizontalFocalLength()
      Returns the horizontal focal length of a camera. The larger the focal length the larger objects will appear, as focal length determines the amount of "zoom". The relation between horizontal and vertical focal length determines the aspect ratio of images. Note: Negative values will reverse projected points or geometric objects horizontally.
      Returns:
      Horizontal focal length.

    • setHorizontalFocalLength

      public final void setHorizontalFocalLength(double horizontalFocalLength)
      Sets the horizontal focal length of a camera. The larger the focal length the larger objects will appear, as focal length determines the amount of "zoom". The relation between horizontal and vertical focal length determines the aspect ratio of images Note: Negative values will reverse projected points or geometric objects horizontally.
      Parameters:
      horizontalFocalLength - Horizontal focal length to be set.

    • getVerticalFocalLength

      public double getVerticalFocalLength()
      Returns the vertical focal length of a camera. The larger the focal length the larger objects will appear, as focal length determines the amount of "zoom". The relation between horizontal and vertical focal length determines the aspect ratio of images Note: Negative values will reverse projected points or geometric objects vertically.
      Returns:
      Vertical focal length.

    • setVerticalFocalLength

      public final void setVerticalFocalLength(double verticalFocalLength)
      Sets the vertical focal length of a camera. The larger the focal length the larger objects will appear, as focal length determines the amount of "zoom". The relation between horizontal and vertical focal length determines the aspect ratio of images Note: Negative values will reverse projected points or geometric objects vertically.
      Parameters:
      verticalFocalLength - Vertical focal length to be set.

    • getAspectRatio

      public double getAspectRatio()
      Returns aspect ratio. Aspect ratio is the relation between vertical and horizontal focal lengths. If objects are meant to be displayed with no horizontal/vertical scaling distortion, then aspect ratio must be set to 1.0, which means that both horizontal and vertical focal lengths are equal.
      Returns:
      Aspect ratio.

    • setAspectRatioKeepingHorizontalFocalLength

      public void setAspectRatioKeepingHorizontalFocalLength(double aspectRatio)
      Sets provided aspect ratio but keeping current horizontal focal length value. If objects are meant to be displayed with no horizontal/vertical scaling distortion, then aspect ratio must be set to 1.0, which means that both horizontal and vertical focal lengths are equal.
      Parameters:
      aspectRatio - Aspect ratio to be set.

    • setAspectRatioKeepingVerticalFocalLength

      public void setAspectRatioKeepingVerticalFocalLength(double aspectRatio)
      Sets provided aspect ratio but keeping current vertical focal length value. If objects are meant to be displayed with no horizontal/vertical scaling distortion, then aspect ratio must be set to 1.0, which means that both horizontal and vertical focal lengths are equal.
      Parameters:
      aspectRatio - Aspect ratio to be set.

    • getHorizontalPrincipalPoint

      public double getHorizontalPrincipalPoint()
      Returns horizontal principal point. Determines where the origin of coordinates of 2D points will be located horizontally on the retinal plane. This is usually the center of an image. If not specified, then the origin of coordinates on the retinal plane is located at (0, 0) by default. Principal point is usually related to the slanting between the camera sensor and lens. If properly aligned then principal point is usually located at image center.
      Returns:
      Horizontal principal point.

    • setHorizontalPrincipalPoint

      public final void setHorizontalPrincipalPoint(double horizontalPrincipalPoint)
      Sets horizontal principal point. Determines where the origin of coordinates of 2D points will be located horizontally on the retinal plane. This is usually the center of an image. If not specified, then the origin of coordinates on the retinal plane is located at (0, 0) by default. Principal point is usually related to the slanting between the camera sensor and lens. If properly aligned then principal point is usually located at image center.
      Parameters:
      horizontalPrincipalPoint - Horizontal principal point to be set.

    • getVerticalPrincipalPoint

      public double getVerticalPrincipalPoint()
      Returns vertical principal point. Determines where the origin of coordinates of 2D points will be located vertically on the retinal plane. This is usually the center of an image. If not specified, then the origin of coordinates on the retinal plane is located at (0, 0) by default. Principal point is usually related to the slanting between the camera sensor and lens. If properly aligned then principal point is usually located at image center.
      Returns:
      Vertical principal point.

    • setVerticalPrincipalPoint

      public final void setVerticalPrincipalPoint(double verticalPrincipalPoint)
      Sets vertical principal point. Determines where the origin of coordinates of 2D points will be located vertically on the retinal plane. This is usually the center of an image. If not specified, then the origin of coordinates on the retinal plane is located at (0, 0) by default. Principal point is usually related to the slanting between the camera sensor and lens. If properly aligned then principal point is usually located at image center.
      Parameters:
      verticalPrincipalPoint - Vertical principal point to be set.

    • getSkewness

      public double getSkewness()
      Returns skewness of axes on the retinal plane. This usually zero or a value close to zero. The larger the value in absolute terms the more skewed (i.e. slanted) x-y axes will be on projected images.
      Returns:
      Skewness of axes.

    • setSkewness

      public final void setSkewness(double skewness)
      Sets skewness of axes on the retinal plane. This is usually zero or a value close to zero. The larger the value in absolute terms the more skewed (i.e. slanted) x-y axes will be on projected images.
      Parameters:
      skewness - Skewness of axes to be set.

    • getSkewnessAngle

      public double getSkewnessAngle()
      Returns skewness angle in radians of retinal x-y axes associated to current skewness value. This is usually zero or a value close to zero. The larger the value in absolute terms the more skewed (i.e. slanted) x-y axes will be on projected images.
      Returns:
      Skewness angle in radians.

    • setSkewnessAngle

      public void setSkewnessAngle(double skewnessAngle)
      Sets skewness angle in radians of retinal x-y axes associated to current skewness value. This is usually zero or a value close to zero. The larger the value in absolute terms the more skewed (i.e. slanted) x-y axes will be on projected images.
      Parameters:
      skewnessAngle - Skewness angle in radians to be set.

    • createCanonicalIntrinsicParameters

      public static PinholeCameraIntrinsicParameters createCanonicalIntrinsicParameters()
      Creates a canonical intrinsic parameters instance which has no effect on projected 3D points into 2D points.
      Returns:
      Canonical intrinsic parameters instance.

    • createTypicalIntrinsicParameters

      public static PinholeCameraIntrinsicParameters createTypicalIntrinsicParameters(int imageWidth, int imageHeight)
      Creates typical intrinsic parameters for an image of provided size. Typical intrinsic parameters have principal point located at image center and a focal length which results in a frustum of approximately 45ยบ.
      Parameters:
      imageWidth - Width of image in pixels.
      imageHeight - Height of image in pixels.
      Returns:
      Typical intrinsic parameters.
      Throws:
      IllegalArgumentException - raised if provided width or height is negative.

    • isValidMatrix

      public static boolean isValidMatrix(com.irurueta.algebra.Matrix m)
      Determines whether provided matrix is considered a valid matrix for pinhole camera intrinsic parameters. Provided matrix must be 3x3, upper triangular and its last element (3,3) must be 1.0.
      Parameters:
      m - 3x3 and upper triangular matrix to be checked.
      Returns:
      True if provided matrix is valid, false otherwise.

    • isValidMatrix

      public static boolean isValidMatrix(com.irurueta.algebra.Matrix m, double threshold)
      Determines whether provided matrix is considered a valid matrix for pinhole camera intrinsic parameters. Provided matrix must be 3x3, upper triangular (up to provided threshold) and its last element (3,3) must be 1.0.
      Parameters:
      m - 3x3 and upper triangular matrix to be checked.
      threshold - Threshold to determine whether matrix is upper triangular.
      Returns:
      True if provided matrix is valid, false otherwise.
      Throws:
      IllegalArgumentException - Raised if provided threshold is negative.

    • normalize

      private static void normalize(com.irurueta.algebra.Matrix m)
      Normalizes provided matrix so that element (3,3) becomes one.
      Parameters:
      m - Matrix to be normalized.

    • clone

      public PinholeCameraIntrinsicParameters clone() throws CloneNotSupportedException
      Clones this instance of pinhole camera matrix.
      Overrides:
      clone in class Object
      Returns:
      A copy of this instance.
      Throws:
      CloneNotSupportedException - if clone fails.

    • create

      public static PinholeCameraIntrinsicParameters create(double focalLength, double sensorWidth, double sensorHeight, int imageWidth, int imageHeight)
      Creates an instance of pinhole camera intrinsic parameters using provided data. Created instance assumes that skewness is zero and that principal point is located at origin of coordinates. This method can be used if for instance actual camera sensor data such as focal length expressed in millimeters and sensor size expressed in millimeters is known along with the size of the obtained image data.
      Parameters:
      focalLength - focal length of camera expressed in millimeters.
      sensorWidth - camera sensor width expressed in millimeters.
      sensorHeight - camera sensor height expressed in millimeters.
      imageWidth - captured image width expressed in pixels.
      imageHeight - captured image height expressed in pixels.
      Returns:
      an instance of pinhole camera intrinsic parameters.