Creating lens distorsion models with Hugin’s lens calibrator

Creating lens distorsion models with Hugin’s lens calibrator

If your lens is missing in LensFun database, you can create it thanks to lens calibration app from newly released version of Hugin, a free panorama stitcher. Learn how to do it.

The by far most popular library for fixing lens distorsion is LensFun which relies on panotools model. It's used in darktable, Rawstudio, digiKam, UFRaw and other digital photography apps for Linux. It works quite nicely, but the lens database isn't exactly complete, and there is no dedicated user interface to create new entries for this library. Which is why Andrew Zabolotny, principal developer of LensFun, suggested to everyone to just use Hugin.

Hugin lens calibration app is, therefore, a first step in the direction of providing such a user interface. Download Hugin here, build it, if you are on Linux, and run Hugin Calibrate Lens application. Here is how it works.

First of all, if you need to create a new or better (since some lens descriptions are very simplistic) lens distorsions model, you need a set of images shot with different focus distance (if it's a zoom lens). It can be a printed grid target shot from close distance, or a photo of a building with prominent horizontal and vertical lines.

You have to be careful about initial yaw, pitch and roll of the lens, because it's all about detecting horizontal and vertical lines. The image below is, for this very reason, a somewhat poor example, because it has crippled horizontal perspective. You can fix horizontal keystone in e.g. darktable, but then it's not a clean lens model anymore. Edit: Bruno comments below that this is actually not a big deal.

Hugin lens calibration UI

It's best to have several images loaded for better precision, but let's go for just one in this case.

In some rather rare cases the application won't read focal length and crop factor from Exif. You can easily fix it by setting those manually:

Adding images and setting basic metadata

Once you have it loaded and set, you need to find a good combination for edge detection which is how the lens calibration app figures out what the horizontal and vertical lines of an image are. The principle is that the higher edge detection scale and threshold values are, the less edges you get.

Edge detection options

Press Find lines button to run lines detection. Then you can switch to edge detection display mode in the top toolbar. This mode is easier for evalutation of detected lines. Here is what it looks like:

Automatically detected horizontal and vertical lines in a photo

If some of the detected lines aren't good enough, single-click on them to mark them for exclusion from calculations. Clicked lines become red:

A couple of horizontal and vertical lines marked as bad

When you think you're done, click Optimize button in the sidebar to calculate a, b and c values for panotools distorsions model.

Calculated lens distorsion settings

To try how it works you can switch display mode to Corrected and see if it works well. If it does, the next step is to create a new XML file in a text editor and copy the calculated values there, then save the file and send it to Andrew for inclusion in the next version of LensFun. Andrew provides a rather detailed manual on creating XML files for LensFun database. Please refer to it for details.

When it's done, you can locally patch an existing database. The XML files of the database are stored in /usr/share/lensfun/ directory on Linux. Then your digital photography application will pick the updated database and will be able to fix distorsions for your lens.

The article logo is based on artwork by Henrik Andersson of fellow darktable project.

Was it useful? There's more:

29 Responses. Comments closed for this entry.

  1. Good article. Though you don’t have to be careful finding a subject with horizontal and vertical lines, the lines can be in any direction and the photo can have perspective distortion - The only requirement is that they are straight in reality.

    (technically the optimiser adjusts the distortion so that the lines fit great-circles when projected onto the virtual sphere).

    Also, to do this properly the tool allows you to process several photos at the same time, you will get much more reliable parameters from the optimisation this way.

    Patches that output the lensfun XML format directly are welcome.

  2. อัมพวา 10 October 2011 at 1:12 pm

    Nice PIC. Good Article Thanks for Sharing.

  3. Good article and good to know that calibrating a lens is getting that easy now. But unfortunately the parameters I retrieved were not as accurate as the ones I got by the old control point method in Hugin.

    For best results I will still follow this tutorial

  4. Alexandre Prokoudine 14 October 2011 at 11:09 pm


    Oh, I didn’t even know you updated your plug-in in September! Do you know that there is a GEGL operation for using LensFun now?

  5. Hi Sebastian, yes the ‘best’ way to get good lens-correction parameters is to stitch a panorama, preferably with a calibrated panorama head. But this is learning another skill and it shouldn’t be necessary, there are a lot of users who will never do this.

    However, the lens calibration tool should give very good results if you use lots of photos simultaneously, i.e. if you just use one photo you might get lucky, but it could also go very wrong.

  6. @Alexandre
    I didn’t know the GEGL implementation. Looks interesting, though the GUI is quite simple and does not analyze the exif information. Anyway… a good starting point for a GEGL port of the plugin.

    I tried several photographs but did not succeed to get consistent results. But this could also be the fault of the images I used for calibration. I will take some more photographs from buildings with many straight lines and give it another try. Taking good images suited for reliable calibration is tricky with all the other methods as well.

  7. For something a little different, I found this post very helpful:

    This post refers to this page:

  8. I calculated a profile for the new Tamron SP 24-70mm F/2.8 Di VC USD lens. where do I send it?
    Here below :
          <model>Tamron SP 24-70mm F/2.8 Di VC USD</model>
          <mount>Nikon F AF</mount>
            <distortion model=“ptlens” focal=“24” a=“0.05013” b=”-0.1372” c=“0.07787” >
            <distortion model=“ptlens” focal=“35” a=“0.00747” b=”-0.01777” c=“0.0066” >
            <distortion model=“ptlens” focal=“50” a=”-0.04004” b=“0.15509” c=”-0.17226” >
            <distortion model=“ptlens” focal=“70” a=”-0.02056” b=“0.07751” c=”-0.06572” >

  9. I have put some love into getting a distortion profile for the Panasonic “LUMIX G 14mm F2.5”

    Not knowing how to submit it to the project, here it goes:

          <model>LUMIX G 14mm F2.5</model>
          <mount>Micro 4/3 System</mount>
            <distortion model=“ptlens” focal=“14” a=“0.0116” b=”-0.04802” c=”-0.00435” >

  10. Alexandre Prokoudine 22 December 2012 at 11:02 pm

    Interesting, that’s two submissions already :)

    Did you try registering and submitting a bug report with the file attached?

  11. I am not sure I understand. 

    I have a Nikon D800 with a 24-70 mm lens.  This is the standard lens for the camera, so I am surprised it is not in the database.  But I am willing to give calibration a try.  What I don’t understand is that presumably the calibration depends on the focal length and the distance of the camera from the subject.  How many sample choices do I have to do calibration for, and how do I choose them?

    I also have a couple of related questions.  The Lensfun database says the 70-200 mm lens, which I have, is in the database, but it doesn’t show up in darktable or in GimpLensfun.  How do I fix that?

    Finally,  those programs show the D800 camera, and If I choose it with the lens blank, they do some sort of correction.  Does that correction have any validity at all?

  12. Alexandre Prokoudine 28 September 2013 at 8:30 pm

    Hi Leonard,

    Lenses have focal length markers. E.g. Nikkor 24-70mm f2.8 has these ones: 24, 28, 35, 50, 70. Typically people use those for sampling.

    I don’t see Nikkor 24-70mm f2.8 in the list at and i,t’s not in /usr/share/lensfun/slr-nikon.xml. Unless we are talking about Sigma’s 24-70, of course. OTOH, I don’t have D800 there either, so I guess indeed my database is outdated.

    As for corrections, Nikon D800 seems to be a full-frame camera, so crop-factor correction shouldn’t apply. I’m not sure what’s going on there. Perhaps it’s best to check back with developers.

  13. Torsten Bronger has told me the following.

    “The data for the 24-70 is too new.  You would have to copy’n'paste the entry from

    I copied the entry from there and pasted it into /usr/share/lensfun/slr-nikon.xml
    and it works fine.

    He also explained that

    “70-200 was made with an APS-C sensor.  LensFun
    refuses to extrapolate this on full frame.  You will have to calibrate yourself.”

    I’ve used hugin in the past to stitch images, so I should be able to calibrate my 70-200 lens myself.

    Also, I hope I can calibrate any other lenses I get.

  14. Alexandre Prokoudine 06 October 2013 at 6:43 am

    Leonard, I’m glad it worked for you. Coincidentally, we have a far more detailed write-up on updating LensFun database coming.

  15. I can’t get the hugin calibrator to work, perhaps because I don’t have enough lines extending the whole width.  If I fiddle with the parameters, I get small line segments, and after eliminating ones that are wrong, and applying Optimize,  I get very strange looking values for a, b,  and c.  When I click on Corrected, I get a blank screen.

    I had greater luck using the hugin panorama maker, by picking control points.  Then I get more plausible looking values for a, b,  and c, but I don’t see how to display the image with those corrections in place.  I suppose I could put them in slr-nikon.xml, and see what happens, but before doing that,  I would like to feel I know what I’m doing.

    Any suggestions would be appreciated.

  16. I shou ld have noted in the previous comment that I was trying to calibrate my Nikkor 70-200 f/4 lens for my Nikon D800

  17. Alexandre Prokoudine 15 October 2013 at 3:04 pm

    @Leonard, do you think you could upload an image you are trying to calibrate against? I’d love to have a look.

  18. I’m sorry, but I don’t see how to upload an image

  19. Alexandre Prokoudine 15 October 2013 at 10:21 pm

    You can use any online storage such as e.g.

  20. Okay I uploaded it

    I know I’m being stupid, but I don’t see how I make it available for you to look at.

    I also put it in
    but I’ve forgotten how to make it visible to the pubic, and it will take me some time to remember how to do that.

  21. Ok, an old entry. Anyway.
    I do not know why it should be a picture of real life.
    I created this template and I’ve taken pictures for each focal length:

  22. Yafu’s template certainly looks as if it would do the job.  The only ting I wonder about is the following.  Even if put on a large poster, the template would have to be photographed fairly close up.  But the amount of distortion may vary according to the focus distance.  So I wonder whether a less complete scene at a normal distance for what I am photographing might produce better results.

  23. @Leonard Evens.
    I printed the template in A4 paper and I’ve stuck with scotch tape to a blackboard. There should be no wrinkles in the paper. Then I took RAW photos for each focal length, perfectly placing the camera in front of the paper. In each of the photos I tried the larger outer square of the template is as close as possible to the outer limit of the camera frame. Therefore, for each focal length I must move away a little relative to the template. You must open the RAW in your favorite program (without applying lens corrections), and export it as JPG so that the distortion appears in the JPG. Then open each one at a time in Hugin Lens Calibrator GUI (you do not load more than one image at different focal lengths. Work with a single image at a time). In Hugin Lens Calibrator GUI I had to adjust some values ​​to as many lines as possible were detected.
    I guess in Hugin Lens Calibrator GUI more than one image for the same focal length can be loaded, for a more accurate result. But to me it seems to work fine working with a single image.
    I really do not know if this method has disadvantages compared to do it with real life scenes, but seems to work.

  24. Of course, you place the template horizontally, not as shown above.

  25. I have asked Torsten Bronger and answered me:
    “Some lenses have different characteristics for different distances.
    Therefor, I prefer calibrations based on a minimal subject distance
    of 3 metres.”
    So I guess for wide angle I can use the straight edges of my blackboard :)
    But really, at least with my camera that has no real aperture, I do not notice much difference.

  26. What is this word “distorsion”? I can’t find it in any of the dictionaries.

  27. Good article. Good to know that calibrating a lens is getting that easy.

  28. Ken, he means “distortion.”