fotoxx quick guide

File menu	File Management
Index (thumbnails)	Show thumbnail images - files in the current directory (more).
Open RAW File	Open a RAW file from a digital camera and convert to tiff (more).
Open Image File	File open dialog - open an image file to view or edit.
Save Image File	File save dialog - save the current (edited) image to a file (more).
Print Image File	Arrange images and text in a layout for printing (more).
Trash Image File	Move an image file into the fotoxx trash bin (more).
Rename Image File	Rename (series of) image files, add sequence numbers (more).
Quit fotoxx	Exit from fotoxx.
Tools menu	Utilities and setup functions.
Check Monitor	Display a color palette for tuning your monitor (more).
Synch Tags and Thumbs	Re-index tags and thumbnails after file rearrangements (more).
Brightness Graph	Show brightness distribution graph of current image (more).
Clone fotoxx	Open a new window (e.g. to compare two images) (more).
Slide Show	Show images full screen (no menu or toolbar) (more).
Show RGB	Show RGB values at position of mouse click (more).
Lens Parameters	Edit parameters for your cameras and lenses (more).
Language	Change the GUI language
Tags menu	Manage tags (keywords) / star ratings / dates  (more)
Edit Tags	Add or change image date / stars rating / tags (keywords) (more).
Search Tags	Find images with desired tags / star ratings / dates (more).
View EXIF Data	View image EXIF data (date, exposure data, tags) (more).
Edit menu	These functions modify image files  (more).
Select Area	Outline an area for subsequent editing using the mouse (more).
Clear Select Area	Remove area - subsequent edits apply to the entire image.
Flatten Brightness	Flatten the brightness distribution to enhance detail (more).
Tune Image	Edit brightness distribution, color balance, saturation (more).
Color Depth	Reduce color depth (number of colors displayed) (more).
Remove Red Eyes	Click on a red-eye to remove it (more).
Blur Image	Blur an image (smoothen skin) (more).
Sharpen Image	Sharpen a blurred image (more).
Reduce Noise	Reduce noise (speckles) in low-light images (more).
Trim Image	Cut out a rectangular portion of an image (more).
Resize Image	Scale an image up or down (more).
Rotate Image	Rotate an image (level a tilted image or turn in 90° steps) (more).
Unbend Image	Fix perspective problems (more).
Warp Area	Distort image within a selected area by pulling with the mouse (more).
Warp Image	Distort entire image by pulling with the mouse (more).
Make HDR Image	HDR = high dynamic range (more).
Panorama	Combine overlapping images to make an ultra-wide image (more).
Help menu	User guide, README, change log  (more).
Toolbar buttons
Index	Show thumbnail images - files in the current directory (more).
Open	File open dialog - open an image file to view or edit.
Prev	Go to previous image in the current directory.
Next	Go to the next image in the current directory.
Save	File save dialog - save the current (edited) image to a file (more).
Undo	Undo (reverse) the results of the previous edit function.
Redo	Redo the previous undo. Undo/redo depth is 50 edits.
Zoom+	Magnify the image. A left mouse click also magnifies.
Zoom-	Reduce the image. A right mouse click also reduces.
Trash	Move an image file into the fotoxx trash bin (more).
Quit	Exit from fotoxx.

Keyboard Shortcuts

main window
left / right arrow keys	previous / next image
plus(+) / minus(-)  keys	zoom bigger / smaller
Z  key	zoom to 100% / fit to window
R / L  keys	rotate 90° right / left
T or X  key	open thumbnail index window
Delete key	move image to fotoxx trash
Escape key	Exit slide show mode
thumbnail window
up / down arrow keys	move up / down by one row of thumbnails
left / right arrow keys	move to previous / next page of thumbnails
plus(+) / minus(-)  keys	bigger / smaller thumbnail image size
Escape key	close thumbnail window

License and Warranty
fotoxx is licensed under the GNU General Public License V2 (Free Software Foundation).
fotoxx is not warranted for any purpose, but if you find a bug, I will try to fix it.

Origin and Contact
fotoxx originates from the author's web site: http://kornelix.squarespace.com/fotoxx
Other web sites may offer it for download. Modifications may have been made.
If you have questions, suggestions, or a bug to report, contact kornelix@yahoo.de

Translations
See the menu  Help > Translations  or the text file TRANSLATIONS for guidance on how to modify an existing translation or make a new one.

Some additional technical notes can be found here.


Navigation

Press the [index] toolbar button to get a window of thumbnails showing image files in the current image directory. Use this thumbnail window to scroll around the directory and select files by clicking thumbnails. The buttons at the top allow scrolling forward or back by rows or pages. Use the file and folder buttons to navigate elsewhere if wanted. Make the window bigger to show more thumbnails, or use the [bigger] and [smaller] buttons to increase or decrease the thumbnail size and change the number of visible thumbnails accordingly. Pressing the [index] button in the fotoxx main window will bring the index window forward with the current file's thumbnail in the upper left corner. Clicking on a thumbnail will bring the fotoxx main window forward with the selected image.

Open RAW File

This is a dialog for opening a RAW file from a digital camera. The selected file is converted to tiff-48 format (16 bits per RGB color), using the program "ufraw". This may need 20 seconds or more to complete. When the converted image appears, you can proceed to edit or save the image in a normal jpeg or tiff file.

Save Image File

You have a choice of formats for saving an edited image file. "jpeg" is normally the best option, since the saved files are compressed to reduce space. You can choose quality "good" (highly compressed, with some loss of detail), "better" (less compression, negligible loss of detail), or "best" (least compression, uncompromising quality). Files may also be saved in 24 or 48 bits per pixel tiff format. The 48 bit tiff format (16 bits per color) only makes sense for files converted from a RAW format supporting more than 8 bits per color. Camera RAW files are typically 12 bits per color.
 
File sizes for a 10 megapixel file are roughly as follows:

tiff-48	tiff-24	jpeg-best	jpeg-better	jpeg-good
58 MB	20 MB	8 MB	1.2 MB	0.7 MB

 
Print Image File

The print menu starts the program printoxx (if installed) with the current image loaded into the printoxx layout window. Printoxx allows you to add images and text to the layout window, change their size, move them around, and print or save the final layout. Printox is available at http://kornelix.squarespace.com/printoxx.

Trash Image File

There is no standard location for the trash folder in Linux, and in practice it varies. fotoxx puts discarded images into a desktop folder named "fotoxx-trash". You can delete it or move it to your distro-specific trash folder.

Rename Image File(s)

This function can help automate the process of renaming a series of files that have the same root name (e.g. an event or place name) and a sequence number. It is good for renaming a series of files from a digital camera. Open the first file in the series, input a new name, and press the [rename] button. The next file is then opened. You can use the same name again by pressing the [previous] button and then add a suffix or sequence number. If you are using sequence numbers, press the [ +1 ] button after the [previous] button to get the next sequence number added to the name.

Check Monitor

Eight color bands are written across the screen with brightness from zero (black) to 100%. You can use this to adjust the brightness and gamma of your monitor. The left end of each stripe should be as black as possible, but you should start to see some color within a few mm from the left edge. If the completely black portion is wider than this, adjust the monitor. There are 255 brightness steps from black to 100%. The steps are too small to distinguish with the eye. This evaluation should be done in a darkened room (no external light falling on the monitor screen).

Synch Tags and Thumbs

You need to do this if you move or reorganize image files and directories. Nothing is lost, but tag searching will not work, and thumbnail index windows will be slow. The synch function regenerates the tags index file and the thumbnail images that make the thumbnail windows fast. A dialog will ask for the topmost directory of your image files. That directory and any subdirectories containing images will be processed. The indexing speed is 100-600 images per minute, depending on CPU and disk speed.

Brightness Graph

This function opens a small window that shows a brightness distribution graph of the current image in the main window. This graph updates immediately as edit functions change the brightness.

Clone fotoxx

Start a new instance of fotoxx in a new window, starting with the current image file. This is useful to compare images or to work with more than one image at a time.

Slide Show

The image window is enlarged to the whole desktop, and the menu and toolbar are removed. Use the keyboard for navigation (more). Use the escape key to get out of slide show mode.

Show RGB

This function changes the mouse mode. When a point on the image is left-mouse clicked, the RGB values are shown in the status bar at the bottom. The values have the format xxx.ddd, where xxx is the upper 8 bits of the color value, with range 0-255, and .ddd is the lower 8 bits, with range .000 to .999. The lower 8 bits are zero unless the image has been edited. Only changes in brightness affect the lower 8 bits, and this data is preserved only if the image is saved in 48 bit tiff format. A right-mouse click restores the normal mouse mode (click to zoom).

Lens Parameters

This is a dialog for setting and saving the two lens parameters, lens_mm and lens_bow, which must be set for each camera/lens used for panoramas. These parameters govern how fotoxx "bends" the two panorama input images so that they can fit together accurately. Enter a name for the lens/camera and the two parameters. Up to four lens/cameras may be entered. Lens_mm is roughly the focal length of the lens (35mm film camera equivalent), and lens_bow is a factor for the barrel/pincushion distortion. How to set these parameters is described here, but you should read the section on making panoramas first, in order to better understand the following instructions.

Setting Lens Parameters Automatically
The [search] button in the panorama pre-alignment dialog initiates an automated search for optimum lens parameters. Use a suitable image pair: the subject is 20+ meters away, the images have a low horizon difference and little relative rotation, and there is plenty of high-contrast detail in the overlap area. Input your nominal lens focal length for lens_mm. Use zero for lens_bow. After doing a decent pre-align, press the [search] button and wait a while for the results. Do this a second time and observe the changes. If the values remain consistent, you can use them for your panoramas. The search function steps through a range of values for lens_mm, lens_bow, and the image alignment offsets for x, y, and theta. It searches for the lens values that give the best alignment results for the given images. The process needs a minute or more, but you only need to do this once to characterize a given camera lens. Be sure to save the results using the lens parameters menu.

Setting Lens Parameters Manually
Make a panorama image of a brick or tile wall with about 40% image overlap. Within the panorama pre-align process, adjust lens_mm and lens_bow until the overlapping vertical and horizontal lines coincide. When making the two images, be sure to turn the camera on a vertical axis through the lens, minimizing lateral movement and rotation in other axes - otherwise the images may fit poorly and your factors may not be optimum.

Tags - General Principles

Image files can have classification tags (categories, keywords) assigned to them. These can be used to search a large image library for those images having desired tags. Typical tags: the main subject of a photo, the associated event, the location, the person(s), etc. Tags reside inside the image (in the EXIF data) and are independent of its file name or directory location. You can use file names and directory structure to make a physical organization of your images, e.g. directory names corresponding to year or location or other scheme, and file names corresponding to the main subject of the image, or simply sequence numbers (as produced by the camera). Tags can then be used to make other organizations, e.g. mark the images of one person across all years, events, locations, etc. The images having a desired tag or tags can be found quickly and displayed in a pagable window of thumbnail images, where you can further review the images and choose those for viewing, editing, or changing their tags. Images may have a date which is pulled from the image EXIF data, if present, or manually set. Images may have a "star rating" for the importance of an image. Dates and star ratings can also be used as search critera.

The package exiftool must be installed for tag editing. This program is used by fotoxx to read and write the EXIF data within image files.

Limitations and Practical Tips
The following are the default limits for tags. These are compile time constants which can be easily increased if needed, although I believe they are large enough to exceed practical limits:
    o   max. tag length: 20 characters
    o   max. tags for one image file: 200 characters
    o   max. tags for all images: 1000 unique tags with up to 9000 total characters
    o   max. tags in a search: 100 characters
The practical limit for the overall number of tags is in the range 100-200. Exceeding this range is possible but will lead to some practical problems: The window showing available tags will be large and tags will become hard to find (although ordered alphabetically), and the point and click method of adding tags will become more cumbersome. Typing the tags manually will work, but this may lead to typos and other tag redundancies. This is a bigger problem when tags are initially being defined for a library with thousands of imags, and less of a problem afterwards when new images are added in small batches. Searching tags is also more cumbersome if the window of available tags is huge. If the tags are broadly defined and fewer in number, the search results will be larger, but using the search results thumbnail window to find a smaller set of images is also quite fast. Physical file organization is also preserved in the thumbnail window (files located together in their directories will also appear together in the search results). All in all, my recommendation for the casual photographer is to use fewer and broader tag categories. Tag search speed is thousands of images per second on a modern PC with adequate memory.

Edit Tags

Open an image file and then select the edit tags menu. Existing tags are shown in "current tags". Available tags are shown in the "assigned tags" window below. One of these tags can be added by pointing and clicking with the mouse. A tag can be deleted by pointing and clicking within the current tags. Tags recently added are shown in "recently added". This is a convenience to make adding tags to a new batch of images easier, assuming that many of the same tags will be used again and again. Point and click the same way. New tags that have never been used before (and do not appear in the list) can be added by typing them in and pressing [create tag].  The date of the image, if available, is shown as "photo date". This may be entered if missing, or changed. You may enter an optional "stars" rating in the stars field. Use numeric values, e.g. 5 for a 5-star rating. The dialog remains open if you navigate to a new image, and the current tags are filled-in from that image.

Search Tags

Use the search tags menu to find images having desired tags. Available tags are shown and can be chosen with point and click. Use the radio buttons to select "match all tags" or "match any tag". Press the [search] button to perform the search. Matching images are displayed in a pagable thumbnail index window. Choose images to view or edit by clicking the thumbnails. The set of matching images will remain in effect for image navigation (the buttons [prev], [next], [next page], etc.) until you use the [file] or [folder] buttons to establish a new navigation set (all images in the same directory as the chosen file). A date range may be optionally entered, to further restrict the search to images within the date range. The format is yyyymmdd. Images are selected which have a date on or after the first date, if present, and on or before the second date, if present. Missing mmdd defaults to 0101 and missing dd defaults to 01. A pair of star ratings may be optionally entered to restrict the results to images having a star rating within the given range. A missing low value implies zero, and a missing high value means unlimited. To find all images with no tags, search with no tags, no stars, and no dates.

View EXIF Data

If the package exiftool is installed, the View EXIF menu will display EXIF data in the current image file, if available. EXIF data contains the date and time of a photo, shutter speed, focal length, pixel dimensions, etc. Most cameras store this data inside the image. If the image is edited and then saved, the EXIF data is updated and stored with the new image. NOTE THAT THE EXIFTOOL PACKAGE IS REQUIRED IF YOU WANT TO RETAIN EXIF DATA WHEN AN IMAGE IS MODIFIED AND SAVED.

General Editing Procedure

The image in the main window can be operated on with the edit menu functions. You can use these functions in any order, and the changes are accumulated for the current image and shown in the main window. The [undo] and [redo] buttons can be used to review the before/after results for the last 50 edits of the current image. These buttons do not work during an image edit function, but some of these functions have their own method to undo and redo changes during the edit. When finished with an image, use [save] to replace the original file or save to a new file.

Select Area

It is possible to modify part of an image while leaving the rest unchanged. If no image area has been selected, edit functions apply to the entire image. If an area has been selected and is still active (has not been deleted), then the following edit functions will be carried out within the selected area: all brightness and color functions, warp local, sharpen, blur, reduce noise. The warp local function works only within a selected area, and the warp global function works on the whole image. Other functions (trim, red-eye, rotate, resize, HDR, panorama, unbend) will ignore a selected area.

An area may be selected before starting an edit function, or while an edit function is active. The selected area is immediately active, and edits done on a prior area or the whole image are retained. If another edit function is started, the selected area remains active, so it is possible to carry out a series of edits on one area, or one edit function on a series of areas.

Press the [select] button to begin selecting an area. Use the mouse to outline the target area. Hold the left mouse button and drag the mouse to draw a dotted line. Release the button and press again to fix the end of the line and start a new connecting line from that point. Continue around the target area until it is surrounded with connected dotted lines (an arbitrary polygon). You can use the right mouse button to undo the last line(s). Alternatively, just click the left mouse button to define each new point of the surrounding polygon. When the polygon is nearly closed, click the [finish] button to close the last gap. The selected area is now active and subsequent edit functions will operate within the area. The [delete] button deletes the area (all edits are retained). A new area can now be started if desired. The [blend width] sliding control defines the width of blending into the surrounding image. Edits made within a selected area are blended with the surrounding image over this width. The leftmost slider position gives a hard edge (zero blending), and the rightmost position blends the changes over a width of 300 pixels. This control can be adjusted interactively while editing an area, with instant visual feedback. The select area dialog can be exited and started again later (with the [select] button). The blend width can then be revised, affecting current and future edits.

Determining which pixels are inside a selected area, and how far they are from from the nearest edge (for the blending calculation) is very processor intensive. If you have enclosed a large area using hundreds of separate lines, 10 or more seconds may be needed. This calculation is done only once, when finishing a selected area. Subsequent movements of the blend width slider are processed very fast.

The button [invert] inverts an existing selected area: the entire image is selected except for the existing selected area. Using [invert] two times returns the original selected area. Inverting a selected area can take a long time for the new calculations to complete, because there are usually many more pixels for calculating the edge distance.

Flatten Brightness

This is a fast and easy way to compensate for a common limitation in photos: there is not enough range in the brightness to show good detail in all areas. This function finds where there are too many pixels with nearly the same brightness and spreads them apart, compressing other areas to make room. Technically, the brightness distribution is made more uniform (flatter). Move the slider and watch the image, which may lag a few seconds. Some images will show good results, others not.

Tune Image

This function is used to change brightness levels, color intensity, color saturation, and color balance. The curve "brightness level" is used to adjust image brightness across the brightness spectrum from dark to bright white. Drag the line up or down with the mouse to change brightness levels. Anchor points (black dots) are added to the line wherever it is pulled, and this becomes a constraint for subsequent pulls: the line will continue to go through this point as other parts of the line are pulled. Anchor points can be dragged, or deleted by right-clicking them. The left side of the line affects the darker parts of the image, the right side the brighter parts.

The color intensity slider increases or decreases color intensity. Areas of lower brightness and higher color (RGB components unequal) are affected more. Thus color can be brightened in darker image areas where it tends to get lost. The color saturation slider increases or decreases the dominant RGB color(s) and moves the less-dominant in the opposite direction. The three color balance sliders change each RGB color level independently.

Color Depth

This function changes the normal 16 bits per RGB color (red, green, blue) to any value between 1 and 16 bits per color. At 8 bits per color, there are 16.8 million total color combinations. At 4 bits per color there are only 4096 total colors. Use 1-4 bits for an interesting "poster" effect.

Remove Red Eye

This function reduces the red-eye effect from electronic flash photos. Two methods are provided. The first is faster but will not handle difficult cases (e.g. the eyelids are just as red as the pupil, making the boundary unclear). The second method is more robust but also needs more time and care. In the red-eye dialog, you can use both methods and correct multiple red-eyes within one image.

To use the first function, left-click on a red-eye one or more times until satisfied. If a red-eye cannot be fixed correctly, right-click to un-do the change, and then use the second method.

The second method can better handle difficult cases where the red-eye is only slightly red and the color difference with the eyelids is too little for the automatic algorithm to distinguish. Place the cursor over the center of the red eye. Hold the left mouse button and drag the cursor down and to the right. A dotted circle will appear enclosing the red eye. Repeat if needed to get the red eye centered in the circle (roughly). Left-click inside the circle repeatedly while watching the red eye darken, and stop when it is dark enough. If you go too far, the eyelids may start to darken. Right-click to undo and repeat if necessary.

Blur image

This function can be used to blur or un-sharpen an image. Each pixel is mixed with neighboring pixels to reduce the differences, making edges fuzzy. Enter a value for blur radius and press [apply] to see the results. A small value mixes each pixel with its nearest neighbors and larger values mix more distant pixels. The contribution from each pixel decreases with distance, so the nearest pixels have the greatest contribution. This function is useful to smooth mottled skin tones. You can use "select area" to limit the blur to a face or part of a face.

Sharpen Image

This function sharpens a blurry image. Three methods are implemented: edge detection, unsharp mask, and Laplacian. Edge detection is a simple algorithm: find adjacent pixels with the largest brightness difference and increase the difference. This is repeated for several cycles, with the threshold for brightness difference decreased each cycle. Unsharp mask is a traditional method also found in Gimp and other tools. It is fast and effective (a technical description can be found via Google). The edge detection method gives sharper edges where the contrast is high and softer edges elsewhere, making it good for portraits (sharp eyes, smooth skin). For images that are partly sharp and partly blurred (e.g. depth of field or motion problem), the edge detection method will affect only the blurry areas, whereas unsharp mask may put "halos" around edges that are already sharp. The Laplacian method is very similar to unsharp mask, producing slightly better results in some cases and slightly worse in others. The radius value limits the distance over which pixels around an edge are changed. It should be small (1-2) for images that are slightly fuzzy and larger for poorer images. Threshold suppresses changes to low-contrast pixels: a higher values reduces the amplification of low level irregularities.

For the edge detection method, enter the following parameters:
    cycles         number of iterations
    reduce         brightness threshold reduction per cycle, 80 means 0.80
    threshold      brightness change low cutoff threshold

For the unsharp mask or Laplacian method, enter the following parameters:
    radius         distance pixels around an edge are changed
    amount         amount of correction, 100 = normal
    threshold      brightness change low cutoff threshold (unsharp mask only)

Press the button for the method selected and wait a few seconds to see the result. The default values are suggested starting points. Make changes and repeat the process until satisfied. You can go back and forth among the methods to compare which is best for a given image.

Reduce Noise

This function reduces the noise present in photos taken under poor lighting conditions (uniform surfaces appear speckled). Choose one of the three methods described below. Press the [reduce] button repeatedly while watching the image. If you go too far, sharpness and detail will be lost. The radius input determines the area around each pixel that is compared. A default radius is set when a method is selected, but other values may work better in some cases. For a large image, these algorithms may run a minute or longer. To save time, select a small area and experiment with the different methods and radius settings until you make a decision, then clear the selected area and apply the chosen method to the whole image. All of these algorithms are applied to each RGB color independently.
(1) Flatten outlyers by color: extreme pixels (outlyers) within a radius are moderated.
(2) Set median brightness by color: pixels are set to the median value of their neighbors.
(3) Top hat: detect outlyers by comparison with a band of pixels at some distance away. Distance is increased in steps from 1 pixel to radius limit.

Trim Image

The HDR and panorama functions will leave some black margins around the edges where the images did not overlap. Use the trim function to remove these areas, or any other unwanted margins. An initial dotted line rectangle is drawn, encompassing about 60% of the image. Areas outside the final rectangle will be discarded. Click anywhere to redraw the rectangle with the nearest corner at the clicked position. You can also drag any corner of the rectangle to a new position. When done, press the [trim] button in the dialog box.

Resize Image

This function allows setting a new image width and height in pixels, or as a percent of the original size. You can input the new width and height directly. Buttons are present for setting the new size to 3/4, 2/3, 1/2, 1/3, or 1/4 of the original size. Using one of these ratios will minimize loss of resolution. If the lock ratio box is checked, the original width / height ratio will be preserved, meaning that if one dimension is changed, the other dimension will be changed to match. After setting the new dimensions, use the [apply] button to perform the rescale. The window may look the same, but the image behind it is rescaled. The status bar shows the new dimensions. The file size is not updated until the modified image is saved.

Rotate Image

The rotate menu function starts a dialog to rotate the image clockwise (+) or counterclockwise (-) in steps of 0.1, 1, 10, or 90 degrees. For a tilted image, use the mouse to drag the right edge up or down until the image looks level. Use the 90 degree steps to convert an image taken in vertical format to horizontal. No resolution is lost with 90 degree rotation. For other angles, the loss of resolution varies up to about 1/2 pixel. The output image is increased to accommodate the rotated input image without size reduction - e.g. a 100 x 100 image rotated 45 degrees will be inside a new image box of 141 x 141 pixels.

Unbend Image

Panoramas of nearby subjects (typically buildings or interior rooms) may show straight lines that are curved, or buildings that are slanted. Bending of the images is necessary in the panorama process in order for the images to fit together. For remote subjects (typically landscapes) this is not noticeable. The unbend function can be used to straighten curved lines and remove the slant from verticle lines. Verticle and horizontal dotted lines are drawn over the image, showing the unbend axes. Click or drag the mouse near the end of a line to move it. Input values for horizontal and vertical unbend and watch the effect on the image. Increase or decrease the values and repeat until satisfied. Move the axes to change the centers of unbending. See also "Warp Image" for another method of correcting perspective problems.

Warp Area

This function can be used to make distortions within an image. You can select an image area and drag the mouse to stretch this area with respect to the rest of the image. The image reacts as if made of rubber. The movement is maximum at the mouse pointer and declines to zero at the edges of the selected area. Many mouse drags of different lengths and directions can be combined to achieve the desired results. The [undo] button will remove the most recent stretch (up to the last 100 can be undone). When finished, you can select another area and do some more warping, or select [done] to exit the function.

Warp Image

This function is useful to correct perspective problems (see also "Unbend"). Drag the image from any edge, using the mouse. The entire image will be pulled or pushed in the direction of the mouse, but areas near the mouse are moved more than more distant areas.

Make HDR Image (high dynamic range)

HDR combines (overlays) two images of the same subject with different exposure levels (underexposed and overexposed). The combined image has improved visibility of detail in both the darker and brighter areas, in effect using information from the brighter image for the darker areas, and from the darker image for the brighter areas. Many digital cameras do exposure bracketing: take multiple shots in quick succession with different exposure levels. You can combine two such images to make a better one. If the camera is adjusted manually between shots, take care to keep it level and aim at the same point. Some misalignment of the two images can be tolerated. If things move between the two shots (people, windblown trees), fuzziness and ghosting cannot be avoided.

Open the 1st image file with the [open] button, then select the HDR menu function. A file open dialog is started to select the 2nd image file. The two images are aligned and combined automatically. When done, the combined image is shown, along with a dialog for manual fine adjustment. The contribution from each image can be adjusted independently for different brightness levels in the combined image. The initial ramp causes the darkest areas to be taken mostly from the brighter image, and the brightest areas mostly from the darker image. Use the mouse to pull the curve and change the contributions from the two input images. This will also add an anchor point that will not move when other parts of the curve are moved. An anchor point can be dragged or deleted with a right-click.

Panorama

This function stitches two images together to make a wide image or panorama. The images must overlap by 10% or more, so that the program can find where they coincide and put them together.

Open the left image file first. Select the panorama menu function. A file open dialog is started to select the right image file. The two images are initially joined with a small transparent overlap. A dialog pops up asking you to move the right image into rough alignment with the left image. Do this with the mouse, dragging the right image leftwards until it is within a few pixels of the best match with the left image. Rotate the right image if needed, by dragging the right edge up or down.

The images should be correctly curved and fit together well. If they do not fit, you need to set the lens parameters as described under "Lens Parameters". You can adjust these parameters within the dialog until the images fit reasonably well, and this may be good enough for most panorama jobs.

Press [proceed] when rough alignment is finished, and the program will do fine alignment and join the images. Internally, the images are shifted and rotated and the degree of match is evaluated. This is done with increasing image sizes until the best match is found within a fraction of a pixel. The process needs 30 seconds to 2 minutes, depending on CPU speed and image size.

When fine alignment is complete, the combined image is displayed. A dialog pops up for fine adjustment of brightness and color match. You may see a sharp border because the two images do not have the same brightness and color balance. The [auto] button can be used to perform an automatic color match, which is usually the best starting point. This button toggles the auto color match on and off. The other controls allow you to make additional changes to better match the two images. Changes are made to both images, in opposite directions. Change the values for brightness and color and press the [apply] button to see the results. The "blend width" input governs how the two images are blended together: the color balance is gradually shifted over this many pixels, to mask imbalances that cannot be fully corrected. The default is 1 pixel, which makes any brightness or color differences look obvious. When done, you can use the unbend, global warp, rotate, trim, and other functions for final adjustments.

Panoramas of three or more images can be done as follows: After joining the first two images, Start the panorama function again to open and join a 3rd image. In this manner you can string together several images. New images are always joined on the right.

Verticle Panoramas
Rotate the images 90° to make them match as a left-right pair. After doing the panorama, rotate them back.

Help Menu

About
This displays a short message about the fotoxx version number, license, home page, and credits.

User Guide
The user guide (this document) is displayed (created using the WYSIWYG HTML editor SeaMonkey).

README
Displays the README file distributed with fotoxx, which may contain new information about installation or dependencies. When you install a new release of fotoxx, you should look at README and the Change Log to check if there is anything special you need to do.

Change Log
Displays the changelog file distributed with fotoxx, containing details about functional changes, additions, or bug fixes for the current and previous releases.

Translate
Displays a short text file which explains how to make a new translation or change an existing one. This involves editing a text file that contains English text messages with corresponding translations.


Technical Notes

Fotoxx version 6
This release incorporated some major changes. The FreeImage library is used for image file input and output, in place of the GDK Pixbuf library. This was done to allow images with 48 bits per pixel to be read and saved (GDK works in 24 bits). All edit functions now use 48 bits per pixel. Digital camera RAW files can be read and converted to other formats, including 48 bit tiff ('ufraw' is used for this). Reading and writing EXIF data now uses 'exiftool' instead of 'exiv2'. Some edit functions are slightly slower because 48 bit images are twice as large in memory as 24 bit images. Others have been made faster by greater use of parallel threads (on computers having multiple cores or hyperthreaded CPUs). The use of GDK and GTK functions in threads has been eliminated, which eliminates a major source of bugs. The most interactive edit functions (flatten, tune, color depth, rotate, unbend, global warp) use the image displayed in the window as a 'preview' image: interactive changes are made to this image, which is usually much smaller than the main image (e.g. 1-2 megapixels instead of 10 megapixels). This makes the editing and visual feedback work faster. The main image is not updated until the [apply] or [done] button in the edit dialog is pressed. If, before editing, the fotoxx window is made smaller than full-screen, these functions work faster.

Command Line Options
The following command line options can be used in launchers to simplify startup:
   fotoxx /.../imagefile.jpg         #  initial image directory or file to open
   fotoxx -l lc                      #  language code to use for GUI (de, fr ...)
   fotoxx -d                         #  debug mode - lots of messages to stdout
   fotoxx -v                         #  output version and build date and exit

Status Bar Information
The status bar contains information relevant to the current activity:
   during navigation: 1234x987x24 0.45MB 56%  edits: 3
   during HDR/pano: align: 2345  offsets: +12.3 -23.4 +0.0023 +1.2 -2.3  match: 0.91234

   1234x987x24  image width x height x depth (bits per pixel)
   0.45MB       image file size (updated when a modified image is saved)
   56%          zoom status, image % size
   edits: 3     3 prior versions are saved in the undo stack
   2345         HDR or panorama alignment cycles done (progress indicator)
   +12.3 etc.   alignment offsets: x, y, theta, two y-stretch values
   0.91234      image match (creeps up as alignment improves, reset each stage)

Alignment Algorithm
5000 high-contrast or "edge" pixels are selected to control alignment in HDR and Panorama. The actual pixels used are shown in red during the alignment process, which is also entertaining.

Alpha Channels
Images having alpha channels (transparency information) can be processed, but the alpha channel is lost when the processed file is saved.

Panorama Limitations
Panoramas including nearby objects can be tricky: when the two photos are made, be careful to turn the camera on a vertical axis through the lens, with minimum lateral movement, otherwise the images may align poorly due to movement of foreground objects against the background (parallax). This is not an issue when the subject is 20+ meters away, since a small lateral movement has little impact.

Panoramas of interior rooms or buildings may show lines that look curved or slanted, but this can be largely eliminated using the unbend and global warp functions.

Image Deterioration From Repeated Editing
If you save an edited image file and then use this file later to perform additional edits, pixel resolution may be lost. It is better if you do all edits when the image files are first processed, to minimize image deterioration (or go back to the originals if you still have them). The following edit functions reduce resolution about 1/2 pixel, and this error can accumulate from repeated edits: rotate (other than 90 degrees), HDR, panorama, unbend, warp. Resize will of course reduce resolution, but using the fraction 1/2, 1/3, or 1/4 gives the best results. The following functions do not reduce resolution: flatten, tune, color depth, red eye, sharpen, trim.

Source Code
The C++ source code is heavily commented in the hope that others can understand and use the code for their own projects. If you have a technical question about how something works, or a better idea to pass along, you can write to me at kornelix@yahoo.de.

Questions and Problems
If you have a question or run into a problem, you can write to me at kornelix@yahoo.de. If you send any images that work poorly, I can use these to try to improve fotoxx. If there are any error messages in the log file (/home/<user>/.fotoxx/fotoxx.log) please send these also.

Technical Reference Book
I recommend the book "Introduction to Image Processing and Analysis" by Russ and Russ, CRC Press. The following algorithms were adapted from this book: flatten brightness distribution, sharpen (unsharp mask, Laplacian), noise reduction (median smoothing, top hat).