# Adding new lenses to the database

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.

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.

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:

    # 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

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:

- During a lens search the case of characters is ignored. Thus, Lensfun does not care if it is "smc" or "SMC".
- 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".

So, looking at other database entries and trying to create a similar-looking lens name we'll create our first lens entry:

    <lens>
        <maker>Pentax</maker>
        <model>SMC PENTAX DA 12-24mm F/4 ED AL IF</model>
        <mount>Pentax KAF2</mount>
    </lens>

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

There exists also a shorter tutorial for Lensfun calibration. 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.

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.

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.

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.

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.

- Calculating lens distortion
- Calculating lens transversal chromatic aberration (TCA)
- Calculating lens vignetting