fotoxx user guide

Fotoxx User Guide v.12.01

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.

User Guide changes for this version can be found here.

Getting Started

When you see the word directory, substitute folder if this is your way of thinking. The terms file and image and image file mean a single computer file of type .jpg .png .tif etc. containing a single image (photograph).

Installation
To install Fotoxx, 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 system menu after installation (or maybe after a new login). If not, use the command "fotoxx" in a terminal window or launcher.

Initialization
Fotoxx needs to know where all your image files are located (directory and file names) and their imbedded metadata (if any): tags, captions, comments, ratings and dates. These must be indexed for fast searching. Fotoxx also needs to create thumbnail images so that the gallery windows (thumbnail pages) will work fast. When Fotoxx starts, it checks for a top image directory and index file. These will be missing the first time Fotoxx is started, and a popup dialog (Synchronize Files) will ask you to supply a top image directory so that your image files can be found and indexed, and thumbnail files created. The top image directory is simply a directory containing all your image files (or subdirectories with image files). This is typically named "/home/<user>/Pictures" or similar. Use the [browse] button to locate this directory and press [proceed]. A popup window will list the image files as they are indexed. If you have many thousands of images, this will need some time to finish (a fast computer will do over 1000 images per minute). Fotoxx does not change or copy the image files - it only reads them to get data for the search index and to make thumbnails. After this function has finished, the gallery windows will be fast and the Search Images function will be very fast.

If you start Fotoxx after new image files have been added to your collection, the synchronize function starts automatically. A popup window will list the new image files found. You can use Fotoxx normally to navigate and view images, but editing images will be blocked until the synchronize function is finished. This normally needs a few seconds unless there are hundreds of new images to process. The popup window is left open for your inspection. You can close it at any time, but synchronize will always continue to completion. For more details, see the topic Synchronize Files.

Test Run
After Fotoxx finishes initialization, use the [open] button on the toolbar to select an image file to view in the main window. Choose the menu Retouch > Brightness/Color, and in the dialog use the [+++] button to brighten the image. Use the [cancel] button to leave the dialog without changing the image file on disk. Use the [gallery] toolbar button to see all the images in the current directory as thumbnails in a new window. Use the navigation buttons on the gallery window to navigate within the directory. Use the [parent] button to leave this directory and choose another. Click on a thumbnail image to view the image in the main window.

Essential Information for those who hate big user manuals:
o Menu functions and dialogs have live help activated by keyboard F1.
o Mouse left click: zoom image bigger and move center to mouse position.
o Mouse drag across a zoomed image: scroll and pan the image.
o Mouse right click: un-zoom image to fit in the window.
o Gallery button: thumbnail browser: view all images in current directory.
o Click image in thumbnail browser: show image in main window.
o The status bar at the bottom of the main window contains status information.

Fotoxx Startup: To start Fotoxx, use the command "fotoxx" in a launcher or terminal window. Command line options are listed in the Technical Notes section.

This User Guide is available in the menu Help > User Guide. The F1 key will bring up a help topic for the current menu or dialog. This appears in your chosen web browser (and can get hidden under the Fotoxx window).

Mouse Actions on Main Window
To zoom the image in the main window, left-click a position on the image. The image will grow with each click and the clicked position will move toward the center. A right-click will restore the image to fit within the window. To scroll a zoomed image, left-drag the mouse across the image. This works like invisible scroll bars: the image moves in the opposite direction of the mouse. Diagonal scrolls work. The mouse wheel may also be used to zoom the image in or out. The middle mouse button (wheel) will make a zoomed image re-center at the mouse position.

Mouse Ownership
Some dialogs use the mouse to reference or alter the image in the main window. There may be more than one such dialog active at the same time. The mouse is also used to zoom and scroll the image, and you may need to do this while using a dialog. Therefore it is important to understand who owns the mouse (dialog or main window) and how to change the ownership:
1. The mouse is owned by the dialog that was last clicked or modified. Mouse cllicks and drags on the main window are inputs to this dialog and DO NOT zoom or scroll the image.
2. To zoom or scroll the image while a mouse-using dialog is active, press the CTRL key before clicking or dragging the mouse. The mouse acts on the main window and the dialog is not affected. The mouse wheel can always be used for zooming the image - the CRTL key is not needed.

Dialog buttons mostly work as follows:
   Proceed - close dialog, proceed with lengthy task.
   Apply - apply settings from dialog, leave dialog active.
   Done - keep dialog changes and close dialog.
   Cancel - discard changes and close dialog.

General Editing Procedure
The image in the main window (the current image) can be operated on with the edit functions (in the menus Transform, Retouch, Art, Combine). These functions modify the current image in memory. 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 current active edit function. After the function is closed (dialog [done] or [cancel]), these buttons can be used to review all the edits done to the current image (up to 99). When finished editing an image, use [Save] to replace the original image file with the modified one. Use [Save+V] to save the modified image with the original file name appended with a version number (both are kept). Use [Save+F] to save the modified image to a new file.

Many image edit dialogs have sliders, spin buttons, or editable curves that update the image in the main window. The reaction time depends on the size of the image, the complexity of the function and the speed of your computer. This is typically <1 second for a fast computer.

Curve Editing:

Several image edit functions use editable curves. You can manipulate the curves to change some property of the image (e.g. color saturation) depending on some other property (e.g. brightness). To illustrate, you could increase color saturation in the darker areas of an image without changing it in brighter areas. Generally, the X-axis of the curve represents the input property (brightness in the prior example) and the Y-axis the output property (color saturation). The curves can be moved (pulled) with the mouse. "Up" increases the effect of the current edit function and "down" decreases the effect. 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. Delete by right-clicking them. The curve edit windows have buttons [open] and [save] which can be used to load a curve previously saved to a file. This may reduce the time to edit the curves for a series of images receiving the same treatment.

Simple Workflow
Most of the time you can just edit the JPEG file 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 "color bands" 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+) to reduce the file size (from typically 50 MB to 2 MB). You will almost never be able to see any 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.

Suggestions for how to organize a large image collection can be found here.

Selecting Images from an Image Gallery Window
This procedure is used in several functions which use or modify multiple image files (batch add or delete tags, batch convert images, others). It is explained once here, and this paragraph is linked from each of the functions using this procedure.

When image files are selected, 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 gallery window to other directories and choose images in any order. 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. The next image file added will be inserted at this position. If the [delete] button is pressed, the current list position 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 Images to establish a set of images, the gallery window will contain this set. You can select individual images from the gallery, or use [add all] and then delete unwanted images.

Fotoxx Menus and Toolbar Buttons

File Menu	File Management
Image Gallery	Show thumbnail images - image files in the current directory (more).
Clone 50/50	Clone Fotoxx and share the desktop 50/50 with the old instance (more).
Clone Overlay	Clone Fotoxx and open a new window slightly offset from the old one (more).
Open Image File	File open dialog - open an image file to view or edit (more).
Open in New Window	File open dialog - open new file in a new window (more).
Open Previous File	Go back to the last image file opened (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 Version	Save modified image to the same file with a new version number appended (more).
Save to New File	Save modified image to a new file (more).
Create Blank Image	Create a new blank image file (more).
Trash Image File	Move an image file into the trash bin (more).
Rename Image File	Rename image files, optionally add sequence numbers (more).
Batch Rename Files	Rename many image files using a base name and sequence number (more).
Print Image File	Select printer / paper format / orientation and print image (more).
Quit Fotoxx	Exit from Fotoxx.

Tools Menu	Utilities and setup functions.
Manage Collections	Make image collections, arrange the sequence, etc. (more).
Move Collections	Update collections when image top directory is changed (more).
Batch Convert	Convert / resize / export images (for upload to the web, e-mail, etc.) (more).
Convert RAW Files	Convert RAW image files to tiff (more).
Slide Show	Show a series of images full screen (no menu or toolbar) (more).
Synchronize Files	Rebuild the image search index and refresh thumbnails (more).
Show RGB	Show RGB values at position of mouse click (more).
Grid Lines	Add or remove grid lines for image alignment (warp, rotate) (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 E-mail program (more).
Check Monitor	Display a color palette for tuning your monitor (more).
Monitor Gamma	Adjust monitor gamma for better image editing (more).
Brightness Distribution	Show brightness distribution graph of current image (more).
Change Language	Change the GUI language (more).
Edit Translations	Revise a translation interactively (more).
Menu and Launcher	Add a system menu entry and desktop launcher (more).
User Settings	A collection of user preferences and settings (more).
Memory Usage	Dump a memory usage table to the log file (more).

Info Menu	View and edit image data and attributes
Edit Caption/Comments	Add or change descriptive text for an image (more).
Tags Overview	Explanation of tags and how they are used (more).
Edit Tags	Add or change image tags (keywords), stars rating, or date (more).
Manage Tags	Create tags and tag categories (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).
View Info (short)	View most important image data (more).
View Info (long)	View all available image data (more).
Edit Info	Add or change the data for a specific key (more).
Delete Info	Delete a specific key or all image data (more).
Search Images	Find images with desired tags / stars / dates / comments / captions (more).
Search Metadata	Search and report any desired metadata (EXIF/IPTC/etc.) (more).

Select Menu	Selected areas within images where edits are confined
Overview	Explanation of area selection and 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).
Unselect	Unselect an area (more).
Copy / Paste	Copy an area to memory and paste it somewhere else (more).
Open / Save	Save an area to a file and load it later to use in other images (more).
Select Whole Image	Select the whole image as a mask for retouch edit functions (more).
Select and Edit	Mouse over an image area to apply an edit function incrementally (more).

Transform Menu	Functions that change image size, shape, content
Rotate Image	Rotate an image (level an image or turn in 90° steps) (more).
Trim Image	Cut out a rectangular portion of an image (more).
Auto-Trim Image	Auto-select trim margins to remove after rotate, unbend, or warp functions (more).
Resize Image	Scale an image up or down (more).
Annotate Image	Write text annotations on an image (more).
Flip Image	Mirror an image horizontally or vertically (more).
Make Negative	Make a black-white or color negative, or a positive from a negative (more).
Unbend Image	Fix perspective problems (more).
Keystone Correction	Straighten a photo made from an offset angle (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).

Retouch Menu	Functions that change image qualities
Brightness / Color	Edit brightness, contrast, color saturation, color balance (more).
Gamma Curve	Edit brightness and color using the classic gamma curve (more).
Expand Brightness	Clip low / high brightness levels and expand the rest (more).
Flatten Brightness	Flatten the brightness distribution to enhance detail (more).
Brightness Ramp	Horizontal / Vertical variation of brightness (more).
Tone Mapping	Increase local contrast to to enhance details (more).
White Balance	Remove false color from an image (more).
Match Colors	Match the colors in one image to those in another image (more).
DRGB	Change brightness or RGB colors using OD units (more).
Revise RGB	Make complex color corrections that vary over the image (more).
Red Eyes	Remove red eyes from flash photos (more).
Blur Image	Blur an image (e.g. smoothen skin) (more).
Sharpen Image	Sharpen a blurred image (more).
Reduce Noise	Reduce noise (speckles) in low-light images (more).
Smart Erase	Remove power lines and other spoilers by substituting neighboring pixels (more).
Remove Dust	Remove dust spots on images made from scanned slides (more).
Fix Stuck Pixels	Fix stuck pixels (always bright or dark) from defective camera sensor (more).
Edit Pixels	Edit pixels and paint lines or areas using the mouse (more).

Art Menu	Functions that make artful transformations
Color Depth	Reduce color depth (posterize) (more).
Drawing	Transform a photo into a simulated pencil or chalk drawing (more).
Outlines	Transform a photo into a colorized line drawing (more).
Embossing	Transform a photo into a simulated embossing (more).
Tiles	Transform a photo into tiles (pixelate image) (more).
Dots	Transform a photo into an array of dots (more).
Painting	Transform a photo into a simulated painting (more).

Combine Menu	Functions that combine multiple images
High Dynamic Range	Make a high dynamic range image from multiple images (more).
High Depth of Field	Make a high depth of field image from multiple images (more).
Stack / Paint	Combine multiple images to remove tourists and cars (more).
Stack / Noise	Combine multiple images to reduce noise (more).
Panorama / Vertical Panorama	Join 2-4 overlapping images to make an ultra-wide image (more).

Plugins Menu

Other image edit programs can be used as edit functions in foloxx (more).

Help Menu

User guide, README, change log (more).

Toolbar Buttons
Gallery	Show thumbnails of image flles in the current directory (more).
Open	File open dialog - open an image file to view or edit (more).
Prev / Next	Go to previous or next image in the current directory or search set.
Zoom+	Magnify the image. A left mouse click also magnifies.
Zoom-	Reduce the image to fit window. A right mouse click also reduces.
Undo / Redo	Undo one edit / Redo one edit - up to 99 edits of the current image.
Shift-key + Redo / Redo	Changes the buttons to [undo all] and [redo all].
Save / Save+V / Save+F	Save image to the same file, to a new version, or to a new file (more).
Trash	Move an image file into the trash bin (more).
Quit	Exit from Fotoxx.
Help	Show online user guide (more).

Keyboard Shortcuts
Main Window	shows current image file to view oe edit
left / right arrow keys	previous / next image
plus(+) / minus(-) keys	zoom image bigger / smaller
Z key	toggle: zoom image to 100% / fit image in window
R / L keys	rotate image 90° right / left (change is permanent)
G key	toggle grid lines on or off
T key	shortcut for menu Transform > Trim
B key	shortcut for menu Retouch > Brightness/Color
A key	change toolbar undo/redo buttons to undo/redo ALL edits
N key	shortcut for menu File > Rename Image File
Delete key	move image to trash bin
Escape key	Exit slide show mode
Spacebar	pause and resume slide show timer
Control + s	Save to original file (no questions asked)
Control + S	Save+F: dialog to choose a target file
Control + v or V	Save+V: save to new version (no questions asked)
Control + q or Q	Quit Fotoxx
Control + z or Z	undo one edit level
Control + Shift + z or Z	redo one edit level
Image Gallery window	thumbnail images of current directory
Home / End keys	move to first / last page of image gallery
Page Up / Down keys	move to previous / next page of image gallery
up / down arrow keys	move up / down by one row of image gallery
left / right arrow keys	move to previous / next page of image gallery
plus(+) / minus(-) keys	bigger / smaller thumbnail size
Escape key	close image gallery window
Dialogs for User Input
F1 function key	display user guide section for current function
Escape key	cancel dialog

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 a zoomed image in the opposite direction, like a scroll bar.

Some supplimentary technical notes can be found here.

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, the latest search results, or the current named collection. 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 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 you want to view both.

There are three types of image gallery windows: (1) the image files in a single directory (plus subfolders at the top of the list), (2) the results of using the image search function to find images that may be in many different directories, (3) the images in a named collection. The title bar of the window will show the directory path, "Search Results", or the collection file name.

Clone Fotoxx
Start a new instance of Fotoxx in a new window. There are two variations: split the screen 50/50 between the two windows, or open the new window over the old window, slightly offset for visibility. Clone is useful to compare images or to work with more than one image at a time. Both windows can be used to edit images. The new window will initially have an unmodified version of the current image file. The original window keeps whatever edits have been done. If the same file is edited in both windows, the result will depend on whichever window saved it last. Use the toolbar button [Save+F] if you want to keep both image files.

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. The main window title bar always shows the file name and directory of the current image file. 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 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 in 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. Add Fotoxx to the "open with" list for jpeg, tiff, etc. in Nautilus or other file browser. If the current image gallery list is from an image search function or a named collection, and you open a new file with Open Image File, the gallery will be replaced with image files from the same directory as the opened file. A message informs you and gives the option to proceed or cancel.

Camera RAW files can also be opened. This may need a few seconds depending on file size and processor speed. The RAW file is converted to tiff-16 and this file is opened. It remains on the disk unless you delete it or move it to Trash. RAW files are not included in gallery lists because the processing time is too much. If you want them in the galleries, I suggest the following: save the converted tiff file in a smaller size and format so that less disk space is required. A 1/4 size jpeg file will use less than 1% of a full-size tiff. Of course you can always get the full size image back from the RAW file.

Open in New Window
This is the same function, but the new file is opened in a new instance of Fotoxx. The current file remains in the old instance. This function is a combination of open file and clone.

Open Previous File
Go back to the previously opened image file, also if this is 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, or the previous image in the last search results.

Open Recent File
The 99 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 file back to itself. If the file is a JPEG file, the default quality (90) is used. If this is an original file (not a versioned file), you will be warned that you are overwriting the original file. You can override the warning and continue. You can also elect to permanently supress this warning if wanted. If you have disabled the warning and wish to reinstate it, you must edit the file /home/<user>/.fotoxx/parameters and change the value of "warn overwrite" from "0" to "1".

Menu File > Save to New Version or toolbar button [Save+V]
Save the current image file with a new version number. File names with version numbers are formatted "filename.vNN.ext" where NN is a version number 01 to 99. The 4 characters .vNN are inserted between the file name and extension. If the file name has no versions, version .v01 will be created. If file versions are already present on disk, then the next higher version number is used. There is no dialog or confirmation. If the file is a JPEG file, the default quality (90) is used.

Menu File > Save to New File or toolbar button [Save+F]

A dialog opens 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 smaller files 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 16 bits per color can be seen with the eye. However, an image with higher bits has more latitude when the brightness is altered with a program like Fotoxx. If "make current" is checked, the newly saved file will become the current file. In either case, the edit history is retained (i.e. undo and redo still work).

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

There is a technical note about JPEG files and loss of image quality.

Create Blank Image
Create a blank image with specified pixel dimensions and color. This can be used as a background for a mashup using cutouts taken from other images (via Select Area) and annotation text (via Annotate Image). Input a file name, choose a background color, and set the desired pixel dimensions.

Trash Image File
Fotoxx uses the Linux desktop standard for trash. If this works, trashed image files go into the standard trash location and can be recovered later if wanted. Otherwise, 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. Use the [next] button to move to the next file if wanted. 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 try to update file name and tag associations in the search index file.

Print Image File
The print menu brings up a standard Page Setup dialog where you can select a printer, a paper size (letter, A4 ...), and orientation (portrait or landscape). Select your printer (do not use a default setting). The paper size shown will be the one last set in the Printer Properties dialog (a separate admin function in the System menu). If the paper size is wrong, fix it using the Printer Properties dialog. Changing the paper in the Page Setup dialog may be ignored or lead to a "paper mismatch" failure. After using the [apply] button, another dialog starts for entering the print margins. Use these to shrink the image size on the paper or shift the image position. When done, a Print dialog starts for the actual printing. Use the Print Preview button to check that the image has the right orientation and position and cancel the print if not.

Tools Menu

Manage Collections - Concepts
An image collection is an arbitrary collection of images that is manually assembled from other images. This is one method to make groups of associated images (other methods are tags, captions and comments, directory and file names). An image collection is simply a list of the member image files. The image files themselves are not copied or changed. A given image can be a member of multiple collections. Collections can be used to group images with some shared characteristics, such as photos from a vacation trip, photos of a given person taken at different times or events, a "best photos" collection, etc. Once a collection is made, you can call it up by name and use it for other purposes, e.g. view as a slide show or burn to a CD. You can add and remove images in a collection and rearrange the order of the images. An image may also be present multiple times in a collection.

Manage Collections Dialog

New: Supply a new collection name. This will be named in the dialog as the "Editing" collection.
Edit: Select an existing collection for editing. This will become the "Editing" collection.
View: Select a collection for viewing. The gallery window will show its thumbnails. This can be the collection being edited or any other.
Delete: Select an existing collection to delete. The collection is deleted, not the images.

After a collection for editing is created or selected, you can add or remove images by right clicking on a gallery thumbnail or main window image. A popup menu appears with the following entries:
    + add image to collection: <collection name>
    + remove image from collection
    + remove and save image
    + insert saved images here

Procedures
(1) Add images: use [New] or [Edit] to establish an edit collection. Use [Open] or [Gallery] to navigate to the images to add. Right-click each image to add and select the "add" menu. You can also use [View] to add images from an existing collection.
(2) Remove images: use [View] to view a thumbnail gallery of images in the collection. Right-click each image to remove and select the "remove" menu.
(3) Rearrange images: use [View] to view a thumbnail gallery of images in the collection. Right-click each image to be moved and select the "remove and save" menu. The thumbnails are immediately removed from the gallery and the images are saved in a separate list. Right-click the thumbnail where the saved images are to be inserted (after) and select the "insert" menu.

Move Collections
An image database can be moved by renaming or moving its top directory. The image files will follow automatically. The function Synchronize Files can fix the Fotoxx search index. The named collections, however, will become useless because the stored file paths are invalid. The function Move Collections can be used to replace the top directory in all the existing named collections. Enter the old and new top directory names in the dialog and press [apply].

Batch Convert / Resize / Export

This function is used to convert, resize and export 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). Select a maximum width and height for the output files (use huge values if no size reduction is wanted). Select the output file type. "same" means the file type will not be changed, otherwise all files will be converted to the specified type. Select the option: "replace originals" or "export to location". For the latter, input a directory where the resized and converted image files will be written, or use the [browse] button to locate the directory. Use the checkbox to remove EXIF/IPTC data from the output files, if desired. Finally, use the [proceed] button to start the resize process. A popup window shows the progress.

Convert RAW Files
This function converts selected RAW image files to JPEG, PNG, TIFF-8 or TIFF-16 format, using the program ufraw-batch. The two TIFF formats have respectively 8 and 16 bits per color. RAW files generally have 10-12 bits, therefore use TIFF-16 to keep all of the data available in a RAW file (the difference between 8 and 16 bit color is rarely visible). A file chooser dialog is opened. Choose one or more RAW image files (hold down the CTRL key to select multiple files). Then you will be asked to choose one of the above output formats. 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 fast PC does about 24 image files per minute using a mix of raw file types and TIFF-16 output).

Slide Show

The images in the current directory, from a named collection, or from a previous search function are shown one by one. The image window is enlarged to the whole screen, and the menu and toolbar are removed. A dialog pops up to ask for some initial inputs. Enter a time duration to show each image, select the option to show only the latest image versions, and select the transition mode(s) to use when the image changes. Transition modes include arrow-keys (manual transition), instant replacement, fade-out / fade-in, and several kinetic methods of image replacement (e.g. the new image expands from the center to replace the old image). If "arrow-keys" is selected, then the time duration is irrelevant and the keyboard left and right arrow keys are used to move to the next or previous image. The arrow keys can still be used even if one of the other modes is selected. Use the escape key to get out of slide show mode. The spacebar can be used to pause and resume the timer between slides. If an image search is done before a slide show, these images are shown. Before starting the slide show, you can use the function Info > Edit Comments or Edit Caption to show relevant text for each image in a small window which you can push to the side. The text is updated for each image viewed in the slide show. The other Info menu displays will also update with each image. The slide show dialog also has an input for a music file or playlist. If not blank, the music will be started with the slide show.

It is also possible to start a slide show with or without music from the command line:
$ fotoxx -slideshow /.../imagefile1.jpg -music /.../musicfile.ogg
The slide show begins with the given image file and proceeds to following files in the same directory. The -music parameter is optional. If present, the following file is a music file (.mp3 .ogg ...) or a playlist. xdg-open is used to open the file with the preferred music player.

Synchronize Files

This is needed when Fotoxx is started for the first time, 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 if a large number of files were added or moved, and the Search Images function will not find the new or moved files. The Synchronize Files function will create missing thumbnails, replace outdated ones, and refresh the search index file using current data from your image files. On a fast computer, new files are processed at 1000+ per minute and old files at 1000+ per second.

Images created (i.e. edited and saved) or moved within Fotoxx are taken care of automatically. Synchronize Files is only needed when new image files are created from outside Fotoxx (e.g. a new batch of files from a camera), or if files are moved or renamed from outside Fotoxx.

If you have used directory and/or file names to classify your images, you can make immediate use of these in the Search Images function. If you have saved captions, tags, titles, or ratings in your images (using Photoshop, Fotoxx, or other tools), these will also be searchable.

Synchronize Files starts automatically at Fotoxx startup if image files are detected with a date/time newer than the last Fotoxx session. It can also be started manually from the Tools menu. A dialog will ask for the topmost directory of your image files (e.g. /home/<user>/Pictures). That directory and any subdirectories containing images will be processed. It does not matter if other files are mixed. A popup window shows the new image files as they are found and processed. This window is left open for your inspection after the synchronize function is finished. After the images have been indexed, searching them (by captions/comments, file names, tags, date, rating) is almost instantaneous.

When Synchronize runs, you can use Fotoxx normally to navigate and view images, but editing images and metadata (tags, comments, etc.) is blocked until Synchronize is finished. You can see in the status bar if Synchronize is running. Unless there are hundreds of new images to process, this will be done in a few seconds.

Show RGB

When a point on the image is clicked, the RGB values are shown in a dialog window. The values have the format xxx.dd, where xxx is the upper 8 bits of the color value and .dd is the lower 8 bits. The range is 0.00 to 255.99. The lower 8 bits are zero unless the image is being edited or the image is a 16-bit tiff file. EV (exposure value) and OD (optical density) units are alternative units, useful for precise color adjustment. EV is zero for mid-brightness (128). OD (optical density or reflectivity) is 2.0 - Log(100 * RGB / 256). The outputs are updated immediately if the image is being edited. The last five points clicked are shown. The points are labeled on the image corresponding to the letters A-E in the dialog window.

RGB	0	1	2	4	8	16	32	64	128	256
EV	nan	-7	-6	-5	-4	-3	-2	-1	0	1
OD	nan	2.41	2.11	1.81	1.51	1.20	0.90	0.60	0.30	0.0

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 lines each in order to divide the image into thirds horizontally and vertically. 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. This works also during an edit function. If an image is printed with grid lines enabled, the grid lines are also printed.

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. In the dialog, 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. 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.

This function uses xdg-email (Linux Standards Base) which must be installed and work correctly. It works for some Linux flavors with some e-mail programs and not for others. If it does not work for you, then the next best appproach is to use Transform > Batch Convert to select, optionally reduce, and export the image files to your Desktop. Then you can conveniently attach them from within your e-mail program.

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 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 (with little external light falling on the monitor).

Monitor Gamma

Gamma determines how RGB brightness values (0-255) are converted into brightness as perceived by the eye. The standard value is 2.2 and this should normally be used for image editing. An adjustment chart is provided, courtesy of Norman Koren. Adjust the dialog slider until the shaded bands disappear at scale location 2.2. The chart only works at 100% size, so do not zoom the chart.

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

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

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

Edit Translations

This function is used to revise the GUI translations interactively, as Fotoxx is being used. Traditionally, translation files (.po files) are edited separately. These are then installed and Fotoxx is exercised to see how the translations look. The advantage with this new method is that the application context is experienced as the translation is made, which should result in easier and better translations. Also, the new translations are immediately used by Fotoxx. For details about how to do translations, see the menu Help > Translations. This describes how .po files work and the procedures for editing them. The section "Interactive Translations" describes how to use this interactive method to update .po files. You can also start Fotoxx with the command line parameter "-translate" to make it start up in translation mode. This will capture the main window menu and toolbar translations which would be missed if the menu function is used.

Menu and Launcher
This function puts a Fotoxx icon / launcher on the desktop and adds Fotoxx to the desktop menu system under the category "Graphics". Your system must be LSB compliant (Linux Standards Base). The effectiveness of this has been sporadic. You may need to log off and back on to see the new menu entry. A dialog allows you to customize the startup options.

User Settings

Various user preferences and settings are collected in this dialog.

Startup Display	The initial window content when Fotoxx is started. Directory can be the top image directory or any sub-subdirectory underneath. Image File is any valid image file.
Toolbar Style	The desired toolbar style for the main window and gallery window.
Warn Overwrite	Whether attempts to save a modified image replacing the original image is warned or not. Saving to a new version is never warned. Saving to a new file name is warned only if the file already exists.
Panorama	The two lens parameters used for Panoramas. Normally EXIF data is used for lens mm (35mm focal length equivalent), and the value here is used only if there is no EXIF (e.g. a scanned print from a film camera). Lens bow is for compensation of barrel/pincushion distortion. There is no EXIF for this, but fortunately it can usually be left at zero. There is a way to measure this described in the Panorama topic.
Zoom Ratio	The image size increase with each zoom-in. The choices are 4/3/2/1 zooms for each 2x increase in size.

Memory Usage
This is a diagnostic tool to detect memory leaks. A table is dumped to the log file (stdout) which shows total memory usage and usage by category. If any of these numbers increase consistently with Fotoxx usage, then there could be a memory leak bug.

Info Menu

Note: the program exiftool must be installed for the following functions to work. Fotoxx uses this program to read and write text information stored within an image file (metadata: EXIF, IPTC, etc.). If exiftool is not installed, then modifying an image with Fotoxx will lose all metadata. For recent Ubuntu, the package name is: libimage-exiftool-perl. Other distros may be different.

I have provided a short analysis of the alternatives for organizing a large image collection so that it can be easily searched. If you are interested, you can find it here.

Edit Caption/Comments

This is a special function for editing image text saved in IPTC "Captions" and EXIF "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 [Apply] button to save the text in the IPTC and EXIF data for the current image. The dialog can be left open while navigating to different images, and the current text for each image is shown, if any. Enter or modify the text and press [Apply] 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 captions and comments (see topic Search Images).

Tags 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 metadata (IPTC:keywords). Tags are normally one word, but a short phrase with imbedded blanks or other delimiters can be used. Commas and semicolons are recognized internally as delimiters (separators) between tags, and therefore cannot be used within a tag. A compound tag like "Arizona scenery" is allowed, but you should use two tags instead for more flexibility: you can search for images having either tag or both tags.

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. to 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 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 Images" 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.

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 tag category: 50000 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 harder 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 tags.

Edit Tags

To assign tags to the current image, select the menu Info > Edit Tags. 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/day is logically equivalent to 01/01 when used as a low limit for searching, or 12/31 when used as a high limit. 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 [Apply] button writes the tag information to the image file and to the search index file used for searching images.

Manage Tags

To create new tags, use the menu Info > Manage Tags. You can also 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, scenery, buildings, art, etc. 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 the Edit Tags dialog is open, its window of defined tags will also be updated. You can keep both the Edit Tags and Manage Tags dialogs open if you need to create or change tags for immediate application to images. Tags used in images but not assigned to a category will appear under "nocatg".

Note: a newly created tag is appended to the end of the tag list for its category. The next time fotoxx is started, all categories and their tag lists are sorted alphabetically, except that "nocatg" is always last. A tag will also disappear from the list if it is no longer assigned to any image.

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 the tags to the image files.

Batch Delete/Replace Tag
This function is used to delete a single 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 Images function).

View Info (short)
View Info (long)

The View Info functions will display metadata for the current image file, if available. EXIF metadata contains the date and time of a photo, shutter speed, focal length, pixel dimensions, etc. Digital cameras store this data inside the image. IPTC metadata contains tags (from Fotoxx, Photoshop ...) and captions (often for published images). If an image is edited and then saved, the metadata is updated and stored with the new image.

The View Info short report outputs 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, comments, caption, and a history of Fotoxx edit functions that have been applied to the image. The long report reports all the data available.

Fotoxx uses the following EXIF / IPTC data items:

Key Name	Fotoxx Usage
Date/Time Original	Edit Tags function - image date
Keywords	Edit Tags function - image tags
Rating	Edit Tags function - image stars
User Comments	Edit Comments function
Caption-Abstract	Edit Caption function
Edit Status	History of Fotoxx edits applied to the image
any key	Edit Info, Delete Info

Edit Info
A specific metadata ID (key) can be added (if legitimate) 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 EXIF key "User Comment" 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 Info
This function allows deletion of a specified metadata key, or all metadata at once. Input a key name in lower case and without blanks, e.g. the EXIF key "User Comment" is entered as "usercomment".

Search Images

Example: select images in 2005 or later, with 4 stars or more, having tags buildings or monuments, and containing dresden in the directory or file name.

A search 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, comments, captions, dates and star ratings saved inside the image file itself (EXIF and IPTC metadata). Thus you can rearrange your image directories and image files without losing anything - you must only regenerate the search index file, which is simple and fast. See Tools > Synchronize Files.

Use the Search Images function to find images having desired tags, dates, stars, comments, captions, or file names. Available tags are shown and can be chosen with point and click. Use the radio buttons "all" or "any" to indicate if all tags or any tag must be present for an image to be selected. 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 are used for the buttons [prev] and [next]. If an image file is selected with the File > Open function or toolbar button [Open], then the current image 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 month/day default to 01/01 for the low date limit and to 12/31 for the hight date limit.

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. In the input field "file names", enter any number of names used for your image directories and file names, separated by blanks. An input of [ egypt cairo ] would match all image directory/file names containing either of these strings. Name matching is not sensitive to case.

Image comments and captions may also be searched (see Edit Comments, Edit Captions). Enter the words to search for in the dialog "search text" field, separated by blanks. These will be matched to every word in the comments and captions of all images, and matching images are selected.

The radio buttons "all" and "any" apply to all matching options: tags, text, and file names. You can select images having ALL the entered strings, or ANY of the entered strings. Example: if the search file field contains [egypt cairo] and "any" is selected, then image files with either of these names within the directory or file name would be selected.

You can use comments, captions and directory/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, if less exacting. Simply name your image files with the key topic or content, and add comments or captions 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 defined tags is automatically maintained and presented when you search images, and adding tags to new images is a point and click operation.

Search Metadata

Report any desired metadata using a combined image and text layout. The starting point is always the current image gallery list, which can be an image directory (the normal case) or the results from an immediately preceeding Search Images. The selection criteria available in Search Images is always shown first: file name, date, star rating, caption, comments, and tags. When Search Metadata is started, you can enter up to five more metadata items to report. The items available in any given image file can be shown using View Info (long). These include camera make and model, exposure time, F-number, ISO, metering mode, focal length, shooting mode, etc. etc. You can enter shortcut names like "exposuretime" instead of "Exposure Time". You may also enter match criteria, if wanted, so that only the images with matching metadata are reported. For example, if you enter "camera model name" with the match value "DMC-FZ28" (my Panasonic) then only the images taken with this camera will be reported. You can also enter multiple match values for one key, separated by blanks.

Performance: If no extra metadata to report is entered, then 1000+ images/second are searched and reported. If extra metadata is entered, the search performance slows down to something like 100 images/second. This is because the image files are being read to extract the metadata, instead of using the search index file. For good performance, always use Search Images first to reduce the images being searched as much as possible. Use dates, tags, file names, etc. to reduce the image count. Then use Search Metadata to search for and report additional metadata.

Select Menu

Overview
Edit functions normally apply to the entire image, but it is possible to edit part of an image (an "area") and leave the rest unchanged. If an image area has been selected, then the Retouch and Art edit functions will work only within this area. Other functions 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 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.

"Layers" in Photoshop and Gimp are "areas" in Fotoxx. Instead of selecting something from the image, making a separate layer from the selection, performing edit functions on the layer and finally merging the layers, you select something in the image and perform edit functions on the selection, with WYSIWYG feedback during the edit. Areas can also be saved, pasted into other images, and edited there.

Select Area

If an area is already present, its outline will be shown. You can continue to edit this area or use [Unselect] to discard it and start a new area. Select one of the methods (explained below) and proceed to define the area. 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 select area dialog can be exited and re-started later to modify a selected area or start a new one.

Methods to enclose one or more spaces that will belong to the final area:

Rectangle	drag the mouse to enclose a rectangular area
Ellipse	drag the mouse to enclose an elliptical area
Freehand Draw	drag and click the mouse to draw lines that 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 Mouse	select a small area of pixels around the mouse and aggregate adjacent areas with pixels matching in color and brightness

Methods may be used in any sequence to define spaces that are either joined or detached. The following paragraphs explain the details of each method.

Rectangle: Drag the mouse from one corner to the opposite corner of the desired rectangular area to select. A rectangle is drawn to enclose the area. Right-click to delete and start over. Repeat the process to select more rectangular areas.

Ellipse: This works the same as rectangle selection, except that the area enclosed is an ellipse that fits within the rectangle.

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). 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 mouse: 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 all pixels inside the circle, and the degree of match is defined by the match control: 100 means a perfect match is required. Adjacent areas (within search range) with pixels matching any of the selected pixels will be selected. 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 to match new pixels enclosed by the mouse and within the search range. 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. The radius of selection is limited by search range which is a multiplyer of the mouse radius. A small radius and search range can be used to follow along an edge and select pixels up to the edge with good precision. Change to a larger radius and/or search range to select larger areas after the fine work is complete. If the "firewall" is enabled, then already-selected pixels will act as a barrier to stop the search for new pixels. This is sometimes useful, e.g. an existing selection boundary should remain fixed and you want to extend the selection in the interior. Right drag acts as an un-select: pixels matching pixels inside the mouse radius and within the search range are un-selected. You may need some practice to get a feeling for this and be able to work efficiently.

Summary

left click or drag	select pixels inside radius and those with matching colors inside search range
right click	undo previous selection, repeat to unselect more
right drag	unselect pixels inside radius and those with matching colors inside search range
match mouse color	uncheck to turn color matching off: only pixels within the mouse radius are selected or unselected

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 (unedited) image. At a distance of "blend width" from any edge inside 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 within 4 pixels of the image edge.

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.

Color: Alternates the color used to show the area outline (red, green, black).

Finish: When you are finished selecting the enclosed 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 "outline has a gap". If there is a gap in the outline, 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. Carefully inspect the outline of the area, close the hole, and use [Finish] again. An area is not effective for edits until it is successfully finished. Any enclosed area can be selected, even those not explicitely outlined (e.g. if you use select by mouse to select a donut with a hole, you can still click the hole to include it in the area).

Unfinish: To re-edit a finished area, it is sometimes necessary to un-finish it to make the edit functions work normally.

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.

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 will be repeated if edge blending is selected.

Unselect: Discard 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 Unselect
Permenently discard 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 resize and angle buttons to resize or rotate 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 Select 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 Select > Copy, it can be saved to an image file using the menu Select > Save. You are asked to supply a name. Two files are saved: the image is saved to filename.tiff and the transparency data is saved to filename.info. These files reside at /home/<user>/.fotoxx/saved_areas/. Use Select > Open to choose a saved area (choose the tiff file), which will be dumped into the image where it can be moved around, resized, etc. as with the copy and paste functions.

Select Whole Image

It is sometimes effective to apply a retouching function controlled by image brightness, e.g. apply noise reduction to darker areas of the image while leaving brighter areas alone. To do this, use the menu Select > Select Whole Image. Choose brightness or one of the RGB colors as the controller. The editable graph controls how subsequent edit functions are applied to the image. The x-axis is pixel brightness from dark to bright, or the selected RGB color from 0 to 100% of the pixel brightness. The y-axis value governs how strongly the edit function affects a corresponding pixel. A low value minimizes the effect, and a high value maximizes it. Example: apply tone mapping primarily to dark pixels: Use Select > Select Whole Image and drag the curve so that high values are on the left (dark pixels) and low values are in the middle and on the right (bright pixels). Now use Retouch > Tone Mapping to apply tone mapping to the darker areas of the image. You can edit either curve (whole image curve, tone mapping curve) while watching the resulting image.

Select and Edit

Use this function in combination with a retouch edit function. Specify a mouse radius and power factors for the mouse center and radius edge. Then start a retouch edit function if not already active. The mouse pointer will be surrounded by a circle with the specified radius. When the mouse is dragged over an area of the image, the current retouch function is applied within the circle. The "strength" of the function is regulated by the power factors. Typically you will use a high value at the center and zero at the edge, meaning that the strength of the edit will be maximum at the center, changing gradually to zero at the edge of the circle. As you drag the mouse over the same area repeatedly, the edits are slowly accumulated. For example, if the edit function is Brightness/Color, and the brightness curve is set to a high level, then the image will be slowly brightened in the area where the mouse is dragged. This is called dodge and burn in other image editors, but other retouch functions can also be used, e.g. tone mapping or blur. Use the [undo] and [redo] toolbar buttons to monitor the change, which may be hard to notice at first. Set the center power to 100 to make faster changes (with less fine control). Use a left-button drag to weaken the edit or ultimately erase it. When done using one edit function in one or more image areas, use the [done] button on the edit dialog to complete the edit. Use the [reset area] button to erase the active area that is now left over from the mouse dragging. If you leave the area active and start a new edit function, the results are unpredictable. A suggested approach is: (1) start the Select and Edit dialog, (2) start the edit function with its initial settings (the effect on the image will be zero since no mouse dragging has been done), (3) drag the mouse over the desired areas and watch the effect, (4) adjust the edit function settings, (5) alternate between the previous two steps. This method to "paint" a retouch function incrementally can improve selected areas of an image quickly and easily. It works with any edit function that can use selected areas. The most useful are Brightness/Color and Tone Mapping.

Transform Menu

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

Trim Image (aka crop)
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 [Done] 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. You can use the width and height spin buttons to input desired pixel dimensions directly, and the selection rectangle will adjust to these.

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

Auto-Trim Image

The functions panorama, HDR/HDF, stack, unbend, and warp can leave black margins where images did not overlay or were bent away from the edge. Auto-Trim automatically sets trim margins to omit these areas and then starts the Trim function (previous topic) with the margins pre-set. If these are correct, press the [done] button to finish. If not, change the margins as described above. Auto-Trim tries to find a maximum rectangle that does not overlap any of the black margin areas. This may or may not be the desired margins, so you can keep them or move them with the mouse before comitting with the [done] button.

Resize Image (aka rescale)

This function sets a new image width and height. You can input the new pixel width and height directly or choose a percent change for width and height. 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. The change is made immediately, but the image will look the same unless it becomes smaller than the window, causing a visible shrinkage. Leave the dialog with [done] to save the changes or [cancel] to keep the original size. The image file size (status bar) is not updated until the modified image is saved.

Annotate Image

With this function you can 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 or drag to move the text elsewhere. Right click to remove the text. Use the [Font] button to select a different font and size. Use the [Size] control to 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 green text on a blue background, with the background being 77% transparent, meaning that the image shows through the background. The 3rd color option is to supply an optional outline around the text, in this case red. [Width] controls how wide the outline is. 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 items in the dialog are loaded or saved (text, font, etc.), so 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).

Flip Image
Choose either horizontal or vertical flip from the dialog. The image is reversed (mirrored) 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.

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.

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. The linear values will slant the image left/right or top/bottom edges to remove slant. The curved values will straighten the image curving that comes from making a panorama. See also "Warp Image" for another method of correcting image curving and perspective problems.

Keystone Correction

This function can be used to straighten a photo made from an offset angle. The painting on the left is the original photo, taken from below and left of center, to reduce reflections. The painting on the right is the straightened version. This function can also be used to straighten a building photographed from an angle, or a book page or document, etc.

Click on the four corners of the tetragon shape that you want to make into a rectangle (in the above case, the four corners of the painting or frame), then select [apply]. Use [reset] to go back and try again if needed. The clicked corners are labeled with small letters A, B, C, D. The upper left corner of the square enclosing the letter precisely marks the corner position. Clicking near a corner will move it to the new position. After the 4th corner is defined, a new click replaces the closest corner.

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.

Retouch Menu

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. For example, to increase overall contrast, make the Brightness curve lower on the left and/or higher on the right. To brighten areas that are too dark, raise the left side of the Brightness curve. The buttons [+++] etc. can be used to shift the whole curve rapidly 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. The curves for the three colors change one color at a time. For example, if dark image areas have a red hue, lower the left side of the Red curve.

The scale range is +/- 2.0 EV (F-stops) for a total brightness range of 1/4 to 4x. The step size for the buttons [+++] etc. is 0.1 EV or about 7% brightness change. The alternative small step size is 1/3 as big.

Gamma Curve

This is the classic gamma curve edit found in Photoshop and many other image edit programs. The x-axis maps the input pixel brightness and the y-axis the output or adjusted pixel brightness. The straight line at 45 degrees is the neutral curve, mapping input brightness values to the same values for output brightness. The edited curve shown here will cause darker pixels to become darker, mid-range pixels to have an increased brightness range (more contrast), and the brightest pixels to become brighter. In effect, contrast is being removed from the darker and brighter image areas so that the mid-range areas can have more contrast. Moving the low end of the curve to the right will cause dark pixels to be clipped (made black), and moving the top end of the curve to the left will cause bright pixels to be clipped (made white).

Edit the ALL curve while watching the image for instant feedback. You can also select and modify individual RGB colors after finishing the ALL color. Editing the ALL curve forces the RGB curves to match the ALL curve, so do RGB curve adjustments after adjusting the ALL curve.

Expand Brightness

This function expands the brightness range of an image that does not utilize the full brightness range available, possibly making it look contrast-poor. You can see this in the brightness distribution graph. If the distribution shows little or no area at the extreme low and high ends of the horizontal scale, the image may benefit from expanding the brightness range. This means that the darkest pixels are made darker and/or the brightest pixels are made brighter. Move the sliders to extend the brightness range and observe the image.

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. Using this function within a selected area is often very effective. Edge blending may be needed to make the boundary invisible.

Brightness Ramp

This function varies the brightness across an image, with the direction and magnitude of the brightness slope determined by editable curves. You can use this to compensate for uneven lighting or vignetting (darker image corners). 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. If used with a selected area, the scales refer to the enclosing rectangle of the area instead of the whole image. Thus you can select an area of an image and apply a brightness ramp across the area. If the button "all" is selected (default) then all colors are adjusted equally (i.e. brightness is adjusted). If one of the colors is selected, the image is adjusted for that color only, and the "all" curve is ignored. Any or all three RGB colors may be adjusted in this manner. You can use this to remove a color-caste that varies across an image or image area.

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. 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 (brightness range) 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 and the perceived brightness range.

In the dialog, the graphic curve determines how much local contrast is increased depending on initial 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 Amplify slider below the curve regulates the internal algorithmic calculation, from no contrast amplification on the left to full amplification on the right. If moved too far to the right, the image may show artifacts (bright or dark "rays"), so push it back 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 amplify 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.

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.

Match Colors

This function matches the colors in one image to those in another. A small spot, determined from a mouse click, is sampled from each image. The spot on the 2nd image will be made to have the same average color (RGB values) as the spot from the 1st image. The factors used to make the RGB values the same are then applied to all the pixels in the 2nd image. The most common use is to remove a color-cast from an image by marking a spot on the image that should have a given color which is taken from another image.

Procedure: The dialog lists 5 steps to take in sequence. (1) Set a radius for the spot sample. The mouse cursor will have a circle of this radius which is the spot area that will be sampled. (2) Open the 1st image (press the [open] button for a file open dialog). If the current image is already the one you want, this step can be skipped. (3) Click on the image to take a color sample from the spot area enclosed by the mouse circle. You can change the radius and click again if wanted. (4) Open the 2nd image by pressing the [open] button. (5) Click on the image at the spot you want to match the spot color from the 1st image. The image colors will change within a second or two. You can change the radius and click on another spot if wanted, and the colors will change accordingly. Click the dialog [done] or [cancel] button to finish.

DRGB

This function is used to change overall brightness or selected colors using OD (optical density) units. The input values range from -99 to +99 which represent -0.99 to +0.99 OD. OD is a logarithmic scale where -1 is a 10x increase and +1 is a 10x decrease in brightness. The input steps (0.01 OD) make a 2.3% change in brightness, which is barely visible with undo/redo and not visible with a side-by-side comparison. The contrast buttons change contrast by 0.01 OD per step, meaning that the brightest and darkest pixels are changed by 0.01 OD in opposite directions, with intermediate pixels changed proportionally.

DRGB is the tool for converting color space between monitor and printer. Print a standard color chart, use DRGB to adjust the Fotoxx image and print again until the printout is good. Save the settings (color offsets) and use them to print subsequent images with correct color the first time. The settings will be different for different printers and paper types. Use [save] to save the settings to a file, and use [open] to load the settings from a saved file.

Revise RGB

This function can be used to make complex color corrections, whereby different parts of the image need different corrections. Select up to 9 control points on the image by clicking them with the mouse. The points are added to the list in the dialog window, with the most recent point at the top. The points are labeled A-I in the list and on the image window. The current RGB values are shown (or EV or OD units if selected). Change the RGB/EV/OD values in the dialog, and the image will be changed to match. Each pixel in the image is influenced by all the control points in the dialog, with the closer control points having more influence than those farther away. The slider Soften Peaks determines how widely the control points spread their influence. If "delta" is checked, the values shown are the deltas (differences) from the original image.

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 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 (1)	The highest and lowest pixel values within a radius are moderated slightly.
Flatten outliers (2)	Pixels are compared to the mean and sigma of pixels within a radius. Those outside one sigma are moved back toward the mean.
Median brightness	Pixels are set to the median value of their neighbors within a radius.
Top hat	Detect outliers by comparison with a band of pixels at a distance. The distance is increased in steps from 1 pixel to the radius limit.

Smart Erase

This function can be used to erase small objects that can spoil a good photo, such as power lines, trash on the ground, a sign, etc. The unwanted object is replaced with pixels taken from the surrounding area. This is sometimes very effective (side-effects almost invisible), and sometimes not. It works best for small or narrow objects in the photo (e.g. <20 pixels wide). Radius controls the size of a circle around the mouse pointer, defining the area to select and erase. Drag the mouse to enclose all or part of the object to be removed. Left-drag selects and right-drag un-selects. Press [Erase] to erase the selected area, replacing the pixels with the nearest pixels from outside the selection. If the selection was not precise enough, use [Undo], adjust the selected area, and [Erase] again. Repeated selections and erasures will accumulate until you use [New_Area] to start a new selection. The prior erased areas are now fixed and [Undo] will only work for the current selection. As with all edit functions, the toolbar buttons [Undo] and [Redo] can be used to review all changes. It is likely best to work with an image zoomed to 200% or more. The Blur control adds blur to the replacement pixels. This can reduce visible side-effects, since the replacement pixels may be sharper or have more contrast than the surroundings. Change the Blur setting and repeat the [Erase] button. A blur of 0.5 or 1 pixel is usually effective.

Remove Dust

Images made from dusty scanned slides can have many small dark spots - shadows of the dust on the slides. This function can be used to remove the majority of such spots. Move the three sliders until the maximum number of dust spots are painted red, then press the [erase] button to erase them. Press [red] to bring back the red view, then you can adjust the sliders again and press [erase]. The "spot size limit" slider limits the size of the spots that will be erased. The "max. brightness" slider sets a theshhold for ignoring spots that are not dark enough. The "min. contrast" slider screens out spots having low contrast with their surroundings. This process is usually a compromise. If the settings are not optimal, small features like tree leaves can be erased, or large spots may be left in place. Different parts of the image may need different settings, e.g. sky can be treated more aggressively than a building wall. You can simply use Erase Dust multiple times with different settings as needed to get all the dust spots. Or you can use select area to process the image in sections. If some spots are persistent, you can treat them manually with Smart Erase: set a small mouse radius and click on each spot to remove it. Spots from fibers (long and thin) are usually not removed automatically, but Smart Erase can be effective here.

Fix Stuck Pixels (always bright or dark)

Camera sensors may have defects causing isolated pixels to be always bright or always dark. This may be one RGB color or all of them. I have seen a case where a group of 3x3 pixels was always too red. This function can find such pixels in an image and repair them by substituting neighboring pixels.

Select the defect sizes to search for: 1 pixel, 4 pixels in a 2x2 block, or 9 pixels in a 3x3 block. The defects found are surrounded by small circles which you can toggle between write, black and red. Zoom-in to inspect these and determine if they are real defects. Use the contrast control to precisely select the defects. If set too low, small high-contrast spots in the image may be erroneously selected. If set too high, real defects may be missed. Use the [apply] button to erase the defects in the current image. You can apply the function many times using different settings if needed. The currently shown (encircled) defective pixels can be saved to a file by using the [save] button. This file can be used later to fix the defects in any image made by the same camera: use the [open] button, select the saved defects file, then use the [apply] button to fix the current image. Using a saved defects file from one image to fix the defects in another image will only work if the two images have never been trimmed, or if exactly the same trim was applied to both images. This is necessary because the defective pixels in the two images must have the same locations. If more than one contrast setting or pixel group selection is needed to accurately find all the defects in one image, you can save the respective defect files and combine them manually into one file. Use any text editor for this. I suggest you make a test images to find defects: Make a photo of a paper sheet or blank wall that is underexpsed to come out gray. This image can be used to find both bright and dark stuck pixels.

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

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.

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.

Outlines
This function transforms a photo into a colorized line drawing showing outlines of objects within the image. Edges (sharp transitions in brightness or color) in the image are brightened, and the rest of the image is darkened. There are three sliding controls. Outline threshold: regulates how bright an edge must be in order to get enhanced, from "show no edges" at the low end to "show all edges" (even faint ones) at the high end. Outline width: the width of the enhanced edges, from 1-pixel to about 5 pixels. Image brightness: the brightness of the image itself, from dark (show only the outlines) to full brightness.

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.

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". Use Select Area to confine the transform to a limited area, such as a face.

Dots
This function transforms a photo into a array of dots, like old-fashioned comic book pictures or Roy Lichtenstein paintings. The only control is the dot size. Also experiment with using color saturation, color depth, or other functions before using Dots.

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 Embossing function can add interesting texture to the image.

Combine Menu

Make a High Dynamic Range Image (HDR)
Combine (overlay) 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 distant 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 initial curve for the brightest image will be high on the left and low on the right, meaning a high contribution to dark pixels and a low contribution to bright pixels. The darkest image will be low on the left and high on the right, and the remaining images will be in-between. 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 a High Depth of Field Image (HDF)
Combine (overlay) 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. 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 image mix to the selected image for the area being painted. For each area or object in the image, choose an input image that is sharp in that area. 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.

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 in the image. Some of these can be made unimportant by changing the image used for painting (if more than one image is sharp enough). Using warp mode, make fine adjustments as needed to eliminate visible shifts.

Stack / Paint

Combine (overlay) multiple photos of the same subject taken at different times. Remove tourists and cars that come and go between shots by painting them away with the mouse.

Making the photos: aim the camera at the same distant point and take multiple photos as tourists or cars move in front of the subject. Try to get at least one photo with each part of the subject not obscured by the moving objects.

Processing the photos: in Fotoxx, choose the Stack / Paint 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. 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 image mix to the selected image for the area being painted. For each area in the image, choose an input image that is free from the moving objects. The radius of the paintbrush can set larger or smaller, so you can paint large areas quickly and control fine detail when needed.

Stack / Noise
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 / Noise 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 if the median method is selected.

Make a Panorama Image
This function stitches 2-4 images together to make a wide image or panorama. The images must overlap by 15% 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 asks you to drag the images into rough alignment. Drag the images into the correct left to right order. The image to drag may overlap other images. To be clear about which image is being dragged, drag from near the center of the image. After the images are in the correct order, align each image to its left neighbor. It works best to proceed from left to right. Move an image horizontally and vertically into rough alignment with its neighbor to the left, then rotate the image if needed by dragging its bottom edge left or right. The image pivots around the mid-point of its overlap with the image to the left. The fastest method is to align the overlap middle region first, then rotate the right image if needed to bring the upper and lower overlap regions into alignment. Extreme accuracy is not needed. 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, then the lens mm parameter (focal length, 35mm equivalent) needs adjustment. The curvature of the images changes as lens mm is adjusted. The initial value is obtained from the EXIF data if available, and this is normally good enough. The lens bow parameter (barrel or pincushion distortion) is not available in EXIF and must be adjusted manually, but this is often insignificant and can be left at zero. You can measure and set the lens parameters manually as described below.

If an image was trimmed so that the greater dimension (width or height) was reduced, then the EXIF focal length is no longer valid, and the EXIF initial value may not work well. A section of an image taken from the middle has an effective focal length greater than the original. Use the pre-align dialog to increase the lens mm parameter until the images fit together reasonably well.

Press [proceed] when pre-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 from 10 seconds to 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 between images if 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 often satisfactory by itself. The other controls allow you to make additional changes to better match the images. Select one of the images with the radio buttons at the top, 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 images. 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, warp, rotate, trim, and other functions for final adjustments. Use the auto-trim function at the end to automatically get rid of any leftover black margins.

Vertical Panorama
This function works the same as horizontal panorama, except that the images are arranged vertically. To change the order of the images, drag them from near their centers. To rotate an image, drag the right edge up or down. It is best to align from the top down.

Scanned Images
Scanned images can be combined if there is enough overlap. Set the lens mm parameter to the maximum value (999 mm), since there is no curvature in scanned images.

Panorama Limitations
Panoramas including nearby objects can be tricky: when the photos are made, be careful to turn the camera on an 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.

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 Tools > Settings menu.

Setting Lens Parameters Manually
Make a panorama image of a brick wall (or any wall with lots of detail) with about 40% image overlap. The wall should be 5+ meters away. Within the panorama pre-align process, adjust lens_mm and lens_bow until the overlapping bricks 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 lens parameters may not be optimal. The result should roughly correspond to the nominal focal length of your lens (35mm equivalent). It may be off somewhat (my 27mm lens works best with a lens_mm setting of 29-30mm). I speculate that this is because wide-field camera lenses are not ideal lenses (pinhole equivalent). Most panoramas will still work OK even if the lens_mm setting is off by 10%.

Plugins Menu

Other image edit programs (e.g. Gimp) can be added to this menu. They will then work like any other edit function in Fotoxx. After using one of these external programs to modify an image, you can use the Fotoxx [Undo] and [Redo] buttons to check the results, perform additional edits with Fotoxx, or use [Save] or [Save+F] to save the edited image. The image passed by Fotoxx to the external program is a TIFF file with 16 bits per color. Most programs can read this but may use only 8 bits. When finished using the external editor, save the image back to itself ("save" menu) and exit the program. Fotoxx will then pick up the revised file and use it as though the edit had been done in Fotoxx.

To add a new plugin, use the function Plugins > Edit Plugins. Input a menu name (e.g. "Gimp"), a command to start the program (e.g. "gimp") and press the [Add] button. You can also remove a plugin by selecting it from the list and pressing the [Remove] button. The Plugins menu will not be updated until the next time Fotoxx is started.

The plugins are saved in a file: /home/<user>/.fotoxx/plugins which you can manipulate with a text editor if desired. This is the only way to change the sequence of the menu entries. Be careful not to screw up the format: menu = command (with exactly one space before and after the '=' character).

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

User Guide Changes
This is a summary of changes in the User Guide for the most recent versions. The intent is to enable you to survey the changes without reading the whole document.

Edit Functions Summary
A one-page "quick reference" summary of the image edit functions is displayed.

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 (see technical notes, below).

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.

Organizing a Large Image Collection for Searching

Fotoxx can edit and search for the following image attributes: photo date, "star" rating, tags, file names, and words appearing in captions or comments. These are explained in the Info section of the user guide. The image search function is also explained there. The following is an attempt to give an overview of the options and tradeoffs.

Physical organization - directory and file names: these names can be used as a basic organization that will enable you to find images even if more elaborate organizations (tags, collections, captions) are not used. The physical organization should be by time (not event or place or person ...). I suggest using one directory per year named 2001, 2002, etc. This will also help to keep any one directory from becoming excessively large. The image files may further be organized in time sequence by using MM.DD as the start of the file name. The rest of the file name can be an event or place name, and a sequence number.
Example: /top-directory/2011/08.20 Spitzbergen 23
This very basic organization allows Fotoxx to find files by searching file names. In the above example, a search for "spitzbergen" or even "spitz" will produce all the images of Spitzbergen. The batch rename function in Fotoxx (File > Batch rename Files) lets you rename a whole batch of camera files taken on one day at one location or event by selecting the files and inputting a template name like "08.20 Spitzbergen". The sequence numbers are automatic.

Captions: A simple method of organization is to use captions and comments (Info > Edit Captions/Comments). These are arbitrary text strings that can be added to images in rapid sequence:
input some text, press [next], input some text, press [next] ...
Captions and comments are two separate inputs but treated logically the same. They are searchable: words appearing in captions and comments can be searched for. You can add the names of persons or other information to each image, and then find them again quickly. With this method, you can search images using a combination of dates, file names, and any words appearing in captions or comments. Dates are taken from the EXIF data in the camera file. This presumes the camera clock was set correctly when the photos were made. If not, dates can be edited using the Info > Edit Tags function.

Collections: Another simple method of organization is to use named collections. Choose a name for each collection and assign any desired images to the collection, using basically two clicks per image (plus the time to find the images to add). This method is independent of tags, captions, file names, etc. See Tools > Manage Collections. Callections can be selected by name and viewed directly as a gallery of thumbnails or sequentially in the main window.

Tags: The most powerful tool is tags, but this is also the most demanding of organizational care. You can go through your images sequentially and add tags by clicking on a list of defined tags. New tags can be defined as needed. Images can have many tags, and can be searched for AND/OR combinations of tags (along with date, star rating, file name, caption, comments). Tagging is the fastest way to classify a large collection, needing a few seconds per image. The hitch is the tagging system. You need to lay this out in advance and stick to it, otherwise things can get chaotic. If you end up with 1000 tags they will not be very useful. If the images are physically organized by time, then groups of images will tend to have the same tags, which makes the process of adding tags faster.

User Guide Changes

This section is provided to help you quickly review the changes without reading the whole manual. This also helps translators to find the topics needing revision.

v.12.01

The introductory sections were rearranged and revised for functionality changes.
The paragraph about "my mouse" was replaced with "mouse ownership" and references to "my mouse" elsewhere were removed. My mouse is dead.
Select Area introduction - new paragraph about "layers" and "areas".
New topic: Search Metadata
Revised topic: Search Images
New Technical Notes: Preview Mode, File Size, Search Image Benchmarks.
Technical Note deleted: Missing Toolbar Button Text (see Tools > User Settings).
Technical Note deleted: How to get a traceback dump. This is now automatic.
Technical Note: Translations: file name for language xx changed to fotoxx-xx.po.
Lens Parameters topic was removed from Tools menu and added to Panorama topic.
Toolbar Style topic was removed from Tools menu and added to the User Settings topic.
User Settings menu and topic was added to the Tools menu.
New Technical Note: Ubuntu Unity Launcher (drop-down menu with options).
Technical Note revised: The option -blank was added to Command Line Options.

v.11.12

New topic: Auto-Trim
New topic: Fix Stuck Pixels
Topic Modified: Batch Resize / Export
Topic Modified: Convert RAW Files
Topic Modified: Panorama Images (clarifications)
Topic Modified: Select Area (select by mouse)
New command line parameter -translate (Technical Notes)

v.11.11

The Collection topics were all replaced by a new topic Manage Collections.
A new topic was added: Move Collections
A new topic was added: Organizing a Large Image Collection
Getting Started topic: modified for new startup synchronize functionality.
Two new topics under the Help menu: User Guide Changes and Edit Functions Summary.
Synchronize Files topic: automatic background operation and other changes.
Straighten function was renamed to Keystone Correction.
The keyboard shortcuts table was revised (A, Control+Z, N, escape).

v.11.10

Getting Started: Installation and Initialization changes for Synchronize Files.
Save Image File: new functionality to warn about overwriting an original file.
Print Image File: revised to match revised functionality.
Slide Show: new option to show only the latest version of each image file.
Gamma Curve: new topic, added after Brightness/Color.
Straighten Image: new topic, added after Unbend Image.
Slide Show: a sentence was added to explain pause/resume via spacebar.

v.11.09

The two menus Edit Caption and Edit Comments were combined.
The menu and topic Open RAW File was eliminated and Open Image File was revised.
(open Image File can be used to open a single RAW file).
A paragraph about scanned images was added to the panorama topic.
The topic Print Image File was revised for the addition of print margins.

v.11.08

Getting Started: the paragraph Fotoxx Startup was added.
General Editing Procedure: expanded for clarity.
Select Area: "Delete" was changed to "Unselect" in several places
(some people thought it meant deleting a part of the image).
"Whole Image" was changed to "Select Whole Image" in several places.
The new topic DRGB was added after Expand Brightness.
Revise RGB: A sentence was added for the new "delta" mode.
Show RGB: minor errors corrected.

v.11.07

Brightness/Color: explain the graph range and the step size for the buttons.
Match Colors: new topic for new function.
Save Image File: A new paragraph was added for Save to New Version.
Show RGB: expanded to explain the EV and OD units.
The Clone topic was expanded to cover the new function Clone Overlay.
Open Image File topic was expanded to cover "Open in New Window".
Toolbar Buttons (table): updated to: Save / Save+V / Save+F.
The Brightness Ramp topic was expanded to explain the new RGB buttons.
Keyboard Shortcuts (table): added entry "Control + v or V".
Toolbar Buttons (table): Undo and Redo text revised for shift key.
Replaced "Tools > Rebuild Search Index" with "Tools > Synchronize Files".
The Select Area topic was revised to improve clarity.
Select Area topic: an explanation for the unfinish button was added.
The new topic Revise RGB was added.
The topic Save to New File was revised to reflect changed functionality.
Technical Notes: command line options: add entry for -recent

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/share/fotoxx/locales/fotoxx-de.po (the German translation). A new translation for language code xx would be saved at /usr/share/fotoxx/locales/fotoxx-xx.po. After making such a file, you can test it by starting Fotoxx on the command line: $ fotoxx -lang xx.

Hardware and Software Requirements
Fotoxx works best on a fast computer with at least a gigabyte of memory. Multiple CPU cores are utilized for compute intensive functions (e.g. sharpen, rotate, warp, tone mapping, HDR, panorama). Slower computers (notebooks) 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.

Programs 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 image metadata (tags, comments, etc.)
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

Note: package names and exactly which files are included in each package are decisions made by each Linux distro. The above names are valid for Debian-based distros (including Ubuntu). For other distros you may have to dig to find the right packages to install.

Command Line Options

-v	output version and build date and exit
/.../imagefile.jpg	initial image directory or image file to open
-recent (or -r)	show a gallery of recent files, most recent at the top
-prev (or -p)	show the last file viewed in the previous session
-blank (or -b)	show a blank window
-lang lc_RC	language code (+ opt. region code) to use for GUI (de, de_AT, fr ...)
-slideshow /.../image1.jpg [ -music /.../playlist.pls ]	start a slide show using image1 and following images optional music playlist for slide show
-translate (or -t)	start in online translation mode (to capture the initial menus)

Status Bar Information
Example: CPU 123% 1234x987x8 0.45MB 56% edits: 3 menu locked area active dialog open

CPU 123%	current Fotoxx process CPU loading for all threads
1234x987x8	image width x height x depth (bits per color)
0.45MB	image file size (updated when a modified image is saved)
56%	zoom status, image % size
edits: 3	3 edits have been made and can be reversed with the [undo] button
menu locked	an edit function is active; other edit functions are blocked
file sync busy	synchronize files operation is running; image edit functions are blocked
area active	a select area is present and enabled - edits are confined within the area
dialog open	a dialog for user input is open and waiting

Ubuntu Unity Launcher
The following launcher will have a right-click dropdown menu with three different startup options: blank window, last image viewed, and a gallery of up to 100 recent images that can be selected. Save the following text as a file named fotoxx.desktop, make it executable, and drag the file to the Unity left side launcher list.

[Desktop Entry]

Name=fotoxx

GenericName=Photo Editor

Comment=Edit photos and manage collections

Categories=Photography;

Type=Application

Terminal=false

MimeType=image/bmp;image/gif;image/tiff;image/jpeg;image/png;

Exec=/usr/bin/fotoxx

Icon=/usr/share/fotoxx/icons/fotoxx.png

X-Ayatana-Desktop-Shortcuts=blank window;last image;recent images

[blank window Shortcut Group]

Name=blank window

Exec=fotoxx -blank

TargetEnvironment=Unity

[last image Shortcut Group]

Name=last image

Exec=fotoxx -prev

TargetEnvironment=Unity

[recent images Shortcut Group]

Name=recent images

Exec=fotoxx -recent

TargetEnvironment=Unity

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, with 3 RGB colors and 8 bits per color. Libtiff supports TIFF files with 1-bit depth (black/white), 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. Black/white and grayscale images are treated as RGB inside Fotoxx, with all RGB colors having the same value (shades of gray). Fotoxx converts camera RAW files to TIFF RGB with 16 bits per color, using the program ufraw-batch.

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 can lead to visible "banding" or "picket fence distribution". If the image was converted from RAW to 16-bit tiff before editing, this problem can be reduced, even when the image is converted back to 8 bits for storage.

Alignment Algorithm (HDR, HDF, Stack, Panorama)
Relatively few high-contrast or "edge" pixels are selected to control alignment in HDR, HDF, Stack and Panorama. The actual pixels used are shown in red during the alignment process, which is also entertaining. Each image in succession is systematically warped various small amounts and the fit with the previous or adjoining 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. Also the cylindrical image projection used for panoramas is only an approximation of what the camera lens actually does.

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.

Alpha Channels
Images having alpha channels (transparency information) can be edited, but the alpha channel is lost when the edited 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 multiple functions are applied in series: rotate (other than 90 degrees), HDR, HDF, stack, panorama, unbend, keystone, 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. Other functions do not reduce resolution (except for those that do it deliberately).

Image Deterioration From Repeated Saving of JPEG files
Reading a compressed JPEG image and saving it again can lead to loss of detail and increased JPEG artifacts. The effect seems to be negligible if the JPEG-quality is set to a high value. I read and saved a JPEG image 30 times using a quality of 90 (the Fotoxx default). A rapid A:B comparison with the original image showed no visually detectable loss of quality. The TIFF and PNG formats are lossless and therefore have no deterioration. They are only disk space hogs.

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 desired tags get lost, you must restore them manually.

Newline characters in User Comments or Captions
When editing User Comments or Captions, if you need to align text in columns, you can use the [enter] key to force new lines. These are converted into the string "\n" before being stored in image EXIF/IPTC data, since newline characters are not allowed (exiftool converts them into periods). If the text is viewed or edited again, the "\n" strings are converted back to new lines, so that the original text alignments are restored. This is not standard, so don't expect the text to remain aligned if viewed in Photoshop, etc. If this is a requirement, then do not use the enter key to make new lines when entering long text - just let the text overflow to the next line by itself.

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 /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 search_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/	annotations saved from Transform > Annotate Image
/collections/	image collections from Tools > Manage Collections
/saved_areas/	"cutout" files saved from the Select > Save dialog
/saved_curves	curve data saved from Retouch curve edit dialogs
fotoxx.log	Fotoxx outputs that may be relevant for diagnosing problems
parameters	setup parameters that are saved across Fotoxx sessions
printfile.png	the last file printed with Fotoxx
recent_files	a list of the last 100 files opened by Fotoxx, saved when Fotoxx exits
search_results	a list of the last image files found with Info > Search Images
tags_defined	a list of all categories and tags currently used in all images
search_index	a large text file containing searchable data for all image files
zdialog_positions	saved dialog window positions (relative to main window)

Preview Mode
Some edit functions use a reduced image size for a faster interactive response time. This reduced size is shown on the status bar as "preview". When [done] is pressed, the full-size image is then processed. This is why [done] sometimes takes noticeable time. A monitor-size image (2 megapixels) is 5 times faster to process than a 10 megapixel image. This method is used whenever the preview edits can be applied to the full-size image without visible impact (Rotate, Unbend, Warp and all brightness, contrast and color related functions). It cannot be used for things like sharpen and tone mapping because the results for a small image cannot be converted for a larger image. Thus Tone Mapping is not as responsive as Gamma Curve, for example.

File Size in Status Bar
The file size shown on the status bar while an image is being edited is the original (unedited) file size. The file size for an edited image is not known until the image is compressed and saved on disk. In memory the size is length x width x 3 colors x 2 bytes. A 10 megapixel image uses 60 megabytes in memory and typically < 2 megabytes on disk (if jpeg). When the edited image is saved, the correct file size is updated on the status bar.

Image Search Benchmarks
Here are a few benchmark numbers for a test image collection of 29892 images and a total size of 25.6 GB. The first benchmark is for a new install of Fotoxx on a computer having nearly 30 thousand images. The next two represent subsequent startups with no new image files and 15 new image files present. The Search Image benchmarks show the fast search speed using data that is in the search index file. The Search Metadata benchmark shows the slower search speed when non-indexed metadata is searched: the 4140 files from a prior Search Image were searched for specific EXIF data.

Synchronize Files from initial status (no index file, no thumbnails)	28 minutes
Synchronize Files at startup, no new files present	< 1 second
Synchronize Files at startup, 15 new files present	3 seconds
Search Images by date range, find 2178 from 29892 with a date in 2006	< 1 second
Search Images by file name, find 4140 from 29892 with "gallery" in directory/file name	< 1 second
Search Images by tags, find 258 from 29892 having both tags "alaska" and "scenery"	< 1 second
Search Metadata, find 228 of 4140 files having "2011" in EXIF: Modifiy Date	30 seconds

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, you may contact me. If you send me 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. Please explain exactly how to produce the error, and what version of Fotoxx and what Linux flavor you are using.

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 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 GNU/Linux ecosystem. Thanks to those who have donated their work for translations (see Fotoxx Help > About), and those who have donated their ideas for development and their time for testing.