lensfun: Structures and functions for lenses

lensfun 0.3.1.0

- Main Page
- Related Pages
- Modules
- Classes
- Files
- Examples

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 }
| 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 }
| 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 }
| 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
lfLens * | lf_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

enum lfDistortionModel

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.

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

enum lfVignettingModel

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/

## Function Documentation

const char* lf_get_crop_desc | ( | enum lfCropMode | mode,
|  | const char ** | details,
|  | const lfParameter *** | params
| ) |  |

See also
  lfLens::GetCropDesc

const char* lf_get_distortion_model_desc | ( | enum lfDistortionModel | model,
|  | const char ** | details,
|  | const lfParameter *** | params
| ) |  |

See also
  lfLens::GetDistortionModelDesc

const char* lf_get_lens_type_desc | ( | enum lfLensType | type,
|  | const char ** | details
| ) |  |

See also
  lfLens::GetLensTypeDesc

const char* lf_get_tca_model_desc | ( | enum lfTCAModel | model,
|  | const char ** | details,
|  | const lfParameter *** | params
| ) |  |

See also
  lfLens::GetTCAModelDesc

const char* lf_get_vignetting_model_desc | ( | enum lfVignettingModel | model,
|  | const char ** | details,
|  | const lfParameter *** | params
| ) |  |

See also
  lfLens::GetVignettingModelDesc

void lf_lens_add_calib_crop | ( | lfLens * | lens,
|  | const lfLensCalibCrop * | cc
| ) |  |

See also
  lfLens::AddCalibCrop

void lf_lens_add_calib_distortion | ( | lfLens * | lens,
|  | const lfLensCalibDistortion * | dc
| ) |  |

See also
  lfLens::AddCalibDistortion

DEPRECATED void lf_lens_add_calib_fov | ( | lfLens * | lens,
|  | const lfLensCalibFov * | cf
| ) |  |

See also
  lfLens::AddCalibFov

void lf_lens_add_calib_real_focal | ( | lfLens * | lens,
|  | const lfLensCalibRealFocal * | cf
| ) |  |

See also
  lfLens::AddCalibRealFocal

void lf_lens_add_calib_tca | ( | lfLens * | lens,
|  | const lfLensCalibTCA * | tcac
| ) |  |

See also
  lfLens::AddCalibTCA

void lf_lens_add_calib_vignetting | ( | lfLens * | lens,
|  | const lfLensCalibVignetting * | vc
| ) |  |

See also
  lfLens::AddCalibVignetting

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

  dest | The destination object
  source | The 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

  lens | The lens object to destroy.

See also
  lfLens::~lfLens

void lf_lens_guess_parameters | ( | lfLens * | lens | ) |

See also
  lfLens::GuessParameters

cbool lf_lens_interpolate_crop | ( | const lfLens * | lens,
|  | float | focal,
|  | lfLensCalibCrop * | res
| ) |  |

See also
  lfLens::InterpolateCrop

cbool lf_lens_interpolate_distortion | ( | const lfLens * | lens,
|  | float | focal,
|  | lfLensCalibDistortion * | res
| ) |  |

See also
  lfLens::InterpolateDistortion

DEPRECATED cbool lf_lens_interpolate_fov | ( | const lfLens * | lens,
|  | float | focal,
|  | lfLensCalibFov * | res
| ) |  |

See also
  lfLens::InterpolateFov

cbool lf_lens_interpolate_real_focal | ( | const lfLens * | lens,
|  | float | focal,
|  | lfLensCalibRealFocal * | res
| ) |  |

See also
  lfLens::InterpolateRealFocal

cbool lf_lens_interpolate_tca | ( | const lfLens * | lens,
|  | float | focal,
|  | lfLensCalibTCA * | res
| ) |  |

See also
  lfLens::InterpolateTCA

cbool lf_lens_interpolate_vignetting | ( | const lfLens * | lens,
|  | float | focal,
|  | float | aperture,
|  | float | distance,
|  | lfLensCalibVignetting * | res
| ) |  |

See also
  lfLens::InterpolateVignetting

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
| ) |  |

See also
  lfLens::RemoveCalibCrop

cbool lf_lens_remove_calib_distortion | ( | lfLens * | lens,
|  | int | idx
| ) |  |

See also
  lfLens::RemoveCalibDistortion

DEPRECATED cbool lf_lens_remove_calib_fov | ( | lfLens * | lens,
|  | int | idx
| ) |  |

See also
  lfLens::RemoveCalibFov

cbool lf_lens_remove_calib_real_focal | ( | lfLens * | lens,
|  | int | idx
| ) |  |

See also
  lfLens::RemoveCalibRealFocal

cbool lf_lens_remove_calib_tca | ( | lfLens * | lens,
|  | int | idx
| ) |  |

See also
  lfLens::RemoveCalibTCA

cbool lf_lens_remove_calib_vignetting | ( | lfLens * | lens,
|  | int | idx
| ) |  |

See also
  lfLens::RemoveCalibVignetting