<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<link rel="stylesheet" type="text/css" href="docs.css">
<title>Adding new lenses to the database</title>
</head>
<body>
<h1>Adding new lenses to the database</h1>
<p>Often I'm asked how to add new lenses to the databases, and how to evaluate the
distortion, tca and vignetting lens parameters for a particular lens.
A few years ago I had no answer to these questions – there was some commercial
software available which could compute some of these parameters, but I had no
access to it so I had no idea what it can and what can't do.
</p>
<p>But in the later years the Hugin open-source program have evolved, so now it
covers most of the functionality that Lensfun can use. In fact, it was an oncoming
traffic, as Lensfun was also modified to be more compatible with Hugin models.
So today it is possible to create a complete lens database entry using just
Hugin and the tools which are part of the Hugin package.
</p>
<p>Let's try to create a complete lens description from scratch, step by step.
First of all, we have to create the basic description for the lens. For this we
will need to know what's the complete name of the lens. First, let's see if exiftool
or exiv2 can decipher the lens name from the metadata of some raw or jpeg file:
</p>
<pre>
# exiftool sg201196.dng | grep -i lens
Lens Type : smc PENTAX-DA 12-24mm F4 ED AL [IF]
Lens ID : smc PENTAX-DA 12-24mm F4 ED AL [IF]
# exiv2 -pt sg201196.dng | grep -i lens
</pre>
<p>So, exiftool identifies the lens as "smc PENTAX-DA 12-24mm F4 ED AL [IF]", and
exiv2 was not able to identify it. We can use just this name in database, but for
aestetics we'll change the name to the same form as used through the database using
knowledge about the rules Lensfun uses when doing a fuzzy search of lenses in database:
</p>
<ul>
<li>During a lens search the case of characters is ignored. Thus, Lensfun does not
care if it is "smc" or "SMC".
<li>During a lens search the order of words does not matter. That is, "pentax da smc"
and "smc da pentax" are absolutely equivalent. 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. The full lens name
will be split into words "smc", "pentax", "da", "12", "24", "mm", "4", "ED", "AL", "IF".
</ul>
<p>So, looking at other database entries and trying to create a similar-looking
lens name we'll create our first lens entry:
</p>
<pre>
<lens>
<maker>Pentax</maker>
<model>SMC PENTAX DA 12-24mm F/4 ED AL IF</model>
<mount>Pentax KAF2</mount>
</lens>
</pre>
<p>Now to make the lens description really useful we have to find out the mathematical
model of its distortions and fill them in the database. For this we'll need a few test
shots made with the lens you're trying to model (if it is a zoom lens, make several
series of shots at several intermediate focal lengths including the extremes). Also,
you will need Hugin – the best tool for automatic dealing with image distortions I know.
In fact, Hugin will do most of the calibration work for us; our task is to feed the
correct data and click the correct buttons :)
</p>
<p>There exists also a
shorter <a href="http://wilson.bronger.org/lens_calibration_tutorial/">tutorial
for Lensfun calibration</a>. It is not as comprehensive regarding the
theoretical background. But it includes a free command-line program that
automates most of what is explained here.</p>
<p>In my case I've used the Samsung GX20 body (crop factor 1.5, 14 megapixels).
I made three panoramic test shots (turning 5–10 degrees after every shot) at focal
lengths of 12, 15, 18, 21 and 24 mm, thus in the end I've got 15 test shots.
All raw files were developed to TIFFs. For TCA and vignetting calibration,
these TIFFs must be in the sensor's linear RGB colour space.
</p>
<p>When making test shots for computing distortion, choose the aperture that makes
your lens maximally sharp (usually this is something between 8.0 and 16.0).
Since distortion does not depend on aperture, this will make your work easier
when you'll put control points on the image.
</p>
<p>The crop factor of the camera that was used to make test shots should be added
to the database in the <cropfactor> tag. This value will help Lensfun scale
the model to fit the shot made with other camera with possibly other crop factor.
</p>
<p>For example, if a model is made with a crop factor of 1.0, it can be used with
shots made with another camera with a crop factor of 1.5, but Lensfun will have
to scale the coordinates accordingly. On the other hand, if the model was made
for a crop factor of 1.5, it is not a very good idea to use this model for shots
made with another camera with a crop factor of, say, 1.1, because the math model
was verified only for the smaller portion of the image in the center. However,
most of the time this works too.
</p>
<ul>
<li><a href="lens-distortion.html">Calculating lens distortion</a></li>
<li><a href="lens-tca.html">Calculating lens transversal chromatic aberration (TCA)</a></li>
<li><a href="lens-vignetting.html">Calculating lens vignetting</a></li>
</ul>
</body>
</html>