Package com.irurueta.ar.calibration

Class AlternatingCameraCalibrator

java.lang.Object
com.irurueta.ar.calibration.CameraCalibrator
com.irurueta.ar.calibration.AlternatingCameraCalibrator
public class AlternatingCameraCalibrator extends CameraCalibrator
Calibrates a camera in order to find its intrinsic parameters and radial distortion by using an alternating technique where first an initial guess of the intrinsic parameters, rotation and translation is obtained to model the camera used to sample the calibration pattern, and then the result is used to find the best possible radial distortion to account for all remaining errors. The result is then used to undo the distortion effect and calibrate again to estimate the intrinsic parameters and camera pose. This alternating process is repeated until convergence is reached.

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_MAX_ITERATIONS

      public static final int DEFAULT_MAX_ITERATIONS
      Default maximum number of times to do an alternating iteration to refine the results.
      See Also:

    • MIN_MAX_ITERATIONS

      public static final int MIN_MAX_ITERATIONS
      Minimum allowed value to be set as max iterations.
      See Also:

    • DEFAULT_CONVERGENCE_THRESHOLD

      public static final double DEFAULT_CONVERGENCE_THRESHOLD
      Default threshold to determine that convergence of the result has been reached.
      See Also:

    • MIN_CONVERGENCE_THRESHOLD

      public static final double MIN_CONVERGENCE_THRESHOLD
      Minimum allowed value to be set as convergence threshold.
      See Also:

    • 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.

    • maxIterations

      private int maxIterations
      Maximum number of times to do an alternating iteration to refine the results.

    • convergenceThreshold

      private double convergenceThreshold
      Default threshold to determine that convergence of the result has been reached.

    • distortionMethod

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

    • 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.

    • iterProgress

      private float iterProgress
      Overall progress taking into account current number of iteration.

    • previousNotifiedProgress

      private float previousNotifiedProgress
      Previously notified progress.

  • Constructor Details

    • AlternatingCameraCalibrator

      public AlternatingCameraCalibrator()
      Constructor.

    • AlternatingCameraCalibrator

      public AlternatingCameraCalibrator(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.

    • AlternatingCameraCalibrator

      public AlternatingCameraCalibrator(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 if both samples and quality scores do not have the same size.

  • Method Details

    • getMaxIterations

      public int getMaxIterations()
      Returns maximum number of times to do an alternating iteration to refine the results.
      Returns:
      maximum number of times to do an alternating iteration.

    • setMaxIterations

      public void setMaxIterations(int maxIterations) throws com.irurueta.geometry.estimators.LockedException
      Sets maximum number of times to do an alternating iteration to refine the results.
      Parameters:
      maxIterations - maximum number of times to do an alternating iteration.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is zero or negative.

    • getConvergenceThreshold

      public double getConvergenceThreshold()
      Returns threshold to determine that convergence of the result has been reached.
      Returns:
      threshold to determine that convergence of the result has been reached.

    • setConvergenceThreshold

      public void setConvergenceThreshold(double convergenceThreshold) throws com.irurueta.geometry.estimators.LockedException
      Sets threshold to determine that convergence of the result has been reached.
      Parameters:
      convergenceThreshold - threshold to determine that convergence of the result has been reached.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is negative.

    • 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.

    • estimateRadialDistortion

      protected double estimateRadialDistortion(List<com.irurueta.geometry.Point2D> idealFallbackPatternMarkers) throws CalibrationException
      Estimates radial distortion using estimated intrinsic parameters among all samples to estimate their camera poses to find non-distorted points and compare them with the sampled ones.
      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.

    • 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

    • refreshDistortionEstimatorListener

      protected void refreshDistortionEstimatorListener()
      Refreshes listener of distortion estimator

    • 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.