fotoxx quick guide

File menu	File management and other administrative functions.
Open	File open dialog - open an image file to view or edit.
Save	File save dialog - save the current (edited) image to a file.
Trash	Move the current image into the fotoxx trash folder.
Print	Arrange images and text in a layout for printing (see sister application printoxx: http://kornelix.squarespace.com/printoxx).
Quit	Exit from fotoxx.
Edit Parameters	Edit parameters affecting the panorama and HDR functions. You must set "pano lens mm" to match your camera lens (35mm equivalent). Other adjustments may be needed (more).
Create Thumbnails	Create thumbnail images to make thumbnail pages display faster (more).
Check Monitor	Display a color palette for tuning your monitor. Adjust so that gradations in brightness can be seen for all colors at both ends of the image (more).
Slide Show	Use the entire monitor to show images (no menu or toolbar) (more).
Clone	Start another instance of fotoxx with the current image (more).
Tags menu	Manage image tags (keywords for searching), star ratings, dates (more).
Edit Tags	Add or change the photo date, star rating, and tags (keywords) for an image (more).
Search Tags	Search all images for desired tags and / or star ratings and / or date range (more).
Build Tags Index	Build an index of photo dates, star ratings, and tags for all images (more).
View EXIF Data	View EXIF data for the current image, including date, exposure data, and tags (more).
Edit menu	These functions modify image files (more).
Select Area	Outline an area for subsequent editing using mouse clicks and drags. If no such area is active, editing functions use the entire image.  Invert: replace the selected area with the entire image except the selected area (more).
Brightness Distribution	Flatten the brightness distribution. Enhances low-contrast areas of the image. Sometimes a fast and easy method to make significant improvements (more).
Brightness/ Contrast/Color	Change brightness and color intensity independently for image areas with different brightness, e.g. brighten dark areas while not affecting bright areas (more).
Color Depth	Reduce color depth (number of colors displayed). Makes a poster or painting effect (more).
Color Intensity	Increase or decrease the color intensity on a scale from zero (gray) to maximum color (more).
RGB Spread	Intensify or reduce the main color for each image location, e.g. gray <> pink <> red (more).
Sharpen	Sharpen a blurred image (more).
Blur	Blur an image (make skin look smoother, or soften hard edges) (more).
Reduce Noise	Reduce noise (speckles) in low-light images (more).
Red Eye	Remove red-eyes from electronic flash photos. Normally just click the red-eye 1-3 times. For hard cases, drag a circle around the red-eye and click to darken in steps (more).
Trim	Cut out a rectangular portion of an image (more).
Rotate	Rotate an image (level a tilted image or turn in 90° steps) (more).
Resize	Change the pixel dimensions, typically used to reduce the size of a large image (more).
Unbend	Fix image perspective problems: curved walls or slanting buildings (more).
Warp	Distort an image by pulling on a location with the mouse. For funny effects (more).
HDR	Combine an underexposed and overexposed image to make an image that shows better detail in both bright and dark areas. HDR = high dynamic range (more).
Panorama	Combine two overlapping images to make an ultra-wide image (more).
Help menu	User guide, README notes, list of changes (more).
Toolbar
index	Show a window of thumbnail images, starting with the current image. The thumbnail window can be paged and navigated to other locations. Clicking on a thumbnail will display that image in the main window (more).
open	File open dialog - open an image file to view or edit.
save	File save dialog - save the current (edited) image to a file.
trash	Move the current image into the fotoxx trash folder.
prev	Go to previous image in the current directory, if any.
next	Go to the next image in the current directory, if any.
undo	Undo (reverse) the results of the previous edit function. Up to the last 20 edits can be reversed.
redo	Redo the previous undo. Repeat to redo each undo made on the current image.
zoom+	Magnify the image. A left mouse click also magnifies.
zoom-	Reduce the image. A right mouse click also reduces.
kill	Stop the current long-running function (HDR, Panorama). Do this if you see that the wrong images are being combined.
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	leave 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 text file TRANSLATIONS ( /usr/local/share/doc/fotoxx/ ) for guidance on how to modify an existing translation or make a new one for a new language.

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.

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

Select an 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: brightness and color edits, warp, sharpen, blur, reduce noise. The warp function works only within a selected area (but the whole image can be selected). 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 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.

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.

Brightness Distribution

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. Move the slider and watch the image, which may lag a few seconds. Some images will show good results, others not.

Brightness/Color/Contrast

This 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. 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. 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. Examples: brightness button [ - + ] incrases overall contrast. Whiteness button [+ - +] removes whiteness from the mid-level brightness areas, intensifying color and reducing fog/haze. Brightness button [ - + - ] can be used to add back the lost brightness.

Color Depth reduction

This function changes the normal 8 bits per color (red, green, blue) to any value between 1 and 8 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 3 or 4 bits for an interesting "poster" effect.

Color Intensity and RGB Spread

For both functions, moving the slider to the left makes all RGB values more equal, producing gray tones at the left end. For the color intensity function, moving the slider to the right increases all RGB value by the same factor - the color is not changed but intensified. This effect is greatest in the darker areas of the image. For the RGB spread function, moving the slider to the right increases the larger RGB value(s) and decreases the smaller one(s) - the dominant color component is intensified, but not the total R+G+B sum (brightness).

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

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

Reduce Noise

This function reduces the noise present in photos taken under poor lighting conditions (uniform surfaces appear speckeled). 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 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.

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.

Trim

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.

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

Resize

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

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. 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. An area must be selected before warping can begin. 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.

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.

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 9 sliders define brightness bands where the contribution from each image 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 (people, 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.

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

Setting Lens Parameters Automatically
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.

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.

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.

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.

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.

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.

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

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. 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 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 into the top window 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 (buttons [prev], [next], [next page], etc.) until you use the [file] or [folder] buttons to establish a new set. A date range may be optionally entered, to further restrict the search to images within the date range. The format is yyyymmdd. Only the 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.

Build Tags Index

You need to do this when fotoxx is first installed, or if you reorganize image files and directories. 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 are within one top-level directory. Many users can share a set of images if they are within one top directory, but each user will have his/her own tag index file. To use the function, select the menu and select the topmost directory containing all the images to be indexed. The indexing speed is 1000+ images per minute. An index file (a simple database) is used because this is 100 times as fast as reading the EXIF data directly.

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. NOTE THAT THE EXIV2 PACKAGE IS REQUIRED IF YOU WANT TO RETAIN EXIF DATA WHEN AN IMAGE IS MODIFIED AND SAVED.

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 of 500-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 (more). Use the escape key to get out of slide show mode.

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.

You will need to set "pano lens mm" at a minimum, and "pano lens bow" may also be needed. The others can normally be left at their default values. If you have an image that does not align correctly, you can adjust these parameters to be more conservative (and slower).

Change the values shown in the dialog and use the [save] button to save them to the default file which is loaded each time fotoxx is started (/home/<user>/.fotoxx/parameters). If you need multiple parameter files (for multiple cameras or lenses), you must manage their names yourself. Use the buttons [load] and [save] to load and save them.

parameter name	default	description
pixel sample size	5	How many pixels (x1000) are sampled during alignment.
pano lens mm	40	Curves images to make alignment possible.
pano lens bow	0	Compensates for lens barrel / pincushion distortion.
pano prealign size	500	Image size (pixels) for prealignment.
pano mouse leverage	2	Mouse steps to drag image by 1 pixel, for easier control.
pano align size increase	1.6	Image size increase at each alignment stage.
pano blend reduction	0.7	Image comparison area reduction at each alignment stage.
pano minimum blend	10	Final image comparison area, percent of image size.
pano image stretch	1	Image stretch search range for optimum fit.
jpg save quality	85	Quality vs compression for jpg output files.

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

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

pano image stretch
Panoramas made with images from a wide-angle lens are more prone to alignment problems. This can happen if the two images have significant relative rotation, or if 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. Fotoxx has an optional 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. 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).

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 85 is a good compromise: it is nearly impossible to see any loss of quality, and the file size is about 40% 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.


Technical Notes

Command Line Options
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 xx                          #  language to use for GUI (xx = en de es fr gl el)

Status Bar Information
The 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

   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)

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. The install command "make launcher" does not work due to KDE not following LDS standars. You can create a desktop launcher manually using the command fotoxx.

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 with 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 is defined by the parameter jpg_save_quality. Set your default here, and change it on a case by case basis, remembering that any changed value will continue to be used in the current session until changed again. A quality of 85 is uncompromising. A quality of 50 is good enough for the differences to be unnoticeable, and the file size will be reduced by half.

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. The default value is 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 may align poorly due to the shifting or foreground objects against background objects (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, 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: brightness and color edits, trim, red eye, sharpen, noise reduction.

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 directories: /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.

Questions and Problems
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).