lensfun.h

Go to the documentation of this file.

/* -*- mode:c++ -*- */
/*
    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        3
#define LF_VERSION_MICRO        1
#define LF_VERSION_BUGFIX       0
#define LF_VERSION      ((LF_VERSION_MAJOR << 24) | (LF_VERSION_MINOR << 16) | (LF_VERSION_MICRO << 8) | LF_VERSION_BUGFIX)

#define LF_MAX_DATABASE_VERSION 1

#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 || __clang__
#           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

#ifndef CONF_LENSFUN_INTERNAL
#    ifdef __GNUC__
#        define DEPRECATED __attribute__((deprecated))
#    elif defined(_MSC_VER)
#        define DEPRECATED __declspec(deprecated)
#    else
#        pragma message("WARNING: You need to implement DEPRECATED for this compiler")
#        define DEPRECATED
#    endif
#else
#    define DEPRECATED
#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_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 lfLensCalibRealFocal
{
    float Focal;
    float RealFocal;
};

C_TYPEDEF (struct, lfLensCalibRealFocal)


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 CropFactor;
    float AspectRatio;
    lfLensType Type;
    lfLensCalibDistortion **CalibDistortion;
    lfLensCalibTCA **CalibTCA;
    lfLensCalibVignetting **CalibVignetting;
    lfLensCalibCrop **CalibCrop;
    lfLensCalibFov **CalibFov;
    lfLensCalibRealFocal **CalibRealFocal;
    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);

    DEPRECATED void AddCalibFov (const lfLensCalibFov *cf);

    DEPRECATED bool RemoveCalibFov (int idx);

    void AddCalibRealFocal (const lfLensCalibRealFocal *cf);

    bool RemoveCalibRealFocal (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;

    DEPRECATED bool InterpolateFov (float focal, lfLensCalibFov &res) const;

    bool InterpolateRealFocal (float focal, lfLensCalibRealFocal &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);

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

LF_EXPORT cbool lf_lens_interpolate_real_focal (const lfLens *lens, float focal,
    lfLensCalibRealFocal *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);

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

DEPRECATED LF_EXPORT cbool lf_lens_remove_calib_fov (lfLens *lens, int idx);

LF_EXPORT void lf_lens_add_calib_real_focal (lfLens *lens, const lfLensCalibRealFocal *cf);

LF_EXPORT cbool lf_lens_remove_calib_real_focal (lfLens *lens, int idx);

/*----------------------------------------------------------------------------*/

enum
{
    LF_SEARCH_LOOSE = 1,
    LF_SEARCH_SORT_AND_UNIQUIFY = 2
};

struct LF_EXPORT lfDatabase
{
    char *HomeDataDir;
    char *UserUpdatesDir;

#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,
    /* Value 0x00000004 is deprecated. */
    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 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 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 ApplySubpixelDistortion (float xu, float yu, int width, int height,
                                  float *res) const;

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

private:
    float GetRealFocalLength (const lfLens *lens, float focal);

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_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__ */