lensfun  0.3.2.0
Classes | Enumerations | Functions
Structures and functions for lenses

These structures and functions allow to define and examine the properties of a lens. More...

Classes

struct  lfLensCalibDistortion
 Lens distortion calibration data. More...
 
struct  lfLensCalibTCA
 Laterlal chromatic aberrations calibration data. More...
 
struct  lfLensCalibVignetting
 Lens vignetting calibration data. More...
 
struct  lfLensCalibCrop
 Struct to save image crop, which can depend on the focal length. More...
 
struct  lfLensCalibFov
 Struct to save calibrated field of view, which can depends on the focal length (DEPRECATED) More...
 
struct  lfLensCalibRealFocal
 Struct to save real focal length, which can depends on the (nominal) focal length. More...
 
struct  lfParameter
 This structure describes a single parameter for some lens model. More...
 
struct  lfLens
 Lens data. Unknown fields are set to NULL or 0. More...
 

Enumerations

enum  lfDistortionModel {
  LF_DIST_MODEL_NONE, LF_DIST_MODEL_POLY3, LF_DIST_MODEL_POLY5, LF_DIST_MODEL_PTLENS,
  LF_DIST_MODEL_ACM
}
 The Lensfun library implements several lens distortion models. This enum lists them. More...
 
enum  lfTCAModel { LF_TCA_MODEL_NONE, LF_TCA_MODEL_LINEAR, LF_TCA_MODEL_POLY3, LF_TCA_MODEL_ACM }
 The Lensfun library supports several models for lens lateral chromatic aberrations (also called transversal chromatic aberrations, TCA). More...
 
enum  lfVignettingModel { LF_VIGNETTING_MODEL_NONE, LF_VIGNETTING_MODEL_PA, LF_VIGNETTING_MODEL_ACM }
 The Lensfun library supports several models for lens vignetting correction. More...
 
enum  lfCropMode { LF_NO_CROP, LF_CROP_RECTANGLE, LF_CROP_CIRCLE }
 Different crop modes. More...
 
enum  lfLensType {
  LF_UNKNOWN, LF_RECTILINEAR, LF_FISHEYE, LF_PANORAMIC,
  LF_EQUIRECTANGULAR, LF_FISHEYE_ORTHOGRAPHIC, LF_FISHEYE_STEREOGRAPHIC, LF_FISHEYE_EQUISOLID,
  LF_FISHEYE_THOBY
}
 Lens type. See Change of projection for further information. More...
 

Functions

lfLenslf_lens_new ()
 Create a new lens object. More...
 
void lf_lens_destroy (lfLens *lens)
 Destroy a lfLens object. More...
 
void lf_lens_copy (lfLens *dest, const lfLens *source)
 Copy the data from one lfLens structure into another. More...
 
cbool lf_lens_check (lfLens *lens)
 
void lf_lens_guess_parameters (lfLens *lens)
 
const char * lf_get_distortion_model_desc (enum lfDistortionModel model, const char **details, const lfParameter ***params)
 
const char * lf_get_tca_model_desc (enum lfTCAModel model, const char **details, const lfParameter ***params)
 
const char * lf_get_vignetting_model_desc (enum lfVignettingModel model, const char **details, const lfParameter ***params)
 
const char * lf_get_crop_desc (enum lfCropMode mode, const char **details, const lfParameter ***params)
 
const char * lf_get_lens_type_desc (enum lfLensType type, const char **details)
 
cbool lf_lens_interpolate_distortion (const lfLens *lens, float focal, lfLensCalibDistortion *res)
 
cbool lf_lens_interpolate_tca (const lfLens *lens, float focal, lfLensCalibTCA *res)
 
cbool lf_lens_interpolate_vignetting (const lfLens *lens, float focal, float aperture, float distance, lfLensCalibVignetting *res)
 
cbool lf_lens_interpolate_crop (const lfLens *lens, float focal, lfLensCalibCrop *res)
 
DEPRECATED cbool lf_lens_interpolate_fov (const lfLens *lens, float focal, lfLensCalibFov *res)
 
cbool lf_lens_interpolate_real_focal (const lfLens *lens, float focal, lfLensCalibRealFocal *res)
 
void lf_lens_add_calib_distortion (lfLens *lens, const lfLensCalibDistortion *dc)
 
cbool lf_lens_remove_calib_distortion (lfLens *lens, int idx)
 
void lf_lens_add_calib_tca (lfLens *lens, const lfLensCalibTCA *tcac)
 
cbool lf_lens_remove_calib_tca (lfLens *lens, int idx)
 
void lf_lens_add_calib_vignetting (lfLens *lens, const lfLensCalibVignetting *vc)
 
cbool lf_lens_remove_calib_vignetting (lfLens *lens, int idx)
 
void lf_lens_add_calib_crop (lfLens *lens, const lfLensCalibCrop *cc)
 
cbool lf_lens_remove_calib_crop (lfLens *lens, int idx)
 
DEPRECATED void lf_lens_add_calib_fov (lfLens *lens, const lfLensCalibFov *cf)
 
DEPRECATED cbool lf_lens_remove_calib_fov (lfLens *lens, int idx)
 
void lf_lens_add_calib_real_focal (lfLens *lens, const lfLensCalibRealFocal *cf)
 
cbool lf_lens_remove_calib_real_focal (lfLens *lens, int idx)
 

Detailed Description

These structures and functions allow to define and examine the properties of a lens.

Enumeration Type Documentation

enum lfCropMode

Different crop modes.

Enumerator
LF_NO_CROP 

no crop at all

LF_CROP_RECTANGLE 

use a rectangular crop

LF_CROP_CIRCLE 

use a circular crop, e.g. for circular fisheye images

The Lensfun library implements several lens distortion models. This enum lists them.

Distortion usually heavily depends on the focal length, but does not depend on the aperture. In the following, \(r_d\) refers to the distorted radius (normalised distance to image center), and \(r_u\) refers to the undistorted, corrected radius. See section How it is really done for further information.

For a popular explanation of lens distortion see http://www.vanwalree.com/optics/distortion.html

Enumerator
LF_DIST_MODEL_NONE 

Distortion parameters are unknown.

LF_DIST_MODEL_POLY3 

3rd order polynomial model, which is a subset of the PTLens model.

\[r_d = r_u \cdot (1 - k_1 + k_1 r_u^2)\]

The corresponding XML attribute is called “k1”. It defaults to 0.

LF_DIST_MODEL_POLY5 

5th order polynomial model.

\[r_d = r_u \cdot (1 + k_1 r_u^2 + k_2 r_u^4)\]

The corresponding XML attributes are called “k1” and “k2”. They default to 0. Ref: http://www.imatest.com/docs/distortion.html

LF_DIST_MODEL_PTLENS 

PTLens model, which is also used by Hugin.

\[r_d = r_u \cdot (a r_u^3 + b r_u^2 + c r_u + 1 - a - b - c)\]

The corresponding XML attributes are called “a”, “b”, and “c”. They default to 0.

LF_DIST_MODEL_ACM 

Adobe Camera Model. The coordinate system is different here. Everything is measured in units of the focal length of the lens.

\[\begin{aligned} x_d &= x_u (1 + k_1 r_u^2 + k_2 r_u^4 + k_3 r_u^6) + 2x_u(k_4y_u + k_5x_u) + k_5 r_u^2, \\ y_d &= y_u (1 + k_1 r_u^2 + k_2 r_u^4 + k_3 r_u^6) + 2y_u(k_4y_u + k_5x_u) + k_4 r_u^2, \end{aligned} \]

with \(r_u^2 = x_u^2 + y_u^2\). The corresponding XML attributes are called “k1”, “k2”, “k3”, “k4”, and “k5”. They default to 0. Note that Adobe's fisheye model is also covered by this by setting the lens type to "fisheye" and using only the \(k_1\) and \(k_2\) parameters. Ref: http://download.macromedia.com/pub/labs/lensprofile_creator/lensprofile_creator_cameramodel.pdf

enum lfLensType

Lens type. See Change of projection for further information.

Enumerator
LF_UNKNOWN 

Unknown lens type.

LF_RECTILINEAR 

Rectilinear lens.

Straight lines remain stright; 99% of all lenses are of this type.

LF_FISHEYE 

Equidistant fisheye.

Ref: http://wiki.panotools.org/Fisheye_Projection

LF_PANORAMIC 

Panoramic (cylindrical)

Not that there are such lenses, but useful to convert images to this type, especially fish-eye images.

LF_EQUIRECTANGULAR 

Equirectangular.

Not that there are such lenses, but useful to convert images to this type, especially fish-eye images.

LF_FISHEYE_ORTHOGRAPHIC 

Orthographic fisheye.

LF_FISHEYE_STEREOGRAPHIC 

Stereographic fisheye.

LF_FISHEYE_EQUISOLID 

Equisolid fisheye.

LF_FISHEYE_THOBY 

Fisheye as measured by Thoby (for Nikkor 10.5).

Ref: http://michel.thoby.free.fr/Blur_Panorama/Nikkor10-5mm_or_Sigma8mm/Sigma_or_Nikkor/Comparison_Short_Version_Eng.html

enum lfTCAModel

The Lensfun library supports several models for lens lateral chromatic aberrations (also called transversal chromatic aberrations, TCA).

TCAs depend on focal length, but does not depend of the aperture. In the following, \(r_d\) refers to the distorted radius (normalised distance to image center), and \(r_u\) refers to the undistorted, corrected radius. See section How it is really done for further information.

For a popular explanation of chromatic aberrations see http://www.vanwalree.com/optics/chromatic.html

Enumerator
LF_TCA_MODEL_NONE 

No TCA correction data is known.

LF_TCA_MODEL_LINEAR 

Linear lateral chromatic aberrations model.

\[\begin{aligned} r_{d,R} &= r_{u,R} k_R \\ r_{d,B} &= r_{u,B} k_B \end{aligned}\]

The corresponding XML attributes are called “kr” and “kb”. They default to 1. Ref: http://cipa.icomos.org/fileadmin/template/doc/TURIN/403.pdf

LF_TCA_MODEL_POLY3 

Third order polynomial.

\[\begin{aligned} r_{d,R} &= r_{u,R} \cdot (b_R r_{u,R}^2 + c_R r_{u,R} + v_R) \\ r_{d,B} &= r_{u,B} \cdot (b_B r_{u,B}^2 + c_B r_{u,B} + v_B) \end{aligned}\]

The corresponding XML attributes are called “br”, “cr”, “vr”, “bb”, “cb”, and “vb”. vr and vb default to 1, the rest to 0. Ref: http://wiki.panotools.org/Tca_correct

LF_TCA_MODEL_ACM 

Adobe camera model for TCA. The coordinate system is different here. Everything is measured in units of the focal length of the lens.

\[\begin{aligned} x_{d,R} &= \alpha_0 \left(\left(1 + \alpha_1 r_{u,R}^2 + \alpha_2 r_{u,R}^4 + \alpha_3 r_{u,R}^6\right) x_{u,R} + 2(\alpha_4 y_{u,R} + \alpha_5 x_{u,R}) x_{u,R} + \alpha_5 r_{u,R}^2\right), \\ y_{d,R} &= \alpha_0 \left(\left(1 + \alpha_1 r_{u,R}^2 + \alpha_2 r_{u,R}^4 + \alpha_3 r_{u,R}^6\right) y_{u,R} + 2(\alpha_4 y_{u,R} + \alpha_5 x_{u,R}) y_{u,R} + \alpha_4 r_{u,R}^2\right), \\ x_{d,B} &= \beta_0 \left(\left(1 + \beta_1 r_{u,B}^2 + \beta_2 r_{u,B}^4 + \beta_3 r_{u,B}^6\right) x_{u,B} + 2(\beta_4 y_{u,B} + \beta_5 x_{u,B}) x_{u,B} + \beta_5 r_{u,B}^2\right), \\ y_{d,B} &= \beta_0 \left(\left(1 + \beta_1 r_{u,B}^2 + \beta_2 r_{u,B}^4 + \beta_3 r_{u,B}^6\right) y_{u,B} + 2(\beta_4 y_{u,B} + \beta_5 x_{u,B}) y_{u,B} + \beta_4 r_{u,B}^2\right), \end{aligned}\]

with \(r_{u,\ast} = \sqrt{x_{u,\ast}^2 + y_{u,\ast}^2}\). The corresponding XML attributes are called “alpha0” to “alpha5”, and “beta0” to “beta5”. alpha0 and beta0 default to 1, the rest to 0. Ref: http://download.macromedia.com/pub/labs/lensprofile_creator/lensprofile_creator_cameramodel.pdf

The Lensfun library supports several models for lens vignetting correction.

We focus on optical and natural vignetting since they can be generalized for all lenses of a certain type; mechanical vignetting is out of the scope of this library.

Vignetting is dependent on focal length and aperture. There is also a slight dependence on focus distance. In the following, \(C_d\) refers to the corrected destination image pixel brightness, and \(C_s\) refers to the uncorrected source image pixel brightness.

For a popular explanation of vignetting see http://www.vanwalree.com/optics/vignetting.html

Enumerator
LF_VIGNETTING_MODEL_NONE 

No vignetting correction data is known.

LF_VIGNETTING_MODEL_PA 

Pablo D'Angelo vignetting model (which is a more general variant of the \(\cos^4\) law).

\[C_d = C_s \cdot (1 + k_1 r^2 + k_2 r^4 + k_3 r^6)\]

The corresponding XML attributes are called “k1”, “k2”, and “k3”. They default to 0. Ref: http://hugin.sourceforge.net/tech/

LF_VIGNETTING_MODEL_ACM 

Adobe's vignetting model. It differs from D'Angelo's model only in the coordinate system. Everything is measured in units of the focal length of the lens.

\[C_d = C_s \cdot (1 + \alpha_1 r^2 + \alpha_2 r^4 + \alpha_3 r^6).\]

The corresponding XML attributes are called “alpha1”, “alpha2”, and “alpha3”. They default to 0. Ref: http://download.macromedia.com/pub/labs/lensprofile_creator/lensprofile_creator_cameramodel.pdf

Function Documentation

const char* lf_get_crop_desc ( enum lfCropMode  mode,
const char **  details,
const lfParameter ***  params 
)
const char* lf_get_distortion_model_desc ( enum lfDistortionModel  model,
const char **  details,
const lfParameter ***  params 
)
const char* lf_get_lens_type_desc ( enum lfLensType  type,
const char **  details 
)
const char* lf_get_tca_model_desc ( enum lfTCAModel  model,
const char **  details,
const lfParameter ***  params 
)
const char* lf_get_vignetting_model_desc ( enum lfVignettingModel  model,
const char **  details,
const lfParameter ***  params 
)
void lf_lens_add_calib_crop ( lfLens lens,
const lfLensCalibCrop cc 
)
void lf_lens_add_calib_distortion ( lfLens lens,
const lfLensCalibDistortion dc 
)
DEPRECATED void lf_lens_add_calib_fov ( lfLens lens,
const lfLensCalibFov cf 
)
void lf_lens_add_calib_real_focal ( lfLens lens,
const lfLensCalibRealFocal cf 
)
void lf_lens_add_calib_tca ( lfLens lens,
const lfLensCalibTCA tcac 
)
void lf_lens_add_calib_vignetting ( lfLens lens,
const lfLensCalibVignetting vc 
)
cbool lf_lens_check ( lfLens lens)
See Also
lfLens::Check
void lf_lens_copy ( lfLens dest,
const lfLens source 
)

Copy the data from one lfLens structure into another.

Parameters
destThe destination object
sourceThe source object
See Also
lfLens::operator = (const lfCamera &)
void lf_lens_destroy ( lfLens lens)

Destroy a lfLens object.

This is equivalent to C++ "delete lens".

Parameters
lensThe lens object to destroy.
See Also
lfLens::~lfLens
void lf_lens_guess_parameters ( lfLens lens)
cbool lf_lens_interpolate_crop ( const lfLens lens,
float  focal,
lfLensCalibCrop res 
)
cbool lf_lens_interpolate_distortion ( const lfLens lens,
float  focal,
lfLensCalibDistortion res 
)
DEPRECATED cbool lf_lens_interpolate_fov ( const lfLens lens,
float  focal,
lfLensCalibFov res 
)
cbool lf_lens_interpolate_real_focal ( const lfLens lens,
float  focal,
lfLensCalibRealFocal res 
)
cbool lf_lens_interpolate_tca ( const lfLens lens,
float  focal,
lfLensCalibTCA res 
)
cbool lf_lens_interpolate_vignetting ( const lfLens lens,
float  focal,
float  aperture,
float  distance,
lfLensCalibVignetting res 
)
lfLens* lf_lens_new ( )

Create a new lens object.

Returns
A new empty lens object.
See Also
lfLens::lfLens
cbool lf_lens_remove_calib_crop ( lfLens lens,
int  idx 
)
cbool lf_lens_remove_calib_distortion ( lfLens lens,
int  idx 
)
DEPRECATED cbool lf_lens_remove_calib_fov ( lfLens lens,
int  idx 
)
cbool lf_lens_remove_calib_real_focal ( lfLens lens,
int  idx 
)
cbool lf_lens_remove_calib_tca ( lfLens lens,
int  idx 
)
cbool lf_lens_remove_calib_vignetting ( lfLens lens,
int  idx 
)