Package com.irurueta.ar.calibration

Class RadialDistortion

java.lang.Object
com.irurueta.ar.calibration.Distortion
com.irurueta.ar.calibration.RadialDistortion
All Implemented Interfaces:
Serializable
public class RadialDistortion extends Distortion implements Serializable
Class implementing Brown's radial distortion. This kind of distortion is usually modelled after the distortion introduced by lenses on cameras when taking short range pictures using wide angle lenses. Brown's radial distortion typically follow an expression such as: xd = xu + (xu - xc)*(K1*r^2 + K2*r^4 + ...) yd = yu + (yu - yc)*(K1*r^2 + K2*r^4 + ...), where (xu, yu) stands for the undistorted point coordinates, (xd, yd) stands for the distorted point coordinates, (xc, yc) stands for the distortion center, r^2 is typically (xu - xc)^2 + (yu - yc)^2 stands for the squared distance of the distorted point respect to the distortion center. r^2 is computed taking into account provided intrinsic parameters And K1, K2 are the distortion parameters. Usually K1 dominates and K2 is much smaller. Further terms are usually neglected as they are not meaningful and typically produce numerical instabilities, but can also be provided in array form.

NOTE: in order to be able to converge to correct values when computing distortions, RadialDistortion should work with normalized point coordinates between -1.0 and 1.0.

See Also:

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private com.irurueta.geometry.Point2D
    center
    Radial distortion center.
    static final double
    DEFAULT_FOCAL_LENGTH
    Defines default focal length if none is defined.
    static final int
    DEFAULT_MAX_ITERS
    Default maximum number of iterations to do when attempting to un-distort a point if convergence is not reached.
    static final double
    DEFAULT_SKEW
    Defines default skewness if none is defined.
    static final double
    DEFAULT_TOLERANCE
    Default tolerance to consider point convergence when un-distorting a point.
    private double
    horizontalFocalLength
    Horizontal focal length expressed in pixels.
    private com.irurueta.algebra.Matrix
    kInv
    Inverse of intrinsic parameters' matrix.
    private double[]
    kParams
    Radial distortion parameters.
    private double
    skew
    Skew in pixels.
    private double
    verticalFocalLength
    Vertical focal length expressed in pixels.

  • Constructor Summary

    Constructors
    Constructor
    Description
    RadialDistortion()
    Constructor.
    RadialDistortion(double[] kParams)
    Constructor with radial distortion parameters and center assumed to be at the origin of coordinates (0, 0).
    RadialDistortion(double[] kParams, com.irurueta.geometry.Point2D center)
    Constructor with radial distortion parameters and center.
    RadialDistortion(double[] kParams, com.irurueta.geometry.Point2D center, double horizontalFocalLength, double verticalFocalLength, double skew)
    Constructor with radial distortion parameters, center and other camera intrinsic parameters.
    RadialDistortion(double k1, double k2)
    Constructor with radial distortion parameters and center assumed to be at the origin of coordinates (0, 0).
    RadialDistortion(double k1, double k2, com.irurueta.geometry.Point2D center)
    Constructor with radial distortion parameters and center.
    RadialDistortion(double k1, double k2, com.irurueta.geometry.Point2D center, double horizontalFocalLength, double verticalFocalLength, double skew)
    Constructor with radial distortion parameters, center and other camera intrinsic parameters.
    RadialDistortion(com.irurueta.geometry.Point2D distortedPoint1, com.irurueta.geometry.Point2D distortedPoint2, com.irurueta.geometry.Point2D undistortedPoint1, com.irurueta.geometry.Point2D undistortedPoint2, com.irurueta.geometry.Point2D distortionCenter)
    Constructor with points and distortion center.

  • Method Summary

    Modifier and Type
    Method
    Description
    boolean
    canDistort()
    Indicates whether this instance can distort points.
    boolean
    canUndistort()
    Indicates whether this instance can un-distort points.
    void
    distort(com.irurueta.geometry.Point2D undistortedPoint, com.irurueta.geometry.Point2D distortedPoint)
    Distorts provided 2D point and stores result into provided distorted point.
    com.irurueta.geometry.Point2D
    getCenter()
    Returns radial distortion center.
    double
    getHorizontalFocalLength()
    Returns horizontal focal length expressed in pixels.
    com.irurueta.geometry.PinholeCameraIntrinsicParameters
    getIntrinsic()
    Returns pinhole camera intrinsic parameters associated to this distortion.
    double
    getK1()
    Returns first degree distortion parameter or zero if not available.
    double
    getK2()
    Returns second degree distortion parameter or zero if not available.
    DistortionKind
    getKind()
    Returns kind of distortion.
    double[]
    getKParams()
    Returns all radial distortion parameters.
    double
    getSkew()
    Returns skew expressed in pixels.
    double
    getVerticalFocalLength()
    Returns vertical focal length expressed in pixels.
    void
    setCenter(com.irurueta.geometry.Point2D center)
    Sets radial distortion center.
    final void
    setFromPointsAndCenter(com.irurueta.geometry.Point2D distortedPoint1, com.irurueta.geometry.Point2D distortedPoint2, com.irurueta.geometry.Point2D undistortedPoint1, com.irurueta.geometry.Point2D undistortedPoint2, com.irurueta.geometry.Point2D distortionCenter)
    Estimates this radial distortion from points and distortion center.
    void
    setHorizontalFocalLength(double horizontalFocalLength)
    Sets horizontal focal length expressed in pixels.
    void
    setIntrinsic(com.irurueta.geometry.PinholeCameraIntrinsicParameters intrinsic)
    Sets intrinsic parameters from pinhole camera.
    final void
    setIntrinsic(com.irurueta.geometry.Point2D center, double horizontalFocalLength, double verticalFocalLength, double skew)
    Sets intrinsic parameters.
    void
    setK1(double k1)
    Sets first degree distortion parameter.
    void
    setK2(double k2)
    Sets second degree distortion parameter.
    void
    setKParams(double[] kParams)
    Sets all radial distortion parameters.
    void
    setSkew(double skew)
    Sets skew expressed in pixels.
    void
    setVerticalFocalLength(double verticalFocalLength)
    Sets vertical focal length expressed in pixels.
    void
    undistort(com.irurueta.geometry.Point2D distortedPoint, com.irurueta.geometry.Point2D undistortedPoint)
    Un-distorts provided 2D point and stores result into provided undistorted point
    void
    undistort(com.irurueta.geometry.Point2D distortedPoint, com.irurueta.geometry.Point2D undistortedPoint, int maxIters, double tolerance)
    Un-distorts provided 2D point and stores result into provided undistorted point.

    Methods inherited from class com.irurueta.ar.calibration.Distortion

    distort, distort, distort, undistort, undistort, undistort

    Methods inherited from class java.lang.Object

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

  • Field Details

    • DEFAULT_FOCAL_LENGTH

      public static final double DEFAULT_FOCAL_LENGTH
      Defines default focal length if none is defined.
      See Also:

    • DEFAULT_SKEW

      public static final double DEFAULT_SKEW
      Defines default skewness if none is defined.
      See Also:

    • DEFAULT_MAX_ITERS

      public static final int DEFAULT_MAX_ITERS
      Default maximum number of iterations to do when attempting to un-distort a point if convergence is not reached.
      See Also:

    • DEFAULT_TOLERANCE

      public static final double DEFAULT_TOLERANCE
      Default tolerance to consider point convergence when un-distorting a point.
      See Also:

    • center

      private com.irurueta.geometry.Point2D center
      Radial distortion center.

    • kParams

      private double[] kParams
      Radial distortion parameters.

    • horizontalFocalLength

      private double horizontalFocalLength
      Horizontal focal length expressed in pixels.

    • verticalFocalLength

      private double verticalFocalLength
      Vertical focal length expressed in pixels.

    • skew

      private double skew
      Skew in pixels.

    • kInv

      private com.irurueta.algebra.Matrix kInv
      Inverse of intrinsic parameters' matrix.

  • Constructor Details

    • RadialDistortion

      public RadialDistortion()
      Constructor.

    • RadialDistortion

      public RadialDistortion(double k1, double k2)
      Constructor with radial distortion parameters and center assumed to be at the origin of coordinates (0, 0).
      Parameters:
      k1 - first degree distortion parameter.
      k2 - second degree distortion parameter.

    • RadialDistortion

      public RadialDistortion(double[] kParams)
      Constructor with radial distortion parameters and center assumed to be at the origin of coordinates (0, 0).
      Parameters:
      kParams - radial distortion parameters of any length.
      Throws:
      IllegalArgumentException - if radial distortion parameters is null.

    • RadialDistortion

      public RadialDistortion(double k1, double k2, com.irurueta.geometry.Point2D center)
      Constructor with radial distortion parameters and center.
      Parameters:
      k1 - first degree distortion parameter.
      k2 - second degree distortion parameter.
      center - center of radial distortion. If null it is assumed to be at the origin of coordinates (0, 0), which is the typical value.

    • RadialDistortion

      public RadialDistortion(double[] kParams, com.irurueta.geometry.Point2D center)
      Constructor with radial distortion parameters and center.
      Parameters:
      kParams - radial distortion parameters of any length.
      center - center of radial distortion. If null it is assumed to be at the origin of coordinates (0, 0), which is the typical value.
      Throws:
      IllegalArgumentException - if radial distortion parameters is null.

    • RadialDistortion

      public RadialDistortion(double k1, double k2, com.irurueta.geometry.Point2D center, double horizontalFocalLength, double verticalFocalLength, double skew) throws RadialDistortionException
      Constructor with radial distortion parameters, center and other camera intrinsic parameters.
      Parameters:
      k1 - first degree distortion parameter.
      k2 - second degree distortion parameter.
      center - center of radial distortion. If null it is assumed to be at the origin of coordinates (0, 0), which is the typical value.
      horizontalFocalLength - horizontal focal length expressed in pixels.
      verticalFocalLength - vertical focal length expressed in pixels.
      skew - skew expressed in pixels.
      Throws:
      RadialDistortionException - if provided focal lengths are degenerate (i.e. zero).

    • RadialDistortion

      public RadialDistortion(double[] kParams, com.irurueta.geometry.Point2D center, double horizontalFocalLength, double verticalFocalLength, double skew) throws RadialDistortionException
      Constructor with radial distortion parameters, center and other camera intrinsic parameters.
      Parameters:
      kParams - radial distortion parameters of any length.
      center - center of radial distortion. If null it is assumed to be at the origin of coordinates (0, 0), which is the typical value.
      horizontalFocalLength - horizontal focal length expressed in pixels.
      verticalFocalLength - vertical focal length expressed in pixels.
      skew - skew expressed in pixels.
      Throws:
      RadialDistortionException - if provided focal lengths are degenerate (i.e. zero).
      IllegalArgumentException - if radial distortion parameters is null.

    • RadialDistortion

      public RadialDistortion(com.irurueta.geometry.Point2D distortedPoint1, com.irurueta.geometry.Point2D distortedPoint2, com.irurueta.geometry.Point2D undistortedPoint1, com.irurueta.geometry.Point2D undistortedPoint2, com.irurueta.geometry.Point2D distortionCenter) throws RadialDistortionException
      Constructor with points and distortion center.
      Parameters:
      distortedPoint1 - 1st distorted point (i.e. measured).
      distortedPoint2 - 2nd distorted point (i.e. measured).
      undistortedPoint1 - 1st undistorted point (i.e. ideal).
      undistortedPoint2 - 2nd undistorted point (i.e. undistorted).
      distortionCenter - distortion center or null if center is at origin of coordinates (which is the typical value).
      Throws:
      RadialDistortionException - if distortion could not be estimated.

  • Method Details

    • setFromPointsAndCenter

      public final void setFromPointsAndCenter(com.irurueta.geometry.Point2D distortedPoint1, com.irurueta.geometry.Point2D distortedPoint2, com.irurueta.geometry.Point2D undistortedPoint1, com.irurueta.geometry.Point2D undistortedPoint2, com.irurueta.geometry.Point2D distortionCenter) throws RadialDistortionException
      Estimates this radial distortion from points and distortion center.
      Parameters:
      distortedPoint1 - 1st distorted point (i.e. measured).
      distortedPoint2 - 2nd distorted point (i.e. measured).
      undistortedPoint1 - 1st undistorted point (i.e. ideal).
      undistortedPoint2 - 2nd undistorted point (i.e. undistorted).
      distortionCenter - distortion center or null if center is at origin of coordinates (which is the typical value).
      Throws:
      RadialDistortionException - if distortion could not be estimated.

    • getCenter

      public com.irurueta.geometry.Point2D getCenter()
      Returns radial distortion center.
      Returns:
      radial distortion center.

    • setCenter

      public void setCenter(com.irurueta.geometry.Point2D center)
      Sets radial distortion center.
      Parameters:
      center - radial distortion center to be set.

    • getHorizontalFocalLength

      public double getHorizontalFocalLength()
      Returns horizontal focal length expressed in pixels.
      Returns:
      horizontal focal length expressed in pixels.

    • setHorizontalFocalLength

      public void setHorizontalFocalLength(double horizontalFocalLength) throws RadialDistortionException
      Sets horizontal focal length expressed in pixels.
      Parameters:
      horizontalFocalLength - horizontal focal length expressed in pixels.
      Throws:
      RadialDistortionException - if provided value is degenerate (i.e. zero).

    • getVerticalFocalLength

      public double getVerticalFocalLength()
      Returns vertical focal length expressed in pixels.
      Returns:
      vertical focal length expressed in pixels.

    • setVerticalFocalLength

      public void setVerticalFocalLength(double verticalFocalLength) throws RadialDistortionException
      Sets vertical focal length expressed in pixels.
      Parameters:
      verticalFocalLength - vertical focal length expressed in pixels.
      Throws:
      RadialDistortionException - if provided value is degenerate (i.e. zero).

    • getSkew

      public double getSkew()
      Returns skew expressed in pixels.
      Returns:
      skew expressed in pixels.

    • setSkew

      public void setSkew(double skew)
      Sets skew expressed in pixels.
      Parameters:
      skew - skew expressed in pixels.

    • getIntrinsic

      public com.irurueta.geometry.PinholeCameraIntrinsicParameters getIntrinsic()
      Returns pinhole camera intrinsic parameters associated to this distortion.
      Returns:
      pinhole camera intrinsic parameters associated to this distortion.

    • setIntrinsic

      public void setIntrinsic(com.irurueta.geometry.PinholeCameraIntrinsicParameters intrinsic) throws RadialDistortionException
      Sets intrinsic parameters from pinhole camera.
      Parameters:
      intrinsic - intrinsic parameters to be set.
      Throws:
      RadialDistortionException - if focal length is degenerate (i.e. zero).

    • setIntrinsic

      public final void setIntrinsic(com.irurueta.geometry.Point2D center, double horizontalFocalLength, double verticalFocalLength, double skew) throws RadialDistortionException
      Sets intrinsic parameters.
      Parameters:
      center - radial distortion center.
      horizontalFocalLength - horizontal focal length expressed in pixels.
      verticalFocalLength - vertical focal length expressed in pixels.
      skew - skew expressed in pixels.
      Throws:
      RadialDistortionException - if focal length is degenerate (i.e. zero).

    • getK1

      public double getK1()
      Returns first degree distortion parameter or zero if not available.
      Returns:
      first degree distortion parameter or zero if not available.

    • setK1

      public void setK1(double k1)
      Sets first degree distortion parameter.
      Parameters:
      k1 - first degree distortion parameter.

    • getK2

      public double getK2()
      Returns second degree distortion parameter or zero if not available.
      Returns:
      second degree distortion parameter or zero if not available.

    • setK2

      public void setK2(double k2)
      Sets second degree distortion parameter.
      Parameters:
      k2 - second degree distortion parameter to be set.

    • getKParams

      public double[] getKParams()
      Returns all radial distortion parameters. Typically only first and second degree radial distortion parameters are used.
      Returns:
      all radial distortion parameters.

    • setKParams

      public void setKParams(double[] kParams)
      Sets all radial distortion parameters. With this method more than 2 radial distortion parameters can be set if needed.
      Parameters:
      kParams - radial distortion parameters to be set.

    • distort

      public void distort(com.irurueta.geometry.Point2D undistortedPoint, com.irurueta.geometry.Point2D distortedPoint)
      Distorts provided 2D point and stores result into provided distorted point.
      Specified by:
      distort in class Distortion
      Parameters:
      undistortedPoint - undistorted point to be undistorted.
      distortedPoint - distorted point where result is stored.

    • undistort

      public void undistort(com.irurueta.geometry.Point2D distortedPoint, com.irurueta.geometry.Point2D undistortedPoint)
      Un-distorts provided 2D point and stores result into provided undistorted point
      Specified by:
      undistort in class Distortion
      Parameters:
      distortedPoint - distorted point to be undistorted
      undistortedPoint - undistorted point where result is stored

    • undistort

      public void undistort(com.irurueta.geometry.Point2D distortedPoint, com.irurueta.geometry.Point2D undistortedPoint, int maxIters, double tolerance)
      Un-distorts provided 2D point and stores result into provided undistorted point.
      Parameters:
      distortedPoint - distorted point to be undistorted.
      undistortedPoint - undistorted point where result is stored.
      maxIters - maximum number of iterations to un-distort a point in case that convergence is not reached.
      tolerance - tolerance to indicate that convergence has been reached.

    • canDistort

      public boolean canDistort()
      Indicates whether this instance can distort points. This implementation always returns false, hence attempting to distort a point will result in a NotSupportedException being raised.
      Specified by:
      canDistort in class Distortion
      Returns:
      true if points can be distorted, false otherwise.

    • canUndistort

      public boolean canUndistort()
      Indicates whether this instance can un-distort points. This implementation always returns true.
      Specified by:
      canUndistort in class Distortion
      Returns:
      true if points can be undistorted, false otherwise.

    • getKind

      public DistortionKind getKind()
      Returns kind of distortion.
      Specified by:
      getKind in class Distortion
      Returns:
      kind of distortion.