/** @mainpage Lensfun: A library for rectifying and simulating photographic lens distortions @section intro Introduction The goal of the Lensfun library is to provide a open source database of photographic lenses and their characteristics. In the past there was a effort in this direction (see http://www.epaperpress.com/ptlens/), but then author decided to take the commercial route and the database froze at the last public stage. This database was used as the basement on which Lensfun database grew, thanks to PTLens author which gave his permission for this, while the code was totally rewritten from scratch (and the database was converted to a totally new, XML-based format). The Lensfun library not only provides a way to read the database and search for specific things in it, but also provides a set of algorithms for correcting images based on detailed knowledge of lens properties and calibration data. Right now Lensfun is designed to correct distortion, transversal (also known as lateral) chromatic aberrations, and vignetting. Furthermore, it can convert between different types of lenses, for example from fisheye into rectilinear. @section contents Contents @page license Software license The libraries which are part of this package are licensed under the terms of the GNU Lesser General Public License, version 3. Libraries are located under the subdirectory libs/ of the source package. A copy of the license is available in the file lgpl-3.0.txt which can be found in the source archive. You can read it here: @ref lgpl or on the GNU site. Applications which are part of this package are licensed under the terms of the GNU General Public License, version 3. Applications are located under the apps/ subdirectory of the source package. A copy of the license can be found in the file gpl-3.0.txt which can be found in the source archive. You can read it here: @ref gpl or on the GNU site. Test programs and tools are put into public domain, unless explicitly specified otherwise in the header of the source files. Test programs are located under the tests/ subdirectory, and tools are located in tools/. The lens database is licensed under the Creative Commons Attribution-Share Alike 3.0 license. The database is located under the data/ subdirectory of the source package. You can read it here: @ref cc-by-ca or on the Creative Commons Web site. @page credits Credits This project was contrived by Andrew Zabolotny, who developed all features present in Lensfun. Later, when Andrew had no time anymore for regular releases, Sebastian Kraft took over maintenance. The following people contributed code: The following people directly or indirectly contributed to the birth and growth of this library: Also I would like to thank all the people sending profiles for the database. @page lensfun-update-data Updating Lensfun's database: lensfun‑update-data New lenses and cameras arrive at Lensfun every week. So, it is desirable to update your copy of Lensfun's database to stay up-to-date. In particular, if you have sent calibration pictures to Torsten's calibration service, you must update your local Lensfun database after the calibration in order to be able to use the new calibrations. For this purpose, there exists a simple command-line tool called “update‑lensfun‑data”. If you call it (it doesn't need parameters), just wait for a second and the database is updated. It will report whether an update was necessary. If you want the updates to be installed system-wide, the program needs root privileges. So call the program with “sudo lensfun‑update‑data” and enter your root password. There exists a second version of the programm called “g‑lensfun‑update‑data”. It will let you enter the root password – if new data is available – in a neat window. This version is especially useful for GUI programs, which can call it in the background. If it is sufficient that the updates are available to only your user account, call “lensfun‑update‑data” without root priviledges. The updates are then written to ~/.local/share/lensfun/updates”. In case there is more than one version of Lensfun on your system (e.g. you installed a new version, but the original version of your Linux distribution is still there and used by some programs), “lensfun‑update‑data” tries to detect this and updates the other database versions, too. @page lensfun-add-adapter Adding mount adapters: lensfun‑add‑adapter Lensfun contains information about lens mounts of cameras and available mounts for lens models. This way, the calling application can offer the user a list with lenses that fit on their camera in order to pick one. Otherwise, you would see *all* lenses every time. This can be pretty overwhelming. But if you bought an adapter for another mount system, you would want to see lenses of that mount system listed for your camera. So, you must tell Lensfun somehow that you own the adapter. You can do so by calling lensfun‑add‑adapter. The easiest way to use it is to call it with no parameters. lensfun‑add‑adapter will then enter an interactive mode. First you have to enter your camera model. lensfun‑add‑adapter will use that to determine the destination mount. In particular, the extended lens lists will show up for every camera with that mount, not just the one you entered. Then, you have to select the mount of the lenses you can now put on your camera, using the adapter. That's it. You can also use lensfun‑add‑adapter to reset your adapter configuration. Call it with the ‑‑help paremeter to see all functions. @page database Lens database Lensfun uses an XML-based format for its database. A single XML file can contain entries for mounts, cameras and lenses. The whole file content is enclosed in a @ element. The database is made of multiple XML files, conventionally split by manufacturer and camera type. Compact, SLR, and mirrorless cameras/lenses are split apart for easier maintainance. The database contains three kinds of objects: @b mounts, @b cameras and @b lenses. Every @b camera has a mount type assigned (and only one). Similarily, @b lenses also have a list of mounts assigned, because lenses often come in several variants with different mounts. Finally, every @b mount has assigned a list of compatible mounts, so if your camera has mount B which is compatible with mount A, you can list all the lenses that come either with mounts A or B. However, there are various custom adapters that can be used to connect lenses to bodies with “incompatible” mounts, so the application in any case may provide a mean to choose from the whole list in addition to filtering lenses by mount. The cameras may be autodetected by using EXIF information from the source image. However, the Lensfun library is not tied in any way to EXIF tags, it is in the application's responsibility to read those tags in any way they like. In fact, you may detect the camera which was used to take the image in some other way (for example, if you want to use Lensfun for processing images taken from videocams, which usually do not use EXIF, or scanned images from film cameras), you may even ask the user directly to choose the camera from a list. Same about lenses: you may either autodetect them (which is tricky even if you have EXIF information, since unlike camera/model the lens model is highly manufacturer-dependent and is usually hidden in the Exif.MakerNote tag which is a big binary blob; luckily the exiv2 library can parse many vendor-specific MakerNote's), or you may provide some mean for the user to enter the lens model manually. The Lensfun library will help you a little here, since it provides a means to match a set of lenses from the database given a human-entered lens description (e.g. fuzzy lens search). @page dbformat Database file format Here goes a simple lens database file, I hope I don't have to explain much what is what, as the format is pretty much self-documenting. @verbatim Pentax K M42 Pentax SMC Pentax M 50mm f/1.4 Pentax K 1.0 rectilinear Pentax Pentax K10D Pentax KAF2 1.531 @endverbatim The “version” attribute at the @ element denotes the format version of this database file. It is an integer number and defaults to “0”. Because it was introduced in Lensfun 0.3, “0” is the format version of all Lensfun releases before that. Database format changes mostly are backwards-compatible, so that a certain Lensfun version supports database versions up to a certain number. The most recent lens database is offered for download in all versions, and the @ref lensfun-update-data "lensfun-update-data" program fetches the appropriate for you. See @ref db_versions for the version history. Since lenses and cameras may be known with different names in different languages/countries, the library provides a built-in mechanism for name translations. You can provide such multi-language strings for every language you want, and when the library client will ask for string value, it will get the one in the current locale. This mechanism is also useful sometimes when you want to use a name for camera which is different from the value put in EXIF data. For example: @verbatim Konica Minolta Camera, Inc. Konica Minolta Коника Минольта @endverbatim The value without a “lang” attribute is always used for identification, but GUI may use the translated string for display. If no language matches, and an "en" translation is present, it is used. And only if there's no native translation and there's no "en" translation, the no-language version is used. Here is a complete list of elements recognized by the library and the format of the data within elements. @page db_versions Database format versions
database
version		Lensfun
release		changesincompatibilities with
previous versions
0≤ 0.2.8——
10.3
  • new: @ tag
  • new: @ tag
  • removed: @ tag
  • APS-C crop factors are given with a higher accuracy
—
@page el_mount Describing camera mounts: \ Add \ element only for mounts for interchangeable lenses. If the lens is fixed (mostly a compact camera), a \ element for it may be declared locally by the user (see \ref lensfun-add-adapter), but it should not be in the core database. Possible embedded elements:
\string\
This gives the name of the mount. Mount names for fixed-lens cameras – and only they – must start with a lower case letter.
\string\
Declares that this mount is compatible with another one. Usually this means that either they are directly compatible (e.g. the Pentax KAF2 mount is compatible with Pentax K so you can insert K lenses into a KAF2 camera) or there exists mount adapters which permit to install lenses with such mounts into this mount. Note that the compatibility is unidirectional, e.g. in the above example it doesn't say that you can insert Pentax KAF2 lenses into a Pentax K camera; if you need a two-way compatibility, declare it both ways. Also the “compatibility” is restricted in the sense that if mount A is compatible with mount B (e.g. you can put B lenses on an A camera), and mount B is compatible with mount C, this does not neccessarily mean that mount A is compatible with mount C. Recursion doesn't work here, this is a design decision. If you need to make mount A compatible with mount C, declare it so explicitely. Things are slightly complicated with mirrorless systems because they are adaptable to virtually any non-mirrorless system. In order to avoid too many useless entries in the lens selection lists for mirrorless mounts, only important (e.g. because only few native lenses yet exist) compatibilities should be included into Lensfun's official database (e.g. Canon EF on Canon M). The user can override this easily in their local database files, adding compatibilities for all mounts they have adaptors for, see @ref lensfun-add-adapter.
@page el_camera Declaring cameras: \ Possible embedded elements:
\string\
Camera maker. This must be specified \b exactly as it is specified in camera EXIF data to allow for automatic recognition of the camera. Upper and lower case doesn't matter, though.
\string\
Camera model. This must be specified \b exactly as it is specified in camera EXIF data to allow for automatic recognition of the camera. Upper and lower case doesn't matter, though.
\string\
Camera variant. Sometimes makers create several cameras without changing EXIF information. Unfortunately, camera variant cannot be automatically detected so this is a manual choice item. This field can also be used to deal with cameras with more than one aspect ratio. For every available aspect ratio, make a copy of the \ entry, entering the aspect ratio into the \ field (e.g. \16:9\). Of course, the crop factor may have to be adapted as well.
\string\
Camera mount. There can be only one such element in camera declaration. If you want to specify that it is possible to use lenses with a different mount on this camera, use the \ element in mount declaration.
\number\
Camera crop factor. This is the ratio between the standard film frame diagonal (36x24mm) and camera sensor diagonal. Be accurate here. For example, no APS-C camera really has crop factor 1.5.
@page el_lens Declaring lenses: \ Possible embedded elements:
\string\
Lens maker.
\string\
Lens model. This must be specified exactly as it is returned by EXIF reading libraries to allow for automatic recognition of the lens. However, upper and lower case doesn't matter, neither does the ordering of the “words” in the lens model name. A “word” in Lensfun interpretation is a sequence of characters of the same type (Lensfun senses three character types: digits, punctuation characters and all others). Words made of single punctuation characters are ignored. Also, as a special exception, the word consisting of a single “f” is ignored too. So, “[IF]” is really split into three words – “[”, “IF”, “]”, and then first and last words are discarded. Accordingly, “smc PENTAX-DA 12-24mm F4 ED AL [IF]” is split into “smc”, “pentax”, “da”, “12”, “24”, “mm”, “4”, “ED”, “AL”, “IF”. Have a look at other lenses of the same manufacturer for the naming conventions. See below for further information about the parsing of the model name field.
\string\
Lens type. This is one of: “rectilinear", “fisheye”, “panoramic”, “equirectangular”, “orthographic”, “stereographic”, “equisolid”, “fisheye_thoby”. If this field is not given, Lensfun assumes rectilinear.
\
Lens focal length in mm. This can be either a single value for a fixed-focal length lens, or a minimum and maximum value in the case of a zoom lens.
\
Lens aperture as the f-number. This can be either a single value for a fixed-aperture lens (very rare), or the minimal and maximal possible f-stop number for this lens (over the whole zoom range for a zoom lens).
\string\
Lens mount. There can be multiple \ entries if the same lens is manufactured with several mounts, or it has a variable mount (e.g. Tamron Adaptall).
\number\
This is the crop factor of the camera with which all shots for computing distortion models were made. The library will compute correction factors if you used this lens on another camera with a different crop factor. Generally it is advised to use a camera with maximal crop factor for this lens, because the models may become imprecise for crop factors smaller than the one used for models.
\number\
This is the aspect ratio of the camera with which all shots for computing distortion models were made. It is the ratio of the longer edge to the shorter edge. Lensfun needs the aspect ratio internally for correct application of the distortion parameters. You may give it is as a real number or as a ratio with a colon like “4:3”. It defaults to 1.5 or 3:2.
\
The decentering of the lens, i.e. the offset of its optical axis from the center of the viewframe. “x” denotes the offset in horizontal direction, “y” in vertical direction. The scale is so that the smaller dimension (for very most cameras the height) has the value 2. Both offsets default to 0. It may be particularly helpful for shift lenses.
\calibration data\
@ref elem_calibration
Library recognizes several ways to specify lens parameters directly in lens model name. The first way to specify lens focal length and aperture range is “[min focal]-[max focal]mm f/[min aperture]-[max aperture]” where the “mm” and “f/” are totally optional. For primes the 'max' values may be omited. Examples:
  • 70-210mm f/4-5.6
  • 18-55 3.5-5.6
  • 50 f2
Another pattern for lens parameters is “[min aperture]-[max aperture]/[min focal]-[max focal]”. Examples:
  • 2.8-3.5/25-45
  • 4.5/300
(Note that “max aperture” refers here to the minimal f-stop number at the maximal focal length of a zoom lens. Its value is ignored by Lensfun. As explained above, Lensfun only stores the minimal and maximal possible f-stop number of the lens, not matter at which focal length, e.g. 3.5–32.) If the focal length in the lens model name is wrong because a converter is used, one of the words “converter” or “extender” must appear somewhere in the lens model name. Moreover, the library finds missing min/max values for focal length and aperture by looking at the range of these parameters in the @ section. @page elem_calibration Lens calibration data format Possible embedded elements:
\
Declares the image distortion model for this lens. Distortion is specific for every focal length (in mm), so you can declare multiple distortion entries with different focal values; the library will interpolate the parameters for intermediate focal lengths. The model name may be "none", "poly3", "poly5", or "ptlens". @see lfDistortionModel
\
Declares the Transversal Chromatic Aberrations model for this lens, depending on focal length. The library will interpolate the parameters for intermediate focal lengths. The model name may be "none", "linear", or "poly3". @see lfTCAModel
\
Declares the vignetting model for this lens at given focal length (in mm), given aperture (as f-number), and given distance to subject in focus (in meters). This kind of calibration requires relatively many sample points since it depends on three variables. The library will interpolate the parameters for between the sample points if necessary. The model name may be "none" or "pa". @see lfVignettingModel
\
Declares the image crop for this lens. Crop can be specific for every focal length (in mm), so you can declare multiple crop entries with different focal values; the library will interpolate the parameters for intermediate focal lengths. The mode name may be "no_crop", "crop_rectangle", or "crop_circle". @see lfCropMode
\
Declares the *real* focal length of the lens in the paraxial approximation, in contrast to the *nominal* focal length used in all "focal" attributes. Especially for fisheye lenses, both values can differ significantly. Lensfun itself needs the real focal length for lens type transformations. It uses the nominal focal length as a fallback. The real focal length can be determined reliably only with a 360° panorama, e.g. with Hugin. However, Hugin's results need to be rectified. The real focal length must correspond to the distortion coefficients. Typically, they are the result of the very same parameter optimisation.
@page dbsearch How database files are found and loaded In a typical application, all XML files are loaded automatically at startup. If the same object is defined in multiple files, later definitions override earlier definitions, e.g. user can override system-wide definitions by placing appropriately formatted XML files in its home directory. A typical application will initialize the lens database by calling the method lfDatabase::Load() with no parameters. This method searches for all available XML files and loads them, ignoring files with errors. The main place where Lensfun looks for database files usually is /usr/share/lensfun/version_x, where x is the database format version (@ref db_versions). However, this is configurable at compilation time, and for locally compiled Lensfun, it is mostly /usr/local/share/lensfun/version_x. A special directory is /var/lib/lensfun-updates/version_x: If it exists and contains a newer database, it is loaded instead of the main place. On Windows, this is something like C:\\Documents and Settings\\\%User\%\\something\\version_x but I'm not sure exactly :-). “Newer database” means that the file timestamp.txt, which is amongst the XML files, contains a larger value. This value is the database timestamp in UNIX time. After having read the global database, the user's home directory is searched. Usually, this is ~/.local/share/lensfun. The exact path can be found in the variable lfDatabase::HomeDataDir. The subdirectory updates/version_x may contain a user-specific DB update. This represents an alternative to /var/lib/lensfun-updates/version_x for which no root priviledges are needed. ~/.local/share/lensfun/version_x is also scanned with higher priority than the one without the version_x, so that the user can set entries specific for a database version. This is useful only if you need to maintain two or more different Lensfun versions on your system. So sum it up for Linux and other Unix-like platforms, the load order is:
  1. the directory Lensfun's database was installed into (usually /usr/share/{local/}lensfun/version_x), @em or /var/lib/lensfun-updates/version_x, @em or ~/.local/share/lensfun/updates/version_x, whatever is newest
  2. ~/.local/share/lensfun
  3. ~/.local/share/lensfun/version_x
Another way to load database file is to load them one by one. For this you call lfDatabase::Load(const char *) for every XML file that must be loaded. @page corrections How the corrections work For both the people working on Lensfun and the people working with Lensfun, it is very important to understand how corrections are applied to the images. @section ordering Order of the image operations The image operations are not commutative. Thus, it is important to apply them in the right order. This is:
  1. devignetting
  2. anti-TCA
  3. undistortion
  4. change of projection
  5. scaling
@subsection imagecorrections Image corrections The first three image operations that are applied are the image corrections. Their order relative to each other is closely connected with the way the lens errors are \a measured. Vignetting is measured on the pristine image, consequently, it must be corrected before any pixel-warping operations are applied. The same is true for TCA measurements. Distortion is also measured on the pristine image, however, undistortion is not affected by a previous devigneting or anti-TCA. This results in the above enumerated order: First devignetting, then anti-TCA, then undistortion. Well, the order of devignetting and anti-TCA is still not clearly defined by this actually. But imagine very very hefty TCA. It distorts the red and the blue channel relatively to the green one. This would affect the vignetting measurement considerably. However, the other way round would be much less invasive: A massive vignetting would not change the TCA measurements much. Therefore, vignetting must be eliminated before TCA is eliminated. Otherwise, devignetting would work on the wrong image. By the way, correcting TCA and distortion one directly after the other makes it possible to do this very efficiently: The pixel coordinates are transformed by both image operators, and after that, only \a one interpolation and \a one pixel value lookup are necessary. @subsection changeofprojection Change of projection Lensfun can also re-map a fisheye to a rectilinear image. Mathematically speaking, a perfect lens follows a well-defined projection (in other places also called “lens type” or “geometry”), like: @f[\begin{aligned} r &= 2f\sin(\theta/2) &\text{equisolid} \\ r &= f\theta &\text{equidistant} \\ r &= 2f\tan(\theta/2) &\text{stereographic} \\ r &= f\sin(\theta) &\text{orthographic} \\ r &= f\tan(\theta) &\text{rectilinear} \end{aligned} @f] Here, @f$\theta@f$ is the angle between the incoming ray of light and the optical axis, @f$f@f$ is the focal length, and @f$r@f$ is the distance of the resulting dot on the sensor from the sensor center. You see, the rectilinear projection is just one of many. And all of them have their advantages and disadvantages. The first four projections are considered fisheye. Lensfun can change the projection of the image. But converting e.g. from fisheye to rectilinear is not a correction. A fisheye image is as perfect as a rectilinear image if it follows the respective projection formula. And the image follows the projection formula after a successful distortion correction. Therefore, the change of projection is perfomed \a after the image corrections. @subsection scaling Scaling Often it is desirable to scale the resulting image, e.g. to eliminate black areas at the borders caused by one of the previous image operations. This scaling affect the resulting image, therefore, it comes last in the processing. @section actualorder How it is really done The actual order perfomed in the Lensfun-calling program will differ from the above list. Why is this? Understanding this is very important for hacking on Lensfun as well as for using it in your own programs. When it comes to pixel coordinate transformations, it is very sensful to start with the perfect, rectified image (still empty) and distort its pixel coordinates to the distorted image. This distorted image is the source image (the RAW file), and you can do a simple pixel lookup there, possibly with interpolation. This way, you find all pixel values for your rectified image efficiently and accurately. However, if you perform pixel lookup this way, things happen the other way round compared to the section before, because you follow the path through the image manipulations the reverse way:
  1. scaling
  2. change of projection
  3. undistortion
  4. anti-TCA
  5. devignetting
This reverse order is the reason why the formulae for distortion models in ::lfDistortionModel map the \a undistorted coordinate to the \a distorted coordinate. This seems to be wrong at first because we want to undistort after all. But given how undistortion is actually done, it makes sense. The same is true for ::lfTCAModel. Note that in the sequence \a scaling → change of projection → \a undistortion → anti-TCA, the resulting coordinates of the previous step are the input coordinates for the respective next step. In reality, devignetting is performed first nevertheless, because it can be separated from all other operations, by calling lfModifier::ApplyColorModification. Then, you do the coordinate-transforming operations from scaling to anti-TCA. Lensfun can do this in one function call with lfModifier::ApplySubpixelGeometryDistortion. Finally, you do a lookup on the vignetting-corrected RAW data, using the transformed coordinates. @page programming Using this library in your programs One of main goals while developing this library was easiness of use. Libraries with complex API are usually slow to be accepted by the community, and often libraries that can do less but have a cleaner API are preferred over more sophisticated libraries that have a user-unfriendly API. The library is accessible both from plain C and C++ programs. Since the library itself is written in C++ (without use of bloated and bloating libraries like libstdc++ or boost), the C interface is a (very) thin wrapper around the C++ classes. The overhead imposed by the wrappers is negligible.
  • @ref basearch
  • @ref samplecode
@page basearch Library architecture The library provides five basic types of objects to work with: @b mounts (lfMount), @b cameras (lfCamera), @b lenses (lfLens), @b databases (lfDatabase) and @b modificators (lfModifier). The lfMount structure provides the information about a mount. For now the only information about a mount is its name and the list of compatible mounts. The lfCamera structure provides information about a particular camera. Camera maker, model name, mount type and other things are included here. The lfLens structure provides information about a lens. This structure contains a lot of information, since it's the heart of the library. Besides other things, this contains a list of lens calibration data. This information tells the library how to correct images distorted by a certain lens. The lfDatabase class provides a interface to the XML database. It allows to load, save XML files and to search the database for lenses, cameras and mounts. Finally, the lfModifier class will allow you to modify images. Not only correct for distortion introduced by lenses but also apply special effects on a image such as emulating certain lens (e.g. apply a reverse transform), modify the geometry of a image (e.g. convert a fisheye image to a rectilinear etc). A typical application will first load the database by creating a lfDatabase object and invoking the respective lfDatabase::Load() method. After that it can look for a Lens object using the bits of information from the user or from the source file. For example, the EXIF data contains the camera maker and camera model. Using this you can search for the respective camera in the database. In camera record you look at the mount field, and then do a lens search based on at least mount name. Additionaly, you may provide the lens manufacturer and/or model name from the EXIF data (which is not always possible). You get a list of possible lenses. If it's just one lens, you can assume that it's exactly the lens that was used to take the shot (this is true for compact cameras which have a fixed mount). Now if you found more than one matching lens you must provide the user a choice. User chooses the exact lens that was used to make a shot. After that you can create a lfModifier object using lens data. Using this object the image may be modified according to user preferences. Lensfun transformations -- at least those involving TCA and vignetting correction -- must be applied to linear RGB data in the sensor's original colour space. Linear RGB can only be retrieved from RAW files, as JPEG files from most cameras already have colour transfromations applied. This is very important. If you do e.g. TCA correction on sRGB data, the colour fringes are still visible. And if you do vignetting correction after a gamma has been applied, the corners probably will look too bright. So make sure that Lensfun comes early enough in your processing chain. @page filldb Filling the database Earlier or later (usually earlier) you'll find out that your camera/lens is not in the database. Well, that's easy to fix, just add it to the database yourself! ;) As stated in the section @ref dbsearch, the library will look for xml database files in various subdirectories. The best place to put your own definitions into is ~/.local/share/lensfun/. This directory is guaranteed to not be overwriten by library or even OS upgrades, so it's safe to keep them there. So now you just create a new file under ~/.local/share/lensfun/ -- with any name, but with the '.xml' extension: @verbatim ... put your definitions here ... @endverbatim and it will be automatically found and loaded at library initialization time, Of course, if you create new camera/lens definitions, I will be grateful if you send them to me so that I can include them in future releases of the database.
  • @ref addcamera
  • @ref addlens
@page addcamera Adding new cameras to the database Adding new cameras is very easy. You just have to know its crop factor, and the EXIF identification strings for this camera; that's all. If you don't know the crop factor, you can search in google for e.g. “Nikon D300 sensor size”. Let's suppose you found out that your sensor size is 23.6 × 15.8mm. Now compute the length of the diagonal using Pythagora's theorem: @f[ d = \sqrt{23.6^2 + 15.8^2}\,\mathrm{mm} = 28.4\,\mathrm{mm} @f] Now you just divide the magic number 43.27 (the diagonal of a usual 35mm film frame) by the number you got: @f[ \mathrm{cropfactor} = \frac{43.27}{28.4} = 1.523 @f] Now you must find out the identification string for your camera from EXIF data. For this you can use the exiv2 script: @verbatim $ exiv2 blah.nef .... Camera make : NIKON CORPORATION Camera model : NIKON D300 .... @endverbatim Now you can create a XML entry for your camera: @verbatim Nikon Corporation Nikon Nikon D300 D300 Nikon F AF 1.523 @endverbatim Now add this definition to a XML database file along Lensfun database search path and your camera will be detected and Lensfun will work properly with images produced by it.
  • @ref el_camera
@page addlens Adding new lenses to the database There are several levels of detalization you can use when adding a new lens into the database. First, you could just add the basic identification information to the database, just to let the database know that such a lens exist. Then, you might try to find out the mathematical model for the distortion of the lens. Finally, you might try to find out the vignetting and transversal chromatic aberration parameters of the lens and get a complete lens description in database. A simple lens database entry would look something like: @verbatim Pentax smc Pentax-DA 12-24mm f/4 ED AL IF Pentax KAF2 @endverbatim The above code just tells Lensfun that there exist a lens called “smc Pentax-DA 12-24mm f/4 ED AL IF” manufactured by Pentax and it uses the Pentax KAF2 mount. This is not very useful except to make user happy that there's at least one other person in the world owning his lens. A better lens database entry would contain at least some data about how to correct lens distortion. This data can be calculated from test shots. Some special program should be used for this, or you could try to manually adjust the coefficients until you get decent results. Computing math model coefficients for distortion, tca, vignetting is a separate very complex matter. It is out of the scope of this manual to give even a short brief about this. There's a tutorial on Lensfun site that will teach you how to create a complete lens entry using just Hugin.
  • @ref el_lens
@page samplecode Sample code Here goes some coding examples, from simple to complex.
  • \ref example.c
This is a example written in pure C and it shows how to load the whole database, then prints it to stdout and finally saves the whole database to a new XML file.
  • \ref tfun.cpp
This is a more complex sample in C++ which shows how to do database lookups. The results found are saved to a new XML file.
  • \ref lenstool.cpp
This is a more or less complex command-line application which can access most library functionality. It has been used as the main library testbed. */ /** \example example.c Sample program demonstrating basic usage of C API. */ /** \example tfun.cpp This example shows how to do basic database lookups. */ /** \example lenstool.cpp Library testbed. This program can access most library functionality. */ /** \page gpl GNU General Public License, version 3 \verbinclude gpl-3.0.txt */ /** \page lgpl GNU Lesser General Public License, version 3 \verbinclude lgpl-3.0.txt */ /** \page cc-by-ca Creative Commons Attribution-Share Alike 3.0 Unported \verbinclude cc-by-sa-3.0.txt */