Package com.irurueta.ar.calibration

Class CameraCalibrator

java.lang.Object
com.irurueta.ar.calibration.CameraCalibrator
Direct Known Subclasses:
AlternatingCameraCalibrator, ErrorOptimizationCameraCalibrator
public abstract class CameraCalibrator extends Object
Calibrates a camera in order to find its intrinsic parameters and other parameters such as radial distortion.

  • Field Details

    • DEFAULT_HOMOGRAPHY_METHOD

      public static final com.irurueta.numerical.robust.RobustEstimatorMethod DEFAULT_HOMOGRAPHY_METHOD
      Default robust estimator method to be used for homography estimations.

    • DEFAULT_IAC_METHOD

      public static final com.irurueta.numerical.robust.RobustEstimatorMethod DEFAULT_IAC_METHOD
      Default robust estimator method to be used for IAC estimation.

    • DEFAULT_ESTIMATE_RADIAL_DISTORTION

      public static final boolean DEFAULT_ESTIMATE_RADIAL_DISTORTION
      Indicates whether radial distortion must be estimated or not by default.
      See Also:

    • DEFAULT_PROGRESS_DELTA

      public static final float DEFAULT_PROGRESS_DELTA
      Default amount of progress variation before notifying a change in estimation progress. By default, this is set to 5%.
      See Also:

    • MIN_PROGRESS_DELTA

      public static final float MIN_PROGRESS_DELTA
      Minimum allowed value for progress delta.
      See Also:

    • MAX_PROGRESS_DELTA

      public static final float MAX_PROGRESS_DELTA
      Maximum allowed value for progress delta.
      See Also:

    • DEFAULT_METHOD

      public static final CameraCalibratorMethod DEFAULT_METHOD
      Default method used for camera calibration. The default method uses an alternating technique where first intrinsic parameters and camera pose are estimated without accounting for distortion and then the results are used to obtain an initial guess for distortion, which is then used to correct initially sampled points and repeat the whole process until convergence is achieved.

    • pattern

      protected Pattern2D pattern
      Pattern used for camera calibration. Each pattern contains a unique combination of 2D points that must be sampled using the camera to be calibrated.

    • samples

      protected List<CameraCalibratorSample> samples
      List of samples obtained from different pictures using the same camera device (or same camera model). Several samples can be used to calibrate the camera. The more samples are used, typically the better the results.

    • samplesQualityScores

      protected double[] samplesQualityScores
      Quality scores for samples. This can be used on certain robust estimation methods of the IAC such as PROSAC and PROMedS. If not provided, homography quality scores will be estimated based on re-projection error and this value will be ignored. Typically, this will not be provided, but it can be used in case that it can be assured by some means that one sample is better than another.

    • homographies

      protected List<com.irurueta.geometry.Transformation2D> homographies
      Estimated homographies from provided list of samples respect to provided pattern.

    • homographyQualityScores

      protected double[] homographyQualityScores
      Quality scores for estimated homographies to be used during IAC estimation when PROSAC or PROMedS robust method is used. This value is only computed when no samples quality scores are provided. Homography quality scores are obtained based on re-projection error of marker coordinates.

    • homographyQualityScoresRequired

      protected boolean homographyQualityScoresRequired
      Indicates whether homography quality scores need to be estimated if samples quality scores are not provided.

    • iac

      protected ImageOfAbsoluteConic iac
      Estimated image of absolute conic. This can be used to obtain intrinsic pinhole camera intrinsic parameters.

    • intrinsic

      protected com.irurueta.geometry.PinholeCameraIntrinsicParameters intrinsic
      Estimated intrinsic pinhole camera parameters. Intrinsic parameters contain data related to the camera sensor such as focal length, skewness or principal point. Except focal length, typically intrinsic parameters are fixed, and even in some situations such as when camera lens is fixed, focal length also remains constant. Because the latter is true in most phone cameras, it can be considered that intrinsic parameters remain constant for all phones of the same maker and model, and for that reason a calibrator can be used with pictures taken from different phones as long as they are the same phone model.

    • distortion

      protected RadialDistortion distortion
      Estimated radial distortion. Radial distortion is inherent to the camera lens, and remains constant as long as the lens doesn't change. Because in most phone cameras the lens remains constant, lens distortion can be modeled once for each phone model, and for that reason a single calibrator can be used with pictures taken from different phones as long as they are the same phone model.

    • estimateRadialDistortion

      protected boolean estimateRadialDistortion
      Indicates whether radial distortion must be estimated or not.

    • homographyMethod

      protected com.irurueta.numerical.robust.RobustEstimatorMethod homographyMethod
      Robust estimator method to be used during homography estimation. This will only be taken into account if more than 4 markers are detected on a single sample, otherwise no robust method is used and a single LMSE solution for the homography is found.

    • imageOfAbsoluteConicMethod

      protected com.irurueta.numerical.robust.RobustEstimatorMethod imageOfAbsoluteConicMethod
      Robust estimator method to be used during IAC estimation. This will only be taken into account if more than 1 sample is provided, otherwise no robust method is used and a single LMSE solution for the IAC is found.

    • homographyEstimator

      protected com.irurueta.geometry.estimators.PointCorrespondenceProjectiveTransformation2DRobustEstimator homographyEstimator
      Robust estimator of homographies between sampled markers and ideal pattern markers.

    • iacEstimator

      protected ImageOfAbsoluteConicRobustEstimator iacEstimator
      Robust estimator of the Image of Absolute Conic (IAC).

    • homographyEstimatorListener

      protected com.irurueta.geometry.estimators.ProjectiveTransformation2DRobustEstimatorListener homographyEstimatorListener
      Listener for homography estimator.

    • iacEstimatorListener

      protected ImageOfAbsoluteConicRobustEstimatorListener iacEstimatorListener
      Listener for image of absolute conic estimator.

    • locked

      protected volatile boolean locked
      Indicates whether this instance is locked because calibration is in progress.

    • progressDelta

      protected float progressDelta
      Amount of progress variation before notifying a progress change during estimation.

    • listener

      protected CameraCalibratorListener listener
      Listener to notify when calibration starts, finishes or its progress significantly changes.

    • homographyProgress

      protected float homographyProgress
      Indicates progress of homography estimation.

    • sampleProgress

      protected float sampleProgress
      Indicates progress of homography estimation for all samples.

    • iacProgress

      protected float iacProgress
      Indicates progress of IAC estimation.

    • intrinsicProgress

      protected float intrinsicProgress
      Indicates progress of estimation of intrinsic parameters.

  • Constructor Details

    • CameraCalibrator

      protected CameraCalibrator()
      Constructor.

    • CameraCalibrator

      protected CameraCalibrator(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.

    • CameraCalibrator

      protected CameraCalibrator(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

    • getPattern

      public Pattern2D getPattern()
      Returns pattern used for camera calibration. Each pattern contain a unique combination of 2D points that must be sampled using the camera to be calibrated.
      Returns:
      pattern used for camera calibration.

    • setPattern

      public void setPattern(Pattern2D pattern) throws com.irurueta.geometry.estimators.LockedException
      Sets pattern used for camera calibration. Each pattern contains a unique combination of 2D points that must be sampled using the camera to be calibrated.
      Parameters:
      pattern - pattern used for camera calibration.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • getSamples

      public List<CameraCalibratorSample> getSamples()
      Returns list of samples obtained from different pictures using the same camera device (or same camera model). Several samples can be used to calibrate the camera (a pinhole camera can be estimated for each sample). The more samples are used, typically the better the results.
      Returns:
      list of samples.

    • setSamples

      public void setSamples(List<CameraCalibratorSample> samples) throws com.irurueta.geometry.estimators.LockedException
      Sets list of samples obtained from different pictures using the same camera device (or same camera model). Several samples can be used to calibrate the camera (a pinhole camera can be estimated for each sample). The more samples are used, typically the better the results.
      Parameters:
      samples - list of samples.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if not enough samples are provided to estimate the intrinsic parameters. By default, the minimum is 1, but depending on the settings at least 3 samples might be required.

    • getSamplesQualityScores

      public double[] getSamplesQualityScores()
      Returns quality scores assigned to each provided sample. This can be used on certain robust estimation methods of the IAC such as PROSAC and PROMedS. If not provided, homography quality scores will be estimated based on re-projection error and this value will be ignored. Typically, this will not be provided, but it can be used in case that it can be assured by some means that one sample is better than another
      Returns:
      quality scores assigned to each provided sample.

    • setSamplesQualityScores

      public void setSamplesQualityScores(double[] samplesQualityScores) throws com.irurueta.geometry.estimators.LockedException
      Sets quality scores assigned to each provided sample. This can be used on certain robust estimation methods of the IAC such as PROSAC and PROMedS. If not provided, homography quality scores will be estimated based on re-projection error and this value will be ignored.
      Parameters:
      samplesQualityScores - quality scores assigned to each provided sample.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if not enough quality scores are provided for the corresponding samples to estimate the intrinsic parameters. By default, the minimum is 1, but depending on the settings at least 3 samples might be required.

    • getHomographyQualityScores

      public double[] getHomographyQualityScores()
      Returns quality scores for estimated homographies. If samples quality scores were provided, these will be equal to those provided. If no samples quality scores were provided, these scores will be related to the estimated homography estimation error based on sampled data and ideal data. This should rarely be used. It can be used for debugging purposes teo determine whether homographies used for calibration are reliable or not.
      Returns:
      estimated quality scores for homographies.

    • getEstimatedImageOfAbsoluteConic

      public ImageOfAbsoluteConic getEstimatedImageOfAbsoluteConic()
      Returns estimated image of absolute conic. This can be used to obtain intrinsic pinhole camera intrinsic parameters.
      Returns:
      estimated image of absolute conic or null if estimation has not been completed.

    • getEstimatedIntrinsicParameters

      public com.irurueta.geometry.PinholeCameraIntrinsicParameters getEstimatedIntrinsicParameters()
      Returns estimated pinhole camera intrinsic parameters.
      Returns:
      estimated pinhole camera intrinsic parameters or null if estimation has not been completed.

    • getDistortion

      public RadialDistortion getDistortion()
      Returns estimated radial distortion due to camera lens.
      Returns:
      estimated radial distortion or null if estimation has not completed or radial distortion was not requested.

    • getEstimateRadialDistortion

      public boolean getEstimateRadialDistortion()
      Returns boolean indicating whether radial distortion must be estimated or not during calibration.
      Returns:
      true if radial distortion must be estimated, false otherwise.

    • setEstimateRadialDistortion

      public void setEstimateRadialDistortion(boolean estimateRadialDistortion) throws com.irurueta.geometry.estimators.LockedException
      Sets boolean indicating whether radial distortion must be estimated or not during calibration.
      Parameters:
      estimateRadialDistortion - true if radial distortion must be estimated, false otherwise.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • getHomographyMethod

      public com.irurueta.numerical.robust.RobustEstimatorMethod getHomographyMethod()
      Returns robust estimator method to be used during homography estimation. This will only be taken into account if more than 4 markers are detected on a single sample, otherwise no robust method is used and a single LMSE solution for the homography is found.
      Returns:
      robust estimator method to be used during homography estimation.

    • setHomographyMethod

      public void setHomographyMethod(com.irurueta.numerical.robust.RobustEstimatorMethod homographyMethod) throws com.irurueta.geometry.estimators.LockedException
      Sets robust estimator method to be used during homography estimation. This will only be taken into account if more than 4 markers are detected on a single sample, otherwise no robust method is used and a single LMSE solution for the homography is found.
      Parameters:
      homographyMethod - robust estimator method to be used during homography estimation.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • getImageOfAbsoluteConicMethod

      public com.irurueta.numerical.robust.RobustEstimatorMethod getImageOfAbsoluteConicMethod()
      Returns robust estimator method to be used during IAC estimation. This will only be taken into account if more than 1 sample is provided, otherwise no robust method is used and a single LMSE solution for the IAC is found
      Returns:
      robust estimator method to be used during IAC estimation

    • setImageOfAbsoluteConicMethod

      public void setImageOfAbsoluteConicMethod(com.irurueta.numerical.robust.RobustEstimatorMethod imageOfAbsoluteConicMethod) throws com.irurueta.geometry.estimators.LockedException
      Sets robust estimator method to be used during IAC estimation. This will only be taken into account if more than 1 sample is provided, otherwise no robust method is used and a single LMSE solution for the IAC is found.
      Parameters:
      imageOfAbsoluteConicMethod - robust estimator method to be used during IAC estimation.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • getHomographyEstimator

      public com.irurueta.geometry.estimators.PointCorrespondenceProjectiveTransformation2DRobustEstimator getHomographyEstimator()
      Returns homography estimator, which can be retrieved in case that some additional parameter needed to be adjusted. It is discouraged to directly access the homography estimator during camera calibration, as it might interfere with the results.
      Returns:
      homography estimator.

    • getIACEstimator

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

    • isZeroSkewness

      public boolean isZeroSkewness()
      Returns boolean indicating whether camera skewness is assumed to be zero or not. Skewness determines whether LCD sensor cells are properly aligned or not, where zero indicates perfect alignment. Typically, skewness is a value equal or very close to zero.
      Returns:
      true if camera skewness is assumed to be zero, otherwise camera skewness is estimated.

    • setZeroSkewness

      public void setZeroSkewness(boolean zeroSkewness) throws com.irurueta.geometry.estimators.LockedException
      Sets boolean indicating whether camera skewness is assumed to be zero or not. Skewness determines whether LCD sensor cells are properly aligned or not, where zero indicates perfect alignment. Typically, skewness is a value equal or very close to zero.
      Parameters:
      zeroSkewness - true if camera skewness is assumed to be zero, otherwise camera skewness is estimated.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • isPrincipalPointAtOrigin

      public boolean isPrincipalPointAtOrigin()
      Returns boolean indicating whether principal point is assumed to be at origin of coordinates or not. Typically principal point is located at image center (origin of coordinates), and usually matches the center of radial distortion if it is taken into account.
      Returns:
      true if principal point is assumed to be at origin of coordinates, false if principal point must be estimated.

    • setPrincipalPointAtOrigin

      public void setPrincipalPointAtOrigin(boolean principalPointAtOrigin) throws com.irurueta.geometry.estimators.LockedException
      Sets boolean indicating whether principal point is assumed to be at origin of coordinates or not. Typically principal point is located at image center (origin of coordinates), and usually matches the center of radial distortion if it is taken into account.
      Parameters:
      principalPointAtOrigin - true if principal point is assumed to bet at origin of coordinates, false if principal point must be estimated.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • isFocalDistanceAspectRatioKnown

      public boolean isFocalDistanceAspectRatioKnown()
      Returns boolean indicating whether aspect ratio of focal distances (i.e. vertical focal distance divided by horizontal focal distance) is known or not. Notice that focal distance aspect ratio is not related to image size aspect ratio. Typically, LCD sensor cells are square and hence aspect ratio of focal distances is known and equal to 1. This value is only taken into account if skewness is assumed to be zero, otherwise it is ignored.
      Returns:
      true if focal distance aspect ratio is known, false otherwise.

    • setFocalDistanceAspectRatioKnown

      public void setFocalDistanceAspectRatioKnown(boolean focalDistanceAspectRatioKnown) throws com.irurueta.geometry.estimators.LockedException
      Sets boolean indicating whether aspect ratio of focal distances (i.e. vertical focal distance divided by horizontal focal distance) is known or not. Notice that focal distance aspect ratio is not related to image size aspect ratio. Typically, LCD sensor cells are square and hence aspect ratio of focal distances is known and equal to 1. This value is only taken into account if skewness is assumed to be zero, otherwise it is ignored.
      Parameters:
      focalDistanceAspectRatioKnown - true if focal distance aspect ratio is known, false otherwise.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • getFocalDistanceAspectRatio

      public double getFocalDistanceAspectRatio()
      Returns aspect ratio of focal distances (i.e. vertical focal distance divided by horizontal focal distance). This value is only taken into account if skewness is assumed to be zero and focal distance aspect ratio is marked as known, otherwise it is ignored. By default, this is 1.0, since it is taken into account that typically LCD sensor cells are square and hence aspect ratio focal distances is known and equal to 1. Notice that focal distance aspect ratio is not related to image size aspect ratio. Notice that a negative aspect ratio indicates that vertical axis is reversed. This can be useful in some situations where image vertical coordinates are reversed respect to the physical world (i.e. in computer graphics typically image vertical coordinates go downwards, while in physical world they go upwards).
      Returns:
      aspect ratio of focal distances.

    • setFocalDistanceAspectRatio

      public void setFocalDistanceAspectRatio(double focalDistanceAspectRatio) throws com.irurueta.geometry.estimators.LockedException
      Sets aspect ratio of focal distances (i.e. vertical focal distance divided by horizontal focal distance). This value is only taken into account if skewness is assumed to be zero and focal distance aspect ratio is marked as known, otherwise it is ignored. By default, this is 1.0, since it is taken into account that typically LCD sensor cells are square and hence aspect ratio focal distances is known and equal to 1. Notice that focal distance aspect ratio is not related to image size aspect ratio. Notice that a negative aspect ratio indicates that vertical axis is reversed. This can be useful in some situations where image vertical coordinates are reversed respect to the physical world (i.e. in computer graphics typically image vertical coordinates go downwards, while in physical world they go upwards).
      Parameters:
      focalDistanceAspectRatio - aspect ratio of focal distances to be set.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.
      IllegalArgumentException - if focal distance aspect ratio is too close to zero, as it might produce numerical instabilities.

    • isLocked

      public boolean isLocked()
      Indicates whether this instance is locked because calibration is in progress.
      Returns:
      true if this instance, false otherwise.

    • getProgressDelta

      public float getProgressDelta()
      Returns amount of progress variation before notifying a progress change during estimation.
      Returns:
      amount of progress variation before notifying a progress change during estimation.

    • setProgressDelta

      public void setProgressDelta(float progressDelta) throws com.irurueta.geometry.estimators.LockedException
      Sets amount of progress variation before notifying a progress change during estimation.
      Parameters:
      progressDelta - amount of progress variation before notifying a progress change during estimation.
      Throws:
      IllegalArgumentException - if progress delta is less than zero or greater than 1.
      com.irurueta.geometry.estimators.LockedException - if this estimator is locked because an estimation is being computed.

    • isReady

      public boolean isReady()
      Indicates whether this instance is ready to start camera calibration
      Returns:
      true if this instance has enough data to start camera calibration, false otherwise.

    • getHomographyEstimatorThreshold

      public double getHomographyEstimatorThreshold()
      Returns threshold to robustly estimate homographies between ideal pattern markers and sampled pattern markers. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments
      Returns:
      threshold to robustly estimate homographies between ideal pattern markers and sampled pattern markers.

    • setHomographyEstimatorThreshold

      public void setHomographyEstimatorThreshold(double homographyEstimatorThreshold) throws com.irurueta.geometry.estimators.LockedException
      Sets threshold to robustly estimate homographies between ideal pattern markers and sampled pattern markers. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments.
      Parameters:
      homographyEstimatorThreshold - threshold to robustly estimate homographies between ideal pattern markers and sampled pattern markers.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is zero or negative.

    • getHomographyEstimatorConfidence

      public double getHomographyEstimatorConfidence()
      Returns confidence to robustly estimate homographies between ideal pattern markers and sampled pattern markers. 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.

    • setHomographyEstimatorConfidence

      public void setHomographyEstimatorConfidence(double homographyEstimatorConfidence) throws com.irurueta.geometry.estimators.LockedException
      Sets confidence to robustly estimate homographies between ideal pattern markers and sampled pattern markers. 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:
      homographyEstimatorConfidence - confidence to robustly estimate homographies.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is not between 0.0 and 1.0.

    • getHomographyEstimatorMaxIterations

      public int getHomographyEstimatorMaxIterations()
      Returns the maximum number of iterations to be done when estimating the homographies between ideal pattern markers and sampled pattern markers. 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.

    • setHomographyEstimatorMaxIterations

      public void setHomographyEstimatorMaxIterations(int homographyEstimatorMaxIterations) throws com.irurueta.geometry.estimators.LockedException
      Sets the maximum number of iterations to be done when estimating the homographies between ideal pattern markers and sampled pattern markers. 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:
      homographyEstimatorMaxIterations - maximum number of iterations to be done when estimating the homographies between ideal pattern markers and sampled pattern markers.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is negative or zero.

    • getIACEstimatorThreshold

      public double getIACEstimatorThreshold()
      Returns threshold to robustly estimate the image of absolute conic. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments.
      Returns:
      threshold to robustly estimate the image of absolute conic.

    • setIACEstimatorThreshold

      public void setIACEstimatorThreshold(double iacEstimatorThreshold) throws com.irurueta.geometry.estimators.LockedException
      Sets threshold to robustly estimate the image of absolute conic. Usually the default value is good enough for most situations, but this setting can be changed for finer adjustments.
      Parameters:
      iacEstimatorThreshold - threshold to robustly estimate the image of absolute conic.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is zero or negative.

    • getIACEstimatorConfidence

      public double getIACEstimatorConfidence()
      Returns confidence to robustly estimate image of absolute conic 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 the IAC.

    • setIACEstimatorConfidence

      public void setIACEstimatorConfidence(double iacEstimatorConfidence) throws com.irurueta.geometry.estimators.LockedException
      Sets confidence to robustly estimate image of absolute conic. 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:
      iacEstimatorConfidence - confidence to robustly estimate the IAC.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is not between 0.0 and 1.0.

    • getIACEstimatorMaxIterations

      public int getIACEstimatorMaxIterations()
      Returns the maximum number of iterations to be done when estimating the image of absolute conic. 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 image of absolute conic.

    • setIACEstimatorMaxIterations

      public void setIACEstimatorMaxIterations(int iacEstimatorMaxIterations) throws com.irurueta.geometry.estimators.LockedException
      Sets the maximum number of iterations to be done when estimating the image of absolute conic. 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:
      iacEstimatorMaxIterations - maximum number of iterations to be done when estimating the image of absolute conic.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.
      IllegalArgumentException - if provided value is negative or zero.

    • getListener

      public CameraCalibratorListener getListener()
      Returns listener to notify when calibration starts, finishes or its progress significantly changes.
      Returns:
      listener to notify when calibration starts, finishes or its progress significantly changes.

    • setListener

      public void setListener(CameraCalibratorListener listener) throws com.irurueta.geometry.estimators.LockedException
      Sets listener to notify when calibration starts, finishes or its progress significantly changes.
      Parameters:
      listener - listener to notify when calibration starts, finishes or its progress significantly changes.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if this instance is locked.

    • create

      public static CameraCalibrator create(CameraCalibratorMethod method)
      Creates a camera calibrator using provided method.
      Parameters:
      method - a camera calibrator method.
      Returns:
      a camera calibrator.

    • create

      public static CameraCalibrator create(Pattern2D pattern, List<CameraCalibratorSample> samples, CameraCalibratorMethod method)
      Creates a camera calibrator using provided pattern, samples and method.
      Parameters:
      pattern - a 2D pattern to use for calibration.
      samples - samples of the 2D pattern taken with the camera to be calibrated.
      method - a camera calibrator method.
      Returns:
      a camera calibrator.
      Throws:
      IllegalArgumentException - if not enough samples are provided.

    • create

      public static CameraCalibrator create(Pattern2D pattern, List<CameraCalibratorSample> samples, double[] samplesQualityScores, CameraCalibratorMethod method)
      Creates a camera calibrator using provided pattern, samples and method.
      Parameters:
      pattern - a 2D pattern to use for calibration.
      samples - samples of the 2D pattern taken with the camera to be calibrated.
      samplesQualityScores - quality scores for each sample.
      method - a camera calibrator method.
      Returns:
      a camera calibrator.
      Throws:
      IllegalArgumentException - if not enough samples are provided.

    • create

      public static CameraCalibrator create()
      Creates a camera calibrator using default method.
      Returns:
      a camera calibrator.

    • create

      public static CameraCalibrator create(Pattern2D pattern, List<CameraCalibratorSample> samples)
      Creates a camera calibrator using provided pattern, samples and default method.
      Parameters:
      pattern - a 2D pattern to use for calibration.
      samples - samples of the 2D pattern taken with the camera to be calibrated.
      Returns:
      a camera calibrator.
      Throws:
      IllegalArgumentException - if not enough samples are provided.

    • create

      public static CameraCalibrator create(Pattern2D pattern, List<CameraCalibratorSample> samples, double[] samplesQualityScores)
      Creates a camera calibrator using provided pattern, samples and default method.
      Parameters:
      pattern - a 2D pattern to use for calibration.
      samples - samples of the 2D pattern taken with the camera to be calibrated.
      samplesQualityScores - quality scores for each sample.
      Returns:
      a camera calibrator.
      Throws:
      IllegalArgumentException - if not enough samples are provided.

    • calibrate

      public abstract 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.
      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 abstract CameraCalibratorMethod getMethod()
      Returns the camera calibrator method used by this instance.
      Returns:
      the camera calibrator method.

    • notifyProgress

      protected abstract void notifyProgress()
      Notifies progress to current listener, if needed.

    • computeIntrinsicProgress

      protected void computeIntrinsicProgress()
      Computes intrinsic estimation progress.

    • reset

      protected void reset()
      Resets estimated value to their initial values.

    • estimateIntrinsicParameters

      protected void estimateIntrinsicParameters(List<com.irurueta.geometry.Point2D> idealFallbackPatternMarkers) throws CalibrationException
      Estimates pinhole camera intrinsic parameters without accounting for lens radial distortion.
      Parameters:
      idealFallbackPatternMarkers - ideal pattern markers coordinates used as fallback if pattern is not provided for a given sample.
      Throws:
      CalibrationException - if calibration fails for some reason.

    • homographyTransformationError

      protected static double homographyTransformationError(com.irurueta.geometry.Transformation2D homography, List<com.irurueta.geometry.Point2D> idealPatternMarkers, List<com.irurueta.geometry.Point2D> sampledPatternMarkers)
      Computes average transformation error as a result of comparing sampled pattern markers against the transformation of ideal pattern markers using the estimated homography.
      Parameters:
      homography - estimated homography.
      idealPatternMarkers - ideal pattern markers.
      sampledPatternMarkers - sampled pattern markers.
      Returns:
      average re-projection error.

    • refreshHomographyEstimatorListener

      protected void refreshHomographyEstimatorListener()
      Refreshes listener of homography estimator.

    • refreshIACEstimatorListener

      protected void refreshIACEstimatorListener()
      Refreshes listener of IAC estimator.

    • internalSetSamples

      private void internalSetSamples(List<CameraCalibratorSample> samples)
      Internal method to set list of samples obtained from different pictures using the same camera device (or same camera model). Several samples can be used to calibrate the camera (a pinhole camera can be estimated for each sample). The more samples are used, typically the better the results. This method is for internal use only and does not check whether this instance is locked or not.
      Parameters:
      samples - list of samples.
      Throws:
      IllegalArgumentException - if not enough samples are provided to estimate the intrinsic parameters. By default, the minimum is 1, but depending on the settings at least 3 samples might be required.

    • internalSetSamplesQualityScores

      private void internalSetSamplesQualityScores(double[] samplesQualityScores)
      Sets quality scores assigned to each provided sample. This can be used on certain robust estimation methods of the IAC such as PROSAC and PROMedS. If not provided, homography quality scores will be estimated based on re-projection error and this value will be ignored. This method is for internal use only and does not check whether this instance is locked or not.
      Parameters:
      samplesQualityScores - quality scores assigned to each provided sample.
      Throws:
      IllegalArgumentException - if not enough quality scores are provided for the corresponding samples to estimate the intrinsic parameters. By default, the minimum is 1, but depending on the settings at least 3 samples might be required.

    • internalSetHomographyMethod

      private void internalSetHomographyMethod(com.irurueta.numerical.robust.RobustEstimatorMethod homographyMethod)
      Sets robust homography estimation method. If method changes, then a new homography robust estimator is created and configured.
      Parameters:
      homographyMethod - robust homography estimation method to be set.

    • internalSetImageOfAbsoluteConicMethod

      private void internalSetImageOfAbsoluteConicMethod(com.irurueta.numerical.robust.RobustEstimatorMethod imageOfAbsoluteConicMethod)
      Sets robust IAC estimation method. IF method changes, then a new IAC robust estimator is created and configured
      Parameters:
      imageOfAbsoluteConicMethod - robust IAC estimation method to be set