phfluuh ====== this is the README for phfluuh. phfluuh helps you make panorama images. the phfluuh homepage is http://www.acc.umu.se/~janlert/phfluuh/ all mail should go to phfluuh@acc.umu.se the software is licensed under the GNU GPL. how to make panorama images with phfluuh ---------------------------------------- here is a short step by step description how to make your own panorama images. 1 take some pictures and transfer them to your computer 2 calculate the numbers needed for the enfish plugin 3 run the plugins 4 crop and adjust each step is described in detail below and we suggest that you read the whole document before you try anything. sounds easy enough, right? take some pictures and transfer them to your computer ----------------------------------------------------- start with finding a nice view. make sure that you're holding the camera straight, no tilt, no pitch, no nothing. any rotation will _surely be noticeable in the result_. use a tripod if you can! make sure that all the images are overlapping. the more they overlap, the less problem you'll have with radial distortion and other bad things. make sure that you lock the white balance of the camera if you can. if you don't, the colors of the pictures probably won't match and you'll end up spending hours matching them. calculate the numbers needed for the enfish plugin -------------------------------------------------- all cameras are different. to be able to transform your images correctly, the enfish plugin needs to know a few things about your camera. > lens width the first number, the lens width, is quite easy to calculate. take a photo of a wall x units away, make sure the camera points straight at the wall. measure how wide area the the image covers (y), the lens width is now y/x. for example: if i take a photo 1m from the wall and the width is 0.98m the lens width value is 0.98. when you're at it you might as well measure the lens height too, if you want to take portrait pictures (all our examples are portrait pictures originally). camera -> C - / \ | / \ | distance (x) / \ - ------------------------- <-- wall |-------| width (y) > radial distortion the other two numbers needed are for compensating for the radial distortion. radial distortion is the effect that makes straight lines become not so straight when you photograph them, things bend. radial distortion is not fun. if you take a photograph of a grid (for example a printout of the grid plugin for gimp) the grid will be "bent" on the photograph. to compensate for this you need to know how much your camera "bends" the pictures. we're not that sure how to do this the best way. the way we describe here gave us "rather" good results. first you take a photo of a grid (where the squares are exactly square). make an image with the grid plugin and print it for example. make sure the printer doesn't mess with the aspect ratio. for example, we got the image in radial.jpg included in the distribution. now take out your toolbox and select the "measure tool". measure a couple of squares in the middle of the image (5-10 or so) and divide with the number of squares, so you get the size of one square in pixels. the radial distorion is very small at the center so this number is probably very close to the "real" size. now start measuring the distance from the series origo to points towards the corner. write down the measured distance (in pixels) and how long it should have been (the "calculated value"). for example, if i measure from the center and 10 square up and 15 squares left and get a distance of 725 pixels. this is sqrt(10^2+15^2) squares and "should" be sqrt(10^2+15^2)*squaresize pixels. the measured value is 725 and the calculated is 740.4 (we have a squaresize of 47.3 pixels). there is an image included with the distribution that might help clarify this: radihelp.jpg If the measured distance from each point to the center is r, and the calculated value is rstar you should now solve the over determined system [r r^2] * [k1 k2]' = [r ./ rstar - 1] note that the "distance" that enfish uses is not measured in pixels, but in "real" distance. so all distances should be multiplied with lenswidth/imagewidth (where imagewidth is in the width in pixels). the advantage of this is that you don't have to recalculate these numbers if you take photos with different resolutions with the same camera or if you take portrait pictures. if you have matlab or octave (free GPL matlab-like language, available from http://www.octave.org/ or maybe it comes with your operating environment) we have included a file that helps you calculate these numbers, just run "matlab radi.m" (or "octave radi.m"). this program asks you for the lens width, image width and five series of data (the calculated and one for each corner) (and assumes that the calculated distance is equal for all four series). the input should be given in pixels in matlab-style row vectors. octave's input function doesn't seem to handle multilined input, so if you have the values 1, 3, 5, 7 and 9 you should type [1 3 5 7 9]' (including the ending '). the output is the two constants (the first value is k1 and the second k2). the file radi.example gives an example how we calculated the values for one of the cameras we've used. to make things even more interesting the radial distortion center is often not exactly in the center of the image, if there is a visible effect of this, measure from what you think is the center of the radial distortion. there should probably be entries for this in the dialog. next version. now try using the enfish plugin with your k-values. unset the "compensate for cylider map" so the image is just compensated for radial distortion. all the lines should now be fairly straight. as with everything else related to this, don't expect perfect results. we're using a second order polynom to approximate the distortion, and .. other stuff.. but.. anyways.. :) if the lines still bends out from the center (like they did from the beginning) you can increase the constants, and vice versa. all this is as you can guess (or know) not that fun to do. so if you do get some decent values for your camera, please send them to us and maybe someone else doesn't have to do the same work again. if you feel like you don't understand any of this radial distortion thingie and can't find anyone to help you, just enter zeros. the result will probably not be that good though. run the plugins --------------- the software is split into two gimp plugins. these have been tested with gimp 1.2.0 under solaris 2.6, let us know if you have any problems with some other platform/version. lineup (shows up under /Filters/Misc/Lineup) takes a bunch of pictures and lines up in one big image. when it runs it will ask you for a file containing the filenames of the files to line up (_not_ the files themselves). one per line, lines starting with # and blank lines are ignored. for example, if you have all the images in the current directory (and no other images) you can probably do "ls *.jpg > line.txt" or "ls -r *.jpg > line.txt" (if they're named sanely) and select the file "line.txt". the resulting image can be quite large and use up alot of memory, especially before you start cropping unnecessary parts. use a computer with a lot of RAM and be _sure to give gimp enough tile cache_! for example the mit-roof image was originally 22000 pixels wide (before cropping), and gimp took about 800MB RAM (15 images, each 2048x1536). when you've got them all lined up it is time to transform them so they match each other, the "most important" step. enfish is the plugin that does this (available under /Filters/Map/Enfish). when enfish starts it wants several "magic" numbers. fill in these numbers (as described above). there are three options: * all layers if this is set the plugin maps all the layers except the background, it this is not set the plugin only transforms the current layer. if there is only one layer, it is mapped no matter what. * compensate for cylinder mapping if this is set the plugin will map the image on a virtual cylinder, and fix the perspective. * compensate for radial distortion if this is set the plugin will compensate for the radial distortion caused by the camera. after this is done the images will be "bent" and (mostly :) ) match each other. move, crop and adjust --------------- we usually do one layer att the time. make only the current layer and the layer below visible. select the layer, lower its opacity to ~50% and move it with the mouse or the arrow keys so it matches the layer below. when moving the layers around, be sure to concentrate on the "important" areas: sharp edges and other things that the eye sees immediately. when they match, place a guide where you want to cut and then use the crop tool to kill the overlapping parts. you probably want to put the guide as close to the middle of the image as possible to minimize distortion. the images will probably have different characteristics. adjust these (position/brightness/contrast/colors/rotation/scale) with various tools (transform tool and stuff under /Image/Color). the tranformation tool may come in handy. if you have problems with fine details such as trees moving the clone tool is very good, use a "scattered" brush such as "confetti". then flatten the image and maybe do some final adjustments. some things are best to adjust before flattening (brightness, color matching) and some after (hiding the edges with the clone tool). why don't my pictures match perfectly? ---------------------------------------- so your pictures don't match perfectly? is the edge noticeable? don't worry, so are ours. but you should be able to get as good results as our examples without too much trouble. our examples are manually adjusted as described in step 5. just after enfish, when we viewed the overlapping area (with the upper layer having 50% opacity) we got the pictures to not miss by more than say 3 pixels with 1500x2000 images, just so you know what to aim at. so why don't they match? well here are some sources of error. * you didn't hold the camera straight or you moved it when you took the pictures, try using a tripod, you can also first just compensate for radial distortion, rotate/tilt/share/etc the image and then compensate for just cylinder mapping. * the camera lens is not perfect, the cameras we have used all have small (but noticeable) defects * some of the calculated numbers aren't as good as they could be. the radial distortion of the camera lens can be tricky to get right. try to get better values. * your pixels aren't exactly square (ccd camera) which we assume. this should probably go under "bugs". perhaps we'll fix this in a future release. * other distortions caused by the camera that we don't compensate for (what you don't know can't hurt you...) * focus. we you rotate the camera, the focus will probably change. when then focus changes the zoom changes and the pictures will have different sizes/lens widths. * things moved. people, cars, water, trees. try to avoid putting the cuts through these things, or use the clone tool and copy from the original image. * we've got something wrong.. basically we sat down, guessed how things were, tried it, got it wrong. repeat. once in a while we did do some thinking but not as much as we should have. * bug. we got it right but wrote it wrong. not that unlikely either :) and probably a couple of thousand more that we didn't think of. last words ---------- if you produce some nice panorama images with these tools, please share them with us if you want to. if you find any bugs or have any other tips or things we've done wrong, please let us know! mail goes to phfluuh@acc.umu.se enjoy -- Andreas Öman magnus janlert Tomas Ögren