Package org.jvision.camera

Interface DigitalCamera

All Superinterfaces:
org.jorigin.property.HandleUserProperties, org.jorigin.identification.Identified, org.jorigin.identification.Named
public interface DigitalCamera extends org.jorigin.identification.Named, org.jorigin.identification.Identified, org.jorigin.property.HandleUserProperties
A digital camera. This interface describe a digital camera and its characteristics (intrinsics parameters). The camera model specifies the transformation from 3D point expressed within the camera coordinate system to the pixel coordinates in an image. Coordinates reference systems
The camera coordinate system is such as follows:
  • its origin is the camera projection center;
  • the Z axis points towards the viewing direction;
  • the X axis points to the right;
  • the Y axis points down.
The image coordinate system is a computer graphics standard and is described such as follows:
  • its origin is the top left image pixel;
  • the X axis in the image coordinate system points to the right;
  • the Y axis points down.
Intrinsic parameters
Camera model relies on set of parameters that are determined during a calibration process. These parameter are:
  • f be the camera focal length expressed in pixel (px)
  • (cx, cy) the camera principal point offset (the offset of the projection center on an image from the image center) expressed in pixel (px);
  • imagew / imageh respectively the the width / height of an image produced by this camera expressed in pixel (px);
  • framew / frameh respectively the the width / height of the camera sensor frame expressed in millimeters (mm);
  • affinity (also denoted B1) the the differential scaling between the horizontal and vertical pixel spacings;
  • skew (also denoted non-orthogonality coefficient, or B2) the nonorthogonality (axial skew) between the x and y axes.
Lens distortion
As digital camera relies on optical lens systems, camera integrate a lens distortion model that enable to apply / correct lens distortion. The distortion model provides distort() and undistort() methods in order to respectively apply / correct the lens distortion.

Geometric transformations
The transformation from 3D point to pixel relies on the camera intrinsic parameters. Let (X, Y, Z) a 3D point expressed within the camera coordinate system, we have:
 
(1) (x, y) = (X / Z, Y / Z) Perspective correction.
(2)(x', y') = distort(x, y)Applying distortion.
(3) (u, v) = (imagew * 0.5 + cx + x'f + x'B1 + y'B2, imageh * 0.5 + cy + y'f)Retrieve pixel coordinates

Camera model description can be found within document Automatic Camera Calibration In Close-range Photogrammetry by Clive S. Fraser.
Since:
1.0.0
Version:
"1.0.0" b202104211400L
Author:
Julien Seinturier - JOrigin - contact@jorigin.org - https://github.com/jorigin/jvision

  • Method Summary

    Modifier and Type
    Method
    Description
    org.jeometry.geom2D.point.Point2D
    distort​(org.jeometry.geom2D.point.Point2D point, boolean ppOffsetCorrection)
    Apply lens distortion to the given point expressed within image coordinates system (in pixel).
    double
    getAffinity()
    Get the differential scaling between the horizontal and vertical pixel spacings (affinity).
    String
    getCameraManufacturer()
    Get the manufacturer of the camera.
    String
    getCameraModel()
    Get the model of the camera.
    DigitalCameraSensor
    getCameraSensor()
    Get the sensor of the camera.
    String
    getCameraSerialNumber()
    Get the serial number of the camera.
    double
    getFocalLengthMetric()
    Get the focal length of the camera.
    float
    getFocalLenth()
    Get the focal length of the camera.
    LensDistortion
    getLensDistortion()
    Get the lens distortion attached to this camera.
    org.jeometry.geom2D.point.Point2D
    getPrincipalPointOffset()
    Get the camera principal point offset.
    double
    getSkew()
    Set the nonorthogonality (axial skew) between the x and y axes.
    org.jeometry.geom2D.point.Point2D
    pointCameraToImage​(org.jeometry.geom2D.point.Point2D camera, boolean applyDeformation)
    Get the coordinate of the given image point (in camera coordinates system) within the image coordinates system.
    The camera coordinate system is such as follows:
    org.jeometry.geom2D.point.Point2D
    pointImageToCamera​(org.jeometry.geom2D.point.Point2D pixel, boolean compenseDeformation)
    Get the coordinate of the given image point (in pixel) within the camera coordinates system.
    The camera coordinate system is such as follows: its origin is the camera projection center; the Z axis points towards the viewing direction; the X axis points to the right; the Y axis points down.
    void
    setAffinity​(double affinity)
    Set the differential scaling between the horizontal and vertical pixel spacings (affinity).
    void
    setCameraManufacturer​(String manufacturer)
    Set the manufacturer of the camera.
    void
    setCameraModel​(String model)
    Set the model of the camera.
    void
    setCameraSensor​(DigitalCameraSensor sensor)
    Set the sensor of the camera.
    void
    setCameraSerialNumber​(String serial)
    Set the serial number of the camera.
    void
    setFocalLength​(float focal)
    Set the focal length of the camera.
    void
    setLensDistortion​(LensDistortion distortion)
    Set the lens distortion attached to this camera.
    void
    setPrincipalPointOffset​(org.jeometry.geom2D.point.Point2D point)
    Set the camera principal point.
    void
    setSkew​(double nonOrthogonality)
    Set the nonorthogonality (axial skew) between the x and y axes.
    org.jeometry.geom2D.point.Point2D
    undistort​(org.jeometry.geom2D.point.Point2D point, boolean ppOffsetCorrection)
    Remove lens distortion from the given point expressed within image coordinates system (in pixel).

    Methods inherited from interface org.jorigin.property.HandleUserProperties

    clearUserProperties, getUserProperty, getUserPropertyNames, setUserProperty

    Methods inherited from interface org.jorigin.identification.Identified

    getIdentification, setIdentification

    Methods inherited from interface org.jorigin.identification.Named

    getName, setName

  • Method Details

    • getCameraModel

      String getCameraModel()
      Get the model of the camera.
      Returns:
      the model of the camera.
      See Also:
      setCameraModel(String)

    • setCameraModel

      void setCameraModel​(String model)
      Set the model of the camera.
      Parameters:
      model - the model of the camera.

    • getCameraManufacturer

      String getCameraManufacturer()
      Get the manufacturer of the camera.
      Returns:
      the manufacturer of the camera.
      See Also:
      setCameraManufacturer(String)

    • setCameraManufacturer

      void setCameraManufacturer​(String manufacturer)
      Set the manufacturer of the camera.
      Parameters:
      manufacturer - the manufacturer of the camera.
      See Also:
      getCameraManufacturer()

    • getCameraSerialNumber

      String getCameraSerialNumber()
      Get the serial number of the camera.
      Returns:
      the serial number of the camera.
      See Also:
      setCameraSerialNumber(String)

    • setCameraSerialNumber

      void setCameraSerialNumber​(String serial)
      Set the serial number of the camera.
      Parameters:
      serial - the serial number of the camera.
      See Also:
      getCameraSerialNumber()

    • getCameraSensor

      DigitalCameraSensor getCameraSensor()
      Get the sensor of the camera. A digital camera sensor is defined by a frame size, an image size and a pixel size.
      Returns:
      the sensor of the camera
      See Also:
      setCameraSensor(DigitalCameraSensor)

    • setCameraSensor

      void setCameraSensor​(DigitalCameraSensor sensor)
      Set the sensor of the camera. A digital camera sensor is defined by a frame size, an image size and a pixel size.
      Parameters:
      sensor - the sensor of the camera
      See Also:
      getCameraSensor()

    • getFocalLenth

      float getFocalLenth()
      Get the focal length of the camera. The focal length unit is the pixel
      Returns:
      the focal length in pixels of the camera (px).
      See Also:
      setFocalLength(float), getFocalLengthMetric()

    • setFocalLength

      void setFocalLength​(float focal)
      Set the focal length of the camera. The focal length unit is the pixel.
      Parameters:
      focal - the focal length in pixels of the camera (px).

    • getFocalLengthMetric

      double getFocalLengthMetric()
      Get the focal length of the camera. The focal length unit is millimeters (mm).
      Returns:
      the focal length of the camera. The focal length unit is millimeters (mm).
      See Also:
      getFocalLenth()

    • getPrincipalPointOffset

      org.jeometry.geom2D.point.Point2D getPrincipalPointOffset()
      Get the camera principal point offset.
      Returns:
      the camera principal point offset.
      See Also:
      setPrincipalPointOffset(Point2D)

    • setPrincipalPointOffset

      void setPrincipalPointOffset​(org.jeometry.geom2D.point.Point2D point)
      Set the camera principal point.
      Parameters:
      point - the camera principal point.
      See Also:
      getPrincipalPointOffset()

    • getAffinity

      double getAffinity()
      Get the differential scaling between the horizontal and vertical pixel spacings (affinity). Within some literature, this parameter is called B1.
      Returns:
      the differential scaling between the horizontal and vertical pixel spacings.
      See Also:
      setAffinity(double)

    • setAffinity

      void setAffinity​(double affinity)
      Set the differential scaling between the horizontal and vertical pixel spacings (affinity). Within some literature, this parameter is called B1.
      Parameters:
      affinity - the differential scaling between the horizontal and vertical pixel spacings.

    • getSkew

      double getSkew()
      Set the nonorthogonality (axial skew) between the x and y axes. Within some literature, this parameter is called B2.
      Returns:
      the nonorthogonality (axial skew) between the x and y axes.
      See Also:
      setSkew(double)

    • setSkew

      void setSkew​(double nonOrthogonality)
      Set the nonorthogonality (axial skew) between the x and y axes. Within some literature, this parameter is called B2.
      Parameters:
      nonOrthogonality - the nonorthogonality (axial skew) between the x and y axes.
      See Also:
      getSkew()

    • getLensDistortion

      LensDistortion getLensDistortion()
      Get the lens distortion attached to this camera.
      Returns:
      the lens distortion attached to this camera.
      See Also:
      setLensDistortion(LensDistortion), LensDistortion

    • setLensDistortion

      void setLensDistortion​(LensDistortion distortion)
      Set the lens distortion attached to this camera.
      Parameters:
      distortion - the lens distortion attached to this camera.
      See Also:
      getLensDistortion(), LensDistortion

    • pointImageToCamera

      org.jeometry.geom2D.point.Point2D pointImageToCamera​(org.jeometry.geom2D.point.Point2D pixel, boolean compenseDeformation)
      Get the coordinate of the given image point (in pixel) within the camera coordinates system.
      The camera coordinate system is such as follows:
      • its origin is the camera projection center;
      • the Z axis points towards the viewing direction;
      • the X axis points to the right;
      • the Y axis points down.

      This method can be used in two ways.

      If the parameter compenseDeformation is set to true, for a given pixel \((u,\ v)\) the coordinates of the corresponding point \((x,\ y)\) within the camera coordinate system are obtained as follows:
       
      (1)\(y' = \frac{v\ -\ image_{h}\times{}0.5\ -\ c_{y}}{f}\)
      \(x' = \frac{u\ -\ image_{w}\ \times\ 0.5\ -\ c_{x}\ -\ y'B_{2}}{f\ +\ B_{1}}\)
      (2)\((x, y)\ =\ undistort(x', y')\)

      On the other hand, if the parameter compenseDeformation is set to false, for a given pixel \((u,\ v)\) the coordinates of the corresponding point \((x,\ y)\) within the camera coordinate system are obtained as follows:
       
      (1)\(y = \frac{v\ -\ image_{h}\times{}0.5}{f}\)
      \(x = \frac{u\ -\ image_{w}\ \times\ 0.5\\ -\ y'B_{2}}{f\ +\ B_{1}}\)

      The first case is used if the input point come from an original produced image. The second case should be used if the input pint come from an already corrected image.
      Parameters:
      pixel - coordinates in pixel (px) of the point.
      compenseDeformation - is true if this method has to take in account deformation (principal point offset and lens distortion) during the computation. This is the case if the input point comes from the original image produced. This parameter has to be set to false if the input point comes from an already corrected images (with no principal point offset and no distortion).
      Returns:
      the coordinates of the point within the camera coordinate system.
      See Also:
      pointCameraToImage(Point2D, boolean)

    • pointCameraToImage

      org.jeometry.geom2D.point.Point2D pointCameraToImage​(org.jeometry.geom2D.point.Point2D camera, boolean applyDeformation)
      Get the coordinate of the given image point (in camera coordinates system) within the image coordinates system.
      The camera coordinate system is such as follows:
      Parameters:
      camera - a point expressed within the camera coordinates system.
      applyDeformation - is true if this method has to take in account deformation (principal point offset and lens distortion) during the computation. This is the case if the output point has to be expressed on an original image (as its come from the camera). This parameter has to be set to false if the output point has to be expressed within corrected images (with no principal point offset and no distortion).
      Returns:
      the coordinates of the point within the image coordinates system.
      See Also:
      pointImageToCamera(Point2D, boolean)

    • distort

      org.jeometry.geom2D.point.Point2D distort​(org.jeometry.geom2D.point.Point2D point, boolean ppOffsetCorrection)
      Apply lens distortion to the given point expressed within image coordinates system (in pixel). The returned point integrate the distortion and is also expressed within image coordinates system (in pixel).
      This method aims to retrieve the position of the point in an original image from an undistorted one. The distortion is applied by the underlying lens distortion.
      Parameters:
      point - a point that is not affected by the distortion expressed within image coordinates system (in pixel).
      ppOffsetCorrection - specifies if the method has to process to the principal point offset correction. If true, it is considered that the input point does not integrate principal point offset correction and so this method will make it. If false, it is considered that the input point integrates the principal point offset correction and so this method does not make it. In the two cases, the returned point as the same integration of the principal point offset than the input point.
      Returns:
      the input point affected by the distortion expressed within image coordinates system (in pixel).
      See Also:
      undistort(Point2D, boolean)

    • undistort

      org.jeometry.geom2D.point.Point2D undistort​(org.jeometry.geom2D.point.Point2D point, boolean ppOffsetCorrection)
      Remove lens distortion from the given point expressed within image coordinates system (in pixel). The returned point does no more integrate the distortion and is also expressed within image coordinates system (in pixel).
      This method aims to retrieve the position of the point in an undistorted image from an distorted one. The distortion is corrected by the the underlying lens distortion.
      Parameters:
      point - a point that integrates the distortion expressed within image coordinates system (in pixel).
      ppOffsetCorrection - specifies if the method has to process to the principal point offset correction. If true, it is considered that the input point does not integrate principal point offset correction and so this method will make it. If false, it is considered that the input point integrates the principal point offset correction and so this method does not make it. In the two cases, the returned point as the same integration of the principal point offset than the input point.
      Returns:
      the input point not affected by the distortion expressed within image coordinates system (in pixel).
      See Also:
      distort(Point2D, boolean)