Вы находитесь на странице: 1из 8


IrfanView version 1. Introduction As suggested by its name, the program was originally designed to provide increased functionality for the Samyang 8 mm f/3.5 "diagonal fisheye" lens. Its primary function is the remapping of fisheye images into panoramas with cylindrical perspective - like those produced by the somewhat exotic "swing lens" panorama cameras. You are given the choice between 3 different cylindrical projections. Section 4 describes this in detail. Also, you can instruct the program to produce images with rectilinear or "academic" perspective. The program will use the excellent (and free) little image processor IrfanView for file format conversion and image display. If IrfanView is not found on your computer, the Samyang program will work with BMP files only. IrfanView can be configured to use the Samyang program as external editor. This means that you can order fisheye conversion directly from IrfanView. This is explained in Section 6. The program needs the complete original image. Do not crop or distort the image in any way before ordering fisheye conversion. The Samyang program will do batch processing but this will require the user do do some extra work. If you are using the Samyang 8 mm lens, you can safely skip the last sections (7-9). These sections were added to assist users trying to make the program work with other fisheye lenses. Section 5 provides some extra information for theoretically interested users. The Samyang program is written for the Free Pascal compiler and will work on all 32 or 64 bit Windows and Linux machines. The present version is designed for images not larger than 12 megapixels but is easily modified to support larger image files. 2. Starting the program All Windows versions, including Windows 7, will allow the user to issue commands. In the following command descriptions, it is assumed that commands are simply typed in a DOS window or in the command box provided by some of the more advanced file managers. IrfanView allows the user to define up to 3 different commands that can be sent to an external editor such as the Samyang program. This is explained in Section 6. A command consists of a program name, usually followed by a number of parameters that will tell the program what to do. Assuming that DSC_1234.jpg is the name of a JPG image file to be processed, this is the simplest command that will make the program work: samyang DSC_1234.jpg The program will create a new JPG file with a cylindric panorama image in the source directory. In this case, its name will become CY_DSC_1234.jpg. If a file with this somewhat special name already exists, the program will overwrite it without warning. During execution, the program will use a text window to inform the user about what is going on. Note that path information about the Samyang.exe file as well as the image file may be required in commands. There is a simple way to handle that: start the Samyang program from IrfanView! To perform batch processing, you must have a simple text file where the names of your input files are listed - one per line. Lines (file names) longer than 64 characters are not allowed in list files. Assuming that the name of this file is myfilelist.txt, you can use the command:

samyang @myfilelist.txt The character @ specifies that the rest of the first parameter string is a file list name. If you have a clever way to execute the old DOS command dir >dirlist.txt in your image directory you can simply use the resulting dirlist.txt as your file list. The Samyang program will automatically edit the directory list file and extract the image file names. (Remember to add the @ character to the directory list file name in the command line). A number of other parameters can be added after the file name in the command line. Parameters must be separated by at least one space. Important: all file names and parameters containing spaces must be surrounded by double quotes like here: "My best photo.jpg". The program will always create an output image with the same number of horizontal and vertical pixels as the input image. When creating a cylindrical panorama, the program will need to read some pixels which are located outside the original image borders. Since such pixels don't exist, some pixels in the corners of the output image will become undefined. The program will paint them white. If you have ordered the program to rotate the image (see Section 3) two of the white corners will grow bigger while the other two will get smaller. This is not a real problem - working with a cylindrical panorama, you will usually want to crop the top and bottom away. The general image processing rule applies: your picture may need sharpening but sharpening must be the very last operation after all other image transformations are done. 3. Program control with parameters The command line may contain one or several parameters after the input file name. They are used to get more detailed control over program operations. Usually, you should keep your camera horizontal when shooting panoramas. It is not too difficult to keep the optical axis of the lens horizontal if you pick a distant aiming point at the same height as the camera. Because the viewfinder gives you a fisheye view of the world, it can, however, be more difficult to get the vertical lines vertical. Since this can be quite important for cylindrical panoramas, the Samyang program offers a simple way to correct the problem during the image conversion. Parameters starting with + or - are rotate commands. The plus sign will give clockwise rotation and the minus sign will give counterclockwise rotation by the number of degrees specified. An example: samyang DSC_1234.jpg +2.5 In this case, the resulting panorama will be rotated clockwise by 2.5 degrees. The Samyang 8 mm lens is available for several camera models. To use this program, you must know the width of your camera's image sensor. If it is not 23.6 mm (the usual value for Nikon DX cameras), you must inform the program about it. I believe that this command will work for a Canon sensor with crop factor 1.6: samyang DSC_1234.jpg /w22.3 The /w parameter tells the program to forget its default sensor width and use another value, in this case 22.3 mm. If you want a rectilinear wide angle image, the program will make one. The quality will not be quite perfect for the simple reason that a fisheye will produce relatively few pixels in regions far from the image center while you actually need a lot of pixels in these places to make a rectilinear image look sharp. To create an image, apparently shot with a 12 mm rectilinear lens, you can use the command: samyang DSC_1234.jpg /f12

This will create a new file named RC_DSC_1234.jpg. The /f parameter instructs the program to switch from cylindrical to rectilinear mode and read the simulated focal length, in this case 12 mm. If the parameter is just /f (with no numerical value attatched), the program will assume that you want to use the actual focal length of the fisheye lens. All the other parameters described in this section will also work during rectilinear operations. You may want the program to save your panorama in the directory C:\Photos\Panoramas which is not the source directory. By adding a redirect parameter to the command line, you can specify an alternative target directory: samyang DSC_1234.jpg //C:\Photos\Panoramas The program will now create the file C:\Photos\Panoramas\CY_DSC_1234.jpg. The two slashes // orders the program to redirect the output. The target directory must exist before you try this. When the job is done, the program will normally wait for the user to hit the Enter key before terminating. If you want the program to terminate immediately after completion, add the "no wait" parameter /nw to the command line. When the program is not in batch mode, it will accept the parameter /show . This parameter will cause the resulting image file to be opened by IrfanView after conversion. You can see the new image immediately and work with it. The /nw parameter is not needed if you are using /show. In some cases, it will be convenient if the program asks the user to specify the required conversion type after it has been started. The parameter /ask will acomplish that. The program will recognize two additional parameters, /mc and /eq . The are used for cylindrical projection control as described in section 4. 4. Cylindrical projections The cylindrical panorama was introduced in photography around the year 1900. Back then, it was done with a clever camera design where a lens swinging around a vertical axis made the exposure on a cylindrical film sheet through a narrow vertical slit. You can still buy such cameras. Today, a computer program can create a cylindrical panorama from a digital photo made with a fisheye lens if the program knows the lens mapping function. To describe a cylindrical projection we use two functions. Two angles, u and w are required: u w is the angle between the horizontal plane and the line-of-sight to a distant object point is the angle between the lens axis and projection of the line-of-sight on the horizontal plane

If we use the well known XY coordinate system in the image plane with the image center at (0,0), the most common projection is defined by: x=aw y = a tan(u) Normal cylindrical projection

Here, the length a is just some scaling factor which determines the size of the final image. You may see this projection as a weird mixture: an equidistant mapping function in the horizontal and a rectilinear mapping function in the vertical direction. (Section 5 describes mapping functions). However, there are other cylindrical projections where the vertical mapping is handled differently. The Samyang program can use two other projections where the x-dependence is the same as above while the y-dependence is defined by: y = a arctanh(sin(u)) y=au Mercator's projection and Equirectangular projection

For small values of the angle u , the three projections look the same for all practical purposes. There are, however, considerable differences at larger angles. The normal cylindrical projection will inflate distances at larger angles where it will neither conserve size nor shapes. Mercator's projection is the only cylindrical projection that will conserve shapes and angles locally. This was discovered by the Flemish cartographer Gerardus Mercator in 1569. It will not conserve size but at large angles, it will not exaggerate lengths as much as than the normal projection. The equirectangular projection will conserve size for all angles but not shapes. If you compare pictures made with the three projections, you will see that Mercator's projection acts like a compromise between the two other projections. The normal projection emulates the swing lens camera which is why this subject caught the programmer's interest in the first place. The Samyang program will use the normal projection as its default cylindrical mode but it will accept two parameters, /mc which orders Mercator and /eq which orders equirectangular mode. If you order the program to convert the file DSC_1234.jpg with one of these two parameters in the command line, the output file will get the name MC_DSC_1234.jpg or EQ_DSC_1234.jpg. Obviously, it makes no sense to use more than one of the parameters /mc , /eq , /f or /ask in the same command. 5. Mapping functions A lens mapping function describes how a lens will warp your camera's view of the world. A precise description of the different types will require a bit of simple math. We shall need 3 geometrical variables, f, v and r: f v r is the focal length of the lens is the angle between the lens axis and the line-of-sight to a distant object point is the distance between the image center and the corresponding image point

A perfect standard lens for normal photography should have this mapping function: r = f tan(v) rectilinear or "academic perspective

This function will go towards infinity when the angle v approaches pi/2 radians (90 degrees). Fisheye mapping functions are mathematically well behaved at large angles. The idealized mapping functions for the 4 main types are: r = f sin(v) r = 2 f sin(v/2) r=fv r = 2 f tan(v/2) orthographic equisolid angle equidistant stereographic

Orthographic lenses are generally useless for photography because they will brutally compress the outer regions of the image. Equisolid angle lenses are better. They have an interesting quality: the size of any area element in the image plane will be proportional to the size of the corresponding solid angle element in the outer world. You can take a shot of the sky and determine the cloud percentage by counting pixels. An equidistant lens will allow you to measure certain angles directly on a photo. The stereographic lens is the best choice for general use where you don't need the special properties offered by the other types. Conversion to other projections where you need a reasonable number of pixels to define the outer regions of the image will work best with stereographic lenses.

The following graph shows the theoretical fisheye mapping functions as calculated from the above expressions. For comparison, the graph also shows experimental data for the Samyang 8 mm lens:

The Samyang program has been calibrated to use the lens mapping function for the Samyang 8 mm lens. Its actual focal length is very close to 8.5 mm and the mapping function seems to be a compromise between the equidistant and the stereographic type. It is possible to calibrate the program for other fish eye lenses. For determination of a lens mapping function, special test shots are required. Section 7 is dealing with this. 6. Using the Samyang program as external editor for IrfanView The location of the Samyang.exe program folder must be known. In special cases where the file Samyang.ini is required for program operation (see Section 7) this file must be located in the same folder as the Samyang.exe program. Now, start IrfanView and open a fisheye image file which is to be converted by the Samyang program. On the keyboard, press P . A window labeled Properties/Settings will appear. In its little menu, select Miscellaneous. In the right side of the window, you may now define 3 external editors (or, as shown in this example, the same external editor with 3 different commands). Assuming that the Samyang program is located in the folder c:\Util\ , we can define:
C:\Util\Samyang.exe ""%1" /show" C:\Util\Samyang.exe ""%1" /mc /show" C:\Util\Samyang.exe ""%1" /ask /show"

The Browse buttons next to the 3 command boxes can be used if you need to search for the program or if you don't want to type too much. The symbol %1 shows where IrfanView must insert the image file name in the command that will be sent to the Samyang program. The command parameters /show , /mc and /ask are described in sections 3 and 4. Other legal parameters such as /f and /cc are acceptable too.

Please note the use of quotation marks "". They are needed by IrfanView for correct interpretation. After checking that the commands have been properly entered, click the OK button. When command setup is done, you can easily order the Samyang program to process any picture that you have opened with IrfanView. You may use the keyboard or the IrfanView File menu. If you hit one of the keys 1, 2 or 3 while pressing the Shift key, one of the commands defined above will be executed. As an example, 2 will create a cylindrical panorama using the Mercator projection. The /show parameter will ensure that the resulting panorama image file opens in a new IrfanView window where you can work with it as you please. If you don't want to remember the meaning of the 3 numbers, just use the IrfanView File menu and select Open with external editor. The available options will be displayed and you click on the one that you want. Actually, only one of the above commands is really needed to perform normal program functions. In this example, number 3 with the /ask parameter gives the user a completely free choice after the Samyang program has started. 7. Finding a mapping function If a file named Samyang.ini exists in the same directory as the program file Samyang.exe, the program will try to read certain important data from this file. The file is a simple text file like this:
#Nikon D300 sensor data: wsensor: 23.6 #Lens data: focallength: 8.53 formfactor: 1.097 tweak2: -5.0 tweak4: 0 #redfactor: 1.0000 #bluefactor: 1.0000 lensname: Samyang 8 mm fisheye #IrfanView location: #irfanview: C:\Program Files (x86)\IrfanView\i_view32.exe #end

Usually, the file contains parameters which define a mapping function that the program must use instead of the built-in function. Also, the file may specify a new value for the sensor width so you can avoid typing a /w parameter in the command line. To determine the mapping function for a fisheye lens, you will need to work with this data file. The program will understand several keywords which define numerical values. Important examples are wsensor: , focallength: , formfactor: , tweak2: and tweak4: . Keywords must have a colon as their last character and must start in the first column on a line. Lines not starting with a legal keyword are neglected by the program and can be used for comments (as shown in the example). The last line must be a comment or an empty line. Keywords can not contain space characters. Two additional keywords, redfactor: and bluefactor: can define parameters used for chromatic aberration (CA) correction. This function is described in Section 8. In the example above, they are hidden inside comments and therefore not active. A special keyword, lensname: allows the user to define a name that will be displayed when the program starts. There must be a space character between the colon and the name. It is necessary for the Samyang program to find IrfanView. If it has been installed in some unusual place, the irfanview: parameter must be used to provide this information. If a key value is not defined in the data file, the program will use its built-in value. In this example, the first numerical value, wsensor , is the camera's sensor width. It is followed by a set of 4 parameters which define the mapping function to be used. The problem is how to find them

for your own lens. You will need two (very different) test photos to do this. The focallength is the f-value from section 5. Lens manufacturers will frequently specify a nice integer value which is not really accurate. Samyang's 8 mm lens has f = 8,53 mm. Actually, you must measure your focal length to be sure. For this, you need the first test shot: As target, attatch a sheet of document paper to the wall in a reasonably large room at camera height. Let a be the width of the target. The camera is placed at a distance L from the target. L must be much larger than a. Now, aim at the target center and take a picture. Use a suitable image processor to find p which is the number of pixels that corresponds to the target width in the image. With N as the total number of horizontal pixels on the sensor, the focal length can now be calculated as: focallength = (L/a) (p/N) wsensor What you really need here is an accurate value for the ratio between focallength and wsensor. This means that the quantity (L/a) (p/N) is the important result here. (Section 9 will make this clearer). The next important quantity is formfactor. This dimensionless constant determines the overall shape of the mapping function (see Section 5). If the lens has a truly equidistant mapping function then, by definition, formfactor = 1. An equisolid angle lens has formfactor = 0.9003. A stereographic lens has formfactor = 1.2732. For most fisheyes, a good first guess would be a value just under 0.9. A fine tuning of the formfactor value is always required. For this, you need the second test shot. A good target is a large wall covered with tiles. The spaces between tiles must define clearly visible and absolutely straight vertical lines. The camera must be positioned such that its fisheye will see tiles everywhere from the middle of the image and all the way out to the fisheye's angle-ofview limit. One of the vertical lines should be close to the edge of the image. Do a number of shots while keeping the camera as horizontal as possible and select the best shot as your reference picture. Of course, your target can be any structure which contains a suitable number of long and perfectly straight vertical lines. Also, you can use a tile covered floor. In this case, rotate the camera 90 degrees and rotate the image back to landscape orientation before proceeding. Now, create a Samyang.ini file with the known values of wsensor, focallength and your best guess for the formfactor value. Start by setting tweak2 and tweak4 to zero. Then make a cylindrical panorama from your test shot. Usually, this must be repeated several times with slightly different formfactor values until you have found he best value for formfactor. By then, the vertical lines should be straight near the edges of the image. If this is not quite possible you can try some nonzero values for tweak4. Image correction close to the center is not a problem. If vertical lines in the middle zone between center and edge are bending slightly, it may be corrected by a non-zero tweak2 value. Both tweak percentages can be given positive as well as positive values. However, their absolute values should not exceed 10% by by much. If your demands for quality are really high, you may need to spend some time with experiments here. The system with three variable parameters is quite flexible. A good solution will always exist if you have managed to find the right value for the ratio between focallenght and wsensor. 8. Correcting chromatic aberration (CA) If you are using a camera that does automatic CA correction for your lens, you should forget about this function. If you need CA correction, the program can do it during image conversion. However, this requires you to determine two CA correction parameters for the lens. They are called redfactor and bluefactor and both must be defined in the Samyang.ini file (see Section 7). The program assumes that the red, green and blue images might be created with slightly different focal lengths. As a result, the three images can have slightly different sizes. The effect of this will, of course, be most visible close to the image borders. The program will use the green image as its reference image. The parameter redfactor is the ratio between the (linear) size of the red image and

size of the green image. The definition of bluefactor is similar. There is no need to specify a greenfactor since, by definition, it is always 1. If these parameters are not defined in the Samyang.ini file, they are automatically set to 1, meaning that no CA correction is done. A suitable target for a test photo could be a vertical white strip on a black background, placed close to one side of the image field. If the strip in the uncorrected test photo shows a red fringe on the outside, it means that redfactor should be slightly larger than 1. A red fringe on the inside indicates that redfactor should be slightly less than 1. Similar rules apply for bluefactor. A green fringe on the outside will mean that both redfactor and bluefactor need to be decreased a bit. (Remember that greenfactor is always normalized to 1). It is possible to use the program for color correction without doing cylindrical or rectilinear conversions at the same time. This is done by using the color correction parameter /cc in the command line. This parameter is only accepted by the program if both redfactor and bluefactor are defined in the data file. If you apply color correction only to the image DSC_1234.jpg in this way, the new file will get the name CC_ DSC_1234.jpg. 9. Sensor width and length units You may own a fine digital camera and a fine fisheye adapter without knowing anything about the camera's sensor width. You can still use the Samyang program if you create a Samyang.ini file by the procedures described in section 7. The trick is based on the fact that the program basically works with angles not with lengths. The program finds angles by comparing lengths but is does not matter if these lengths are measured in millimeters, inches or nautical miles. The only requirement is that all lengths are measured in the same units. The program's built-in lens and sensor data are measured in millimeters. Therefore, you must use millimeters in /w and /f parameters if you run the program using the built-in data. However, you can use any length unit that you want in the Samyang.ini file if you make sure the two lengths (wsensor and focallength) are measured in the same unit. This allows you to chose a new length unit that is based on the (unknown) sensor width. Just remember that if you use the /f parameter in the command line, the simulated focal length must now be provided in the length unit that you used in the data file. The parameters formfactor, tweak2 and tweak4 are completely independent of your length units. If you grew up with the classic 24 36 mm cameras you may find it convenient to set the wsensor value to 36. This defines 1/36 of the sensor width as the program's new length unit. No problem. And there is a slight advantage: the command line parameter /f18 will now give the same angle of view as an 18 mm wide angle lens will give you on a 24 36 mm camera (in this case 90 degrees). [m.hoffmann.j@gmail.com]