fotoxx user guide

Fotoxx User Guide v.10.11

Essential Information for those who hate big user manuals:
o Menu functions have live help activated by F1.
o Mouse left click: zoom image bigger, centered at mouse position.
o Mouse right click: restore image to fit in window.
o Mouse drag across image: works like scroll bars.
o Gallery button: thumbnail browser: view all images in current directory.
o Click image in thumbnail browser: show image in main window.
o Menu: Tools > Change Language: switch between English and your language.

When you see the word directory, substitute folder if this is your way of thinking.

License and Warranty
Fotoxx is licensed under the GNU General Public License v3 (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, you may contact me.

Getting Started

Try the appropriate package file first (packages). It may install OK with one click. If not, you must install from source code. Instructions are here: downloads. Fotoxx should show up in the Graphics menu after installation (maybe after a new log-on). If not, use the command "fotoxx" in a terminal window or launcher. Use the toolbar button [open] to find an image file (.JPG .TIF .PNG ...) and check that it is displayed OK. Use the menu Retouch > Brightness/Color and press the button [+++] a few times - the image should brighten. Use the button [cancel] to exit this function. Press the toolbar button [gallery] to show all the image files in the same directory as an array of thumbnail images. This may be slow at first, since the thumbnails must be generated, but it will be fast the next time you visit the same directory. Click on any thumbnail to show the image full-size. If all this works OK, then fotoxx is working normally.

There are two more initialization steps to make fotoxx work optimally. The menu function Tools > Rebuild Thumbnails will create thumbnails for all your image files. This makes gallery windows fast and smooth-scrolling. The menu function Tools > Rebuild Tags Index will build the search index used for image searching. This makes it possible to search thousands of images per second. These functions may need several minutes to complete if you have thousands of images or a slow computer. The first time you run one of these functions, you must enter a "top image directory". This is a directory containing all your image files, either in itself or in its subdirectories. Most Linux flavors have a pre-installed location like /home/<user>/Images. For more details, see Rebuild Thumbnails and Rebuild Tags Index.

Fotoxx Menus and Toolbar Buttons

File menu	File Management
Image Gallery	Show thumbnail images - image files in the current directory (more).
Open Image File	File open dialog - open an image file to view or edit (more).
Open Previous File	Go back to the last image file opened, also if in another directory (more).
Open Recent File	Choose from a list of the most recent image files opened (more).
Save to Same File	Save modified image to the same file (overwrite) (more).
Save to New File	Save modified image to a new file (more).
Print Image File	Select printer / paper format / orientation, and print image (more).
Trash Image File	Move an image file into the Fotoxx trash bin (more).
Rename Image File	Rename image files with optional sequence numbers (more).
Batch Rename Files	Rename many image files using a base name and sequence number (more).
Quit Fotoxx	Exit from Fotoxx.

Tools menu	Utilities and setup functions.
Check Monitor	Display a color palette for tuning your monitor (more).
Brightness Graph	Show brightness distribution graph of current image (more).
Clone Fotoxx	Open a new window (e.g. to compare two images) (more).
Slide Show	Show images full screen (no menu or toolbar) (more).
Show RGB	Show RGB values at position of mouse click (more).
Grid Lines	Add or remove grid lines for image alignment (unbend, rotate) (more).
Lens Parameters	Edit parameters for your cameras and lenses (more).
Change Language	Change the GUI language (more).
Create Launcher	Create a desktop icon / launcher for Fotoxx (more).
Convert RAW Files	Convert one or many RAW image files to tiff (more).
Burn Images to CD/DVD	Select images and write them on a CD or DVD (more).
E-mail Images	Select images, downsize, send to your preferred e-mail program (more).
Rebuild Thumbnails	Rebuild thumbnail images for fast browsing (more).
Rebuild Tags Index	Rebuild tags index for searching tags (more).
Convert Tags	Convert tags to new standard for Fotoxx v.10.0 (more).

EXIF menu	View or edit EXIF data.
Basic EXIF data	View most important EXIF data (more).
All EXIF data	View all EXIF data (more).
Edit EXIF data	Add or change the data for a specific EXIF key (more).
Delete EXIF data	Delete a specific EXIF key or all EXIF data (more).

Tags menu	Manage tags (keywords) / star ratings / dates (more).
Edit Tags	Add or change image tags (keywords), stars rating, or date (more).
Batch Add Tags	Add many tags to many images at once (more).
Batch Delete Tag	Delete or replace one tag for many images at once (more).
Edit User Comments	Add or change user comments for an image (more).
Search Tags	Find images with desired tags / star ratings / dates (more).

Area menu	Areas within images where edits are confined
Overview	Explanation of area editing (more).
Select	Select an area for subsequent editing (more).
Show / Hide	Show or hide an area outline (more).
Enable / Disable	Enable or disable an area for subsequent editing (more).
Invert	Invert an area (more).
Delete	Delete an area (more).
Copy / Paste	Copy an area to memory and paste it somewhere else (more).
Open / Save	Save an area as an image file and load it later to save into other images (more).

Retouch menu	Functions that change image qualities
Adjust White Balance	Remove false color-cast from an image (more).
Make Negative	Make a black-white or color negative, or a positive from a negative (more).
Flatten Brightness	Flatten the brightness distribution to enhance detail (more).
Brightness / Color	Edit brightness, contrast, color saturation, color balance (more).
Brightness Ramp	Horizontal / Vertical variation of brightness (more).
Expand Brightness	Clip low / high brightness levels and expand the rest (more).
Tone Mapping	Increase local contrast (not overall contrast) (more).
Red Eyes	Click on a red-eye to remove it (more).
Blur Image	Blur an image (smoothen skin) (more).
Sharpen Image	Sharpen a blurred image (more).
Reduce Noise	Reduce noise (speckles) in low-light images (more).

Transform menu	Functions that change image size, shape, content
Trim Image	Cut out a rectangular portion of an image (more).
Resize Image	Scale an image up or down (more).
Batch Resize	Resize multiple images (for upload to the web, e-mail, etc.) (more).
Annotate Image	Add text annotations to images, using EXIF or writing on the image (more).
Rotate Image	Rotate an image (level a tilted image or turn in 90° steps) (more).
Flip Image	Reverse an image horizontally or vertically (more).
Unbend Image	Fix perspective problems (more).
Warp Image (area)	Distort image within an area by pulling with the mouse (more).
Warp Image (curved)	Distort entire image by pulling with the mouse (more).
Warp Image (linear)	Distort entire image by pulling with the mouse (more).
Warp Image (affine)	Distort entire image by pulling with the mouse (more).

Art menu	Functions that make artful transformations
Color Depth	Reduce color depth (posterize) (more).
Simulate Drawing	Transform a photo into a simulated pencil or chalk drawing (more).
Simulate Embossing	Transform a photo into a simulated embossing (more).
Simulate Tiles	Transform a photo into tiles (make large pixels) (more).
Simulate Painting	Transform a photo into a simulated painting (more).
Edit Pixels	Edit pixels and paint lines or areas using the mouse (more).

Combine menu	Functions that combine multiple images
HDR	Make a high dynamic range image (more).
HDF	Make a high depth of field image (more).
Stack	Combine multiple images to reduce noise (more).
Panorama	Join overlapping images to make an ultra-wide image (more).

Help menu

User guide, README, change log (more).

Toolbar buttons
Gallery	Show thumbnail images - image flles in the current directory (more).
Open	File open dialog - open an image file to view or edit (more).
Prev	Go to previous image in the current directory.
Next	Go to the next image in the current directory.
Save	Save modified image to the same file (overwrite) (more).
Save As	Save modified image to a new file (more).
Undo	Undo (reverse) the results of the previous edit function.
Redo	Redo the previous undo. Undo/redo depth is 99 edits.
Zoom+	Magnify the image. A left mouse click also magnifies.
Zoom-	Reduce the image. A right mouse click also reduces.
Trash	Move an image file into the Fotoxx trash bin (more).
Quit	Exit from Fotoxx.
Help	Show online user guide

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 (temporary)
G key	toggle grid lines on or off
T key	shortcut for menu Transform > Trim
B key	shortcut for menu Retouch > Brightness/Color
Delete key	move image to Fotoxx trash
Escape key	Exit slide show mode
Control + s	Save to original file (no questions asked)
Control + S	Save-as: dialog to choose a target file
Control + q or Q	Quit Fotoxx
Image Gallery window
Home / End keys	move to first / last page of thumbnails
Page Up / Down keys	move to previous / next page of thumbnails
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 image gallery window
Dialogs for User Input
F1 function key	display user guide section for current function

Mouse Functions

left click	Zoom-in: magnify image, center at click position.
right click	Zoom-out: restore image to window size.
drag on image	Scroll image in opposite direction, like a scroll bar.

Some additional technical notes can be found here.

Selecting Images from an Image Gallery Window

This procedure is used in several functions which process multiple image files (burn images to CD/DVD, e-mail images, batch add and delete tags, batch resize images). It is explained once here, and this paragraph is linked from each of the functions using this procedure.

When the "Select Files" button is pressed, a dialog box appears with an empty list for the selected image files. Behind it is a gallery window which permits the selection of multiple images. To select an image, click its thumbnail and the image file will be added to the list. You can navigate the image gallery window to other directories and choose images randomly. The list of image files can also be manipulated to change the sequence or remove images added by mistake. Click on a file in the list to show its thumbnail in the dialog and also set the current list position for subsequent adds and deletes. The next image file added will be inserted at this position. If the [delete] button is pressed, the current image file will be deleted, and if the [insert] button is pressed, the last deleted image file will be inserted at the current position. To move an image to a new position in the list: click the image file (its thumbnail will be shown), press [delete], click another image file and press [insert] - the deleted image will be inserted before the selected image. The list can also be edited directly: you can use cut and paste to get the sequence you wish, but be careful to always cut and paste entire lines (files) only. The [add_all] button will add all the image files in the current image gallery. After using Search Tags to establish a set of images, the gallery window will start with this same set. You can select individual images from the gallery, or use [add all] and then delete unwanted images.

File Menu

Navigation

Use the Image Gallery menu or the [gallery] toolbar button to open an image gallery window (thumbnails) showing image files in the current directory. Use this window to scroll around the directory and select image files by clicking thumbnails. The buttons at the top allow scrolling forward or back by rows or pages. Use the [parent] and [open] buttons to jump to other locations. Use the [bigger] and [smaller] buttons to change the thumbnail size and the number of visible thumbnails. Pressing the [gallery] button in the Fotoxx main window will bring the gallery window forward with the current image file thumbnail in the top row. Clicking on a thumbnail will bring the Fotoxx main window forward with the selected image. The windows seem to replace each-other, but one is only on top of the other, and they can be dragged apart if wanted.

Open Image File

This function starts a standard file open dialog, allowing you to select an image file or navigate to another directory and select an image file. The selected file is opened in the Fotoxx main window where you can view or edit the image file using the menus and toolbar buttons. Drag and drop can also be used to open a file: drag an image file from Nautilus (or other source) to the Fotoxx window or to the Fotoxx desktop launcher, and Fotoxx will open the file. If text is dragged from gedit (or other program with drag sourcing), Fotoxx will assume the text is a filespec and try to open it. Thus you can make a list of filespecs within a text file and use this list with Fotoxx. Effectively, you can use Nautilus or text files to navigate a collection of images as an alternative to the Fotoxx navigation system.

Open Previous File

Go back to the previously opened image file, also if in a different directory. This differs from the toolbar button [Prev] which goes to the previous image file in the same directory as the current image file.

Open Recent File

The 30 previously opened image files are presented in a list, from which you can select a file to open.

Save Image File

Menu: File > Save to Same File, or toolbar button [Save]:
Save the current image image file back to itself without confirmation. If the file is a JPEG file, the default quality (90) is used.

Menu: File > Save to New File, or toolbar button [Save As]:
Open a dialog to save the current image file to a selected file, which can be the original file, another existing file, or a new file. An edited image file can be saved in three formats, JPEG, PNG, and TIFF. JPEG is normally the best option, since these are compressed to reduce space. You can choose a JPEG quality value in the range 1-100. Lower values give greater compression and less image quality. Values above 70 are generally hard to distinguish from 100 (highest quality, largest file size). PNG files are compressed without any loss of quality and are usually larger than JPEG files of the highest quality. TIFF files are uncompressed and larger than JPEG or PNG. TIFF files may be saved with 8 or 16 bits per color. The 16-bit TIFF format only makes sense for files converted from a RAW format supporting more than 8 bits per color (camera RAW files are typically 12 bits per color with noise in the lowest 1-2 bits). It is rare that the difference between 8 and >8 bits per color can be seen with the eye. However, an image with higher bits has more latitude when the brightness is altered with an image edit program like Fotoxx. If "make new version" is checked, then the file name will have a version number appended, either -02 if no versions exist for this file name, or the next higher version number if one or more versions exist. This makes it easy to save a modified image file without losing the original, or retain a series of changes. Any edits made to an image file are still active after the file is saved: [undo] and [redo] can be used, more edits can be added, and the image file saved again. The current image file is set to the (new) saved file if [Save As] was used and the directory was not changed. Use the menu File > Open Previous File to go back to the original image file if wanted.

File sizes for a 10 megapixel image are roughly as follows (depending on amount of detail):

tiff-16	tiff-8	png	jpeg-100	jpeg-90	jpeg-80	jpeg-70
58 MB	19 MB	14 MB	7 MB	2 MB	1 MB	0.6 MB

Print Image File

The print menu brings up a dialog where you can select a printer, a paper format (e.g. letter, A4), and an orientation (portrait or landscape). Use the [print] button to print the current image using the selected printer and paper format. You may also choose a format "custom" where the paper width and height can be edited to any reasonable values, in centimeters. The format is "custom N.N x N.N cm" and you must not change this - just replace N.N with your centimeter values (as in the predefined formats). Depending on your print software and printer, you may be able to see a "print preview" before printing, and you may be able to select the type of paper (plain or photo) and the print quality. Some of the predefined formats may not work for some printers. Margins seem to be a bit random. You can compensate by changing the paper dimensions: use the custom format with increased dimensions to get reduced margins on the paper. I have only been able to test with CUPS and an HP Officejet printer. I suggest you experiment with plain paper before comitting expensive photo paper.

Trash Image File

Starting with v.10.8, Fotoxx tries to use the new Linux desktop standard for trash. If it works, trashed image files go into the standard trash location and can be recovered later if wanted. If it does not work, Fotoxx puts trashed images into a desktop directory named "fotoxx-trash". You can delete it or move it to your Linux-specific trash. If standard trash does not work, you may be able to fix this yourself. See the technical note about this.

Rename Image File

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

Batch Rename Files

This function is helpful if you want many image files (perhaps with the same date or from the same event) to have the same names with an added sequence number. In the dialog, specify a base name, a starting sequence number, and an increment. For example, a base name of "arctic cruise-", a starting sequence number of 100, and an increment of 1 will produce a series of file names like this: arctic cruise-100, arctic cruise-101, arctic cruise-102, etc. (file extensions will not be changed). Use the button [select files] to open a file chooser dialog to select as many image files as you want. When done, press [proceed] to rename all the image files at once. Don't use this function to rename non-image files, since Fotoxx will also update file name and tag associations in the tag index file.

Tools Menu

Check Monitor

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

Brightness Graph

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

Clone Fotoxx

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

Slide Show

The image window is enlarged to the whole desktop, and the menu and toolbar are removed. A dialog pops up to ask for the time duration to show each slide. You can also use the keyboard for navigation (more). Use the escape key to get out of slide show mode. If a tag search is done before a slide show, these images are shown. You can use the function Tags > Edit User Comments to show the user comments for each image, in a small window which you can push to the side. The text is updated for each image viewed, and you can add or revise the text if wanted.

Show RGB

When a point on the image is left-mouse clicked, the RGB values are shown in a dialog window. The values have the format xxx.ddd, where xxx is the upper 8 bits of the color value, with range 0-255, and .ddd is the lower 8 bits, with range .000 to .999. The lower 8 bits are zero unless the image has been edited. Only the edit functions for color and brightness affect the lower 8 bits, and this data is preserved only if the image is saved in 16-bit tiff format.

Grid Lines

This function adds or removes horizontal and vertical lines across the image. The lines are useful when an image must be rotated for horizon alignment, or when an image is unbent or warped to straighten walls or other objects in the image. The settings for x- and y-spacing control the spacing (pixels) between the lines. If the controls for x- and y-count are NOT zero, then the x- and y-spacing values are ignored and the number of lines will be set to these counts. Example: set x- and y-count to "2" in order to divide the image into thirds. The x- and y-grid checkboxes can be used to enable and disable the veritcal and horizontal lines separately. The keyboard key G can be used to toggle the grid lines on and off: the x- and y-grid checkboxes are reversed.

Lens Parameters

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

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

Setting Lens Parameters Manually
Make a panorama image of a brick or tile wall with about 40% image overlap. Within the panorama pre-align process, adjust lens_mm and lens_bow until the overlapping bricks or tiles 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.

Change Language

This function allows you to change the GUI to one of the available languages. If your language is not available or has missing translations, consider making a translation, which is not difficult (more).

Create Launcher

This function puts a Fotoxx icon / launcher on the desktop and enters Fotoxx in the menu system in the category "Graphics". Your system must be LSB compliant (Linux Standards Base).

Convert RAW Files

This function converts one or more RAW image files to tiff-16 format, using the program "ufraw-batch". A file chooser dialog is opened. Choose one or more RAW image files (hold down the CTRL key to select multiple files). The image files are converted one at a time and displayed in the main window. Depending on the number of files, this can take a long time (my 2.67 GHz processor does about 18 image files per minute using a mix of raw file types).

Burn Images to CD/DVD

This function enables you to choose image files and burn them into a CD or DVD. When the function starts, an image gallery window is displayed from which you can select the image files to burn (link). When done, the list of image files is sent to Brasero to burn a CD or DVD.

E-mail Images

This function enables you to choose up to about 40 image files and send them to your preferred e-mail program. The e-mail program is started with the selected image files as attachments. You must then add the subject, text, and recipients, and finally send the e-mail. Press the [select files] button to display an image gallery window from which you can select the image files (link). After selecting the images, set the desired maximum width and height in the dialog. The [proceed] button will do the image reductions and send them to the e-mail program. The reduced images are put into a temporary directory (/tmp/<user>/fotoxx/) and do not affect the original images. This function uses xdg-email (Linux Standards Base) which must be installed and must work correctly for your Linux flavor.

Rebuild Thumbnails

You need to do this after first installing Fotoxx, if you add new image files to your collection, or if you move or rename image files or their directories. Nothing is lost when image files are moved, but the image gallery (thumbnail) windows will be slow. This is a self-healing problem in that a second visit to the same image files will be much faster. This function regenerates all thumbnail images to make all gallery windows fast. A dialog will ask for the topmost directory of your image files. That directory and any subdirectories containing images will be processed. If you have multiple image directories not within the same hierarchy, make one directory with links to all the others. The time required depends on computer speed and average image size. My 2.67 GHz computer does about 1600 images / minute.

Rebuild Tags Index

You need to do this if you are using tags or user comments (see Edit Tags and Edit User Comments), and you move or rename image files or their directories. Nothing is lost when image files are moved around, but the Search Tags function will fail to find the moved images. This function regenerates the tags index file from the tags and comments stored in the images. A dialog will ask for the topmost directory of your image files. That directory and any subdirectories containing images will be processed. If you have multiple image directories not within the same hierarchy, make one directory with links to all the others.The time required depends on computer speed and average image size. My 2.67 MHz computer does about 700 images / minute. Once the images have been indexed, searching them using tags and comments is almost instantaneous. This function also works incrementally: if only a few images have been moved (unknown to Fotoxx), then only these images are processed. The indexing should complete in seconds instead of minutes. There is a limit of 100K images. The index file is at /home/<user>/.fotoxx/tags_index.

Convert Tags (Important, please read)

Prior to version 10.0, Fotoxx used the EXIF key "UserComment" to save user-defined tags. This is the documented purpose of this key, but in reality another key is the predominate standard, and that is the IPTC key "Keywords". In order for Fotoxx to share tags with other programs, Fotoxx needs to conform. Fotoxx version 10.0 converts tags to the new standard. The menu Tools > Convert Tags does the job of moving tags from "UserComment" to "Keywords". The special keyword "Stars=N" is converted to the more standard EXIF key "Rating" (a 5-star rating system). Blank tag separators are replaced with semicolons (which seems to be the most common practice).

If you have created tags using Fotoxx prior to version 10.0, you must do the tags conversion before any image or tag editing is done, or else tags for edited images will be lost. You will be warned at Fotoxx startup to do the conversion. Nothing is deleted, so the conversion job can be repeated if needed, and the "Keywords" key will be written again. If the conversion fails, you can continue to use the previous version of Fotoxx (v.9.9) until the problem is fixed.

If you have tags from Fotoxx 9.9 or earlier, and you want to keep them, do the following:
(1) Back-up your image files
(2) Do the function: Tools > Convert Tags
(3) The function: Tools > Rebuild Tags will follow automatically
The process is slow: my 3800 image database required almost 30 minutes to convert.

If you have never used Fotoxx tags, or if you have tags from another program you want to keep, then do the following:
(1) DO NOT run the function: Tools > Convert Tags
(2) Do the function: Tools > Rebuild Tags

There were a few image files in my database (from a 10-year-old camera) which had EXIF structural errors and did not convert (exiftool output an error message). I was able to fix these using Fotoxx to save the image file to itself, and then Tags > Edit Tags to add the correct tags manually.

If you have problems, please write me at:
http://kornelix.squarespace.com/contact

EXIF Menu

Basic EXIF Data
All EXIF Data

The word EXIF is used to represent all the different forms of metadata contained in digital images. Fotoxx uses the program exiftool to read and write metadata, and therefore supports all metadata types supported by exiftool. These include EXIF, IPTC, IRB, ICC, and many others.

If the package exiftool is installed, the View EXIF menu will display EXIF data in the current image file, if available. EXIF data contains the date and time of a photo, shutter speed, focal length, pixel dimensions, etc. Most cameras store this data inside the image. If the image is edited and then saved, the EXIF data is updated and stored with the new image. The exiftool package must be installed if you want to retain EXIF data when an image is modified.

There are two menus for viewing EXIF data, Basic EXIF data and All EXIF data. Basic EXIF Data is a short report of the most commonly needed data, including the photo date and time, exposure data, focal length (real and 35mm equivalent), user-assigned tags and star rating, user comments, and a history of Fotoxx edit functions that have been applied to the image. All EXIF Data reports all available data, including IPTC and other categories supported by the program exiftool.

Fotoxx uses the following EXIF / IPTC keys:

Date/Time Original	Edit Tags function - image date
Keywords	Edit Tags function - image tags
Rating	Edit Tags function - image stars
User Comments	Edit User Comments function
Edit Status	history of Fotoxx edits applied to the image

Edit EXIF data

A specific EXIF key can be added or revised. Enter the key name and press [fetch] to retrieve existing data, if any. Enter the new data and press [save] to save the new or revised data. You may enter the key name in lower case and without blanks, e.g. the key "User Comment" in View EXIF Data may be more easily entered as "usercomment". The dialog is live: the current key name will be fetched automatically for each new image file opened, and it can then be revised and saved if wanted.

Delete EXIF data

This function allows deletion of a specified EXIF key, or all EXIF data at once. Input a key name in lower case and without blanks, e.g. the key "User Comment" in View EXIF Data would be entered as "usercomment".

Tags Menu

Overview
Image files can have classification tags (categories, keywords) assigned to them. These can be used to search a large image collection for those images having desired tags. Typical tags: the main subject of a photo, the associated event, the location, the person(s), etc. Tags reside inside the image (in the EXIF data) and are independent of its file name or directory location. You can use a directory hierarchy to make a physical organization of your images, e.g. directory names corresponding to year or location or other scheme. You can use file names for the main subject of the image. Such physical organizations are useful but optional: you can also put all your images in one giant directory and keep the numeric file names that come out of the camera. Regardless of the physical organization, "tags" can be used to create other organizations, e.g. label all the images of one person over all years, events, locations, etc. All images having a desired tag or tags can be found quickly and displayed in an image gallery window (thumbnails), where you can further review the images and choose those for viewing, editing, or changing their tags.

If you have used directory and image file names in a meaningful way, you can keep using these, and you can also search for images using these names as well as tags. There is no need to duplicate information already available. See "Search Tags" below.

Images may have a date (date of photo) which is pulled from the image EXIF data, if present, or manually set. Images may have a "star rating" for the importance or quality of an image. Dates and star ratings can also be used as search criteria.

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

A tag index file is used for searching, which makes it very fast (thousands of images per second are searched). The index is generated from the tags data inside the image EXIF data. Thus you can rearrange your image directories and image files without losing anything - you must only regenerate the index file, which is simple and fast. See Tools > Rebuild Tags Index.

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: 50 characters per tag
    o   max. tags for one image file: 1000 characters
    o   max. tags in a category: 10000 characters
    o   max. tags overall: 50000 characters
    o   max. tags in a search: 200 characters
    o   max. tags for Batch Add Tags: 200 characters

The practical limit for the overall number of tags is in the range 200-500. 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 sorted by category and within category), and the point and click method of adding tags will become more cumbersome. If tags are broadly defined and fewer in number, the search results will be larger, but using the search results (image gallery window) to find a smaller set of images is also quite fast. Physical file organization is also preserved in the gallery window (image files located together in their directories will also appear together in the gallery window). All in all, my recommendation for the casual photographer is to use fewer and broader tag categories.

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 "defined tags" window below. One of these tags can be added to the image by pointing and clicking with the mouse. A tag can be deleted by pointing and clicking within "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 repeatedly. Point and click the same way. The date of the image, if available, is shown as "image date". This may be entered if missing, or changed. You can enter a full date in the format yyyymmdd or a shorter format yyyy or yyyymm. A missing month or day is logically equivalent to "01" for search purposes. The [use last] button fills-in the date from the last date entered or shown. This is to allow easy dating of a series of images. You may enter an optional "stars" rating for the image. The dialog remains open if you navigate to a new image, and the current tags are filled-in from that image. The [Save] button writes the tag information to the EXIF data in the image file and to the tag index file for searching tags.

Tag Categories
You can assign categories to tags to help organize them and locate them more quickly when adding tags to images. They are optional and they play no role in tag assignment or searching: only the tag is stored in an image, not its category. Typical categories are people, places, things, events, landscapes, buildings, art, etc. When creating categories and tags, check "manage tags" to prevent clicked tags from being added to the image (if done accidentally, click the tag in "current tags" to remove). To add a new tag with a new category, enter the caterory and tag and click [create]. The category can be left blank and the tag will be assigned to "nocatg". To assign a tag to a different category, click a category (bold text) or enter a new one, click the tag, and press [create]. The tag will move from the old to the new category. To delete a tag, click the tag and press [delete]. The window of defined tags is updated to reflect changes. If you have a large number of tags and categories, expand the window to show more of them or use the scroll bar. Tags used in images but not assigned to a category will appear under "nocatg".

Batch Add Tags

When adding tags to a large number of images having many of the same tags (i.e. the same event or subject), use this function to speed up the process. In the dialog, use the [select files] button to open a gallery window with thumbnail images from which you can select the image files (link). After selecting files, specify tags to add to the images by clicking tags in the "defined tags" list. If you need a new tag, input the tag and press [create tag] to add it to the list. When done specifying image files and tags, press [proceed] to add all the tags to all the image files.

Batch Delete/Replace Tag

This function is used to delete a tag from many images at once, or replace a tag with another one. In the dialog, input a tag to delete and an optional replacement tag. Use the [select files] button to open a gallery window with thumbnail images from which you can select the image files (link). Alternatively, use the "search all files" checkbox to specify that the tag will be removed/replaced for all image files in the image database (all image files having the tag, as found with the Search Tags function).

Edit User Comments

This is a special function for editing EXIF data for the key "User Comments". Enter any text you want to associate with the current image. Multiple text lines of any length can be entered, up to an overall limit of 1000 characters. Press the [Save] button to save the text in the EXIF data for the current image. The dialog can be left open while navigating to different images. The current text for each image is shown, if any. Enter or modify the text and press [Save] to make the change permanent. If you need to enter (nearly) the same text for multiple images, you can use cut and paste. You can leave this window open in a corner of the monitor to show the comments as new images are viewed (also in Slide Show mode). You can search for images based on user comments (see topic Search Tags).

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 pageable image gallery window (thumbnails). Choose images to view or edit by clicking the thumbnails. The set of matching images will remain in effect for image navigation (the buttons [prev], [next]). The image set will also remain in effect when a member file is opened, saved, renamed, or trashed. If an image file is opened that is not in the set, then the current set (gallery window list) is replaced by the directory of the newly opened image file.

A date range may be optionally entered, to further restrict the search to images within the date range. The format is yyyymmdd. Images are selected which have a date on or after the first date, if present, and on or before the second date, if present. Missing mm or dd default 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.

Image directory and file names may also be searched, with simple wildcard matching. Example: in the input field labeled "/path*/file*", enter *egypt*cairo* to select all image files with "egypt" and "cairo" in the directory or file names. The matching rule is simple: * matches any sequence of characters anywhere in the full /pathname/filename. Example: the file /home/jack/aaa/bbb/xxx.jpg would match *aaa* and *xxx* and *aaa*xxx* but would not match aaa* or *xxx or *aaa/xxx*. You can enter multiple file search strings separated by blanks, and image files matching any of the strings will be selected. Name matching is not sensitive to case: both *aaa* and *AAA* would match the previous example. If file names include blanks, use quote marks around the search string, otherwise the blank will result in two separate search strings, e.g. *NYC parade* would be interpreted as a search for *NYC and parade*, so use "*NYC parade*" to keep the text together.

Image comments may also be searched (see topic Edit User Comments). Enter the words to search for in the dialog comments field, separated by blanks. These will be matched to every word in the user comments of all images, and matching images are selected. Wildcards can also be used here. Note: this feature is new with Fotoxx 10.11. If you have upgraded from a previous version of Fotoxx, then use the menu Tools > Rebuild Tags Index to index the user comments.

The options "match all tags" and "match any tag" apply to all matching options: tags, comments, and file name. You can select images having ALL the entered strings, or ANY of the entered strings. Example: if the /path*/file* field contains *egypt* *cairo* (with a space in-between) and "match any tag" is selected, then image files with either of these names within the directory or file name would be selected.

You can use user comments and directory and file names as an alternative to using tags. Effective use of tags can require high organization and attention to detail, and therefore lots of time. Also revising your tag organization can be very hard if hundreds of images are affected. User comments and file names are much easier. Simply name your image files with the key topic or content, and / or add comments with adequate descriptive words. You do not have to have an elaborate tag system, and revisions are easier. The tags system has the advantage that a complete list of available tags is automatically maintained and presented when you search images.

The example above: select images rated 4 stars or more, having either of the tags "gardens" or "scenery", and having either "hawaii" or "NZ" in the directory or file names.

If you have added, deleted, or moved image files outside of Fotoxx, be sure to run Tools > Rebuild Tags Index to get the search index synchronized with the actual image files.

Area Menu

Overview
Edit functions normally apply to the entire image, but it is possible to edit part of an image and leave the rest unchanged. If a smaller image area has been selected, then the following edit functions will be carried out within the selected area: white balance, flatten brightness, brightness/color, brightness ramp, expand brightness, tone mapping, warp area, sharpen, blur, reduce noise, and all art functions. The warp area function works only within a selected area. Other functions (trim, red-eye, rotate, resize, HDR, HDF, panorama, unbend, warp image) 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, prior edits are retained, and future edits (those listed above) will apply only within the area. 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.

Select Area

In the select area dialog, if an area is already there, it will be shown. You can continue to edit this area or use [Delete] to delete it and start a new area. Select one of the four methods (explained below) and proceed to define the area. Use the [Pause] button to suspend editing and free the mouse for zooming or scrolling a zoomed image to another position in the window. Use the [Resume] button to resume editing. The [Hide] button removes the area outline (for better visibility of image edits and edge blending). Use the [Show] button to show the outline. The [Delete] button removes the area, allowing another area to be started. The select area dialog can be exited and re-started later, to modify the selected area or start a new one.

There are four methods (described below) to enclose one or more spaces that will belong to the final area. These enclosed spaces will be affected by future image edits (brightness, color, etc.).

The four methods may be used in any sequence to define spaces that are joined or detached. Choose from the four corresponding radio buttons: Freehand draw: drag and click the mouse to draw lines to outline an enclosed space. Follow edge: click along the edge of an object in the image to draw lines that follow the edge, or drag the mouse to draw freehand. Select by color: select a small area of pixels around the mouse and aggregate adjacent areas with matching pixels. Radius: select or de-select a circular area around the dragged mouse position. The following paragraphs explain the details of each method.

Freehand draw: Drag the mouse (left button down) to draw a freehand (curvey) line, or left-click to connect a straight line from the last point drawn to the point clicked. Continue around the target area until it is surrounded with connected curves and lines. Right click to remove previous lines (mistakes) in order to re-draw them. A right click will remove the previous clicked or dragged line, up to 50 pixels. Right click repeatedly to remove more. A new clicked line will always connect to the end of the previous line. A new dragged line will connect to the previous line if it is started close to the end of that line. If it is started elsewhere, a disconnected line will be drawn. You can start a new drag from far away and draw back to meet the previous line. If a clicked line connects to an undesired point (i.e. you don't want to connect to the last line drawn), right click to erase it and then use drag to start a new sequence of lines. A right-button drag can be used to erase small segments: right-drag closely along a line to erase it, then left-drag to re-draw the line. At the end, an area must be fully enclosed, with no gaps. Lines that overlap a little at the ends are OK. Gaps can be difficult to find and correct, so work at 100% image size or greater and be careful. A series of lines automatically connected with left clicks will not leave gaps, but deviation from this sequence is likely to create gaps. To reduce the possibility of gaps, use deliberate overlaps when manually connecting lines.

Follow edge: High-contrast pixels (likely object edges) between the last point drawn and a newly clicked position are found and connected. This is effective for clear edges that are not too irregular. Fuzzy and ragged edges may not work well and freehand draw will be needed if high precision is necessary. The rules for connecting lines are the same as explained above. Dragging the mouse instead of clicking works like freehand draw, so you can switch back and forth.

Select by color: The "radius" control will define a circle around the mouse pointer. Click the left mouse button somewhere on the image to define a group of pixels to match. The group is defined by "radius" and the degree of match is defined by the "match" control (100 means a perfect match is required). Adjacent areas with pixels matching any of the selected will be selected and shown. A bigger radius or a lesser match value will select more pixels. If the mouse is dragged or clicked within the selected area, the selection will be expanded for any new pixels enclosed by the radius. Drag the mouse over new areas you want to include, or over "islands" of non-matching pixels you want to include. Watch the selected area expand accordingly. If you go too far, right click to remove the last selection. Repeat if needed to remove more previous selections. Reduce the radius or increase the match level to gain finer control - the selection will expand more slowly and stay closer to the mouse position. If the "color select firewall" is enabled, then already-selected pixels will act as a barrier to the propagation of newly-selected pixels. This is sometimes useful, e.g. an existing selection boundary needs to remain fixed and you want to extend the selection in the interior or from another boundary. You will need some practice to get a feeling for this and be able to work efficiently.

Select by mouse: Enter a value in the radius control. A corresponding circle will appear around the mouse pointer. A left mouse click or drag will select all pixels within the circle, and a right mouse click or drag will un-select all pixels within the circle (i.e. those that were previously selected). Use a large radius to rapidly enclose large spaces, and a small one to carefully follow along the edge of a subject in the image. For areas selected with one of the two "draw" methods, un-selecting with right click or drag will not work unless the area has been finished ([finish] button) beforehand - only then does the mouse know what pixels are already selected. Simply finish that area if you want to expand or reduce it using this method.

Pause / Resume: Use [Pause] to suspend editing and free the mouse to zoom or scroll the image. Use [Resume] to continue editing the area.

Show / Hide: Use [Hide] to hide the area outlines. This is useful when editing the image/area, to better see the effects of the edit without interference from the area outlines. Use [Show] to show the outlines and resume editing the area.

Finish: When you are finished selecting the enclised spaces, use the [Finish] button to complete the process. A popup dialog will ask you to click the mouse inside each enclosed space in sequence. This action launches a search for all pixels within the enclosed space, and these are mapped and saved. The enclosed space is temporarily colored so you can see exactly what part of the image is being selected. The dialog will show the status of the search, "success" or "there is a gap". If there is a gap in the outline (i.e. the space is not fully enclosed), an attempt is made to show where the gap is: you will see a line coming out of the colored space to meet the edge of an imaginary rectangle enclosing the space. You may be able to follow this line back to the gap, but if the area is convoluted finding the gap can be difficult. Each use of [finish] will produce a different picture that may lead you to the gap. When all spaces have been mapped in this manner, close the popup dialog.

Blend Width: Edits made within an area can be blended with the surrounding image over a distance called "blend width". At the edge of the selected area, the image is the original image. At a distance of "blend width" from any edge into the area, the image is the edited image. For distances in-between, the pixels are a mix of original and edited pixels with a gradual transition. Use the Blend Width control to set the blend width for the current or subsequent edit functions. Zero blend width gives a hard edge to the area edit. Increasing blend width makes the edges of the edit more gradual and harder to distinguish from the original image. Changing the value for the first time after editing an area will cause the edge distance to be calculated for each pixel in the area. This is normally fast (a few seconds), but it may take minutes if the area is large and has a complex geometry (a very long edge). Whenever an area is re-edited or inverted, the edge calculation is discarded and must be repeated if blending is wanted. If the edge of a selected area is within 4 pixels of the image edge, it is no longer considered an edge for blending. If a selected area includes a portion of the image edge, and you do not want blending along this edge (the normal case), be sure the edge of the area is tightly bound to the image edge.

Invert: This function inverts an existing area: the entire image is selected except for the existing area. Using the function two times returns the original selected area. Inverting a selected area invalidates the edge calculation which must be repeated if edge blending is desired.

Disable / Enable: Disable the current area and keep the data so that it can be re-activated later. This allows you to alternate edits within a selected area and edits for the entire image.

Delete: Delete the current area permanently.

Area Show / Hide

Show or hide the outline of the current area. Hiding the area is useful when the area is being modified with one of the edit functions. This makes it easier to judge the effects of the edit. These are also available as buttons in the Select Area dialog.

Area Enable / Disable

Disable the current area and keep the data so that it can be re-activated later (Enable menu). This allows you to alternate edits within a selected area and edits for the entire image. These are also available as buttons in the Select Area dialog.

Area Invert

Invert an existing area: the entire image is selected except for the existing area. Using the function two times returns the original selected area. Inverting a selected area invalidates the edge calculation which must be repeated if edge blending is desired. This is also available as a button in the Select Area dialog.

Area Delete

Permenently delete the current area. This is also available as a button in the Select Area dialog.

Area Copy / Paste

Copy: The current selected area is copied and saved in memory.
Paste: The saved area is pasted into the current image. It can be moved around by dragging with the mouse. Use the buttons [+10%] etc. to resize the pasted object. Use the edge blend slider to make a blended edge if desired. Press the [done] button in the popup dialog. The pasted area now behaves like a selected area. You can edit within the area and use the [blend width] control in the Select Area dialog.

Area Open and Save

If a selected area is active or has been saved with the menu Area > Copy, it can be saved to an image file using the menu Area > Save As. You are asked to supply a name. Two files are saved: the image is saved to filename.tiff and the edge distance data is saved to filename.dist. These files reside at /home/<user>/.fotoxx/saved_areas/. Use Area > Open File to choose a saved area, which will be dumped into the image where it can be moved around, resized, etc. as with the copy and paste functions.

Image Edit Menus

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 Toolbar [undo] and [redo] buttons can be used to review the before/after results for the last 99 edits of the current image. These buttons also work during an image edit to review the before/after results of the current edit function. When finished with an image, use [save] or [save-as] to replace the original image file or save to a new file.

Suggested Workflow:
Normal workflow: Most of the time you can just edit the JPEG that comes out of the camera. Use the following more complex procedure only if you see "color bands" after editing the image. Complex workflow: Convert the camera RAW file to TIFF, which will produce an image with 16 bits/color. The high color depth reduces the risk of visible "banding" from functions that can radically shift the brightness distribution (especially Flatten and Tone Mapping). When finished, convert the final TIFF to JPEG (quality level 70-90) to reduce the file size (from typically 50 MB to 2 MB). You will not be able to see a difference between the final TIFF and JPEG images. To preserve the possibility of re-editing the image later, keep the RAW file, which is much smaller than the TIFF file.

Retouch Menu

Adjust White Balance

This function is an easy way to remove a false color-cast, e.g. the whole image has an overall blue or red tinge. After strarting the function, click somewhere on the image that should have no color - a white or gray area. If that location has any color other than white or gray, it will be used as a measure of overall false color, and this amount of color will be removed from the whole image. You can click around on various areas and see the impact instantly. Press the [done] button when you are satisfied, or [cancel] if not.

Make Negative

Use this function to make a black and white or color negative, or convert a negative image into a positive image.
Select one of the four buttons:

black/white positive - convert a color image to black and white
black/white negative - convert to black and white and reverse brightness
color positive - do nothing at all, or undo one of the others
color negative - replace each RGB color with its compliment

Color negative: Each RGB color is replaced with the maximum value - the color value. For example, if the RGB colors (% of maximum) are 20/40/60, then the negative color is 80/60/40. Doing this twice brings back the original colors. This produces complimentary colors as follows: red becomes cyan, green becomes magneta, and blue becomes yellow.

Flatten Brightness

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

Brightness/Color

This function is used to change brightness, contrast, color saturation, and color balance (relative RGB levels). You can adjust all of these items as a function of the original image pixel brightness. To illustrate, you could increase color saturation in darker image areas and leave it unchanged in brighter image areas.

There are 5 response curves for the 5 image attributes of brightness, color saturation, and color balance (levels of red, green, and blue). The radio buttons select which curve is active and displayed. The curve represents a value (Y-axis) for each level of image brightness (X-axis). The middle Y-value is neutral (no change from the initial value). Higher and lower Y-values represent corresponding higher and lower settings for the 5 attributes. The initial curves are flat at the middle value.

The curves can be dragged up or down with the mouse. An anchor point (black dot) is added to the curve wherever it is pulled, and this becomes a constraint for subsequent pulls: the curve will continue to go through this point as other parts of the curve are pulled. Anchor points can also be dragged, or deleted by right-clicking them.

The image changes in real-time as the curves are moved. Simply move the curves and observe the image until you are satisfied. To increase overall contrast, use a brightness curve that slopes upward. The buttons [+++] etc. can be used to shift the whole curve in various ways.

Brightness changes all RGB values for a pixel by the same factor. Color saturation changes the dominant RGB color(s) within each pixel and moves other colors in the opposite direction, so that overall brightness does not change.

Brightness Ramp

This function can be used to compensate for uneven lighting such as vignetting (darker image periphery), left/right or top/bottom brightness differences, etc. The function dialog displays two editable curves, horizontal and vertical. The horizontal curve adjusts brightness horizontally, and the vertical curve adjusts brightness vertically. Move the curves in the directions labeled "+" and "‒" to increase or decrease the image brightness in the corresponding image area. To remove vignetting in the image corners, move both ends of both curves in the "+" direction while fixing the middle areas or even moving them in the "‒" direction. To brighten the upper right corner, move the right end of the horizontal curve and the upper end of the vertical curve in the "+" direction, as in the example above.

Expand Brightness

This function expands the brightness range of pixels having a brightness within a specified low - high range. Pixels outside this range will be clipped to have brightness zero and maximum, respectively, and the rest will be expanded to the range zero to maximum. This function is useful for improving a dull-looking or contrast-poor image, usually in preparation for other brightness and color adjustments or tone mapping. HDR can produce dull-looking images because the averaging of many input pixels may produce output pixels with less range than zero to maximum brightness.

Tone Mapping

Tone mapping increases the apparent brightness range of an image by increasing local contrast. It is especially useful to improve HDR images, but can also be applied to any image. HDR images often seem "flat" because the contrast between nearby pixels has been reduced to make the overall contrast fit within the available range (normally 8 bits per color). Tone Mapping increases the contrast between nearby pixels without increasing the overall contrast. It relies on the nature of human vision: contrast within a small angle is perceived more strongly than contrast over a large angle. Tone mapping also brings out subtle details (low contrast) that would otherwise be hard to notice.

Other methods can also be used: adjusting the brightness curve can increase contrast for a selected brightness range (possibly at the expense of others). Flattening the brightness distribution can spread the available contrast more evenly. Increasing color saturation can also bring out more detail. These methods operate globally: all pixels of a given color and brightness are processed the same. Tone mapping processes pixels differently depending on the brightness of surrounding pixels and is more effective at enhancing detail.

In the dialog, the graphic curve determines how much local contrast is increased depending on local contrast. The left end of the x-axis corresponds to low-contrast pixels and the right end high-contrast pixels. Raise the left side of the curve to increase the contrast of low-contrast pixels, but this will also enhance low-level noise. The Constrain slider below the curve regulates the internal algorithmic calculation, from no constraint on the left to full constraint on the right. If moved too far to the left, the image will show artifacts (bright or dark "rays"), so push it right until these disappear.

The curve can be dragged with the mouse and its effect on the image will show up in a few seconds (depending on image size and CPU speed). The constraint slider also needs a few seconds to show up in the image. If more contrast is wanted, raise the curve. If uniform areas (e.g. sky) become mottled, pull the left end of the curve down to reduce amplification for low-contrast pixels. In some cases it will be best to select different areas of the image and process them separately, e.g. more conservative for sky, more aggressive for textured surfaces like stone walls.

Remove Red Eye

This function reduces the red-eye effect from electronic flash photos. Two methods are provided. The first is faster but will not handle difficult cases (e.g. the eyelids are almost as red as the eye). The second method is more robust but also needs more time and care.

To use the first function, left-click on a red-eye one or more times until satisfied. If the darkened area is too small or off-center, do a right-click to undo the change and then left-click more precisely on the center of the red-eye. If a red-eye cannot be fixed correctly, right-click to undo 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 ellipse will appear enclosing the red eye. Repeat if needed to get the red eye centered in the ellipse (roughly). Note that the shape of the ellipse depends on the direction of the drag, which can allow more precise enclosure of only the red-eye. Left-click inside the ellipse repeatedly while watching the red eye darken, and stop when it is dark enough. If you go too far, the eyelids may start to darken. Right-click to undo and repeat if necessary.

Blur image

This function can be used to blur or un-sharpen an image. Each pixel is mixed with neighboring pixels to reduce the differences, making edges fuzzy. Enter a value for blur radius and press [apply] to see the results. A small value mixes each pixel with its nearest neighbors and larger values mix more distant pixels. The contribution from each pixel decreases with distance, so the nearest pixels have the greatest contribution. This function is useful to smooth mottled skin tones. You can use "select area" to limit the blur to a face or part of a face. This is also a way to cure "banding" in sky areas (this can happen if the flatten, brightness, or tone mapping functions cause the distribution to spread out, making the brightness steps perceptible).

Sharpen Image

This function sharpens a blurry image. Three methods are implemented: edge detection, unsharp mask, and gradient. Edge detection: find adjacent pixels with the largest brightness difference (contrast) and increase the difference. This is repeated for several cycles, with the threshold for brightness difference decreased each cycle. Unsharp mask: a fast and effective method also found in Gimp and other tools. A technical description can be found via Google. Gradient: pixels are processed left to right and top to bottom. The brightness difference (contrast) between each pixel and its prior neighbors (left and above) is increased, and the pixel brightness is modified to match. This brightness change is propagated to the next pixel where the process is repeated.

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 primarily affects the blurry areas, whereas unsharp mask may put "halos" around edges that are already sharp. The gradient method works about as well as unsharp mask for slightly blurry images. The radius value limits the distance over which pixels around an edge are changed. It should be small (1-2) for images that are slightly fuzzy and larger for poorer images. Threshold suppresses changes to low-contrast pixels: a higher values reduces the amplification of low-level irregularities.

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

For the unsharp mask 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

For the gradient method, enter the following parameters:
   amount        amount of correction, 100 = normal
   threshold     brightness change low cutoff threshold

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. Use Select Area to operate on different parts of the image with different methods and parameters.

Reduce Noise

This function reduces the noise present in photos taken under poor lighting conditions, making uniform surfaces appear speckled. Choose one of the methods described below. Press the [reduce] button repeatedly while watching the image. If you go too far, sharpness and detail will be lost. The radius input determines the area around each pixel that is compared. A default radius is set when a method is selected, but other values may work better. For a large image, these algorithms may run a long time. To save time, select a small area and experiment with the different methods and radius settings until you make a decision, then clear the selected area and apply the chosen method to the whole image. There are four different methods, and each method applies to each RGB color independently.

Flatten outliers by color: the highest and lowest pixel values within a radius are moderated slightly.
Flatten outliers by color: pixels are compared to the mean and sigma of pixels within a radius. Those outside one sigma are moved back toward the mean by half the excess over one sigma.
Set median brightness by color: pixels are set to the median value of their neighbors within a radius.
Top hat: detect outliers by comparison with a band of pixels some distance away. The comparison distance is increased in steps from 1 pixel to the radius limit.

Transform Menu

Trim Image

The HDR, HDF 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 selection rectangle is drawn (using previous trim dimensions if they fit within the current image size). Click or drag near any corner of the rectangle to move that corner. When done, press the [apply] button in the dialog box to cut-off parts of the image outside the selection rectangle. The dialog box shows the current width/height ratio of the selection rectangle. If the box "lock ratio" is checked, then moving one corner of the rectangle will also move the opposite corner to keep the same ratio. You can also drag from the middle of the rectangle to shift the whole rectangle without changing its dimensions.

The six ratio buttons allow you to choose a preset width/height ratio. The button [invert] exchanges the width/height ratio (2:1 becomes 1:2 etc). You can change the ratio button names and the corresponding ratios with the button [customize] which starts the second dialog shown above. Enter desired button names in the first row of six text entry areas, and enter the corresponding width/height ratios in the second row (the default names are the same as the ratios, except for "gold"). Use the format "width:height", e.g. "16:9" for the HDTV format. The default [gold] button uses the golden ratio, about 1.618:1. You do not have to keep it.

Resize Image

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

Batch Resize

This function is used to resize many image files at once (for planned uploads to a web site, to save disk space, etc.). The menu opens a dialog to select image files and specify options. Use the button [select files] to select image files from a gallery window (link). You can select the option: "replace originals" or "export to location". For the latter, input a directory where the resized image files will be written, or use the [browse] button to locate the directory. Finally, use the [proceed] button to start the resize process. A popup window shows the progress. If the replace option is chosen, EXIF data (including tags) will be preserved. If the export option is chosen, use the checkbox to determine if the EXIF data is exported or omitted. Restriction: resized image files are JPEG regardless of the file type of the input files.

Annotate Image

This function provides a way to edit descriptive text and write directly on the image. Enter the text into the dialog. Multiple lines can be used. After editing the text in the window, left-click the mouse where you want the text on the image. Click again to move the text elsewhere, or drag the text. Right click to remove the text. Use the [font] button to select a different font and size. Use the [size] control to quickly increase or decrease the text size. Use the [angle] control to change the angle of the text. The foreground (text) and background colors and transparency can be adjusted. The example shows red text on a blue background, with the background being 40% transparent, meaning that the (faded) image shows through the background. The [open] and [save] buttons start a file chooser dialog with which you can load or save all annotation data from or to a file. All the data in the dialog are loaded or saved (text, font, etc.). Thus you can keep a collection of often-used annotations.

Making a Watermark: use a foreground transparency of 70% or more and a background transparency of 100%. The text should be faint but readable. To add a "relief" effect, use Select Area to put a box around the text and use the function Art > Simulate Embossing to raise the text (if brighter than the image) or recess the text (if darker).

Rotate Image

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

Flip Image

Choose either horizontal or vertical flip from the dialog. The image is reversed vertically or horizontally. Repeating the flip restores the original image. Doing both a horizontal and vertical flip is the same as a 180 degree rotation.

Unbend Image

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

Warp Image (area)

This function can be used to make distortions within an image. You can select an image area and drag the mouse to stretch this area with respect to the rest of the image. The image reacts as if made of rubber. The movement is maximum at the mouse pointer and declines to zero at the edges of the selected area. Many mouse drags of different lengths and directions can be combined to achieve the desired results. The [undo last] button will remove the most recent stretch (up to the last 100). When finished, you can select another area and do some more warping, or select [done] to exit the function. The method used limits loss of resolution from repeated warps: for each warp step, the total movement of each pixel is accumulated and the original image is warped to the latest pixel positions. The pixels are interpolated to reduce jaggies and improve sharpness.

Warp Image (curved)

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

Warp Image (linear)

This function is useful to correct perspective problems (see also "Unbend"). Drag the image from any position, using the mouse. The entire image will be pulled or pushed in the direction of the mouse, but areas near the mouse are moved more than more distant areas. You can straighten curved lines or deliberately curve the image. This function works over a broader area than the curved warp and causes less image curvature. To minimize the addition of curvature, pull only on the image corners.

Warp Image (affine)

This function can be used to warp an image in interesting ways. Drag the image from a corner or edge using the mouse. The changes are purely linear so straight lines remain straight. This transform is called "affine". Technical details can be found with Google.

Art Menu

Color Depth

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

Simulate Drawing

This function transforms a photo into a black and white high-contrast image or into a line drawing where only the edges of objects are shown as black lines on white background or white lines on black background. The sliding control "contrast" will deepen dark areas to black. The sliding control "threshold" will convert the image from gray-scale to black and white. The sliding control "outlines" will highlight high-contrast pixels (edges of objects) and suppress low-contrast pixels. This can be black on white or white on black, depending on the selection of the radio buttons "pencil" and "chalk". Manipulate both "threshold" and "outlines" to find the best balance.

Simulate Embossing

This function transforms a photo into a simulated relief or embossed image. The "radius" setting determines the feature size or level of detail. The "depth" setting determines how deep the features go into the surface.

Simulate Tiles

This function transforms a photo into an array of large monocolor tiles. You can control the tile size and the thickness of the space between tiles (caulk, grout). This is also called "pixelate" or "pixelize".

Simulate Painting

This function transform a photo into something looking more like a painting. It reduces the number of colors, maps each contiguous pixel area having the same color, and then consolidates smaller areas into adjacent larger areas having the best color match. Four user settings control this process: "color depth" sets the number of colors to be used (bits per RGB color). 1 = 8 colors, 2 = 64 colors ... 5 = 32768 colors; "target group area" sets a lower limit for areas that will have their own color: areas smaller than this number of pixels will be absorbed into an adjacent area with the nearest color match; "req. color match" sets the minimum color match required for a smaller area to be consolidated into an adjacent larger area: 0 = don't care (maximum consolidation), 100 = perfect match required (no consolidation); "borders" determines whether the colored areas will be delineated with a thin black border, like irregular tiles in a mosaic. After using this function, using the "emboss" function can add interesting texture to the image.

Edit Pixels

This function changes individual pixels. There are three modes of operation: pick, paint, and erase. Pick mode: click anywhere on the image to set the current color. Paint mode: click or drag anywhere on the image to paint with the current color. Erase mode: click or drag anywhere on the image to restore modified pixels to their original color. The button [color] allows you to pick a color using a color wheel, and it always shows the current color. The "brush radius" control sets how large an area of pixels will be changed with each mouse click or drag. The "transparency" controls determine how intensely the color is applied at the center and edges of the brush. Zero transparency applies the full color immediately whereas a high transparency (90-99) applies a little color and allows you to gradually change the color using many clicks or drags (analogous to spray painting from a distance). Erase also works this way: use zero transparency to immediately erase, and high transparency to erase gradually. The [suspend] button releases the mouse so you can use the mouse to scroll or zoom the image. The button changes to [resume]. The [undo_last] button removes the last edit (modifications from the last click or drag operation), and this can be repeated to remove many recent edits. The memory for undo operations is limited to 200 megabytes, which can be reached if you make many edits using a large brush (every change to every pixel is saved). It is useful to save the image after each satisfactory change to free this memory. The amount of memory available is displayed in the dialog, so you can see when the limit is approaching. If a selected area is enabled, the painting is confined within the area. You can select an area by color and then change the color without taking care about the edges. NOTE: zoom the image to 100% or more when using this function. If the mouse steps are larger than the image pixels and a small brush is being used, some pixels may be skipped by the mouse and cannot be painted.

Combine Menu

Make HDR Image (high dynamic range)

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

Select the HDR menu function. A file open dialog is started to select up to 9 image files, which must all have nearly the same pixel dimensions. The images are aligned and combined automatically, which may need a minute or more. When done, the combined image is shown, along with a dialog for manual adjustments. The contributions from the input images are shown as a series of editable curves. The horizontal scale represents pixel brightness, from dark to bright white. Each curve represents an image which contributes to the pixels. The image contribution at a given brightness level is proportional to the height of its curve at that level. The curves can be edited by dragging them with the mouse. The anchor points (small squares on a curve) can be pulled around while others remain fixed. The corresponding image contributions are changed accordingly, and you can see the results in quasi-real-time in the output image. Right-click on an anchor point to remove it. In general, the brightest image should have a higher contribution to the darker pixels, and the darkest image a higher contribution to the brighter pixels. You will likely need practice to become effective at working the curves.

A faster and easier alternative may work as well: after the images are combined, ignore the curves and exit from HDR. Use various edit functions to refine the image: Flatten, Expand Brightness, Brightness/Color, and Tone Mapping. Select Area can be used to enclose any area in the image which needs more brightness, color, or local contrast, so you can apply different methods and parameters to different areas.

Make HDF Image (high depth of field)

HDF combines (overlays) multiple photos of the same subject with different focus settings from near to far. Different parts of the subject are in sharp focus in each image. The idea is to combine the images so that all parts of the subject are sharp. This technique is most useful for extreme close-ups.

Making the photos: choose a point for the center of the image. Aim the camera at a near object and depress the shutter button 1/2 way to set the focus on this object. Hold the button at the 1/2 position, aim the camera at the chosen center, and snap the photo. Now choose a farther object and do the same. Repeat with increasing focus distance. Hopefully each part of the subject is sharp in at least one photo. The camera position should be very nearly the same for all photos, which can be a challenge when the subject is very close. Camera movement can cause scaling and parallax problems (nearer objects shifted against farther objects). Such problems may be fixable later in Fotoxx, but this may require considerable time. It is better to avoid the problems.

Processing the photos: in Fotoxx, choose the HDF menu function and select up to 9 images. The images will now be aligned as well as possible. This may take a minute or more per image, depending on image size and CPU speed. The output image is an even mix of the aligned input images. A small amount of camera movement between the photos is compensated, but this is limited, and parallax shifts are not compensated at all. When the alignment is complete, a dialog opens. You can select any input image and "paint" with the mouse on any area of the output image. This converts the original mix to the selected image for the area being painted. The radius of the paintbrush can set larger or smaller, so you can paint large areas quickly and control fine detail when needed. If you have overlapping near and far objects, time and patience will be needed to make all of them sharp. The examples in the fotoxx gallery took about 5-10 minutes each, but the object overlaps were also minor.

Misalignments can be corrected by selecting the "warp" option in the dialog. The underlying images can then be dragged and warped with the mouse, and the composite output image is changed accordingly. The warp is limited to the area around the mouse. When a painted area is dragged, the corresponding image is automatically selected and dragged, while areas painted with other images remain fixed. Areas that have not been painted cannot be dragged. Move around to different areas and make incremental drags until all areas are aligned.

Suggested workflow:
Using paint mode, choose each image in sequence and paint all areas that look sharp with that image. Any boundaries that are not well-aligned will show up clearly as shifts in the edges of objects. Some of these can be made unimportant by changing the image used for painting (if more than one image is sharp enough). Use [suspend] to free the mouse to zoom and pan to other areas. The button is changed to [resume], and will re-activate the painting mode. Using warp mode, make fine adjustments as needed to eliminate visible shifts. Use [suspend] and [resume] as needed to zoom and pan to other areas.

Stack Images

This function combines 2-9 images (photos) of the same subject. The photos should be nearly the same, except for small offsets caused by a hand-held camera. If the photos were made with a very high ISO setting (low light conditions), the pixels will have considerable noise. By making many photos and averaging them, the noise can be mostly eliminated.

Making the photos: choose a point for the center of the image. Take several photos using the same center and being careful not to shift or rotate the camera too much. The more photos the better. Up to nine can be used with Fotoxx, but you can take more in order to have some to discard if they are not sharp, a common problem with low light conditions and long exposure times. In Fotoxx, chose the Stack function and select up to nine image files. They will be combined automatically and shown, and then a dialog will open.

The initial output image is a combination of all the selected input images, averaged together. This means that the RGB values for each output pixel are the average of the RGB values for the corresponding input pixels. A few alternative tools can be used to possibly reduce the remaining noise a little more. The "use median" button will change the output pixels from an average of the input pixels to the median of the input pixels (1-3 "middle" RGB values are averaged, depending on the number of images). This may or may not be better, so switch back and forth to compare (the screen update may need several seconds). The checkboxes for "omit low pixel" and "omit high pixel" will cause the lowest and highest RGB input values to be discarded before the average is calculated. This may help to get noise spikes removed from the mix. This has no effect on the median calculation.

Make a Panorama Image

This function stitches 2-4 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.

Using the panorama menu function, select 2-4 image files. The images are initially joined and shown with a small transparent overlap. A pre-align dialog pops up asking you to drag the images into rough alignment. Drag the images with the mouse to align them to each-other. It works best to proceed from right to left. Change the order by dragging an image until it trades places with a neighbor image. Rotate an image by dragging the BOTTOM edge. Use the [resize] button to get a bigger combined image after moving them closer together.

The images should be correctly curved and fit together well. If they do not fit, you need to set the lens parameters as described under "Lens Parameters". You can adjust these parameters within the pre-align dialog until the images fit reasonably well, and this may be good enough. The lens mm parameter (focal length) is obtained from the EXIF data if available. The lens bow parameter (curve distortion) must be adjusted manually, but this is often insignificant and can be left at zero.

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. This may take a minute or more per image, depending on CPU speed and image size.

When fine alignment is complete, the combined image is displayed. A dialog pops up for fine adjustment of brightness and color match. You may see a sharp border because the images do not have the same brightness and color balance. The [auto color] button can be used to perform an automatic color match, which is usually the best starting point. The other controls allow you to make additional changes to better match the images. Change the values for brightness and color and press the [apply] button to see the results. Use [auto color] to match the other images to the one changed. Use [file color] to restore the original values from the input image files. The "blend width" input governs how the images are blended together: at the image joints, 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 unbend, image warp, rotate, trim, and other functions for final adjustments.

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

Panorama Limitations
Panoramas including nearby objects can be tricky: when the 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 shifting foreground objects (parallax). This is not an issue when the subject is 50+ meters away, since a small lateral movement has little impact on the image.

Help Menu

About
This displays a short message about the Fotoxx version number, license, credits, and contact address.

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

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 be aware of.

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

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

Home Page
Shows the Fotoxx home page from the Internet. Look here for program updates (the page named "recent changes"). This page is published via RSS and you can subscribe to get timely notification of changes.

Technical Notes

Translations
See the menu Help > Translations or the text file TRANSLATIONS for guidance on how to modify an existing translation or make a new one. This is a fairly simple process: edit a text file with English text strings followed by their corresponding translations. See one of the existing translations as an example, e.g. /usr/local/share/fotoxx/locales/de/fotoxx.po (the German translation). A new translation for language code xx would be saved at /usr/local/share/fotoxx/locales/xx. After making such a file, you can test it by starting Fotoxx on the command line: $ fotoxx -l xx.

Hardware and Software Requirements
Fotoxx works best on a fast computer with at least one gigabyte of memory. Multiple CPU cores are utilized for compute intensive functions (e.g. sharpen, rotate, warp, tone mapping, HDR, panorama). Slower computers (notebooks, netbooks) will work, but will be quite slow for some functions. Monitors smaller than 1200x800 will feel confining for some functions. The typical notebook screen with limited brightness and color should not be used for image retouching.

Packages Required by Fotoxx
Fotoxx requires the following libraries and programs to function at run time:
   libtiff4        read and write tiff files, 8 and 16 bits per color
   xdg-utils          open text or html files with user's preferred application
   exiftool              read and write EXIF data, including user-defined image tags and comments
   ufraw-batch      import raw image files from a digital camera
   brasero        burn a CD or DVD with selected images

Packages Required for Fotoxx Source Build
See the README file for instructions on compiling Fotoxx from source.
In addition to the programs listed above, the following are also needed:
   g++                   GNU C++ compiler
   libgtk2.0-dev Gnome GTK/GDK/Pixbuf/etc. development files
   libtiff4-dev             tiff library development files

Command Line Options
   fotoxx /.../imagefile.jpg      # initial image directory or image file to open
   fotoxx -l lc                            # language code to use for GUI (de, fr, es, ...)
   fotoxx -v                         # output version and build date and exit

Status Bar Information
   navigation:      1234x987x24 0.45MB 56% edits: 3
Explanations:
   1234x987x24    image width x height x depth (bits per pixel)
   0.45MB          image file size (updated when a modified image is saved)
   56%            zoom status, image % size
   edits: 3       3 prior versions are now saved in the undo stack

File Types Supported
Fotoxx uses two libraries to support reading and writing of image files: the GDK pixbuf library and libtiff. Pixbuf supports JPEG, PNG, ICO and BMP files, all with 3 RGB colors and 8 bits per color. Libtiff supports TIFF files with 1-bit depth (bi-level), 8-bit and 16-bit grayscale, and 3 RGB colors with 8 or 16 bits per color. Other TIFF formats are not supported by Fotoxx, although they could be added if there is a need. Bi-level and grayscale images are treated as RGB inside Fotoxx, with all RGB colors set to the same value (shades of gray). Fotoxx converts camera RAW files to TIFF RGB with 16 bits per color (using the program ufraw).

Missing Toolbar Button Text
This is a Gnome configuration issue. The default varies with the phase of the moon. Open a terminal window and give the command "gconf-editor". In the dialog, select desktop > gnome > interface. Set the toolbar style to "both", meaning icons and text.

Color Depth
8-bit color (256 brightness levels), as supported by JPEG files, is the norm for image files and is usually adequate. LCD monitors are limited to 8-bits, and the effective brightness range for photo paper is less than 8 bits. One brightness step (averaging 1/256 or 0.4% over the gamma range) is very hard to see. 16-bit color can be useful if a narrow brightness range within an image has been greatly expanded (via various retouching functions). This expansion within a narrow range can lead to visible "banding" or "picket fence distribution". If the image has a 16-bit color depth, this effect can be reduced, even after the image is truncated back to 8 bits for storage (JPEG) or display on a monitor.

Alignment Algorithm (HDR, HDF, Panorama)
5000 high-contrast or "edge" pixels are selected to control alignment in HDR, HDF, and Panorama. The actual pixels used are shown in red during the alignment process, which is also entertaining. For Panorama and HDF, one image is systematically warped various small amounts and the fit with the other image is tested. This is done because two photos made with slightly different horizons or rotations will not fit perfectly with simple translation and rotation.

Tone Mapping Algorithm
The method used by Fotoxx is home-made, but inspired by Fattal and other gradient-based methods. It is not as effective as fattal in some cases, but close. On the other hand, Fotoxx is both fast and simple. The source code is about 250 lines, including the GUI and multi-threading.

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

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 if you save and open the image file between edits: rotate (other than 90 degrees), HDR, HDF, panorama, unbend, warp. Resize to a smaller size 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: white balance, flatten, brightness/color, brightness ramp, expand, tone mapping, red eye, sharpen, reduce noise, trim, flip, and all art functions.

EXIF Errors
Cameras (esp. older ones) do not always produce structurally correct EXIF data, and the program exiftool (used by Fotoxx to manipulate EXIF data) may produce error messages. I have been able to fix these cases by saving the image file on top of itself, which will replace the EXIF data with whatever exiftool was able to read correctly. If tags get lost, you must restore them manually.

Standard Trash Directory
If the Fotoxx [trash] menu and toolbar button does not put trashed image files into the standard wastebasket (where they are also recoverable using the GUI wastebasket browser), you may be able to fix this yourself. If your image files are not on the root disk or the /home disk, there may be no wastbasket directory by default. You can add one yourself following this example: if the disk containing image files is mounted at /images and your UID is 1000, there should be a directory named /images/.Trash-1000, owned by UID 1000, with full permissions for UID 1000. The standard trash function will put trashed files there. Add this directory manually if it is not there. This may fix the problem.

Special Fotoxx Files
The following files reside in /home/<user>/.fotoxx/. The tags_index file duplicates data contained in the EXIF and IPTC metadata within the image files. It is there because it can be read 1000 times faster than reading the image files.

/annotations/filename	annotation data files saved from the Annotate Image dialog
/saved_areas/filename	"cutout" files saved from the Area > Save dialog
fotoxx.log	fotoxx outputs that may be relevant for diagnosing problems
parameters	setup parameters that are saved across fotoxx sessions
printfile.jpeg	the last file printed with fotoxx
recent_files	a list of the last 30 files opened by fotoxx, saved when fotoxx exits
search_results	a list of the last image files found with the Search Tags function
tags_defined	a list of all tags currently used in all images
tags_index	a large file containing current tags and comments for all image files

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

Questions and Problems
If you have a question or run into a problem, contact me. If you send any images that work poorly, I can use these to try to improve Fotoxx. If there is a traceback dump on the screen, or error messages in the log file /home/<user>/.fotoxx/fotoxx.log, please send these also.

How to get a traceback with source code line numbers
If you have a "crash" problem, it is much easier for me to debug and fix if I can get a traceback with source code line numbers. Here is a method to produce this traceback: In a terminal, run the command: gdb fotoxx. Fotoxx will start under control of the Gnu debugger program: gdb. In fotoxx, do whatever makes it crash. The gdb program will say it crashed. In gdb, enter the command "backtrace". After this, enter "q" (quit) and "y" (yes, really quit). Copy all the gdb output from the terminal window, paste into an e-mail message and send it to me, along with a description of what you did leading to the crash.

Technical Reference Book
I recommend the book "Introduction to Image Processing and Analysis" by Russ and Russ, CRC Press. It is clear and concise. The following algorithms were adapted from this book: flatten brightness distribution, unsharp mask, noise reduction (median smoothing, top hat), simulated embossing. The affine transform method for image warping and rotation was found via Google.

Acknowledgements
The programs libtiff, ufraw, exiftool and brasero have helped Fotoxx evolve much faster than otherwise possible. Of course this also applies to GTK, GDK, the pixbuf library, the GNU tools and libraries, and the entire Linux ecosystem. Thanks to those who have donated their time for translations and testing (see Help > About), and those who have donated their ideas for development.