WHAT IS IT
----------
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. Right now lensfun is designed to correct
distortion, transversal (also known as lateral) chromatic aberrations,
vignetting and colour contribution of the lens (e.g. when sometimes
people says one lens gives "yellowish" images and another, say, "bluish").
The interface is defined both using C++ style and plain C.
The C interface is a wrapper around the C++ classes.
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: http://www.gnu.org/licenses/lgpl-3.0.html
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: http://www.gnu.org/licenses/gpl-3.0.html
Also the build system (the contents of the build/ subdirectory plus the
ac.py file) is licensed under GPL v3.
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:
http://creativecommons.org/licenses/by-sa/
QUICK BUILDING AND INSTALL
--------------------------
For people that just want to quickly build and install the library and
forget it, here goes a quick reference.
To build the library, you must first configure the library and then
build/install it, as usual. In order to successfully configure and
build the project the following tools are more or less required:
- Python to run the configure script.
- GNU Make 3.80 or later to run the (rather complex) makefiles.
- Doxygen in order to generate the library documentation.
- GLib 2.0 and later which is used for low-level I/O and XML parsing.
- libpng is required to build and run test programs.
First, configure it almost as usual when you use autoconf-based build systems:
CFLAGS="..." CXXFLAGS="..." LDFLAGS="..." LIBS="..." \
./configure --prefix=... [--bindir, --libdir, --sysconfdir, ...] \
[--staticlibs (by default it builds shared libs)]
(see ./configure --help for a full list of configuration options).
If all goes well, you now can enter:
make install
This will build and install everything required for installation. No separate
build step is required, it will work in just one step. If you want to install
somewhere else, not to the directory given by --prefix, you can define a
installation prefix:
make install INSTALL_PREFIX=/some/where
also, for compatibility with GNU autotools, DESTDIR is also accepted as an
alias for INSTALL_PREFIX.
If you have special requirements for installing some components into separate
directories (like the Debian packages have special requirements for installing
html manual into a directory different than --docdir), you may override the
target directory for any submodule by specifying the value of a variable named
INSTDIR.${module}, like this:
make install INSTDIR.manual=/usr/share/doc/lensfun-manual
BUILDING FOR WINDOWS
--------------------
You have two choices to build the library for Windows: you build under Windows
and you build under Linux using WINE. I prefer the later since I don't have
Windows installed anywhere. Also you can choose between MSVC and MinGW32
compilers, native and cross-building is supported for both.
In any case, building for Windows is quite a trick (like always). There are no
hardcoded paths on Windows, like in Unix. However, if needed, using hard-coded
paths is still possible (e.g. when using the MinGW32 cross-compiler on Unix,
the prefix can be hardcoded to something like /usr/i686-pc-mingw32/sys-root/mingw).
So both dynamic and static paths are supported for Windows builds.
To enable dynamic paths, you must define the respective static path to empty.
For example, to make lensfun use dynamic paths (on supported platforms) you
must use the --prefix="" --datadir="" configure command-line options so that
CONF_DATADIR becomes undefined.
with MSVC
---------
You will need Python (native Unix python will work fine if cross-compiling),
glib binary and devel packages for Windows (download it from gtk homepage:
http://www.gtk.org/download-windows.html) and the MSVC compiler. You may use
the free command-line MSVC that's available for download somewhere on
Microsoft's site, like I do.
If you're on WINE, you must run the following script before starting compilation:
. build/mak/msvc-wine.sh /path/to/msvc x
This will set up the environment and PATH appropiately.
Now to configure I recommend the following command line:
python configure --compiler=msvc --target=windows.x86 --mode=release \
--prefix= --bindir= --includedir= --libdir= --docdir= --datadir= \
--sysconfdir= --libexecdir=
After that you may run make and build it.
with MinGW32
------------
For cross-compiling just install mingw32 and the required libraries.
On my system I had to install the following RPMs:
mingw32-gcc-c++
mingw32-libpng
mingw32-glib2
Everything else was pulled in by dependencies.
Configuring and building is similar to MSVC builds:
export TKP=i686-pc-mingw32-
export SDKDIR=/usr/i686-pc-mingw32/sys-root/mingw
./configure --compiler=gcc --target=windows.x86 --mode=release \
--prefix= --bindir= --includedir= --libdir= --docdir= --datadir= \
--sysconfdir= --libexecdir= $*
the TKP variable defines the compiler prefix to use (e.g. i686-pc-mingw32-gcc
instead of gcc, i686-pc-mingw32-g++ instead of g++ and so on). The SDKDIR
variable (just as for MSVC) will set the directory prefix where configure
will look for header files and libraries, because there's no pkg-config
on Windows.
To prepare a distribution it is recommended that you use the following
command line:
make install INSTALL_PREFIX=distr/ CONF_INCLUDEDIR=include/ \
CONF_LIBDIR=lib/ CONF_DATADIR=lib/lensfun/
BUILD SYSTEM IN DEPTH
---------------------
This project does not use autoconf, but the configure script tries to mimic
it to some extent. You can see a list of configure options by typing:
./configure --help
as usual. After that you can build one or several "modules" (which are
the separate pieces which together form this whole project). To see what
modules are there, type "make" without parameters. For example, to build
all test programs, type:
make tests
The build system hides the complexity of the commands run under macros like
GCC.CC, GCC.LD and so on, to avoid cluttering the output and let you easily
identify warnings and errors. However, if you're curious to see the full
commands used while building, set the makefile variable "V" to 1, e.g:
make install V=1
If for some reason you need a static library (by default a shared library is
built), you must use the --staticlibs configure switch, which will force all
shared libraries to be built statically. For example it is more convenient
to debug with static libraries, because you don't have to set the
LD_LIBRARY_PATH variable to the directory where the shared libraries
are built.
The build system allows quick switching between compiling in debug and
release mode. The default is release mode for those quick guys that just
need to build lensfun as a dependency for something bigger. You can change
the build mode by specifying a value to the MODE makefile variable, e.g:
make MODE=debug
Another feature of the build system is that it uses a special tool called
makedep to automatically build dependencies. If it is installed in your
system, configure will detect and use that. If not, it will be automatically
built and used. If you don't want this to happen, you must set the AUTODEP
variable to 0:
make all AUTODEP=0
These are the most important features so far. The build system currently
lacks a complete documentation, but I hope the above info is enough to
productively use it.
DOCUMENTATION
-------------
The end-user documentation for the library can be built by issuing the
command:
make docs
Also you can read it online at any time by pointing your browser to:
http://lensfun.berlios.de/manual/
The documentation on the site is updated every night from SVN, so it always
contains the latest info on the library.
CREDITS
-------
Here goes a full list of people who have contributed to this library:
CODE:
Andrew Zabolotny <zap@homelink.ru>
LENS DATA:
Tom Niemann: original open-source ptlens database.
THANKS:
Pablo d'Angelo for the idea of a open-source lens database.
The whole PanoTools team:</b> for all math and knowledge I have borrowed
from PanoTools:
Helmut Dersch - The father of most (all?) open-source panorama
creation tools.
Daniel M. German
Kevin Kratzke
Rik Littlefield
Fulvio Senore
Jim Watters
Thomas Rauscher
Pablo d'Angelo (thanks once more :)
Bret McKee
Robert Platt
Also I would like to thank the people that made valuable contributions to lensfun:
Niels Kristian Bech Jensen
Pascal de Bruijn
