/**
@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.  And last but not
least, it can correct the perspective, simulating a shift lens.

@section contents Contents

<ul>
<li>@ref license
<li>@ref credits
<li>@ref build
<li>Command line programs
    <ul>
    <li>@ref lensfun-update-data
    <li>@ref lensfun-add-adapter
    <li>@ref lensfun-convert-lcp
    </ul>
<li>@ref database
    <ul>
    <li>@ref dbformat
    <li>@ref dbsearch
    <li>@ref filldb
    </ul>
<li>@ref corrections
<li>@ref perspective-correction
<li>@ref programming
    <ul>
    <li>@ref basearch
    <li>@ref samplecode
    </ul>
</ul>


@page license Software license

The libraries which are part of this package are licensed under the terms of the
<b>GNU Lesser General Public License, version 3</b>. 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 <a href="http://www.gnu.org/licenses/lgpl-3.0.html">on the GNU site</a>.

Applications which are part of this package are licensed under the terms of the
<b>GNU General Public License, version 3</b>. 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 <a href="http://www.gnu.org/licenses/gpl-3.0.html">on the GNU site</a>.

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
<a href="http://creativecommons.org/licenses/by-sa/">on the Creative Commons Web site</a>.


@page credits Credits

This project was contrived by <b>Andrew Zabolotny</b>, who developed all
features present in Lensfun.  Later, when Andrew had no time anymore for
regular releases, <b>Sebastian Kraft</b> took over maintenance.  The following
people contributed code:

<ul>
<li><b>Niels Kristian Bech Jensen</b>
<li><b>Pascal de Bruijn</b>
<li><b>Thomas Modes</b>
<li><b>Torsten Bronger</b>
</ul>

The following people directly or indirectly contributed to the birth and growth
of this library:

<ul>
<li><b>Thomas Niemann</b> for the original open-source PTLens software and database.
<li><b>Pablo d'Angelo</b> for the idea of a open-source lens database.
<li><b>The whole PanoTools team:</b> for all math and knowledge I have borrowed
    from PanoTools.
    <ul>
    <li><b>Helmut Dersch</b> – The father of most (all?) open-source panorama creation tools.
    <li><b>Daniel M. German</b>
    <li><b>Kevin Kratzke</b>
    <li><b>Rik Littlefield</b>
    <li><b>Fulvio Senore</b>
    <li><b>Jim Watters</b>
    <li><b>Thomas Rauscher</b>
    <li><b>Pablo d'Angelo</b> (thanks once more :)
    <li><b>Bret McKee</b>
    <li><b>Robert Platt</b>
    </ul>
</ul>

Also I would like to thank all the people sending profiles for the database. 


@page build Build instructions

The build system is based on CMake (http://www.cmake.org/). In order to
successfully configure and build the project, the following tools are more
or less required:

 - CMake
 - Doxygen in order to generate the library documentation.
 - GLib > 2.26 which is used for low-level I/O and XML parsing.
 - GLib > 2.40 to build the unit tests with the GLib test framework.
 - libpng is required to build and run the example implementation.
 - xmllint to test the database XML validity

First enter the Lensfun root folder and create a build directory.

    cd lensfun
    mkdir build

Enter the build directory and run CMake to configure your sources and create
the build files

    cd build
    cmake ../

Run make/make install as usual

    make
    make install

The following CMake options can be set (defaults are upper case):

    -DCMAKE_BUILD_TYPE=DEBUG|Release        select debug or release build mode
    -DINSTALL_HELPER_SCRIPTS=off|ON         install various helper scripts
    -DCMAKE_INSTALL_PREFIX=/USR/LOCAL       install prefix

    -DBUILD_STATIC=OFF|on       build static or shared lib
    -DBUILD_TESTS=OFF|on        build also the test programs
    -DBUILD_LENSTOOL=OFF|on     build Lensfun reference implementation
    -DBUILD_FOR_SSE=off|ON      build with SSE optimisation
    -DBUILD_FOR_SSE2=off|ON     build with SSE2 optimisaiton
    -DBUILD_DOC=OFF|on          build documentation

If you want to have more detailed output when running 'make' you can simply add
'VERBOSE=1' to the make command line.

You can also build packages with cmake:

    Add -DCPACK_BINARY_DEB:BOOL=ON or -DCPACK_BINARY_RPM:BOOL=ON to the
    command line and then "make package". (But this is not extensively tested.)

Please note that running cmake again does NOT reset all options to default or
reconfigure all variables. To restart with a clean configuration delete all files
in your cmake_build folder.

If you prefer setting the configuration with a GUI or want to get an extensive
overview of all available settings and cache values you can run cmake-gui.

@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 lensfun-convert-lcp Converting Adobe LCP files to Lensfun: lensfun‑convert‑lcp

While Lensfun's lens database is pretty comprehensive, it does not contain all
lenses.  Moreover, only for distortion correction, the coverage is at almost
100%.  Most datasets lack vignetting data, and many lack TCA data.  Therefore,
it may be helpful for you that Lensfun is able to use so-called LCP files.  LCP
files contain lens correction information – just like Lensfun's database does.
Usually, one LCP file contains data of exactly one lens.  The LCP file format
is defined by Adobe (see the <a
href="http://download.macromedia.com/pub/labs/lensprofile_creator/lensprofile_creator_cameramodel.pdf">specification</a>)
and used in their Lightroom and Photoshop products.  Everyone can create LCP
profiles using Adobe's <a
href="http://www.adobe.com/support/downloads/detail.jsp?ftpID=5490">Lens
Profile Creator</a>.  Moreover, a comprehensive library of LCP profiles is
shipped with <a
href="http://www.adobe.com/support/downloads/product.jsp?product=106&platform=Windows">Adobe's
DNG converter</a>, but pay attention to the licence agreement associated with
this software.

The RawTherapee community has created a <a
href="http://rawpedia.rawtherapee.com/How_to_get_LCP_and_DCP_profiles">page
describing in detail how to get LCP profiles</a>.  Additionally, you may google
for further sources of LCP profiles.

Once you have put the LCP files in a directory on your computer, you can easily
import them into Lensfun by calling “lensfun‑convert‑lcp” in this directory.
After that, the data is immediately available in your favourite Lensfun-using
RAW converter.  “lensfun‑convert‑lcp” merges the two data sources, so you get
the best of both worlds.  See the manpage of “lensfun‑convert‑lcp” and its
output with the “‑h” option for further information.

<blockquote>
Note however, that Adobe files tend to undercorrect distortion and vignetting.
In particular, vignetting is corrected only partially.  Moreover, since recent
Adobe products do not correct TCA based on LCP files anymore, TCA coverage is
bad for newer lenses.  And last but not least, automatic lens detection is much
more reliable with genuine Lensfun datasets.  In Lensfun's official database,
no profiles using “acm” models are accepted.  Thus, instead of using LCP
profiles, please consider <a
href="http://wilson.bronger.org/calibration">uploading RAW images suitable for
calibration</a>.  This way, you do not only benefit from increased quality, but
you also help others with the same lens models by providing freely available
data.

Thank you!
</blockquote>


@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 @<lensdatabase@> 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).

<ul>
<li>@ref dbformat
<li>@ref dbsearch
</ul>


@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
<lensdatabase version="1">

    <mount>
        <name>Pentax K</name>
        <compat>M42</compat>
    </mount>

    <lens>
        <maker>Pentax</maker>
        <model>SMC Pentax M 50mm f/1.4</model>
        <mount>Pentax K</mount>
        <cropfactor>1.0</cropfactor>
        <focal value="50" />
        <aperture min="1.4" max="22" />
        <type>rectilinear</type>
        <calibration>
            <!-- WARNING: this calibration data is completely bogus :) -->
            <distortion model="ptlens" focal="50" a="0.012" b="-0.036" c="0" />
        </calibration>
    </lens>

    <camera>
        <maker>Pentax</maker>
        <model>Pentax K10D</model>
        <mount>Pentax KAF2</mount>
        <cropfactor>1.531</cropfactor>
    </camera>

</lensdatabase>
@endverbatim

The “version” attribute at the @<lensdatabase@> 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
<maker>Konica Minolta Camera, Inc.</maker>
<maker lang="en">Konica Minolta</maker>
<maker lang="ru">Коника Минольта</maker>
@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.

<ul>
<li>@ref el_mount
<li>@ref el_camera
<li>@ref el_lens
</ul>


@page db_versions Database format versions

<table>
  <tr><th>database<br/>version</th><th>Lensfun<br/>release</th><th>changes</th><th>incompatibilities with<br/>previous versions</th></tr>
  <tr><td>0</td><td>≤ 0.2.8</td><td>—</td><td>—</td></tr>
  <tr><td>1</td><td>0.3</td><td><ul>
        <li>new: @<aspect-ratio@> tag</li>
        <li>new: @<real-focal-length@> tag</li>
        <li>removed: @<field_of_view@> tag </li>
        <li>APS-C crop factors are given with a higher accuracy</li>
    </ul></td><td>—</td></tr>
  <tr><td>2</td><td>??</td><td>new: "acm" models for distortion, TCA, and vignetting;
  the @<real-focal-length@> tag moved into the real-focal attribute in @<distortion@></td><td>—</td></tr>
</table>


@page el_mount Describing camera mounts: \<mount\>

Add \<mount\> element only for mounts for interchangeable lenses.  If the lens
is fixed (mostly a compact camera), a \<mount\> 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:
<dl>
<dt>\<name\>string\</name\>
<dd>This gives the name of the mount.  Mount names for fixed-lens cameras – and
only they – must start with a lower case letter.
<dt>\<compat\>string\</compat\>
<dd>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.</dl>

@page el_camera Declaring cameras: \<camera\>

Possible embedded elements:
<dl>
<dt>\<maker\>string\</maker\>
<dd>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.
<dt>\<model\>string\</model\>
<dd>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.
<dt>\<variant\>string\</variant\>
<dd>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
    \<camera\> entry, entering the aspect ratio into the \<variant\>
    field (e.g. \<variant\>16:9\</variant\>).  Of course, the crop
    factor may have to be adapted as well.
<dt>\<mount\>string\</mount\>
<dd>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 \<compat\> element in mount declaration.
<dt>\<cropfactor\>number\</cropfactor\>
<dd>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.
</dl>

@page el_lens Declaring lenses: \<lens\>

Possible embedded elements:
<dl>
<dt>\<maker\>string\</maker\>
<dd>Lens maker.
<dt>\<model\>string\</model\>
<dd>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.
<dt>\<type\>string\</type\>
<dd>Lens type. This is one of: “rectilinear", “fisheye”, “panoramic”, 
    “equirectangular”, “orthographic”, “stereographic”, “equisolid”,
    “fisheye_thoby”.  If this field is not given, Lensfun assumes rectilinear.
<dt>\<focal min="number" max="number" value="number" /\>
<dd>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.
<dt>\<aperture min="number" max="number" value="number" /\>
<dd>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).
<dt>\<mount\>string\</mount\>
<dd>Lens mount. There can be multiple \<mount\> entries if the same lens is manufactured
    with several mounts, or it has a variable mount (e.g. Tamron Adaptall).
<dt>\<cropfactor\>number\</cropfactor\>
<dd>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.
<dt>\<aspect-ratio\>number\</aspect-ratio\>
<dd>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.
<dt>\<center x="number" y="number" /\>
<dd>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.
<dt>\<calibration\>calibration data\</calibration\>
<dd>@ref elem_calibration
</dl>

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:

<ul>
<li>70-210mm f/4-5.6
<li>18-55 3.5-5.6
<li>50 f2
</ul>

Another pattern for lens parameters is
“[min aperture]-[max aperture]/[min focal]-[max focal]”. Examples:

<ul>
<li>2.8-3.5/25-45
<li>4.5/300
</ul>

(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 @<calibration@>
section.


@page elem_calibration Lens calibration data format

Possible embedded elements:
<dl>
<dt>\<distortion focal="number" model="name" k1="number" k2="number" k3="number" a="number" b="number" c="number"
                 real-focal="number"/\>
<dd>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", "ptlens", or "acm".  See @ref real-focal for a
    description of the optional “real-focal” attribute.  @see lfDistortionModel
<dt>\<tca focal="number" model="name" kr="number" kb="number" /\>
<dd>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",
    "poly3", or "acm".  @see lfTCAModel
<dt>\<vignetting focal="number" aperture="number" distance="number" model="name" k1="number" k2="number" k3="number" /\>
<dd>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", "pa", or "acm".
    @see lfVignettingModel
<dt>\<crop focal="number" mode="name" left="number" right="number" top="number" bottom="number" /\>
<dd>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
</dl>

@section real-focal Real focal length

The optional attribute “real-focal” for the @<distortion@> element declares the *real*
focal length of the lens in the <a
href="http://en.wikipedia.org/wiki/Paraxial_approximation">paraxial
approximation</a>, 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.  The images must overlap by at least half an image width.
However, Hugin's results <a
href="https://bugs.launchpad.net/hugin/+bug/1307457">need to be rectified</a>.
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

The database files could be loaded in two ways:

  1. Call lfDatabase::Load(const char *) to load single files. If the given path
  points to a folder instead of a file, all included XML files will be parsed.
  If the same object is defined in multiple files, or lfDatabase::Load(const char *)
  is called several times for different paths, later definitions override
  earlier definitions.

  2. Call lfDatabase::Load() with no parameters. This will try to load the database
  from several standardized locations. It also detects updated database versions
  which where downloaded with the @ref lensfun-update-data
  "lensfun-update-data" tool. A user can override system-wide lens profiles by
  placing appropriately formatted XML files in its home directory. This method
  should be preferred if Lensfun is installed system-wide (typically only for
  Linux distributions with package managers).

@section dblocations Pre-defined database locations

Lensfun has four pre-defined database locations which are available from the following
static class members:

  1. lfDatabase::SystemUpdatesLocation
  2. lfDatabase::SystemLocation
  3. lfDatabase::UserUpdatesLocation
  4. lfDatabase::UserLocation

When lfDatabase::Load() is called without arguments, it first searches in
lfDatabase::SystemLocation, lfDatabase::SystemUpdatesLocation and
lfDatabase::UserUpdatesLocation. Only the folder with the newest database will
be loaded, finally. The age of the database is determined based on the
`timestamp.txt` file found in the database folder. It contains the UNIX time stamp
of the last Git commit, hence a higher number identifies a more recent database.

Afterwards, lfDatabase::UserLocation is loaded without considering a `timestamp.txt`.
This means that profiles in lfDatabase::UserLocation will always have the highest
priority and will overwrite previously loaded profiles with the same name.

@subsection db_unix Linux, UNIX and Mac OS X

The system-wide database folders can be configured at compile time and are preset by
the `GNUInstallDirs` CMake Module.

lfDatabase::SystemLocation defaults to
`${CMAKE_INSTALL_DATAROOTDIR}/lensfun/version_x`, where
<i>x</i> denotes the database format version (@ref db_versions). <br>On Linux this
is typically `/usr/share/lensfun/version_1` or similar.

lfDatabase::SystemUpdatesLocation defaults to
`${CMAKE_INSTALL_LOCALSTATEDIR}/lib/lensfun-updates/version_x`, where
<i>x</i> denotes the database format version (@ref db_versions). <br>On Linux this
is typically `/var/lib/lensfun-updated/version_1` or similar.

The user folders are set at run time based on the current user name and home
directory.

lfDatabase::UserLocation is at `~/.local/share/lensfun/updates/version_x`, where
<i>x</i> denotes the database format version (@ref db_versions).

lfDatabase::UserLocation is at `~/.local/share/lensfun`.

@subsection db_win Windows

As `GNUInstallDirs` CMake Module does not create any meaningful output on Windows
systems, `${CMAKE_INSTALL_DATAROOTDIR}` will be preset by the `%%ALLUSERSPROFILE%`
environment variable.

lfDatabase::SystemLocation defaults to
`${CMAKE_INSTALL_DATAROOTDIR}/Lensfun/version_x`, where
<i>x</i> denotes the database format version (@ref db_versions). <br>This
is typically `C:/ProgramData/lensfun/version_1` or similar.

lfDatabase::SystemUpdatesLocation defaults to
`${CMAKE_INSTALL_DATAROOTDIR}/Lensfun-updates/version_x`, where
<i>x</i> denotes the database format version (@ref db_versions). <br>This
is typically `C:/ProgramData/lensfun-updates/version_1` or similar.

The user folders are set at run time based on the current user name and home
directory.

lfDatabase::UserLocation is at `%%USERSPROFILE%/AppData/Local/lensfun/updates/version_x`,
where <i>x</i> denotes the database format version (@ref db_versions).

lfDatabase::UserLocation is at `%%USERSPROFILE%/AppData/Local/lensfun`.

@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:

<ol>
<li>devignetting
<li>anti-TCA
<li>undistortion
<li>change of projection
<li>perspective correction
<li>scaling
</ol>

@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 pc Perspective correction

Lensfun can correct the effects of tilting of the camera, also known as
perspective correction, see @ref perspective-correction.  In order for this to
work properly, the distortion needs to be corrected, and the image needs to be
converted to rectilinear projection if necessary.  Therefore, perspective
correction is performed \a after the change of projection.

@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.  Because
all other transformations assume the pristine sensor image, in particular for
assuming the correct focal length, scaling 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:

<ol>
<li>scaling
<li>perspective correction
<li>change of projection
<li>undistortion
<li>anti-TCA
<li>devignetting
</ol>

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 → <em>perspective correction</em> →
<em>change of projection</em> → \a undistortion → <em>anti-TCA</em>, 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 perspective-correction Applying perspective correction

Perspective correction, also known as perspective control or keystone
correction, corrects parallel lines.  For example when taking a picture of a
tower, it may be necessary to tilt the camera in order to have the whole tower
in the viewframe.  But then, the verticals of the tower are not parallel in the
picture.  Instead, the edges of the tower become narrower towards the top.

In general, whenever you tilt a camera relatively to a plane in your image
(e.g. the front wall of a building), you get so-called “aberrant lines”, i.e.,
you lose the parallelity of lines (e.g. wall edges) on that plane.  Moreover,
circles become ellipses.

In some cases, such effects may be desired.  In all other cases, Lensfun offers
correction for them.  All it needs are “control points”, i.e. points lying on
lines that are supposed to be parallel.  Note that in most cases, Lensfun also
needs the proper focal length and crop factor for perspective correction.

You can use Lensfun's perspective correction in five different modes, which are
distinguished by the number of control points given.  This table presents an
overview:

<table>
  <tr><th>number of<br/>control points</th><th>type</th><th>short description</th>
    <th>focal length<br/>necessary</th><th>full<br/>correction</th></tr>
  <tr><td>4</td><td>lines</td><td>(1) & (2) define first line, (3) & (4) define second line, both should be parallel</td>
    <td>yes</td><td>no</td></tr>
  <tr><td>5</td><td>circle</td><td>points on (distorted) circle line</td>
    <td>yes</td><td>no</td></tr>
  <tr><td>6</td><td>lines</td><td>(1)–(4) as with 4 control points; (5) & (6) define line perpendicular to the other two</td>
    <td>yes</td><td>yes</td></tr>
  <tr><td>7</td><td>circle & line</td><td>(1)–(5) as with 5 control points; (6) & (7) define perfectly horizonal or vertical line</td>
    <td>yes</td><td>no</td></tr>
  <tr><td>8</td><td>lines</td><td>(1)–(6) as with 6 control points; (7) & (8) define line parallel to the (5)/(6) line</td>
    <td>no</td><td>yes</td></tr>
</table>

In this table, “full correction” means that all lines that are parallel in the
original (horizonal, vertical, diagonal, whatever, as long as they are within
the plane) become parallel after the correction.  No full correction means that
only lines in <i>one</i> direction are corrected.


@section lines-based-pc Lines-based correction

<div class="image-portrait43">
\image html pc-8-points.svg "8 points: two horizontals, two verticals"
</div>
<div class="image-landscape">
\image html pc-6-points.svg "6 points: two verticals, one horizonal"
</div>
<div class="image-landscape">
\image html pc-4-points.svg "4 points: two verticals"
</div>

Using 4, 6, or 8 control points activates a lines-based correction using 2, 3,
or 4 lines, respectively.  Each consecutive pair of points defines a line.  The
ordering within a pair doesn't matter.  In the images, you see examples for
placing the control points in each case.

As you can see in the 8-points image, points may also share their coordinates.
In the 6-points image, points 5 and 6 could be the same as 2 and 3,
respectively.  But try to use lines as long as possible.

Whether a line or a pair of lines is to be interpreted as vertical or
horizontal, is decided by Lensfun by taking the best match.  For example in the
8-points case, you could swap verticals and horizontals, and it would work
either way.

@section circle-based-pc Circle-based correction

<div class="image-landscape">
\image html pc-7-points.svg "7 points: one circle, one horizonal"
</div>
<div class="image-landscape">
\image html pc-5-points.svg "5 points: one circle"
</div>

Using 5 or 7 control points activates a circle-based correction using an
ellipse which is supposed to become a circle.  Mathematicaly, 5 points define
an ellipse.  Two additional points may be used to define a horizonal or
vertical line, whichever is closer.

There is, unfortunately, an ambiguity to sort out: A circle may become an
ellipse by tilting the camera upwards or downwards.  Without further
information, Lensfun cannot know what happened in a particular image.  Thus, if
you set the control points clockwise, Lensfun assumes that the first point is
farther away from the camera than the centre of the circle.  Accordingly,
counter-clockwise control points indicate that the first point is closer to the
camera than the centre of the circle.  This may sound complicated but in most
cases, the camera is tilted upwards like in the example images.  Then, just set
the control points clockwise beginning at the top, and it works.

@section pc-postprocessing Shifting, scaling, and rotating

After a successful perspective correction, it is highly senseful to apply some
post-processing.  Additionally to what is already in Lensfun's chain of
transformations, it adds the following:

<ul>
<li>It shifts the image to that the original centre remains in the centre.  In
some extreme cases, the original centre cannot be displayed anymore because it
is beyond the vertex.  Then, the centre of the control points is used
instead.</li>
<li>It scales the image so that the centre of the image keeps its scale.</li>
<li>It rotates the image so that lines supposed to be vertical or horizonal actually are.</li>
</ul>

@section pc-d-parameter The d parameter for fine-tuning

\image html pc-d-parameter.svg "Relative tilting angle for different d values"

Very often, a full correction of the perspective is not the artistically best
option.  Instead, a slight undercorrection leads to a more pleasing result.
For this and similar purposes, Lensfun offers a fine-tune parameter called “d”.
It takes values from −1 to +1 with the following meaning:

<table>
  <tr><th>d</th><th>meaning</th></tr>
  <tr><td>−1</td><td>no change of the image</td></tr>
  <tr><td>0</td><td>perfect correction</td></tr>
  <tr><td>+1</td><td>over-correction by 24%</td></tr>
</table>

Technically, by increasing d from −1 to 0, the tilting angle is decreased from
the original value to 0.  Values of d greater than 0 increase the tilting angle
to the opposite direction up to 24% of the original tilt.

@section pc-tips Tips

<ul>
<li>Use lines which are as long as possible.</li>
<li>Use circles which are as large as possible.</li>
<li>Take care that pairs of lines which are supposed to be parallel are as far apart as possible.</li>
<li>Use 8 points only if the focal length is unknown or inaccurate.</li>
<li>Do not mark lines that are already parallel in the original image.</li>
<li>Do not mark circles that are already perfectly circular in the original image.</li>
</ul>


@section pc-in-own-code How to implement perspective correction in own code

Currently, perspective correction has its own initialiser
lfModifier::EnablePerspectiveCorrection.  Typically, you will call this method
immediately after lfModifier::Create and lfModifier::Initialize.  In plain C,
you call ::lf_modifier_enable_perspective_correction immediately after
::lf_modifier_new and ::lf_modifier_initialize.  The only real challenge is to
get the control point coordinates.

@subsection pc-coordinates Control point coordinates

Control points are given using their pixel coordinates.  The origin of the
coordinate system is in the top left corner, with the first pixel having the
coordinates (0, 0).  The first coordinate is measured to the right, and the
second is measured to the bottom.  For best accuracy, the coodinates do not
refer to the pristine image.  Instead, the following transformations need to
have been applied when the coordinates are determined:

<ul>
<li>distortion correction</li>
<li>transformation into rectilinear, if necessary</li>
</ul>

Since for most lenses, both transformations don't change much, you can also use
pristine RAW image coordinates lenses for simplicity, but this may lead to
slightly inaccurate perspective correction, and fails for fisheyes.  In
contrast, the following transformations <i>must not</i> have been applied when
the coordinates are determined:

<ul>
<li>scaling</li>
<li>rotation</li>
<li>shift</li>
<li>crop</li>
<li>any other coordinate-changing transformation</li>
</ul>

Vignetting and TCA corrections don't matter.

@subsection pc-suggestion-for-implementation Suggestions for getting control points

If you wish to offer perspective correction in an interactive way, it is
recommended to present a distortion-corrected, rectilinear image to the user.
Then, the user picks coordinates in the image, and these coordinates are ready
to be used for perspective correction directly.

Another possibility is to let the used set control points in the really
pristine image (without any transformations applied).  Then, you set up a
modifier object only for distortion correction and – in case of a fisheye lens
– for transformation into the rectilinear projection.  <i>It is important that
you set the “reverse” option to “true” for this modifier.</i> Then, you send
the control point coordinates through lfModifier::ApplyGeometryDistortion and
get the coordinates for perspective correction.  Of course, for the actual
correction, you need a different modifier object.

@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.

<ul>
<li>@ref basearch
<li>@ref samplecode
</ul>


@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
<lensdatabase version="1">
    ... put your definitions here ...
</lensdatabase>
@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.

<ul>
<li>@ref addcamera
<li>@ref addlens
</ul>


@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
    <camera>
        <maker>Nikon Corporation</maker>
        <maker lang="en">Nikon</maker>
        <model>Nikon D300</model>
        <model lang="en">D300</model>
        <mount>Nikon F AF</mount>
        <cropfactor>1.523</cropfactor>
    </camera>
@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.

<ul>
<li>@ref el_camera
</ul>


@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
    <lens>
        <maker>Pentax</maker>
        <model>smc Pentax-DA 12-24mm f/4 ED AL IF</model>
        <mount>Pentax KAF2</mount>
    </lens>
@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.

<ul>
<li>@ref el_lens
</ul>


@page samplecode Sample code

Here goes some coding examples, from simple to complex.

<ul><li>\ref example.c</ul>

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.

<ul><li>\ref tfun.cpp</ul>

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.

<ul><li>\ref lenstool.cpp</ul>

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

