• Subscribe

    Subscribe to This Week In Panospace by eMail.
    Subscribe in a reader
  • License

    Creative Commons License
    This work is © 2008-2012
    by Yuval Levy
    and licensed under a
    Creative Commons License.
  • Entries

    December 2008
    M T W T F S S
    « Nov   Jan »
  • Archives


hugin-logoInspired by a discussion of Bruno Postle and Tom K. Sharpless, Daniel M. German added a new projection to libpano, the library underlying hugin for geometrical transforms. The new Panini projection, named after one of the most famous vedutismo painters, would not be immediately available within hugin.

For me, this was the chance to get a little bit deeper into the code. I had a free hour. I had a flu and did not want to pass it on to my baby. So I set on a journey that looking back would only take a few minutes to an experienced coder. And next time it will indeed take me much less. But next time I might leave the challenge to another contributor – maybe a potential Google Summer of Code student looking to commit a patch as part of the selection process.

I started from a fresh and clean build according to the standard instructions for Ubuntu. The file system layout is such that a top level src folder contains a libpano13 folder and a hugin folder with their respective sources fresh from SVN. Since this is an additional projection, I looked at something similar for orientation to what I need to do – in this case how other libpano projections are implemented in hugin.

First I looked at Daniel’s most recent changes to libpano, specifically this change in the list of features that libpano gives to external programs calling it. I happened to find a minor bug in it and posted a patch. And I understood from it that I was to add the preojection #12, PANINI.

I opened a terminal window and searched throughout the hugin source tree for the implementation of the Lambers projection:

$ find . -exec grep -l "LAMBERT" {} \;

returned the list of files to look into, with the exception of those files with .svn/ in the path, as they are part of the subversion system.

I found and looked into the following files:


I looked inside to understand what they were doing and how I shall change them to accommodate the new projection.

In ./src/hugin_base/panodata/PanoramaOptions.h I added PANINI to the enumeration – just search for LAMBERT to see where it is likely that changes are needed.

In ./src/hugin_base/panodata/PanoramaOptions.cpp I had to add the projection and return sensible value for the maximum horizontal and vertical field of views (HFOV and VFOV). I was not sure. Daniel sugested 220° and 180°. Anything wide enough is OK, if users find that it goes to far, the limit can be adjusted later on. UPDATE: a second look at the code shows that the info comes from libpano13’s queryfeature.c, so no need to edit that.

In ./src/PTBatcherGUI/ProjectListBox.cpp I just added the projection to the list of displayed PTBatcher’s GUI options. I have not tested PTBatcher.

In ./src/hugin_base/panotools/PanoToolsInterface.cpp I added an additional case for PANINI and the _panini value, analog to the other projections. To make sure that I did not have to do additional changes, I grepped for _lambert to confirm that this is just the symbol passed on to libpano and nothing more has to be done in hugin. Indeed I found the symbol in libpano.

For the next three files, I needed to know a little bit about the projection, specifically about its behaviour at the poles. Since AFAIK it does not have “stretchy poles”, I did not make any change in ./src/hugin1/hugin/OutputProjectionInfo.cpp nor in ./src/hugin1/hugin/ChoosyRemapper.cpp. I was not sure about whether it streches across the 360° seam. Since it is a projection that has similarities to RECTILINEAR, I replicated that behavior in ./src/hugin1/hugin/VertexCoordRemapper.cpp. Probably a mistake – the fast preview show gibberish for the new Panini projection, but some of the more expert coders may look into that, and it does not affect the traditional preview nor the rendering output.

Last but not least, ./src/hugin1/tests/test_projections.cpp. It seems that the function of this file is to test the transforms, and it has been neglected for a while: the tests stopped at Lambers Azimuthal – no tests for Albers Conic Equal Areas nor Miller Cilindrical, both of which have been added later to libpano. It was simply an updater of the counter’s upper limit to PANINI that extended the test to these projections, as well as to the new one.

All changes done, cross fingers and continue with the standard build / install process. If something does not work, try to find out what it is. Ask the community!

I was lucky. Everything built and installed.

The next step is to prepare a patch and post it for peer review in the community:

$ svn diff hugin > hugin.panini.patch

Since this is a minor change that does not seem to break anything, and since I have commit privilege, and since we have no policy about svn commits of unstable / insufficiently tested code, I decided to take the sortcut and committed.

$ svn ci -m "support for libpano13's panini" hugin

So simple, if you know what to do. I hope this tutorial is helpful and will motivate you to put your hands under the hood. It is specific to Linux but most likely works with very little changes on OS X as well. Conceptually it is the same in Windows, using Windows’ Explorer instead of the find/grep command line duo, and TortoiseSVN’s diff functionality.

The most important is: try it! Sooner or later you’ll get it right.

“Only those who risk going too far can possibly find out how far one can go.”
T.S. Eliot (1888-1965)

By the time I finished, Daniel already added a new projection, called Architectural. Will somebody be faster than me and use this tutorial to add it?