lfModifier Struct Reference
[Image correction]

A modifier object contains optimized data required to rectify a image. More...

#include <lensfun.h>

List of all members.

Public Member Functions

int Initialize (const lfLens *lens, lfPixelFormat format, float focal, float aperture, float distance, float scale, lfLensType targeom, int flags, bool reverse)

Initialize the process of correcting aberrations in a image.

void Destroy ()

Destroy the modifier object.

void AddCoordCallback (lfModifyCoordFunc callback, int priority, void *data, size_t data_size)

Add a user-defined callback to the coordinate correction chain.

void AddSubpixelCallback (lfSubpixelCoordFunc callback, int priority, void *data, size_t data_size)

Add a user-defined callback to the subpixel coordinate rectification chain.

void AddColorCallback (lfModifyColorFunc callback, int priority, void *data, size_t data_size)

Add a user-defined callback to the color modification chain.

bool AddSubpixelCallbackTCA (lfLensCalibTCA &model, bool reverse=false)

Add the stock TCA correcting callback into the chain.

bool AddColorCallbackVignetting (lfLensCalibVignetting &model, lfPixelFormat format, bool reverse=false)

Add the stock lens vignetting correcting callback into the chain.

bool AddColorCallbackCCI (const lfLens *lens, lfPixelFormat format, bool reverse=false)

Add the stock CCI correcting callback into the chain.

bool AddCoordCallbackDistortion (lfLensCalibDistortion &model, bool reverse=false)

Add the stock lens distortion correcting callback into the chain.

bool AddCoordCallbackGeometry (lfLensType from, lfLensType to, float focal)

Add the stock lens geometry rectification callback into the chain.

bool AddCoordCallbackScale (float scale, bool reverse=false)

Add the stock image scaling callback into the chain.

float GetAutoScale (bool reverse)

Compute the automatic scale factor for the image.

bool ApplySubpixelDistortion (float xu, float yu, int width, int height, float *res) const

Image correction stage 1: apply subpixel distortions.

bool ApplyColorModification (void *pixels, float x, float y, int width, int height, int comp_role, int row_stride) const

Image correction step 2: fix image colors.

bool ApplyGeometryDistortion (float xu, float yu, int width, int height, float *res) const

Image correction step 3: apply the transforms on a block of pixel coordinates.

bool ApplySubpixelGeometryDistortion (float xu, float yu, int width, int height, float *res) const

Apply stage 1 & 3 in one step.

Static Public Member Functions

static lfModifier * Create (const lfLens *lens, float crop, int width, int height)

Create a empty image modifier object.

Detailed Description

A modifier object contains optimized data required to rectify a image.

You can either create an empty modifier object and then enable the required modification functions individually, or you can take a lens object, which contains a set of correction models, and create a modifier object from it.

Every image modification has a corresponding inverse function, e.g. the library allows both to correct lens distortions and to simulate lens characteristics.

The normal order of applying a lens correction on a image is:

Fix chromatic aberrations (TCA)
Fix lens vignetting
Fix lens colour contribution
Fix lens distortion
Fix lens geometry
Scale the image

This process is divided into three stages.

In the first stage - subpixel distortion - application corrects transversal chromatic aberrations. For every target pixel coordinate the modifier will return you three new coordinates: the first will tell you the coordinates of the red component, second of the green, and third of the red component. This operation requires building new image in a new allocated buffer: you cannot modify the image in place, or bad things will happen.

Then the colors of the image pixels are fixed (vignetting and colour contribution). You pass a pointer to your pixel data, and it will be modified in place.

And finally, the distortions introduced by the lens are removed (distortion and geometry), and an additional scaling factor is applied if required. This again requires copying the image, but you can use the same buffers as in stage one, just in reverse order.

Of course, you can skip some stages of the process, e.g. if you, for example, don't want to change a fisheye image to a rectilinear you can omit that step.

Obviously, when simulating lens distortions, the modification stages must be applied in reverse order. While the library takes care to reverse the steps which are grouped into a single stage, the application must apply the stages themselves in reverse order.

HOWEVER. Doing it in three stage is not memory efficient, and is prone to error accumulation because you have to interpolate pixels twice - once during stage 1 and once during stage 3. To avoid this, it is acceptable to do stages 1 & 3 in one step, provided that the changes made in stage 2 are applied to R,G,B channels separately, e.g. the output R from the stage 2 depends ONLY of the input R to the stage 2, same about G and B. This is true for vignetting correction, so we can apply stages in the order 2, (1+3). In this case the output R,G,B coordinates from stage 1 are feed directly into the ApplyGeometryDistortion() function, which will correct the R,G,B coordinates independently.

Examples:: tmod.cpp.

Member Function Documentation

void lfModifier::AddColorCallback	(	lfModifyColorFunc	callback,
		int	priority,
		void *	data,
		size_t	data_size
	)

Add a user-defined callback to the color modification chain.

Parameters:

	callback	The callback to be called for every strip of pixels.
	priority	Callback priority (0-999). Callbacks are always called in increasing priority order.
	data	A pointer to additional user data. A copy of this data is made internally, so client application may do whatever it needs with this data after this call.
	data_size	User data size in bytes. If data size is zero, the data is not copied and instead a verbatim copy of the 'data' parameter is passed to the callback.

bool lfModifier::AddColorCallbackCCI	(	const lfLens *	lens,
		lfPixelFormat	format,
		bool	reverse = `false`
	)

Add the stock CCI correcting callback into the chain.

The CCI correction callback always has a fixed priority of 750 when rectifying a image and 250 on reverse transform.

Parameters:

	lens	The lens for which CCI is to be corrected.
	format	The pixel format of the image to be corrected.
	reverse	If true, the reverse model will be applied, e.g. simulate a lens' CCI on a clean image.

Returns:: True if CCI model is valid and the callback was added to chain.

bool lfModifier::AddColorCallbackVignetting	(	lfLensCalibVignetting &	model,
		lfPixelFormat	format,
		bool	reverse = `false`
	)

Add the stock lens vignetting correcting callback into the chain.

The vignetting correction callback always has a fixed priority of 250 when rectifying a image or 750 when doing reverse transform.

Parameters:

	model	Lens vignetting model data.
	format	Pixel format of your image (bits per pixel component)
	reverse	If true, the reverse model will be applied, e.g. simulate a lens' vignetting on a clean image.

Returns:: True if vignetting model is valid and the callback was added to chain.

void lfModifier::AddCoordCallback	(	lfModifyCoordFunc	callback,
		int	priority,
		void *	data,
		size_t	data_size
	)

Add a user-defined callback to the coordinate correction chain.

Parameters:

	callback	The callback to be called for every strip of pixels.
	priority	Callback priority (0-999). Callbacks are always called in increasing priority order.
	data	A pointer to additional user data. A copy of this data is made internally, so client application may do whatever it needs with this data after this call.
	data_size	User data size in bytes. If data size is zero, the data is not copied and instead a verbatim copy of the 'data' parameter is passed to the callback.

bool lfModifier::AddCoordCallbackDistortion	(	lfLensCalibDistortion &	model,
		bool	reverse = `false`
	)

Add the stock lens distortion correcting callback into the chain.

The distortion correction callback always has a fixed priority of 250 when rectifying a image and 750 on reverse transform.

Parameters:

	model	Lens distortion model data.
	reverse	If true, the reverse model will be applied, e.g. simulate a lens' distortion on a clean image.

Returns:: True if distortion model is valid and the callback was added to chain.

bool lfModifier::AddCoordCallbackGeometry	(	lfLensType	from,
		lfLensType	to,
		float	focal
	)

Add the stock lens geometry rectification callback into the chain.

The geometry correction callback always has a fixed priority of 500.

Parameters:

	from	The lens model for source image.
	to	The lens model for target image.
	focal	Lens focal distance.

Returns:: True if a library has a callback for given from->to conversion.

bool lfModifier::AddCoordCallbackScale	(	float	scale,
		bool	reverse = `false`
	)

Add the stock image scaling callback into the chain.

The scaling callback always has a fixed priority of 100. Note that scaling should be always the first operation to perform no matter if we're doing a forward or reverse transform.

Parameters:

	scale	Image scale. If equal to 0.0, the image is automatically scaled so that there won't be any unfilled gaps in the resulting image. Note that all coordinate distortion callbacks must be already added to the stack for this to work correctly!
	reverse	If true, the reverse model will be applied.

Returns:: True if the callback was added to chain.

void lfModifier::AddSubpixelCallback	(	lfSubpixelCoordFunc	callback,
		int	priority,
		void *	data,
		size_t	data_size
	)

Add a user-defined callback to the subpixel coordinate rectification chain.

Parameters:

	callback	The callback to be called for every strip of pixels.
	priority	Callback priority (0-999). Callbacks are always called in increasing priority order.
	data	A pointer to additional user data. A copy of this data is made internally, so client application may do whatever it needs with this data after this call.
	data_size	User data size in bytes. If data size is zero, the data is not copied and instead a verbatim copy of the 'data' parameter is passed to the callback.

bool lfModifier::AddSubpixelCallbackTCA	(	lfLensCalibTCA &	model,
		bool	reverse = `false`
	)

Add the stock TCA correcting callback into the chain.

The TCA correction callback always has a fixed priority of 500. The behaviour is undefined if you'll add more than one TCA correction callback to a modifier.

Parameters:

	model	Lens TCA model data.
	reverse	If true, the reverse model will be applied, e.g. simulate a lens' TCA on a clean image.

Returns:: True if TCA model is valid and the callback was added to chain.

bool lfModifier::ApplyColorModification	(	void *	pixels,
		float	x,
		float	y,
		int	width,
		int	height,
		int	comp_role,
		int	row_stride
	)			const

Image correction step 2: fix image colors.

This includes vignetting transform and CCI transform (e.g. rectification of image colors).

Parameters:

	pixels	This points to image pixels. The actual pixel format depends on both pixel_format and comp_role arguments. The results are stored in place in the same format.
	x	The X coordinate of the corner of the block.
	y	The Y coordinate of the corner of the block.
	width	The width of the image block in pixels.
	height	The height of the image block in pixels.
	comp_role	The role of every pixel component. This is a bitfield, made by one of the LF_CR_X macros which defines the roles of every pixel field. For example, LF_CR_4(RED,GREEN,BLUE,UNKNOWN) will define a RGBA (or RGBX) pixel format, and the UNKNOWN field will not be modified.
	row_stride	The size of a image row in bytes. This can be actually different from width * pixel_width as some image formats use funny things like alignments, filler bytes etc.

Returns:: true if return buffer has been altered, false if nothing to do

Examples:: tmod.cpp.

bool lfModifier::ApplyGeometryDistortion	(	float	xu,
		float	yu,
		int	width,
		int	height,
		float *	res
	)			const

Image correction step 3: apply the transforms on a block of pixel coordinates.

The undistorted coordinates are computed for every pixel in a rectangular block: (xu, yu), (xu+1, yu), ... , (xu + width - 1, yu), (xu, yu + 1), ..., (xu + width - 1, yu + height - 1).

The corrected coordinates are put into the output buffer sequentially, X and Y values.

This routine has been designed to be safe to use in parallel from several threads.

Parameters:

	xu	The undistorted X coordinate of the start of the block of pixels.
	yu	The undistorted Y coordinate of the start of the block of pixels.
	width	The width of the block in pixels.
	height	The height of the block in pixels.
	res	A pointer to an output array which receives the respective X and Y distorted coordinates for every pixel of the block. The size of this array must be at least widthheight2 elements.

Returns:: true if return buffer has been filled, false if nothing to do

Examples:: tmod.cpp.

bool lfModifier::ApplySubpixelDistortion	(	float	xu,
		float	yu,
		int	width,
		int	height,
		float *	res
	)			const

Image correction stage 1: apply subpixel distortions.

The undistorted R,G,B coordinates are computed for every pixel in a square block: (xu, yu), (xu+1, yu), ... , (xu + width - 1, yu), (xu, yu + 1), ..., (xu + width - 1, yu + height - 1).

Returns the corrected coordinates separately for R/G/B channels The resulting coordinates are put into the output buffer sequentially, X and Y values.

This routine has been designed to be safe to use in parallel from several threads.

Parameters:

	xu	The undistorted X coordinate of the start of the block of pixels.
	yu	The undistorted Y coordinate of the start of the block of pixels.
	width	The width of the block in pixels.
	height	The height of the block in pixels.
	res	A pointer to an output array which receives the respective X and Y distorted coordinates of the red, green and blue channels for every pixel of the block. The size of this array must be at least widthheight2*3 elements.

Returns:: true if return buffer has been filled, false if nothing to do

Examples:: tmod.cpp.

bool lfModifier::ApplySubpixelGeometryDistortion	(	float	xu,
		float	yu,
		int	width,
		int	height,
		float *	res
	)			const

Apply stage 1 & 3 in one step.

See the main comment to the lfModifier class. The undistorted R,G,B coordinates are computed for every pixel in a square block: (xu, yu), (xu+1, yu), ... , (xu + width - 1, yu), (xu, yu + 1), ..., (xu + width - 1, yu + height - 1).

Returns the corrected coordinates separately for R/G/B channels The resulting coordinates are put into the output buffer sequentially, X and Y values.

This routine has been designed to be safe to use in parallel from several threads.

Parameters:

	xu	The undistorted X coordinate of the start of the block of pixels.
	yu	The undistorted Y coordinate of the start of the block of pixels.
	width	The width of the block in pixels.
	height	The height of the block in pixels.
	res	A pointer to an output array which receives the respective X and Y distorted coordinates for every pixel of the block. The size of this array must be at least widthheight2 elements.

Returns:: true if return buffer has been filled, false if nothing to do

Examples:: tmod.cpp.

static lfModifier* lfModifier::Create	(	const lfLens *	lens,
		float	crop,
		int	width,
		int	height
	)			`[static]`

Create a empty image modifier object.

Before using the returned object you must add the required modifier callbacks (see methods AddXXXCallback below).

Parameters:

	lens	The center shift for all modifications from this lens object will be used. If NULL, CenterX == CenterY == 0.0. Also the lens crop factor together with camera crop factor for all distortions.
	crop	The crop factor for current camera. The distortion models will take this into account if lens models were measured on a camera with a different crop factor.
	width	The width of the image you want to correct.
	height	The height of the image you want to correct.

Returns:: A new empty image modifier object.

Examples:: tmod.cpp.

void lfModifier::Destroy ( )

Destroy the modifier object.

This is the only correct way to destroy a lfModifier object.

Examples:: tmod.cpp.

float lfModifier::GetAutoScale ( bool reverse )

Compute the automatic scale factor for the image.

This expects that all coordinate distortion callbacks are already set up and working. The function will try at its best to find a scale value that will ensure that no pixels with coordinates out of range will get into the resulting image. But since this is an approximative method, the returned scale sometimes is a little less than the optimal scale (e.g. you can still get some black corners with some high-distortion cases).

Parameters:

reverse

If true, the reverse scaling factor is computed.

int lfModifier::Initialize	(	const lfLens *	lens,
		lfPixelFormat	format,
		float	focal,
		float	aperture,
		float	distance,
		float	scale,
		lfLensType	targeom,
		int	flags,
		bool	reverse
	)

Initialize the process of correcting aberrations in a image.

You must provide the original image width/height even if you plan to correct just a part of the image.

The modifier object will be set up to rectify all aberrations found in the lens description. Make sure the focal length and aperture value are correct, otherwise the modifier may pick up wrong model parameters!

Parameters:

	lens	The lens which aberrations you want to correct in a image.
	format	Pixel format of your image (bits per pixel component)
	focal	The focal length at which the image was taken (distortion, tca, vignetting).
	aperture	The aperture at which the image was taken (vignetting).
	distance	The approximative distance-to-subject (vignetting).
	scale	An additional scale factor to be applied onto the image (1.0 - no scaling; 0.0 - automatic scaling).
	targeom	Target geometry. If LF_MODIFY_GEOMETRY is set in flags and targeom is different from lens->Type, a geometry conversion will be applied on the image.
	flags	A set of flags (se LF_MODIFY_XXX) telling which distortions you want corrected. A value of LF_MODIFY_ALL orders correction of everything possible. If the LF_MODIFY_REVERSE flag is set, the object is prepared for a reverse modification.
	reverse	If this parameter is true, a reverse transform will be prepared. That is, you take a undistorted image at input and convert it so that it will look as if it would be a shot made with lens.

Returns:: A set of LF_MODIFY_XXX flags in effect. This is the flags argument with dropped bits for operations which are actually no-ops.

Examples:: tmod.cpp.

The documentation for this struct was generated from the following file:

lensfun.h


Public Member Functions
int	Initialize (const lfLens *lens, lfPixelFormat format, float focal, float aperture, float distance, float scale, lfLensType targeom, int flags, bool reverse)
	Initialize the process of correcting aberrations in a image.
void	Destroy ()
	Destroy the modifier object.
void	AddCoordCallback (lfModifyCoordFunc callback, int priority, void *data, size_t data_size)
	Add a user-defined callback to the coordinate correction chain.
void	AddSubpixelCallback (lfSubpixelCoordFunc callback, int priority, void *data, size_t data_size)
	Add a user-defined callback to the subpixel coordinate rectification chain.
void	AddColorCallback (lfModifyColorFunc callback, int priority, void *data, size_t data_size)
	Add a user-defined callback to the color modification chain.
bool	AddSubpixelCallbackTCA (lfLensCalibTCA &model, bool reverse=false)
	Add the stock TCA correcting callback into the chain.
bool	AddColorCallbackVignetting (lfLensCalibVignetting &model, lfPixelFormat format, bool reverse=false)
	Add the stock lens vignetting correcting callback into the chain.
bool	AddColorCallbackCCI (const lfLens *lens, lfPixelFormat format, bool reverse=false)
	Add the stock CCI correcting callback into the chain.
bool	AddCoordCallbackDistortion (lfLensCalibDistortion &model, bool reverse=false)
	Add the stock lens distortion correcting callback into the chain.
bool	AddCoordCallbackGeometry (lfLensType from, lfLensType to, float focal)
	Add the stock lens geometry rectification callback into the chain.
bool	AddCoordCallbackScale (float scale, bool reverse=false)
	Add the stock image scaling callback into the chain.
float	GetAutoScale (bool reverse)
	Compute the automatic scale factor for the image.
bool	ApplySubpixelDistortion (float xu, float yu, int width, int height, float *res) const
	Image correction stage 1: apply subpixel distortions.
bool	ApplyColorModification (void *pixels, float x, float y, int width, int height, int comp_role, int row_stride) const
	Image correction step 2: fix image colors.
bool	ApplyGeometryDistortion (float xu, float yu, int width, int height, float *res) const
	Image correction step 3: apply the transforms on a block of pixel coordinates.
bool	ApplySubpixelGeometryDistortion (float xu, float yu, int width, int height, float *res) const
	Apply stage 1 & 3 in one step.
Static Public Member Functions
static lfModifier *	Create (const lfLens *lens, float crop, int width, int height)
	Create a empty image modifier object.

lfModifier Struct Reference [Image correction]

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

lfModifier Struct Reference
[Image correction]