lensfun.h

Go to the documentation of this file.

/*
    LensFun - a library for maintaining a database of photographical lenses,
    and providing the means to correct some of the typical lens distortions.
    Copyright (C) 2007 by Andrew Zabolotny
 
    This library is free software; you can redistribute it and/or
    modify it under the terms of the GNU Library General Public
    License as published by the Free Software Foundation; either
    version 2 of the License, or (at your option) any later version.
 
    This library is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    Library General Public License for more details.
 
    You should have received a copy of the GNU Library General Public
    License along with this library; if not, write to the Free
    Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
 
#ifndef __LENSFUN_H__
#define __LENSFUN_H__
 
#include <stddef.h>
 
#ifdef __cplusplus
extern "C" {
#  define C_TYPEDEF(t,c)
#else
#  define C_TYPEDEF(t,c) typedef t c c;
#endif
 
/*----------------------------------------------------------------------------*/
 
#define LF_VERSION_MAJOR        0
#define LF_VERSION_MINOR        2
#define LF_VERSION_MICRO        7
#define LF_VERSION_BUGFIX       0
#define LF_VERSION      ((LF_VERSION_MAJOR << 24) | (LF_VERSION_MINOR << 16) | (LF_VERSION_MICRO << 8) | LF_VERSION_BUGFIX)
 
#if defined CONF_LENSFUN_STATIC
#   define LF_EXPORT
#else
#   ifdef CONF_SYMBOL_VISIBILITY
#       if defined PLATFORM_WINDOWS
#           define LF_EXPORT    __declspec(dllexport)
#       elif defined CONF_COMPILER_GCC
#           define LF_EXPORT    __attribute__((visibility("default")))
#       else
#           error "I don't know how to change symbol visibility for your compiler"
#       endif
#   else
#       if defined PLATFORM_WINDOWS || defined _MSC_VER
#           define LF_EXPORT    __declspec(dllimport)
#       else
#           define LF_EXPORT
#       endif
#   endif
#endif
 
#define cbool int
 
typedef char *lfMLstr;
 
enum lfError
{
    LF_NO_ERROR = 0,
    LF_WRONG_FORMAT
};
 
C_TYPEDEF (enum, lfError)
 
 
LF_EXPORT void lf_free (void *data);
 
LF_EXPORT const char *lf_mlstr_get (const lfMLstr str);
 
LF_EXPORT lfMLstr lf_mlstr_add (lfMLstr str, const char *lang, const char *trstr);
 
LF_EXPORT lfMLstr lf_mlstr_dup (const lfMLstr str);
 
/*----------------------------------------------------------------------------*/
 
struct LF_EXPORT lfMount
{
    lfMLstr Name;
    char **Compat;
 
#ifdef __cplusplus
 
    lfMount ();
 
    lfMount &operator = (const lfMount &other);
 
    ~lfMount ();
 
    void SetName (const char *val, const char *lang = NULL);
 
    void AddCompat (const char *val);
 
    bool Check ();
#endif
};
 
C_TYPEDEF (struct, lfMount)
 
 
LF_EXPORT lfMount *lf_mount_new ();
 
LF_EXPORT void lf_mount_destroy (lfMount *mount);
 
LF_EXPORT void lf_mount_copy (lfMount *dest, const lfMount *source);
 
LF_EXPORT cbool lf_mount_check (lfMount *mount);
 
/*----------------------------------------------------------------------------*/
 
struct LF_EXPORT lfCamera
{
    lfMLstr Maker;
    lfMLstr Model;
    lfMLstr Variant;
    char *Mount;
    float CropFactor;
    int Score;
 
#ifdef __cplusplus
 
    lfCamera ();
 
    lfCamera (const lfCamera &other);
 
    ~lfCamera ();
 
    lfCamera &operator = (const lfCamera &other);
 
    void SetMaker (const char *val, const char *lang = NULL);
 
    void SetModel (const char *val, const char *lang = NULL);
 
    void SetVariant (const char *val, const char *lang = NULL);
 
    void SetMount (const char *val);
 
    bool Check ();
#endif
};
 
C_TYPEDEF (struct, lfCamera)
 
 
LF_EXPORT lfCamera *lf_camera_new ();
 
LF_EXPORT void lf_camera_destroy (lfCamera *camera);
 
LF_EXPORT void lf_camera_copy (lfCamera *dest, const lfCamera *source);
 
LF_EXPORT cbool lf_camera_check (lfCamera *camera);
 
/*----------------------------------------------------------------------------*/
 
enum lfDistortionModel
{
    LF_DIST_MODEL_NONE,
    LF_DIST_MODEL_POLY3,
    LF_DIST_MODEL_POLY5,
    LF_DIST_MODEL_FOV1,
    LF_DIST_MODEL_PTLENS,
};
 
C_TYPEDEF (enum, lfDistortionModel)
 
 
struct lfLensCalibDistortion
{
    enum lfDistortionModel Model;
    float Focal;
    float Terms [3];
};
 
C_TYPEDEF (struct, lfLensCalibDistortion)
 
 
enum lfTCAModel
{
    LF_TCA_MODEL_NONE,
    LF_TCA_MODEL_LINEAR,
 
    LF_TCA_MODEL_POLY3
};
 
C_TYPEDEF (enum, lfTCAModel)
 
 
struct lfLensCalibTCA
{
    enum lfTCAModel Model;
    float Focal;
    float Terms [6];
};
 
C_TYPEDEF (struct, lfLensCalibTCA)
 
 
enum lfVignettingModel
{
    LF_VIGNETTING_MODEL_NONE,
    LF_VIGNETTING_MODEL_PA
};
 
C_TYPEDEF (enum, lfVignettingModel)
 
 
struct lfLensCalibVignetting
{
    enum lfVignettingModel Model;
    float Focal;
    float Aperture;
    float Distance;
    float Terms [3];
};
 
C_TYPEDEF (struct, lfLensCalibVignetting)
 
 
enum lfCropMode
{
    LF_NO_CROP,
    LF_CROP_RECTANGLE,
    LF_CROP_CIRCLE
};
 
C_TYPEDEF(enum, lfCropMode)
 
 
struct lfLensCalibCrop
{
    float Focal;
    enum lfCropMode CropMode;
    float Crop [4];
};
 
C_TYPEDEF (struct, lfLensCalibCrop)
 
 
struct lfLensCalibFov
{
    float Focal;
    float FieldOfView;
};
 
C_TYPEDEF (struct, lfLensCalibFov)
 
 
struct lfParameter
{
    const char *Name;
    float Min;
    float Max;
    float Default;
};
 
C_TYPEDEF (struct, lfParameter)
 
 
enum lfLensType
{
    LF_UNKNOWN,
    LF_RECTILINEAR,
    LF_FISHEYE,
    LF_PANORAMIC,
    LF_EQUIRECTANGULAR,
    LF_FISHEYE_ORTHOGRAPHIC,
    LF_FISHEYE_STEREOGRAPHIC,
    LF_FISHEYE_EQUISOLID,
    LF_FISHEYE_THOBY
};
 
C_TYPEDEF (enum, lfLensType)
 
 
struct LF_EXPORT lfLens
{
    lfMLstr Maker;
    lfMLstr Model;
    float MinFocal;
    float MaxFocal;
    float MinAperture;
    float MaxAperture;
    char **Mounts;
    float CenterX;
    float CenterY;
    float RedCCI;
    float GreenCCI;
    float BlueCCI;
    float CropFactor;
    lfLensType Type;
    lfLensCalibDistortion **CalibDistortion;
    lfLensCalibTCA **CalibTCA;
    lfLensCalibVignetting **CalibVignetting;
    lfLensCalibCrop **CalibCrop;
    lfLensCalibFov **CalibFov;
    int Score;
 
#ifdef __cplusplus
 
    lfLens ();
 
    lfLens (const lfLens &other);
 
    ~lfLens ();
 
    lfLens &operator = (const lfLens &other);
 
    void SetMaker (const char *val, const char *lang = NULL);
 
    void SetModel (const char *val, const char *lang = NULL);
 
    void AddMount (const char *val);
 
    void AddCalibDistortion (const lfLensCalibDistortion *dc);
 
    bool RemoveCalibDistortion (int idx);
 
    void AddCalibTCA (const lfLensCalibTCA *tcac);
 
    bool RemoveCalibTCA (int idx);
 
    void AddCalibVignetting (const lfLensCalibVignetting *vc);
 
    bool RemoveCalibVignetting (int idx);
 
    void AddCalibCrop (const lfLensCalibCrop *cc);
 
    bool RemoveCalibCrop (int idx);
 
    void AddCalibFov (const lfLensCalibFov *cf);
 
    bool RemoveCalibFov (int idx);
 
    void GuessParameters ();
 
    bool Check ();
 
    static const char *GetDistortionModelDesc (
        lfDistortionModel model, const char **details, const lfParameter ***params);
    static const char *GetTCAModelDesc (
        lfTCAModel model, const char **details, const lfParameter ***params);
 
    static const char *GetVignettingModelDesc (
        lfVignettingModel model, const char **details, const lfParameter ***params);
 
    static const char *GetCropDesc (
        lfCropMode mode, const char **details, const lfParameter ***params);
 
    static const char *GetLensTypeDesc (lfLensType type, const char **details);
 
    bool InterpolateDistortion (float focal, lfLensCalibDistortion &res) const;
 
    bool InterpolateTCA (float focal, lfLensCalibTCA &res) const;
 
    bool InterpolateVignetting (
        float focal, float aperture, float distance, lfLensCalibVignetting &res) const;
 
    bool InterpolateCrop (float focal, lfLensCalibCrop &res) const;
 
    bool InterpolateFov (float focal, lfLensCalibFov &res) const;
#endif
};
 
C_TYPEDEF (struct, lfLens)
 
 
LF_EXPORT lfLens *lf_lens_new ();
 
LF_EXPORT void lf_lens_destroy (lfLens *lens);
 
LF_EXPORT void lf_lens_copy (lfLens *dest, const lfLens *source);
 
LF_EXPORT cbool lf_lens_check (lfLens *lens);
 
LF_EXPORT void lf_lens_guess_parameters (lfLens *lens);
 
LF_EXPORT const char *lf_get_distortion_model_desc (
    enum lfDistortionModel model, const char **details, const lfParameter ***params);
 
LF_EXPORT const char *lf_get_tca_model_desc (
    enum lfTCAModel model, const char **details, const lfParameter ***params);
 
LF_EXPORT const char *lf_get_vignetting_model_desc (
    enum lfVignettingModel model, const char **details, const lfParameter ***params);
 
LF_EXPORT const char *lf_get_crop_desc (
    enum lfCropMode mode, const char **details, const lfParameter ***params);
 
LF_EXPORT const char *lf_get_lens_type_desc (
    enum lfLensType type, const char **details);
 
LF_EXPORT cbool lf_lens_interpolate_distortion (const lfLens *lens, float focal,
    lfLensCalibDistortion *res);
 
LF_EXPORT cbool lf_lens_interpolate_tca (const lfLens *lens, float focal, lfLensCalibTCA *res);
 
LF_EXPORT cbool lf_lens_interpolate_vignetting (const lfLens *lens, float focal, float aperture,
    float distance, lfLensCalibVignetting *res);
 
LF_EXPORT cbool lf_lens_interpolate_crop (const lfLens *lens, float focal,
    lfLensCalibCrop *res);
 
LF_EXPORT cbool lf_lens_interpolate_fov (const lfLens *lens, float focal,
    lfLensCalibFov *res);
 
LF_EXPORT void lf_lens_add_calib_distortion (lfLens *lens, const lfLensCalibDistortion *dc);
 
LF_EXPORT cbool lf_lens_remove_calib_distortion (lfLens *lens, int idx);
 
LF_EXPORT void lf_lens_add_calib_tca (lfLens *lens, const lfLensCalibTCA *tcac);
 
LF_EXPORT cbool lf_lens_remove_calib_tca (lfLens *lens, int idx);
 
LF_EXPORT void lf_lens_add_calib_vignetting (lfLens *lens, const lfLensCalibVignetting *vc);
 
LF_EXPORT cbool lf_lens_remove_calib_vignetting (lfLens *lens, int idx);
 
LF_EXPORT void lf_lens_add_calib_crop (lfLens *lens, const lfLensCalibCrop *cc);
 
LF_EXPORT cbool lf_lens_remove_calib_crop (lfLens *lens, int idx);
 
LF_EXPORT void lf_lens_add_calib_fov (lfLens *lens, const lfLensCalibFov *cf);
 
LF_EXPORT cbool lf_lens_remove_calib_fov (lfLens *lens, int idx);
 
/*----------------------------------------------------------------------------*/
 
enum
{
    LF_SEARCH_LOOSE = 1
};
 
struct LF_EXPORT lfDatabase
{
    char *HomeDataDir;
 
#ifdef __cplusplus
 
    static lfDatabase *Create ();
 
    void Destroy ();
 
    lfError Load ();
 
    lfError Load (const char *filename);
 
    lfError Load (const char *errcontext, const char *data, size_t data_size);
 
    lfError Save (const char *filename) const;
 
    lfError Save (const char *filename,
                  const lfMount *const *mounts,
                  const lfCamera *const *cameras,
                  const lfLens *const *lenses) const;
 
    static char *Save (const lfMount *const *mounts,
                       const lfCamera *const *cameras,
                       const lfLens *const *lenses);
 
    const lfCamera **FindCameras (const char *maker, const char *model) const;
 
    const lfCamera **FindCamerasExt (const char *maker, const char *model,
                                     int sflags = 0) const;
 
    const lfCamera *const *GetCameras () const;
 
    const lfLens **FindLenses (const lfCamera *camera, const char *maker,
                               const char *model, int sflags = 0) const;
 
    const lfLens **FindLenses (const lfLens *lens, int sflags = 0) const;
 
    const lfLens *const *GetLenses () const;
 
    const lfMount *FindMount (const char *mount) const;
 
    const char *MountName (const char *mount) const;
 
    const lfMount *const *GetMounts () const;
 
protected:
    /* Prevent user from creating and destroying such objects */
    lfDatabase () {}
    ~lfDatabase () {}
#endif
};
 
C_TYPEDEF (struct, lfDatabase)
 
 
LF_EXPORT lfDatabase *lf_db_new (void);
 
LF_EXPORT void lf_db_destroy (lfDatabase *db);
 
LF_EXPORT lfError lf_db_load (lfDatabase *db);
 
LF_EXPORT lfError lf_db_load_file (lfDatabase *db, const char *filename);
 
LF_EXPORT lfError lf_db_load_data (lfDatabase *db, const char *errcontext,
                                   const char *data, size_t data_size);
 
LF_EXPORT lfError lf_db_save_all (const lfDatabase *db, const char *filename);
 
LF_EXPORT lfError lf_db_save_file (const lfDatabase *db, const char *filename,
                                   const lfMount *const *mounts,
                                   const lfCamera *const *cameras,
                                   const lfLens *const *lenses);
 
LF_EXPORT char *lf_db_save (const lfMount *const *mounts,
                            const lfCamera *const *cameras,
                            const lfLens *const *lenses);
 
LF_EXPORT const lfCamera **lf_db_find_cameras (
    const lfDatabase *db, const char *maker, const char *model);
 
LF_EXPORT const lfCamera **lf_db_find_cameras_ext (
    const lfDatabase *db, const char *maker, const char *model, int sflags);
 
LF_EXPORT const lfCamera *const *lf_db_get_cameras (const lfDatabase *db);
 
LF_EXPORT const lfLens **lf_db_find_lenses_hd (
    const lfDatabase *db, const lfCamera *camera, const char *maker,
    const char *lens, int sflags);
 
LF_EXPORT const lfLens **lf_db_find_lenses (
    const lfDatabase *db, const lfLens *lens, int sflags);
 
LF_EXPORT const lfLens *const *lf_db_get_lenses (const lfDatabase *db);
 
LF_EXPORT const lfMount *lf_db_find_mount (const lfDatabase *db, const char *mount);
 
LF_EXPORT const char *lf_db_mount_name (const lfDatabase *db, const char *mount);
 
LF_EXPORT const lfMount *const *lf_db_get_mounts (const lfDatabase *db);
 
/*----------------------------------------------------------------------------*/
 
enum
{
    LF_MODIFY_TCA        = 0x00000001,
    LF_MODIFY_VIGNETTING = 0x00000002,
    LF_MODIFY_CCI        = 0x00000004,
    LF_MODIFY_DISTORTION = 0x00000008,
    LF_MODIFY_GEOMETRY   = 0x00000010,
    LF_MODIFY_SCALE      = 0x00000020,
    LF_MODIFY_ALL        = ~0
};
 
enum lfPixelFormat
{
    LF_PF_U8,
    LF_PF_U16,
    LF_PF_U32,
    LF_PF_F32,
    LF_PF_F64
};
 
C_TYPEDEF (enum, lfPixelFormat)
 
 
enum lfComponentRole
{
    LF_CR_END = 0,
    LF_CR_NEXT,
    LF_CR_UNKNOWN,
    LF_CR_INTENSITY,
    LF_CR_RED,
    LF_CR_GREEN,
    LF_CR_BLUE
};
 
C_TYPEDEF (enum, lfComponentRole)
 
 
#define LF_CR_1(a)              (LF_CR_ ## a)
 
#define LF_CR_2(a,b)            ((LF_CR_ ## a) | ((LF_CR_ ## b) << 4))
 
#define LF_CR_3(a,b,c)          ((LF_CR_ ## a) | ((LF_CR_ ## b) << 4) | \
                                 ((LF_CR_ ## c) << 8))
 
#define LF_CR_4(a,b,c,d)        ((LF_CR_ ## a) | ((LF_CR_ ## b) << 4) | \
                                 ((LF_CR_ ## c) << 8) | ((LF_CR_ ## d) << 12))
 
#define LF_CR_5(a,b,c,d,e)      ((LF_CR_ ## a) | ((LF_CR_ ## b) << 4) | \
                                 ((LF_CR_ ## c) << 8) | ((LF_CR_ ## d) << 12) | \
                                 ((LF_CR_ ## e) << 16))
 
#define LF_CR_6(a,b,c,d,e,f)    ((LF_CR_ ## a) | ((LF_CR_ ## b) << 4) | \
                                 ((LF_CR_ ## c) << 8) | ((LF_CR_ ## d) << 12) | \
                                 ((LF_CR_ ## e) << 16) | ((LF_CR_ ## f) << 20))
 
#define LF_CR_7(a,b,c,d,e,f,g)   ((LF_CR_ ## a) | ((LF_CR_ ## b) << 4) | \
                                 ((LF_CR_ ## c) << 8) | ((LF_CR_ ## d) << 12) | \
                                 ((LF_CR_ ## e) << 16) | ((LF_CR_ ## f) << 20) | \
                                 ((LF_CR_ ## g) << 24))
 
#define LF_CR_8(a,b,c,d,e,f,g,h) ((LF_CR_ ## a) | ((LF_CR_ ## b) << 4) | \
                                 ((LF_CR_ ## c) << 8) | ((LF_CR_ ## d) << 12) | \
                                 ((LF_CR_ ## e) << 16) | ((LF_CR_ ## f) << 20) | \
                                 ((LF_CR_ ## g) << 24) | ((LF_CR_ ## h) << 28))
 
typedef void (*lfSubpixelCoordFunc) (void *data, float *iocoord, int count);
 
typedef void (*lfModifyColorFunc) (void *data, float x, float y,
                                   void *pixels, int comp_role, int count);
 
typedef void (*lfModifyCoordFunc) (void *data, float *iocoord, int count);
 
struct LF_EXPORT lfModifier
{
#ifdef __cplusplus
 
    static lfModifier *Create (const lfLens *lens, float crop, int width, int height);
 
    int Initialize (
        const lfLens *lens, lfPixelFormat format, float focal, float aperture,
        float distance, float scale, lfLensType targeom, int flags, bool reverse);
 
    void Destroy ();
 
    void AddCoordCallback (lfModifyCoordFunc callback, int priority,
                           void *data, size_t data_size);
 
    void AddSubpixelCallback (lfSubpixelCoordFunc callback, int priority,
                              void *data, size_t data_size);
 
    void AddColorCallback (lfModifyColorFunc callback, int priority,
                           void *data, size_t data_size);
 
    bool AddSubpixelCallbackTCA (lfLensCalibTCA &model, bool reverse = false);
 
    bool AddColorCallbackVignetting (lfLensCalibVignetting &model, lfPixelFormat format,
                                     bool reverse = false);
 
    bool AddColorCallbackCCI (const lfLens *lens, lfPixelFormat format,
                              bool reverse = false);
 
    bool AddCoordCallbackDistortion (lfLensCalibDistortion &model, bool reverse = false);
 
    bool AddCoordCallbackGeometry (lfLensType from, lfLensType to, float focal);
 
    bool AddCoordCallbackScale (float scale, bool reverse = false);
 
    float GetAutoScale (bool reverse);
 
    bool ApplySubpixelDistortion (float xu, float yu, int width, int height,
                                  float *res) const;
 
    bool ApplyColorModification (void *pixels, float x, float y, int width, int height,
                                 int comp_role, int row_stride) const;
 
    bool ApplyGeometryDistortion (float xu, float yu, int width, int height,
                                  float *res) const;
 
    bool ApplySubpixelGeometryDistortion (float xu, float yu, int width, int height,
                                          float *res) const;
 
protected:
    /* Prevent user from creating and destroying such objects */
    lfModifier () {}
    ~lfModifier () {}
#elif defined _MSC_VER
    /* Sucks, like always */
    void *dummy;
#endif
};
 
C_TYPEDEF (struct, lfModifier)
 
 
LF_EXPORT lfModifier *lf_modifier_new (
    const lfLens *lens, float crop, int width, int height);
 
LF_EXPORT void lf_modifier_destroy (lfModifier *modifier);
 
LF_EXPORT int lf_modifier_initialize (
    lfModifier *modifier, const lfLens *lens, lfPixelFormat format,
    float focal, float aperture, float distance, float scale,
    lfLensType targeom, int flags, cbool reverse);
 
LF_EXPORT void lf_modifier_add_coord_callback (
    lfModifier *modifier, lfModifyCoordFunc callback, int priority,
    void *data, size_t data_size);
 
LF_EXPORT void lf_modifier_add_subpixel_callback (
    lfModifier *modifier, lfSubpixelCoordFunc callback, int priority,
    void *data, size_t data_size);
 
LF_EXPORT void lf_modifier_add_color_callback (
    lfModifier *modifier, lfModifyColorFunc callback, int priority,
    void *data, size_t data_size);
 
LF_EXPORT cbool lf_modifier_add_subpixel_callback_TCA (
    lfModifier *modifier, lfLensCalibTCA *model, cbool reverse);
 
LF_EXPORT cbool lf_modifier_add_color_callback_vignetting (
    lfModifier *modifier, lfLensCalibVignetting *model,
    lfPixelFormat format, cbool reverse);
 
LF_EXPORT cbool lf_modifier_add_color_callback_CCI (
    lfModifier *modifier, const lfLens *lens,
    lfPixelFormat format, cbool reverse);
 
LF_EXPORT cbool lf_modifier_add_coord_callback_distortion (
    lfModifier *modifier, lfLensCalibDistortion *model, cbool reverse);
 
LF_EXPORT cbool lf_modifier_add_coord_callback_geometry (
    lfModifier *modifier, lfLensType from, lfLensType to, float focal);
 
LF_EXPORT cbool lf_modifier_add_coord_callback_scale (
    lfModifier *modifier, float scale, cbool reverse);
 
LF_EXPORT float lf_modifier_get_auto_scale (
    lfModifier *modifier, cbool reverse);
 
LF_EXPORT cbool lf_modifier_apply_subpixel_distortion (
    lfModifier *modifier, float xu, float yu, int width, int height, float *res);
 
LF_EXPORT cbool lf_modifier_apply_color_modification (
    lfModifier *modifier, void *pixels, float x, float y, int width, int height,
    int comp_role, int row_stride);
 
LF_EXPORT cbool lf_modifier_apply_geometry_distortion (
    lfModifier *modifier, float xu, float yu, int width, int height, float *res);
 
LF_EXPORT cbool lf_modifier_apply_subpixel_geometry_distortion (
    lfModifier *modifier, float xu, float yu, int width, int height, float *res);
 
#undef cbool
 
#ifdef __cplusplus
}
#endif
 
#endif /* __LENSFUN_H__ */