fotoxx User Guide v. 5.4
Introduction fotoxx introduction
Quick Start one page quick start guide
Keyboard Shortcuts main window and thumbnail window shortcuts
Navigation finding image files and directories
Editing Images general image edit process
Select outline an image area to edit
Flatten flatten brightness distribution
Tune change image brightness and color 
Red-eye remove red-eye effect from electronic flash photos
Crop cut off unwanted margins around an image
Rotate level a tilted image or turn by 90 degrees
Resize set a new image pixel size or % of original image size
HDR high dynamic range: merge images with different exposure levels
Panorama stitch images together to make an ultra-wide image
Unbend remove bending from panorama images
Warp stretch and distort selected areas of an image
Sharpen sharpen a fuzzy image
Blur un-sharpen a sharp image
Reduce Noise reduce specks in images taken in low light conditions
Color Depth reduce color depth (poster effect)
Color Intensity change color intensity
Print
 print one or more images on a page, with added text
Tags Menu add tags (keywords) to images, search images by tags
Etc. Menu misc. functions: edit parameters, create thumbnails, slide show ...
Help Menu Help Functions
Technical Notes     command line options, status bar information, notes on methodology ...


fotoxx Introduction
fotoxx is a free open source Linux program for editing image files from a digital camera. The goal is to meet most image editing needs while remaining simple and easy to use.

The following functions are currently provided:
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


fotoxx Quick Start
The following is a 1-page quick-guide to help you get started. To better utilize all available functionality, please read the detailed user guide in the following pages.

toolbar buttons

select
 outline an image area to be edited, using the mouse
index
 open navigation window: thumbnail images of current directory
file
file open dialog: select directory / image file to view or edit
prev
move to previous image in the current directory
next
move to next image in the current directory
undo
undo last edit of current image (last 20 edits can be undone)
redo
redo last undo (review and evaluate previous edits)
zoom+
magnify image to 100% or 200%
zoom-
 scale image back down to window size
kill
stop a long-running function before completion
print
 arrange images on a page, add text, print
save
save the current (modified) image to a file (JPG)
trash
move the current image to trash folder
quit       
exit fotoxx

Image Edit menu functions
flatten
flatten image brightness distribution 
tune
change brightness distribution / color intensity
crop
cut out an area of interest and discard the rest
red eye
remove red-eye effect from an electronic flash photo
rotate
rotate an arbitrary angle or turn 90 degrees
resize
resize to a target pixel size or % of original size
HDR
combine brighter and darker images to improve visible detail
panorama
join two images to make a wide (panorama) image
unbend
remove image bending apparent with some panoramas
warp
stretch / distort an image area by dragging the mouse
sharpen
sharpen a fuzzy image
blur
blur an image (e.g. make skin look smoother)
reduce noise
reduce noise in photos made under low light conditions
color depth
reduce color depth (bits per color) to get a poster effect
color intensity
change color intensity from gray scale to intensified color

Example operation: Make an HDR image, adjust brightness and color, crop to final size:
file button
File open dialog: select the first image
HDR menu
Select 2nd image - will auto-align and merge with first image.
popup dialog
 Make fine adjustments of image contributions.
tune menu
Adjust brightness and color for the merged image.
crop menu
Cut image to final size.
save button
 Save the image to a new file.


Keyboard Shortcuts
  keyboard main window action thumbnail window action
   left arrow previous image previous page
   right arrow next image next page
   up arrow
up one row (previous row)
   down arrow
down one row (next row)
   + (plus) zoom larger larger thumbnails
   - (minus) zoom smaller smaller thumbnails
   Z zoom: 100% <--> fit window
   R rotate image 90 degrees right
   L rotate image 90 degrees left
   Delete move image to trash folder
   T show thumbnail window
   Escape leave slide show mode leave thumbnail window

If the image is magnified and does not fit in the window, the central portion of the image is visible. A left-mouse click moves the clicked position to the middle. Pressing the Z key will magnify the image to 100% in one step. Pressing it again will restore the image to fit within the current window size.


Navigation


Press the [index] toolbar button to get a window of thumbnails showing image files in the current image directory (upper left in above screenshot). Use the file and folder buttons to navigate elsewhere if wanted. 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. 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. You can also use the [prev] and [next] buttons in the fotoxx main window (lower right) to step through the image files one at a time. 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.


Editing Images - General Process 
The image in the main window can be operated on with the edit menu functions: tune, crop, HDR, etc. 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 20 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. When you open a new file, the undo memory for the previous file is discarded.


Selecting an Image Area to Edit
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: flatten, tune, warp, sharpen, blur, reduce noise, color depth, color intensity. The warp function works only within a selected area (but the whole image can be selected). Other functions (crop, 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 200 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.


Flatten
This is a fast and easy way to compensate for a common limitation in photos: the central subject is too bright or too dark, or there is not enough range in the brightness to show good detail in all areas. This flatten 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 by increasing or decreasing the brightness of chosen pixels.

Usage: open an image file and choose the flatten menu function. A dialog window will open up with a slider labeled "flatten". Move the slider and watch the image. Leave the slider at the best position and press [done] when finished or [cancel] to exit with no changes. The buttons [undo] and [redo] can be used to rapidly flip back and forth between the modified and unmodified image.

For the curious, the [graph] button produces a bar-chart of the brightness distribution. The brightness range is divided into 20 bands from dark to bright. The 20 bars represent the number of pixels in each of the 20 bands.


Tune
The tune function adjusts the brightness and whiteness (saturation) of an image independently for 9 brightness zones, using sliding controls. "Whiteness" is the lowest brightness present in all three of the primary colors red, green, and blue. Up to this amount can be removed from all three colors, or added to them. In the example below, the sliding controls show the adjustments made to increase both contrast and color. Compare the modified bird in the lower image with the original bird above.



Usage: Open an image with [file] and then select the tune menu function. The dialog with the sliders starts up. Adjust the sliders and view the results. If the image is large, it may take a few seconds to update after a slider is moved. When you are satisfied, use the [done] button to exit the dialog. The left-side buttons can be used to move all the sliders at once: up, down, or in a profile that slopes or curves up or down. Reset all controls with [reset]. Click [cancel] to abandon the changes.

Tune - Defog
The example below illustrates how to reduce fog or haze. Whiteness has been reduced in the darker image areas where the haze dominates. Contrast has been increased slightly for the dark and midrange areas (ascending brightness adjustments), and decreased for the brightest areas (descending brightness adjustments).





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 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.


Crop
The HDR and panorama functions will leave some black margins around the edges where the images did not overlap. Use the crop function to remove these areas, or any other unwanted margins.

Select the crop menu function. An initial dotted line rectangle is drawn, encompassing about 60% of the image. Areas outside the final rectangle will be discarded. A dialog pops up asking you to drag the mouse to modify the rectangle as desired. Drag the dialog box out of the way if needed. 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 [crop] button in the dialog box. The selected area is cut out and expanded to fill the window. Press the [cancel] button to abandon the operation.


Rotate
The rotate menu function starts a dialog to rotate the image clockwise (+) or counterclockwise (-) in steps of 0.1, 1, 10, or 90 degrees. Use the small steps to level a tilted image and then crop the image. 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.

To make a panorama image from two images made in vertical format:
[image]

Resize
This function allows setting a new image width and height in pixels, or as a percent of the original size. Open an image and then select the resize menu function. A dialog is initiated. You can input the new width and height directly. Buttons are present for setting the new size to 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 desired 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.


HDR  (high dynamic range imaging)
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.

Usage: Open the 1st image file with the [file] 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. The images may have a significant relative offset and rotation (especially if the camera was manually adjusted between shots), and some time may be required for the program to find the best alignment. When done, the combined image is shown, along with a dialog for manual fine adjustment.

The example below shows the two input images and the output image, as adjusted by the sliding controls in the dialog box.



The 9 sliders define 8 brightness bands where the contribution from each image (image weights in the dialog) can be adjusted independently. The left sliders govern the darkest areas of the combined image, and the remaining sliders govern progressively brighter areas. The initial settings define a ramp whereby the darkest areas are taken mostly from the brighter image, and the brightest areas mostly from the darker image. Play with the sliders to find the best settings. The sliders are very responsive, but the image may need a few seconds to catch up with the slider values, especially if the image is large.

The image alignment algorithm is accurate up to about 3 degrees of rotation and 5% image offset. If you make the exposure adjustment manually between shots, take reasonable care to aim at the same distant point and keep the camera level. If things move between the two shots (clouds, windblown trees), fuzziness and ghosting cannot be avoided.


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.

Before using panorama, you need to set two parameters (lens_mm and lens_bow) to match your camera lens. This small one-time job is required for each camera lens you plan to use for panoramas. The procedure for this is described later, but read this section first.

Press the [file] button and select the left image file. 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 (below) 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 do the one-time job mentioned above, to set the lens parameters for your camera. 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 right image is 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 or more depending on CPU speed.

When fine alignment is complete, the combined image is displayed. A dialog pops up for fine adjustment of brightness and color match (below). You will usually 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, rotate, crop, and tune functions for final adjustments, and then save the image to a file using the save function. The example above needs to be rotated a few degrees to level the room, unbent, and the black areas cropped off.

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.

Automatic lens adjustment
The [search] button in the pre-alignment dialog initiates an automated search for optimum lens parameters, lens_mm (focal length) and lens_bow (barrel or pincushion distortion). Use a suitable image pair: the subject is 20+ meters away, and the images have a low horizon difference and relative rotation. Input your nominal lens focal length for lens_mm. (for digital cameras, use the 35 mm film camera equivalent). 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. Use the parameter edit function (parameters menu) to input your new default values for lens_mm and lens_bow, and then save the parameters file so the values will be preserved for the next session. See the parameter edit function below.

The auto_lens 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. Each iteration takes a minute or more, but you only need to do this once to characterize a given camera lens. The next section describes an alternative manual method for setting these parameters.

Setting the lens parameters manually
Making two partly-overlapping images align with each-other requires them to be curved inward or shrunk in the overlapping areas. Also, a lens may have barrel or pincushion distortion, adding curvature at the image edges and reducing how well they can fit.

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. The example below shows a tiled wall before and after these adjustments. 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.



The lens_mm factor is roughly the focal length of the camera lens (35mm film camera equivalent). This may be used as a starting point for a more precise adjustment. The lens_bow factor depends on the lens and may be positive or negative.

After setting the values for lens_mm and lens_bow manually, try the auto_lens button to find more precise values automatically. Do this again to check that the values are stable. When done, save the values for lens_mm and lens_bow using the parameter edit function.


Unbend
Panoramas of nearby subjects (typically buildings or interior rooms) may show a noticeable bending effect (e.g. flat walls look curved). This bending of the images was necessary in the panorama process in order for the images to fit together. For remote subjects (typically landscapes) this is barely noticeable.



Usage: Select the unbend menu. The dotted lines are the vertical and horizontal "horizons" that are the unbend axes. Click the mouse (do not drag) near the end of a line to move it to the mouse position. Input values for horizontal and vertical unbend and press the [apply] button to see the effect. Increase or decrease the values and repeat until satisfied. Move the axes and press [apply] to change the centers of unbending.


Warp
This function can be used to make deliberate distortions in 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 like it was 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 example below illustrates the potential for mischief.



Usage: select the warp menu function. A dialog pops up with a few instructions and buttons. Select the toolbar button [select] to start the process of selecting the target area (as described in the select area section). When done selecting the area, warping for the area is activated. Now drag the mouse anywhere within the selected area and the picture will move with the mouse pointer. You can drag many times and in many directions within the same area until you get the desired result. This may take a little practice. 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. The [cancel] button removes all warps made during the session.


Sharpen
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 test images below show the capabilities and limitations. The 1st image is the original sharp image. The 2nd image was made by blurring the 1st image. The 3rd and 4th images were sharpened from the 2nd image, using edge detection and unsharp mask. 



Usage: after starting the function, a dialog pops up with funny inputs that you can usually leave at their default values. Radius 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: higher values reduce 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. The [undo] button restores the original image (or the selected area).


Blur
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.



Usage: after starting the function, a dialog pops up. To select an area to blur within the image, press [select area] and click the mouse around the desired area. Otherwise the whole image is processed. 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.


Noise Reduction
This function reduces the noise present in photos taken under poor lighting conditions (uniform surfaces appear speckeled). In the pop-up dialog, press the [reduce] button repeatedly while watching the image. If you go too far, sharpness and detail will be lost. Use the [reset] button to start over. When done, you can use the [undo] and [redo] buttons to review the results. The radius input determines the area around each pixel that is compared. A value of 1 or 2 usually works best.

Four algorithms are provided which have different characteristics. The first one usually works the best, but the others can be better under some circumstances.
    #1: Extreme pixels (outlyers) within a radius are moderated. Done independently per RGB color.
    #2: Same as #1, but overall brightness is moderated and color ratios are preserved.
    #3: Gaussian smoothing (blending) of neighboring pixels. Faster, but sharp edges get blurred.
    #4: Pixels are set to the median value of their neighbors. Done independently per RGB color.



Color Depth reduction
This function changes the color depth from the JPEG normal of 8 bits per color to any value between 1 and 8 bits per color. At 8 bits per color, there are 256 shades available for each of the primary colors red, green and blue, giving 256 x 256 x 256 = 16.77 million colors. At 4 bits per color there are 16 shades per color available, or 4096 total colors.

After starting the function, a dialog pops up. Use the spin control to choose a color depth of 1 to 8 bits per color, and press the [apply] button. Real differences start to become apparent below 6 bits per color. The example here is 8 bits and 3 bits per color.




Color Intensity
This function changes the color intensity on a scale from 0 to 100.

Use the dialog to enter a new color intensity from 0 to 100:
      0     no color (black/white or gray scale image)
    50     normal color, defined by the original unmodified image
  100     intensified color (saturation)
In-between values give in-between results.

Press the [apply] button after entering a new color value.



Between 0 and 50, all RGB color values are ramped linearly from the mean gray-scale value of (R+G+B)/3 to the original unmodified values. Between 50 and 100 all RGB color values are increased by the same ratio until the largest reaches the maximum value 255. This is reduced for darker pixels and "grayer" pixels, because the results are useless if dark areas become as bright as bright areas, and gray areas become white.

The table below illustrates what happens. The middle column depicts unmodified pixels, and the outer columns show what happens to these pixels as the intensity is moved to 0 or 100.


 gray    
scale 		normal
color 		max.  
color
  intensity 0 50 100





  red 200 150 151 bright pixel, blue near maximum
  green 200 200 201
  blue 200 250 252
  red 20 10 21 dark pixel with color
  green 20 20 42
  blue 20 30 64
  red 0 0 0 black pixel
  green 0 0 0
  blue 0 0 0
  red 50 50 50 gray pixel (R = G = B)
  green 50 50 50
  blue 50 50 50
  red 50 0 0 mid-level pixel with color
  green 50 50 80
  blue 50 100 159


Print
This function (toolbar button) invokes the sister application printoxx with the current image pre-loaded on the print layout page. With printoxx, you can add multiple images to a print layout, move them around and change their sizes using the mouse, add text of any font and size, and print the finished layout. More information is available at http://kornelix.squarespace.com/printoxx.


Tags Menu

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 an image, the associated event, the location, 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 theme, and file names corresponding to the main subject of the image, or simply sequence numbers. Tags can then be used to make other organizations, e.g. the images of a person over 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.

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 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 into the top window and pressing [add new]. 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 ([prev] [next] [next page] etc.) until you use the [file] or [folder] buttons to establish a new set. To find all images with no tags, search with no tags.


Build Tags Index
If you reorganize image files and directories, the tags index becomes invalid. The tags are inside the images (in the EXIF data), so nothing is lost. The tags index can be rebuilt quickly using the menu function. The one assumption is that all the image files (for one log-in user name) are within one top-level directory. Many users can share a set of images if they are within one topmost directory, but each user will have his/her own tag index file. To use the function, select the menu and enter the topmost directory containing all the images to be indexed. The indexing speed is a few thousand images per minute on a PC with 2 GHz clock speed. An index file (a simple database) is used because this is something like 100 times as fast as reading the EXIF data directly.

Tag 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 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 (for the simple methodology used in fotoxx). 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 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 windows to find a smaller set of images is also quite fast. Physical file organization is also preserved in the thumbnail windows (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.

View EXIF Data
If the package exiv2 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.



Etc. Menu

Open works the same as the [file] button on the toolbar - a file open dialog to select an image file.

Edit Parameters
The HDR and panorama functions superimpose and compare two images, pixel by pixel. Their relative x/y offsets and rotation are varied to search for the best overlay position. The initial image sizes are small, and get larger with each stage. The best fit at each stage is the starting point for the next stage. The parameters described here control the process.

Use the edit parameters menu to start the function. Change the values shown in the dialog and use the [save] button to save them to the default file "parameters", which is loaded each time fotoxx is started (/home/<user>/.fotoxx/parameters).

The parameter "pixel sample size" determines how many pixels are compared at each stage, for both comp and panorama. The remaining parameters relate only to panorama.

The panorama lens factors depend on the camera lens (focal length and distortion), and are more likely to need customizing. This process was described previously.

The default values for the other parameters should work fine, but if you have an image that does not align correctly, you can adjust these parameters to be more conservative (and slower). More details can be found below.

You can have multiple profiles, for different cameras/lenses or normal vs. problem images. The default parameter file is loaded each time fotoxx is started. If you need multiple parameter files, you must manage their names and load and save them on your own. In the parameter dialog, use the buttons [load] and [save] to load or save a parameters file.

parameter name default    description
pixel sample size 5  How many pixels (x1000) are sampled during alignment.
Impacts execution time.
jpg save quality 80  Quality vs compression for jpg files. Explained below.
pano lens mm 40  Curves images in the overlap area to make alignment possible.
pano lens bow 0  Compensates for lens barrel distortion.
pano prealign size 500  Image size (pixels) for prealignment. Explained below.
pano mouse leverage 2  Mouse movement pixels to drag the image by 1 pixel.
This makes precise control easier.
pano align size increase 1.6  Image size increase at each alignment stage.
Reduce if you have problems. Impacts execution time.
pano blend reduction 0.7  Image comparison area reduction at each alignment stage.
pano minimum blend 10  Final image comparison area, in percent of image size.
pano image stretch 0  0: Do not use the image stretch / shrink algorithm.
1: Do use this algorithm (slower). Explained below.

If you install a new version of fotoxx, you should delete the old parameter file and let fotoxx make a new one. This is because some parameters may have been added or removed in the new version. Note your customizations (lens mm and lens bow) and make these same changes to the new file.

pano image stretch parameter
Panoramas made with images from a wide-angle lens may have alignment problems. This can happen if the two images have significant relative rotation, or if the vertical aiming level (horizon) is significantly different (i.e. a large vertical offset is needed to make the two images fit together). The more an object is displaced from the image center, the bigger it is on the image, and with wide-angle lenses this effect can be large enough to cause visible alignment errors in the joined images. Starting with v. 2.3, fotoxx has an optional additional algorithm to stretch or shrink the right side image as needed to make a better match to the left side image. The upper and lower image halves are stretched or shrunk separately. This algorithm is slow and is not used unless the parameter "pano image stretch" is set to 1 or more. The value determines the algorithm search range and ultimately the amount of stretching or shrinking that can be applied. It is OK to leave it at zero for most cases. If you notice a vertical step at the image joint, you can set this parameter to 1 or 2 to engage the algorithm. The run time will be 10-20 seconds longer (based on a 2 GHz CPU).

pano pre-alignment image size
You can decrease this parameter to obtain smoother mouse control during pre-alignment. This may be helpful for computers without fast graphics processors (some notebooks). The alignment image may be fuzzier but the final results are not affected.

jpeg save quality
This regulates how strongly saved image files are compressed. Use a value from zero to 100. Zero gives awful image quality and a very small file size. 100 gives the highest quality and a large file size. The default value of 80 is a good compromise: it is nearly impossible to see any loss of quality, and the file size is about 30% of the highest quality file size. In the technical notes you can find a more detailed discussion of this.

other parameters
You can adjust the alignment parameters to make them more conservative and robust (and slower): increase the pixel sample size, reduce the pano align size increase, make the pano minimum blend smaller (alignment focuses more on the immediate area around the joint line), and enable pano image stretch. This may help in the case of images that do not fit well together, or have large areas (e.g. sky) with few details that can help alignment.

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 weak 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. This evaluation should be done in a darkened room (no external light falling on the monitor screen).

Create Thumbnails
In a directory with hundreds or thousands of images, navigation can be slow - a few seconds may be needed to generate the thumbnail screen when a new page is selected. This is because the thumbnails must be created each time by reading and compressing the image files. Most of this overhead can be avoided by storing the thumbnails permanently on disk, and navigation will be about 5X faster as a result. Use the "create thumbnails" function to do this job. A popup dialog will ask for a directory. Select the top-level directory of your image files. That directory and any subdirectories containing images will be processed. Missing or outdated thumbnails will be generated at a rate up to about 1000 per minute, depending on image sizes and processor speed. The thumbnails are saved in subdirectories named ".thumbnails" which are added to any directory found to contain image files. Once this directory is present, new and modified images will have their thumbnails updated automatically. The thumbnail size is 256 pixels and typically about 70 KB. These directories can be deleted with no effect except for the speed of paging through thumbnails.

Clone
Start a new instance of fotoxx in a new window, starting with the current image file. This is useful to evaluate changes as they are being made, 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 (see keyboard shortcuts section). Use the escape key to get out of slide show mode.


Help Menu

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

fotoxx user guide
The user guide (this document) is displayed. The first page is an index of topics which can be clicked to jump to the corresponding section of the document (document created using the WYSIWYG HTML editor Kompozer).

README file
Displays the README file distributed with fotoxx, which may contain new information about installation or dependencies.

change log
Displays the changelog file distributed with fotoxx, containing details about functional changes, additions, or bug fixes for the current release and previous releases. When you install a new release of fotoxx, you should at least look at this file to check if there is anything special you need to do.

error log
Displays the error log file, containing fotoxx error messages and possible traceback dumps from serious bugs. This file is accumulated until deleted. If you experience a bug, please send this file to: kornelix@yahoo.de. The file location is: /home/<user>/.fotoxx/fotoxx.log.


Technical Notes

Command line options and desktop launchers
The following command line options can be used in launchers to simplify startup:
   -i <image file directory>      #  full absolute path
   -f <image file to open>        #  absolute or relative to -i path
   -p <parameter file>            #  absolute or relative to /home/<user>/.fotoxx
   <image file to open>           #  same as -f but without the -f
   -l de                          #  language to use for GUI (en de es fr)

 You can use fotoxx as the application to launch when a .jpg file (or other image file type) is selected in the Nautilus browser. Right click a .jpg file, select properties, open with, add, and custom command. Locate and select the fotoxx executable (/usr/local/bin/fotoxx).

Status Bar information
The main window status bar contains information relevant to the current activity:
during navigation
 1234x987 0.45MB 56% 52/234 modified undo=3
during alignment
aligning: 2345 +12.3 -23.4 +0.0023 match: 0.9123
during crop
crop: 1234x978

explanation of the above fields:
1234x987
image pixel size, width x height
0.45MB
image file size (updated when a modified image is saved)
52/234
image file position and total image files in the current directory
56%
 zoom status, image % size
modified
the current image has been modified
undo=3
3 prior versions are saved in the undo stack
2345
HDR or panorama alignment cycles done (progress indicator)
+12.3 etc.
alignment values: x and y offsets in pixels, theta offset in radians
0.9123
image match (creeps up as alignment improves, reset each stage)
1234x978
new image size during crop operation

If panorama image stretching has been enabled, two more alignment values will show up: stretch/shrink values for the upper half and lower half of the right side image.

KDE and fotoxx
I tried fotoxx with Open Suse 10.2 (KDE) and it worked fine. The toolbar button text was missing by default, but this can be added using KDE's customization menus.

Multiple Threads on SMP processors
I was not able to make HDR and panorama run significantly faster by dividing the work between two threads on an SMP system (2 processors). A possible explanation is limited memory bandwidth: if one thread is able to utilize the full bandwidth, then multiple threads will not gain any performance. fotoxx uses uncompressed image files in memory that often exceed 20 MB, which is far more than the typical processor L2 cache size of 1-4 MB.

Trash folder
There is no standard location for the trash folder in Linux, and in practice it varies. Starting with v. 4.3, discarded images are moved into a desktop folder named "fotoxx trash". You can delete it or move it to your system-specific trash folder.

JPG file quality
The JPG image quality can be set when a file is saved by using the [quality] button in the file save dialog. The default quality is defined by the parameter jpg_save_quality. If you set a different quality, this value will be used for subsequent file saves. A new fotoxx session begins with jpg_save_quality. Therefore set your default here, and change it on a case by case basis, remembering that the changed value will continue to be used in the current session until changed again.

I made some simple evaluations which are summarized in the table below. The test file was a 7 megapixel JPG file of 2.7 MB from my digital camera, which I repeatedly saved with a quality of 0, 10, 20 ... 100. I viewed these files on an LCD monitor using the gThumbs image viewer at 100% image size. I compared the images by flipping back and forth in the same window (instant replacement). My conclusion is that quality 50 is usually good enough, and 70 is uncompromising (at least for my eyes and monitor).

The files that come out of a camera are generally huge (presumably because of the limited time and processing power available for compression). These huge files can be replaced with much smaller ones by using a quality setting of 50-70.
quality
size MB visual differences compared to quality=100 image
   90
  1.3 no visible differences
   80
  0.90 no visible differences
   70
  0.71 no visible differences
   60
  0.59 small differences can be seen, but no loss in quality
   50
  0.52 some color banding can be seen if you look hard
   40
  0.45 slight color banding can be seen
   30
  0.38 noticeable color banding, slight loss of sharpness
   20
  0.30 moderate color banding and loss of sharpness
   10
  0.21 obvious color blocking and banding, loss of sharpness
     0
  0.13 severe blocking (8x8 pixel squares) and color loss

Alignment Algorithm
A few thousand high-contrast or "edge" pixels are selected to control alignment in HDR and Panorama. The number of pixels sampled is an adjustable parameter. I have set the default value to 5 (5000 pixels). 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 as a .jpg file.

Panorama Limitations
My testing with panoramas of nearby objects revealed some issues: 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 will not align very well. This is not an issue when the subject is 10+ meters away, since a small lateral movement has little impact.

Panoramas of interior rooms or buildings may show lines that look curved, but this can be largely eliminated using the unbend function.

Sometimes the two images may not be joined at the optimum place: fotoxx converges on a local optimum instead of the global optimum. I have always been able to overcome this by making the alignment parameters more conservative or the pre-alignment more precise.

I have two cameras for which the auto-lens function gives inconsistent results. For images made at 38mm focal length (according to the EXIF data), the auto_lens function gives 38mm for one camera and 46mm for the other one. These values do work for fotoxx even if they are inconsistent. Inspection of the images revealed that the barrel distortions are vastly different (auto_lens gives bow values of 0.2 and 1.5). Possibly there is an exchange of focal length and bow taking place. Whatever this is, it does not seem to affect the results.

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. 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, crop, red eye, sharpen, noise reduction, color depth, color intensity.

Noise Reduction Algorithms
Four noise reduction algorithms are supplied. They perform differently with different noise characteristics, and have variable effectiveness in the preservation of detail. When quality is critical and you have enough time, try all four methods, and vary the radius of analysis between 1 and 2. You can also use area selection to confine the operation to the darkest (noisiest) parts of the image.

Thumbnail images
Starting with fotoxx v. 4.3, the file names for the thumbnail images were revised. Instead of using random names, the image file names are used, with ".png" appended. If you take no action, fotoxx will still work normally, but large image directories will be slower to navigate with the thumbnail viewer, since existing thumbnail files are no longer being used.
What you should do for optimal navigation performance:
  + delete the old thumbnails directory: /your/image/directory/.thumbnails
  + use the create_thumbnails menu to generate new thumbnails

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, please write me at kornelix@yahoo.de.

Translations
The fotoxx GUI can be used with non-English languages. French, German and Spanish are available, and I am hoping for more. See files  /usr/local/share/fotoxx/fotoxx.xtext  and  zfuncs.xtext  to see how this is done. Other languages can simply be added to the same files. English can be terse compared to other languages (e.g. "undo" becomes "rückgängig machen" in German), which can cause ugliness in the GUI layout. If you do a translation, try to make the menus and buttons short, and carefully inspect all dialogs. I can consolidate translations and redistribute them with fotoxx. The user guide is available in English and French.

Help
If you have a question or run into a problem, you may write 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 (Gaussian, median smoothing).