lensserious.h

Go to the documentation of this file.

/*
    LensSerious — lens-correction mathematics as data, not as a library of callbacks.
 
    Copyright (C) 2026 Aurélien PIERRE.
    Model evaluators, coordinate conventions and interpolation semantics ported from
    Lensfun 0.3.4 (libs/lensfun/{modifier,mod-coord,mod-subpix,mod-color,lens,auxfun}.cpp),
    Copyright (C) 2007 Andrew Zabolotny and the Lensfun contributors.
 
    This library is free software: you can redistribute it and/or modify it under the
    terms of the GNU Lesser General Public License as published by the Free Software
    Foundation, either version 3 of the License, or (at your option) any later version.
 
    It 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 Lesser General Public License for more details.
*/
 
#ifndef LENSSERIOUS_H
#define LENSSERIOUS_H
 
#include <stddef.h>
 
/* The closed forms themselves, shared verbatim with opencl/lensserious.cl. */
#include "lensserious_eval.h"
 
#ifdef __cplusplus
extern "C" {
#endif
 
typedef enum ls_dist_model_t
{
  LS_DIST_NONE = 0,
  LS_DIST_POLY3,   
  LS_DIST_POLY5,   
  LS_DIST_PTLENS,  
  LS_DIST_KNOTS,   
} ls_dist_model_t;
 
typedef enum ls_tca_model_t
{
  LS_TCA_NONE = 0,
  LS_TCA_LINEAR,   
  LS_TCA_POLY3,    
} ls_tca_model_t;
 
typedef enum ls_vig_model_t
{
  LS_VIG_NONE = 0,
  LS_VIG_PA,       
  LS_VIG_KNOTS,    
} ls_vig_model_t;
 
typedef struct ls_calib_dist_t { ls_dist_model_t model; float focal; float terms[3]; } ls_calib_dist_t;
typedef struct ls_calib_tca_t  { ls_tca_model_t  model; float focal; float terms[6]; } ls_calib_tca_t;
typedef struct ls_calib_vig_t  { ls_vig_model_t  model; float focal, aperture, distance; float terms[3]; } ls_calib_vig_t;
typedef struct ls_calib_real_focal_t { float focal; float real_focal; } ls_calib_real_focal_t;
 
enum { LS_MAX_CALIB = 512 }; /* the densest lens in the 2026 database has ~300 vignetting points */
 
typedef enum ls_lens_type_t
{
  LS_LENS_UNKNOWN = 0,
  LS_LENS_RECTILINEAR,
  LS_LENS_FISHEYE,
  LS_LENS_PANORAMIC,
  LS_LENS_EQUIRECTANGULAR,
  LS_LENS_FISHEYE_ORTHOGRAPHIC,
  LS_LENS_FISHEYE_STEREOGRAPHIC,
  LS_LENS_FISHEYE_EQUISOLID,
  LS_LENS_FISHEYE_THOBY,
} ls_lens_type_t;
 
typedef struct ls_lens_t
{
  ls_lens_type_t type;
  float crop_factor;   
  float aspect_ratio;  
  float min_focal, max_focal; 
  float center_x, center_y; 
  int n_dist; ls_calib_dist_t dist[LS_MAX_CALIB];
  int n_tca;  ls_calib_tca_t  tca[LS_MAX_CALIB];
  int n_vig;  ls_calib_vig_t  vig[LS_MAX_CALIB];
  int n_real_focal; ls_calib_real_focal_t real_focal[LS_MAX_CALIB];
} ls_lens_t;
 
#define LS_ENABLE_DISTORTION (1 << 0)
#define LS_ENABLE_TCA        (1 << 1)
#define LS_ENABLE_VIGNETTING (1 << 2)
#define LS_ENABLE_SCALE      (1 << 3)
#define LS_ENABLE_GEOMETRY   (1 << 4)
 
typedef struct ls_knots_t
{
  int   n;
  float radius[LS_MAX_KNOTS];
  float cor_rgb[3][LS_MAX_KNOTS];
 
  int   vn;
  float vig_radius[LS_MAX_KNOTS];
  float vig[LS_MAX_KNOTS];
} ls_knots_t;
 
typedef struct ls_modifier_t
{
  /* Coordinate system — ported from lfModifier::lfModifier() (modifier.cpp).
   * norm_scale converts centred pixel coordinates to the calibration sensor's
   * normalized system; centre includes the lens's optical-centre shift. */
  float norm_scale, norm_unscale;
  float aspect_ratio_correction; /* vignetting works in the half-diagonal system */
  float center_x, center_y;   /* in normalized coordinates */
  float width, height;        /* the (dimension − 1) values, lensfun's own convention */
 
  int   enabled;              /* LS_ENABLE_* actually resolved (calibration present) */
  int   reverse;              /* non-zero for the reverse direction (lensfun's `reverse`) */
  /* Set when the requested projection change cannot be expressed radially -- panoramic or
   * equirectangular on either side. Those two map x and y differently; everything else
   * (rectilinear, the four fisheyes, thoby) goes through ls_eval_geometry(). */
  int   geometry_unsupported;
 
  float scale;                /* linear scaling factor, applied first (priority 100) */
  int   geom_from, geom_to;   /* projection change, ls_lens_type_t (priority 500) */
  float geom_focal;           /* focal / 12mm, the normalized-radius reference */
  ls_calib_dist_t dist;       /* resolved (interpolated) at the shooting focal */
  ls_calib_tca_t  tca;
  ls_calib_vig_t  vig;
 
  /* The alternative to the three above: a maker's own measured table, already turned to
   * face the requested direction. Filled by ls_modifier_init_knots(), left zeroed by
   * ls_modifier_init(), and never both.
   *
   * Shaped the way ls_eval_t holds it rather than the way ls_knots_t states it, because
   * turning it round is what this struct is for and doing it twice is how the two would
   * drift. The radii are per channel HERE and shared THERE: inverting sends each channel to
   * its own set of radii, so only the direction that needs them can carry them. */
  int   knot_axes;
  int   knot_n, knot_vn;
  float knot_r[3][LS_MAX_KNOTS];
  float knot_c[3][LS_MAX_KNOTS];
  float knot_vr[LS_MAX_KNOTS];
  float knot_v[LS_MAX_KNOTS];
} ls_modifier_t;
 
int ls_modifier_init(ls_modifier_t *mod, const ls_lens_t *lens,
                     float crop, int width, int height,
                     float focal, float aperture, float distance,
                     float scale, int target_type, int flags, int reverse);
 
int ls_modifier_init_knots(ls_modifier_t *mod, const ls_knots_t *knots,
                           int width, int height, float scale, int flags, int reverse);
 
float ls_modifier_autoscale(const ls_modifier_t *mod);
 
int ls_modifier_set_projection(ls_modifier_t *mod, int from_type, int to_type,
                               float focal_mm, float crop_factor);
 
int ls_eval_from_modifier(const ls_modifier_t *mod, ls_eval_t *out);
 
int ls_eval_adopt_vignetting(ls_eval_t *dst, const ls_eval_t *src);
 
int ls_modifier_apply_subpixel_geometry(const ls_modifier_t *mod,
                                        float xu, float yu, int width, int height,
                                        float *res);
 
int ls_modifier_apply_vignetting(const ls_modifier_t *mod,
                                 float xu, float yu, int width, int height,
                                 float *rgba, int row_stride_bytes);
 
#ifdef __cplusplus
}
#endif
 
#endif /* LENSSERIOUS_H */