Fotoxx User Guide

Fotoxx User Guide v.15.04
For experienced users, skip to the Table of Contents.
Review the recent changes to this guide.
Summary Description
Fotoxx is a Linux application for editing photos and managing an image collection.
Goal: Meet the needs of serious photographers while remaining fast and easy to use.
Fotoxx is standards compliant and compatible with other photo apps (no lock-in).
Fotoxx Capabilities
• Thumbnail browser / navigator with variable size thumbnails and list view.
• Camera RAW file conversion with retention of 16 bits per color.
• Internal processing in 24 bits per color (float), image file output in 8 or 16 bits.
• A comprehensive set of image edit, retouch and repair functions: brightness,
color, contrast, tone mapping, trim, resize, rotate, de-noise, paint, clone, red eyes,
write text, warp, HDR, panorama, montage, art effects, metadata edit and report,
edit / copy / paste selected image objects or areas (without using layers) ...
• Rapid visual feedback using the full image or selected zoom-in area.
• Batch tools for renaming, resizing, converting, adding and revising metadata.
• Search images using any metadata, directory / file names or substrings.
• Geotag mapping and reporting by location or by clicking on a map image.
• Albums of images from various directories ("named collections" or "views").
• Photomontage: put images and text into an arbitrary (huge) layout.
• Comprehensive user guide and help popups.
Hardware Requirements
Fotoxx works best on a strong computer: multi-core CPU, 2+ GHz, 8+ GB RAM.
Multiple CPU cores are used for compute intensive functions. A weaker computer
will generally work, but may be quite slow for some functions. A monitor smaller than
about 1600x1000 will feel confining. The monitor should have good color accuracy.
Software Requirements
Most recent releases of Linux will work (Debian, Ubuntu, Fedora, Suse, Arch ...).
Fotoxx packages are built using Ubuntu.
License and Warranty
Fotoxx is licensed under the GNU General Public License v3.
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: kornelix.com/fotoxx.
If you have questions, suggestions, or a bug to report, you may contact me.
Program Updates
To be automatically informed of new releases, subscribe to recent changes (RSS).
Latest source code for use with $ make install: tarballs
Latest installable packages: packages
Fotoxx packages are also available from many web sites and Linux distros.
Some of these are not updated regularly and may be quite old. It is better to use the above links.
NOTE: The optional package fotoxx-maps should always be installed after Fotoxx is installed.
(See World Maps View, below).
Getting Started
Quick Start
This is a 1-page document shown when Fotoxx is started the first time.
It is also available via the menu Help > Quick Start. quickstart-en.html
Fotoxx is easy to use but unconventional. Read the first few pages of this guide - up to the table of contents below. The rest can be used for reference as needed. Use the F1 key at any time to view information for the current or last-used menu function.
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 file of type JPEG, PNG, TIFF, etc. containing a single image (photo or illustration).
Installation
To install Fotoxx, try the appropriate package first: packages. This may work with one click.
If not, you must install from source code. Instructions are here: tarballs.
Initialization
Fotoxx needs to know where all your image files are located (directory and file names) and their imbedded metadata (dates, tags (keywords), geotags, captions, comments, ratings). This data is indexed for fast searching. Fotoxx also creates thumbnail images on disk, so that the gallery windows (thumbnail pages) will work fast. Fotoxx does not modify or copy your image files - it only reads them to get data for the search index and thumbnails.
When Fotoxx starts the first time, you are asked to supply a few key items of information for the initial file indexing process:
Top image Directories are those containing your image files, e.g. /home/<user>/Pictures or similar. Subdirectories underneath your top directories are automatically included, to any depth. Use the [browse] button to locate and add your top image directories, one or more. Other files may be mixed with your image files.
Thumbnails is the directory where thumbnail files will be placed. These are generally 1% as large as typical photo files (10K bytes compared to megabytes). You can use the supplied default or set another location.
If you have many thousands of images, the file index function may need significant time. A strong computer will process about 1500 images per minute (based on a 7200 rpm disk). Some computers will be much slower. When you start Fotoxx after new image files have been added to your collection, the Index Files function starts automatically to process the new images. This normally needs a few seconds unless there are hundreds of new images. For more details, see Index Image Files.
Navigation
Use the following three buttons to switch among the three available viewing modes:

Image view: the current image fills the entire window. (key F)
Gallery view: current thumbnail gallery (directory or other image grouping). (key G)
World Maps view: images with geotags are dots on the map, which can be clicked. (key W)

Essential Information for those who hate big user manuals (you and me):
• Menu functions and dialogs have popup help activated by keyboard F1.
• Zoom an image in / out with the left / right mouse buttons or mouse wheel.
• Pan and scroll a zoomed image with mouse left-drag.
• Gallery button: view a thumbnail gallery of images in the current directory.
• Click a gallery thumbnail: show the clicked image at full window size.
• Use the menus to edit the image and perform utility functions.
• The window title bar shows the current image file and directory path.
• The status bar above the image shows image and edit status information.

This User Guide is available in the menu Help > User Guide. This appears in your web browser. The F1 key will show a help topic for the current menu or dialog.
Window Views and Menus
Image File View
The current image file is shown, filling the entire window. Click the arrow button to move to the previous or next image in the gallery. Other buttons in this view show popup menus which are used to modify the image or perform utility functions.

change to gallery view
change to world maps view
custom favorites popup menu
sync, open, save, rename, print, trash ...
index, settings, batch functions, albums ...
tags, captions, geotags, search functions
select areas for separate edit, copy, paste
trim, rotate, resize, brightness, contrast, text ...
sharpen, denoise, red eyes, color, paint, clone ...
fix perspective, warp, flatten book page ...
artistic effects, conversions ...
HDR, HDF, stack, panorama, mashup ...
use other edit apps within Fotoxx
user guide, change log, translations ...
left / right mouse click: undo / redo one edit step (*)
left / right mouse click: move to previous / next gallery image
save (replace), save new version, save new file name

(*) When combined with the 'A' key, undo / redo becomes undo all / redo all. This is a convenient way to compare the original image with the version being edited.
Mouse Actions for Image File View
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 to the center. A right-click will restore the image to fit within the window. To pan or 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. In the menu Tools > User Settings, you can change the mouse pan / scroll mode to make the image move with the mouse instead of in the opposite direction.
Shortkut Keys for Image File View

+ or = | zoom in (amount adjustable in user settings)
− | zoom back, fit entire image within window
Z | toggle: zoom to 1x image size, zoom back to fit window
← / → keys | go to previous / next image in current gallery

Gallery View
All image files in the current directory are shown as thumbnails. Use this window to scroll around and select image files by clicking thumbnails. The arrow buttons allow scrolling forward or back by rows or pages. Use the zoom buttons to change the thumbnail size and the number of thumbnails fitting in the window. Clicking on a thumbnail will change to the full image view. Pressing the gallery button will show the gallery, with the current image scrolled to the top row. The directory path is shown at the top of the gallery window. Click on one of the higher level directories to go to that directory. Its subdirectories will be shown as folders. Click on one of them to go to that directory. Click the [Top] button to choose another top image directory (if more than one), the root directory ( / ) your home directory (/home/<user>), a gallery of the most recently viewed images, or a gallery of the newest images added to the image database.

change to image view
change to world maps view
set gallery to the directory of the current image file
open another directory for a new image gallery
open a list of bookmarks, select one and go there
use larger thumbnails
use smaller thumbnails or no thumbnails (show file names only)
sort gallery list by file name or date, ascending or descending
go to the top of the gallery (the first image files)
go to the last page in the gallery
go up (back) one page
do down (forward) one page
go up one row
go down one row
scroll gallery window in slow motion
batch and combine functions (convenience duplicates)

There are several types of galleries:
• Directory: all the image files in a single directory (folder)
• Search results: images found by the search function, in various directories
• Images in an Album, which may be located in various directories
• Recent Files: the most recently viewed or edited images
• Newest Files: the images most recently added to the image database

The gallery title bar will show the directory name (path), the album name, or "Search Results" or "Recent Files" or "Newest Files". All galleries work the same way: use the navigation buttons to move around within the gallery. Click a thumbnail to switch to image view, where you can edit the image if wanted. Press the gallery button to go back to the gallery view, which is positioned to show the current image in the top row.
A gallery thumbnail has a right-click menu with some commonly used functions. These include Popup Image and Popup Image (add). These create a popup window with a larger image, which can be rapidly zoomed to any size with the mouse wheel. If Popup Image is selected from another thumbnail, the popup image is replaced. If the (add) variant is chosen, a new popup window is created. Many windows can be open at once. This is especially useful for reviewing multiple photos to decide which ones to keep or discard. If the popup image is zoomed down to a small size, it disappears. Popup Image (add) has a keyboard shortcut: Shift + left click. F11 can be used to expand the popup to full-screen and back. Escape can be used to close the popup.
If the current gallery is not a directory gallery (e.g. Recent Files), you can navigate to a directory by using the [Top] button, the [Open] button, or the [Sync.G] button. The [Sync.G] button replaces the current gallery (e.g. Recent Files) with the directory of the current image file (the keyboard S key is a shortcut for Sync.G).
The [Sort] button is used to sort the thumbnails by file name, file modification date, or photo date (from EXIF data). The displayed date is photo date unless the sort is by file date. Ascending or descending order can be chosen.
World Maps View
This is initially a world map image. A left click on any area will expand that area to a much larger size, and a right click will return to the whole map view. The mouse wheel also works. Red dots are shown where there are images with a corresponding geotag location (from a camera GPS receiver or entered manually into the image EXIF data). The red dots can be clicked to show a gallery view of the corresponding images. The Tools menu allows selection of larger-scale contenintal maps, and you can also install other maps (countries, cities, parks, etc.). These all work the same way. The initial maps are provided in a separate package: fotoxx-maps. The maps are available to Fotoxx when the fotoxx-maps package is installed. Fotoxx-maps is large - almost 100 MB of maps are provided. Install fotoxx-maps only after fotoxx is installed.
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 (which dialog or main window) and how to change the ownership:

- The mouse is owned by the dialog that was last clicked or used. Mouse clicks and drags on the image are inputs to this dialog and DO NOT zoom or scroll the image.
- If you hold the CTRL key down while clicking or dragging the mouse, the image will zoom or pan / scroll, and active dialogs are not affected.
- The mouse wheel can always be used for zooming and re-centering the image.

Dialog buttons mostly work as follows:
[Proceed] - proceed with lengthy task based on dialog inputs.
[Apply] - apply settings from dialog to image, leave dialog active.
[Done] - same as [Apply], but the dialog is closed.
[Cancel] - discard image changes and close the dialog.
General Editing Procedures
The image in the main window (the current image) can be operated on with the edit functions (the menus Edit, Repair, Color, Bend, Effects, 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 [undo / redo] button can be used to review the before / after results for the current active edit function. Use a left / right mouse click for undo / redo respectively. After an edit function is closed, this button can be used to review all the edits done to the current image. When finished editing an image, use [Save] to save the modified image back to the same file, save to a new file version (filename.v01.jpg), or input a new file name and / or location. Many image edit dialogs have sliders, spin buttons, or editable curves that immediately 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 less than second for most edit functions done with a strong computer.
Edit Workflow
You can minimize the time needed to process many images if you understand the following:

- Choosing a new edit function will automatically complete a prior active edit.
  The new edit starts with the end result of the prior edit, and an undo / redo position is created.
- Opening a new image file during an edit function will automatically cancel the edit.
  The edit function is restarted with the new image.
- The [Save] button can be used during an active edit to save the current image status.
  The edit function restarts automatically, and an undo / redo position is created.
- Some frequently used functions have a [Prev] button which recalls previous settings,
  making it easier to process multiple photos needing the same or similar adjustments.

Example Workflow for the initial rotate and trim (crop) of a new batch of photos.
You can process one photo every few seconds (+ think time).
1. Copy the files from the camera memory card to a directory.
2. Open the first file.
3. Menu > Image > Trim / Rotate.
4. Turn the image if it needs leveling (drag the right edge).
5. Trim the image by dragging the trim borders to suit.
6. Press [Save] and choose "overwrite" or "new version" or "new file".
7. Press [Next] to start the next file. Press [Next] again to skip if wanted.
8. Repeat steps 4-7 for each image. The Trim / Rotate function remains open.
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" or "posterization" after editing the image, an indication that JPEG 8-bit color is limiting the image quality.
Complex Workflow
To edit with deep color (more than 8 bits), you can start with RAW files from your camera. There are three options for processing RAW files:

- Open a RAW file directly with Fotoxx: use the [Open] button or click the gallery thumbnail. The RAW file may now be edited normally. Save the edited image file as type TIFF or PNG with 8 or 16 bit color, or JPEG with 8 bit color. You cannot save the file as a RAW file type. Opening a RAW file may need several seconds, especially on a weak computer, and saving a RAW file as TIFF or PNG may also need several seconds (slower than JPEG).
- Open the RAW file with one of the File > Open RAW menus, or right-click the gallery thumbnail and use one of the popup menus. These are interfaces to specialized RAW editors (currently UFraw and Raw Therapee). Saving the file creates a TIFF-16 file in Fotoxx which may be further processed.
- Use one of the Tools > Batch RAW menus. You can select many RAW files and convert all of them to type TIFF or PNG with 8 or 16 bit color, or JPEG with 8 bit color. You may then select and edit these files with Fotoxx.

RAW files have typically 10-12 bit color depth and noise beyond that. Conversion into a PNG or TIFF file with 16 bit color will preserve the additional color depth available in the RAW file. The high color depth reduces the risk of visible "color bands" when retouch functions are used that can radically shift the brightness distribution. When finished editing, convert the final file to JPEG (quality level 70 or greater) to reduce the file size to 10% or less. Note that editing in deep color is more important than having deep color in the final image. You will rarely be able to see any difference between a 16 bit TIFF / PNG file and a JPEG made from that same file. To preserve the possibility of re-editing the image later, keep the RAW file, which is much smaller than the TIFF or PNG file.

Curve Editing Some image edit functions use editable curves. You can manipulate the curves to change some property of the image depending on some other property. The example here shows a brightness curve, whereby you can change brightness depending on brightness (e.g. brighten dark image areas without changing bright areas). Generally, the X-axis of the curve represents the input property (brightness in this example) and the Y-axis the output property (also brightness). The curves can be moved (pulled) with the mouse. "Up" increases the effect and "down" decreases the effect. An anchor point (black dot) is added to the curve wherever it is pulled, and this point remains fixed 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 an anchor point by right-clicking it.

Batch Editing
There are some batch functions in the Tools menu to speed some common tasks.
You can select a number of image files and apply a batch function to all of them.
Batch functions can be used for the following tasks:
• Rename files (using a base name and sequence number)
• Convert file types (e.g. png to jpeg)
• Find and upright photos made with the camera turned 90°
• Resize files (e.g. reduce for web upload or e-mail)
• Copy or move files to another location
• Convert RAW files to tiff, png, or jpeg
• Add / change / remove tags or geotags
Managing a Large Image Collection
You can use Fotoxx to manage a huge image collection and still be able to quickly find the images you want. Some effort by the user to organize the images is required. Search methods include directory and file names, image dates, image ratings, tags (labels for persons, places, objects, events ...), captions and comments, and geotags (location names and latitude / longitude). This is done in a standards-compliant manner so that data can be shared with other image management applications. Options for how to organize a large image collection can be found here.
Selecting Images from an Image Gallery Window
This procedure is used for all functions that operate on multiple image files (batch add or delete tags, batch convert images, batch RAW convert, manage albums, others). It is explained once here, and this topic is linked from each of the functions using this procedure.
The dialog box is used to select image files. Behind it is a gallery window for the current directory, album, or search results. To select an image, click its thumbnail and the image file will be added to the list in the dialog. Other options are shown below. You can navigate the gallery window to other directories by clicking on the directory names at the top or clicking on thumbnails represending subdirectories. You can choose images from any gallery 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. The last 100 images deleted are saved and can be re-inserted anywhere: each use of the [insert] button removes one image from the saved list and inserts it at the current position. To move images to a new position in the list: click the image file (its thumbnail will be shown), click [delete]. Repeat to delete more images. Click an image file to set the insert position, then click [insert]. The first deleted image will be inserted before the selected image. Repeat to insert more images from the deleted list. The file list in the dialog 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). 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. A single image may also be added multiple times to the list.
Thumbnail click rules:

- left click: add the image at the current list position.
- right click: remove the image from the list, if present.
- Shift + left click: add all images from the last image added to the clicked image.
  Ascending and descending order will both work.

Menu Shortcuts
The Fotoxx menus are large. You may need time to get used to them and remember where the functions are located. There are three shortcut methods available for frequently used functions:

- Right-click the main window or gallery window thumbnail.
  A popup menu appears with some commonly used menu functions.
- Keyboard shortcuts - these are documented in a table below.
  You can also add your own shortcuts for menu functions you choose.
- Favorites menu - a graphic popup menu. You can add text and / or icons that link to any menu functions you choose. You can arrange them in a layout window. You can leave this window open and access its functions with mouse clicks.

Table of Contents - Menu Functions

Favorites | User-designed graphic menu for quick access to frequent functions
File Menu | File Management
Sync Gallery | Replace thumbnail gallery with the directory of the current image file
New Window | Clone Fotoxx and open a new window slightly offset from the old one
Open Image File | File open dialog - open an image file to view or edit
Open Previous File | Go back to the last image file opened
Recently Seen Images | Gallery of the most recent image files viewed or edited
Newest Images | Gallery of the most recently added new image files
Open RAW File | Open a camera RAW file and edit with UFraw or Raw Therapee
Save to Disk | Save modified image to disk file
Rename Image File | Rename image files, optionally add sequence numbers
New Blank Image | Create a new blank image file
Trash Image File | Move the current image file into the trash folder
Delete Image File | Delete the current image file forever
Print Image File | Select printer / paper format / orientation and print image
Quit Fotoxx | Exit from Fotoxx.
Tools Menu | Utilities and setup functions.
Index Image Files | Rebuild the image search index and refresh thumbnails
User Settings | A collection of user preferences and settings
Keyboard Shortcuts | Assign keyboard shortcut keys to menu functions
Manage Albums | Make image albums, add and remove images, arrange the sequence
Slide Show | Show a series of images full screen (no menu)
Batch Convert | Rename / convert / resize / move / upright images
Batch Upright | Upright images that are rotated 90° or 180° (camera turned)
Batch RAW | Convert RAW image files to jpeg, png, or tiff
Brightness Distribution | Show brightness distribution graph of current image
Grid Lines | Add or remove grid lines for image alignment (warp, rotate)
Line Color | Set color for overlay lines (trim rectangle, select area outlines ...)
Show RGB | Show RGB values at current mouse position and prior clicked positions
Magnify Image | Magnify the image within a radius of the mouse. Works like a magnifying glass.
Dark / Bright Pixels | Highlight the darkest and / or brightest pixels, with adjustable thresholds
Find Duplicate Images | Search all image files and report duplicates
Monitor Color | Display a color palette for tuning your monitor
Monitor Gamma | Adjust monitor gamma for better image viewing
Change Language | Change the GUI language
Missing Translations | List missing translations to a popup window
Menu and Launcher | Add a system menu entry and desktop launcher
Burn Images to CD / DVD | Select images and write them to CD, DVD or BlueRay
Resources | Dump resource usage data to the log file
Metadata Menu | View and edit metadata (data stored within image files)
View Metadata (short) | View most important image metadata
View Metadata (long) | View all available image metadata
View Captions and Comments | View captions and comments only in a small popup window
Show Captions on Images | Show metadata captions and comments at the top of images
Tags Overview | Explanation of tags and how they are used
Edit Metadata | Add or change image date, rating, caption, comments, or tags (keywords)
Edit Any Metadata | Add or change any metadata
Delete Metadata | Delete specific metadata or all image metadata
Batch Add / Remove Tags | Add or remove multiple tags for multiple image files
Geotags Overview | General Information
Edit Geotags | Add geotag data (city, latitude, longitude) to image EXIF data
Batch Add Geotags | Add the same geotag data to multiple image files
Images by Location / Date | Find images from selected country / city / date range
Images by Map Location | Click on a map to get images at or near the selected location
Search Images | Find images with any desired metadata or (partial) directory and file names
Area Menu | Selected areas within images where edits are confined
Overview | Explanation of area selection and editing
Select | Select an area for subsequent editing
Show / Hide | Show or hide an area outline
Enable / Disable | Enable or disable an area for subsequent editing
Invert | Invert an area
Unselect | Unselect an area
Area Color | Change color of select area outlines
Copy / Paste | Copy an area to memory and paste it somewhere else
Open / Save | Save an area to a file and load it later to use in other images
Edit Menu | Functions that change or improve an image
Trim / Rotate | Trim / crop image edges and / or rotate an image to level it
Upright | Turn an image 90° or 180° to upright the image
Auto-Trim | Auto-select trim margins to remove after rotate, unbend, or warp functions
Voodoo Enhance | Automatic image enhancement
Retouch Combo | Edit brightness, contrast, color, saturation, white balance
Tone Mapping | Increase local contrast to to enhance details
Brightness Distribution | Flatten or expand the brightness distribution
Zonal Flatten | Flatten brightness distribution in independent image zones
Resize | Scale an image up or down (pixel dimensions)
Flip | Mirror an image horizontally or vertically
Add Text | Write text on top of an image
Add Lines | Add lines and arrows on an image
Brightness Ramp | Vary brightness across the image using horizontal and vertical curves
Paint Edits | Apply an edit function gradually by "painting" with the mouse
Leverage Edits | Apply edit functions regulated by initial brightness or color
Plugins | Use other image edit programs as edit functions in Fotoxx
Repair Menu | Functions to correct problems in an image
Sharpen | Sharpen a blurred image
Blur | Blur an image (e.g. smoothen skin)
Reduce Noise | Reduce noise (speckles) in low-light images
Smart Erase | Remove power lines and other spoilers from an image
Red Eyes | Remove red eyes from flash photos
Paint / Clone | Paint pixels or areas with color or with other parts of the image
Remove Dust | Remove dust spots on images made from scanned slides
Anti-alias Tool | Reduce jagged lines or edges in low-resolution images
Fix Color Fringes | Reduce chromatic aberration
Fix Stuck Pixels | Fix stuck pixels (always bright or dark) from camera sensor defects
Shift Colors | Shift RGB colors relative to each-other
Color Mode | Make a black-white or color negative, or positive from negative, or sepia
Color Profile | Convert an image profile, e.g. sRGB <> Adobe RGB
Match Colors | Match the colors in one image to those in another image
Revise RGB | Make complex color corrections that vary over the image
CMYK | Change brightness, color, contrast using CMYK colors
Bend Menu | Funtions that bend or warp an image
Unbend | Fix perspective problems
Fix Perspective | Straighten a photo made from an offset angle
Warp area | Distort image within an area by pulling with the mouse
Warp curved | Distort entire image by pulling with the mouse
Warp linear | Distort entire image by pulling with the mouse
Warp affine | Distort entire image by pulling with the mouse
Flatten Book Page | Flatten / straighten a photographed page from a book
Effects Menu | Functions that make artful transformations
Color Depth | Reduce color depth (posterize)
Sketch | Transform a photo into a pencil sketch
Line Drawing | Transform a photo into a colored line drawing
Color Drawing | Transform a photo into a solid color drawing
Graduated Blur | Blur pixels according to contrast
Embossing | Transform a photo into a simulated embossing
Tiles | Transform a photo into tiles (pixelate image)
Dots | Transform a photo into an array of dots
Painting | Transform a photo into a simulated painting
Vignette | Change brightness or color in a radial pattern
Texture | Add textured surfaces to an image
Pattern | Add a background pattern to an image
Mosaic | Transform an image into a mosaic using tiles made from all images
Custom Kernel | Apply a custom convolution kernel to an image
Make Waves | Warp an image with a wavy pattern
Directed Blur | Blur an image in a single direction using the mouse
Combine Menu | Functions that combine multiple images
High Dynamic Range | Make a high dynamic range image from multiple images
High Depth of Field | Make a high depth of field image from multiple images
Stack / Paint | Combine multiple images to remove tourists and cars
Stack / Noise | Combine multiple images to reduce noise
Panorama | Join 2-4 overlapping images horizontally
Vertical Panorama | Join 2-4 overlapping images vertically
Mashup | Arrange multiple images and text on a layout
Help Menu | User guide, translations, change log

Right-Click Popup Menus
These menus appear when the image view window or a gallery thumbnail is right-clicked with the mouse.
Most of these duplicate functions in the main menu. There are a few others:

Image View popup menu |
Copy to Location | Copy the image file to another location (duplicate the file)
Move to Location | Move the image file to another location (delete the original)
Copy to Clipboard | Copy the image file to the clipboard (some apps support clipboard paste)
Gallery View popup menu |
Popup Image | Open a window with a large image - resizable, movable, persistent until canceled
Popup Image (add) | Same as above, but a new window is opened instead of re-using the previous one
Others | The copy and move menus (see above) are also available
Popup Image shortcut | Shift key + left click on a gallery thumbnail creates a popup window containing the image. Zoom in/out using the mouse wheel. When zoomed small it disappears.

Keyboard Shortcuts
Keyboard shortcuts are available for some functions. The notation "Alt+G" means press and hold the Alt key, then press the G key. Many of these can be changed, and new shortcuts can be added (see KB shortcuts).

General |
F / G / W keys | Change view mode: image File, Gallery, World maps
F1 function key | Display user guide for current or prior function
F11 function key | Toggle main window to full-screen (no menu) and back
Image File View |
left / right arrow keys | Previous / next image
+ or = / - keys | Zoom image bigger / smaller (zoom amount adjustable in User Settings)
Z | Toggle: zoom image to 100% / fit image in window
S | Sync Gallery to current image file
M | Magnify Image
P | Open Previous File (or toggle between last two files)
U | Undo current edit, or undo one edit step in the current image
Shift+U | Redo current edit, or redo one edit step in the current image
N | Rename Image File
K | View and edit keyboard shortcuts
Alt+G | Grid Lines on / off (toggle)
T | Trim / Rotate Image
V | Voodoo Enhance
R | Retouch Combo
Escape key | Exit a dialog, exit Slide Show mode
Space Bar | Pause / resume a running slide show
Gallery View |
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
+ or = / - keys | bigger / smaller thumbnail size
Escape key | exit a dialog

Mouse Functions

left click | Zoom-in: magnify image, center at click position
right click | Zoom-out: restore image to window size. If no zoom, popup menu with common functions.
mouse wheel | Zoom in and out depending on wheel direction
left drag on image | Pan / scroll zoomed image, same direction or magnified opposite direction (like scroll bars)
right drag on gallery | Scroll down or up by dragging to the top or bottom edge, faster as mouse approaches the edge.
mouse + Ctrl key | Mouse acts on main window instead of a mouse-using dialog like Select Area.

Favorites Menu (heart icon)
This is a graphic menu in a popup window which you can populate with your frequently used functions and arrange them on the window using the mouse. The initial popup window (left image) is blank. Right click an empty space on the window to define a new menu entry. Right click an existing entry to modify it. Use the resulting dialog (right image) to define or change the menu entry.

menu text | text for the popup menu - optional if a menu icon is used
menu func | the Fotoxx function to use - the exact menu name
menu icon | menu icon - /directory.../filename.png - optional if a menu text is used
icon size | if icon is used, its size from 24x24 to 64x64 pixels
close window | checkbox: close the popup window when this menu is selected

Left drag a menu entry to move it somewhere else on the popup window. The popup window can be resized to fit the contained menu entries. Left click a menu entry to select the menu. If "close window" was checked, the popup window will close. All menu settings and icon files are saved in a configuration file whenever the popup window is closed. The configuration file and saved icons are located in the directory /home/<user>/.fotoxx/favorites. The configuration file can be edited directly - at your own risk. You can use either the English menu names or their translations for your locale. The menu names must exactly match the Fotoxx menus, but case is not significant. The menu text may include "\n" to represent a newline character.
Icon library: Icons for all image edit functions can be found here:
/usr/share/fotoxx/icons/edit-funcs
File Menu
Sync Gallery (Key S)
Replace the current gallery (recent files, search results ...) with the directory of the current image file: the image shown when image view is selected.
New Window
Start a new instance of Fotoxx in a new window, slightly offset for visibility. This 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. If the same image file is edited in both windows, the final result is the file saved last.
Open Image File or button [Open]
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 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, 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 images as an alternative to the Fotoxx navigation system.
Camera RAW files can also be opened. This may need a few seconds depending on file size and processor speed. You can proceed to edit the RAW file like any other image file. RAW files are also included in thumbnail galleries, as long as a .jpeg thumbnail image can be extracted from the RAW file (normally true). When saving a RAW file, you must specify a type TIFF or PNG (8 or 16 bit color), or JPEG (8 bit).
Open Previous File (Key P)
Go back to the previously opened image file, also if this is in a different directory. This differs from the button [Prev/Next] which goes to the previous or next image file in the current gallery (directory, search results, album). This function retains the current image zoom size and position, which is ideal for rapidly comparing two edited versions of the same image. Zoom-in on the area to compare, and use this function to switch back and forth between the two images.
Recently Seen Images
The 100 most recently seen image files (viewed or edited) are shown in a gallery, from which you can select a file to open.
Newest Images
The 200 most recently added new image files (from Index Image Files), are shown in a gallery, from which you can select a file to open.
Open RAW File (ufraw)
Open RAW File (rawtherapee)
Select and open a RAW camera file using either UFRaw or Raw Therapee.
You can make adjustments to the RAW file such as color temperature, white balance, brightness, color, noise, etc. from the program GUI. When the file is saved, a TIFF file is created with 16-bit color depth. This file is now opened in Fotoxx and can be further edited, saved as JPEG, etc. The RAW file type (file extension) must be included in the list of known RAW file types in Tools > User Settings.
Raw Therapee does not allow the location and type of the output file to be determined from a calling program, therefore you must save the output file where Fotoxx can find it - in the same directory as the RAW file. The file type must be TIFF (.tif) with a color depth of 16 bits.
Save to Disk or button [Save]
In the first dialog, select one of the three options: new version, new file name, or replace file.
Replace: Save the current image file back to itself. If a JPEG file, the default quality is used (this value can be set in User Settings).
New Version: 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 is used (this value can be set in User Settings).
New File: The 2nd 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 formats JPEG, PNG, BMP and TIFF. BMP is normally not recommended for photos (does not support metadata). 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 larger than JPEG files of the highest quality. TIFF files are uncompressed and larger than JPEG or PNG. TIFF and PNG files may be saved with 8 or 16 bits per color. The 16-bit formats only makes sense for files converted from a RAW format having more than 8 bits per color (camera RAW files are typically 10-12 bits with noise beyond that). 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 distribution is altered with a program like Fotoxx. PNG-16 files are smaller than TIFF-16 but slower to save due to the compression process. Saving a file as TIFF or PNG can be quite slow, especially with a weak computer.
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 will still work).
File sizes for a 10 megapixel image are roughly as follows (depending on image detail).
The jpeg numbers are the quality value given when the file is saved to disk.

tiff-16 | tiff-8 | png-16 | png-8 | jpeg-100 | jpeg-90 | jpeg-80 | jpeg-70
70 MB | 35 MB | 23 MB | 17 MB | 8 MB | 3 MB | 2 MB | 1 MB

The default JPEG quality is used unless you change the value in the save-as dialog.
The default value is a User Settings option, and is initially set at 90.
The Technical Notes section describes potential loss of image quality from repeated edit and save of JPEG images. At the default quality of 90 this can be generally ignored.

Rename Image File (key N) This function can 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. Open the first image file in the series, input a new name, and press the [apply] button. Use the [next] button to move to the next file if wanted. You can use the same name again by pressing the [previous name] button and then add a suffix or sequence number. Press the [add 1] button to increment the sequence number.

New Blank Image
Create a blank image with specified pixel dimensions and color. This can be used as a background for cutouts taken from other images (via Select Area) and annotation text (via Add Text). Input a file name, choose a background color, and set the desired pixel dimensions. See also the Mashup function.
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. If both standard and desktop trash do not work (some distros are like this), you are given the option to delete the image file.
Delete Image File
The current image file is deleted permanently. There is no recovery possible.
Print Image File
The print menu brings up a standard Page Setup dialog where you can select a printer, a paper size (letter, A4, etc.), 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 paper margins and an image scale. The margins can be used to shrink the image or shift it on the page. Image scale can be set in the range 5-100%, where 100% means print the maximum size image that fits within the margins. Smaller values will shrink the image proportionally. The actual print size (image width and height in centimeters) is updated in the dialog as margins and scale are changed, and this can be used to reach a desired printed image size. After the margins dialog, a Print dialog starts for the actual printing. This includes paper type and qality inputs, and a preview of the printed layout which can be accepted or rejected.
Tools Menu
Index Image Files
The Index Image Files function is needed when Fotoxx is started for the first time, when you add new image files to your collection, or if you move or rename image files or their directories. This function will create missing thumbnails, replace outdated ones, and refresh the metadata index using current data from your image files. This may need significant time if you have many thousands of (new) images and / or a weak computer. A strong computer can process about 1500 image files per minute, but some computers will be much slower ("strong computer" means a 3 GHz CPU and a 7200 rpm disk). If there are no new image files, Fotoxx startup should take a few seconds at most (my computer, with 7700 images, needs <1 second). If the image files are on a solid-state disk (SSD) the initial indexing speed may exceed 2800 image files per minute.
Image files created (i.e. edited and saved) or moved within Fotoxx are taken care of automatically. Index Image Files is only needed when new image files are created from outside Fotoxx (e.g. a new batch of photos is added), or if files are moved or renamed from outside Fotoxx.
Index Image Files starts automatically at Fotoxx startup. It can also be started manually from the Tools menu. Unless there are hundreds of new images to process, this will be done in a few seconds.
Enter your top image directories (e.g. /home/<user>/Photos). Enter the directory paths directly in the window, or use the [browse] button to locate and add directories. These directories and any subdirectories containing images will be processed. It does not matter if other files are mixed with the images. The simplest way is to use /home/<user> as the only top directory, but it is better to separate the image files from the hundreds of thousands of other files that may be under /home/<user>.
Enter the thumbnails directory where thumbnail files will be stored. Use the supplied default or set your own location. The directory name must end with .../thumbnails, and this will be added to your selection if needed. If the lowest directory level (/thumbnails) is not present, it is created.
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, geotags, titles, or ratings in your images (using Photoshop or other apps), these will also be searchable. After the images have been indexed, searching them (by caption, comments, file name, tags, geotags, date, rating) is almost instantaneous. See Search Images.
User Settings
Various user preferences and settings are collected in this dialog.
They are also saved in the file /home/<user>/.fotoxx/parameters.

Startup Display | Determines the initial window content when Fotoxx is started. Recent Files: the most recently viewed or edited image files (gallery display). Newest Files: image files most recently added to the Fotoxx database (gallery). Previous Gallery: the directory of the last image viewed (gallery). Previous Image: show the last image viewed. Blank Window: start with no current image and the top image directory in the gallery. Directory Gallery: the given top image directory or sub-subdirectory underneath. Image File: the given image file.
Menu Style | The menu style: icons only or both text and icons.
Image Pan (zoomed image) | Drag: image moves with the dragged mouse. Scroll: image moves against the dragged mouse (like invisible scroll bars). Magnified: movement is magnified: multiple drags for large movement are not needed.
Monitor scale | If a high DPI monitor is scaled up to make fonts larger, enter the scale value used. 1.0 is default. If clicking inside the Gallery top panel jumps to the wrong directory, the problem is here.
Zooms for 2x | Choose 1, 2, or 3 zooms for each 2x increase in image size.
JPEG quality | The default quality value when saving an image as a jpeg file type.
Thumbnail size | The pixel size for gallery thumbnail width/height: 128|256|512 (default 256). 512 is a bit slower but better for a large monitor or one with a high DPI resolution, or when viewing gallery pages with a large thumbnail size. If this is changed, you need to delete your thumbnail files so that the index process is forced to rebuild them with the new size. Only those needing replacement are rebuilt.
hidden directories | Show hidden directories in gallery view. If not checked, these are not displayed.
prev/next version | Show only the last versions of image files when using the prev/next button or KB keys.
RAW command | The command used to convert camera RAW files to tiff-16. This can be changed if you need. See the man page for dcraw for more details.
RAW file types | The RAW file types recognized. If your camera uses something else, add it to the list and this may work. You can also shorten the list to those file types you actually use.

Bookmarks (Gallery View only)
Assign names ("bookmarks") to chosen gallery locations (directory and image file), keep the names in a list, and use the list to select a name and go instantly to the associated gallery and image position in the gallery. There are two parts: an edit dialog to build the list of bookmarks, and a [GoTo] button in the gallery view to show the bookmarks and select a location to go to. To assign new bookmarks, press the [GoTo] button and then select [Edit Bookmarks] in the dialog that follows. The Edit Bookmarks dialog is started. Click on a gallery thumbnail to add this location to the bookmark list. The assigned bookmark name will default to the file name. This shows up in an input field which you can edit to assign a better name. If you select an existing bookmark with a mouse click, its name is shown in the input field. You can change the name or press [delete] to remove the bookmark. New bookmarks are inserted at the last bookmark location selected. To go to a bookmark, press the [GoTo] button. The list of bookmarks is shown. Click on an entry to go there.

Keyboard Shortcuts (key K) This function is used to view or change custom keyboard shortcuts. The currently assigned shortcuts are shown in the window. Enter a new shortcut using the keyboard. You can use the keys A-Z, 0-9, F2-F9, and most of the symbols (# $ & ^ < etc.). You can combine a key with Ctrl, Alt or Shift: Press and hold Ctrl, Alt or Shift, then press the key, then release both. Select one of the available menu assignments from the drop-down list. To remove a shortcut, select it and press [Delete]. If you press [cancel] or [x] all changes will be discarded. The shortcuts shown in the tables above are reserved and changing them is blocked.

Manage Albums - Concepts
An album is an arbitrary sequence of images that is manually assembled from existing images. This is one method to make groups of associated images. An image album 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 albums, or may be present more than once within an album. Albums can be used to group images with some shared attributes, such as photos from a vacation trip, photos of a given person taken at different times or events, a "best photos" collection, etc. You can add and remove images in an album and rearrange the order of the images. Once an album is made, you can call it up by name and it becomes a gallery. This gallery works like any other: you can scroll through the gallery, step through the images with the [Prev/Next] button, or edit the images. Keep in mind that editing an image in an album will edit the unique image file, so any other way to view this image will show the same image.
Image Cache
This is an intermediate storage area used to hold selected images for later insertion into an album. In general, you select image files from gallery windows and add them to the cache, then you make a new album with images from the cache, or you add the cached images to an existing album at a chosen position within the album.

Manage Albums Dialog New: Start a new album or replace an existing one. The dialog shown immediately below is started. Choose: Choose an album to view or edit. The gallery window will show its current images. Use the thumbnail popup menu (below) to add or remove images. Images: Add images to the image cache using the standard dialog for selecting images from gallery windows (link). Select image files in any order from any gallery. You can also use Search Images to create a gallery for selecting images, or choose an album gallery. Selected images are added to the image cache. The cached images can now be added to an album using the popup menu (below). Clear: Discard all images in the image cache. Delete: Select an album to delete. Image files are not deleted. New Album dialog Specify an album name, or use the [browse] button to select an existing album to be replaced. Select one of the three options. Option 1 creates the album with no images. Option 2 fills the album from cached images, if any. Option 3 creates the album from the current gallery. This may be a directory, the output of an image search, or an album. Right-click Popup Menu Gallery thumbnails from any gallery have a right-click popup menu. Copy to Image Cache adds the image to the image cache. The other menu entries are present only if the gallery is an album. Cut to Image Cache removes the image from the album and add it to the image cache. Paste Image Cache Here (xxxx) inserts all cached images at the clicked position. Click roughly between two thumbnails where the images will be inserted. The (keep) option keeps the image cache and (clear) clears it. Remove from Album removes the clicked image from the album.

Drag and Drop
You can rearrange images within an album by dragging thumbnails with the mouse. Drag the thumbnail until the mouse cursor changes to a small image of the thumbnail. Continue dragging this image to the position where it should be inserted, and release the mouse button. Position the mouse roughly between the images where the dragged image is to be inserted. If the drag approaches the top or bottom edge of the window, the gallery will scroll to bring more images into view.
Summary

- Make a new album: Use the [New] button and provide a name.
- Add images to an existing album: Use the [Choose] button and select an album. Use the [Images] button to select images from any gallery. After closing this dialog, the gallery reverts to the chosen album. Right-click an album thumbnail and select one of the Paste menus to insert the selected images. You can also choose another album and insert the images if you did not clear the cache.
- Remove images from an album: Right-click each thumbnail, then select the Remove menu.
- Move images within an album: Use the Cut or Copy menu and the Paste menu to move multiple images. To move one image at a time within a single album, you can use mouse drag and drop.

Slide Show
With this function you can show a pre-selected sequence of images in full-screen mode.
There are three dialogs used to define and customize a slide show.
Use the Manage Albums function to assemble the images for a slide show as an album with an assigned name. This allows you to collect images from anywhere in your image database and order them as desired. In the slide show dialog, press [Select] and choose an album from the list provided. Press the Proceed button to start the slide show with the first image (or the current image if a member of the slide show album). Use the escape key or F11 to exit the slide show and return to the dialog.
The spacebar can be used to pause and resume between slides. The B-key can be used to blank the screen and pause the show. Press again to restore the current image, or press the spacebar to resume with the next image. You can use the left and right arrow keys to go back and forth within the sequence of images. You can interrupt the slide show by pressing the ESC key for a gallery view. Click on a thumbnail image, and this will be the next image to show. This allows you to skip around more easily than stopping and starting the show each time. The M-key can ge used (whenever the slide show is paused) to start the magnify function to view selected parts of the image at higher size.
Seconds: The standard time each image is shown. This can be modified per image with the Images Preferences dialog.
Clip Limit: Images are scaled to fit the window. If the image and window aspect ratios are different, this will create black margins above and below or left and right of the image. You can optionally make the images expand to fill these margins and cut off the opposite sides of the image (e.g. if the margins are on the left and right, the image is expanded to fill these margins and cut off the top and bottom equally). You control how much of this is allowed with the Clip Limit, which is the percent difference in aspect ratios above which expansion and clipping will not be done. Zero means no clipping is done, 10% means that images with 10% or less difference in aspect ratio will be expanded and clipped.
Music File: An optional music file or playlist that will start when the slide show is started.
Full Screen: If checked, images are shown full-screen without menu, title bar, etc.
Auto-replay: if checked, the slide show will start over after reaching the end.
Press [transitions] to start a dialog to select and customize the transitions between images. These include instant replacement, fade-out / fade-in, and many animated methods of image replacement (e.g. the new image expands from the center to replace the old image). Select the transitions to be used and whether they are used randomly or in sequence. The slowdown parameters can be used to slow transitions that may operate too fast on some computers (some may be too slow on slow computers, but this cannot be helped). The preference parameters specify a relative preference which will influence how frequently the transition type is used when random sequence is selected. The random method avoids using a transition that was used shortly before, and will only work if 5 or more transitions are selected.
Press [image files] to start a dialog for image preferences. These are optional. An image is selected for customizing by clicking its thumbnail (press the [gallery] button or G-key to show thumbnails). The dialog is filled-in with default settings or the previous settings for this image. Enter revisions and press [done], or click on the next image to be customized. If Play Tone is selected, a tone is played when the image appears during the slide show. The Show Caption / Comments times determine how long the image caption and comments will be shown above the image. After this time they disappear. Captions and comments are edited with Edit Metadata. The Wait times determine how long the image will wait before and after the optional zoom-in, before moving on to the next image. These are always used, even if there is no zoom. Zoom size controls how much the image will be zoomed-in and Steps determines how many steps are made during the zoom. 1.0 means no zoom, and 3.0 is the maximum zoom (image is 3x larger). Use at least 300 steps for a smooth zoom, and more than this if you want it to zoom-in more slowly. Zoom location determines the center of the zoom-in, expressed as a percent of the image width and height (50/50 is the center of the image). These are set by mouse-clicking the thumbnail image at the desired zoom-in center. Transition is used to select a transition type to be used for this image. If "next" is selected, then the normal transition sequence is used, as specified in the Transitions dialog.
Sequence of slide show events for each image:
• play the tone if specified
• show the caption and comments for the specified times (may be zero)
• wait for the first interval
• perform the zoom-in (if the zoom size is > 1)
• wait for the 2nd interval (may be zero)
• wait for the standard interval specified in the Slide Show dialog
• do the transition to the next image
Batch Convert Files
This function is used to rename, convert, resize, upright and move multiple image files at once.

Select Files | Select files to convert from a gallery window (link).
New Name | Optional new name with # characters to be replaced with sequence numbers.
base, adder | Starting sequence number and adder for each output file.
New Location | Optional new directory location for the converted files.
new file type | File type for converted images, or "no change".
max. width, height | Output images will fit within these dimensions (ratio is not changed).
delete originals | Delete the input files after successful conversion.
copy metadata | Copy all EXIF and IPTC metadata to the output files.
upright | If an image is rotated 90°/180°, upright it (status known from EXIF).
sharpen | Sharpen output images using the two supplied parameters

When input and output file names are the same, delete originals is ignored.
If an output file already exists, the input file is not converted.
For an explanation of the sharpen parameters, see the Sharpen function.
Albums
If image files are renamed or moved using Batch Convert, and if deletion of the original image files was also specified, then all albums containing any of the input files are updated to reflect the new names and locations.
Upload Photos to a Website
Most photo websites have the ability to upload multiple image files from a single directory, using only a web browser. Use the above Fotoxx function to select, resize, and export image files to the desktop or any other directory. From there, use the photo website's native browser interface to upload the image files.
Batch Upright
This function works like Batch Convert Files but only does the upright function, replacing the original image file with the uprighted version. It depends on EXIF data to know when a file is rotated. It ignores files that are not rotated. It is much faster than Batch Convert Files. You can simply select all candidate files and let it find the ones that are rotated.
Batch RAW (DCraw)
Batch RAW (Raw Therapee)
These functions convert selected RAW image files to JPEG, PNG-8, PNG-16, TIFF-8 or TIFF-16 format, using the program DCraw or Raw Therapee. The PNG and TIFF formats have either 8 or 16 bits per color. RAW files generally have 10-12 bits per color, and noise beyond that. Therefore use a 16 bit format to keep all of the data available from a RAW file. The difference between 8 and 16 bit color is rarely visible, but a higher color depth provides a greater margin for retouch functions that can radically shift the brightness distribution, causing a problem known as "banding" or "posterization".
Use the [Select Files] button to choose one or more RAW image files from a gallery window (link). Choose one of the output formats. Choose one of the downsize options if wanted, and set the auto sharpen parameters if wanted. See the Sharpen function for an explanation of these parameters.
The remaining parameter options (white balance etc.) apply only to DCraw - they are not shown if Raw Therapee is used, because parameter settings for batch operation are not available (defaults are used). The default settings for DCraw generally work well and you probably will not need to change them. The parameters for dcraw are documented in the dcraw man page (command: $ man dcraw).
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 (a strong PC does about 40 files per minute for most RAW file types and TIFF-16 output). PNG-16 produces much smaller files than TIFF-16 because the files are compressed (with no data loss). This also needs more time to do the compression work.
Brightness Distribution
This function opens a small window that shows a brightness distribution graph of the current image in the main window, or the currently selected area of the image. This graph updates immediately for new images or as edit functions change the image. There are four graphs in four colors: red, green, blue graphs are for the respective colors. The black graph is for overall brightness which is labeled "white". Use the buttons [Red] [Green] [Blue] and [White] to select the colors to show. White means all colors added together.
Grid Lines (key Alt+G)
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 vertical and horizontal lines separately. The keyboard shortcut Alt+G can be used to toggle the grid lines on and off (this shortcut can be changed). If an image is printed with grid lines enabled, the grid lines are also printed. The x- and y-offset controls can be used to shift the grid lines to intersect a desired point in the image.
Several edit functions have a button [grid] which starts this same dialog. The resulting grid line settings are specific to that function only, and will be restored whenever that function is in use.
Line Color - Change Color of Foreground Lines
Some functions draw lines over the image (Trim / Rotate, Area Outlines, others). You can change the color of these lines to maximize contrast against the background image. The small dialog can be left open while editing, to conviently switch among the available colors (black, white, red, green).
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 or PNG file. EV (exposure value) is an alternative unit, useful for precise color adjustment. EV is zero for mid-brightness (128). The outputs are updated immediately if the image is being edited. The last nine points clicked are shown. The points are labeled on the image corresponding to the letters A-I in the dialog window. If "delta" is checked and the image is being edited, then the changes are shown instead of the absolute values. If no edit is active, "delta" does nothing.

RGB | 0 | 1 | 2 | 4 | 8 | 16 | 32 | 64 | 128 | 256
EV | nan | -7 | -6 | -5 | -4 | -3 | -2 | -1 | 0 | 1

Magnify Image (key M)

This function magnifies the image in an area around the mouse pointer. Left-drag the mouse around the image to magnify different areas, analogous to viewing a printed image through a magnifying glass. Use the dialog to adjust the radius of the area and the amount of magnification. A mouse click will end the magnify, and a new mouse drag will start it again. Use the M-key shortcut to start or end the Magnify function.

Dark / Bright Pixels
This function is used to highlight the darkest and / or the brightest pixels in an image. Adjust the two sliders to set the brightness thresholds, which are initially 0 for dark pixels and 255 for bright pixels. Pixels with a brightness less than the dark threshold or greater than the bright threshold are highlighted on the image. The image responds quickly to changes in the sliders. You can use this function in parallel with edit functions to control edit results.

Find Duplicate Images This function is used to find duplicated image files anywhere within your image database. A duplicate image file can be an image file that exactly duplicates another image file, or an image file that "almost" duplicates another. For the sake of speed, thumbnail images are compared in memory. Hence it is possible that identical thumbnails are found for which the main images have some minor (likely invisible) differences that do not show up in the thumbnails. An image copy that was reduced to 1/2 size is likely be classified as a duplicate. The thumbnail size can be set from 32 to 256 pixels (max. width or height). A larger size reduces the probability of false positives. The thumbnail size greatly affects the amount of main memory required - e.g. for 100K images, size 32 needs 220 MB, whereas size 64 needs 880 MB. The memory required is roughly size x size x 0.75 x 3 x (image count). Two parameters are used to set the sensitivity for detection of identical or nearly identical images: pixel difference is the RGB value difference below which pixels are considered equal. Set to 1 to detect any pixel difference. pixel count is the number of different pixels below which two images are classified as duplicates. Example: if pixel difference = 3 and pixel count = 100, then images are classified as duplicates if fewer than 100 pixels are different by less than 3. The output is a gallery view, showing each pair (or more) of duplicate images. Screening 100K images needs about 11 minutes on a strong PC.

Monitor Color 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 on the monitor. The standard value is 2.2 and this should normally be used for image editing. Adjust the dialog slider until the middle band has the same brightness as the upper and lower bands at scale location 2.2. Be far enough from the monitor that you cannot see the fine lines in the chart. The chart only works at 100% size, so do not zoom the chart. The command line utility "xgamma" is required (normally present). The chart image originates from Norman Koren. The linked web site has more information about this chart.

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 (technical notes).
Missing Translations
This function lists all missing translations to a popup window. Translations left as English are not reported, since this is often deliberate, e.g. words like "font" or "icon" may be the same in both languages.
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.
Burn Images to CD / DVD
This function enables you to choose image files and burn them into a CD or DVD or BlueRay disc. 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 the disc.
Resources
This is a diagnostic tool to monitor resources, especially memory leaks.
The popup window contains the following data:
process time: CPU time used, since the last time shown here
zdialog counts: total dialogs in memory and those still active (visible)
zmalloc counts: memory allocations and releases since the last time shown here
MB: total allocated memory at this time
Metadata Menu
Metadata means text data that is stored inside an image file. Digital cameras automatically create some data automatically, such as date and time, technical data about the camera and image, and location data (if the camera has a GPS receiver). Other data can be added by the user, such as captions, comments, ratings, and tags (keywords that can be used to search images, e.g. persons, places, things, events).
The program exiftool must be installed for the metadata functions to work. Fotoxx uses this program to read and write metadata. For recent Ubuntu, the package name is: libimage-exiftool-perl. Other distros may be different.
There are several alternatives for organizing a large image collection so that it can be easily searched. It would be good to review these before choosing a system.
View Metadata (short)
View Metadata (long)
Short Report
Long Report
The View Metadata functions will display available metadata for the current image file. 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 (frequently found in published images). If an image is edited and then saved, the metadata is updated and stored with the new image. The View Metadata 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 metadata available.
Fotoxx uses the following EXIF / IPTC data items:

Key Name | Fotoxx Usage
Date / Time Original | Edit Metadata function - image date
Keywords | Edit Metadata function - image tags
Rating | Edit Metadata function - image stars
User Comments | Edit Metadata function
Caption-Abstract | Edit Metadata function
Geotags | Edit Geotags function, 3 search image functions
Image History | History of Fotoxx edits applied to the image
any key | Edit Any Metadata, Delete Metadata

Show Captions on Image
Show the metadata items IPTC Caption and EXIF User Comments at the top of each image displayed. This menu is a toggle switch - the display of captions and comments is set on and off alternatively. If neither is available, nothing is displayed. If only one is available, it is displayed. If both are available, they are displayed on two lines. The lengths are truncated at 200 characters. To see up to 1000 characters, use the View Captions and Comments function. If Show Captions switched ON, captions and comments are also displayed during a Slide Show.
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 persons or things contained, 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 meaningless 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 a 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, 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:
• max. tag length: 50 characters per tag
• max. tags for one image file: 1000 characters
• max. tags in a tag category: 100,000 characters
• max. unique tags overall: 100,000 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 still quite fast. Physical file organization is also preserved: image files located together in their directories will also appear together in search results. All in all, my recommendation for the casual photographer is to use fewer and broader tags.
Images downloaded from the internet often have many tags in them (sometimes every conceivable tag has been added). These of course have no organization and are collectively chaotic. If you develop a tagging system of your own, it is best to review such images and clean up the tags to conform with your system, or delete them. Failing this, editing tags will become complicated because there will be thousands of them, without categories, and usually meaningless for you.
Edit Metadata
The function Metadata > Edit Metadata is used to edit the most frequently used metadata: image date, rating, caption, comments, and tags. The dialog initially shows existing data for the current image. After making additions or changes, press [Apply] to update the image file. The changes apply to the current open image file and version visible in File View. There is no file versioning for metadata changes unless you do this yourself by saving a new version and then modifying the metadata.
Existing tags are shown in "image tags". Available tags are shown in the "defined tags" window below. One of these tags can be added to the image by clicking with the mouse. A tag can be deleted from the image by clicking it within "image tags". Tags recently added are shown in "recent tags". 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 yyyy-mm-dd or a shorter format yyyy or yyyy-mm. 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 [get prev] button fills-in the date from the previous data entered. This is to allow easy dating of a series of images. If time is important, you can include a time using the format hh:mm ( :ss is optional). You may enter an optional "stars" rating for the image. The dialog remains open if you navigate to a new image, and the data is updated from that image. The [Apply] button writes the data to the image file and to the metadata index file used for searching images.
Manage Tags
This dialog starts from the button [manage tags] in the Edit Metadata dialog. 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 category and the tag, then 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]. 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.
Use the [orphan tags] button to list tags that are defined but not assigned to any images. These may be deleted if no use is planned.
Edit Any Metadata
This is a dialog for editing any EXIF or IPTC metadata. Enter the desired key name and press [Fetch]. Change the returned data, if any, and press [Save]. The metadata is updated. You may enter the key name in lower case and with or without spaces between the words, e.g. "Bits per Sample" and "bitspersample" will both work. To see all present keys and data, use View Metadata (long).
Delete Metadata
Specify the key name to delete, or select "All". The metadata is deleted. Use "All" to clean an image of any identifying information that might be in there. Some keys are not deletable, e.g. "File Name".
Batch Add / Remove 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 to create new tags, use the [manage tags] button as described above. When done specifying image files and tags, press [proceed] to add the tags to the image files.
Removing tags works much the same way: select the image files and the tags to remove. You can add and remove at the same time if the images to process are the same ones. To replace tags, specify the new names in the add tags list and the old names in the remove tags list. To get a list of images having specific tags (which you want to remove or replace), use the Search Images function (below) to find the images, then start this function and use the [select files] button to add all the image files that you just found, or select any subset.
Geotags - General
Modern cameras can record the location of each photo, using an internal GPS receiver. Latitude, longitude, city and country are recorded in the EXIF metadata of the image JPEG or RAW file. The Fotoxx Edit Geotags function allows location data to be entered or revised for any image. The Fotoxx Search Images function can find images by location, including an optional range: e.g. find all photos taken within 30 km of London. Locations may also be specified by clicking on a map. There are two functions that can find all images from a specified location or region: Images by Location / Date: find all images for a country, a country and city, or a country, city and date range. Images by Map Location: click on a map to show all images within a range of the clicked location.
Edit Geotags
The dialog displays the location data for the current image, if any. The live display is updated when a new image is opened. For an image with missing or incorrect location data, enter a city name and use the [Find] button to either complete the data in the dialog, or get a list of matching cities to choose from (e.g. London, United Kingdom and London, Canada). Partial matches are found, so you can usually enter a leading substring, e.g. "hono" for Honolulu. Use the [Apply] button to enter the data into the EXIF metadata for the current image, and also into the metadata index file for later searching by location. If the data is revised in the dialog (spelling of city / country, or revision of latitude / longitude), this will take precedence for future city searches. Use the [Prev] button to fill the dialog data with the last location used. If the [Find] button does not find a city (it is not present in any other image), you can use the [Web] button to find the city and location data from an internet web service (MapQuest Open for now, but this can change). The location data is completed and returned into the dialog. These names are not standardized and there are many duplicates, so check the returned data for reasonableness and change the spelling and capitalization if needed. The [Apply] button will add the location data to the image, and this location will be available for future use by using the [Find] button. If the [Web] button fails, you can manually find the city in the internet and enter the location data into the Edit Geotags dialog. Pressing [apply] will add the data to the current image and make the location available for future use.
Here are two web sites to look-up a city / country (there are many others):
http://www.worldatlas.com/aatlas/findlatlong.htm
http://brainoff.com/geocoder/
Blank the latitude and longitude if you want to save only the city and / or country name in the image file. If the latititude / longitude data is changed from the values returned by [Find], these values are saved and will be used from now on for new entries for this city. Previous images with the same city are not revised. You can use Images by Location / Date (see below) to find all images for a city, and Batch Add Geotags (see below) to change the latitude / longitude for all of them.
Note: If the location name is not a city (e.g. Yellowstone Park), simply use this name for the City input.
Note: Non-English locales: If a comma is used for a decimal point in latitude / longitude, this is accepted but converted to a period internally. The web service returns periods.
Note: If a city is saved without latitude / longitude, there will be no "red dot" to mark the city on a map, and finding photos for this city by clicking on a map will not work (see below, Images by Map Location). The other method to find photos by city (Images by Location / Date, see below) will still work.
The [Map] button changes to world maps view mode. Zoom-in to the area you need and click on a map position. The closest known city (within the specified range) will be selected. Use [Apply] to save the location into the image file.
For a series of photos made in the same location, you can quickly add location data. After getting the location data for the first image, use the [Next] button to open the next image, then the Edit Geotags [Prev] button to fetch the previous location data, then the [Apply] button to save into the current image file. If there are many photos, you can use Batch Add Geotags (see below) to quickly update all of them.
Summary:
• Open an image file and select the Edit Geotags menu.
• Enter (or change) a city name (possibly abbreviated) in the dialog.
• Use [find] to find the city and auto-fill country, latitude, longitude.
• If there are multiple matches, choose from the list.
• If there are too many matches, add more letters or supply the country and try again.
• If there are zero matches (not found), try the [Web] button (country is required).
• If still not found, add more letters to the city.
• If still not found, use one of the above web services and input the data manually.
• Use [apply] to update the image file and make the location available for future use.
• Open the next image (use the [next] button if appropriate).
• Use the [prev] and [apply] buttons to add the same location data again, if wanted.

Batch Add Geotags With this function, you can select many images and add the same location data to all of them. Use the [select files] button to select the image files from a gallery window (link). Then get the location data as described above in Edit Geotags. Press [proceed] to start the update process. Use this function also to correct city / country spellings or latitude / longitude data, or to fix inconsistencies.

Images by Location / Date
This is a fast way to find all photos made in a given country or city and country. In the dialog, select the desired level of grouping: by country, by country and city, by country and city and date. In the last case, you can select a date range for grouping of images having nearby dates. A number N will group images with dates that are N days or less apart from other images in the group (i.e. gaps are <= N days).
A popup window shows all cities found in the image geotags, and the dates of photos taken in those cities. The count of photos taken is also shown. In the above example, 9 photos are from Grossglockner starting Oct. 19, 2006. Click on a line in the window to get a thumbnail gallery of those images, and from there you can click on any image to view or edit.
Images by Map Location
If the separate package fotoxx-maps is installed, a set of geographic maps is available for Fotoxx. These are a world map and maps of each continent. Click the menu bar World Maps button to change to map view mode. A world map is shown at first. Click on any area to get a much larger view of that area. The map image can then be panned and scrolled to any other area by dragging the mouse. Map locations having corresponding geotagged images are marked with red dots. Click on a map location to get a gallery of images from the marked location. The window changes to the gallery view and the gallery appears. Press the maps button and click a new location for a new gallery report. When in map mode, a Map Functions menu is available with two functions: Choose Map allows you to choose any available map. You can install maps of your own (e.g. country, city, park ...). Instructions are below. All maps will show red dots where there are corresponding geotagged images. Map Search Range allows you to set a search distance when a map location is clicked. Images within this radius will be included in the gallery report. The default is 10 km.
Map Navigation: zoom and pan / scroll for a map is slightly different from image files:
• mouse wheel forward: zoom the map to full size, centered on the mouse position
• mouse wheel backward: shrink the map to fit within the window
• left click on a red dot: show gallery of images geotagged for that marked location
• left click NOT on a red dot: zoom the map to full size, centered on the clicked position
• right click: shrink the map to fit within the window
• keyboard Z key: alternate between full size and shrink to fit
• mouse drag: the zoomed map image pans and scrolls like other images
Installing Custom Map Files
Obtain the map from any suitable source, e.g. Google Maps or Open Street Map. You need to get the map as a graphic image, a JPEG or PNG file. (Open Street Map offers a download tool, but I have not been able to make it work.) Screen capture works. You can use the Fotoxx Mashup tool to stitch many maps together to make a big map (e.g. 100 megapixels). These work well with Fotoxx pan and zoom.
To install a map, put the graphic image file into the directory /usr/share/fotoxx-maps/data. In this directory you must create a text file named maps_index (or modify the existing file). Each map has a line in this file, containing the map file name and the latitude-longitude range of the map. Here is an example maps_index file:

USA.jpg, 24.855, 49.17, -124.99, -59.766 Europe.jpg, 30.89, 71.25, -10.73, 39.71

The entries are map file name, low and high latitude, low and high longitude. All values are separated by commas. Spacing does not matter. Fotoxx assumes a Mercator projection, but this is not significant for maps covering < 100 km.
If you make a map using screen capture, getting accurate latitude and longitude values for the map edges can be tricky. Use the Open Street Map "export" option to view maps with an overlay rectangle labeled with latitude and longitude. Adjust the rectangle to match a corner of a map you have captured and record the values. You need accurate latitude and longitude data only for the upper left and lower right corners of the completed map.
Search Images
Use the Search Images function to find images having any desired metadata. A metadata index file is used for searching, which makes it possible to search thousands of images per second. The index contains a subset of the EXIF and IPTC metadata in the image files. Some of this data is automatic, created by the camera. Other data, such as tags and star ratings, can be added by the user (using Fotoxx, Photoshop, others.). You can rearrange your image directories and image files without losing anything - you must only regenerate the metadata index file, which is simple and fast (see Index Image Files).
An example search: find all images dated 2006 or later, rated with 4 stars or more, having tag "buildings" and geotag "Dresden". The output report for this search is shown here:
Search Images Dialogs
The main dialog is on the left. The Geotags dialog appears if the [geotags] button is used to select location data, and the Metadata dialog appears if the [other] button is used to select metadata that is not available in the main dialog.
In the main dialog, select which images to search, either "all" (the entire image database) or "current", meaning the current set of images as shown in the current gallery list (can be a directory, album, or the results of a prior image search). Then choose what to do with the matching images found: "new set" means replace the current set with the images found, "add" means add them to the current set, and "remove" means remove them from the current set (to remove images, you must search the current set).
Select the desired report type. The gallery report is a page of thumbnail images, as long as needed to hold all the images that match the search criteria. The metadata report has both thumbnail images and a list of metadata items beside each thumbnail. These are some standard items (date, rating, tags, geotags, captions, comments) and any items you added in the metadata selection dialog.
Enter your search criteria. Select desired tags, dates, star ratings, text (comments, captions) and 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 or any of the given values must be present for an image to be selected. Press the [proceed] button to perform the search. Matching images are displayed in gallery view mode. Choose images to view or edit by clicking the thumbnails. Navigate this set of searched images using the navigation buttons in the gallery view window, or the [Prev/Next] button in the image view window. You can save the searched images as a permanent album, which can be further edited to add or remove images (see Manage Albums).
A date range may be entered to 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 high date limit. Times may optionally be specified using the format yyyymmddhhmm. Missing times default to 00:00 and 23:59.
A pair of star ratings may be entered to restrict the results to images having a star rating within the given range. A missing low value implies no stars, and a missing high value means the hightest rating, 5 stars.
If last version only is checked, image files with multiple versions will be filtered to include only the last version of each file. This depends on the Fotoxx version naming convention: The original file name is normally filename.ext, and edited versions are filename.v01.ext, filename.v02.ext, etc. If no versions are present, the original file is selected. Otherwise, the last available version is selected. If this convention is not followed, then this option will do nothing.
Image directory and file names may also be searched. In the field search files, 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 or file names containing either of these strings. Name matching is not sensitive to case, and substrings will also match.
Image comments and captions may also be searched. 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. Substrings will also match.
The radio buttons all and any apply to 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.
Geotags Dialog
The [geotags] dialog selects images by location. Enter a city name and press [find] (as described in Edit Geotags) to get country and latitude / longitude added automatically. Enter a kilometer range to determine the max. distance of images from this location to be included. If latitude / longitude and kilometer range are present in the dialog, these are used to locate images by latitude / longitude. If you want to search only by city and / or country name, erase latitude / longitude and leave the city and / or country. Use the [map] button to change to map view. Click on the selected map to set a latitude / longitude to search. You may enter "null" for city, country, or latitude / longitude to find images lacking these geotags.
Search Metadata Dialog
You may use this dialog to search for metadata items not present in the main dialog. The items available for any given image file can be shown using View Metadata (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 "model" 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 thousands of images per second are searched and reported (assuming a strong PC). If extra metadata is entered, the search performance slows to something like 90 images per second. This is because the image files are being read to extract the metadata not included in the metadata index. For good performance, always use dates, file names, etc. to maximize the use of the metadata index and minimize the number of image files that must be read.
There is a separate topic on image organization options.
Areas 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 most edit functions will work only within this area. Some 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 to a file, copied and pasted into other images, and edited there.
Select Area
The Select Area dialog is started with the menu Areas > Select. Select one of the 8 methods (explained below). Each method selects image areas in a different way. You can change methods at any time, and the selected areas are accumulated. An outline of the selected image area(s) is shown as you add or remove areas from the selection. The [Finish] button is used to make the area ready for subsequent image edits within the area. The [Hide] button removes the area outline, giving you better visibility of image edits and area edge blending. Use the [Show] button to show the area outline. The select area dialog can be exited and re-started later to modify an existing area or start a new one.
Line Drawing Color
The color used for the mouse selection circle and the area outline can be changed with the menu Areas > Area Color. Choose a color for good visibility against the given background. You can change this at any time.
The following methods are used to enclose one or more image spaces that will belong to the final area. These methods may be used in any sequence to define spaces that are either joined or detached.

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 or drag along the edge of an image object to draw lines that follow the edge.
Replace | Drag the mouse near an area edge-line to move the edge to the mouse.
Select area within mouse | Left / right drag to select / unselect all pixels within the mouse circle. Selection is independent of color.
Select one matching color within mouse | Click on the image to select a color. Left / right drag to select / unselect pixels inside the mouse circle that match the selected color within "match level".
Select all matching colors within mouse | Left / right drag to select / unselect pixels surrounding the mouse that match the color of any pixels inside the mouse circle, within "match level".
Controls for mouse selection methods | "mouse radius" sets the size of a selection circle around the mouse pointer. "match level" sets the color match (0-100%) required for pixel selection.

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.
Freehand draw
Drag the mouse (left button down) to draw a freehand (curvy) 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.
Replace
Drag the mouse near and along an existing area edge-line. The line will be erased and redrawn at the mouse pointer. This is a faster way to make a small adjustment in an existing line.
Select area within mouse
Left click or drag will select the pixels enclosed by the mouse circle. A right click will unselect the last selection (repeat to unselect more). A right drag will unselect the enclosed pixels.
Select one matching color within mouse
Click on the image to select a color. The color is shown on the color button. You can also use the button to set a color directly. Left / right drag to select / unselect pixels within the mouse circle that match the selected color within match level. Adjust the match level down / up to match more / fewer pixels.
Select all matching colors within mouse
Left / right drag to select / unselect pixels inside the mouse circle. Pixels beyond the mouse circle are also included if they meet these conditions: 1) their color matches any color inside the mouse circle, within the current match level. 2) they are within search range of the mouse pointer. This is a factor of mouse radius, e.g. if mouse radius is 20 and search range is 3, then the search range is 60 pixels from the mouse pointer. Drag the mouse over new areas you want to include. Watch the selected area expand into areas with colors matching those inside the mouse circle. 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 circle. A small radius and high match level 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 lower match level to select larger areas after the fine work is complete. Right drag acts as an unselect: pixels inside the mouse circle and matching pixels within the search range are unselected. If a selection goes too far, it is often easy to correct this by unselecting from outside the selected area. You may need some practice to get a feeling for this and be able to work efficiently.
Mouse Radius and Match Level
These two controls apply only to the "select within mouse" methods described above. Mouse Radius defines the size of a circle around the mouse pointer. Pixels within the circle are selected, or they provide a set of colors for matching and selecting pixels outside the circle. Match Level defines a degree of match (0-100%) to select pixels based on their color and brightness. 0 means anything matches, and 100 means a perfect match is required.
The firewall checkbox can be used to stop the search wherever already-selected pixels are met. Use this if the border of an area has already been defined and you want to stay within this border.
Summary

left drag | select pixels inside mouse circle and those with matching colors within search range
right click | undo previous selection, repeat to unselect more
right drag | unselect pixels inside mouse circle and those with matching colors within search range

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.
Edge Creep
An area that has been finished can be expanded or contracted in 1-pixel steps. The area remains finished, but blend width is no longer valid and must be repeated if needed. This can be helpful to reduce edge effects when an area selected by matching colors is edited in a way that changes its brightness. Selection by color may leave a narrow band of underselected or overselected pixels along an edge where color has become mixed with background. Expanding or contracting the area a pixel or two can produce a cleaner looking 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.
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 explicitly outlined - if you have a donut with a hole, you can select the donut, the hole, or both.
Areas selected using one of the "select within mouse" methods are automatically finished whenever you click inside any enclosed area. These areas are mapped during the selection process, whereas areas selected with one of the "line drawing" methods are mapped only when clicked.
If you select any of the four extend to corner options, the area outline is automatically extended to the corner from drawn lines that meet the image edges. This avoids the work of drawing the area outline along the image edges to the corner. Example: to select the sky, draw the boundary line between sky and ground, meeting the left and right edges of the image. Then select the upper left and right corners in the Finish dialog. The entire sky area will be selected, without having to outline the rest of the sky.
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
Permanently discard the current area. This is also available as a button in the Select Area dialog.
Area Color
You can change the color of the select area border lines, to maximize contrast against the background image. The small dialog can be left open while editing, to conviently switch among the available colors (black, white, red, green).
Area Copy / Paste
Copy: The current selected area is copied and saved in memory.
Paste: Left click on the current image and the saved area is pasted into the 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. The brightness slider is used to adjust the brightness to match the background. 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
A selected area 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.tiff. These files reside at /home/<user>/.fotoxx/saved_areas.
Use Select > Open to choose a saved area (choose the xxx.tiff file, not xxx.info.tiff), which will be dumped into the image where it can be moved around, resized, etc. as with the copy and paste functions.
Save PNG
Save a selected area as a .png image file with transparency. An image containing the selected area is saved. The parts outside the selected area are transparent and this information is saved in the .png file (.jpeg files do not support this). Fotoxx ignores transparency information, but this can be used in other image editors, e.g. Gimp.
Edit Menu
Trim / Rotate Image (key T)
This function is used to remove unwanted image margins, and / or to rotate an image to level or upright it.
When the dialog opens, a "selection rectangle" is placed over the image. The areas outside this rectangle are darkened and represent the parts of the image that will be removed. Drag any corner of the rectangle to move that corner. 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 adjust the pixel dimensions (or type-in new values), and the selection rectangle will adjust to these.
You can use the keyboard arrow keys to move a corner of the selection rectangle in 1-pixel steps. The last corner moved with the mouse is the one that is moved with the keyboard.
The maximum button resets the trim rectangle to the full image size (useful if you want only to rotate the image). The invert button will invert the width / height ratio (e.g. 2.0 to 0.5). The previous button retrieves the width and height values last used for a previous image (useful for setting multiple images to the same size, e.g. to fit a monitor or beamer).
The six ratio buttons allow you to choose a preset width / height ratio. You can change the ratio button names and the corresponding ratios with the button [customize] which starts a new dialog shown on the right. Enter desired button labels in the first row, and corresponding width / height ratios in the second row (the default names are the same as the ratios, except for "gold"). The [gold] button uses the golden ratio, about 1.62:1. You do not have to keep it.
To level a tilted image, use the mouse to drag the right edge up or down until the image looks level. Use the 90° and 180° buttons to upright an image made with the camera turned. The degrees control can be used to set any angle, -180 to +180 degrees. No resolution is lost with 90 degree rotation. For other angles, the loss of resolution is about 1/2 pixel. The auto-trim option automatically cuts off the edges (making them perfectly horizontal and vertical) when an image is rotated a small amount to make it level.
A left-click on the image will add vertical and horizontal guide lines to help with image leveling. Use right-click to remove them.
Upright
This dialog is a faster way to upright an image that is turned 90° or 180°.
The Upright button will take the correct action automatically if the image EXIF data is correct (normally yes).
This function is available in the right-click popup menus for the main image window and gallery thumbnails.
Auto-Trim Image
The composite and warp functions 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 / Rotate 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 committing with the [done] button.
Voodoo1 (key V)
This is a fast automatic image enhancement with limited capability. This is sometimes effective and "good enough" for rapidly processing many photos. There is no dialog - the modification is simply done when the menu is selected. Reject the change with the [undo] button if desired. The modification consists of a slight flattening of the brightness distribution, an expansion of the brightness range if less than the full range is used, and a slight increase in the color saturation, more for darker areas of the image than brighter areas. The effect is sometimes minimal or even negative.
Voodoo2
This is an alternative automatic enhancement, using the "zonal flatten" method described below.
Retouch Combo (key R)
This function handles all aspects of adjusting image brightness and color: overall brightness and contrast, brightness curves (overall and per color), color saturation, color temperature, white balance and black level.
brightness curves, overall and by RGB color
x-axis is initial brightness, y-axis is revised brightness
This example shows a reduction of brightness for
darker image areas, and an increase for brighter areas.
Use the sliders for brightness and contrast to optimize
the image. This may be adequate for most photos.
To fine tune brightness and contrast, edit the curves
using the mouse.

amplifier | increases or decreases the effect of the brightness edit curves
brightness | moves the entire curve up or down
contrast | moves the curve lower and upper parts in opposite directions
low color / high | increases or decreases color saturation
warmer / cooler | adjusts color temperature (reddish <--> blueish)
dark areas / bright | apply color changes to darker / all / brighter image areas
brightness distribution | show a brightness distribution graph in the curve edit window
click for white balance | enables the mouse to click on a black point or gray / white point
Settings File | dialog settings can be saved in a file and loaded later for use with other images

After making initial adjustments using the sliders, you can fine tune brightness and contrast by editing the curves with the mouse to change which parts of the image have increased or decreased brightness or contrast. The ALL curve adjusts all colors, and the RGB curves adjust individual colors. Use ALL first, then make revisions using RGB.
Dark - Bright image areas
This modifies the operation of the color adjustments to affect primarily darker or brighter image areas. Leave in the middle to adjust all areas equally.
Checkbox: Brightness Distribution
If checked, a brightness distribution graph is drawn inside the curve edit window. The graph is live and changes as the dialog controls are changed. The edit curve overlays the graph and may still be edited.
Checkbox: click for white balance or black level
If checked, mouse clicks on the image are used to set a black point and / or white balance (otherwise clicks on the image will zoom the image as usual). If you click on a fairly bright gray or white spot on the image, this will be used as a white balance set point, and the image RGB colors will be shifted to make this spot pure gray or white. This is the easiest way to correct a photo with an overall color tint because of bad lighting. You can use the warmer-cooler slider after clicking, and this correction will be added to the prior result. If you click on a very dark spot on the image, this will be used as a black set point, and the image RGB colors will be shifted to make this spot black. This is one way to reduce fogginess in a photo, or make the background sky look black instead of gray in a long-exposure astronomy photo. The All curve base node will be shifted to the right to reflect the new black point.
Settings File
Load button - load all dialog settings (including the curves) from a file chosen by the user
Save button - save all dialog settings to a file chosen by the user
This can help speed up processing when the same or similar settings can be used for multiple photos made under the same conditions.
Buttons
Reset - set all controls back to a neutral position - image is also reset
Prev - set all controls to the values used for the previous image
Done - finish the edit, close the dialog, save the control settings
Cancel - cancel the edit, reset the image, close the dialog
You can use the [Prev] button when processing a series of images made under the same lighting and therefore needing the same or nearly the same adjustments.

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. 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 can bring out subtle details (low contrast) that would otherwise be hard to notice. Other methods can also be used: Retouch Combo can increase the contrast for a selected brightness range (at the expense of others). Flattening the brightness distribution can spread the available contrast (brightness range) more evenly. Increasing color saturation can also enhance 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 second or so (depending on image size and CPU speed). The amplify slider also needs time 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.

Brightness Distribution
Flatten: This is a fast and easy way to compensate for a common limitation in photos: the brightness range is inadequate, or areas of the image have nearly the same brightness and details are lost. This function redistributes the pixel brightness so that each brightness level is more equally represented. 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. A bright monotone area (typically sky) may show "banding" (stripes or patches with brightness steps large enough to notice). This is caused when a narrow brightness range gets spread apart, with larger gaps between the new brightness levels. Example: a region with pixel brightness levels of 250-255 in steps of 1 is spread out so that the new brightness levels are 235-255 with steps of 4. Use the Deband slider to reduce this effect, especially in the brighter image areas.
Darken and Brighten: These functions expand the brightness range of an image that does not utilize the full brightness range available, possibly making contrast-poor. You can see this in the brightness distribution graph. If the distribution shows no or few pixels 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 while observing the image.

Zonal Flatten Zonal Flatten enhances visible detail in image areas having poor contrast. It is similar to Flatten, described above, but is more effective for an image that already has a wide overall brightness distribution. The revised brightness for a pixel is based on its position in the brightness distribution for nearby zones. Zones sets the number of zones. A larger number calculates new pixel values from closer areas. Flatten controls the strength of the effect, and deband moderates darker or brighter image areas. This function is very effective at increasing contrast: it can amplify noise in uniform areas like sky. If the deband control is insufficient to correct this, use Select Area and Reduce Noise to fix the noisy areas. Alternatively, use Select Area beforehand to select sky (or other areas to omit) and then invert the selection prior to using Zonal Flatten. Technical Explanation (optional) The image is divided into areal zones. The zone count approximates the user input and may be slightly more. Each pixel is adjusted based on the 9 closest zones, the 3x3 zones surrounding the zone of the pixel. More zones means smaller and closer zones. The brightness of a pixel is compared to the brightness distributions of the nearby zones, and the brightness is adjusted up or down in the direction that would flatten the distribution if the pixel were really a member. The influence of the 9 zones are weighted based on their distance from the pixel being calculated. The influence of the leftmost zones goes to zero for a pixel on the right edge of its zone. The same is true for the topmost zones, etc. This prevents abrupt brightness transitions that would be visible to the eye. The nature of the eye helps hide the bizarre alterations in pixel brightness, since the eye also judges the brightness of a spot based on its surroundings. A larger number of zones will make each pixel brightness adjustment depend on areas closer to the pixel.

Resize Image (aka rescale) This function sets a new oixel width and height. You can input the new dimensions 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 will minimize loss of resolution. The [Prev] button recalls the settings previously used, which is convenient if multiple images are being set to the same size. If the lock ratio box is checked, the width / height ratio will be preserved (if one dimension is changed, the other one 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.

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.
Add Text to Image
Write text directly on the image. Enter the text into the dialog. Multiple lines can be used. After entering the text, 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. Use the [Size] control to increase or decrease the text size. Use the [Angle] control to change the slant angle of the text. The other controls allow you to provide a background color around the text, a text outline color, and a shadow effect. You can select the color and transparency for all of these. The width control adjusts the width of outlines and shadows. The shadow angle control sets the slant angle of the shadow. The [apply] button makes the current text permanent, so you can start a new one without leaving the dialog. The [Open] and [Save] buttons start a file chooser dialog with which you can load or save all text data from or to a file. All the items in the dialog are loaded or saved, so you can keep a collection of often-used text strings and settings. The Metadata buttons allow you to retrieve the image caption or comments, which will be put into the Text input field. From there you can modify it as needed. The modifications are not written back to the image metadata.

Making a Watermark: use a text 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 Effects > Embossing to give the text an appearance of depth.

Add Lines / Arrows to Image
Write lines or arrows directly on the image. Enter a line length and width into the dialog, and select an arrow head if wanted. Left-click the mouse where you want to place it on the image. Drag the ends of the line/arrow to position it on the image. Right click to remove it. The dialog controls allow you to provide a background color, an outline color, and a shadow effect. You can select the color and transparency for all of these. The width control adjusts the width of outlines and shadows. The shadow angle control sets the slant angle of the shadow. The [apply] button makes the current line / arrow permanent, so you can start a new one without leaving the dialog.
Brightness Ramp
This example shows brightening of the
upper right image quadrant.
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.
Paint Edits
Use this function in combination with some other retouch edit function. Specify a mouse radius and "power" factors for the mouse center and radius edge. 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 Retouch Combo, and the brightness curve is moved upward (brighten), then the image will slowly brighten in the area where the mouse is dragged. This is called dodge and burn in some image editors, referring to an old darkroom procedure for changing the exposure level for selected image areas. In this case, you can use many edit functions effectively.
Use the [undo] and [redo] 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 on the Paint Edits dialog to erase the active area that is now left over from the mouse dragging. If you leave this area active and start a new edit function, the results may be strange (all previous painting is immediately applied to the new function).
A suggested approach is: (1) start the Paint Edits dialog, (2) start an 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 Retouch Combo, Brightness Distribution, Tone Mapping, Sharpen, Blur, Reduce Noise. Most of the Color and Effects functions can also be used.

Leverage Edits It is sometimes effective to apply a retouching function "leveraged" by some image attribute, e.g. apply noise reduction to darker areas of the image while leaving brighter areas alone. To do this, use Leverage Edits. Choose brightness or contrast as the controlling attribute (lever). The lever may be for a single RGB color or for all colors. The editable graph controls how subsequent edit functions are applied to the image. The x-axis is the selected lever, from minimum to maximum value. The y-axis value governs how strongly an edit function affects a pixel having the value on the x-axis. A low y-value minimizes the effect, and a high y-value maximizes it. Example: apply tone mapping primarily to dark pixels: Start Tone Mapping, then start start Leverage Edits 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). You can edit either curve (leverage curve, tone mapping curve) while watching the resulting image.

Plugins
The Plugins menu is on the left. The top entry "Edit Plugins" leads to the dialog on the right. In this dialog you can define menu names and associated commands for using other image edit programs within Fotoxx. These menus are added to the Plugins menu after the top entry. The example shown is a menu named "auto-gamma" which starts the command "mogrify -auto-gamma %s" (an ImageMagick function). The "%s" is a placeholder where Fotoxx will insert the name of a temporary copy of the current file in Fotoxx. The called edit program must process the file and replace it with the edited version. Normally this is done by using the program's File > Save menu. Afterwards, you can use the Fotoxx [Undo] and [Redo] buttons to check the results, perform additional edits with Fotoxx, or use [Save] 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 file but may use only 8 bits. When finished using the external program, save the image back to itself using that program's File > Save menu, and then exit the program. Fotoxx will pick up the revised file and use it as though the edit had been done in Fotoxx. Note that in Gimp you must use the File > Export menu to save the image back to the original input file (File > Save produces a .xcf file).
To add a new plugin, input a menu name and the corresponding command in the Edit Plugins dialog and press the [Add] button. Wherever %s is placed in the command, the file to process will be inserted. Some commands may expect an input and output file to be specified. In this case supply %s in both positions (the output file replaces the input file). You may omit %s if the command does not edit an image file. A warning is given, which you can ignore if this is really your intention.
To modify an existing plugin, select the menu name from the drop-down list. The corresponding command will be shown. Modify the command and press [Add]. You can remove a plugin by selecting it and then pressing the [Remove] button.
A few examples are provided in the initial Fotoxx installation:

Menu Name | command line
Gimp | gimp %s
auto-gamma | mogrify -auto-gamma %s
Gthumb | gthumb %s

The plugin menu is saved in the file /home/<user>/.fotoxx/plugins which you can modify 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.
Repair Menu

Sharpen Image This function sharpens a blurry image. Three methods are implemented: unsharp mask, gradient and Kuwahara. Unsharp mask: a fast and effective method also found in Gimp and other apps. A technical description can be found via Google. Gradient: steepens brightness transition areas directly, somewhat like tone-mapping. Kuwahara: surrounding neighborhoods of pixels above, below, left and right of a pixel are compared to each-other. The pixel is given the mean color of the neighborhood with the smallest variance in brightness. This forces pixels on a blurry edge to move to one side of the edge or the other. Edges are made very sharp, but details can be lost.

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. Amount controls the strength of the modification. Threshold suppresses changes to low-contrast pixels: a higher values reduces the amplification of low-level irregularities (image noise, uneven skin tones, etc.).
Press the button for the method selected and wait a few seconds to see the result. 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 an image with different methods and parameters.
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 image retouch functions cause the distribution to spread out, making the brightness steps perceptible).
Reduce Noise
This function reduces the noise present in photos taken under poor lighting conditions, making uniform surfaces appear speckled. It also works for scanned prints, as in the example here. You may choose among the methods provided, and mixing them (using one and then another) is often helpful. When an [apply] buttons is pressed, the corresponding noise reduction method is applied to the image, using the corresponding setting (radius or threshold). Each new [apply] uses the modified image from the previous [apply], so each use will have increasing impact. With a large image, these algorithms may run a long time. To save time, select a small area and experiment with the different methods and settings until you make a decision, then clear the selected area and apply the chosen method(s) to the whole image.
The dark areas slider can be used to restrict the process to darker image areas, which are most prone to noise. If left at the right end (all areas), all areas are processed. Move it back to the left to process increasingly darker areas only.
Here is a short technical description of each method:

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 slightly 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.
Wavelets | Image brightness (with noise) over distance is converted into a series of wave functions that nearly sum to brightness and represent an approximation with less noise.

The wavelets algorithm was adapted from code found in a Gimp plug-in.
The first version was written by Dave Coffin for the program Dcraw.
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 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. The [show] and [hide] buttons can be used to show the outline of the current selection or hide it to better judge the results after erasing.
Remove Red Eye
This function reduces the red-eye effect from electronic flash photos. Two methods are provided. The first is faster but may not handle difficult cases. 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.
Paint / Clone
This function changes individual pixels by painting them with the mouse.
If a select area is enabled, the painting is confined within the area.
Paint Color
The color button allows you to pick a color, and shows the current color. You can also shift + left-click on the image to choose a color from the image. The "paintbrush radius" control sets a circle around the mouse pointer which shows the area being painted or erased. Left drag on the image to paint with the current color. Right drag over a previously painted area to erase (gradually undo the painting). The "transparency" controls determine how intensely the color is applied (or erased) at the center and edges of the circle. Zero transparency applies the full color immediately whereas a high transparency (90+) allows you to gradually change the color using multiple 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.
NOTE: zoom the image to 100% or more when using a small brush. 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.
Copy From Image (clone)
Instead of one fixed color for all pixels within the paintbrush radius, pixels are taken from somewhere else in the image. Shift + left click on the image to select the source area, then drag on the area to paint. The source area is painted over the dragged area. The transparency controls work as described above. This method can be used to erase an unwanted object, replacing it with background taken from elsewhere.
The [undo-last] button removes the last paint or erase operation, and this can be repeated to remove many recent edits. Each new drag operation is a unit of work that can be separately erased. The memory for undo operations is limited to one gigabyte, 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.
The gradual paint option is the most useful and functions as already described. If you de-select this option, painting and erasing will be sudden instead of gradual. If you are painting within a select area with edge blending, the painted changes will be zero at the edges and 100% for pixels beyond "blend width" from the edges. This works better if "gradual paint" is not selected.
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 threshold 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.
Anti-alias Tool
This function can reduce pixelation (aka "jaggies" or "stair steps") in a low-resolution image. Press the [apply] button to make the change, then [done]. The result is sharper than using the Blur function. The resulting image is 2x the size of the original. It may be useful to apply sharpening afterwards.
Note: this tool is only effective for pixelation with single-pixel "steps". If the image has been resized larger (steps are larger than 1 pixel) the algorithm does not work. It thinks the steps are legitimate because they are big. Pixelation in photos normally occurs only when a photo has been downsized and then upsized. Pixelation is not a problem with normal photography - lens blur is generally larger than the camera sensor pixel size.
Fix Color Fringes
This function is used to reduce chromatic abberation. Look carefully at the left photo, taken from inside a church. It has color fringes that were mostly eliminated in the processed image to the right (these images are 400% size and not very sharp). Color fringes can appear along high-contrast edges, especially in the outer image areas where lens distortions are usually greatest. To get rid of them, zoom the image to a maximum size and center on an area with color fringes. Move the slider controls slowly while watching the image, and leave them where the color fringes are minimized. To speed up the response time, select a small area first (Area > Select), optimize the color fringes in this area, then remove the area before pressing [done] so that the entire image will get the final corrections. The corrections are scaled so that the maximum correction is at the image edges and the correction at the center is zero.
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 underexposed to come out gray. This image can be used to find both bright and dark stuck pixels.

Shift Colors This function converts an image into false colors. Choose any of the three RGB colors and move the slider left or right from the center. One of the two other colors will be substituted in a graduated manner, reaching 100% replacement at the slider end positions. For example, you can gradually substitute green or blue for the color red. The "All" slider shifts all colors together. Do this first to find a first optimum, then shift the RGB colors individually.

Color Mode
Use this function to make a black and white or color negative, or convert a negative image into a positive image, or convert to sepia coloring (a modified black / white conversion for an aged photo effect).
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
sepia - convert to a modified black and white for an aged photo effect
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 magenta, and blue becomes yellow.
Sepia: This is like a conversion to black and white, but a shade of brown called sepia is added to the shades of gray. This makes a photo look like a very old photo from the early days of photography. Many cameras and photo edit programs have this feature.
Color Profile
Use this function to change from the normal sRGB color profile to some other RGB color profile. If you have images with Adobe RGB color, you can change them to sRGB for display on a monitor using sRGB (normally the case). You may need to install ICC color profiles. In Ubuntu, the package names are "icc-profiles" and "icc-profiles-free".

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

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 Blend determines how widely the control points spread their influence. If "delta" is checked, the values shown are the deltas (differences) from the original image.
CMYK
This function is used to change overall brightness and contrast, or that of selected colors. The settings are retained within and across Fotoxx sessions, so this function can be used to process multiple photos made under the same lighting conditions and needing the same (or nearly) adjustments. Use the [reset] button to restore all inputs to neutral values.

Brightness | Increase or decrease overall image brightness
+Red - Cyan etc. | Increase or decrease the brightness of one RGB color and change complimentary colors in the opposite direction
Contrast | Increase or decrease the overall image contrast
Red, etc. | Increase or decrease the contrast of individual RGB colors

Bend Menu
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 landscapes this may not be noticeable. The unbend function can be used to straighten the image. 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.
Fix Perspective
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 below or from the side.
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.
You can use the keyboard arrow keys to move the corner markers in 1-pixel steps. The arrow keys work on the last corner selected or moved with the mouse.
Warp an Image (distort)
Warp area
This function can be used to make distortions within an image. You can select an image area and drag the mouse to stretch this area with respect to the rest of the image. The image is like rubber. If the mouse drag begins within the selected area, then the area is warped within its current boundaries - the movement is maximum at the mouse pointer and declines to zero at the edges of the selected area. If the mouse drag begins outside the selected area, the area edges near the mouse can be pulled out beyond the original area boundary. Many mouse drags of different lengths and directions can be combined to achieve the desired results. 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 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. The control [warp span] determines the radius of warping around the mouse. 1.0 means the full image is warped, and smaller values confine the warp to smaller areas around the mouse.
Warp 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 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.
Flatten Book Page
This function can flatten a photographed page from a book. If the book is thick, the pages bend downward at the binding, and the photographed text is squeezed together. This function straightens the top and bottom edges of the page and unsqueezes the text.
Photo Procedure
First, make the photo as good as possible to minimize the needed corrections. The page curvature can be reduced by holding the book half-opened. Place the camera over the center of the page, so that the top and bottom edge curves look roughly equal. Use lots of illumination to increase the depth of field, to insure the curved-down part of the page remains in sharp focus. Two persons working together can photograph 1-2 pages per minute.
Fotoxx Procedure
First, trim the image, keeping all of the page but little more. Rotate the page if needed. Start the Flatten function. Click the mouse along the top edge, creating visible dots at the clicked points. After 4+ points are available, a curved line is drawn through the points. Add more points and drag the points as needed to make the line conform closely to the page edge. Repeat for the bottom edge. Press [flatten] to flatten the page. The edges should now be straight (or straight enough). The text near the binding is still squeezed together. Unsqueeze the text by pulling the top and bottom sliders. The text is spread out in a way that is proportional the the slope of the top and bottom page edges, so the area near the binding is stretched the most. The [undo] button restores the unmodified image and the edited dots, which can now be adjusted.
Effects 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.
Sketch
This function transforms a photo into something like a pencil sketch. Dark pixels are aggregated into fewer pixels, leaving vacated areas brighter. Contrast can also be used as a proxy for dark pixels. "Threshold" can be used to filter the input image by brightness. "Clip Level" is used to filter the output to further reduce isolated or marginally dark pixels. The Negative checkbox causes black and white to be interchanged. Two algorithms are provided - results may look more interesting with one or the other (subjective). Reducing the size of the input image may also give more interesting results.
Line Drawing
This function transforms a photo into a 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: 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: width of the enhanced edges, from 1-pixel to about 5 pixels. Image brightness: brightness of the image itself, from dark (show only the outlines) to full brightness. The black / white checkbox converts the image from color to black and white, and the negative checkbox makes a negative image (colors are replaced with their compliments).
Color Drawing
This function transforms a photo into a solid color image that looks like an illustration. The Threshold slider separates the image into brighter and darker areas, with the boundary set at a brightness level determined by the slider. The other two sliders regulate the brightness of these two areas. At the settings shown here (Dark Areas pushed left, Bright Areas pushed right), the darker areas are black and the brighter areas as as bright as possible with intense coloration. If the sliders are moved to the opposite sides, the original image is restored. Move the sliders until the image is optimized.
This function can be used to clean up a smudgy blackboard or whiteboard image by separating the writing cleanly from the background (if the background smudges are weaker than the writing). It may help to apply Sharpen to the image beforehand, to increase the contrast of the writing. Use the unsharp mask method with a large radius.
Graduated Blur
This is another function to blur an image, but it works differently. In the dialog, you specify a contrast limit and a blur radius. Only pixels with less contrast than the given limit are blurred, and the blur radius ranges from 1 to the given value for pixels with a corresponding contrast ranging from the given limit to zero. In short: low contrast pixels are blurred more than high contrast pixels. This can be used, for example, to smooth skin tones without blurring hair or reducing the sparkel in the eyes. Taken to extremes, it produces a "cartoon" effect, especially when used in combination with other retouch and effects functions.
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 gap between tiles. 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 a comic book picture or Roy Lichtenstein painting. The only control is the dot size. Also experiment with using color saturation, color depth, or other functions before and after 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; "patch area goal" 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.
Vignette
This function is used to highlight or colorize an object or area within an image.
Click or drag the mouse on the image to change the vignette center, which is initially at the center of the image.
Select Brightness to change the brightness of the image in a radial pattern: Adjust the left or right end of the curve to change the brightness of the center and edges of the image respectively. You can give a dark surround to a portrait face, or you can fix an image with darkened corners. The curve middle level corresponds to no change. Use lower values to darken and higher values to brighten. The example above gradually darkens the periphery of the image while leaving a broad central area unchanged.
Select Color to add a chosen color to the image in a radial pattern. Curve values of zero (at the bottom of the box) represent no change, and higher values add the chosen color to the image. The amount is regulated by the curve value. The highest value (top) corresponds to 100% color. Use this function to add a color surround to an image, e.g. surround a face with a gradually increasing color.
Texture
This function adds a textured surface to an image or selected areas within an image. Radius determines the texture pattern size. Strength determines the intensity of the pattern, from almost invisible to dominant.
Pattern
Add a background pattern to an image. A small image file (pattern file) is used to cover the current image by duplicating the file, like a tiled floor. This file can be a real pattern (e.g. an image of canvas cloth, a brick wall, a repeating geometry ...), or any other kind of image. The pattern is made semi-transparent, so that the base image appears to be printed over the pattern, or the pattern over the image. Many pattern files can be found using a Google search for "pattern image". Download some of these and trim them if needed to a size around 200-500 pixels.
Use the [Browse] button to select a pattern file. The selected pattern will cover the base image. The pattern is partly transparent so that the base image shows through. Adjust Opacity until you have the right mix of base image and pattern. Use Zoom to grow or shrink the pattern size.
Width and Height are initially set to the size of the pattern file. You can adjust these smaller, which will cause less of the pattern to be used for duplication. If the pattern file contains an image that repeats at fixed intervals both horizontally and vertically, the [Calculate] button can be used to set width and height to match. The result will be a continuous pattern without any edge effects.
If the pattern is irregular and edge effects appear where the duplicated patterns are joined, you may be able to improve this. Use Width and Height to revise what part of the pattern image is used. The two Overlap values determine how much the duplicated patterns overlap at the edges, horizontally and vertically. Add some overlap to mask edge effects.
Select Area can be used to apply a pattern to part of an image, or different patterns to different parts. After applying a pattern to an image, it might be interesting to use Embossing or Tone Mapping to add a 3-D effect to the pattern.
Usefull pattern files in LibreOffice: /usr/lib/libreoffice/share/gallery/www-back
Mosaic
Create a mosaic image using tiles made from all your images.
Specify the tile size in pixels (e.g. 36 x 24) and press [Tiles]. Tiles will be created from all of your images (actually the thumbnail images are used since their small size makes the process run much faster). This may take some time (speed is about 11K images / min. using a 5400 rpm disk). If you change the tile dimensions, press [Tiles] again to regenerate the tiles. This may work much faster since the images have been cached in memory by the OS. The generated tiles are saved to a file and loaded again the next time the Mosaic function is used. Regenerate the tiles only when new images have been added to your collection or if you change the tile size.
After the tiles are created, press [Image] to convert the current image into a mosaic using these tiles. This takes only a few seconds. You can process additional images without regenerating the tiles. Tiles are chosen by matching the average tile color to the average image color at the tile position. If thousands of images are available and if the range of colors is good enough, the mosaic will turn out quite good. Use the mouse wheel (or CTRL+left click) to zoom-in on any part of the image to see the tile images.
The Tile blending slider will cause the image to be blended with the tiles, making it look better if the tiles are a bad color match. If the blending is less than about 50%, the tiles remain almost as clear as before (the eye compensates the false tint).
After a mosaic is created, you can click on any tile to get a larger popup image. This is the full image for the tile, so you can drag the window as large as you like and it will remain sharp. A mosaic image can be saved like any other edited image, but if a saved mosaic is opened, clicking the tiles for a bigger image does not work. Regenerating the mosaic is quite fast, so do this if you want the popups to work.
Custom Kernel
Apply a custom convolution kernel to an image (a small matrix useful for blurring, sharpening, embossing, edge-detection, and more). The underlying technology is explained in Wikipedia. Input a kernel size, a divisor, and fill-in the table values. The values can be saved into a file and retrieved later by using the [Load] and [Save] buttons.

Make Waves This function distorts an image into a wave pattern, as if it were being viewed through turbulent water. The dialog allows you to change the mean horizontal and vertical wavelengh, amplitude and variance. The "perspective" input allows the wavelengths to gradually lengthen from top to bottom. Like most effects, this function also works within a seleced area.

Directed Blur Pull a location on the image using the mouse. The area around the mouse will move with the mouse and become blurred in this direction, a "1-dimensional" blur. Blur span can be used to broaden or narrow the size of the area being blurred. Intensity determines the strength of the blur, from barely visible to completely blurred.

Combine Menu
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, ghosting cannot be avoided.
Select the HDR menu function and select up to 9 images, which must all have nearly the same pixel dimensions. The images are aligned and combined automatically. This needs 10 seconds to a minute or more per image, depending on image size and CPU speed. 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. 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 corresponding image contributions are changed accordingly, and you can see the results in quasi-real-time in the output image. 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: Brightness Distribution, Retouch Combo, 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.
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 needs 10 seconds to 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 needs 10 seconds to 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 images. 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.
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 join them together. Start by selecting 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 the 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. You can measure and set lens mm manually using the [search] button described below. If the images have no curvature (e.g. scanned or downloaded images), use the no curve checkbox to set the lens mm effectively to infinity.
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, or use the [search] button to make a more precise determination (described below).
The no auto warp button is normally unchecked. Its purpose is described below.
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. This may need a minute or more for a weak computer working with large images. You can speed up the process greatly if you reduce the input images to 1/2 size. Do this also if the process fails for lack of memory. Panoramas with 4 large images can require 2+ GB of memory during processing.
When fine alignment is complete, the combined image is displayed. The dialog shown here is started, 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. Use this button multiple times to get improved matching at the expense of greater color shifts that could add a false color tint. Restore the original image colors with [file color]. The image selected with the Select Image radio buttons is the starting image for the auto color matching. Reset using [file color] and select a different starting image to see results that may be slightly different. The brightness and RGB color controls allow you to make additional changes to better match the images. Select one of the images with the radio buttons, 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, trim / rotate 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 works best to align from the top down.
Scanned Images
Scanned images can be combined if there is enough overlap. Check "no curve" since there is no curvature in scanned images.
Auto Warping
The images are slightly warped in various directions during alignment to find the best match. This is to compensate for shifts in camera position or rotation, causing image distortions that reduce the quality of fit. If the overlap area of two images includes a large object that moved in or out between the two photos, the alignment process may go crazy trying to match the images, resulting in alignment that is very poor. By selecting no auto warp you may be able to get the alignment to succeed or have only a small error.
Mouse Warp
If the images do not align perfectly, you may be able to improve the alignment by using the mouse to push the images into alignment. In the final dialog, select mouse warp, select which one of the images with the radio buttons, and then drag the mouse carefully along the edge of the image where it should align with its neighbor, and move the image into alignment. The image is moved locally around the mouse while more distant parts stay fixed. Parallax shifting will require a compromise, since it is generally not possible to keep both foreground and background in alignment.
Setting lens mm Automatically
The [search] button in the panorama pre-alignment dialog initiates an automated search for optimum lens mm. 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. 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 change. If lens mm remains consistent, you can use it for your panoramas. The search function steps through a range of values for lens_mm and the image alignment offsets for x, y, and theta. It searches for the lens value 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 and focal length (zoom setting). Use the [save] button in the 1st dialog to put the focal length back into the image EXIF data.
Setting lens mm Manually
Make a panorama image of a brick wall (or any wall with lots of detail). The wall should be 5+ meters away. Take two photos with about 40% overlap. Within the panorama pre-align process, adjust lens_mm until 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 your lens mm 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-angle camera lenses are not ideal lenses (pinhole equivalent). Most panoramas will still work well even if the lens_mm setting is off by 10%.
Color Matching Problems
If the images in a panorama have a large brightness difference in the overlap areas, the automatic color matching may not work well enough. The most common problem is false sky colors. You may be able to improve this by brightening or darkening an input image to more closely match its neighbors in the overlap areas. Sky can be easy to fix by selecting the false areas and copying sky from elsewhere in the image (see Paint / Clone). It seems to work better if you brighten the darker image instead of darkening the brighter one. You can do this in the final dialog as described above, or you can do this before starting the panorama.
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 because foreground objects are shifted against the background (parallax). This is not an issue when the subject is 50+ meters away, since a small lateral movement has little impact on the image. Keep the camera level to avoid a large vertical shift (horizon shift), which can cause image distortions that may not be fully corrected. Avoid rotating the camera for the same reason.
PT Panorama
The Panorama Tools utilities (via the Hugin package) have been integrated into Fotoxx under the menu PT Panorama. The user interface is very simple: specify the input images in any order and proceed. Everything else is automatic. After a minute or so the finished panorama is shown and is now the current file in Fotoxx. The file name is (first input file name)-PT.tif. This is an 8-bit TIF file and is very large. You can save the file as JPEG and delete the original TIF to save space. Panorama Tools usually does a fine job, but I have noticed minor alignment errors in some cases, usually too small to notice. It may be possible to eliminate these by using the full features of Hugin directly instead of the automated script used in Fotoxx. They may also be fixed using Mashup - see the related paragraph in Mashup, below.

Mashup Arrange multiple images and text in a layout (photo montage). Images can be added, resized, rotated and moved around by dragging with the mouse. Images can be made entirely or partly transparent in selected areas. Text can be added, moved, resized and rotated. Text attributes can be specified: font, size, color, outline, shadow, transparency. Lines and arrows can be added. The example here shows some of the possibilities. In the first Mashup dialog, choose a background or layout image where other images will be placed. Choose an existing image or create a new monotone image with a specified size and color. You may also open a previously saved mashup project and continue editing. The 2nd Mashup dialog is a choice: edit images, edit text, edit lines and arrows, save the mashup project for later revision, save the completed composite image (Done) or abandon the image (Cancel). The first three choices lead to dialogs to perform the respective edits. Each of these return to this dialog when done, so you can add or modify images, text, and lines / arrows in any sequence. Rescale is explained below. Use this dialog to select and place images on the layout and revise their appearance: size, rotation, position, and transparency. An image may be partly or wholly transparent, overall or within specified areas. This means that the background image or an overlapped image can show through the transparent areas. The Add button leads to a gallery file selection dialog (link). Selected images are placed on the layout. Click on an image to select it. Drag the image from the middle to reposition the image in the layout. Drag the lower right corner to resize the image. Use the dialog controls to adjust the image. The dialog controls operate on the last image added, clicked or dragged. The Next button will cycle through the images one at a time, flashing the selected image. This can be used when overlapped images make it difficult to select the desired image by clicking it. Scale resizes the image. Angle rotates the image. The Stacking Order buttons raise or lower an image relative to other images - this determines which overlapping image will be on top. Base Transparency is used to make an entire image partly transparent. The [paint] button is used to make any part of an image partly or fully transparent, using the Paint dialog below. The [warp] button is used to bend or warp an image, using the Warp dialog below. The black margins checkbox can be used to remove black margins from other edit functions, e.g. bend or warp. These will be made transparent. The Margins controls can be used to increase edge margins. The Hard margins cut off image edges. The Blend margins make the edges partly transparent to blend them into the background or overlapped images. "Paint" more or less transparency for selected image areas. Click on an image to select it. The mouse will have a circle around it to show the range of action. Use radius to adjust the size of the circle. Left-drag the mouse over the image to make it transparent in the areas covered by the circle. Right-drag to make it opaque. If Gradual is checked, transparency changes are made slowly as the mouse is dragged. Specify a power value for the mouse center and edges to make the changes faster or slower. Click this dialog to insure it is active, and click on an image to select it. Drag the image with the mouse - the image will warp or stretch locally in the direction of the mouse (like sheet rubber). The area of warping is roughly given by warp span, which is a fraction of the image size. Each drag is a step that adds to previous steps. Recent steps can be reversed with [undo last], and the unbent image can be restored with [undo all]. The Edit Text dialog is used for placing text on the layout. Enter some text and press Add. The text is placed on the layout. Drag it into position, then use the dialog controls to set font, size, color, angle, background color, outline size and color, shadow size and color, and transparencies for each of these. Drag the text to a new position at any time. Click on any existing text to show its properties in the dialog and revise them. Click on a text and press Delete to remove it. When done editing, press Done to return to the 2nd Mashup dialog. The Edit Line / Arrow dialog is used for placing lines or arrows on the layout. It works very much like adding text. Enter a length and width and press Add. A line is placed on the layout, or an arrow if one of the Arrow head options is checked. Drag the line / arrow to the desired position. Adjust length, width, angle and attributes (background, outline, shadow) using the dialog. You can also drag either end of the line/arrow to reposition that end while leaving the other end fixed. You can use the mouse to move and resize objects in the layout: • click the object to select it - it flashes to confirm the selection. • drag from the approximate center to reposition the object. • drag the image or text lower right corner to resize. • for a line/arrow, drag either end to move that end only. The keyboard arrow keys can also be used to move the currently selected object in 1-pixel steps. You can add images saved by Select Area. In the Edit Images dialog, press [Add] to start the file selection dialog. Use the [Top] button in the gallery window, select HOME, then select .fotoxx/saved_areas. Open any of the .tiff images found there. The original area outline is used, and edge blending works from these edges. Mashup project files You can save a project and open it later to continue editing. However, the project file will open successfully only if the layout image and all the overlay images are still available in their original locations. The Mashup project is rebuilt using these images and some saved metadata that is in the project file: image and text locations, scales, transparency, etc. Mashup Rescale Working with a very large layout (over 20 megapixels) can be quite slow, especially if the computer is not very strong. Dragging a large overlay image can be slow and jerky. You can work much faster if you use a smaller layout to build the project, and then make it larger after you are finished. There is no loss of resolution in the final image, since the overlay images and text are regenerated from the inputs (e.g. an image that was scaled to 0.2x in the initial layout is rescaled to 0.6x if the layout is magnified by 3x). The original full size image file is used for this rescale. The Rescale button allows you to magnify the project by 2x, 3x or 4x (4x, 9x or 16x by area). There is also a 'reset' option to restore the original smaller project size. With this method, you can work with a 10 megapixel layout and resize it up to 160 megapixels when done. The larger layout can still be worked on directly afterwards, but it will be much slower. PT Panorama Fix Mashup can be used to fix minor alignment offsets from PT Panorama. After running PT Panorama, start Mashup (in the same Fotoxx session), and create a flat layout image with a good size for editing (e.g. 3000 pixels wide). Start the dialog to add images to the layout. Navigate to the directory /tmp/fotoxx-xxx/ where you will find the images left by PT Panorama. They have been color matched and warped to fit together. Add these images to the layout. Check the box to make the black margins transparent. Resize them to fill the layout and move them around to fit together. Zoom the window larger for precise algnment and align the images as well as possible. Small misalignments will persist if the images do not fit perfectly. There may also be brightness or color mismatches at the image edges, but these can be fixed later. Start the Warp Images dialog. Drag the mouse in small steps over a misaligned area to move an image into alignment with its neighbor. Use a small span (e.g. 0.1) to insure that correcting one misalignment does not create others elsewhere. Several cycles of draging the images in several locations may be needed, but with patience you can make the alignments perfect. If there are visible brightness or color mismatches at image edges, blend these together using the margin blend controls. This should be done only after the alignment has been perfected - otherwise this will cause blurring where the images do not align, making alignment corrections harder to see and control. Lastly, rescale the layout to a larger size if wanted.

Help Menu
Quick Guide
This is a 1-page introductory document with Fotoxx essentials.
User Guide (key F1)
The user guide (this document) is displayed (created using the WYSIWYG HTML editor Kompozer).
User Guide Changes
This is a summary of recent changes in the User Guide. 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.
Translations
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 one of the existing translation files as an example, e.g. the German translation:
/usr/share/fotoxx/locales/translate-de.po
A new translation for language code xx would be saved at:
/usr/share/fotoxx/locales/translate-xx.po
After making such a file, you can test it by starting Fotoxx in a terminal:
$ fotoxx -lang xx.
Missing translations are also listed on the terminal window when Fotoxx starts.
Active translators are credited the the menu Help > About.
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.
About
This displays a short message about the Fotoxx version number, license, credits, and contact address.
Organizing Images for Efficient Searching
The goal is to find all images for a given set of criteria, e.g. photos of a given person in a given place and time frame, or all photos of a given person at any time, or photos from specified locations, etc. There are several ways to organize an image collection to accomplish this, with advantages and disadvantages you need to understand. These methods may be used in any combination (I use all of them). Keep in mind that if you want to user other programs for searching images, you need to pay attention to which methods are compatible. Fotoxx is standards-compliant to avoid lock-in, but some other applications use unique methods.
Fotoxx can search using the following image attributes: photo date, rating (0-5 stars), tags (keywords), geotags (location names and earth coordinates), file directories and names, and text appearing in captions or comments. These are explained in the Edit Metadata, Edit Geotags, and Search Images topics. In addition, any metadata can be searched, although not nearly as fast as the previously listed items, which are kept in a special metadata index file for fast searching. The Index Image Files function establishes this index and updates it when new image files are added or their locations are changed from outside Fotoxx.
The following is an attempt to give an overview of the options and tradeoffs.
Physical Organization
Directory and file names can be used as a basic organization that will enable you to find images even if more elaborate organizations (tags, albums, captions) are not used. The highest physical organization should be by time (not event, place, person, etc. IMO). I suggest using one subdirectory per year named 2001, 2002, etc. This will also prevent any one subdirectory from getting too big. 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 name can be a topic or event, and a sequence number.
Example: /images/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 function Tools > Batch Convert lets you rename a whole batch of photos taken on one day at one location or event by selecting the files and specifying a template name like "08.20 Spitzbergen ##". The sequence numbers are automatic, replacing ##.
Captions and Comments
A simple method of organization is to use captions and comments (Metadata > Edit Metadata). These are arbitrary text strings that can be added to a series of images in rapid sequence:
open the first image, input some text, press [apply], press [next], input some text, ...
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 specify persons, location, topic, etc. for each image and then find them again quickly. With this method, you can search images using any words appearing in captions or comments, in combination with dates and file names. Dates are taken from the automatic EXIF data from a digital camera. For other images, dates can be edited using the Edit Metadata function.
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, rating, file name, caption, comments, location). Tagging is generally fast, 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 (the default sequence from the camera), then groups of images will tend to have the same tags, which makes the process of adding tags faster. There is also a batch function for adding the same tags to many images that you select by clicking thumbnails (link). Note that images downloaded from the Internet may have many tags conforming with no system. You will need to clean these out or redo them.
Geotags
Use geotags to assign a city (or national park, etc.) and country, and optionally latitude / longitude to your images. This enables all images for a location to be quickly found (or those near a location if latitude / longitude is used). If you use a camera with a GPS receiver and automatic geotagging, then location is in the image EXIF data and location searching is available automatically. Since image dates are also automatic (in EXIF), images can be searched by date range and location without you having to enter any data for each image. You can leave it at this, or add some of the above extras if you accept the extra effort required. My experience so far with automatic city / country via GPS is that the names are chaotic and you may want to sanitize them (upper / lower case, with / without states or other political subdivisions, fix mixed languages, etc.). You can fix the mess with a little effort: search for the location you want to change (e.g. München), then process the resulting images with the Batch Add Geotags function to change the location (e.g. Munich).
Albums
Another method of organization is to use albums. Choose a name for each album and assign any desired images to the album, using basically two clicks per image (plus the time to find the images to add). The images are not duplicated. This method is independent of tags, captions, file names, etc. See Manage Albums. Albums can be selected by name and viewed directly as a gallery of thumbnails or sequentially in the main window.
Summary
The following table summarizes the options. Keep in mind that searching by date works with any of these methods, and you can combine the methods any way you wish, e.g. "directory and file names" together with "captions and comments".

Method and Example | Advantages | Disadvantages
Directory and File Names e.g. image files like this: /images/2012/Rome-12.jpg | • simple and easy to use • fast implementation: batch move and rename files with added sequence numbers • gallery overview at each level of hierarchy • easy to navigate up / down hierarchy levels | • no overview of available search terms • long file names required for multiple search categories (date, place, persons, events ...) • risk of inconsistent naming and chaos
Captions and Comments e.g. caption or comment like this: 2012 Italy Rome Forum | • simple and easy to use • flexible search using multiple categories • moderately fast implementation: think + write time, per image | • no overview of available search terms • may end up with thousands of categories • risk of inconsistent naming and chaos
Tags (EXIF Keywords) e.g. tags like this: italy, rome, forum, elizabeth | • flexible search using multiple categories • moderately fast implementation: think time + one click per tag, per image (or batch add tags to a group of images) • good overview of available tags to click (organized by persons, places, events ...) • easy addition of new tags | • requires careful planning of tags • slow to find and click tags if 300+ tags • hard to revise tag naming system (batch tag add / delete / replace available) • risk of inconsistent naming and chaos
Geotags e.g. location data like this: Rome Italy 41.89 N 12.48 E | • cameras with GPS store data automatically • add locations in a few seconds per image (or batch add location to many images) • search location by clicking on a map image • search location and date-range by clicking on a report of available locations / dates | • useful only for searching by location • chaotic location naming by cameras (revise using search and batch update)
Albums e.g. album names like this: • best scenery • Italy 2012 | • make ad hoc albums using any criteria • images can be in multiple albums or multiple times within one album | • time to locate and add images to an album (find and click gallery thumbnails) • images not searchable by other categories • not standards compliant

User Guide Changes
This section is provided to help you quickly review the changes without reading the whole manual.
Fotoxx version numbers correspond to year and month of release.
v.15.04 (this release)

- Zonal Flatten: New Edit function to enhance detail in image areas with poor contrast.
- Directed Blur: New Effects function to blur an area in a single direction.
- Plugins: Support added for commands that do not edit an image file.
- Voodoo Enhance: a second method was added based on Zonal Flatten.
- User Settings: an option was added to show or hide hidden directories in gallery view.

v.15.03

- Rotate 90 was renamed to Upright and the funtionality was extended.
- "Named Collections" are now called "Albums". Menus, dialogs and the user guide were revised.
  The directory .../.fotoxx/collections is renamed to .../albums (nothing is lost).
- Mashup has extensive changes for controlling overlay image transparency and warping.

v.15.02

- The startup parameter -nosync was changed to the more correct -noindex.
  See the technical notes section below for command line parameters.
- A multi-row panorama capability was added using the Panorama Tools utilities.
- User Settings has a new parameter: Thumbnail size.
- Slide Show has added flexibility for showing image captions and comments.

v.15.01

- The Plugins menu was moved from the left panel into the Edit menu, to conserve space.
- Adding and revising plugin functions was made easier.
- Reduce Noise: explanation was added for the new dark areas functionality.
- Gallery popup image: new functionality with F11 and Escape keys.
- Magnify function: the user interface was made more flexible.

v.14.12

- Magnify Image: New Tools function to magnify the image in an area around the mouse pointer.
- User Settings: New option to show only latest file versions with prev/next button or KB keys.
- A new command parameter -nosync was added to allow faster startup when no image editing is intended. Please read more about the limitations in the Technical Notes section.
- Select Area: The Finish dialog can extend the selection to designated image corners.

v.14.11

- Popup Menus: expanded to explain new gallery thumbnail popup window options.
- Mouse Functions: new table entry to explain gallery window scrolling with the mouse.
- Images by Map Location: explain the optional fotoxx-maps package and how to install
  custom maps. The function Download Geotags has been removed.

v.14.10

- Make Waves: The topic was expanded to explain additional control options.
- Add Lines: The topic was revised to explain a simplified way to reposition a line or arrow.
- Mashup: The section about lines / arrows was revised for a simplified way to reposition.
- Top Menus: A paragraph was added under Gallery View to explain the thumbnail right-click menu Popup Image.
- User Settings: new parameter Monitor Scale.

v.14.09

- Search Images: A sentence was added to explain how missing times in a date / time search range are defaulted.
- Slide Show: Two sentences were added to explain the new options "full screen" and "auto-replay".
- Batch Convert automatically updates albums containing the moved or renamed image files.
  (The Move Albums function was problematic and was removed.)
- Sync Gallery topic was added to the File menu, where it should have been long ago.
- The Popup Menus topic was expanded.
- Search Images: A section was added to explain the new "last version only" option.
- Find Duplicate Images: This is a new function to find duplicate images anywhere in the image database.

v.14.08

- Menu Structure: The Image and Retouch functions were combined into a single Edit menu. The Color edit functions were moved into the Repair menu.
- Manage Albums: The dialogs were improved. A drag and drop capability was added for rearranging images within an album.
- Make Waves: New Effects function to make an image or selected area appear wavy, as if viewed through turbulent water.
- Area Color and Line Color: Changing the color of overlay lines (Trim rectangle, area outlines ...) was simplified and convenience links were added in the Tools and Areas menus.
- Open Previous File now retains the current zoom level and window position - good for comparing images while editing.

v.14.07

- Fotoxx menus were slightly rearranged for space efficiency. Two menu icons now connect to two functions based on left or right mouse click: edit undo / redo and prev / next file.
- A new menu containing batch and combine functions was added to the gallery view, duplicating functions also found in the image view.
- Mashup: Lines and arrows can be added to the image. Adjusting transparencies and overlaps was simplified.
- Add Lines: New function to add lines or arrows on an image.
- Select Area: New function to save a selected area as a PNG file with transparency information.
- Open RAW and Batch RAW were revised for the addition of Raw Therapee.
- Batch Upright: new function to upright images turned 90°.
- Panorama: image color and brightness matching was improved.
- The world map was made 2x larger, requiring a new download.

Technical Notes
Fotoxx Limitations

image files | Fotoxx was tested with 156K image files and performace was good (see benchmarks, below). 500K image files should be practical on a strong computer, but startup time may be 20+ seconds.
image size | The max. supported image width or height is 20K pixels (compile time constant).
image edits | 99 edits for undo / redo and file version numbering (filename.v01 to filename.v99).
geotag cities | 20,000 different cities / locations for geotagged images (compile time constant).
tags | There are limits listed in the topic Tags Overview.

Running out of memory
Fotoxx can require a huge amount of main memory to edit a large image. A 20 megapixel image requires 720 megabytes for the simplest edits, and more for complex edits. Images in memory are not compressed and each RGB pixel is represented by three floating-point numbers (12 bytes total). HDR, Panorama and other composite functions hold all images in memory during alignment and post-process tuning. If you push the memory limits on a small computer, the Linux OS may kill the Fotoxx process without warning and with no message (this is to keep the operating system itself from failing). What you see is that the Fotoxx window simply vanishes. Fotoxx monitors the amount of memory available in the status bar at the top of the window.
Running out of disk space - temporary files during an edit session
During a series of image edits, each change is saved on disk, and the before / after results can be viewed with the buttons [undo] and [redo]. These images use floating point numbers for color values and are not compressed. A 20 megapixel image makes a 240 MB file. If there are 10 edits in the undo / redo stack, the required disk space is 2.4 GB. If disk space runs out during an edit session, the program terminates with a message. To avoid this, be sure there is plenty of disk space wherever your /tmp directory resides. When you open a new image or quit Fotoxx, the disk space is recovered. If Fotoxx crashes, the space is recovered the next time fotoxx is started.
Additional programs required or recommended for Fotoxx
Fotoxx requires the following libraries and programs to function at run time:

xdg-utils | open text or html files with user's preferred application
exiftool | (v. 8.60 or later) read and write image metadata (tags, comments, etc.)
dcraw | batch convert RAW image files to tiff, jpeg, or png
ufraw | open a RAW image for editing using the ufraw GUI
brasero | burn a CD or DVD with selected images
xgamma | used for the Monitor Gamma function (adjust monitor gamma)
fotoxx-maps | makes several geographic maps available for reporting by clicked location
hugin | the function PT Panorama uses the panorama tools utilities packaged with hugin

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 and C libraries
libgtk3.0-dev | Gnome GTK3 / GDK3 / Pixbuf / etc. function libraries
libtiff5-dev | tiff library development files
libpng12-dev | png library development files
liblcms2-dev | Little CMS development files

Note: package naming and contents are decisions made by each Linux distro (i.e. the usual chaos). The above names are valid for Debian-based distros (including Ubuntu). For other distros you may have problems finding the right packages to install.
zappcrash - backtrace dumps
If Fotoxx has a fatal error (e.g. segment fault - invalid memory reference), it attempts to intercept the error and produce a backtrace dump which appears in a popup window and in the file /home/<user>/.fotoxx/zappcrash. Please send this information to me so I can hopefully fix the error (contact). A description of what you did immediately before the crash would also be helpful.
Command Line Options (long and short forms)

/.../filename.jpg |  | initial image directory or image file to open
-ver | -v | output release version and exit
-recent | -r | show a gallery of recently seen image files, most recent at the top
-new | -n | show a gallery of the newest image files (from Index Image Files)
-prev | -p | show the last file viewed in the previous session
-blank | -b | show a blank window
-lang lc_RC | -l | language code (+ opt. region code) to use for GUI (de, de_AT, fr ...)
-menu "func name" | -m | startup menu function - Fotoxx will start with this function active.
-noindex |  | disable image indexing (see below for bad implications).

-noindex option
This command line parameter can be used at Fotoxx startup to disable the normal metadata index update. The startup will be faster, especially if your image library is large (>20,000 images) or your computer is slow. All image search functions and map functions will be disabled, since results could be wrong if the metadata index no longer matches actual image metadata. These functions will work again after a normal fotoxx startup is made and the metadata index is updated for any new or modified image files. Use this option only if you need to quickly look at a few images and do not intend editing or searching. Gallery pages may also be quite slow if they contain many image files that are new or were modified since the last index update. This is because the thumbnail files must be created as needed.
Status Bar Information
CPU 123% MB 1234 2345x1234x8 3.45MB 56% edits: 3 menu locked area active dialog open

CPU 123% | current Fotoxx CPU load for all threads and processor cores
MB 1234 | total free memory, including the file cache (which can be reallocated to apps)
2345x1234x8 | image width x height x depth (bits per color)
3.45M | 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
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 recent images. 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 libraries to support reading and writing of image files: the GDK pixbuf library, libpng and libtiff. The file types that can be read and written include JPG / JPEG, PNG, TIF / TIFF and BMP. Three RGB colors with 8 bits per color are supported for all types. PNG and TIFF also support 16 bits per color. Fewer than 8 bits per color and grayscale images are partly supported, and are converted to RGB internally.
Image Index Files
These can be found in the directory /home/<user>/.fotoxx/image_index
The files named "index_001", "index_002", etc. contain the image file pathnames and those metadata items that are indexed for fast searching (dates, ratings, tags, caption, comments, geotags). The file "top_directories" contains a list of the top image directories. These are searched for new image files whenever Fotoxx starts up. The last entry is the thumbnails directory.
Color Depth
8-bit color (256 brightness levels), as supported by JPEG files, is the norm for image files and is usually adequate. The effective brightness range for photo paper is less than 8 bits. One brightness step (averaging 1/256 or 0.4% of the entire range) is very hard to see. 16-bit color can be useful if a narrow brightness range within an image has been greatly expanded using retouch or repair functions. This expansion can lead to visible "banding" or "posterization". If the RAW image is edited instead of the JPEG version, this problem can be reduced, even if the image is converted back to JPEG for final storage. See the web page deep color for a more complete explanation with example images.
The JPEG range of 256 brightness steps from black to white has been reduced here to 40 steps, and the image is magnified 2x. If you try hard you may be able to see the steps. This should make it clear that the 256 steps provided by JPEG are fully adequate, except in extreme cases as noted above.
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 more entertaining. Each image in succession is systematically warped various small amounts and the fit with other images 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, it is both fast and simple.
Alpha Channels
Images having alpha channels (transparency information) can be edited, but the alpha channel is ignored and removed 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). Any function that changes image size or shape will reduce resolution about 1/2 pixel. These are the resize, rotate, bend / warp, and all the composite functions. Rotating 90 degrees does not affect resolution. When downsizing an image, using the ratios 1/2, 1/3, 1/4 will give the least loss of resolution. Functions that change brightness, color or contrast do not affect resolution.
JPEG Compression
If a JPEG file from a digital camera is saved with Fotoxx, you will likely notice a large reduction in file size, even if a high JPEG quality level is used. This is because Fotoxx can afford to invest more processing power in the compression. A camera CPU is not very fast and must save the photos quickly to be ready for the next photo, so the processing time needed for high compression is not available. The CPU of a PC is typically much faster and has more time, so the compression level is higher. The smaller file size does not mean that the quality is less.
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 image artifacts. The effect seems to be negligible if JPEG "quality" is set to a high value when the image is saved. The image below was saved 10 times using quality=90 (Fotoxx default), each time opening and saving the previous image. Differences can be found if you look hard enough. The images are 2x size and the insets are 5x.
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 data gets lost, you can restore it using the "Edit Any Metadata" function.
Newline characters in user Comments and Captions
When editing metadata 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. Column alignment is not possible.
Installed Files
The following files are installed with Fotoxx (distro package or "make install" from source package).
/usr is the normal location for installed packages, but this could also be /home/<user>/ or /opt.

/usr/bin/fotoxx | the executable program file
/usr/share/fotoxx/* | user guide, translation.po files, icons, default data, etc.
/usr/share/doc/fotoxx | change log, man page, README and other documentation files.

Installed Files - optional fotoxx-maps package

/usr/share/fotoxx-maps/* | geographic maps data files (112 MB)
/usr/share/doc/fotoxx-maps/* | change log, man page, README

Local Files
The following files reside in /home/<user>/.fotoxx/

/albums | image albums from Manage Albums function
/custom_kernel | saved custom kernel data files
/favorites | saved data for user-configuration of favorites menu
/image_index | text files containing searchable metadata for all image files
/locales | saved translation (.po) files, possibly user-modified
/mashup | saved mashup project files
/patterns | saved background patterns
/retouch_combo | saved settings for the Retouch Combo function
/saved_areas | "cutout" files saved from the Select Area > Save dialog
/saved_curves | curve data saved from Retouch curve edit dialogs
/slideshows | user preferences from Slide Show function
/thumbnails | thumbnail files (default location, user can change this)
/write_text | image text overlays saved from Add Text function
bookmarks | bookmark names and image file locations
KB-shortcuts | user-defined or modified keyboard shortcuts
logfile | Fotoxx outputs that may be relevant for diagnosing problems
mosaic_tiles | binary file, compressed tiles from the Mosaic function
newest files | a list of the 200 most recently added image files
pagesetup | saves page setup data for print function
parameters | setup parameters that are saved across Fotoxx sessions
plugins | saves the plugins menu contents
printsettings | saves print settings data for print function
recent_files | a list of the last 100 files opened by Fotoxx, saved when Fotoxx exits
search_results | list of the last image files found with Search Images
stuck-pixels | data saved from the Fix Stuck Pixels functin
tags_defined | a list of all categories and tags currently used in all images
zdialog_inputs | saved dialog data for dialogs that recall prior inputs
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 (reduced). 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 7 times faster to process than a 14 megapixel image (typical digital camera). This method is used whenever the preview edits can be applied to the full-size image without visible impact (Trim / Rotate, Bend functions, brightness 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.
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 4 bytes. A 10 megapixel image uses 120 megabytes in memory and typically < 2 megabytes on disk (JPEG). When the edited image is saved, the correct file size is updated on the status bar.
Metadata used by Fotoxx
The following metadata items (stored inside the image files) are used by Fotoxx. These items and any other metadata can be viewed or edited using Fotoxx or other programs such as Photoshop. Images can be searched using these items or any other metadata as selection criteria. Those marked "index" can be searched very fast, others more slowly. Items not listed here are searchable but not indexed.

Metadata section and name | Usage | Index
IPTC:Keywords | tags entered by user | yes
IPTC:Rating | "star" rating entered by user | yes
EXIF:ImageSize | pixel width and height, 1234x2345 | yes
EXIF:DateTimeOriginal | date / time photo was made, or entered by user | yes
EXIF:ImageHistory | history of image edits (used by Fotoxx and others) | no
EXIF:UserComment | comment text entered by user | yes
IPTC:Caption-Abstract | caption or abstract text entered by user | yes
EXIF:FocalLengthIn35mmFormat | camera focal length used, 35mm equivalent | no
EXIF:City, Country | city and country from camera GPS, or entered by user | yes
EXIF:GPSLatitude, GPSLongitude | earth coordinates from camera GPS, or entered by user | yes

Dialog Window Positioning
For commonly used dialogs, Fotoxx saves the dialog window position (relative to the main window) and tries to restore the same position the next time the dialog is started. This works, mostly. Sometimes the window manager ignores this request and places the dialog somewhere else.
Benchmarks
Conditions: Fotoxx 15.02, Ubuntu 14.04, Intel Core i5 3 GHz, 7200 rpm disk, EXT4 file system.
The first benchmark is for the initial indexing of 156,240 image files (180 GB).
The next two are for subsequent Fotoxx startups with 0 and 343 new image files.

Benchmark Description | Image Files | Time
First time index, find and index all image files | 156,240 | 96 min.
Subsequent startup with no new image files | 0 new, 156,240 old | 5 sec.
Subsequent startup, 343 new files to index | 343 new, 155,897 old | 16 sec.
Find all images with tag "Rosi" | 5502 found | 1 sec. (1)
Find all images with "Rosi" in file name | 2856 found | 1 sec.
Find all images dated Jan 1 - Feb 28, 2013 | 420 found | 1 sec.
Same time period, with city = "Freising" | 168 found | 1 sec.
Same time period, with EXIF "make" = "panasonic" | 126 found | 7 sec. (2)
Click on world map, France / Esterel | 105 found | 1 sec.
List all locations having images | 368 locations | 2 sec.
Click on location Germany / Augsburg | 231 found | 1 sec.

(1) The search benchmarks show the fast search speed when all search criteria are indexed.
(2) This benchmark shows the slower speed to find non-indexed metadata: 420 images were found quickly by time, then searched again for the non-indexed EXIF data "make". This benchmark also used the Metadata report format with thumbnails and metadata details, which is slower than the normal thumbnail gallery report.
SSD Benchmark
Image files: 100,113 (126 GB). First time index: 35.1 minutes. Startup time (no new images): 2.2 seconds.
Other conditions same as above.
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 may contact me.
Questions, Problems, Bugs
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 (zappcrash) on the screen, or error messages in the log file /home/<user>/.fotoxx/fotoxx.log, please send these also. Please explain how to produce the error if you can.
Technical Reference Book
I used 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, noise reduction (median smoothing, top hat), sharpen (unsharp mask, kuwahara), embossing.
Acknowledgements
The programs libtiff, libpng, liblcms, dcraw, ufraw and 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, their ideas for development and their time for testing. Special thanks to the following: Dick, Jill, Jamps, Andre, Doriano, Curley, Jan, Rosi.