Package com.irurueta.geometry

Class PinholeCamera

java.lang.Object
com.irurueta.geometry.Camera
com.irurueta.geometry.PinholeCamera
All Implemented Interfaces:
Serializable
public class PinholeCamera extends Camera implements Serializable
This class implements the behavior of a pinhole camera. A pinhole camera is a linear mapping between 3D and 2D worlds. Pinhole cameras only take into account translation, rotation and camera intrinsic parameters such as focal length, aspect ratio, skewness and principal point. Pinhole cameras perform projective mappings between 3D and 2D worlds, in other words, the farther an object is, the smaller is represented or parallel lines converge into vanishing points. Pinhole cameras cannot be used for orthographic projections (where parallelism between lines is preserved and there are no vanishing points).
See Also:

  • Field Details

    • PINHOLE_CAMERA_MATRIX_ROWS

      public static final int PINHOLE_CAMERA_MATRIX_ROWS
      Defines the number of rows of a pinhole camera.
      See Also:

    • PINHOLE_CAMERA_MATRIX_COLS

      public static final int PINHOLE_CAMERA_MATRIX_COLS
      Defines the number of columns of a pinhole camera.
      See Also:

    • INHOM_COORDS

      public static final int INHOM_COORDS
      Constant defining the number of inhomogeneous coordinates.
      See Also:

    • EPS

      public static final double EPS
      Constant defining a tiny value close to machine precision.
      See Also:

    • DEFAULT_DECOMPOSE_INTRINSICS_AND_ROTATION

      private static final boolean DEFAULT_DECOMPOSE_INTRINSICS_AND_ROTATION
      Indicates if camera should be decomposed into intrinsic parameters and rotation by default after creation or setting new parameters.
      See Also:

    • DEFAULT_DECOMPOSE_CAMERA_CENTER

      private static final boolean DEFAULT_DECOMPOSE_CAMERA_CENTER
      Indicates if camera should be decomposed to obtain its center after creation or setting new parameters.
      See Also:

    • FRONT_THRESHOLD

      private static final double FRONT_THRESHOLD
      Threshold to determine whether a point is in front or behind the camera.
      See Also:

    • SIGN_THRESHOLD

      private static final double SIGN_THRESHOLD
      Threshold to determine camera sign. If camera sign is negative, its sign must be fixed (multiplying its matrix by -1) so that point cheirality to determine whether points are in front or behind the camera can be correctly determined. When sign is reversed, cheirality gets reversed too. Notice that camera matrix is expressed in homogeneous coordinates, hence multiplying it by -1.0 has no effect on point projection.
      See Also:

    • internalMatrix

      private com.irurueta.algebra.Matrix internalMatrix
      Internal matrix defining this camera.

    • normalized

      private boolean normalized
      Boolean indicating whether this camera has already been normalized. Normalization can help to increase numerical accuracy on camera computations.

    • cameraSignFixed

      private boolean cameraSignFixed
      Boolean indicating whether camera sign has been fixed (it is 1.0). When camera sign is negative, cheirality is reversed, hence it cannot be correctly determined whether points are located in front or behind the camera.

    • intrinsicParameters

      private PinholeCameraIntrinsicParameters intrinsicParameters
      Intrinsic parameters of the camera after decomposition.

    • cameraRotation

      private Rotation3D cameraRotation
      3D rotation of the camera after decomposition.

    • cameraCenter

      private Point3D cameraCenter
      Camera center after decomposition.

  • Constructor Details

    • PinholeCamera

      public PinholeCamera()
      Constructor. Creates a canonical camera, which is equal to the identity 3x4 matrix.

    • PinholeCamera

      public PinholeCamera(com.irurueta.algebra.Matrix internalMatrix) throws com.irurueta.algebra.WrongSizeException
      Constructor. Creates a camera using provided matrix.
      Parameters:
      internalMatrix - matrix to create the camera from.
      Throws:
      com.irurueta.algebra.WrongSizeException - If provided matrix is not 3x4.

    • PinholeCamera

      public PinholeCamera(PinholeCameraIntrinsicParameters intrinsicParameters, Rotation3D rotation, Point2D originImageCoordinates)
      Constructor. Creates a camera using provided intrinsic parameters, 3D rotation and 2D coordinates of the world origin.
      Parameters:
      intrinsicParameters - Intrinsic parameters of the camera.
      rotation - 3D rotation of the camera.
      originImageCoordinates - 2D coordinates of the world origin.

    • PinholeCamera

      public PinholeCamera(PinholeCameraIntrinsicParameters intrinsicParameters, Rotation3D rotation, Point3D cameraCenter)
      Constructor. Creates a camera using provided intrinsic parameters, 3D rotation and 3D coordinates of the camera center.
      Parameters:
      intrinsicParameters - Intrinsic parameters of the camera.
      rotation - 3D rotation of the camera.
      cameraCenter - 3D coordinates of the camera center.

    • PinholeCamera

      public PinholeCamera(Point3D point3D1, Point3D point3D2, Point3D point3D3, Point3D point3D4, Point3D point3D5, Point3D point3D6, Point2D point2D1, Point2D point2D2, Point2D point2D3, Point2D point2D4, Point2D point2D5, Point2D point2D6) throws CameraException
      Creates an instance of a pinhole camera by estimating its parameters from 2D-3D point correspondences.
      Parameters:
      point3D1 - 1st 3D point.
      point3D2 - 2nd 3D point.
      point3D3 - 3rd 3D point.
      point3D4 - 4th 3D point.
      point3D5 - 5th 3D point.
      point3D6 - 6th 3D point.
      point2D1 - 1st 2D point corresponding to the projection of 1st 3D point.
      point2D2 - 2nd 2D point corresponding to the projection of 2nd 3D point.
      point2D3 - 3rd 2D point corresponding to the projection of 3rd 3D point.
      point2D4 - 4th 2D point corresponding to the projection of 4th 3D point.
      point2D5 - 5th 2D point corresponding to the projection of 5th 3D point.
      point2D6 - 6th 2D point corresponding to the projection of 6th 3D point.
      Throws:
      CameraException - if camera cannot be estimated using provided points because of a degeneracy.

    • PinholeCamera

      public PinholeCamera(Plane plane1, Plane plane2, Plane plane3, Plane plane4, Line2D line1, Line2D line2, Line2D line3, Line2D line4) throws CameraException
      Creates an instance of a pinhole camera by estimating its parameters from line/plane correspondences.
      Parameters:
      plane1 - 1st 3D plane.
      plane2 - 2nd 3D plane.
      plane3 - 3rd 3D plane.
      plane4 - 4th 3D plane.
      line1 - 1st 2D line corresponding to 1st 3D plane.
      line2 - 2nd 2D line corresponding to 2nd 3D plane.
      line3 - 3rd 2D line corresponding to 3rd 3D plane.
      line4 - 4th 2D line corresponding to 4th 3D plane.
      Throws:
      CameraException - if camera cannot be estimated using provided lines and planes because of a degeneracy.

  • Method Details

    • project

      public void project(Point3D inputPoint, Point2D result)
      Projects a 3D point into a 2D point in a retinal plane.
      Specified by:
      project in class Camera
      Parameters:
      inputPoint - 3D point to be projected.
      result - 2D projected point.

    • backProject

      public void backProject(Line2D line, Plane result)
      Back-projects a line into a plane and stores the result into provided instance.
      Specified by:
      backProject in class Camera
      Parameters:
      line - 2D line to be back-projected.
      result - Instance where computed back-projected 3D plane data is stored.

    • backProject

      public void backProject(Point2D point, Point3D result) throws CameraException
      Back-projects provided 2D point into a 3D point and stores the result into provided instance. Notice that estimated solution is not unique, since back-projecting a 2D point results in an infinite number of 3D points located in the same ray of light. This method only computes one possible solution. Any other solution can be computed as a linear combination between the camera center and the estimated back-projected point.
      Specified by:
      backProject in class Camera
      Parameters:
      point - 2D point to be back-projected.
      result - Instance where back-projected 3D point data will be stored.
      Throws:
      CameraException - thrown if 2D point cannot be back-projected because camera is degenerate.

    • backProject

      public void backProject(Conic conic, Quadric result)
      Back-projects a 2D conic into a 3D quadric and stores the result into provided instance.
      Specified by:
      backProject in class Camera
      Parameters:
      conic - 2D conic to be back-projected.
      result - Instance where data of back-projected 3D quadric will be stored.

    • project

      public void project(DualQuadric dualQuadric, DualConic result)
      Projects a 3D dual quadric into a 2D dual conic and stores the result into provided instance.
      Specified by:
      project in class Camera
      Parameters:
      dualQuadric - 3D dual quadric to be projected.
      result - Instance where data of projected 2D dual conic will be stored.

    • getType

      public CameraType getType()
      Returns the type of this camera, which is always PINHOLE_CAMERA for instance of this class.
      Specified by:
      getType in class Camera
      Returns:
      Type of this camera.

    • decompose

      public void decompose() throws CameraException
      Decomposes current camera matrix to determine its intrinsic and extrinsic parameters (rotation and translation).
      Throws:
      CameraException - thrown if camera matrix is degenerate.

    • decompose

      public void decompose(boolean decomposeIntrinsicsAndRotation) throws CameraException
      Decomposes current camera matrix to determine its camera center. Intrinsic parameters and rotation will be decomposed as well depending on provided value.
      Parameters:
      decomposeIntrinsicsAndRotation - if true, intrinsic parameters and rotation are computed as well.
      Throws:
      CameraException - thrown if camera matrix is degenerate.

    • decompose

      public void decompose(boolean decomposeIntrinsicsAndRotation, boolean decomposeCameraCenter) throws CameraException
      Decomposes current camera matrix. Intrinsic parameters, rotation and camera center will be computed depending on provided values.
      Parameters:
      decomposeIntrinsicsAndRotation - if true, intrinsic parameters and rotation are computed as well.
      decomposeCameraCenter - if true, camera center is computed as well.
      Throws:
      CameraException - thrown if camera matrix is degenerate.

    • normalize

      public void normalize()
      Normalizes camera matrix. Normalization can help to increase accuracy on camera operations. This method should only be called when an increase on accuracy is needed to save the additional computational cost. Notice that affine pinhole cameras are never normalized, since elements to be used for normalization have norm equal to zero in such case.

    • isNormalized

      public boolean isNormalized()
      Indicates if camera matrix has already been normalized. Notice that this value will be set to false when any camera parameter is modified
      Returns:
      true if camera is normalized, false otherwise

    • fixCameraSign

      public void fixCameraSign() throws CameraException
      Fixes the camera sign so that point cheirality can be correctly determined. Cheirality indicates if points are located in front or behind the camera. Sign needs to be fixed if it is negative.
      Throws:
      CameraException - thrown if there are numerical instabilities.

    • isCameraSignFixed

      public boolean isCameraSignFixed()
      Indicates if camera sign has been fixed. When camera sign has been fixed cheirality can be correctly determined. Cheirality indicates if points are located in front or behind the camera. Notice that when camera parameters are modified, this parameter is set to false again.
      Returns:
      true if camera sign has been fixed, false otherwise.

    • getCameraRotation

      public Rotation3D getCameraRotation() throws NotAvailableException
      Returns camera rotation if camera has already been decomposed and rotation is available.
      Returns:
      camera rotation.
      Throws:
      NotAvailableException - if camera rotation is not available yet.

    • getIntrinsicParameters

      public PinholeCameraIntrinsicParameters getIntrinsicParameters() throws NotAvailableException
      Returns camera intrinsic parameters if camera has already been decomposed and intrinsic parameters are available. Intrinsic parameters contain information related to internal parameters of a camera, usually related to the camera lens and sensor.
      Returns:
      camera intrinsic parameters.
      Throws:
      NotAvailableException - if camera intrinsic parameters are not available yet.

    • getInternalMatrix

      public com.irurueta.algebra.Matrix getInternalMatrix()
      Returns a copy of internal matrix to avoid malicious modifications.
      Returns:
      a copy of the internal camera matrix.

    • setInternalMatrix

      public final void setInternalMatrix(com.irurueta.algebra.Matrix internalMatrix) throws com.irurueta.algebra.WrongSizeException
      Sets internal matrix of this camera. Internal matrix of a pinhole camera must have size 3x4 (i.e. 3 rows and 4 columns).
      Parameters:
      internalMatrix - internal matrix to be set
      Throws:
      com.irurueta.algebra.WrongSizeException - if provided matrix doesn't have size 3x4.

    • areIntrinsicParametersAvailable

      public boolean areIntrinsicParametersAvailable()
      Indicates if camera intrinsic parameters are available for retrieval. Intrinsic parameters become available after camera decomposition (if intrinsic parameters are requested). And become unavailable when any camera parameters are modified.
      Returns:
      true if camera intrinsic parameters are available, false otherwise.

    • isCameraRotationAvailable

      public boolean isCameraRotationAvailable()
      Indicates if camera rotation is available for retrieval. Camera rotation become available after camera decomposition (if camera rotation is requested). And become unavailable when any camera parameters are modified.
      Returns:
      true if camera rotation is available, false otherwise.

    • setCameraRotation

      public void setCameraRotation(Rotation3D cameraRotation) throws CameraException
      Sets camera rotation of this camera. When setting rotation the camera sign becomes unknown and the camera becomes non-normalized.
      Parameters:
      cameraRotation - Camera 3D rotation to be set.
      Throws:
      CameraException - if there are numerical instabilities.

    • rotate

      public void rotate(Rotation3D cameraRotation) throws CameraException
      Combines current camera rotation with provided rotation.
      Parameters:
      cameraRotation - Camera 3D rotation to be added to current rotation.
      Throws:
      CameraException - if there are numerical instabilities.

    • pointAt

      public void pointAt(Point3D point) throws CameraException
      Modifies camera so that it points to provided point while keeping the camera center.
      Parameters:
      point - Point to look at.
      Throws:
      CameraException - thrown if operation cannot be done. This happens usually when point is located very close to the camera center. In those situations orientation cannot be reliably computed.

    • setIntrinsicParameters

      public void setIntrinsicParameters(PinholeCameraIntrinsicParameters intrinsicParameters) throws CameraException
      Sets camera intrinsic parameters. Intrinsic parameters are related to camera lens and sensor and contain parameters such as focal length, skewness or principal point
      Parameters:
      intrinsicParameters - intrinsic parameters to be set
      Throws:
      CameraException - if there are numerical instabilities

    • getCameraCenter

      public Point3D getCameraCenter() throws NotAvailableException
      Returns a 3D point indicating camera center (i.e. location) if center has already been computed and is available for retrieval. If camera center is not available, camera must be decomposed before calling this method.
      Returns:
      camera center.
      Throws:
      NotAvailableException - if camera center is not yet available for retrieval.

    • isCameraCenterAvailable

      public boolean isCameraCenterAvailable()
      Indicates if camera center has been decomposed and is available for retrieval.
      Returns:
      true if camera center is available, false otherwise.

    • setCameraCenter

      public void setCameraCenter(Point3D cameraCenter)
      Sets 3D coordinates of camera center. When setting camera center camera becomes not normalized.
      Parameters:
      cameraCenter - camera center to be set.

    • setIntrinsicParametersAndRotation

      public void setIntrinsicParametersAndRotation(PinholeCameraIntrinsicParameters intrinsicParameters, Rotation3D rotation)
      Sets camera intrinsic parameters and camera 3D rotation. Intrinsic parameters indicate internal camera parameters related to camera lens and camera sensor and rotation indicates camera orientation.
      Parameters:
      intrinsicParameters - intrinsic camera parameters to be set.
      rotation - 3D camera rotation to be set.

    • setIntrinsicAndExtrinsicParameters

      public final void setIntrinsicAndExtrinsicParameters(PinholeCameraIntrinsicParameters intrinsicParameters, Rotation3D rotation, Point2D originImageCoordinates)
      Sets both intrinsic and extrinsic camera parameters. Intrinsic parameters indicate internal camera parameters related to camera lens and sensor, and extrinsic parameters are parameters that indicate camera location and orientation by providing the projected coordinates of world origin and the camera 3D rotation.
      Parameters:
      intrinsicParameters - intrinsic parameters to be set.
      rotation - camera rotation to be set.
      originImageCoordinates - projected coordinates of world origin to be set.

    • setIntrinsicAndExtrinsicParameters

      public final void setIntrinsicAndExtrinsicParameters(PinholeCameraIntrinsicParameters intrinsicParameters, Rotation3D rotation, Point3D cameraCenter)
      Sets both intrinsic and extrinsic camera parameters. Intrinsic parameters indicate internal camera parameters related to camera lens and sensor, and extrinsic parameters are parameters that indicate camera location and orientation by providing camera center and the camera 3D rotation.
      Parameters:
      intrinsicParameters - intrinsic parameters to be set.
      rotation - camera rotation to be set.
      cameraCenter - location of camera center to be set.

    • getXAxisVanishingPoint

      public Point2D getXAxisVanishingPoint()
      Returns the projected 2D coordinates of the x-axis, which corresponds to its vanishing point.
      Returns:
      vanishing point of x-axis.

    • xAxisVanishingPoint

      public void xAxisVanishingPoint(Point2D result)
      Computes the projected 2D coordinates of the x-axis, which corresponds to its vanishing point.
      Parameters:
      result - 2D point where vanishing point of x-axis will be stored.

    • getYAxisVanishingPoint

      public Point2D getYAxisVanishingPoint()
      Returns the projected 2D coordinates of the y-axis, which corresponds to its vanishing point.
      Returns:
      vanishing point of y-axis.

    • yAxisVanishingPoint

      public void yAxisVanishingPoint(Point2D result)
      Computes the projected 2D coordinates of the y-axis, which corresponds to its vanishing point.
      Parameters:
      result - 2D point where vanishing point of y-axis will be stored.

    • getZAxisVanishingPoint

      public Point2D getZAxisVanishingPoint()
      Returns the projected 2D coordinates of the z axis, which corresponds to its vanishing point.
      Returns:
      vanishing point of z axis.

    • zAxisVanishingPoint

      public void zAxisVanishingPoint(Point2D result)
      Computes the projected 2D coordinates of the z axis, which corresponds to its vanishing point.
      Parameters:
      result - 2D point where vanishing point of z axis will be stored.

    • getImageOfWorldOrigin

      public Point2D getImageOfWorldOrigin()
      Returns the projected 2D coordinates of the world origin (0, 0, 0).
      Returns:
      projected point of world origin.

    • imageOfWorldOrigin

      public void imageOfWorldOrigin(Point2D result)
      Computes the projected 2D coordinates of the world origin (0, 0, 0).
      Parameters:
      result - 2D point where projected point of world origin will be stored.

    • setXAxisVanishingPoint

      public void setXAxisVanishingPoint(Point2D xAxisVanishingPoint)
      Sets the projected 2D coordinates of the x-axis, which corresponds to its vanishing point.
      Parameters:
      xAxisVanishingPoint - vanishing point of x-axis to be set.

    • setYAxisVanishingPoint

      public void setYAxisVanishingPoint(Point2D yAxisVanishingPoint)
      Sets the projected 2D coordinates of the y-axis, which corresponds to its vanishing point.
      Parameters:
      yAxisVanishingPoint - vanishing point of y-axis to be set.

    • setZAxisVanishingPoint

      public void setZAxisVanishingPoint(Point2D zAxisVanishingPoint)
      Sets the projected 2D coordinates of the z axis, which corresponds to its vanishing point.
      Parameters:
      zAxisVanishingPoint - vanishing point of z axis to be set.

    • setImageOfWorldOrigin

      public void setImageOfWorldOrigin(Point2D imageOfWorldOrigin)
      Sets the projected 2D coordinates of the world origin (0, 0, 0).
      Parameters:
      imageOfWorldOrigin - projected world origin to be set.

    • getHorizontalAxisPlane

      public Plane getHorizontalAxisPlane()
      Returns plane formed by x and z retinal axes. x-axis is taken respect the projected camera coordinates (i.e. retinal plane), and z-axis just points in the direction that the camera is looking at.
      Returns:
      horizontal plane respect camera retinal plane.

    • horizontalAxisPlane

      public void horizontalAxisPlane(Plane result)
      Computes the plane formed by x and z retinal axes. x-axis is taken respect the projected camera coordinates (i.e. retinal plane), and z-axis just points in the direction that the camera is looking at.
      Parameters:
      result - plane where results will be stored.

    • getVerticalAxisPlane

      public Plane getVerticalAxisPlane()
      Returns plane formed by y and z retinal axes. y-axis is taken respect the projected camera coordinates (i.e. retinal plane), and z-axis just points in the direction that the camera is looking at.
      Returns:
      vertical plane respect camera retinal plane.

    • verticalAxisPlane

      public void verticalAxisPlane(Plane result)
      Computes the plane formed by y and z retinal axes. y-axis is taken respect the projected camera coordinates (i.e. retinal plane), and z-axis just point in the direction that the camera is looking at.
      Parameters:
      result - plane where results will be stored.

    • getPrincipalPlane

      public Plane getPrincipalPlane()
      Returns a plane equivalent to the retinal plane (i.e. the plane where 3D points get projected). The principal plane director vector always points in the direction that the camera is looking at, and the camera center is locus of the principal plane.
      Returns:
      a plane equivalent to the retinal plane.

    • principalPlane

      public void principalPlane(Plane result)
      Computes a plane equivalent to the retinal plane (i.e. the plane where 3D points get projected). The principal plane director vector always points in the direction that the camera is looking at, and the camera center is locus of the principal plane.
      Parameters:
      result - plane where results will be stored.

    • setHorizontalAxisPlane

      public void setHorizontalAxisPlane(Plane horizontalAxisPlane)
      Sets plane formed by x and z retinal plane. x-axis is taken respect the projected camera coordinates (i.e. retinal plane), and z-axis just points in the direction that the camera is looking at.
      Parameters:
      horizontalAxisPlane - horizontal plane respect camera retinal plane to be set.

    • setVerticalAxisPlane

      public void setVerticalAxisPlane(Plane verticalAxisPlane)
      Sets plane formed by y and z retinal plane. y-axis is taken respect the projected camera coordinates (i.e. retinal plane), and z-axis just points in the direction that the camera is looking at.
      Parameters:
      verticalAxisPlane - vertical plane respect camera retinal plane to be set.

    • setPrincipalPlane

      public void setPrincipalPlane(Plane principalPlane)
      Sets plane equivalent to the retinal plane (i.e. the plane where 3D points get projected). Notice that the principal plane director vector always points in the direction that the camera is looking at, and that the camera center is locus of the principal plane.
      Parameters:
      principalPlane - principal plane to be set.

    • getPrincipalPoint

      public Point2D getPrincipalPoint()
      Returns a 2D point indicating where the camera center (or the principal axis) is projected on the retinal plane. Usually the principal plane is located at the center (i.e. origin of coordinates) of the retinal plane.
      Returns:
      the principal point laying on the retinal plane

    • principalPoint

      public void principalPoint(Point2D result)
      Computes the principal point which is a 2D point indicating where the camera center (or the principal axis) is projected on the retinal plane. Usually the principal plane is located at the center (i.e. origin of coordinates) of the retinal plane.
      Parameters:
      result - 2D point where computed principal point will be stored

    • getPrincipalAxisArray

      public double[] getPrincipalAxisArray() throws CameraException
      Returns the principal axis as an array consisting of the x,y,z coordinates of the director vector of the principal plane. Hence, the principal axis contains the direction that the camera is looking at.
      Returns:
      principal axis as an array.
      Throws:
      CameraException - if there is numerical instability in camera parameters.

    • principalAxisArray

      public void principalAxisArray(double[] result) throws CameraException
      Computes the principal axis as an array consisting of the x,y,z coordinates of the director vector of the principal plane. Hence, the principal axis contains the direction that the camera is looking at.
      Parameters:
      result - array where principal axis coordinates will be stored.
      Throws:
      IllegalArgumentException - if provided array does not have length 3.
      CameraException - if there is numerical instability in camera parameters.

    • getCameraSign

      public double getCameraSign() throws CameraException
      Returns camera sign of this camera. Pinhole camera is defined in homogeneous coordinates, hence its internal matrix can theoretically be scaled without affecting results (in practice it can affect accuracy). However, scaling the camera with a different sign can have an impact on determining whether points or objects are located in front or behind the camera. When camera sign is positive (i.e. 1.0), then points are correctly detected whether they are in front or behind the camera (this is called cheirality), when sign is negative, point cheirality is reversed and needs to be fixed.
      Returns:
      1.0 if camera sign is correct, or -1.0 if camera sign needs to be reversed.
      Throws:
      CameraException - if there is numerical instability.

    • getCameraSign

      public double getCameraSign(double threshold) throws CameraException
      Returns camera sign of this camera up to provided threshold. Pinhole camera is defined in homogeneous coordinates, hence its internal matrix can theoretically be scaled without affecting results (in practice it can affect accuracy). However, scaling the camera with a different sign can have an impact on determining whether points or objects are located in front or behind the camera. When camera sign is positive (i.e. 1.0), then points are correctly detected whether they are in front or behind the camera (this is called cheirality), when sign is negative, point cheirality is reversed and needs to be fixed.
      Parameters:
      threshold - threshold to determine whether camera sign is positive or negative. Usually threshold is a very small value close to zero
      Returns:
      1.0 if camera sign is correct, or -1.0 if camera sign needs to be reversed.
      Throws:
      CameraException - if there is numerical instability.

    • getDepth

      public double getDepth(Point3D point) throws CameraException
      Returns the depth of provided point respect to camera center. A positive value indicates that point is in front of the camera, a negative value indicates that point is behind the camera.
      Parameters:
      point - point to be checked.
      Returns:
      depth of provided point respect to camera center.
      Throws:
      CameraException - if there is numerical instability.

    • getDepths

      public List<Double> getDepths(List<Point3D> points) throws CameraException
      Returns the depth of provided points respect to camera center. A positive value indicates that point is in front of the camera, a negative value indicates that point is behind the camera.
      Parameters:
      points - points to be checked.
      Returns:
      depth of provided points respect to camera center.
      Throws:
      CameraException - if there is numerical instability.

    • depths

      public void depths(List<Point3D> points, List<Double> result) throws CameraException
      Computes the depth of provided points respect to camera center and stores the result in provided result list. A positive value indicates that point is in front of the camera, a negative value indicates that point is behind the camera.
      Parameters:
      points - points to be checked.
      result - list where depths of provided points will be stored.
      Throws:
      CameraException - if there is numerical instability.

    • getCheirality

      public double getCheirality(Point3D point) throws CameraException
      Computes the cheirality of a point. A positive cheirality indicates that a point is in front of the camera, a negative value indicates that a point is behind the camera. Cheirality is less expensive to compute than point depth, for that reason when trying to determine if a point is in front or behind the camera is preferable to check cheirality sign rather than depth sign.
      Parameters:
      point - point to be checked.
      Returns:
      a positive value if point is in front of the camera, a negative value otherwise.
      Throws:
      CameraException - if there is numerical instability.

    • getCheiralities

      public List<Double> getCheiralities(List<Point3D> points) throws CameraException
      Return the cheirality of the list of provided points. A positive cheirality indicates that a point is in front of the camera, a negative value indicates that a point is behind the camera. Cheirality is less expensive to compute than point depth, for that reason when trying to determine if a point is in front or behind the camera it is preferable to check cheirality sign rather than depth sign.
      Parameters:
      points - list of points to be checked.
      Returns:
      a list of cheirality values corresponding to provided points.
      Throws:
      CameraException - if there is numerical instability.

    • cheiralities

      public void cheiralities(List<Point3D> points, List<Double> result) throws CameraException
      Computes the cheirality of the list of provided points and stores the result in result list. A positive cheirality indicates that a point is in front of the camera, a negative value indicates that a point is behind the camera. Cheirality is less expensive to compute than point depth, for that reason when trying to determine if a point is in front or behind the camera it is preferable to check cheirality sign rather than depth sign.
      Parameters:
      points - list of points to be checked.
      result - list where cheiralities will be stored.
      Throws:
      CameraException - if there is numerical instability.

    • isPointInFrontOfCamera

      public boolean isPointInFrontOfCamera(Point3D point) throws CameraException
      Determines if a given point is located in front of the camera.
      Parameters:
      point - point to be checked.
      Returns:
      true if point is in front of the camera, false otherwise.
      Throws:
      CameraException - if there is numerical instability.

    • isPointInFrontOfCamera

      public boolean isPointInFrontOfCamera(Point3D point, double threshold) throws CameraException
      Determines if a given point is located in front of the camera up to given threshold.
      Parameters:
      point - point to be checked.
      threshold - a threshold which typically is a small value close to zero.
      Returns:
      true if point is in front of the camera, false otherwise.
      Throws:
      CameraException - if there is numerical instability.

    • arePointsInFrontOfCamera

      public List<Boolean> arePointsInFrontOfCamera(List<Point3D> points, double threshold) throws CameraException
      Returns list indicating if corresponding provided points are located in front of the camera.
      Parameters:
      points - points to be checked.
      threshold - a threshold which typically is a small value close to zero.
      Returns:
      a list of booleans indicating if the corresponding provided point is located in front of the camera or not.
      Throws:
      CameraException - if there is numerical instability.

    • arePointsInFrontOfCamera

      public List<Boolean> arePointsInFrontOfCamera(List<Point3D> points) throws CameraException
      Returns list indicating if corresponding provided points are located in front of the camera.
      Parameters:
      points - points to be checked.
      Returns:
      a list of booleans indicating if the corresponding provided point is located in front of the camera or not.
      Throws:
      CameraException - if there is numerical instability.

    • arePointsInFrontOfCamera

      public void arePointsInFrontOfCamera(List<Point3D> points, List<Boolean> result, double threshold) throws CameraException
      Computes list indicating if corresponding provided points are located in front of the camera or not.
      Parameters:
      points - points to be checked.
      result - list where results will be stored.
      threshold - a threshold which typically is a small value close to zero.
      Throws:
      CameraException - if there is numerical instability.

    • arePointsInFrontOfCamera

      public void arePointsInFrontOfCamera(List<Point3D> points, List<Boolean> result) throws CameraException
      Computes list indicating if corresponding provided points are located in front of the camera or not.
      Parameters:
      points - points to be checked.
      result - list where results will be stored.
      Throws:
      CameraException - if there is numerical instability.

    • createCanonicalCamera

      public static PinholeCamera createCanonicalCamera()
      Creates an instance of PinholeCamera. Created instance is a canonical camera equal to the 3x4 identity, which means that camera is located at the origin with no translation or rotation.
      Returns:
      a canonical pinhole camera.

    • computeIntrinsicsAndRotation

      private void computeIntrinsicsAndRotation() throws CameraException
      Decompose camera matrix 3x3 left minor and computes camera intrinsic parameters and rotation.
      Throws:
      CameraException - if there is numerical instability.

    • computeCameraCenterSVD

      public Point3D computeCameraCenterSVD() throws CameraException
      Computes camera center using singular value decomposition. This method is valid even when center is located at infinity (w = 0), although it is computationally more complex than other methods. This is the default method used when decomposing a camera and computing its center.
      Returns:
      camera center.
      Throws:
      CameraException - if there is numerical instability.

    • computeCameraCenterSVD

      public void computeCameraCenterSVD(Point3D result) throws CameraException
      Computes camera center using singular value decomposition. This method is valid even when center is located at infinity, although it is computationally more complex than other methods. This is the default method used when decomposing a camera and computing its center.
      Parameters:
      result - point where camera center will be stored.
      Throws:
      CameraException - if there is numerical instability.

    • computeCameraCenterDet

      public Point3D computeCameraCenterDet() throws CameraException
      Computes camera center using determinants of camera matrix minors. This method also works when center is located at infinity (w = 0) and is less computationally expensive than SVD, however it might also be less accurate.
      Returns:
      camera center.
      Throws:
      CameraException - if there is numerical instabilities.

    • computeCameraCenterDet

      public void computeCameraCenterDet(Point3D result) throws CameraException
      Computes camera center using determinants of camera matrix minors. This method also works when center is located at infinity (w = 0) and is less computationally expensive than SVD, however it might also be less accurate.
      Parameters:
      result - point where camera center will be stored.
      Throws:
      CameraException - if there is numerical instability.

    • computeCameraCenterFiniteCamera

      public Point3D computeCameraCenterFiniteCamera() throws CameraException
      Computes camera center. This method is better suited when camera is finite (its center is not located at the infinity or close to it). Otherwise, because of numerical precision inaccurate results might be obtained, or even a CameraException might be thrown. This is the less computationally expensive method.
      Returns:
      camera center.
      Throws:
      CameraException - if there is numerical instabilities or center is located at the infinity or close to it.

    • computeCameraCenterFiniteCamera

      public void computeCameraCenterFiniteCamera(Point3D result) throws CameraException
      Computes camera center. This method is better suited when camera is finite (its center is not located at the infinity or close to it). Otherwise, because of numerical precision inaccurate results might be obtained, or even a CameraException might be thrown. This is the less computationally expensive method.
      Parameters:
      result - point where camera center will be stored.
      Throws:
      CameraException - if there is numerical instability.

    • setFromPointCorrespondences

      public final void setFromPointCorrespondences(Point3D point3D1, Point3D point3D2, Point3D point3D3, Point3D point3D4, Point3D point3D5, Point3D point3D6, Point2D point2D1, Point2D point2D2, Point2D point2D3, Point2D point2D4, Point2D point2D5, Point2D point2D6) throws CameraException
      Estimates this camera parameters from 2D-3D point correspondences.
      Parameters:
      point3D1 - 1st 3D point.
      point3D2 - 2nd 3D point.
      point3D3 - 3rd 3D point.
      point3D4 - 4th 3D point.
      point3D5 - 5th 3D point.
      point3D6 - 6th 3D point.
      point2D1 - 1st 2D point corresponding to the projection of 1st 3D point.
      point2D2 - 2nd 2D point corresponding to the projection of 2nd 3D point.
      point2D3 - 3rd 2D point corresponding to the projection of 3rd 3D point.
      point2D4 - 4th 2D point corresponding to the projection of 4th 3D point.
      point2D5 - 5th 2D point corresponding to the projection of 5th 3D point.
      point2D6 - 6th 2D point corresponding to the projection of 6th 3D point.
      Throws:
      CameraException - if camera cannot be estimated using provided points because of a degeneracy.

    • setFromLineAndPlaneCorrespondences

      public final void setFromLineAndPlaneCorrespondences(Plane plane1, Plane plane2, Plane plane3, Plane plane4, Line2D line1, Line2D line2, Line2D line3, Line2D line4) throws CameraException
      Estimates this camera parameters from line/plane correspondences.
      Parameters:
      plane1 - 1st 3D plane.
      plane2 - 2nd 3D plane.
      plane3 - 3rd 3D plane.
      plane4 - 4th 3D plane.
      line1 - 1st 2D line corresponding to 1st 3D plane.
      line2 - 2nd 2D line corresponding to 2nd 3D plane.
      line3 - 3rd 2D line corresponding to 3rd 3D plane.
      line4 - 4th 2D line corresponding to 4th 3D plane.
      Throws:
      CameraException - if camera cannot be estimated using provided lines and planes because of a degeneracy.