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

Classes
struct	lfLensCalibAttributes
	Lens calibration attributes. More...

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	lfLensCalibrationSet
	A set of calibration data. 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
lfLens *	lf_lens_create ()
	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)

void	lf_lens_add_mount (lfLens lens, const char val)

const char const	lf_lens_get_mount_names (const 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 crop, float focal, lfLensCalibDistortion res)

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

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

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

void	lf_lens_add_calib_distortion (lfLens lens, const lfLensCalibDistortion dc)

void	lf_lens_add_calib_tca (lfLens lens, const lfLensCalibTCA tcac)

void	lf_lens_add_calib_vignetting (lfLens lens, const lfLensCalibVignetting vc)

void	lf_lens_add_calib_crop (lfLens lens, const lfLensCalibCrop cc)

void	lf_lens_remove_calibrations (lfLens *lens)

int	lf_lens_available_modifications (lfLens *lens, float crop)

Detailed Description

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

Enumeration Type Documentation

◆ lfCropMode

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

◆ lfDistortionModel

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

◆ lfLensType

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

◆ lfTCAModel

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

◆ lfVignettingModel

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 / (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 / (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

◆ lf_get_crop_desc()

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

See also: lfLens::GetCropDesc

◆ lf_get_distortion_model_desc()

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

See also: lfLens::GetDistortionModelDesc

◆ lf_get_lens_type_desc()

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

See also: lfLens::GetLensTypeDesc

◆ lf_get_tca_model_desc()

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

See also: lfLens::GetTCAModelDesc

◆ lf_get_vignetting_model_desc()

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

See also: lfLens::GetVignettingModelDesc

◆ lf_lens_add_calib_crop()

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

See also: lfLens::AddCalibCrop

◆ lf_lens_add_calib_distortion()

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

See also: lfLens::AddCalibDistortion

◆ lf_lens_add_calib_tca()

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

See also: lfLens::AddCalibTCA

◆ lf_lens_add_calib_vignetting()

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

See also: lfLens::AddCalibVignetting

◆ lf_lens_add_mount()

void lf_lens_add_mount	(	lfLens *	lens,
		const char *	val
	)

See also: lfLens::AddMount

◆ lf_lens_available_modifications()

int lf_lens_available_modifications	(	lfLens *	lens,
		float	crop
	)

See also: lfLens::AvailableModifications

◆ lf_lens_check()

cbool lf_lens_check ( lfLens * lens )

See also: lfLens::Check

◆ lf_lens_copy()

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

◆ lf_lens_create()

lfLens* lf_lens_create ( )

Create a new lens object.

Returns: A new empty lens object.

See also: lfLens::lfLens

◆ lf_lens_destroy()

void lf_lens_destroy ( lfLens * lens )

Destroy a lfLens object.

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