Package com.irurueta.ar.calibration

Class ErrorOptimizationCameraCalibrator

java.lang.Object
com.irurueta.ar.calibration.CameraCalibrator
com.irurueta.ar.calibration.ErrorOptimizationCameraCalibrator
public class ErrorOptimizationCameraCalibrator extends CameraCalibrator
Calibrates a camera in order to find its intrinsic parameters and radial distortion by first estimating the intrinsic parameters without accounting for radial distortion and then use an optimization algorithm to minimize error and adjust estimated camera pose, intrinsic parameters and radial distortion parameters.

This class is based on technique described at: Zhengyou Zhang. A Flexible New Technique for Camera Calibration. Technical Report. MSR-TR-98-71. December 2, 1998.

  • Field Details

    • DEFAULT_RADIAL_DISTORTION_METHOD

      public static final com.irurueta.numerical.robust.RobustEstimatorMethod DEFAULT_RADIAL_DISTORTION_METHOD
      Default robust estimator method to be used for radial distortion estimation.

    • DEFAULT_ESTIMATE_INITIAL_RADIAL_DISTORTION

      public static final boolean DEFAULT_ESTIMATE_INITIAL_RADIAL_DISTORTION
      Indicates whether an initial radial distortion guess is estimated based on sampled data and estimated camera poses before starting the actual radial distortion optimization process.
      See Also:

    • DEFAULT_LEVENBERG_MARQUARDT_MAX_ITERS

      public static final int DEFAULT_LEVENBERG_MARQUARDT_MAX_ITERS
      Default maximum number of iterations to be used when adjusting parameters using Levenberg-Marquardt algorithm.
      See Also:

    • DEFAULT_LEVENBERG_MARQUARDT_TOLERANCE

      public static final double DEFAULT_LEVENBERG_MARQUARDT_TOLERANCE
      Default tolerance to assume that Levenberg-Marquardt algorithm has reached convergence when adjusting parameters.
      See Also:

    • levenbergMarquardtMaxIters

      private int levenbergMarquardtMaxIters
      Maximum number of iterations to be used when adjusting parameters using Levenberg-Marquardt algorithm.

    • levenbergMarquardtTolerance

      private double levenbergMarquardtTolerance
      Tolerance to assume that Levenberg-Marquardt algorithm has reached convergence when adjusting parameters.

    • distortionMethod

      private com.irurueta.numerical.robust.RobustEstimatorMethod distortionMethod
      Robust estimator method to be used for radial distortion estimation.

    • estimateInitialRadialDistortion

      private final boolean estimateInitialRadialDistortion
      Indicates whether an initial radial distortion guess is estimated based on sampled data and estimated camera poses before starting the actual radial distortion optimization process.

    • distortionEstimator

      private RadialDistortionRobustEstimator distortionEstimator
      Robust estimator of radial distortion.

    • distortionEstimatorListener

      private RadialDistortionRobustEstimatorListener distortionEstimatorListener
      Listener for robust estimator of radial distortion.

    • radialDistortionProgress

      private float radialDistortionProgress
      Indicates progress of radial distortion estimation.

    • fittingProgress

      private float fittingProgress
      Indicates progress of Levenberg-Marquardt fitting.

    • previousNotifiedProgress

      private float previousNotifiedProgress
      Previously notified progress.

    • indexToView

      private int[] indexToView
      Array to keep a relation between each point at index i-th and the sample (i.e. view) where it belongs to.

  • Constructor Details

    • ErrorOptimizationCameraCalibrator

      public ErrorOptimizationCameraCalibrator()
      Constructor.

    • ErrorOptimizationCameraCalibrator

      public ErrorOptimizationCameraCalibrator(Pattern2D pattern, List<CameraCalibratorSample> samples)
      Constructor.
      Parameters:
      pattern - 2D pattern to use for calibration.
      samples - samples of the pattern taken with the camera to calibrate.
      Throws:
      IllegalArgumentException - if not enough samples are provided.

    • ErrorOptimizationCameraCalibrator

      public ErrorOptimizationCameraCalibrator(Pattern2D pattern, List<CameraCalibratorSample> samples, double[] samplesQualityScores)
      Constructor.
      Parameters:
      pattern - 2D pattern to use for calibration.
      samples - samples of the pattern taken with the camera to calibrate.
      samplesQualityScores - quality scores for each sample.
      Throws:
      IllegalArgumentException - if not enough samples are provided or both samples and quality scores do not have the same size.

  • Method Details

    • getLevenbergMarquardtMaxIters

      public int getLevenbergMarquardtMaxIters()
      Returns maximum number of iterations to be used when adjusting parameters using Levenberg-Marquardt algorithm.
      Returns:
      maximum number of iterations to be used when adjusting parameters using Levenberg-Marquardt algorithm.

    • setLevenbergMarquardtMaxIters

      public void setLevenbergMarquardtMaxIters(int levenbergMarquardtMaxIters) throws com.irurueta.geometry.estimators.LockedException
      Sets maximum number of iterations to be used when adjusting parameters using Levenberg-Marquardt algorithm.
      Parameters:
      levenbergMarquardtMaxIters - maximum number of iterations to be used when adjusting parameters using Levenberg-Marquardt algorithm.
      Throws:
      IllegalArgumentException - if provided value is zero or negative.
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • getLevenbergMarquardtTolerance

      public double getLevenbergMarquardtTolerance()
      Returns tolerance to assume that Levenberg-Marquardt algorithm has reached convergence when adjusting parameters.
      Returns:
      tolerance to assume that Levenberg-Marquardt algorithm has reached convergence when adjusting parameters.

    • setLevenbergMarquardtTolerance

      public void setLevenbergMarquardtTolerance(double levenbergMarquardtTolerance) throws com.irurueta.geometry.estimators.LockedException
      Sets tolerance to assume that Levenberg-Marquardt algorithm has reached convergence when adjusting parameters.
      Parameters:
      levenbergMarquardtTolerance - tolerance to assume that Levenberg-Marquardt algorithm has reached convergence when adjusting parameter.
      Throws:
      IllegalArgumentException - if provided value is zero or negative.
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • getDistortionMethod

      public com.irurueta.numerical.robust.RobustEstimatorMethod getDistortionMethod()
      Returns robust estimator method to be used for radial distortion estimation.
      Returns:
      robust estimator method to be used for radial distortion estimation.

    • setDistortionMethod

      public void setDistortionMethod(com.irurueta.numerical.robust.RobustEstimatorMethod distortionMethod) throws com.irurueta.geometry.estimators.LockedException
      Sets robust estimator method to be used for radial distortion estimation.
      Parameters:
      distortionMethod - robust estimator method to be used for radial distortion estimation.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • getDistortionEstimator

      public RadialDistortionRobustEstimator getDistortionEstimator()
      Returns radial distortion estimator, which can be retrieved in case that some additional parameter needed to be adjusted. It is discouraged to directly access the distortion estimator during camera calibration, as it might interfere with the results.
      Returns:
      radial distortion estimator.

    • getDistortionEstimatorThreshold

      public double getDistortionEstimatorThreshold()
      Returns threshold to robustly estimate radial distortion. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments.
      Returns:
      threshold to robustly estimate radial distortion.

    • setDistortionEstimatorThreshold

      public void setDistortionEstimatorThreshold(double distortionEstimatorThreshold) throws com.irurueta.geometry.estimators.LockedException
      Sets threshold to robustly estimate radial distortion. Usually the default value is good enough for most situations, but this setting can be changed for finder adjustments.
      Parameters:
      distortionEstimatorThreshold - threshold to robustly estimate radial distortion .
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is zero or negative.

    • getDistortionEstimatorConfidence

      public double getDistortionEstimatorConfidence()
      Returns confidence to robustly estimate radial distortion. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments. Confidence is expressed as a value between 0.0 (0%) and 1.0 (100%). The amount of confidence indicates the probability that the estimated homography is correct (i.e. no outliers were used for the estimation, because they were successfully discarded). Typically, this value will be close to 1.0, but not exactly 1.0, because a 100% confidence would require an infinite number of iterations. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments.
      Returns:
      confidence to robustly estimate homographies.

    • setDistortionEstimatorConfidence

      public void setDistortionEstimatorConfidence(double distortionEstimatorConfidence) throws com.irurueta.geometry.estimators.LockedException
      Sets confidence to robustly estimate radial distortion. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments. Confidence is expressed as a value between 0.0 (0%) and 1.0 (100%). The amount of confidence indicates the probability that the estimated homography is correct (i.e. no outliers were used for the estimation, because they were successfully discarded). Typically, this value will be close to 1.0, but not exactly 1.0, because a 100% confidence would require an infinite number of iterations. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments.
      Parameters:
      distortionEstimatorConfidence - confidence to robustly estimate radial distortion.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is not between 0.0 and 1.0.

    • getDistortionEstimatorMaxIterations

      public int getDistortionEstimatorMaxIterations()
      Returns the maximum number of iterations to be done when estimating the radial distortion. If the maximum allowed number of iterations is reached, resulting estimation might not have desired confidence. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments.
      Returns:
      maximum number of iterations to be done when estimating the homographies.

    • setDistortionEstimatorMaxIterations

      public void setDistortionEstimatorMaxIterations(int distortionEstimatorMaxIterations) throws com.irurueta.geometry.estimators.LockedException
      Sets the maximum number of iterations to be done when estimating the radial distortion. If the maximum allowed number of iterations is reached, resulting estimation might not have desired confidence. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments.
      Parameters:
      distortionEstimatorMaxIterations - maximum number of iterations to be done when estimating radial distortion.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is negative or zero.

    • calibrate

      public void calibrate() throws CalibrationException, com.irurueta.geometry.estimators.LockedException, com.irurueta.geometry.estimators.NotReadyException
      Starts the calibration process. Depending on the settings the following will be estimated: intrinsic pinhole camera parameters, radial distortion of lens, camera pose (rotation and translation) for each sample, and the associated homobraphy of sampled points respect to the ideal pattern samples.
      Specified by:
      calibrate in class CameraCalibrator
      Throws:
      CalibrationException - if calibration fails for some reason.
      com.irurueta.geometry.estimators.LockedException - if this instance is locked because calibration is already in progress.
      com.irurueta.geometry.estimators.NotReadyException - if this instance does not have enough data to start camera calibration.

    • getMethod

      public CameraCalibratorMethod getMethod()
      Returns the camera calibrator method used by this instance.
      Specified by:
      getMethod in class CameraCalibrator
      Returns:
      the camera calibrator method.

    • notifyProgress

      protected void notifyProgress()
      Notifies progress to current listener, if needed.
      Specified by:
      notifyProgress in class CameraCalibrator

    • estimateRadialDistortion

      protected double estimateRadialDistortion(List<com.irurueta.geometry.Point2D> idealFallbackPatternMarkers) throws CalibrationException
      Estimates radial distortion by minimizing the re-projection error by adjusting the camera pose and radial distortion parameters using an optimization algorithm. The initial solution for the optimization algorithm is the estimated camera pose and intrinsic parameters without accounting for radial distortion and radial distortion parameters equal to 0.0.
      Parameters:
      idealFallbackPatternMarkers - ideal pattern markers coordinates. These coordinates are used as fallback when a given sample does not have an associated pattern.
      Returns:
      average re-projection error, obtained after projecting ideal pattern markers using estimated camera poses and then doing a comparison with sampled points taking into account estimated distortion to undo their corresponding distortion.
      Throws:
      CalibrationException - if anything fails.

    • refreshDistortionEstimatorListener

      protected void refreshDistortionEstimatorListener()
      Refreshes listener of distortion estimator when robust estimator method is changed for the distortion estimator.

    • evaluateFunction

      private void evaluateFunction(int i, double[] point, double[] params, double[] result)
      Evaluates provided point and parameters to obtain the distorted points that would be obtained. Levenberg-Marquardt algorithm will iteratively change parameters until the obtained result approximates sampled Y data
      Parameters:
      i - index of point among all provided data.
      point - input point to be evaluated.
      params - parameters to evaluate function.
      result - result of evaluation.

    • dataXToMatrix

      private com.irurueta.algebra.Matrix dataXToMatrix(List<com.irurueta.geometry.Point2D> idealFallbackPatternMarkers) throws com.irurueta.algebra.WrongSizeException
      Converts undistorted points corresponding to ideal pattern markers into a matrix to be used by Levenberg-Marquardt as the input data to be used by the function being fitted.
      Parameters:
      idealFallbackPatternMarkers - ideal pattern markers coordinates. These coordinates are used as fallback when a given sample does not have an associated pattern.
      Returns:
      a matrix.
      Throws:
      com.irurueta.algebra.WrongSizeException - if no undistorted points are available.

    • dataYToMatrix

      private com.irurueta.algebra.Matrix dataYToMatrix() throws com.irurueta.algebra.WrongSizeException
      Converts sampled distorted points into a matrix to be used by Levenberg-Marquardt algorithm as the sampled function evaluations.
      Returns:
      a matrix.
      Throws:
      com.irurueta.algebra.WrongSizeException - if no sampled points are available.

    • paramsFromData

      private void paramsFromData(double[] params)
      Sets parameters of function to be fitted using Levenberg-Marquardt algorithm. These parameters will be used as an initial solution and on each iteration of the Levenberg-Marquardt algorithm.
      Parameters:
      params - arrays where parameters will be set using current data.

    • dataFromParams

      private void dataFromParams(double[] params)
      Sets data in samples from parameters values fitted by the Levenberg-Marquardt algorithm.
      Parameters:
      params - vector containing estimated parameters .

    • computeReprojectionError

      private double computeReprojectionError(List<com.irurueta.geometry.Point2D> idealFallbackPatternMarkers)
      Computes re-projection error taking into account ideal pattern marker points, transforming them using estimated homography, adding to them distortion and comparing them with sampled points.
      Parameters:
      idealFallbackPatternMarkers - ideal 2D pattern marker points used as fallback in case that a given sample does not have an associated pattern.
      Returns:
      average re-projection error.

    • internalSetDistortionMethod

      private void internalSetDistortionMethod(com.irurueta.numerical.robust.RobustEstimatorMethod distortionMethod)
      Sets robust estimator method to be used for radial distortion estimation. If method changes, then a new radial distortion estimator is created and configured.
      Parameters:
      distortionMethod - robust estimator method to be used for radial distortion estimation.

    • numParameters

      private int numParameters(int numHomographies)
      Returns number of parameters of cost function.
      Parameters:
      numHomographies - number of valid estimated homographies.
      Returns:
      number of parameters of cost function.

    • numIntrinsicParameters

      private int numIntrinsicParameters()
      Returns number of intrinsic parameters to be taken into account in cost function.
      Returns:
      number of intrinsic parameters to be taken into account in cost function.