Package com.irurueta.ar.calibration.estimators

Class ImageOfAbsoluteConicEstimator

java.lang.Object
com.irurueta.ar.calibration.estimators.ImageOfAbsoluteConicEstimator
Direct Known Subclasses:
LMSEImageOfAbsoluteConicEstimator, WeightedImageOfAbsoluteConicEstimator
public abstract class ImageOfAbsoluteConicEstimator extends Object
This class defines the interface for an estimator of the Image of Absolute Conic (IAC). The IAC is directly related to pinhole camera intrinsic parameters, implementations of this estimator can be used for camera calibration purposes. Depending on the constraints imposed on the intrinsic parameters of the camera, some parameters of the IAC will be known in advance and fewer equations will be needed. If no constraints are imposed, then at least 5 equations will be needed to estimate the DIAC, and hence 3 homographies will be required (2 equations can be obtained for each homography). 2*n <= 5 ==< n <= 5/2 ==< n <= 2.5 ==< n <= 3 If skewness is assumed to be known and zero, then one less homography is required, hence only 2 homographies will be needed. 2*n + 1 <= 5 ==< n <= 4 / 2 ==< n <= 2 If also principal point is assumed to be known and located at image center (origin of coordinates), then 2 fewer equations are needed, and hence only 1 homography is needed: 2n + 1 + 2 <= 5 ==< n <= 2 / 2 ==< n <= 1 By enabling constraints, results are guaranteed to be more stable (estimation fails fewer times with an exception) and more accurate, so whenever possible constraints should be enabled. The principal point at origin introduces more stability and accuracy than the skewness constraint, but if possible both should be enabled. By default, both constraints are enable.

  • Field Details

    • MIN_REQUIRED_EQUATIONS

      protected static final int MIN_REQUIRED_EQUATIONS
      Minimum number of required equations to solve the IAC linear system of equations.
      See Also:

    • DEFAULT_ZERO_SKEWNESS

      public static final boolean DEFAULT_ZERO_SKEWNESS
      Constant defining whether zero skewness is assumed.
      See Also:

    • DEFAULT_PRINCIPAL_POINT_AT_ORIGIN

      public static final boolean DEFAULT_PRINCIPAL_POINT_AT_ORIGIN
      Constant defining whether principal point is assumed to be at origin of coordinates.
      See Also:

    • DEFAULT_FOCAL_DISTANCE_ASPECT_RATIO_KNOWN

      public static final boolean DEFAULT_FOCAL_DISTANCE_ASPECT_RATIO_KNOWN
      Constant defining 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.
      See Also:

    • DEFAULT_FOCAL_DISTANCE_ASPECT_RATIO

      public static final double DEFAULT_FOCAL_DISTANCE_ASPECT_RATIO
      Constant defining default aspect ratio of focal distances. This constant takes into account that typically LCD sensor cells are square and hence aspect ratio of focal distances is known and equal to 1.
      See Also:

    • MIN_ABS_FOCAL_DISTANCE_ASPECT_RATIO

      public static final double MIN_ABS_FOCAL_DISTANCE_ASPECT_RATIO
      Minimum absolute value allowed for aspect ratio of focal distances.
      See Also:

    • DEFAULT_ESTIMATOR_TYPE

      public static final ImageOfAbsoluteConicEstimatorType DEFAULT_ESTIMATOR_TYPE
      Default estimator type.

    • zeroSkewness

      protected boolean zeroSkewness
      Indicates whether camera skewness is assumed to be zero or not.

    • principalPointAtOrigin

      protected boolean principalPointAtOrigin
      Indicates whether principal point is assumed to be at origin of coordinates or not. If false, the principal point will be estimated, otherwise it will be assumed to be at image center (i.e. origin of coordinates).

    • focalDistanceAspectRatioKnown

      protected boolean focalDistanceAspectRatioKnown
      Indicates 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.

    • focalDistanceAspectRatio

      protected double focalDistanceAspectRatio
      Contains 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.

    • locked

      protected boolean locked
      True when estimator is estimating IAC.

    • listener

      protected ImageOfAbsoluteConicEstimatorListener listener
      Listener to be notified of events such as when estimation starts, ends or estimation progress changes.

    • homographies

      protected List<com.irurueta.geometry.Transformation2D> homographies
      List of homographies (2D transformations) used to estimate the image of absolute conic (IAC), which can be used to obtain pinhole camera intrinsic parameters.

  • Constructor Details

    • ImageOfAbsoluteConicEstimator

      protected ImageOfAbsoluteConicEstimator()
      Constructor.

    • ImageOfAbsoluteConicEstimator

      protected ImageOfAbsoluteConicEstimator(ImageOfAbsoluteConicEstimatorListener listener)
      Constructor with listener.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or estimation progress changes.

    • ImageOfAbsoluteConicEstimator

      protected ImageOfAbsoluteConicEstimator(List<com.irurueta.geometry.Transformation2D> homographies)
      Constructor.
      Parameters:
      homographies - list of homographies (2D transformations) used to estimate the image of absolute conic (IAC), which can be used to obtain pinhole camera intrinsic parameters.
      Throws:
      IllegalArgumentException - if not enough homographies are provided for default settings. Hence, at least 1 homography must be provided.

    • ImageOfAbsoluteConicEstimator

      protected ImageOfAbsoluteConicEstimator(List<com.irurueta.geometry.Transformation2D> homographies, ImageOfAbsoluteConicEstimatorListener listener)
      Constructor.
      Parameters:
      homographies - list of homographies (2D transformations) used to estimate the image of absolute conic (IAC), which can be used to obtain pinhole camera intrinsic parameters.
      listener - listener to be notified of events such as when estimation starts, ends or estimation progress changes.
      Throws:
      IllegalArgumentException - if not enough homographies are provided for default settings. Hence, at least 1 homography must be provided.

  • Method Details

    • 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 estimator 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 be 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 value 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.
      Returns:
      true if this estimator is busy estimating an IAC, false otherwise.

    • getListener

      public ImageOfAbsoluteConicEstimatorListener getListener()
      Returns listener to be notified of events such as when estimation starts, ends or estimation progress changes.
      Returns:
      listener to be notified of events.

    • setListener

      public void setListener(ImageOfAbsoluteConicEstimatorListener listener) throws com.irurueta.geometry.estimators.LockedException
      Sets listener to be notified of events such as when estimation starts, ends or estimation progress changes.
      Parameters:
      listener - listener to be notified of events.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.

    • getHomographies

      public List<com.irurueta.geometry.Transformation2D> getHomographies()
      Gets list of homographies to estimate IAC.
      Returns:
      list of homographies to estimate IAC.

    • setHomographies

      public void setHomographies(List<com.irurueta.geometry.Transformation2D> homographies) throws com.irurueta.geometry.estimators.LockedException
      Sets list of homographies to estimate IAC.
      Parameters:
      homographies - list of homographies to estimate IAC.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.
      IllegalArgumentException - if provided list of homographies does not contain enough elements to estimate the IAC using current settings.

    • getMinNumberOfRequiredHomographies

      public int getMinNumberOfRequiredHomographies()
      Returns minimum number of required homographies needed to estimate the Image of Absolute Conic (IAC). If no constraints are imposed, then at least 3 homographies are required. For each constraint imposed, one less equation will be required, hence if skewness is assumed to be known (by using its typical value of zero), then only 4 equations will be needed (2 homographies). If also the horizontal and vertical coordinates of the principal point are assumed to be known (by being placed at the 2D origin of coordinates, which is a typical value), then only 2 equations will be needed (1 homography).
      Returns:
      minimum number of required homographies required to estimate the IAC

    • isReady

      public boolean isReady()
      Returns value indicating whether required data has been provided so that IAC estimation can start. If true, estimator is ready to compute the IAC, otherwise more data needs to be provided.
      Returns:
      true if estimator is ready, false otherwise.

    • estimate

      public abstract ImageOfAbsoluteConic estimate() throws com.irurueta.geometry.estimators.LockedException, com.irurueta.geometry.estimators.NotReadyException, ImageOfAbsoluteConicEstimatorException
      Estimates Image of Absolute Conic (IAC).
      Returns:
      estimated IAC.
      Throws:
      com.irurueta.geometry.estimators.LockedException - if estimator is locked.
      com.irurueta.geometry.estimators.NotReadyException - if input has not yet been provided.
      ImageOfAbsoluteConicEstimatorException - if an error occurs during estimation, usually because repeated homographies are provided, or homographies corresponding to degenerate camera movements such as pure parallel translations where no additional data is really provided. Indeed, if provided homographies belong to the group of affine transformations (or other groups contained within such as metric or Euclidean ones), this exception will raise because camera movements will be degenerate. To avoid this exception, homographies must be purely projective.

    • getType

      public abstract ImageOfAbsoluteConicEstimatorType getType()
      Returns type of IAC estimator.
      Returns:
      type of IAC estimator.

    • create

      public static ImageOfAbsoluteConicEstimator create()
      Creates an instance of an IAC estimator using provided default type.
      Returns:
      an instance of an IAC estimator.

    • create

      public static ImageOfAbsoluteConicEstimator create(ImageOfAbsoluteConicEstimatorListener listener)
      Creates an instance of an IAC estimator using provided listener and default type.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or estimation progress changes.
      Returns:
      an instance of an IAC estimator.

    • create

      public static ImageOfAbsoluteConicEstimator create(List<com.irurueta.geometry.Transformation2D> homographies)
      Creates an instance of an IAC estimator using provided homographies
      Parameters:
      homographies - list of homographies (2D transformations) used to estimate the image of absolute conic (IAC), which can be used to obtain pinhole camera intrinsic parameters.
      Returns:
      an instance of an IAC estimator.
      Throws:
      IllegalArgumentException - if not enough homographies are provided for default IAC estimation constraints.

    • create

      public static ImageOfAbsoluteConicEstimator create(List<com.irurueta.geometry.Transformation2D> homographies, ImageOfAbsoluteConicEstimatorListener listener)
      Creates an instance of an IAC estimator using provided homographies and listener.
      Parameters:
      homographies - list of homographies (2D transformations) used to estimate the image of absolute conic (IAC), which can be used to obtain pinhole camera intrinsic parameters.
      listener - listener to be notified of events such as when estimation starts, ends or estimation progress changes.
      Returns:
      an instance of an IAC estimator.
      Throws:
      IllegalArgumentException - if not enough homographies are provided for default IAC estimation constraints.

    • create

      public static ImageOfAbsoluteConicEstimator create(ImageOfAbsoluteConicEstimatorType type)
      Creates an instance of an IAC estimator using provided type.
      Parameters:
      type - type of IAC estimator to create.
      Returns:
      an instance of an IAC estimator.

    • create

      public static ImageOfAbsoluteConicEstimator create(ImageOfAbsoluteConicEstimatorListener listener, ImageOfAbsoluteConicEstimatorType type)
      Creates an instance of an IAC estimator using provided listener and type.
      Parameters:
      listener - listener to be notified of events such as when estimation starts, ends or estimation progress changes.
      type - type of IAC estimator to create.
      Returns:
      an instance of an IAC estimator.

    • create

      public static ImageOfAbsoluteConicEstimator create(List<com.irurueta.geometry.Transformation2D> homographies, ImageOfAbsoluteConicEstimatorType type)
      Creates an instance of an IAC estimator using provided homographies and type.
      Parameters:
      homographies - list of homographies (2D transformations) used to estimate the image of absolute conic (IAC), which can be used to obtain pinhole camera intrinsic parameters.
      type - type of IAC estimator to create.
      Returns:
      an instance of an IAC estimator.
      Throws:
      IllegalArgumentException - if not enough homographies are provided for default IAC estimation constraints.

    • create

      public static ImageOfAbsoluteConicEstimator create(List<com.irurueta.geometry.Transformation2D> homographies, ImageOfAbsoluteConicEstimatorListener listener, ImageOfAbsoluteConicEstimatorType type)
      Creates an instance of an IAC estimator using provided homographies, listener and type.
      Parameters:
      homographies - list of homographies (2D transformations) used to estimate the image of absolute conic (IAC), which can be used to obtain pinhole camera intrinsic parameters.
      listener - listener to be notified of events such as when estimation starts, ends or estimation progress changes.
      type - type of IAC estimator to create.
      Returns:
      an instance of an IAC estimator.
      Throws:
      IllegalArgumentException - if not enough homographies are provided for default IAC estimation constraints.

    • internalSetHomographies

      protected final void internalSetHomographies(List<com.irurueta.geometry.Transformation2D> homographies)
      Sets list of homographies to estimate IAC. This method does not check whether estimator is locked.
      Parameters:
      homographies - list of homographies to estimate IAC.
      Throws:
      IllegalArgumentException - if provided list of homographies does not contain enough elements to estimate the DIAC using current settings.