FOTOXX USER GUIDE  v.23.74
   View using the Fotoxx menu Help > User Guide

INTRODUCTION
   \>FOTOXX OVERVIEW\> - description, prerequisites, license, downloads
   \>FOTOXX CAPABILITIES\> - summary of Fotoxx functions and tools

FOTOXX USAGE
   \>INSTALLATION\> - Fotoxx software installation, dependencies
   \>FIRST STARTUP\> - information for when Fotoxx is started for the first time
   \>OUTBOARD PROGRAMS\> - required and optional programs used by Fotoxx
   \>FIRST INDEX\> - locating and indexing image files for fast searching
   \>USER GUIDE\> ← \bclick here\b - how to use this user guide browser
   \>WINDOW VIEWS AND MENUS\> - top-level windows and associated menus
   \>FILE VIEW\> - File View window (view single image file)
   \>GALLERY VIEW\> - Gallery View window (view thumbnails)
   \>MAP VIEW\> - map view window (view map with location markers)
   \>MENU SUMMARY\> - outline of menu groups and contents
   \>DRAG AND DROP\> - file drag and drop methods
   \>EDIT PROCEDURES\> - how to edit image files
   \>EDIT WORKFLOW\> - alternative edit methods - simple and complex
   \>MOUSE OWNERSHIP\> - dialog-mouse control and interaction
   \>MOUSE ALTERNATE RIGHT-BUTTON\> - mouse right-button for touchpads/screens
   \>DIALOG BUTTONS\> - dialog completion options
   \>KEYBOARD ENTER KEY\> - functions of Enter key
   \>KEYBOARD ESCAPE KEY\> - functions of the Escape key
   \>CUSTOM DIALOG WIDGETS\> - how to use custom dialog widgets
   \>CURVE EDITING\> - how to manipulate curves used in edit functions
   \>BATCH PROCESSING\> - overview of batch processing functions
   \>SELECT IMAGE FILES\> - image file selection procedure used everywhere
   \>POPUP REPORTS\> - keyboard navigation for text-based popup reports
   \>MENU SHORTCUTS\> - popup menus, keyboard shortcuts, custom user menu
   \>COLLECTION MANAGEMENT\> - collection management and image searching
   \>RIGHT-CLICK MENUS\> - popup menu functions for File View and Gallery View
   \>KEYBOARD SHORTCUTS\> - keyboard shortcuts for file/gallery/map views
   \>MOUSE FUNCTIONS\> - mouse functions for file/gallery/map views
   \>COMMAND PARAMETERS\> - Fotoxx startup options using command line parameters
   \>TOP PANEL DATA\> - details of information in the File View top panel

\>FILE MENU\>
   \>NEW SESSION\> - start new Fotoxx session in a separate window
   \>OPEN IMAGE FILE\> - open an image file for view or edit
   \>IMAGE FOLDER\> - open corresponding Gallery View from current image file
   \>CYCLE 2\> - cycle through the two most recently seen image files
   \>CYCLE 3\> - cycle through the three most recently seen image files
   \>VIEW 360° PANO\> - view a 360° panorama image with rotating viewpoint
   \>RENAME\> - rename an image file
   \>PERMISSIONS\> - view and set permissions for an image file
   \>CHANGE ALPHA\> - add or remove alpha channel for an image file
   \>BLANK IMAGE\> - create a new blank image file with specified size and color
   \>COPY/MOVE\> - copy or move an image file to another folder
   \>COPY TO DESKTOP\> - copy an image file to the desktop
   \>COPY TO CLIPBOARD\> - copy an image file to the clipboard
   \>DELETE/TRASH\> - delete or trash an image files
   \>CONVERT ADOBE\> - convert Adobe files (.pdf/.ps/.eps/.psd) to jpeg images
   \>SET WALLPAPER\> - set desktop wallpaper from the current image file (Gnome)
   \>SHOW ON MAP\> - show an image file position in Net Map View
   \>PRINT\> - print an image file
   \>PRINT CALIBRATED\> - print an image file using color calibration data
   \>QUIT\> - exit from Fotoxx

\>GALLERY MENU\>
   \>THUMB VIEW\> - Gallery View with large thumbnails and file names only
   \>META VIEW\> - Gallery View with thumbnail and basic metadata used by Fotoxx
   \>RECENT FILES\> - open Gallery View of most recently seen image files
   \>NEWEST FILES\> - open Gallery View of newest image files in the collection
   \>GALLERY SORT\> - change the sort order of a gallery
   \>GALLERY SCREEN\> - select newest, oldest, matching pattern ...
   \>GALLERY HOME\> - jump to gallery start
   \>GALLERY END\> - jump to gallery end
   \>IMAGE FOLDER\> - open corresponding Gallery View from current image file
   \>FOLDER TREE\> - show all image file folders in a tree structure
   \>SELECT FILES\> - select files for input to batch, script or album
   \>RENAME FOLDER\> - rename current folder (file gallery)
   \>ADD SUBFOLDER\> - add new subfolder to existing image folder
   \>BOOKMARKS\> - add bookmarks, view list of bookmarks, go to bookmark
   \>MANAGE ALBUMS\> - create and arrange user-defined image collections
   \>UPDATE ALBUMS\> - update album files for updated image files (new versions)
   \>ALBUM MASS UPDATE\> utilities for mass update of multiple album files
   \>GALLERY TO ALBUM\> - save current gallery as an album with assigned name
   \>SLIDE SHOW\> - create a slide show with animated transitions and zooms

\>MAPS MENU\>
   \>NET MAP\> - use zoomable internet map
   \>NET MAP LOCS\> - define or go to named map location (position and scale)
   \>DOWNLOAD MAPS\> - download geographic map files for use with Fotoxx
   \>FILE MAP\> - use local map files instead of internet map
   \>CHOOSE MAP\> - choose from available maps (USA, France, NYC, etc.)
   \>MARKERS\> - show map markers for all images or only current gallery

\>CUSTOM MENU\> - custom user menu for frequently used functions
\>ZOOM\> - left/right click or [+-] button to zoom image or thumbnail in/out
\>FILE SAVE\> - save an image file (replace, new version, new file name)

\>METADATA MENU\>
   \>VIEW META\> - list main image metadata
   \>VIEW ALL META\> - list all image metadata
   \>TAGS OVERVIEW\> - image tags (keywords) used for image searching
   \>EDIT META\> - edit commonly used metadata
   \>EDIT ANY META\> - edit any metadata (add, change)
   \>DELETE META\> - delete specified metadata or all metadata
   \>COPY META\> - copy metadata from one image file to another
   \>FIX META\> - repair malformed metadata preventing metadata edits
   \>MANAGE TAGS\> - manage user-defined tags
   \>CAPTIONS\> - show file name, title, description in top left image corner
   \>PLACES/DATES\> - list image locations and date groups, click for gallery
   \>TIMELINE\> - table of image counts by year and month, click for gallery
   \>AUTOSEARCH\> - script files can use the Search function to screen files
   \>SEARCH IMAGES\> - search using any metadata or folder/file names

\>SELECT MENU\>
   \>AREA OVERVIEW\> - select area - concepts and usage
   \>SELECT AREA\> - selecting an image feature or area for separate editing
   \>FIND AREA GAP\> - find gap in hand-drawn area outline
   \>AREA BLEND\> - mouse-blend edits made within a selected area
   \>SHOW/HIDE AREA\> - show or hide area outlines
   \>ENABLE/DISABLE AREA\> - enable or disable an area for editing
   \>INVERT AREA\> - invert an area (exchange outside/inside areas)
   \>CLEAR AREA\> - remove an area
   \>COPY/PASTE AREA\> - copy an area and insert somewhere else later
   \>LOAD/SAVE AREA\> - load an area from a file or save an area to a file

\>UNDO/REDO BUTTON\> - sequential undo or redo edits to current image

EDIT FUNCTIONS

\>EDIT MENU\>
   \>ROTATE\> - rotate or level an image
   \>UPRIGHT\> - upright a rotated or mirrored image
   \>CROP\> - crop (trim) image margins
   \>RETOUCH\> - edit brightness, contrast, color, saturation
   \>RESCALE\> - change the image pixel dimensions
   \>MARGINS\> - add margins to an imqage, using any color or transparency
   \>MARKUP\> - draw on image: text, line/arrow, box, oval
   \>COLOR MODE\> - convert to black & white, color, negative, positive, sepia
   \>PAINT IMAGE\> - mouse-paint with a color, brush size, and opacity
   \>PAINT EDITS\> - mouse-paint an edit function locally and gradually
   \>PAINT TRANSP\> - paint increasing transparency using the mouse
   \>COPY IN IMAGE\> - copy pixels within an image using the mouse
   \>COPY FROM IMAGE\> - copy pixels from another image using the mouse
   \>COPY PRIOR EDIT\> - copy pixels from prior edits using the mouse
   \>PLUGINS\> - start a plugin edit function, open plugin output file
   \>EDIT TEMPLATE\> - coding template for new edit functions

\>REPAIR MENU\>
   \>SHARPEN\> - sharpen a blurred image, multiple methods
   \>BLUR\> - blur an image or image area, multiple methods
   \>DENOISE\> - reduce image noise (small random specks)
   \>DEFOG\> - add or remove fog/haze from an image or selected area
   \>RED EYES\> - remove red eyes from flash photos
   \>SMART ERASE\> - remove power lines, trash, signs, other small spoilers
   \>REMOVE HALO\> - remove halos left by sharpen and other edit functions
   \>JPEG ARTIFACTS\> - suppress jpeg artifacts in highly compressed image files
   \>ANTI-ALIAS\> - suppress pixelation (jaggies) along image feature edges
   \>ADJUST RGB\> - adjust image colors using RGB or CMY colors
   \>ADJUST HSL\> - select and change colors using HSL colors
   \>COLOR PROFILE\> - convert color profile (e.g. sRGB <--> Adobe RGB)
   \>REMOVE DUST\> - remove dust spots on images scanned from old photos
   \>CHROMATIC 1\> - fix chromatic aberration (color fringes in periphery)
   \>CHROMATIC 2\> - fix chromatic aberration (color bands along bright edges)

\>REFINE MENU\>
   \>VOODOO 1\> - automatic 1-click enhancement that may work OK
   \>VOODOO 2\> - automatic 1-click enhancement that may work OK
   \>EDIT DIST\> - edit brightness distribution, rebalance dark and bright areas
   \>FLATTEN DIST\> - flatten brightness distribution to improve details
   \>LOCAL CONTRAST\> - add contrast adapted to brightness of each image area
   \>GRADIENTS\> - increase contrast where it is weakest
   \>GLOBAL RETINEX\> - rescale RGB values to remove color cast and fog/haze
   \>LOCAL RETINEX\> - rescale RGB values to remove color cast and fog/haze
   \>SATURATION\> - adjust color saturation, optionally based on brightness
   \>SOFT FOCUS\> - apply classic "soft focus" effect to an image
   \>MATCH COLORS\> - match the colors in one image to those in another image
   \>BRITE RAMP\> - add a brightness/color ramp across an image
   \>VIGNETTE\> - change brightness or color radially around a chosen center

\>EFFECTS MENU\>
   \>SKETCH\> - convert an image into a simulated sketch
   \>CARTOON\> - convert an image to a cartoon-like drawing
   \>DRAWING\> - convert an image to a simulated line drawing
   \>EMBOSS\> - convert an image to a simulated embossing (3D effect)
   \>TILES1\> - convert an image into square tiles with 3D effect
   \>TILES2\> - convert an image into irregular tiles matching image
   \>PAINTING\> - convert an image into a simulated painting
   \>TEXTURE\> - add texture to an image or selected area
   \>PATTERN\> - add a background pattern to an image
   \>DITHER\> - different ways to pixelize or posterize an image
   \>ENGRAVE\> - convert an image into black & white lines
   \>MOSAIC\> - convert an image into a mosaic using tiles made from all images
   \>ADD NOISE\> - add random noise to an image
   \>COLOR DEPTH\> - reduce the number of colors (posterize)
   \>SHIFT COLORS\> - gradually shift RGB colors to GBR or BRG
   \>ALIEN COLORS\> - add random strange colors to an image
   \>COPY COLORS\> - copy selected colors from current image
   \>PASTE COLORS\> - paste selected colors from selected image
   \>CUSTOM KERNEL\> - edit and apply a custom convolution kernel to an image

\>WARP MENU\>
   \>UNBEND\> - straighten images having curved lines, esp. panoramas
   \>PERSPECTIVE\> - straighten an object photographed from an obtuse angle
   \>WARP AREA\> - warp a selected image area by pulling with the mouse
   \>WARP CURVED\> - warp entire image or area using the mouse - curvy warp
   \>WARP LINEAR\> - warp image by mouse drag - straight lines preserved
   \>WARP AFFINE\> - warp image by mouse drag - parallel lines preserved
   \>AREA RESCALE\> - rescale an image down, leaving selected area at full scale
   \>UNWARP CLOSEUP\> - remove distortion from close-up face photo (big nose)
   \>MAKE WAVES\> - warp an image with a wave pattern
   \>TWIST\> - twist an image around a chosen center point
   \>SPHERE\> - curve an image into a spheroid shape
   \>STRETCH\> - add or remove barrel or pincushion distortion
   \>INSIDE-OUT\> - invert the center-edge distance of each pixel
   \>TINY PLANET\> - wrap a panorama image around a circle
   \>ESCHER SPIRAL\> - transform an image into an endless inward spiral
   \>FLATTEN PHOTO\> - flatten a photo of a curved surface

\>COMBINE MENU\>
   \>HDR\> - combine images with varying ISO for an extended brightness range
   \>HDF\> - combine images with varying focus depth for extended depth of field
   \>STACK/PAINT\> - combine images to remove transient cars, tourists, etc
   \>STACK/NOISE\> - combine images to reduce noise by averaging
   \>STACK/VERSIONS\> - combine image versions, select/paint area/version
   \>STACK/SPLIT\> - show two images overlapped with a movable boundary line
   \>PANORAMA\> - stitch together a series of images horizontally
   \>SHOW CIM FILES\> - show input files for the current/latest combined image
   \>MASHUP\> - arrange multiple images and formatted text in a custom layout
   \>IMAGE ARRAY\> - join many images into a compact array format

\>BATCH MENU\>
   \>BATCH CONVERT\> - copy, move, rescale, rename, convert, add text ...
   \>BATCH COPY/MOVE\> - copy/move selected image files to a new folder
   \>BATCH UPRIGHT\> - scan for rotated image files and upright them
   \>BATCH DELETE/TRASH\> - delete or trash selected image files
   \>BATCH RAW\> - convert RAW files to JPEG/PNG/TIFF, 8 or 16 bit color
   \>BATCH OVERLAY\> - add overlay image (copyright ...) to selected host images
   \>BATCH TAGS\> - add or remove tags for selected image files
   \>BATCH RENAME TAGS\> - rename tags for selected or all image files
   \>BATCH PHOTO DATE\> - change photo dates or times, or shift time zone
   \>BATCH CHANGE META\> - add or revise metadata for selected or image files
   \>BATCH REPORT META\> - report metadata for selected or all image files
   \>BATCH MOVE META\> - move metadata between keywords - fix irregular usage
   \>BATCH GEOTAGS\> - add or revise geotags for selected or all image files
   \>EXPORT FILE LIST\> - make a list of selected files (e.g. for shell script)
   \>EXPORT FILES\> - export selected files to a folder (e.g. for web upload)
   \>SCRIPT FILES\> - script files (macros) overview
   \>EDIT SCRIPT\> - record multiple edits in a script, execute on many files
   \>RUN SCRIPT\> - execute script on current image file (custom edit function)
   \>BATCH SCRIPT\> - execute script on all selected image files

\>TOOLS MENU\>
   \>INDEX FILES\> - 1-time job to find and index all image files
   \>QUICK INDEX\> - quick incremental index with no user interaction
   \>SETTINGS\> - user preferences and settings for Fotoxx operation
   \>KB SHORTCUTS\> - show and revise keyboard shortcuts for menu functions
   \>RGB DISTRIBUTION\> - show a brightness distribution graph for current image
   \>MAGNIFY IMAGE\> - turn mouse into a magnifying glass over image
   \>FIND DUPLICATES\> - find duplicate images in a gallery or entire collection
   \>MEASURE IMAGE\> - measure pixel distances within an image
   \>SHOW RGB\> - show RGB values at mouse position or for selected points
   \>POPUP TEXT\> - show popup window with texts to insert into edit widgets
   \>CALIBRATE PRINTER\> - calibrate printer color - compensate for color shifts
   \>GRID SETTINGS\> - show or remove grid lines, set line count or spacing
   \>LINE COLOR\> - set color for select area outlines
   \>DARK/BRIGHT PIXELS\> - tool to highlight clipping
   \>MONITOR COLOR\> - tool to adjust monitor brightness and contrast
   \>SHOW RESOURCES\> - show CPU time and current memory usage

\>HELP MENU\> - user guide, tutorial, change log, about Fotoxx, uninstall

\>OTHER TOPICS\>
   \>VIDEO FILES\> - video files, thumbnails, playing
   \>WEB UPLOAD\> - uploading image files to the internet
   \>MOVE FOTOXX HOME\> - move fotoxx home folder to a new location
   \>ORGANIZING IMAGES\> - organizing image files for effective searching
   \>PRIVACY\> - privacy policy and privacy considerations
   \>PROBLEM REPORTING\> - how to analyze and report problems
   \>LOG FILE\> - Fotoxx log file and crash report file (zappcrash)
   \>QUESTIONS, SUGGESTIONS\> - how to contact the Fotoxx author

\>TECHNICAL TOPICS\>
   \>FOTOXX LIMITATIONS\> - size and performance limits
   \>RUNNING OUT OF MEMORY\> - memory limits and performance
   \>RUNNING OUT OF DISK SPACE\> - disk space requirements
   \>SYMBOLIC LINKS\> - how these are handled and what to avoid
   \>PREVIEW MODE\> - method for higher interactive performance
   \>SUPPORTED FILE TYPES\> - what image file types are supported
   \>INDEX DATA FILES\> - index data files and contents
   \>COLOR DEPTH ISSUES\> - meaning and limitations
   \>NOISE MEASUREMENT\> - how is noise measured
   \>RAW IMAGE NOISE\> - noise in RAW image files
   \>SLIDES AND NEGATIVES\> - how to capture slides and film negatives
   \>HIGH QUALITY IMAGE UPSCALE\> - how to upscale 2x with best quality
   \>ROTATE PERFORMANCE\> - interactive rotation performance
   \>ALIGNMENT ALGORITHM\> - how images are aligned (panorame, HDR, etc.)
   \>ALPHA CHANNELS\> - how alpha channels are handled
   \>IMAGE DETERIORATION FROM REPEATED EDITS\> - analysis
   \>INTERPOLATION METHOD\> - technical description
   \>JPEG COMPRESSION\> - technical description
   \>IMAGE DETERIORATION FROM REPEATED JPEG SAVES\> - analysis
   \>METADATA ERRORS\> - description and handling
   \>NEWLINE CHARACTERS IN METADATA\> - description and handling
   \>DIALOG WINDOW POSITIONING\> - description
   \>FOTOXX PERFORMANCE\> - methods and limitations, benchmarks
   \>GTK TIMEOUT PROBLEM\> - description
   \>FOTOXX PACKAGES\> - package file contents
   \>FOTOXX HOME FOLDER\> - user data files in Fotoxx home folder
   \>IMAGE METADATA USAGE\> - description and limitations
   \>FOTOXX SOURCE CODE\> - how to access Fotoxx source code
   \>FOTOXX FOR WINDOWS 11\> - installing Fotoxx on Windows 11 WSL

\>ACKNOWLEDGEMENTS\>

\>ALL TOPICS INDEX\> alphabetical index of all topics in this document

FOTOXX OVERVIEW
   \bDescription
   Fotoxx is a free open source Linux application for editing photos and managing 
   a large image collection. The goal of Fotoxx is to meet the needs of serious 
   photographers while remaining fast and easy to use. Fotoxx has a rich set of 
   editing, enhancement, repair, and special effects functions. Modifications are 
   displayed instantly in a full-size image, allowing quick visual optimization. 
   Finding desired images can be made fast and easy, even for a collection up to 
   a million image files. Albums can be created and images arranged with drag and 
   drop. Images can be viewed by clicking markers on an interactive world map, 
   scalable from street to continent. A detailed list of Fotoxx capabilities is 
   available below.

   \bHardware Requirements
   Fotoxx works best on a strong computer, e.g. a 3+ GHz multi-core CPU with 16 
   GB RAM and SSD storage. A weaker computer will generally work, but may be slow 
   for some functions and unable to edit large images. A monitor smaller than HD 
   (1920x1080) will feel too small for some functions using multiple windows. 
   The monitor should of course have accurate color.

   \bSoftware Requirements
   Most recent Linux distributions can be used to host Fotoxx.
   Windows WSL works with limitations. See \_https://kornelix.net/fotoxx_topics/

   \bLicense and Warranty
   Fotoxx is licensed under the GNU General Public License v3. Fotoxx source code 
   is free to use, modify, and share with others. Fotoxx is not warranted for any 
   purpose, but if you find a bug, I will try to fix it.

   \bContact
   If you have a question, suggestion, or problem, contact me at 
      \_mkornelix@gmail.com\_.

   \bDownloads
   Fotoxx source code and binary packages are available to download from the
   author's web site at \_https://kornelix.net\_. Both methods are easy to install 
   and instructions are provided. The source package is like Debian packages 
   ($ sudo make install). The binary package works on most recent (>2020) flavors 
   of Linux. To avoid compatibility problems, it includes library files which may 
   be missing or incompatible depending on your flavor and release of Linux. If 
   some other library is missing, an error message is shown when the program is 
   started (start from a terminal to see this). Find and install the missing 
   library using your package manager.

   \bPackages by 3rd Parties
   Installable packages for many popular Linux distributions can be found here:
      \_https://repology.org/metapackage/fotoxx/packages
   Some of these are old and should be avoided. Note the release number and date.

   \bUpdates and Bug Fixes
   Fotoxx is updated periodically with new capabilities and bug fixes. Serious 
   bugs are usually fixed within a few days of being known, and a new release is 
   published on the kornelix.net web site. Fotoxx is also available on many other 
   web sites and package repositories. These may not be updated for new releases. 
   Some of these are years out of date and should be avoided.

   \bUser Guide
   Fotoxx is easy to use but unconventional. If you try to use Fotoxx while 
   ignorant, you will be frustrated and may conclude that Fotoxx is hard to use. 
   You would be wrong. To avoid getting stuck, please read the introductory 
   sections of this user guide. Help for individual functions can be referenced 
   as needed during Fotoxx use, by pressing the F1 key. Fotoxx has deep 
   functionality. Do not expect to master Fotoxx in a few minutes. 

FOTOXX CAPABILITIES
   \bHere is a fairly complete list of what Fotoxx can do.
   • Organize and manage a very large photo/image collection. 
   • Comprehensive user guide and popup context help via F1 key.
   • Thumbnail browser/navigator with variable thumb size and metadata view.
   • Click thumbnail for full-size view, image zoom in/out and pan/scroll.
   • RAW file conversion, single or batch, output with 8 or 16 bits per color.
   • Large set of functions to edit, repair, refine, and transform images.
   • Internal processing in 24 bits per color (float), output in 8 or 16 bits.
   • Edited files have a version number, originals are retained by default.
   • Fast edit visual feedback using the full image or selected zoom-in area.
   • Undo/Redo button - go back and forth to compare original/edited versions.
   • Conventional edit functions include: brightness, contrast, color, rotate,
     saturation, crop, rescale, sharpen, denoise, blur, paint, fix red eyes,
     markup (text/line/arrow/box/oval), fix perspective, fix lens distortion,
     remove chromatic aberration, warp/unwarp, smart erase (remove spoilers),
     soft focus, match colors, vignette (add/remove), suppress JPEG artifacts, 
     HDR (combine dark/light images), HDF (combine different focus depths),
     stack/layer edit, panorama (2-6 images), photo montage, color profile ...
   • Advanced edit functions to bring out details and add flair to an image:
     local contrast, remove fog/haze, edit or flatten brightness distribution, 
     retinex, edit gradients, brightness ramp, convert negative, sepia ...
   • A large set of creative special effects and arty transforms is available:
     sketch, cartoon, drawing, emboss, tiles, dither, painting, mosaic, 
     engrave, sphere, tiny planet, Escher spiral, custom kernels ...
   • Edit functions can be 'painted' locally and gradually using the mouse.
   • Select image objects or areas to edit separately from the background:
     outline by hand, follow feature edges, 'flood' into matching colors ...
   • Complex feature edges can be accurately selected (e.g. hair, foliage).
   • Copy areas within and across images by mouse painting and blending.
   • Create or maintain transparent image areas while editing.
   • Mashup: arrange images and text in an arbitrary layout using the mouse.
     (objects can be resized, rotated, overlapped with transparent areas ...)
   • Custom scripts: record a series of edits and use as a new edit function.
   • Custom user menu: collect frequently used functions into one menu.
   • Plugins: use Gimp, Imagemagick ... as embedded Fotoxx edit functions.
   • Batch tools: rename, resize, convert, export, add/revise/report metadata,
     convert RAW files, add overlay text, apply custom edit script.
   • Metadata edit and report (tags, dates, titles, geotags ... any metadata).
   • Search images using any metadata and folder/file names or partial names:
     dates, tags, locations, ratings, titles, descriptions, exposure data ...
   • Show a table of images by location and date range, click for image gallery.
   • Show an image calendar, click on year or month for a gallery of images.
   • Scalable internet map, click on marker for gallery of images at location.
   • Local file maps: world, continents, nations. Add custom maps. 
   • View 360 degree panorama image (Google Street View format).
   • Show video files as thumbnails (choose thumbnail frame), play video.
   • Show animated GIF files as thumbnails (first frame), play animation.
   • Bookmarks: assign names to folder/file locations, go to name (gallery).
   • Create albums with chosen images arranged by drag & drop. No duplication.
   • Slide show: show album images with animated transitions and pan/zoom.
   • Print an image at any scale. Printer color calibration tool available.
   • Custom keyboard shortcuts can be assigned to chosen functions.
   • Cycle wallpaper images from a Fotoxx album or any folder of image files.
   • Source and binary packages are available, independent of Linux flavor.
   • Gnu GPL3 license (everything is free to use as you please). 

INSTALLATION
   There are three variations of Fotoxx installation:
     • Use the package from your Linux distribution (Debian, RPM, others).
       Install Fotoxx like any other package. \bThe package may be quite old.
     • Use the distro-agnostic binary package from the kornelix.net website. 
       Follow the instructions on the download page to install the package.
     • Use the source code package (tarball) from the kornelix.net website. 
       Follow the instructions to build Fotoxx (basically $ sudo make install). 
       This also has a performance advantage if you add compiler optimization 
       for your target machine ($ gcc -march=native).
   Download page: \_https://kornelix.net/downloads/downloads.html
   
FIRST STARTUP
   There are two initialization tasks to be performed: 
     (1) install outboard programs, some mandatory and some optional
     (2) create the image index and thumbnail images

OUTBOARD PROGRAMS
   +image: outboard-programs.png
   When Fotoxx is started for the first time, the above report is presented, 
   listing the required and optional outboard programs that Fotoxx uses, the 
   function provided by each, and whether the program is installed or not. If 
   any required program is not installed, you are asked to install the program. 
   In this case, Fotoxx will exit when the dialog is closed. After installing 
   the required programs, start Fotoxx again. You can show this list at any time 
   with the menu Help > Outboard Programs. You can decide later if you need to
   install optional outboard programs to handle image files other than those
   supported by default: JPEG, PNG, TIFF and RAW formats.

     \brequired          function                         Debian package
     exiftool          read and write image metadata    libimage-exiftool-perl
     dcraw             index creation, RAW file open    dcraw   
     addr2line         fatal error (crash backtrace)    binutils

     \boptional
     ffmpeg            video, get thumbnail frame       ffmpeg
     dwebp             WEBP image files (.webp)         webp 
     heif-convert      Apple files (.heic .avif)        heif-examples
     opj_decompress    jpeg2000 image files (.jp2)      libopenjp2-tools
     gs command        Adobe files (.pdf/.ps/.eps)      ghostscript
     convert command   Adobe files (.psd)               imagemagick
     vlc               play video files                 vlc 

   Package naming and contents vary by Linux distro (the usual chaos). 
   The above names, or something similar, may be findable in your Linux flavor. 
   Happy hunting.

   Fedora notes:
     • Packages: openjpeg2-tools libheif libheif-devel
     • Build: \_https://apps.fedoraproject.org/packages/fotoxx/sources/spec/

   \bWEBP files (.webp)
   If the program dwebp is installed, Fotoxx will recognize .webp files. 
   When opened, a .tif temporary file is created and viewed. 
   If the image is modified and saved as a new version, a .jpg file is created: 
     filename.webp --> filename.v01.jpg.

   \bApple iPhone HEIF files (.heic .avif)
   Apple iPhones can produce image files with the extension .heic. 
   If the program heif-convert is installed, Fotoxx will recognize .heic files. 
   When opened, a .jpg temporary file is created and viewed. 
   If the image is modified and saved as a new version, a .jpg file is created: 
     filename.heic --> filename.v01.jpg. This also works for .avif files.

   \bJPEG-2000 files (.jp2)
   If the program opj_decompress is installed, Fotoxx will recognize .jp2 files. 
   When opened, a .tif temporary file is created and viewed. 
   If the image is modified and saved as a new version, a .jpg file is created: 
     filename.jp2 --> filename.v01.jpg.
   
   \bAdobe document files (.pdf .ps .eps)
   If the gs command (ghostscript) is installed, these files can be converted to 
   JPEG files, one per document page. Use the menu function File > Convert Adobe.
   
   \bAdobe (Photoshop) image files (.psd)
   If the convert command (imagemagick) is installed, these files can be 
   converted into JPEG files. Use the menu function File > Convert Adobe.

FIRST INDEX 
   +image: first-index.png
   When Fotoxx is started for the first time, it will ask to index your image 
   files. This makes the gallery pages (thumbnails) work fast, enables fast 
   search based on indexed metadata (tags, photo date, location, comments ...), 
   and enables clickable map markers to view images by location. You can defer 
   this step if you wish, but search, batch, and map functions will be disabled 
   and galleries will be slow. The index function will ask for one or more 'top' 
   folders (e.g. /home/<user>/Photos). Subfolders are automatically included. 
   Other non-image files can be mixed-in and will be ignored. Indexing speed can 
   range from a few hundred to a few thousand images per minute, depending on 
   image types, sizes and computer speed. Fotoxx does not modify or copy your 
   image files - it only reads them to make the metadata index and thumbnails. 
   The additional file space is normally <2% of your total image collection size. 
   More detail is available immediately below.

   \bUpgrade from a Fotoxx prior release
   Normally the index file is not affected, so that no re-indexing is required. 
   If the index file format has changed, a full re-index will be needed. You are 
   warned in this case. If your image collection is huge, and your computer is 
   slow, a long time may be needed. My relatively strong computer (core i5-13600)
   indexes at a speed of about 15000 large JPEG images per minute.

   +image: index-files1.png

   \bTop image Folders
   These are the top folders for your image files, e.g. /home/<user>/Pictures. 
   Subfolders under your top folders are automatically included, to any depth. 
   Use the [select] button to locate and add your top image folders, one or more. 
   Other files may be mixed with your image files. It may be useful to select 
   the subfolders instead of the parent (as shown above), which will give you a 
   more direct access to individual folders. A practical limit is about 30 Top 
   folders. Each may have hundreds of subfolders.

   \bThumbnails
   This is the folder where thumbnail files will be placed. These are typically 
   2% as large as your image files (30 KB compared to megabytes). You can use the 
   supplied default or choose another location. Indexing will run faster if this 
   is on separate physical storage from the image files. If you use SSD storage,
   this does not matter. 

   \bMetadata Items
   The following metadata is included in the image index by default: folder and 
   file names, photo date/time, file modification date/time, title, description, 
   rating (0-5 stars), tags (keywords for image contents), geotags (location and
   country names and latitude/longitude). Searching a large image collection for 
   one or more of these items is almost instantaneous.

   You can choose up to 10 extra metadata items to include in the image index. 
   These will also be almost instantaneous to search. You may not need this. 
   You can ignore this initially and add items later if needed. 
   For more details, see \>INDEX FILES\>.

   \bIndex Time Required
   If you have many thousands of image files, the initial index may need time. 
   The speed can range from a few hundred to a few thousand files per minute, 
   depending on processor speed, disk speed, and average file type and size:
     slow case: 1 GHz CPU, spinning disk, large files, many RAW or PNG files
     fast case: 4 GHz CPU, 4+ cores, SSD disk, small mostly JPEG files

   Here are a few real-world benchmarks. Files were mostly JPEG averaging 2.3 MB.
      \bCPU    GHz   cores   disk type          files/minute
      Intel  3.5    6      SSD PCIe           15K
      Intel  3.5    6      SSD PCIe           58K   (small jpeg ca. 0.2 MB)
      Intel  3.5    6      SSD USB-C          9.3K
      Intel  3.5    6      7200 rpm USB-C     1.5K
      Intel  3.5    6      5400 rpm USB-C     1.1K
      ARM    1.2    4      micro-SD card      0.9K 

   When you add new image files to your collection, the next Fotoxx startup will 
   index only the new files. If there are only a few new files, startup will be 
   fast. If there are many new files, startup will need time to index them, as 
   described above.

   \bRemovable Storage
   If your top image folders include folders on a removable drive, and you run 
   Fotoxx without the drive mounted, the index data and thumbnails are still 
   preserved, even though the image files have disappeared. When the removable 
   drive is mounted again, and Fotoxx is started, the last status is restored. 
   If any files were added or modified in the interim, this is detected and index 
   data and thumbnails are updated. For more details, see \>INDEX FILES\>.

   \bBlacklist Folders
   You may have some files that cannot be read by Fotoxx or one of its essential 
   tools: dcraw and exiftool. Some image files, especially from older cameras, 
   may have internal format errors or a proprietary format that depends on OEM 
   software. If Fotoxx or one of its tools crashes on such a file, there is a way 
   to move it out of the way and stop Fotoxx from trying to deal with it. Using a 
   text editor, list the file names or folder names containing the problem files. 
   Save this file with the name "blacklist" in your Fotoxx home folder, 
   e.g. /home/<user>/.fotoxx/blacklist. The character '*' may be used as a 
   wildcard that matches any number of characters. Here are some examples:
      exclude an entire folder and its subfolders: /folder/path/name/*
      exclude a single file: /folder/path/name/filename.jpg
      exclude files containing "asdfg" anywhere in the path or file name: *asdfg*
      exclude files containing "asdfg" in any folders in the path: *asdfg*/*
   Another way: move the problem files out of the declared top image folders.

   \bFotoxx home
   This is where user preferences, settings and data are kept (image files remain 
   at their original locations). The default is /home/<user>/.fotoxx (like most 
   Linux apps). If you have multiple Linux installs and want to share the same 
   Fotoxx data, you can move this to a mounted volume. See \>MOVE FOTOXX HOME\>. 
   If multiple users have access to the same image files, each can have their own 
   Fotoxx home for preferences and settings, and the image files can be in a 
   shared folder not under a /home/<user>/ folder. 

USER GUIDE
   +image: userguide.jpg
   Open the user guide from the menu Help > User Guide. While using Fotoxx, you 
   can press the F1 key to see the User Guide topic for the current menu function
   or the function most recently used.

   The [home] key jumps to the top (table of contents). The [end] key jumps to 
   the end (alphabetical index). To scroll the text, use arrow-up/down and 
   page-up/down keys. The [Find] button opens a dialog for a text search. Enter 
   the desired text and press the [Find] button in this same dialog. Press again 
   for the next occurrence. The keyboard 'F' key also opens the search dialog.

   Underlined text is a clickable link to a topic, e.g. \>INDEX FILES\>. Use the 
   keyboard left/right arrow keys or the buttons [<] and [>] to go back and forth 
   between topics most recently viewed. The button [Recent] presents a list of 
   most recently viewed topics. Click on a topic to go there.

   \>INDEX FILES\> <-- click this text and then press [<] to see what happens.

   Web links (\_https://...\_) can be clicked to view the web page using your 
   web browser.

WINDOW VIEWS AND MENUS
   +image: fotoxx-views.jpg
   \bMenu Buttons
   The icons in the left side panel are menus. When one is clicked, a popup menu 
   appears. These are functions for image viewing and editing, searching, reports 
   and utilities. The top three menus (File, Gallery, Maps) set the corresponding 
   view mode if not already set. The keyboard keys F2/F3/F4 can also be used.

FILE VIEW
   File View is for viewing or editing an image. To zoom an image, left-click a 
   position on the image. The image will grow with each click and the clicked 
   position will move to center. A right-click will restore the image to fit 
   within the window. The Z-key can also be used to alternate between fit-window 
   and 1x image size (1 image pixel is 1 monitor pixel). To pan or scroll a 
   zoomed image, left-drag the mouse across the image. The image can move with 
   the mouse or in the opposite direction (like scroll bars), depending on a user
   setting (see \>SETTINGS\>). The movement may be 1:1 with the mouse, or may be 
   magnified for faster movement. The mouse wheel can also zoom an image in or 
   out. Use the menu buttons (Edit, Refine, etc.) to modify the image. Use the 
   File Save button to save a modified file: replace the file, create a new file
   version, or create a new file (new file name).

   \bKeyboard Navigation Options
   The keyboard arrow keys can be used to step sequentially through the image 
   files in a gallery.
   left/right arrow keys:
      View the previous or next image file in the current gallery. If you reach 
      the start or end of the gallery, a popup message indicates this. You cannot 
      go further.
   up/down arrow keys:
      View only the last version of each image file. This is the original file if 
      no versions exist. If you reach the gallery start or end, a popup message 
      indicates this. You can proceed to the previous or next gallery by pressing 
      the key again. The UP key goes backwards, the DOWN forwards (next file or 
      gallery).

GALLERY VIEW
   All image files in the current folder are shown as thumbnails. This may be 
   hundreds or thousands of images. You can scroll through the thumbnails and 
   navigate to other folders. Use the vertical scroll bar to scroll up and down 
   within a gallery. The keyboard keys can also be used: the arrow up/down keys 
   scroll rows, the page up/down keys scroll pages, and the home and end keys 
   jump to the beginning (top) and end (bottom) of the gallery. You can also 
   scroll the gallery up/down with the mouse wheel. Use the \>ZOOM\> menu button 
   or the keyboard [+] and [–] keys to change the thumbnail size. Clicking on a 
   thumbnail will change to File View and display the image full size. This image 
   is now the "current image". Pressing the F3 key or the 'gallery' menu button 
   will return to Gallery View, with the current image scrolled to the top row. 
   The folder path is shown at the top of the gallery window, with one button per 
   folder level. Click on a folder button to show a gallery for that folder. 
   Its subfolders will be shown as folder thumbnails. Click one of them to show 
   a gallery for that folder. Click the [TOP] button to choose another top image 
   folder, the root folder ( / ), your home folder, your Desktop folder, a 
   gallery of the most recently viewed images, or a gallery of the newest images
   (most recent images added or modified).

   There are several types of galleries:
      • Folder: all the image files in a single folder
      • Images in an Album: an arbitrary collection from various folders
      • Recent Files: the most recently viewed or edited image files
      • Newest Files: image files most recently added or modified
      • Report output: thumbnail images with associated text (metadata)
      • search_results: images found by the Search function. Also an album.

   The gallery window title bar will show the folder name (path), the album name, 
   or "Recent Files" or "Newest Files". If the gallery corresponds to a folder, 
   buttons for navigating to its parent folders are shown in the top panel. The 
   other gallery types have only the buttons for Album (select an album) and TOP 
   (select a top image folder).

   A gallery thumbnail has a right-click menu with some commonly used functions. 
   One of these is Popup Image, which creates a popup window with a larger image 
   that can be rapidly zoomed to any size with the mouse wheel. Multiple popup 
   windows can be open at once. This is useful for comparing multiple photos or 
   multiple edited versions.

   Popup Image Manipulation:
      • Click thumbnail with middle mouse button: popup image appears
      • Click thumbnail with shift + left mouse button: popup image appears
      • Mouse scroll wheel: zoom the popup image bigger or smaller
      • Key F11: make popup image full screen, or return to prior size
      • Left mouse button: close the popup image
      • Escape key: close the popup image

MAP VIEW
   View maps containing markers corresponding to image locations. Click on a 
   marker for a Gallery View of the corresponding images. This depends on your 
   image files having embedded geotag data (latitude, longitude). Modern cameras 
   insert this automatically, and you can also add this data yourself. Two types 
   of maps are available. The better option is Net Map, a scalable internet map 
   that can be zoomed from street level to continental level. If your internet 
   connection is poor, you can use the File Map menu. These are downloaded map 
   files of countries and continents having limited zoom range. You can also 
   add custom maps at any scale (city, park, campus, region, country ...).

   The Net Map option uses a world map from an internet service. Initially a 
   world map is displayed. Use the mouse wheel to zoom-in/out at any location. 
   Left/right mouse clicks also zoom in and out. Shift the map center using mouse 
   drag. The entire world can be viewed at any scale down to street-level.

   File maps are locally stored data files containing map images. A set of maps 
   for the world, all continents, and many countries can be downloaded and 
   installed using the Download Maps menu. Use the Choose Map menu to select a 
   map file. A left click on any map 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. Markers are shown where there are any images with geotags. 
   Clicking a marker shows a Gallery View of corresponding images.

MENU SUMMARY
   +image: menu-summary.jpg
   The image above is an overview of the functions available in each menu group. 
   A left-click on a menu icon has two functions: set the corresponding view if 
   not already current, or show a popup menu with all of the functions for this 
   menu group. Some menu functions will work independently of the current view 
   mode, or will change the view mode as needed.

DRAG AND DROP
   Fotoxx accepts drag-drop of image files to File View or Gallery View. In File 
   View, the file is opened. In Gallery View, the result depends on the type of 
   gallery. If the gallery is a folder, the file is added to the folder and the 
   gallery will show the new file in its sorted position. If the gallery is an 
   album, the file is added to the album in the position where it is dropped. 
   This works also if a text string that is a valid image file name is dropped.

EDIT PROCEDURES
   The image in File View mode (the current image) can be modified with the edit 
   functions in the menus Edit, Repair, Refine, Effects, Warp and Combine. These 
   functions modify the current image in memory and in the window. You can use 
   these functions in any order, and edits are accumulated. When you are finished
   editing, use the [Save] menu button to save the modified image back to the 
   same file, to a new file version (e.g. filename.v01.jpg), or to a new file 
   name and/or folder. Image edit dialogs have sliders, buttons, spin buttons, 
   or editable curves that immediately update the image. The response time to
   display the updated image depends on the size of the image, the complexity of 
   the function and the speed of your Computer. This is typically less than a 
   second for most edit functions on a strong computer. 

   Left or right click the Undo/Redo button to undo or redo the currently active 
   edit function. After an image has had one or more edits applied, the undo/redo 
   button can be used to step back and forth through all the completed steps to 
   view the image status after each step. The middle mouse button shows a popup 
   list of all edits done to the current image, and you can select any step to go 
   back to. The image can be re-edited from any prior step. This will discard 
   edits done after this step, since they are dependent on this step. Re-applying 
   the same edits is sometimes facilitated because the settings used in prior 
   edits are often used as a starting point. This undo/redo capability remains as 
   long as the edited image remains as the current image. If another image is 
   opened, the edit history is discarded.

EDIT WORKFLOW
   You can speed the editing of multiple photos/images if you understand the 
   following rules and methods:
      • Choosing a new edit function automatically completes an active edit. 
        The new edit starts with the 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 (replace, new version, or new file). The edit function 
        restarts, and an undo/redo position is created.
      • Some frequently used functions have a [Prev] button to recall previous 
        settings, making it easier to process multiple photos needing similar 
        adjustments.

   Here is an example workflow for the initial rotate and crop of a new batch of 
   photos. You can process one photo every few seconds (+ think time).
      1. Go to the folder with the new photos to process.
      2. Open the first file.
      3. Menu: Edit > Rotate - upright (±90°) or level image by dragging the edge
      4. Press [crop] button, crop image margins by dragging edges
      5. Press [Save] button and choose "new version".
      6. Press [Prev/Next] button (right click) to edit the next file. 
         Press again to skip over the file.
      Repeat steps 3-6 for each image.

   \bSimple 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 visible image quality.

   \bComplex Workflow
   To edit with deep color (over 8 bits), start with the camera RAW file.
   There are two options for processing RAW files:
      • Click the RAW file gallery thumbnail. The RAW file may now be edited like 
        any other image file. Fotoxx edit functions work with 24 bits per color, 
        so whatever bit depth the RAW file has will be preserved. Save the edited 
        file as type TIFF or PNG with 8 or 16-bit color, or JPEG with 8 bits. 
        You cannot save the edited image as a RAW file type. Opening a RAW file 
        may need several seconds, especially on a slow computer. Saving an image 
        as TIFF or PNG is also slower than JPEG.
      • Use the menu Batch > Batch RAW. 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 bits. You may then select and edit these files as needed with Fotoxx.
   Fotoxx can do most things you can do with a RAW editor. The key is to start 
   with the RAW file or a derived file with 16-bit color depth, so that nothing 
   is lost. When you open a RAW file in Fotoxx, the chosen RAW loader is used
   with parameters you can change (see \>SETTINGS\>). 

   RAW files may have more color depth than 8 bits, especially if the camera is 
   new and expensive. Converting into a PNG or TIFF file with 16-bit color will 
   preserve whatever color depth is available in the RAW file. The higher color 
   depth reduces the risk of visible color bands if your edits radically shift 
   the brightness distribution. When finished editing, convert the final file to 
   JPEG (quality level 70 or greater) to reduce the final file size to 10% or 
   less. Note that editing in deep color is far more important than having deep
   color in the final image. It is nearly impossible to see a difference between 
   a 16-bit TIFF or PNG file and a quality JPEG made from that same file. To 
   preserve the ability to re-editing the image later, keep the RAW file, which 
   is usually much smaller than the TIFF or PNG file.
   
   Dcraw is the default RAW file loader. You can also use a more complex RAW 
   editor like Raw Therapee if you prefer (see \>SETTINGS\>). Dcraw is simple and 
   fast in comparison. The many options in a RAW editor can usually be done more 
   easily with Fotoxx edits.

MOUSE OWNERSHIP
   Some edit 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 an edit dialog. Therefore it is important to understand who owns 
   the mouse (which dialog or main window) and how to change the ownership:
      • For dialogs using the mouse on the image (to paint, select area ...), 
        the mouse is owned by the dialog that was last used and now retains KB 
        focus. Mouse actions 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 on the 
        image, the image will zoom or pan/scroll. Dialogs are not affected.
      • The mouse wheel can always be used to zoom-in/out any part of the image 
        as long as the mouse is on the image and not on a dialog widget (which 
        may be modified by the mouse wheel). 

MOUSE ALTERNATE RIGHT-BUTTON
   For touchpads and touchscreens, some right-mouse functions are missing or 
   clumsy, e.g. right-drag is sometimes missing. If the ALT key is held while 
   pressing the left mouse button, this is interpreted as the right mouse button.

DIALOG BUTTONS
   These mostly work as follows:
     [Reset]     undo changes, return to initial status
     [Apply]     apply settings from dialog to image, leave dialog active
     [Done]      same as [Apply], but the dialog is closed
     [OK]        same as [Done]
     [Cancel]    discard image changes and close the dialog
     [Proceed]   proceed with lengthy task based on dialog inputs

KEYBOARD ENTER KEY
   Many applications handle this key as 'done', meaning that input is complete 
   and the function can be executed. Fotoxx does NOT follow this convention.
   The Enter key action depends on which dialog widget has keyboard focus:
      • text entry (single line) - input is finished.
      • text entry (multi-line) - a new text input line is started.
      • number entry - input is finished.
      • check box - toggle status between 'checked' and 'not checked'.
      • button - the button is pressed, equivalent to a clicking the button.

KEYBOARD ESCAPE KEY
   This key has multiple uses. It affects only the window that has current 
   keyboard focus. This can be the main Fotoxx window or a dialog window. Before 
   using the escape key, note which window has focus and change this if needed.
      • main window has focus:
         • if a long-running function is still running, terminate it
         • if the main window is maximized (full screen), reinstate prior size
         • if the current view mode is gallery or map, change to file view mode
         • none of the above: exit Fotoxx
      • dialog window has focus: kill the dialog (same as [x] button)
      • others: cancel popup image, exit 360 panorama viewer, hide the User Guide 
        window, interrupt or exit Slide Show.

CUSTOM DIALOG WIDGETS
   +image: custom-widgets.png
   Some non-standard widgets are used to reduce dialog size or improve the ease 
   of use. They work almost like standard GTK widgets. The numeric data widget 
   works like a GTK spin-button: the mouse wheel and keyboard up/down arrow keys 
   can be used to rapidly run the value up or down. If using a touchpad, tap the 
   entry to position the cursor, then use the keyboard to enter a value, or use 
   the keyboard up/down arrow keys to rapidly index to a new value. If the key is
   held down, the change rate accelerates over time. The shift key can be used to 
   increase the change rate by 10x. The nonlinear slider expands the scale around 
   the neutral value, so that small changes can be controlled more precisely, 
   especially with a touchpad. A few standard GTK widgets have been reduced in 
   size by removing excess padding. This is controlled by the file 'widgets.css' 
   in the fotoxx home folder. You can modify this file if desired. You can delete
   items or mark them as comments, but do not delete the file, since it will be 
   automatically replaced.

CURVE EDITING
   +image: retouch.png
   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 curve to change brightness depending on brightness (e.g. 
   brighten dark areas without changing bright areas). Generally, the curve 
   X-axis is 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 PROCESSING
   There are several batch functions in the \>BATCH MENU\> to speed some common 
   tasks. You can select many image files and execute the batch function for all 
   of them. Batch functions can be used for the following tasks:
      • Rename files and add sequence numbers or photo dates to the names
      • Convert file types (e.g. .png to .jpeg)
      • Find and upright photos made with the camera turned 90 degrees
      • Rescale 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 image tags or geotags
      • Report or revise metadata items
      • Set image dates/times or shift times to change the time zone
      • Delete files or move them to Trash
      • Script Files: perform multiple edits on one file, save as a script file
        which can then be applied to any number of files in batch mode.
      • Find duplicate image files.

SELECT IMAGE FILES
   +image: select-image-files.jpg
   This procedure is used for all functions operating on multiple image files:
      • batch functions - rescale, rename, add tags, convert ...
      • scripts - perform a predefined set of edits on one or more image files
      • albums - create and edit image collections

   The procedure is explained here, and this topic is linked from each of the 
   functions using the procedure.

   Selected files are added to a list by clicking on gallery thumbnails. 
   The example shows a gallery and a list of files selected from the gallery.
      • add new files to the list: left-click gallery thumbnails
      • add a group of files: click first thumbnail, shift-click last thumbnail
      • add all images in the gallery to the list: press the [Add All] button
      • add the current image to the list: press the [Add Current] button
      • a file may be added multiple times to the list
      • you can navigate to other galleries to select more files as needed
      • delete a file from the list, 2 methods:
         • right-click the file's gallery thumbnail
         • click a list position and press the [Remove] button
      • clear the list: press the [clear] button
      • use KB up/down arrow keys to step through the list and view thumbnails
      • the KB page up/down and home/end keys also work

   The [Disable] button will disable thumbnail clicking to select files. The 
   button is then renamed to [Enable] - press to restore thumbnail clicking. The 
   purpose of this is to enable the normal thumbnail popup menus and left-click 
   to view a file at full size (not available while thumbnail clicks are being 
   used for file selection). You may need these functions during the screening 
   process for selecting files. You can stay in file view mode and index through 
   the images using the arrow keys, while using the [Add Current] button to add 
   files to the selection list.

POPUP REPORTS
   Text reports are shown in a popup text window. Some of these have clickable 
   report lines that trigger actions, e.g. a list of location names that can be 
   clicked to show a gallery of images for the selected location. These reports 
   can be navigated with the keyboard arrow keys, page keys, and home/end keys.

MENU SHORTCUTS
   Fotoxx menus are large. You may need time to get used to them and remember 
   where functions are located. 
   There are three shortcut methods 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 below. You can change the 
        shortcut keys and add shortcuts for functions you choose.
      • Custom menu - collect frequently used functions in one menu. 
        See \>CUSTOM MENU\>.

COLLECTION MANAGEMENT
   You can use Fotoxx to manage a huge image collection and still be able to 
   quickly find wanted images. Some effort to organize your images is required. 
   Search methods include folder and file names or partial names, photo dates, 
   file dates, ratings, tags (labels for persons, places, objects, events ...),
   words found in titles and descriptions, location names and latitude/longitude). 
   Any available image metadata can be used for image searching. Options for how 
   to organize a large collection are explained the topic \>ORGANIZING IMAGES\>.

RIGHT-CLICK MENUS
   Popup menus appear when an image or gallery thumbnail is right-clicked. Most 
   of these functions are also contained in the main menus for File View and 
   Gallery View. The popup menus are shorter and faster to use for the functions 
   they contain.

   \bFile View popup menu
   Right click on current image in File View mode to get the following menu:
      • View Meta - Show short form metadata report
      • View All Meta - Show all available metadata
      • Edit Meta - Edit key metadata items: photo date/time, rating, tags ...
      • Rename - Change the file name
      • Delete/Trash - Delete the image file or move it to the wastebasket
      • Copy/Move - Copy or move the image file to another location (folder)
      • Copy to Desktop - Copy the image file to the desktop window
      • Copy to Clipboard - Copy the image file to the clipboard
      • Rotate - level the image or turn 90 degrees
      • Crop - Trim image margins
      • Retouch - Adjust brightness, color, contrast, saturation, white balance
      • Rescale - Rescale the image pixel width and height
      • Sharpen - Sharpen a blurred image, multiple methods
      • Blur - Blur the image, multiple methods
      • Denoise - Filter noise from low-light photos
      • Voodoo 1 / Voodoo 2 - Limited automatic image enhancement methods
      • Edit Dist - Edit the brightness distribution (histogram shape)
      • Flatten Distribution - increase contrast and lighten shadows
      • Local Contrast - add contrast adjusted for brightness of local area
      • Gradients - Increase contrast and perceived brightness range
      • Saturation - Adjust color saturation, optionally based on brightness

   \bGallery View popup menu
   Right click on thumbnail image to get the following menu:
      • Popup Image - Show image in a new window - zoomable, movable, persistent.
        Zoom in/out using the mouse wheel. When zoomed small, it disappears.
      • View Meta - Show short form metadata report
      • View All Meta - Show all available metadata
      • Edit Meta - Edit key metadata items: photo date/time, rating, tags ...
      • Rename - Change the file name
      • Delete/Trash - Delete the image file or move it to the wastebasket
      • Copy/Move - Copy or move the image file to another location (folder)
      • Copy to Desktop - Copy the image file to the desktop window
      • Copy to Clipboard - Copy the image file to the clipboard

   Album galleries have the following menu additions:
      • Add Selected Files Here - insert previously selected files at the 
        clicked thumbnail position
      • Add Current File Here - insert current (last viewed) file at the 
        clicked thumbnail position
      • Remove from Album - remove this image file from the album

   VIDEO files have the following menu addition:
      • Thumbnail Frame - select thumbnail frame (at minutes/seconds position)

KEYBOARD SHORTCUTS
   Keyboard shortcuts are available for most menu functions. Use the menu 
   Tools > KB Shortcuts to view or change them. The notation "Ctrl+X" means 
   press and hold the Ctrl key, then press the X key.

   The following keyboard functions are fixed and cannot be changed:
      • K key          KB Shortcuts - dialog to view or change shortcuts
      • [+] [=] key    Zoom image or thumbnails larger
      • [-] key        Zoom image or thumbnails smaller
      • Z key          Toggle image between 1x (full size) and fit to window
      • F1 key         Display user guide for current or prior function
      • F2/F3/F4 key   Change to File/Gallery/Map view mode
      • F10 key        Toggle main window full-screen and back
      • F11 key        Same as F10, without menus, title bar and top panel
      • Escape key     Kill running function, Exit active dialog
      • Arrow ←/→      Show previous/next image file in current gallery
      • Arrow ↑/↓      File view: like ←/→ but show only last file versions
                       Gallery view: scroll 1 row up/down, hold for slow scroll
                       Report: scroll report up/down one row at a time
      • Page Up/Down   Gallery view: scroll 1 page up/down, hold for fast scroll
                       Report: scroll report up/down one page at a time
      • Home/End       Gallery view: go to first/last page in gallery
                       Report: go to report start/end

NUMERIC KEYPAD
   +image: number-keys.png
   The numeric keypad can be used for navigation with or without 'num-lock'.
   Thes following keys have the same function as in Keyboard Shortcuts above:
      [+] [-]  Arrow ←/→  Arrow ↑/↓  Page Up/Down  Home/End

MOUSE FUNCTIONS
   File View
      • left click - Zoom-in: magnify image, center at click position
      • right click - If image is zoomed: restore to window size
                      If not, popup menu with common functions
      • mouse wheel - Zoom image in or out depending on wheel direction
      • left drag image - Pan/scroll zoomed image, same or magnified opposite 
                          direction (like scroll bars - see \>SETTINGS\>)
      • mouse + Ctrl key - Mouse acts on main window instead of active dialog

   Gallery View
      • left click thumbnail - Change to File View, show full-size image
      • right click thumbnail - Show popup menu with common functions
      • middle click thumbnail - Pop up image in new zoomable window
      • scroll mouse wheel - Scroll the gallery page up or down

   Map View
      • left click - Zoom map larger at clicked location
      • right click - Zoom map smaller
      • left drag - Drag map, following the mouse
      • mouse wheel - Zoom map larger or smaller
      • left click on marker - Show gallery of all images at marker location

   Text reports and User Guide - text can be selected and copied to the clipboard 
   in the usual manner (AKA copy and paste).

COMMAND PARAMETERS
   The following parameters can be used if Fotoxx is started from a terminal
   using the command  $ fotoxx:
   \blong       short  params    description
   -help       -h              show user guide
   -album      -a              "album name"   initial album (gallery) to open
   -ver        -v              output release version and exit
   -recent     -r              show a gallery of recently seen image files
   -new        -n              show a gallery of the newest image files
   -prev       -p              show the last file viewed in the previous session
   -blank      -b              show a blank window
   -cwp              N name    cycle wallpaper every N secs, album or folder name
   -x0 -x1 -x2                 set index level to 0, 1, or 2 (see below)
   -menu       -m    "menu"    Fotoxx will start with this menu function active
   -devmenu    -d              show normally hidden developer menu
   -home             /folder   alternate Fotoxx home location (see below)

   \b-x0 -x1 -x2  parameter\b  (set index level at startup)
   These parameters can be used to override the value in \>SETTINGS\>.
      -x0   no index - very fast startup with reduced functionality
      -x1   use existing index - fast startup omitting new/modified image files
      -x2   use existing index + find and include new/modified image files

   Note: the first Fotoxx startup after a reboot may be slow if your image 
   collection is very large. Subsequent startups will be faster since folders are 
   now cached in memory. For very fast startup, you can bypass indexing entirely 
   with the command "fotoxx -x0", or by setting the image index level = 0 in 
   \>SETTINGS\>. Search and map functions will be disabled until you allow the 
   indexing to complete normally. See also the topix \>INDEX FILES\>.

   \b-home\b  parameter  (alternate Fotoxx home folder)
   The default location for 'fotoxx home' is: /home/<user>/.fotoxx. This is where 
   user preferences and settings are kept (tag names, bookmarks, defaults ...). 
   Image index data is also kept here. The command "fotoxx -home <foldername>" 
   expects 'fotoxx home' to be in the designated folder. This enables multiple 
   image collections to be managed separately. If Fotoxx is started for the first 
   time with a new -home parameter, the initial file indexing process will begin. 
   You can avoid this by copying the files in /home/<user>/.fotoxx  to the new 
   home folder before starting fotoxx with the new -home parameter. 
   See \>MOVE FOTOXX HOME\>.

   \b-cwp\b  parameter  (cycle desktop wallpaper)
   The full command line is: $ fotoxx -cwp secs container
   This command can be used to cycle the desktop wallpaper using a set of images 
   from a Fotoxx album or any folder containing image files. 'secs' is the 
   interval in seconds between images. 'container' is either a Fotoxx album name 
   or the path name of a folder containing image files (name begins with '/'). 
   Use this command in your log-in startup list to get a new wallpaper at 
   specified intervals. Use an interval of a day or more to get a new wallpapr 
   image with each log-in. The last image used is remembered, and each startup 
   begins with the next image in the sequence. The last image is followed by the 
   first image. If 'secs' is zero, one wallpaper update will be made and Fotoxx 
   will then exit.

TOP PANEL DATA
   +image: top-panel.png
   The top panel has status information about Fotoxx and the current image file.
   The following strings can be present, in approximately the following order:
      2866x1917x8       current image width x height x depth (bits per color)
      41%               zoom status, image % size (window pixels / image pixels)
      edits: 2          current edits, reversible with the [undo/redo] button
      blocked           some functions are blocked until current function is done
      area active       edits are confined within the active selected area
      dialog open       a dialog is waiting for user input
      working 45%       some long-running functions show this progress indicator

   \bBit Depth\b
   This shows the bits per channel (RGB color) of the current file. This is 8 
   bits for JPEG, and 8 or 16 bits for PNG or TIFF. If you opened a RAW file, 
   the actual value recorded in the RAW file EXIF data is shown. Common values 
   are 8/12/14/16 bits. When a RAW file is edited, this is done in 24-bit 
   precision, regardless of the bit depth of the input file.


FILE MENU

+image: ug-file.png

NEW SESSION
   Start a new Fotoxx session in a new window. 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 session will initially have an unmodified version of the 
   current image file. If the same image file is edited in both windows, neither 
   instance will see the changes made by the other, and the final result is the 
   last file saved.

OPEN IMAGE FILE
   Select an image file to view or edit, using a conventional file open dialog
   with folders and lists of files. Click on a file name to select and open. 
   Unlike normal usage for Fotoxx, no thumbnail gallery is displayed. This is 
   useful for the case where files are not indexed and gallery display is very 
   slow, e.g. reading from a camera SD card containing thousands of image files.

IMAGE FOLDER
   Replace the current gallery (Recent Files, search_results ...) with the folder 
   of the current image file shown in the File View window. The default shortcut 
   key is [S].

CYCLE 2
   Open the previously opened image file. Repeating this menu will alternate 
   between the two most recently opened files. 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 the area to compare, and use this function 
   to alternate between the two images. The default keyboard shortcut is key [2].

CYCLE 3
   This works the same way as Cycle 2, but alternating the last 3 opened files.
   The default keyboard shortcut is key [3].

VIEW 360° PANO
   The current file is opened with a special viewer for 360° panorama files. 
   The image width is assumed to be 360°. Use this function to view Google 
   'photosphere' images. Use the mouse and keyboard to control the view:
      • Mouse-drag: pan horizontally 360° and wrap-around at the ends
      • Left and right arrow keys also pan the image horizontally
      • Left and right mouse-click will zoom-in and zoom-out
      • Use Escape to exit the special viewer
   Panoramas with less than 360° can also be viewed, and the two ends will 
   wrap-around regardless.

RENAME
   +image: rename.png
   Rename the current file (File View), or the file of a clicked thumbnail 
   (Gallery View). Enter a new name and press [apply]. This function can also 
   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. File version 
   numbers (.vNN) are not copied and are otherwise not affected.

PERMISSIONS
   +image: permissions.png
   The permissions of the current file (File View), or the file of a clicked 
   thumbnail (Gallery View), are shown in the dialog. Use the [Change] button to 
   revise the permissions data in the dialog, and the [Apply] button to change 
   the permissions of the named file. You can use the arrow keys to navigate to 
   new files in the same neighborhood, and the data in the dialog will be updated. 
   The three permissions shown are for the owner of the file, members of the 
   owner's group, and others. An explanation of Linux permissions can be found 
   in the man page for the "chmod" command.

CHANGE ALPHA
   +image: change-alpha.png
   The dialog shows whether or not the current image file has an alpha channel, 
   containing pixel transparency values. If an alpha channel is present, the 
   [remove] button will remove it. There is no new version - the current file is 
   updated on disk. The opacity values in the alpha channel are applied to the 
   RGB values before the alpha channel is removed: RGB values are multiplied by 
   the alpha value / 255. Completely transparent areas are made black (RGB 0), 
   and partly transparent areas will become darker. If no alpha channel is 
   present, the [add] button will add one, with all values = 255 (fully opaque). 

BLANK IMAGE
   +image: blank-image.png
   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 \>MARKUP\> draw text). Input a file name, choose a 
   background color, and set the desired pixel dimensions. See also \>MASHUP\>.

COPY/MOVE
   +image: copy-move.png
   The current file (File View) or the file of a clicked thumbnail (Gallery View) 
   is copied to the given location. This location can be entered directly or 
   chosen by a file open dialog if the [browse] button is used. Select the copy 
   option to copy the file and leave the source file in place, creating a 
   duplicate. Select the move option to move the file from the original location 
   to the new location. A group of files can be rapidly processed by clicking 
   each thumbnail followed by [apply]. The [Prev] button can be used to copy the 
   previously used file name. Add a version number or something else to avoid a 
   duplicate file name. 

COPY TO DESKTOP
   The current file (File View) or the file of a clicked thumbnail (Gallery View)
   is copied to the desktop folder (/home/<user>/Desktop).

COPY TO CLIPBOARD
   The current file (File View) or the file of a clicked thumbnail (Gallery View) 
   is copied to the clipboard, from which other applications can paste.

DELETE/TRASH
   +image: delete-trash.png
   The current file (File View) or the file of a clicked thumbnail (Gallery View) 
   is deleted or moved to trash, depending on the option selected. Fotoxx assumes 
   the standard for trash (~/.local/share/Trash). Because GTK cannot trash files 
   on mounted volumes, files are moved to ~/Desktop first, and then to trash. 
   If such a file is restored from trash, it will show up on the desktop. If you 
   have multiple files to remove, you can leave the dialog open to speed the 
   process. If another file is opened, the file name in the dialog is updated.
   In Gallery View, if another thumbnail is clicked, the dialog is updated.

CONVERT ADOBE
   A file open dialog can be used to find and open an Adobe file of type .pdf 
   .ps .eps or .psd. Convert an Adobe document file (.pdf .ps .eps) into a set 
   of jpeg image files, one per document page. The output file names have the 
   input file name with the page number appended: filename-N.jpg. Output file 
   pixel size depends on the 'paper size' of the document file (e.g. US Letter: 
   2479 x 3508). The program 'ghostscript' must be installed. Photoshop image 
   files (.psd) can be converted to .jpg, one output file with the same root 
   name as the input file, and the same pixel size. The program 'imagemagick' 
   must be installed.

SET WALLPAPER
   The desktop wallpaper is set from the current file.
   NOTE: this is Gnome specific and may not work for other desktop systems.

SHOW ON MAP
   Change to Net Map View and show the location of the current image.
   The map may need time show up, depending on internet response time.

PRINT
   +image: print-setup.png  +image: print-margins.png
   The print menu brings up a standard Page Setup dialog where you can select 
   a printer, a paper size, and orientation. After using the [apply] button, 
   another dialog starts for entering paper margins and 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) is updated in the dialog as 
   margins and scale are changed, and this can be used to reach a desired print 
   image size. After the margins dialog, a Print dialog starts for the actual 
   printing. This includes paper type and quality inputs, and a preview of the 
   printed layout which can be accepted or rejected. If grid lines are shown on 
   the image, the printed image will also have the grid lines, although much 
   thinner.

PRINT CALIBRATED
   This function works like Print Image File described above, but before printing 
   you are asked to supply a calibration file name which is used to adjust image 
   colors prior to printing. The purpose is to compensate for color distortions 
   caused by the printer. See the topic \>CALIBRATE PRINTER\> for details on how 
   to create a calibration file.

QUIT
   +image: quit.png
   This is used to exit Fotoxx. A popup dialog will ask for confirmation if this 
   option was selected in \>SETTINGS\>. To exit Fotoxx, press the [Yes] button or 
   the 'Y' key or the Enter key. To continue Fotoxx, press the [No] button or the 
   'N' key or Escape. If there are unsaved file changes, or if a long-running 
   function is still running, you are warned and given the chance to cancel or 
   quit anyway.


GALLERY MENU

+image: ug-gallery.png

GALLERY OVERVIEW
   +image: image-management.png
   A gallery of thumbnail images can represent a file folder, the output of an 
   image search, one of the built-in galleries (recent files, newest files), or 
   an album (an ordered list of image files with a given name). Folders should be 
   limited to a few thousand files for practical and performance reasons, but no 
   limit is enforced. A scrolling gallery window is limited to 7 million pixels 
   high (internal GTK limit). If 'normal' thumbnails are used (256x256) and if 
   there are six thumbnails per row, about 140K files can fit in the window.

   \bScrolling the Gallery
   The gallery can be scrolled up and down using the keyboard up and down arrow 
   keys or page-up and page-down keys. [home] and [end] keys may also be used. 
   Use the right-side scroll bar to move rapidly to any position. Left-click and 
   hold on the scroll bar, over or under the scroll button, and the gallery will 
   scroll rapidly to the click position. Right click and hold on the scroll bar 
   to make the gallery scroll slowly to the click position. Continue holding the 
   mouse button and move to the side to increase the scroll speed.

THUMB VIEW
   +image: gallery-view.jpg
   Image files in the current gallery are shown as an array of thumbnails. The 
   text is limited to file name, date, and size. Size is in pixel width and 
   height if the current thumbnail size is small, and the MB size is added if 
   the thumbnails are larger and more space is available. Use the zoom button 
   \>ZOOM\> to change the thumbnail size.

META VIEW
   +image: meta-view.jpg
   Image files in the current gallery are shown together with the basic metadata 
   used by Fotoxx. If custom indexed metadata items are present, these are shown 
   following the standard items.

RECENT FILES
   The 1000 most recently seen image files (viewed or edited) are shown in a 
   gallery, from which you can select files to view or edit. To replace the 
   recent files gallery with the folder of a chosen file, use the function 
   \>IMAGE FOLDER\>.

NEWEST FILES
   The 1000 most recently added or modified image files are shown in a gallery, 
   from which you can select files to view or edit. You are given a choice of 
   using the EXIF photo date or the file modification date to determine newest 
   images. If the EXIF date is chosen, image files that have no EXIF date are 
   ignored. To replace the newest files gallery with the folder of a chosen file, 
   use the function \>IMAGE FOLDER\>.

GALLERY SORT
   +image: gallery-sort.png
   Choose the sort key and ascending or descending order. 
   The Reset checkbox resets all galleries to file name ascending.

   If an Album gallery is sorted, the output does not replace the album but  
   creates a new album named "albumname-sorted". This is done because albums have 
   an order established by the user when image files are added. If sorted, there 
   would be no automatic way to put it back in the original order.

   Folder galleries retain their sort order and scroll position when viewed later
   (i.e. when other galleries are viewed in-between).

   \_File Name/Number
   This is a modified sort by file name. If multiple files have names that differ 
   only by embedded numbers in the same position, this group of files will be 
   sorted in the order of the embedded numbers. The example here illustrates the 
   difference:
      alphabetic order: abc1xx abc11xx abc123xx abc3xx
         numeric order: abc1xx abc3xx abc11xx abc123xx

   \_Metadata from Search Function
   If the gallery was generated by the \>SEARCH IMAGES\> 'metadata report' 
   option, and if you added optional metadata items to the standard report, you 
   can sort the gallery by these metadata items. You can sort the gallery by 
   camera make, lens info, ISO level, exposure time ... any available metadata.

GALLERY SCREEN
   +image: gallery-screen.png
   Select a simple subset of the current gallery and create an album named
   "gallery_screen" containing the selected image files. Selection options:
     - select oldest versions only (original or oldest version available)
     - select newest versions only (or original if no versions available)
     - select images than have been edited (newest version available)
     - select images that have not been edited (no versions exist)
     - include images with a given name or partial name (substring)
     - exclude images with a given name or partial name (substring)
     - some combination of the above
   If "oldest version" is checked, only original images or the oldest existing 
   versions (if original missing) are selected. If "newest version" is checked, 
   only newest versions are selected (or the original if there are no versions). 
   If both are checked, you will get the original (or oldest version) and newest 
   version. If "edited" is checked, you will get only the last version of files 
   that have been edited (versions exist). If "unedited" is checked, you will get 
   the original files that have not been edited (no versions exist). This cannot 
   be used in combination with "oldest" or "newest". If "include" is checked and 
   a corresponding text string is entered, only image files containing this text 
   in the base file name are selected (folder names are ignored). If "exclude" 
   is checked and a corresponding text string is entered, matching files will be 
   omitted. See also \>SEARCH IMAGES\> for a more complete (and complex) image 
   search tool.

GALLERY HOME
GALLERY END
   Jump to the first or last thumbnail in the current gallery.

IMAGE FOLDER
   This is a duplicate of the \>IMAGE FOLDER\> function in File View.

FOLDER TREE
   +image: folder-tree.png
   All top image folders are shown initially. Click on [+] to unfold subfolders, 
   or on [-] to fold them back in. You can click on any folder to get a gallery 
   of the images in that folder. Keep the window open to navigate anywhere in 
   your image collection. This function is also available using the [TOP] button 
   in the gallery top panel.

SELECT FILES
   Pre-select image files for use as inputs for creating albums or for batch 
   functions or script functions. These functions will use the pre-selected files 
   by default, but they also allow the selection to be modified or done over. The 
   procedure for selecting files is described in the topic \>SELECT IMAGE FILES\>.

RENAME FOLDER
   +image: rename-folder.png
   The current folder (image gallery) is renamed. This must be a file gallery, 
   not an album, search result, etc. After renaming, the \>INDEX FILES\> function 
   is started, to update the Fotoxx image index for the image files contained in 
   the renamed folder. This could take some time if the number of files is great. 
   All albums are also updated for the revised folder names.

ADD SUBFOLDER
   +image: add-subfolder.png
   Add a new subfolder to an existing image folder. Navigate to the parent folder 
   first. This must be a file folder, not an album folder. Start this menu 
   function and enter the new subfolder name. If the parent folder is included 
   within your list of top image folders, or if it is a subfolder within one of 
   these, then nothing more is needed. If not, and if you want images added to 
   this new folder to be indexed, you need to add the folder, or its parent, to 
   the list of top image folders. See \>INDEX FILES\>.

BOOKMARKS
   +image: bookmarks.png
   View existing bookmarks. Bookmarks are chosen locations (folder/file names) 
   with user-assigned names. Click on a bookmark to show a gallery of thumbnails 
   starting with that location. Select [Edit Bookmarks] to add, delete, or 
   rename a bookmark.

EDIT BOOKMARKS
   +image: edit-bookmarks.png
   After starting Edit Bookmarks, click on a gallery thumbnail to add this 
   location to the bookmark list. The assigned bookmark name will initially be 
   the file name corresponding to the thumbnail. This name appears in an edit 
   field where you can assign another 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 
   after the last bookmark location selected.

MANAGE ALBUMS
   +image: manage-albums.png
   An album is an arbitrary sequence of images that is manually assembled from 
   existing images. An album is a list of its member image files. The image files 
   themselves are not copied or changed. A given image file 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 of a given 
   person taken at different times or events, a "best photos" collection, etc. 
   You can add and remove images in an album or rearrange their order. Once an 
   album is made, you can call it up by name and it shows as a gallery. Keep in 
   mind that editing an image in an album will edit the underlying image file, 
   so any other way to view this image will show the same changes.

   \bCreate
   Enter a name for a new album. You can make an empty album, an album with 
   pre-selected image files from \>SELECT FILES\>, an album with images from the 
   current gallery, or you can select the initial images for the album. The 
   gallery could also be the result of a Search operation.

   \bRename
   Choose an existing album and enter a new name.

   \bDelete
   Choose an existing album and delete it permanently.

   \bSelect
   The standard file selection dialog is opened (\>SELECT IMAGE FILES\>). When 
   done, right-click on an album thumbnail and select "add selected files here" 
   to insert the new files. The selected files may also be removed from the album
   (see below).

   Edit an album: right-click an album thumbnail and select from the popup menu:
      • Add selected files here - previously selected files are added at the 
        thumbnail position. Click thumbnail left/right side to add before/after.
      • Add current file here - the current file is added at this position.
      • Remove from album - the clicked image file is removed from the album.
   Add files to an empty album:
      • Gallery View > Album button -> select the empty album.
      • Manage Albums > Select Files: select initial files for the album. When 
        you exit Select Files with the [OK] button, the selected files are 
        added to the album.

   \bDrag and Drop
   You can rearrange images in an album by dragging thumbnails with the mouse. 
   Drag the thumbnail until the mouse cursor changes to a small thumbnail image. 
   Continue dragging this image to the position where it should be inserted, and 
   release the mouse button. Position the mouse roughly between the thumbnails 
   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. You can use two Fotoxx sessions to make the selection or movement of 
   many images faster. Drag and drop images from any source gallery on to a 
   target album gallery. The source gallery can be an album or any gallery.

   TIP: 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 files are updated to the new file names and locations. Therefore, do
   not rename folders if they contain images in albums, or manually move image 
   files among folders. Instead, use Batch Convert to move the image files to the 
   new folder, then delete the old folder if empty. To delete image files, use 
   Batch Delete/Trash. This will also purge deleted files from albums.

   \bDesktop Wallpaper
   See \>COMMAND PARAMETERS\> \b-cwp parameter\b to use Fotoxx for cycling the 
   desktop wallpaper image using a Fotoxx album or any folder with image files.

UPDATE ALBUMS
   +image: album-replace-file.png
   Replace specified album files with specified replacements, or add specified 
   new files after specified existing files. Select one or more albums to be 
   processed. In gallery view, click on two thumbnails to specify 'old file' 
   and 'new file' in the above dialog. Select the option: 'new file' replaces 
   'old file' wherever found, or 'new file' is added to albums after 'old file'. 
   Press [clear] to erase the files and start over. Press [proceed] to process 
   the albums. After processing, the dialog is repeated with the same albums 
   selected and the same 'replace or add' option. You can select two more files 
   and press [proceed].

ALBUM MASS UPDATE
   +image: album-mass-update.png
   This is a utility for some of the mass updates that you may need after 
   creating new versions for many image files and needing to update one or more 
   albums to the new versions. This does not cover every need, which is likely 
   impossible, but my hope is that it will help reduce the need to change one 
   file at a time.

   Select one or more albums and then select one of the processing options:
      • Replace all with newest version only
        All albums are updated to have only the newest file versions.
      • Replace all versions with newest version
        All file versions are replaced with only the newest version.
        The original file, if present, is NOT replaced.
      • Add newest versions to existing versions
        The newest version is added to existing versions, if not already there.
        If only the original file is present, the newest version is added.
      • Replace all with original and all versions
        All album files are replaced with the original file and all versions.
      • Replace all with original version and newest version
        All album files are replaced with the original file and newest version.
      • Replace all with selected versions (*)
        All album files are replaced with the selected versions only.
        This includes the original (unversioned) file.
      • Replace all versions with selected versions (*)
        All album file versions are replaced with the selected versions only.
        The original file, if present, is NOT replaced.
      • Add selected versions to existing versions (*)
        The selected version is added to existing versions, if not already there.
        If only the original file is present, the selected version is added.
      • Replace all with original and selected versions (*)
        All album files are replaced with original files and selected versions.

   (*) The four options using selected files: the list of selected files is from 
   the function \>SELECT FILES\>. Album files that do not match any selected 
   files are left in the album. Only files that match a selected file are changed 
   according to the above rules. The matching is based on the file name without 
   version or extension: 'filename.png' and 'filename.v01.jpg' are matches.

   Example: Replace all versions with selected versions: 
   If the album has filename.jpg and filename.v02.png, and the selected files 
   list contains filename.v04.jpg, the result in the updated album will be: 
   filename.jpg and filename.v04.jpg

GALLERY TO ALBUM
   Save the current thumbnail gallery as an album.
   Select an existing album name [Browse], or input a new name, then press [OK].

SLIDE SHOW
   +image: slide-show.jpg
   Use the Manage Albums function to assemble the images for a slide show as an 
   album with an assigned name. In the slide show dialog (top left), press 
   [Select Album] and choose an album from the list provided.

   Change the other settings in the dialog as desired, then press the [Start] 
   button to start the slide show with the first image in the album, or [Resume] 
   to resume a paused slide show from the current image, or another image 
   selected by clicking its thumbnail.

   Use the escape key to exit the slide show and return to the dialog.

   The animated transitions between images, and the display times and zoom 
   behavior of individual images, can be customized using the dialogs explained 
   below.

   Main Dialog Controls
      • Caption Time
        The default time to display title and description, in seconds.
      • Image Time
        The default time to show the image alone, seconds.
      • Clip Limit %
        Images are scaled to fit the window, with margins for difference in 
        aspect ratio. Images with difference < clip limit are cropped to fit.
      • Music File
        Music file to play during the slide show (VLC player is required).
      • 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.
      • Random Image
        If checked, images are shown in random order - otherwise album sequence.

   Keyboard keys can be used to control the slide show. Press [KB controls]
   to show or change current assignments (Keyboard Preferences, bottom right).
   The following actions can be assigned:
      • Blank current image and pause the slide show, or restore image (toggle).
        Default 'B'.
      • Show next image, including transition animation, in a paused slide show.
        Default 'N'.
      • Pause or resume the slide show (toggle).
        Default 'P'.
      • Magnify the image - simulated loupe (see the \>MAGNIFY IMAGE\> function).
        Default 'X'.

   The following KB keys are assigned to actions that cannot be changed:
      • Escape: interrupt the slide show and return to the main dialog.
      • Left / right arrow keys: You can go back and forward at any time and 
        the slide show will continue from there.

   You can configure keys other than P/B/N/X if desired, and space bar (blank) 
   can also be used. Do this by replacing the key name in the dialog.

   Press [transitions] to start a dialog (Transition Preferences, bottom left) 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 time parameter sets the duration of the transition. Times less than 2 
   seconds may cause problems with slow computers or large monitors. If you see
   fleeting gaps in the image, you need to increase the time. The preference 
   parameters specify a relative preference which will influence how frequently 
   the transition is used when random sequence is selected.

   The buttons [load] and [save] allow you to save transition settings in a file 
   and load them later. These files are independent of the slide show files. A 
   slide show will default to the transition settings last used for that slide 
   show (album name), but you can always replace these by using the [load] button 
   to load some other settings, or changing them in the dialog.

   Press [image files] to start a dialog for Image Preferences (top right). These 
   are optional. An image is selected for customizing by clicking its thumbnail 
   in the album/gallery display. The dialog is filled-in with default settings or 
   the previous settings for this image in this slide show. Enter revisions and 
   press [done], or click on the next image to be customized.

   The dialog shows the customizable image events in time order:
      • play an optional tone when the image appears
      • wait for a specified time (may be zero)
      • show the following text items in parallel:
          • image name (file base name) for specified time
          • image title, if any, for a specified time
          • image description, if any, for a specified time
      • wait a specified time before starting an image zoom (may be zero)
      • zoom the image from normal to magnified or from magnified to normal over 
        the specified time. If neither option is selected, there is no zoom.
          • zoom-in: start at normal size, slowly magnify the image while moving 
            the center to a specified position
          • zoom-out: start at magnified size at the specified center, slowly 
            shrink the image back to normal size
          • [zoom center] - press this button, then click on the image thumbnail 
            to specify the zoom center for the image
      • wait for a specified time after zoom (may be zero)
        (the default value comes from the main dialog 'image time' setting)
      • transition to the next image, using the specified transition or 'next' 
        to indicate no preference (will be randomly selected).


MAPS MENU

+image: ug-maps.png

MAP OVERVIEW
   +image: map-click.jpg
   All maps will show markers (red dots) where there are geotagged images. Click 
   on a marker to get a Gallery View of all the images at this location. The 
   range of images selected corresponds to the marker size: images located within 
   the marker area on the map are selected. The effective marker area scales with 
   the map scale. Zoom-in to expand the scale and possibly separate one dot into 
   multiple dots.

NET MAP
   The Net Map function is an internet service to provide maps from any location 
   at any scale. The Net Map offers superior functionality, but depend on having 
   a fast and reliable internet connection. Markers (red dots) will show the 
   locations for your images having geotags. Use mouse wheel or left-clicks to 
   zoom-in on any location. Drag the map to change the center. Click marker to 
   get a Gallery View of images at this location. The range of images selected 
   corresponds to the marker size: images located within the marker area on the 
   map are selected. The marker area scales with the map scale. Nearby markers on 
   a zoomed-in map will consolidate when the map is zoomed out, and clicking a 
   consolidated marker will get all images im the contained markers. Shift + 
   left-click to see the geocoordinates of the clicked location.

   Net Map Navigation
      • left or right-click, NOT on marker: map zoom-in or zoom-out in 2x steps
      • left-click on marker: show gallery of images located within that marker
      • shift + left-click: show the geocoordinates of the location
      • mouse wheel: map zoom-in or zoom-out in 2x steps
      • mouse drag: the map image moves with the mouse

NET MAP LOCS
   +image: netmap-locs.png
   You can save a map location (map center and zoom level) with a given name and 
   recall the map location later with one click. To save a map location, navigate 
   to the location and zoom-in to include what you want within the window. Enter 
   the map location name and press the [Add] button. The new location is added to 
   the list of available locations in the window. To recall a saved map location, 
   simply click on the location name in the list. To delete a map location, click 
   on the name and press the [Delete] button. A few net map locations are present
   by default. You can keep or delete them.

DOWNLOAD MAPS
   Download and install a set of geographic map files for use with Fotoxx. These 
   include a large world map and maps for various continents and countries. The 
   functions FILE MAP and CHOOSE MAP (below) will not work until this download is 
   done. These maps are an alternative to NET MAP. They do not rely on having a 
   fast and reliable internet, but are also limited in the range they can zoom. 
   The download is < 200 MB. No user inputs are needed. The prior method for 
   doing this, the fotoxx-maps package, is now obsolete for fotoxx-22.30 and 
   later. The downloaded map files are located in <fotoxx home>/file_maps.

FILE MAP
   Use local file maps for map functions. The last chosen file map is loaded, or 
   a world map by default. Local file maps come from the DOWNLOAD MAPS menu.

   File Map Navigation
      • left click: zoom map to full size, right click: reduce to fit window
      • mouse wheel: zoom-in or zoom-out. zoom-in for greater magnification
      • mouse drag: the zoomed map image moves with the mouse
      • if map is full size and a marker is clicked, show corresponding gallery

CHOOSE MAP
   Choose a file map from the list of available maps.

   \bCustom 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 JPEG or PNG file. You can use a screen capture 
   function to create the map file. You can use the Mashup tool to stitch many 
   maps together to make a huge map. You can also use a scanner to capture one 
   or more paper maps and accurately stitch them together with Mashup.

   To install a map, put the map file into the folder <fotoxx-home>/file_maps. 
   In this folder you will also find a text file: maps_index. Each map requires 
   a line in this file which specifies the map name and the latitude-longitude 
   range of the map. Add a line for each of your custom map files.

   Here are some example lines in the maps_index file:
       New York City.jpg,  29.479,  30.053, -95.786, -94.905
       France.jpg,         42.074,  51.283,  -5.142,   8.613

   The entries are map file name, low and high latitude, low and high longitude. 
   All values are degrees, separated by commas. Spacing does not matter. Fotoxx 
   assumes a Mercator projection, but this is not significant for maps covering 
   less than 100 km.

   If you make a custom map, 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 created and record the latitude 
   and longitude values. You need accurate latitude and longitude data for the 
   upper left and lower right corners of the completed map. The precision should 
   be suitable for the scale of the map. 1 degree of latitude corresponds to 
   about 110 km on the earth's surface. 0.001 degree corresponds to 110 meters.

   If you have added lines to maps_index and you use the function DOWNLOAD MAPS 
   again (to get maps that were added later), the maps_index file is replaced and 
   your additions lost. Be sure to save your additions and add them back after 
   the download.

MARKERS
   Here you may choose to show markers for all images, or only images in the 
   current gallery. You can use the latter capability to show markers for a 
   chosen subset of images. Use an album, or use the Search function to produce 
   the desired set of images into a gallery. This works for file map and net map.


CUSTOM MENU

   +image: ug-custom.png

   This enables you to collect frequently used functions from multiple menus into 
   a single menu. The last entry in the menu, Edit Menu, opens a text editor for 
   editing the menu list itself. Add or remove the menu names you want, anywhere 
   in the list. The menu names must exactly match the names in the Fotoxx menus, 
   but case is not significant. Custom notes and tips can be added by using the 
   '#' character. Use "-f filename" to open a specified image file to process 
   with a given menu function.

   Menu entries can take the following formats:
      # comment                              a comment that does nothing
      menuname  # comment                    start this menu function
      menuname -f filename  #comment         start menu function using this file
      album -f albumname  #comment           open an album


ZOOM

   +image: ug-zoom.png

   \bZoom Button
   Left or right-click the button to increase or decrease the image size in 
   \>FILE VIEW\> or thumbnail size in \>GALLERY VIEW\>. This applies only if the 
   gallery view mode is \>THUMB VIEW\>. If \>META VIEW\>, nothing is done.


FILE SAVE

   +image: file-save.png
   +image: file-save-as.png

   In the first dialog, select 'new version', 'new file', or 'replace file'.

   \bNew 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 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. If the 
   file is a JPEG file, the default quality is used (see \>SETTINGS\>). 
   A keyboard shortcut can be assigned to this function if desired.

   \bNew File
   The 2nd dialog shown above will open to save the current image 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 and TIFF. JPEG is 
   normally the best option, since these are compressed to reduce space. You can 
   choose a JPEG quality value in the range 1-100. Lower values give smaller 
   files and less image quality. Values above 70 are 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 compressed 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. It is 
   rare that the difference between 8 and 16 bits per color can be seen with the 
   eye. However, an image with greater bits per color has more latitude if an 
   edit function radically alters the brightness distribution. PNG-16 files are 
   smaller than TIFF-16 but slower to save due to the slow compression process. 
   Saving a file as TIFF or PNG can be quite slow for a large image and a slow 
   computer. If an image has transparent areas (e.g. a Warp function creates a 
   non-rectangular image shape with transparent margins), you should save the 
   image as a PNG file if you want the transparent areas to be preserved. If 
   you use JPEG, these areas will be black and opaque. JPEG does not support 
   transparency.

   \bReplace File
   Save the current image file back to itself. If a JPEG file, the default 
   quality is used (this value can be set in \>SETTINGS\>).

   If 'make current' is checked, the saved file (new file name) will become the 
   current file. The source file (old file name) remains unchanged. If not 
   checked, the file is saved with the new name, but the current file remains the 
   source file (old name). In either case, the edit history is retained (Undo and 
   Redo will still work).

   The default JPEG quality is used unless you change the value in the New File 
   dialog. The default value can be set in \>SETTINGS\> (initially 90). You will 
   not be able to see a difference between a file saved with quality 90 and one 
   with 100, but the difference in file space is huge. The \>TECHNICAL TOPICS\> 
   section describes potential loss of image quality from repeated open, edit and 
   save of JPEG images. At the default quality of 90 this issue can be generally 
   ignored.

   The \bpermissions\b used for the new file are shown. These are copied from the 
   source file that was copied or edited to make the current file. If you want 
   different permissions, press the [Change] button to edit the permissions.

   \bRough guidlines for file size and save time
   These numbers are based on a 30 megapixel image with lots of color and detail, 
   and my own strong computer.

   \bfile type      characteristics                 file size      save time
   jpeg           100 quality level               15 MB          1 second
   jpeg           90                              6.7            1
   jpeg           70                              3.4            1
   jpeg           50                              2.5            1
   png-8          8 bits/color                    45             10
   png-16         16                              72             15
   tiff-8         8 bits/color                    88             1
   tiff-16        16                              176            1


METADATA MENU

+image: ug-metadata.png

   Metadata is text data that is stored inside an image file. Digital cameras 
   create some metadata automatically, such as date and time, technical data 
   about the camera and photo parameters, and location data (if the camera has a 
   GPS receiver). Other data can be added by the user, e.g. a title, description, 
   rating, and tags (search categories).

   Fotoxx can search your image collection using any metadata, along with folder 
   and file names or partial names, producing a gallery of matching images. In 
   most cases, the search is almost instantaneous. 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 an organization system for file 
   and folder names and metadata tags, titles, ratings, etc. 
   See \>ORGANIZING IMAGES\>.

   Metadata standards are chaotic. Please review this issue in the topic 
   \>BATCH MOVE META\> before making decisions about which metadata keys to use 
   for your image collection.

VIEW META
VIEW ALL META
   +image: view-metadata.jpg
   The View Meta functions displays commonly useful metadata for the current 
   image file. This includes the date and time of a photo, shutter speed, focal 
   length, image size, ISO, etc. Digital cameras store this data in the image. 
   Metadata may also contain data added by a user: keywords or tags, title or 
   caption, description, comments added by the photographer or later editor 
   (sometimes found in published images).

   If an image is edited and then saved, the metadata is updated and stored with 
   the new image. View Meta shows the history of edits that have been made.

   View All Meta reports all available metadata, and can be over 100 items you 
   likely don't care about.

   The [Extras] button on the View Meta window opens the dialog shown on the 
   right, where you can add extra items to the report. Any item available in the 
   View All Meta report can be added to the short report. Click an item in the 
   left column to add it to the right column and to the report. Click an item in 
   the right column to remove it. Click the entry "Other Item ..." to type-in any 
   item name not contained in the default list, which is limited to the most 
   likely needed items.

   Fotoxx uses these metadata items (keys) for image editing and searching:
      \bData Name\b               \bFotoxx function to add or change the data
      Title                   Edit Meta - title
      Description             Edit Meta - description
      Date/Time Original      Edit Meta - date/time - normally from camera
      Rating                  Edit Meta - rating - 0 to 5 stars
      Geotags                 Edit Meta - location - may come from camera GPS
      Tags                    Edit Meta - image tags (identifiers added by user)

   There are also several batch functions for adding data into many image files 
   at once. These are found in the \>BATCH MENU\>.

METADATA STANDARDS CHAOS
   Metadata standards are chaotic. Multiple standards bodies and corporations 
   (e.g. Adobe, Nikon) have developed multiple overlapping/conflicting standards 
   over the  decades. For example, the title of an image can be found in one or 
   more of the keys 'title', 'subject', or 'headline'. The author or photographer 
   may be found in 'artist', 'by-line', 'creator', 'author', or 'photographer' 
   (not a standard but often present). The content description may be found in 
   'description', 'imagedescription', 'comment', 'usercomment', or 'caption'.

   Fotoxx uses the following metadata for editing, displaying, and searching 
   image files: 'creator', 'description', and 'title'. This choice was based on 
   frequency of use in a large sample of images. Likely you have image files 
   using different metadata keys. You can copy these other keys into the ones 
   used by Fotoxx. For single files, use View Meta to show all available data in 
   all keys, and Edit Meta to copy data into the keys used by Fotoxx. Add all 
   redundant keys to the 'extras' list in View Meta, so you can see them. Run 
   both View Meta and Edit Meta together while viewing images to be fixed. Copy 
   and paste data from View Meta into Edit Meta. Both functions update as you 
   move to other images. \bBetter:\b You can process selected image files, or all 
   files, using \>BATCH MOVE META\> to consolidate metadata into preferred keys.

TAGS OVERVIEW
   Image files can have identification or classification tags (keywords, labels) 
   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 embedded blanks or other delimiters can be used. 
   Commas and semicolons are used as delimiters between tags, and therefore 
   cannot be used within a tag (a standard, external to Fotoxx). 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.

   Regardless of the physical organization of your images (folder and file names), 
   tags can be used to create other organizations. All images having a desired 
   tag or tags can be found quickly and displayed in a gallery window, where you 
   can further review the images and choose those for viewing, editing, or 
   changing their tags. If you have used folder and file names in a meaningful 
   way, you can search for images using these names as well as tags. You can also 
   search images by date, rating, location, and other metadata items. These need 
   not be duplicated in tags. See \>SEARCH IMAGES\> below.

   \bManaged Tag System
   This is appropriate if you are starting from near nothing and are able to plan 
   your tag system before adding tags to your images. In this system, you create 
   a limited number of tag categories (e.g. people, places, things, events, art, 
   scenery ...). You then plan the tags or types of tags that will go into each 
   category. Tags are created and assigned to a category as needed during the 
   process of tagging images. An image is tagged by pointing and clicking on the 
   list of available tags, which is organized by category and alphabetically 
   within category. If a new tag is needed, it is created when first assigned to 
   an image. The number of tags within a category should ideally be less than 
   about 200, so that visual location from a pick-list is fast enough. The 
   pick-list is sorted alphabetically.

   managed tag system advantages
     • prevent inconsistent tag names (e.g. 'landscape' and 'scenery')
     • prevent alternate spellings and typos (e.g. 'susan', 'susy')
     • prevent tags that logically include other tags (e.g. 'landscape', 'lake')
       (this can be planned and deliberate, but should not happen by accident)
     • searching is more reliable because tags do not have the above errors
     • when tagging images, you have a reasonable overview of available tags
       (as opposed to thousands of tags in an unmanaged system)

   A large tag list slows down the process of tagging images due to the time 
   needed to visually find a tag in a long list in a scrolled window. This is 
   mitigated in 3 ways: (1) Up to about 10 most recently used tags are shown in 
   the edit dialog, where they can be easily seen and chosen. Since a series of 
   photos made at the same time will likely share many tags, adding tags to such 
   a series is made easier and faster. (2) When adding tags to an image, you may 
   simply start typing a desired tag name. A popup list of matching tags appears 
   as soon as there are only a few possible matches. You can then click on the 
   desired tag to add it to the image. If there are no matching tags, you have 
   the option of adding the new tag to the list of available tags. (3) You can 
   limit the list of displayed tags to a chosen category.

   If tags are broadly defined and fewer in number, search results for tags will 
   be larger, but using the search results (image gallery window) to find a 
   smaller subset of images can be quite fast. Physical file organization is 
   preserved: image files located together in their folders will also appear 
   together in search results.

   Images downloaded from the internet often contain tags. These of course have 
   no organization and are collectively chaotic. If you use a managed tag system, 
   it is best to review such images and clean up the tags to conform with your 
   system, or delete them. Whatever new tags are present will be automatically 
   added under the category "nocatg". If you notice unwanted tags in your tag 
   list, use \>SEARCH IMAGES\> by tag to find the images with unwanted tags so
   they can be fixed or removed. 

   \bRandom Tag System
   You may prefer to invent tags as needed with no particular system in mind. Or 
   you may already have thousands of tags, making a conversion to a managed tag 
   system difficult (but not impossible: Fotoxx has a function to mass convert 
   tag names). In this case, you can simply type tags into your images, creating 
   new tags as needed. There is still some capability to keep tags organized: 
   existing tags matching the characters you input are shown as soon as there are 
   only a few possible matches. Example: you type "new" and a list of tags is 
   shown: New York, Newman ...  If one of these is your intention, you click on 
   it to select the tag. If not, you keep on typing and eventually press Enter 
   to create a new tag. When searching images for tags, you can type desired tag 
   names or pick them from the list of available tags. Available tags matching 
   the first few letters you type are shown, and you can pick from this list. 
   You cannot enter a search tag that does not exist somewhere in your images.

   \bGeotags
   Modern cameras can record the location of each photo, using an internal GPS 
   receiver. Latitude, longitude, city or location, and country are recorded in 
   the EXIF metadata of the image JPEG or RAW file. The Edit Meta function also 
   allows location data to be entered or revised. Locations may also be specified 
   by clicking on a map. There are three functions that can find images for a 
   specified location or region:
      \>SEARCH IMAGES\>
      Find images by location name (also multiple names and partial matches).
      \>PLACES/DATES\>
      Find images for a country, country/location, or country/location/date range.
      Images by Map Location:
      Click on a map marker to show all images at the marker location.

   Location names (city or other place name, and country) from the camera GPS are 
   not standardized and may be chaotic (e.g. Munich, München, MONACO). How to 
   deal with this is discussed below.

EDIT META
   +image: edit-metadata.png
   The Edit Metadata function is used to add basic metadata to an image. Please 
   read Tags Overview and Geotags Overview (above) before using Edit Metadata.

   Edit Metadata is used to edit the most frequently used metadata: image date 
   and time, rating, title, description, location data, and tags. The dialog 
   initially shows data for the current image. After making additions or changes, 
   press [Apply] to update the image file. There is no automatic file versioning 
   for metadata changes, but can use File Save > New Version if wanted.

   The dialog shows the metadata for the current image in File View, or for a 
   clicked thumbnail in Gallery View. The dialog updates itself when a new image 
   is opened or new thumbnail is clicked.

   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 compared with a low limit for searching, 
   or 12/31 when compared with a high limit. The [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 format hh:mm[.ss].

   You may enter a title, description, and a rating (0-5 stars) for the image.

   If the location data is available from any previous image file, enter the 
   first few characters and press [Find] to get a list of locations to choose 
   from. For the first entry of a location, or to add location data to many files 
   at once, see the topic Adding Geotags below.

   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 it. 
   A tag can be deleted from the image by clicking it in Image Tags. Recently
   added tags are shown in Recent Tags. This is a convenience to make adding tags 
   to a new batch of images easier, since many of the same tags will be used 
   again. Point and click the same way.

   If the list of defined tags is long, it may be easier to type the desired tag 
   into Enter Tag. Existing tags matching what you have typed so far appear in 
   Matching Tags, and you can click on one of these to add the tag to the image. 
   If the input tag is new (no matching tag is shown), press [add new tag] when 
   the tag is complete. It will be added to the image and to the list of defined 
   tags with category "nocatg".

   If you are using tag categories, you can select a category, and only those 
   tags will be shown in the list of defined tags. If your tags list is huge, 
   this can reduce the list to a manageable size for pointing and clicking.

   The [Apply] button writes the data to the image file and to the metadata index 
   file used for searching images.

   The [Prev] button can be used to load all available data from the previous 
   image viewed or edited. This can be used to speed-up the processing of a group 
   of images sharing much of the same data.

   \bAdding Geotags
   The Edit Meta dialog shows the location data for the current image, if any. 
   For an image with missing or incorrect location data, enter a location name 
   (city, park, museum ...) and use the [Find] button to either complete the data 
   in the dialog, or get a list of matching locations to choose from (e.g. London, 
   United Kingdom and London, Canada). The list of locations comes from your 
   image files, so a location will not be known until it is assigned to an image 
   for the first time. 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. Use the [Prev] button to 
   fill the dialog data with the last location used. If the [Find] button does 
   not find a location (it is not present in any other image), you can use the 
   [Lookup] button to find location data from an internal table. This table was 
   downloaded from the internet and uses English place names, which you can 
   change. As with [Find], partial names can be entered to get a picklist of 
   possible matches. The [Apply] button will add the location data to the image, 
   and this location will be available for future use by the [Find] button. If 
   the [Lookup] button fails, you can get location data from Wikipedia or other 
   web service, and enter the data into the dialog.

   Note for non-English locales: If a comma is used for a decimal point in 
   latitude/longitude, this is accepted but converted to a period internally.

   Blank the latitude and longitude if you want to save only the location and/or 
   country name in the image file. If the latitude/longitude data is changed from 
   the values returned by [Find], the new values are saved for this image file. 
   If a location is saved without latitude/longitude, there will be no location 
   marker on a map, and finding photos for this location by clicking on a map 
   will not work. The two other methods to find photos by location, Search Images 
   and Places/Dates, will still work.

   Note: The EXIF keyword "city" is used to mean any location name: city, park, 
   museum, lake, etc. Fotoxx uses "location" to avoid stupidities like "city = 
   Yellowstone Park". Internally, "location" is converted into "city" for 
   metadata storage or retrieval.

   If you change to one of the map views and click on a location, this location 
   will be inserted into the Edit Meta dialog. If you click within a marker 
   (red dot), the location name and latitude/longitude for that marker will be 
   used. If you click outside a marker, the clicked latitude/longitude will be 
   used, and the location name will not be changed.

   If you use the [Find] button to set the dialog location data from a known 
   location, there are two possible outcomes: if there is only one geocoordinate 
   (latitude and longitude) associated with the location, this is returned into 
   the dialog. If there are multiple geocoordinates, the Net Map is shown and 
   zoomed-in to a scale where all markers for all geocoordinates associated with 
   this location are shown. Click within one of the markers to choose the 
   corresponding geocoordinate, or click outside any marker to set a new 
   geocoordinate for this image file. The location name now has a new associated 
   geocoordinate.

   You can use \>BATCH GEOTAGS\> to add location data to many image files at once.

   Summary
      • Enter (or change) a location name (possibly abbreviated) in the dialog.
      • Use [Find] to find a location 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 country.
      • If there are zero matches (not found), try the [Lookup] button.
      • If still not found, add more letters to the location.
      • If still not found, use the above web service and input the data manually.
      • Use [apply] to update the image and make the new location available.
      • If there are multiple geocoordinates for a given location, click on a map 
        marker to select one, or click elsewhere to add a new geocoordinate.

EDIT ANY META
   +image: edit-any-metadata.png
   This is a dialog for editing any metadata for the current image file. The most 
   common keys for editing are listed on the left. Press the [Full List] button 
   to get a list of all available keys for the current image file (there may be 
   hundreds of them). Press [Short List] to go back to the common keys list. 
   Click an item in the list to retrieve the current key value. Change the value 
   if wanted and press [update]. The metadata is updated. To edit a key name not 
   in the list, enter the key name and press [fetch] to retrieve the present 
   value, if any. Then enter or change the value and press [update]. To delete a 
   key, press [delete]. You may enter the key name in lower case and with or 
   without spaces, e.g. "Subject Distance" and "subjectdistance" will both work. 
   Some keys cannot be changed, e.g. 'image width' is the image pixel width, 
   which can only be changed by changing the image size. The source for the 
   short list is the text file "metadata_picklist" in the Fotoxx home folder 
   (/home/<user>/.fotoxx). You can add or remove items from this list.

DELETE META
   Specify the key name to delete, or select All. The metadata is deleted. 
   Use All to clean an image of any identifying information that may be present. 
   Some keys are not deletable, e.g. File Name.

COPY META
   Combined images created with Fotoxx (HDR, panorama, mashup ...) will not 
   contain metadata by default. Use this function to copy metadata from one of 
   the input images, or any other image. Use the [Browse] buttons to choose a 
   file to source the metadata and a file to receive the metadata ("target file" 
   in the dialog).

FIX META
   The metadata of the current image file is repaired. Use this function if you 
   have an image file that produces an error message when you try to edit the 
   metadata. It will delete malformed (illegal) metadata and keep the rest. This 
   may fix the problem. You could also save the image file as a new version, 
   which will keep the original file and remove the offending metadata from the 
   new version.

MANAGE TAGS
   +image: manage-tags.png
   Create tags (keywords) and optionally group them into categories. You can 
   assign categories to tags to help organize them and locate them more quickly 
   when adding tags to images. They are optional and they play no role in tag 
   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]. If the category is blank, 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". A 
   Category with no tags assigned can be deleted - click the category, clear the 
   tag name if present, press [delete].

   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.

CAPTIONS
   +image: choose-captions.png
   \_Choose Captions menu
   Choose which metadata items to use for text captions displayed in the top left 
   corner of the image in file-view mode. Subsequent image views will include all 
   chosen items available in the image metadata. See \>SETTINGS\> for how to 
   control line wrapping.
   \_Toggle Captions menu
   Toggle the display of captions ON or OFF.
   Assign a keyboard shortcut to quickly enable or disable captions display.

PLACES/DATES
   +image: image-locations.jpg
   This is a fast way to find all photos made at a given location or location and 
   date range. In the dialog, choose from the two options: include all images in 
   the report, or include only images found by the previous Search function. Then 
   select the desired grouping level: by country, by country and location, by 
   country and location and date, or by date and country and location. In the 
   last two cases, you can select a date range for grouping of images having 
   nearby dates. A number N will group images together with dates that are N days 
   or less apart.

   A popup report shows all locations found and the dates of photos taken in 
   those locations. The count of photos taken is also shown. In the above example, 
   29 photos are from Grindelwald in March 2008. Click on a line in the report to 
   get a thumbnail gallery of those images, and from there you can click on any 
   image to view or edit. Note that this method uses only location and country to 
   find the images. Earth  coordinates are not used. If you have images with 
   missing or inconsistent earth coordinates for a given location, use this 
   function to get all of them, and then use \>BATCH GEOTAGS\> to make the earth 
   coordinates consistent.

   You can also use the keyboard up/down arrow keys to rapidly step through the 
   report lines and view the gallery for each line. The page up/down keys and the 
   home/end keys also work. Use the [find] button to enter a name and jump 
   directly to that name in the report.

TIMELINE
   +image: timeline-report.jpg
   This report produces a timeline of image counts by month. Choose from the two 
   options: include all images in the report, or include only images found by the 
   previous Search function. Click on a year and month in the resulting report to 
   get a thumbnail gallery of all images with a photo date (EXIF) in the selected 
   month. The example above shows 377 images for May 2016. You can also use the 
   keyboard arrow keys (up/down/left/right) to step quickly through the months 
   or years and view the corresponding galleries. Year 'null' is for images 
   without a photo date.

AUTOSEARCH
   This function can be used by shell script files to extract image files meeting 
   any of the selection criteria available when using the Search Images function 
   (see below). First, use the Search Images function to set desired selection 
   criteria (e.g. folder/file names (wildcards allowed), dates, tags, or other 
   metadata). Use the [save] button to save the criteria as a file with a given 
   name. Use the following command to start Fotoxx and perform the search: 
   $ fotoxx -m autosearch <settings_file> where <settings_file> contains your 
   search criteria. The output goes into the file <fotoxx home>/search_results, 
   where <fotoxx home> is the Fotoxx home folder (default: /home/<user>/.fotoxx/). 
   The settings file is an ordinary text file which can be hand-edited or created
   using a shell script. 

SEARCH IMAGES
   Use the Search Images function to find images having any desired metadata 
   (date, tags, location ...). 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.

   There are two report formats: a gallery of thumbnails showing all images that 
   match the search criteria, or a metadata report which combines thumbnails with 
   metadata text. Here is an example of the metadata report format:
   +image: search-images-metadata.jpg

   \bSearch Dialog
   +image: search-images.jpg
   In the dialog, select which images to search, either all (all images) or the
   current set, meaning the images in the current gallery list, which can be a 
   folder, album, or the results of a prevous image search. Next, 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 (gallery), and 
   'remove' means remove them from the current set. To remove images, you must 
   search the current set.

   For files matching the select criteria, you may additionally specify which 
   versions are selected: last version only, original + last version, original + 
   all versions, or no change. 'no change' ignores file versions and selects all 
   files meeting selection criteria - originals and/or versions. Thus you can get 
   multiple versions of the same file in the output report. The version options 
   depend on the Fotoxx naming convention: The original file name is normally 
   filename.ext. Edited versions are filename.v01.ext, filename.v02.ext, etc. 
   When one of the 'version' options is selected, then each file selected for 
   reporting is replaced by the version or versions specified. Therefore it is 
   possible, for example, that if only version 2 matches the selection criteria, 
   the resulting report includes only version 3, if that is the last version, 
   and if 'last version only' was specified.

   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 include the standard items (date, rating, 
   tags, geotags, title, description) and any other metadata keys you added in 
   the "Keyname" selection list.

   Enter your search criteria. Select desired tags, dates, star ratings, words 
   contained in text (image title,  description), file or folder names, and 
   location names. See more details below.

   Press the [proceed] button to perform the search. The output is a standard 
   gallery of thumbnails, or the metadata report format shown above. Choose 
   images to view or edit by clicking the thumbnails. Navigate this set of 
   searched images like any other gallery. You can save the searched images as a 
   permanent album, which can be further edited to add or remove images 
   (see \>MANAGE ALBUMS\>).

   Available tags are shown in Defined Tags and can be chosen with point and 
   click. If the list of defined tags is long, it may be easier to type a tag 
   into 'enter tag'. Existing tags matching what was typed so far will appear in 
   the 'matches' list, and you can click one of these to add the tag to the 
   search list. If you type a tag with no match (it does not exist in any image), 
   the list of matching tags will be empty.

   If you are using tag categories, you can select a category, and only those 
   tags will be shown in the list of defined tags. If your tags list is huge, 
   this can reduce the list to a manageable size for pointing and clicking.

   A date range may be entered to restrict the search to images within the date 
   range. Choose photo date (EXIF from camera) or file date (creation or last 
   modification date). The format is yyyy-mm-dd. 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 limit. Times may optionally be specified using the 
   format yyyy-mm-dd hh:mm. Missing times default to 00:00 and 23:59.

   To search for images having no EXIF photo date (e.g. scanned images), use 
   "null" in the first date input.

   A pair of star ratings may be entered to restrict the results to images having 
   a rating within the given range. A missing low value implies 0 stars, and a 
   missing high value means the highest rating, 5 stars.

   Folder and file names may be searched. In the field search files, enter any 
   number of names used for your image folders and file names, separated by 
   blanks. An input of "egypt cairo" would match all image folder or file names 
   containing either of these strings. Substrings will also match. If a '*' is 
   present in a search name, the matching is based on wildcards, where '*' 
   matches any string, including a null string. Therefore "*2017*paris*" will 
   match any file containing "2017" and "paris" or "Paris" in that order. Keep 
   in mind that the file name being matched is the entire pathname. Another 
   example: "*2017*/" would match any file with "2017" in any parent folder, 
   but "2017" in a file base name would not match.

   Image title and description may 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 title and description of all images, and matching images are 
   selected. Case does not matter. Search words may also have wildcards, e.g. 
   'veni*' matches both 'Venice' and 'Venizia'.

   To search locations, enter one or more city/location or country names in the 
   search locations field. Only image files with geotags matching one of the 
   entered locations will be selected. A location may be a city, park or other 
   geographical name (whatever is stored in metadata 'City' and 'Country' fields). 
   Matching is based on substrings. A search for "mon" will match "Monaco" and 
   "Montreux". Use commas to separate multiple entries.

   The radio buttons 'all' and 'any' apply to tags, text, file names, and 
   locations. You can select images having ALL the entered strings, or ANY of 
   the entered strings. Example: if the location search field is "new york" and 
   "any" is selected, images from New Zealand and York, England would be included. 
   If "all" is selected, only images located in New York would be included.

   If you wish to find images with missing data, you can enter "null" as a match 
   value.

   \bSearch Additional Metadata
   Using the dialog inputs 'keyname', 'condition', and 'match values' you can 
   specify additional metadata items to use as select criteria, or to be added 
   to the report output if the "metadata" report type is chosen. The items 
   available for a given image file can be shown with \>VIEW ALL META\>. These 
   include e.g. camera make and model, exposure time, F-number, ISO, metering 
   mode, focal length, shooting mode, etc. Enter match criteria, if wanted, so 
   that only images with matching metadata are reported. For example, if you 
   enter "make" with the match value "nikon", then only images from a Nikon 
   camera (any model) will be reported. The pick list comes from the text file 
   <fotoxx home>/metadata_picklist. You can add items to this file if wanted.

   The matching logic can be selected for each metadata key.
      \bmatch method   match value(s)
      report         select and report all values (also missing) - no matching
      reportx        select and report only images that have data for this key
      matches        one or more text values to select, separated by commas
      contains       as above, but any metadata containing this text is selected
      number =       single numeric value - equal metadata values are selected
      number =>      single numeric value - equal or greater values are selected
      number <=      single numeric value - less or equal values are selected

   \bWildcard matching
   The 'matches' method allows the use of wildcards in the match criteria. An 
   asterisk (*) can be used to match any sequence of characters, including zero 
   characters. A question mark (?) can be used to match any single character. 
   Example: "mar?*ony" would match "mark anthony" but would not match "marony". 
   "mar*ony" would match both.

   The [x] buttons on the right side can be used to clear single metadata search 
   items.

   \bDialog Buttons
   [Load] and [Save] can be used to load or save search criteria from a file.
   [Clear] will clear all data in the dialog. [Proceed] will start the search 
   process.

   \bPerformance
   Searching and reporting of indexed metadata is almost instantaneous. The speed 
   for non-indexed metadata depends on computer and disk speed. A strong CPU and 
   SSD disk can search over 2000 files per second. There is a separate topic 
   which explains options for optimizing image searching: \>ORGANIZING IMAGES\>.

   \bsearch_results\b (album)
   The output of Search Images is automatically saved in the album 
   "search_results". This is for convenience. You may perform a search and then 
   perform other functions which change the current gallery. If you need to 
   refer to the previous search, this remains available in the album 
   "search_results". Rename this album if you want to keep later searches from 
   replacing it.

   Limitation: The search function is limited to 40,000 results (images found 
   that meet the search criteria). If this limit is exceeded, you are notified 
   and the search is truncated. This limit exists because the size of a scrolled 
   window in GTK is limited, and an attempt to create a larger window may result 
   in a crash or lock-up.


SELECT MENU

+image: ug-select.png

AREA 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 (e.g. Rescale) 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 is started, the 
   selected area remains active, so it is possible to carry out a series of 
   edits on one area.

   Fotoxx uses 'areas' instead of 'layers' as in Photoshop. 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, 
   loaded and pasted into other images, and edited there.

SELECT AREA
   +image: select-area.jpg
   The Select Area dialog starts with the menu Select > Select Area. Select one 
   of the methods explained below. Each method selects image areas in a different 
   way. You can change methods at any time, and the selected areas accumulate. 
   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 map the image pixels within 
   the area outlines, making them ready to apply subsequent edit functions. The 
   [Hide] button hides the area outline, giving you better visibility of edits 
   and possible area edge effects. Use the [Show] button to show the area outline. 
   The [Clear] button removes all area selections. The select area dialog can be 
   exited and re-started later to modify existing areas or add new ones. 

   \bMethods
   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 to outline a rectangular area
      • Ellipse  - drag to outline a circular or elliptical area
      • Freehand Draw - outline area by drawing (dragging) with the mouse
      • Follow Edge - outline by following image feature edges
      • Select area within mouse - select all pixels within a circle centered on 
        the mouse pointer. Drag the mouse to extend the selection.
      • Select one color within mouse - works as above, but selects only pixels 
        matching a given color within a given match level (0-100%). 
      • Select all colors within mouse (flood) - select all pixels within the 
        mouse, and extend the selection into adjacent areas with colors matching 
        the colors within the mouse circle (this is sometimes called 'flood'). 

   The following paragraphs explain the details of each method.

   \bRectangle
   Drag the mouse from one corner to the opposite corner of a 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.

   \bEllipse
   This works the same as rectangle selection, except that the area enclosed is 
   a circle or ellipse. The drag start location is the center of the resulting 
   ellipse. The angle of the drag determines the shape of the ellipse.

   \bFreehand Draw
   Drag the mouse (left button down) to draw a freehand 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 (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 line 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. There is a gap detection utility described below - 
   \>FIND AREA GAP\>. If an area edge is also an image edge, you do not have to 
   draw this portion of the area. Draw the line off the image edge, and draw it 
   back onto the image at another position along the image edge.

   \bFollow Edge
   High-contrast pixels (likely image feature 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, but with a tendency to follow 
   feature edges from a position slightly behind the mouse. For very irregular 
   edges (hair, foliage), see Select/Deselect below.

   \bMouse Radius and Color Match Level
   These two controls apply only to the 'select within mouse' methods described 
   below. 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. Match level defines a required match level 
   (0-100%) to select pixels based on their color and brightness. 0 means 
   anything matches, and 100 means a perfect match is required.

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

   \bSelect one 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 the match level. Adjust the match level down or up to match a greater
   or lesser range of colors. Click as needed on the image to change the color 
   to be matched.
   
   \bOptional deselect color
   This applies only to 'select one color' above. Shift + click on the image to 
   set a deselect color. When the box is checked, the deselect color is active. 
   If a pixel matches the deselect color better than the select color, the pixel 
   is unselected. When selecting along a feature edge with a low color contrast 
   compared to an adjacent area that should remain unselected, set the deselect 
   color from the adjacent area. This is helpful for accurate selection of a 
    complex edge, like hair or foliage.

   \bSelect all colors within mouse\b (flood)
   This is called 'flood' in some editors. Left/right drag to select/unselect 
   pixels inside the mouse circle. Pixels beyond the mouse circle are also 
   included if they meet these two conditions: 1) their color matches any color 
   inside the mouse circle, within the current match level. 2) they are within 
   the 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 image feature 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, or 
   use the select area within mouse method as described above. 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 easier 
   to correct this by unselecting from outside the selected area instead of 
   selecting from inside the selected area. You may need some practice to get a 
   feeling for this and be able to work efficiently.

   \bSelect all colors within mouse - summary
      • left drag      select pixels inside mouse and matching pixels in range
      • right click    undo previous selection, repeat to unselect more
      • right drag     unselect pixels inside mouse and matching pixels in range

   \bEdge creep
   An area that has been finished (see below) can be expanded or contracted in 
   1-pixel steps. 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 feature color transitions to background. Expanding 
   or contracting the area 1-2 pixels can produce a cleaner looking edge. The 
   area remains finished after creep.

   \bArea outline color
   The color used for the mouse selection circle and the area outline can be 
   changed at any time by clicking one of the color buttons. This allows good 
   visibility against various background colors.

   \bShow/Hide
   Use [Hide] to hide the area outlines. This is useful to better see the effects 
   of the area edits without interference from the area outline. Use [Show] to 
   show the outlines and resume editing the area.

   \bFinish
   +image: select-area-finish.png
   An area is not effective for edits until it is successfully finished. Finish 
   validates drawn outlines and colors the enclosed pixels for visual checking.
   When you are finished outlining areas, use the [Finish] button to complete the 
   process. The popup dialog shown above summarizes two methods you can use to 
   finish.

   Method 1: Left-click the mouse inside areas that were outlined by hand. The 
   enclosed areas are temporarily colored so you can verify that the final result 
   is what you intended. 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. Press keep] when all areas have been clicked and correctly 
   colored. If the outline of a hand-drawn area has a gap, the coloring process 
   will "leak out" and areas outside the enclosure will be colored. In this case, 
   press [Undo] in the Finish dialog, which restores the original area outline. 
   Find the gap in the outline and close it, then try [Finish] again. A 1-pixel 
   gap in a large area can be hard to find. Zoom-in to see better. See the 
   function \>FIND AREA GAP\> below for a fast method to find tiny gaps.

   Method2: Right-click somewhere outside all the enclosed areas. All enclosed 
   areas will be colored for visual verification. If there is a gap, the results 
   and the fix are the same as described in method 1. This method makes sense if 
   you have many hand-outlined areas and you do not want to check them one at a 
   time using method 1.

   Areas selected using the 'select within mouse' methods are automatically 
   finished. These areas are mapped during the selection process, whereas areas 
   selected with rectangle, ellipse, or one of the line-drawing methods are 
   mapped only when you click inside them. If you use only the 'select in mouse' 
   methods, you can cancel the finish dialog without clicking any of the selected 
   areas.

   If you draw a line from one image side to another, you can click on either 
   side of the line to make an area of all pixels on that side of the line. 
   Example: draw a horizontal line on the boundary between sky and land. Click 
   above the line to select sky, below the line to select land. The drawn lines 
   must reach the image edges completely.

   \bClear
   Discard the current area permanently.

FIND AREA GAP
   If an area outline was created by freehand drawing using multiple strokes, it 
   is easy to leave small gaps in the outline that are not visible below 4x zoom. 
   An attempt to finish such an area will fail because the mapping of the 
   interior pixels will leak out through the gap and cover areas outside the 
   intended area. If the Finish function fails, this function can find the gap. 
   Click somewhere on the outline of the failed area. The outline will be slowly 
   re-drawn in one direction from the clicked position, until an "end pixel" is 
   found. This is where the gap is. The outline is then drawn in the opposite 
   direction until the gap is encountered. You can now see the gap position 
   clearly. Zoom-in on the gap and close it using freehand draw, then test again 
   to see if the full outline can be drawn without stopping. This function can be 
   used in parallel with the Select Area function (both dialogs active).

AREA BLEND
   +image: area-blend.png +image: area-blend2.jpg
   Two functions are present in this tool, area edge blending and mouse blending. 

   The edges of an edited select-area can be blended with the original image or 
   prior edit. This can remove noticeable edge effects, e.g. an image feature was 
   brightened against the surrounding background. All area edges change gradually 
   from the prior image to the edited image over the distance 'blend width'. 

   Any part of the area can be mouse-painted to blend with the original or prior 
   edit. Each mouse drag within the select-area will gradually blend-in the prior 
   image. The rate of blending is determined by 'blend rate', which can be set 
   separately for the mouse center and edge. You can use this to selectively 
   blend chosen area edges: Set the blend rates to 50/0 for center/edge, and drag 
   the mouse center over the area edges.
   
   Changing the blend width for the first time will cause edge distance to be 
   calculated for every pixel in the area. This is normally fast, but it may take 
   longer if the area is large with a complex geometry (i.e. a very long edge). 
   If the edge of a select-area runs along an image edge, it is not considered an 
   edge for blending. A long edge calculation can be canceled with the Escape key.

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

ENABLE/DISABLE AREA
   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.

INVERT AREA
   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 area edge blending is desired.

CLEAR AREA
   Permanently discard the current area. This is also available as a button in 
   the Select Area dialog.

COPY/PASTE AREA
   A selected area can be saved to a cache file using the menu Areas > Copy. This 
   area can be pasted into the same or another image using Areas > Paste. Click 
   and drag to position the pasted area. The dialog controls can be used to 
   rescale and rotate the pasted area.

LOAD/SAVE AREA
   A selected area can be saved to a file using the menu Areas > Save. You are 
   asked to supply a file name. A PNG file is created. The PNG file has an alpha 
   channel for transparency information. The image is a rectangle enclosing the 
   selected area. Selected pixels are opaque, and others are transparent.

   These files reside in <fotoxx-home>/saved_areas by default, but you can save 
   them anywhere. Use the menu Areas > Load to load a saved area from a file and 
   paste into the current image file. The background image will show through the 
   transparent parts of the pasted area. Click and drag to position the area. 
   The dialog controls can be  used to rescale and rotate the image. 


UNDO/REDO BUTTON

+image: ug-undo-redo.png

   If an edit function is active and the image has been changed:
      • left mouse click will undo the current edit
      • right mouse click will redo the edit
   This allows you to rapidly compare the "before" and "after" images for the 
   current edit function.

   If no edit function is active, but some edits were made to the current image:
      • left mouse click will undo one edit step per click
      • right mouse click will redo one edit step per click
      • if combined with the A-key, undo/redo ALL edits (original <> final image)
      • middle mouse click pops-up a list of all edit steps - go back to any step
   This works only if the current image file has not changed since being edited. 
   If you open another file, the saved edit steps for the current file are 
   discarded. Of course any saved file versions (created during the edits) are 
   not discarded.


EDIT MENU

+image: ug-edit.png

ROTATE
   +image: rotate.png
   To level a slanted image, use the mouse to drag the right or left side of the 
   image up or down until image looks 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.
   
   Use the 90º and 180º buttons to upright an image made with the camera turned. 
   The input widget can be used to enter any angle - this spin button responds 
   to the mouse wheel and the up/down arrow keys.
   
   The mirror buttons flips the image left-right or up-down. Photos will never 
   be inverted in this manner, but the user can do this if wanted.

   The [Auto Level] button can automatically level the image if the camera 
   recorded EXIF 'roll angle' in the EXIF metadata. The [Auto Upright] button 
   can automatically upright an image made with the camera turned, if 
   'orientation' is present in the EXIF metadata.

   If the rotation is exactly 90 or 180 degrees, no resolution is lost, because 
   pixels are replaced 1:1. For other angles, loss of resolution is < 1/2 pixel.

UPRIGHT
   This is a 1-button fix for an image that is rotated or inverted (mirrored). 
   The image file is fixed on the disk. There is no loss of resolution since 
   pixels are copied 1:1 to the new image layout. This is not an edit function 
   and no record is added to EXIF edit history. See also the function 
   \>BATCH UPRIGHT\>.

CROP
   +image: crop.png  +image: crop-buttons.png
   Use this function to cut off unwanted areas from the image top, bottom, or 
   either side. When the dialog opens, a selection rectangle is placed over the 
   image. Areas outside this rectangle are darkened and represent the parts of 
   the image that will be removed. Drag any side or corner of the rectangle to 
   move that side or corner. The dialog box shows the current width/height ratio 
   of the selection rectangle. If "Lock" is checked, then moving a side or corner 
   will cause another side or corner to move, so that the fixed width/height 
   ratio is maintained. Drag from the middle (marked by a small circle) to shift 
   the whole rectangle without changing dimensions. Use the width and height spin 
   buttons to adjust the image pixel dimensions directly. or enter the desired 
   values. The selection rectangle will adjust to these values.

   Use the keyboard arrow keys to move the selection rectangle in 1-pixel steps. 
   The last side or corner moved with the mouse is the one that is moved with 
   the arrow-keys.

   The [Max] button resets the crop rectangle to the full image size. If a 
   previous edit (Rotate, Warp ...) has left transparent margins around the 
   image, the crop rectangle will find the maximum size fitting within these 
   margins.

   The [Prev] button retrieves a list of previously used width and height values. 
   Select from the list to put these values into the dialog width and height 
   controls.

   If "Auto" is checked, the crop rectangle is set to the maximum size for the 
   current image center and width/height ratio, without overlapping any 
   transparent margin area. Drag from the center to find the best tradeoff 
   between image center and maximum crop rectangle size.

   The five ratio buttons allow you to choose a preset width/height ratio. The 
   [invert] button inverts the current width/height ratio. You can change the 
   ratio button names and corresponding ratios with the button [customize], which 
   starts a new dialog shown on the right. Enter desired button labels in the 
   first row, corresponding width/height ratios in the second row (the default 
   names are the same as the ratios).

RETOUCH
   +image: retouch.png
   Adjust image brightness and color.
     • auto black level - set black point using % darkest RGB values found
     • auto white balance - set white point using % brightest RGB values found
     • click gray spot for white balance - press button, click gray spot on image
     • click dark spot for black level - press button, click dark spot on image
     • click for RGB distribution - press button for popup graph
     • brightness - moves the entire 'all' curve up or down (all colors change)
     • contrast - changes the slope of the 'all' curve
     • color saturation - change saturation (black & white <--> intense colors)
     • color temperature - change RGB illumination balance (warm <--> cool)
     • settings file - load or save dialog settings for use with later edits

   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. The ALL curve 
   adjusts all colors, and the 3 RGB curves adjust individual colors. Use ALL 
   first, then make revisions using RGB.

   \bSettings File
   Load button - load all dialog settings (including the curves) from a file
   Save button - save all dialog settings to a file chosen by the user
   This can help when the same or similar settings can be used for other photos.

   \bButtons
   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

   Use the [Prev] button when processing multiple images needing similar 
   adjustments.

RESCALE
   +image: rescale.png
   This function rescales the image to a new pixel width and height. You can 
   input the new dimensions directly or choose a percent change. Buttons are 
   present for setting the new size to a simple ratio of the original size. 
   Using one of these will minimize loss of resolution. The [Previous] button 
   recalls the previous size, a convenience if multiple images are being set to 
   the same size. If the lock ratio box is checked, the current width/height 
   ratio will be preserved if either width or height is changed. The change is 
   made immediately, but the image will look the same unless it becomes smaller 
   than the window. Resizing an image requires enough memory to hold both the 
   original and the new image for a short time. Use of [2/1] or [3/1] with an 
   image that is already very large may result in failure for lack of memory. 
   A 50 megapixel image rescaled to 2x needs 3.2 GB memory, in addition to the 
   0.8 GB for the original image.

MARGINS
   +image: margins.png
   Use this function to add margins around an image. You can use any color and 
   alpha (transparency) settings for the margins. Set each margin separately, 
   or use the controls 'All±1' and 'All±10' to adjust all margins up or down by 
   the same amount, 1 or 10. Use the mouse wheel or up/down arrow keys for speed.
   
   Use this function to add margins around images that you plan to warp, to 
   prevent some pixels from falling off the edges. 

MARKUP
   +image: markup.jpg
   This is a menu containing the image markup functions:
      draw text, draw line/arrow, draw box, draw oval
   These are described immediately below. All of these functions have an [apply] 
   button which commits the current edit and lets you begin a new one (new text, 
   line, box, oval) within the same edit dialog. Press [done] to commit the last 
   edit and close the dialog. The logical next step would be to save as new v
   ersion or new file, or begin a new edit.

   +image: draw-text.jpg
   This function draws 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 angle of the shadow. Use the emboss controls to give 
   the text a 3D look.

   You can initialize the text from any available metadata in the image file. 
   Enter the metadata key (e.g. "user comments") and press [Fetch]. You can 
   abbreviate key names, e.g. "usercomments" instead of "User Comments".

   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 buttons at the bottom work as follows:
      • Clear - clear the text and metadata fields to blank
      • Replace - image with added text replaces the current image file
      • +Version - image with added text is saved as a new file version
      • Next - open next image file, place the same text at the same position
      • Apply - commit the current edit and start over: enter new text
      • Done - complete the current edit - image is ready to save
      • Cancel - abandon the current edit

   To add the same text to a series of images: prepare and position the text, 
   press [Replace] or [+Version], then [Next], then [Replace] or [+Version], 
   then [Next] ...

   Make a watermark: Use a text transparency of 70% or more and a background 
   transparency of 100%. The text should be faintly readable. Use the emboss 
   controls to make the text appear to be recessed into the image.

   +image: draw-line.png
   This function draws 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. Drag from the middle of 
   the line to move without changing the angle or length. The dialog controls 
   allow you to provide a background color, an outline color, and a shadow effect. 
   You can select 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. To keep a drawn line and begin another one, press 
   [apply].

   +image: draw-box.png
   Choose a color and width for the box outline. Place the cursor at the position 
   where you want a box corner, and drag to open the box in the wanted direction. 
   To replace the box, drag again. To move the box, hold the shift key and drag 
   the box from the center. To move one of the edges, hold the shift key and drag 
   the edge. To keep a drawn box and begin another one, press [apply].

   +image: draw-oval.png
   Choose either the oval (ellipse) or circle checkbox. Choose a color and width 
   for the outline. Place the cursor at the desired center. Drag to draw the 
   oval/circle. The drag angle determines the shape of the oval, from circle to 
   extreme ellipse, wide or tall. To replace the oval/circle, drag again. To move 
   the oval/circle, hold the shift key and drag from the center. To change the 
   size or shape, hold the shift key and drag from the lower right edge. To keep 
   a drawn oval/circle and begin another one, press [apply]. For an oval, you can 
   enter an angle 0-90 degrees for slanted axes, as in the example.

COLOR MODE
   +image: color-mode.png  +image: color-mode2.png
   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 (for an 
   aged photo effect).

   Select one of the buttons:
      • reset - return the image to the original state
      • black/white positive - convert a color image to black and white
      • black/white negative - convert to black and white and invert brightness
      • color negative - replace each RGB color with its compliment
      • RGB -> GBR - red/green/blue colors are replaced with green/blue/red 
      • RGB -> BRG - red/green/blue colors are replaced with blue/red/green 
      • sepia - convert to a modified black and white for an aged photo effect

   The slider can be used to apply the effect incrementally, from 0% to 100%.

   Color negative: Each RGB color is replaced with the maximum value minus the 
   RGB color value. For example, if the RGB colors (% of maximum) are 20/40/60, 
   then the negative color is 80/60/40. For pure RGB colors, red becomes cyan, 
   green becomes magenta, and blue becomes yellow.

PAINT IMAGE
   +image: paint-image.jpg
   This function paints over the image with selected colors, using the mouse.

   The Paint Color button shows the current color. Click this button to choose a 
   color using the standard Gnome color chooser dialog. You can also shift + 
   left-click on the image to choose a color from the image.

   The palette button opens the dialog shown in the middle. Click on the image to 
   select the color at that position. The chosen color is reflected in the color 
   button of the main dialog. The image shown above is the default. You can use 
   any image as a color source. Press the [browse] button and select an image 
   where you have saved colors for recall. This choice remains in effect until 
   changed.

   The HSL button opens an HSL color chooser shown on the right. This dialog can 
   represent any possible color. Move the sliders to get the color you want. The 
   chosen color is reflected in the color button of the main dialog.

   The brush size 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 (undo the painting). 
   The opacity controls determine how rapidly the color is applied (or erased) at 
   the center and edges of the mouse circle. 100% opacity applies the full color 
   immediately, and a low value allows you to gradually change the color using 
   multiple drags (like spray painting from a distance). Erase also works this 
   way: use 100% opacity to erase rapidly, and a low value 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.

   If paint over transparent areas is selected, painting over transparent areas 
   will reduce or eliminate the transparency, depending on the opacity controls. 
   If this option is not selected, only opaque areas of the image are painted.

   The [undo-last] button reverses the last paint or erase operation, and this 
   can be repeated to remove many recent edits. Each new mouse drag operation is 
   a unit of work that can be separately reversed. The memory for undo is 
   limited, so only the most recent paint and erase steps are kept. [undo all] 
   will put the image back in its initial condition.

   You can use the zoom image buttons to zoom the image larger or smaller as 
   needed. If drag image is selected, you can pan or scroll a zoomed image by 
   dragging it with the mouse. This stops the drag from painting or erasing.

   If a \>SELECT AREA\> is active, the painting is confined within the area.

   \bWacom Tablet Operation
   With Paint Image, you can use a Wacom tablet instead of a mouse. Dragging the 
   stylus in contact with the tablet surface will paint as described above. If 
   one of the stylus buttons is held down while dragging, the operation will be 
   erase instead of paint. You can also set paint or erase mode using the radio 
   buttons in the dialog. Holding down a stylus button is cumbersome, which is 
   why the radio buttons are there. Adding pressure to the stylus will increase 
   the opacity, so you can make lighter and darker strokes without adjusting the 
   opacity controls.

PAINT EDITS
   +image: paint-edits.png
   Use this function in combination with some other edit function. Start an edit 
   function and leave the controls in a neutral position. Then start Paint Edits. 
   Specify a mouse radius and power factors for the mouse center and radius edge. 
   The mouse pointer will be surrounded by a circle with the specified radius. 
   When the mouse is left-dragged over an area of the image, the current edit 
   function is applied within the circle. The strength of the function is 
   regulated by the center and edge power factors. Usually 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, and 
   brightness is increased, then the image will brighten within the mouse area 
   as the mouse is dragged.

   Use the [undo] and [redo] buttons to monitor the change, which at first may be 
   hard to see. Set the center power to 100 to make faster changes (with less 
   fine control). Use right-drag to weaken or ultimately erase the edit. When 
   done using one edit function in one or more image areas, use the edit dialog 
   [done] button to complete the edit.

   A suggested approach:
   (1) start the edit function
   (2) start the Paint Edits dialog
   (3) adjust the edit dialog settings
   (4) drag the mouse over the desired image areas and watch the effect
   (5) right-drag to weaken or erase the changes
   (6) adjust the edit settings for the next drag
   (7) alternate among steps 4/5/6 to optimize results
   (8) close Paint Edits - the edit function is also closed

   This method to "paint" edits incrementally can improve selected areas of an 
   image quickly and easily. 
   It works with the following edit functions:
      Edit > Retouch, Color Mode
      Repair > Sharpen, Blur, Denoise, Defog, Adjust RGB, Adjust HSL
      Refine > Edit Distribution, Flatten Distribution, Local Contrast, 
               Gradients, Local Retinex, Saturation, Soft Focus
      Effects > Emboss, Texture, Color Depth, Shift Colors

   See the following functions for alternative methods to make localized edits:
   \>SELECT AREA\>      make edits confined within a pre-selected image area.
   \>STACK/VERSIONS\>   make multiple image versions and 'paint' where each 
                        version is displayed on the image.
   \>COPY IN IMAGE\>    copy from one image area into another area by 'painting'
                        with the mouse.
   \>COPY FROM IMAGE\>  same as above, but source is another image, and scale 
                        of transfer can be varied.

PAINT TRANSP
   +image: paint-transp.png  +image: paint-transp2.png
   Paint transparent or semi-transparent areas on an image. Such areas are 
   useful in the Fotoxx Mashup function, where images or background underneath 
   a transparent area can show through. Other image editors can also use 
   transparent areas.

   The paintbrush radius control sets a circle around the mouse pointer which 
   shows the area being transformed. Left drag on the image to increase the 
   transparency, right drag to decrease. If gradual paint is checked, the 
   strength controls determine how rapidly the transparency changes at the center 
   and edges of the circle. If gradual paint is not checked, transparency is set 
   to 100% (left drag) or 0% (right drag) for the entire  area covered by the 
   mouse circle.

   If a \>SELECT AREA\> is active, only the selected areas are affected.

   An image file having transparency information must be saved as a TIF or 
   PNG file. JPEG files do not support transparency.

COPY IN IMAGE
   +image: copy-in-image.png

   Paint over image areas by copying from elsewhere in the same image. This 
   method can be used to duplicate objects within an image, or erase an unwanted 
   object by replacing it with background taken from elsewhere. In the above 
   example, the right balloon was copied from the left balloon, with care taken 
   not to let the area being copied move outside the baloon edges.

   Left-click on the image to select a source location, then right-click to 
   select the corresponding destination. Drag over the image area to be painted. 
   The source area is painted over the dragged area, immediately or gradually, 
   depending on opacity settings. The source or destination location can be set 
   independently with left or right click, respectively.

   Copy source location to destination location using one or multiple drags:
      left-click source location
      right-click corresponding destination
      drag over destination to copy source pixels
      shift mouse location and drag again to copy shifted source location
      repeat

   Copy the same source location to multiple destinations:
      left-click source location
      right-click corresponding destination
      drag over destination to copy source pixels
      right-click new destination
      drag over destination to copy source pixels from same area as before
      etc.

   The brush size control sets a circle around the mouse pointer which shows the 
   area being painted or erased. Left drag on the image to paint, or right drag 
   over previously painted areas to erase (undo the painting). The opacity 
   controls determine how quickly the image is modified (or erased) at the center 
   and edges of the circle. 100% opacity paints fully and immediately, whereas a 
   low value allows you to gradually paint using multiple drags. Erase also works 
   this way: use 100% to immediately erase, and a lower values to erase gradually.

   The [undo-last] button reverses the last paint operation, and this can be 
   repeated to remove many recent edits. Each new mouse drag operation is a unit 
   of work that can be separately reversed. The memory for undo is limited, so 
   only the most recent paint steps are kept. [undo all] will put the image back 
   in its initial condition.

   If paint over transparent areas is selected, painting over transparent areas 
   will reduce or eliminate the transparency, depending on the mouse opacity 
   controls and the gradual paint setting. If this option is not selected, only 
   opaque areas of the image are painted.

   If a \>SELECT AREA\> is active, the painting is confined within the area.

COPY FROM IMAGE
   +image: copy-from-image.png  +image: copy-from-image2.jpg
   Paint over image areas by copying from another image. The target image is 
   'painted' by dragging the mouse over the area to be modified. A previously 
   selected position in the source image is painted over the target image. The 
   area being copied and the area being painted are both enclosed in circles 
   which move with the mouse, representing the extent of the 'paint brush'. In 
   the above example, the rightmost boat in the right image was copied to the 
   left image.

   Start by opening the target image (the one that will be painted). Select the 
   menu 'Copy From Image'. A 2nd Fotoxx session is started showing the same image. 
   In this 2nd session, navigate to the source image and open it. Arrange the two 
   windows so you can keep both of them in view. Shift + left click the source 
   image to establish a reference position. Shift + left click the target image 
   at the position corresponding to the source image reference position. 
   Left-drag the mouse over the target image area. Pixels from the source image 
   are copied to the target image. Mouse circles are visible on both images and 
   represent the areas being copied from and to. Right-drag to erase (restore the 
   original target image). To change the source or target copy positions, repeat 
   the two left-clicks as needed. Zoom the images to max. size if high precision 
   is needed for the reference positions. The initial reference position is (0,0) 
   (NW corner) for both images. You do not need to invest time to establish 
   precise reference positions if the two images overlay naturally, as with 
   edited versions of one image.

   The brush size control sets the size of the circle around the mouse pointer, 
   which shows the area being painted or erased. Left drag on the image to paint, 
   or right drag over a previously painted area to erase (undo the painting). 
   The opacity controls determine how quickly the image is modified (or erased) 
   at the center and edges of the circle. 100% opacity paints fully and 
   immediately, whereas a low value allows you to gradually paint using multiple 
   drags. Erase also works this way: use 100% to erase immediately, and a low 
   value to erase gradually.

   The [undo-last] button reverses the last paint operation, and this can be 
   repeated to remove many recent paints. Each new mouse drag operation is a unit 
   of work that can be separately reversed. The memory for undo is limited, so 
   only the most recent paint steps are kept. [undo all] will put the target 
   image back in its initial condition.

   The source image scale value is used to scale the source image to the target 
   image. Start by making a trial copy to check the scale. If too big or too 
   small, use [undo all] to erase the trial, change the scale value, and try 
   again.

   If paint over transparent areas is selected, painting over transparent areas 
   will reduce or eliminate the transparency, depending on the mouse opacity 
   controls. If this option is not selected, only opaque areas of the image are 
   painted.

   If a \>SELECT AREA\> Is active, the painting is confined within the area.

COPY PRIOR EDIT
   +image: copy-prior-edit.png
   The image from a previous edit step can be applied to the current image 
   locally and gradually, by "painting" with the mouse. The previous edit must 
   be one of the edits made to the current image while it is still open (unsaved 
   edits are lost when a new image is opened). Thus you can apply any previous 
   edit to any area of the current image being edited, as long as the image 
   remains open as the current image. Select a previous edit using the dropdown 
   list which shows all previous edit steps done on the current image, in 
   sequence, and identified by the edit function used.

   The mouse pointer will have a circle around it with the given radius. As the 
   mouse is dragged, areas within this circle are gradually restored to the 
   status of the selected previous edit. Left drag to 'undo' or remove the edit, 
   right drag to 'redo' or restore the edit. The rate of change is regulated by 
   the center and edge power factors. Typically you will use a high value at the 
   center and zero at the edge, meaning that the rate of change will be maximum 
   at the center, changing gradually to zero at the edge of the mouse circle.

   You can also use \>SELECT AREA\> to restrict edits to selected areas of an 
   image, rather than painting over them afterwards. Use \>AREA BLEND\> afterwards 
   to blend or trim the edges if needed. 

PLUGINS
   +image: plugins.png  +image: plugins-edit.png
   
   Plugin functions are a way to use other image editors within Fotoxx. You can 
   use the image and collection management functions of Fotoxx with other 
   programs that only do edits, e.g. Gimp. You can use a RAW image editor like 
   Rawtherapee and then perform additional edits using Fotoxx.
   
   The usage procedure is:
      1. Open the file to be processed in Fotoxx (the current file).
      2. Start the plugins menu and select the desired program, e.g. Gimp
      3. The plugin program starts and opens the file passed from Fotoxx
      4. Perform the desired edits using the plugin program
      5. When done, save the output file with the same name or base name as the 
         input file (intermediate file name 'fotoxx-plugin-file'). The file .ext 
         can change, e.g. .jpg --> .tiff. The parent folder should not be changed.
      6. Close the plugin program.
      7. Fotoxx opens the plugin output file as an edited version of the current 
         file. The file .ext may have changed.
      8. Perform additional edits, or save the edited file as a new version or 
         new file.
   
   An example Plugins menu is on the left. The top entry "Edit Plugins" starts 
   the text edit application on the right. Use the text editor to define the 
   plugin menu names and the commands to start the corresponding plugin programs. 
   The format is:
         menuname = plugin-command %s
         TIP = explanation of above command
   The 'plugin-command' is the shell command for the plugin function, and '%s' 
   is where the current file name is inserted into the command. Do not put quotes 
   around the '%s' because this is added automatically, allowing file names with 
   blanks or other special characters to be processed. The top example shown is a 
   menu named "Gimp" which starts the command "gimp %s". The TIP text is optional. 
   If present, it is on the next line following the menu name. Hovering the mouse 
   over the menu entry will show this text next to the menu text. 
   
   Some commands may expect both input and output files to be specified. In this 
   case supply '%s' in both positions. The output file will replace the input, 
   but this is not a problem because an intermediate file name is used.
   
   You may omit '%s' if the command does not process an image file.
   
   \bSelect Area
   If the input file has a selected area, the plugin function will only be done 
   on the selected area. Within the plugin window, the entire image will be 
   edited, but when the output is returned to Fotoxx, unselected areas are 
   restored to the original state.

EDIT TEMPLATE
   This is a dummy edit function that is included in the developer menu only.
   The purpose is to provide a template for coding a new edit function.


REPAIR MENU

+image: ug-repair.png

SHARPEN
   +image: sharpen.png

   This function has five methods to sharpen a blurry image, and a method to 
   sharpen motion blur from camera motion or subject motion during exposure.

   \bSharpen - General Blur
   Choose the method, set the parameters, press [apply] 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.

   For all methods, choose a small radius for images that are slightly blured and 
   a larger values 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.).

   Unsharp mask: a fast and effective method also found in other image editors. 
   A technical description can be found with a web search. This method can make 
   visible 'halos' around high-contrast edges.

   Gradient: steepens brightness transition areas directly, somewhat like the 
   Gradients function. Effectiveness is comparable to unsharp mask, but 'halos' 
   are reduced.

   Kuwahara: small neighborhoods of pixels above, below, left and right of each 
   pixel are compared to each-other. The pixel is given the mean color of the 
   neighborhood with the smallest difference 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. Image may appear 'blocky' if a large radius is used. Subtle 
   details can be lost.

   Mean diff: pixel brightness is compared to the mean of pixels within radius. 
   The brightness is increased or decreased for pixels respectively brighter or 
   darker than the neighborhood mean. Effectiveness is comparable to unsharp mask, 
   but 'halos' are greatly reduced. This is the only method that works on each 
   RGB color separately. It can sharpen a color transition even if there is 
   little brightness change.

   Richardson-Lucy: the image is sharpened using the Richardson-Lucy 
   deconvolution method. This method may produce good results, but is also very 
   slow - run time is proportional to (image size) x (radius) x (iterations). 
   To speed things up, start by selecting a small but busy area of the image 
   using \>SELECT AREA\>. Hunt for the optimum radius and iteration count using 
   this small area. Then use the same settings for the full image. Noise in the 
   image will hamper effectiveness. If so, use \>DENOISE\> beforehand. If only a 
   part of the image needs sharpening (e.g. outside camera depth-of-field), use 
   select area for this area only.

   \bFix Motion Blur
   +image: fix-motion-blur.png  +image: fix-motion-blur1.jpg
   This is a tool to hand-optimize images with minor blur from camera motion. 
   Blur from a moving object in an otherwise sharp image can be processed using 
   \>SELECT AREA\> to isolate the object. Blur is assumed to be linear and 
   constant velocity. The inputs are 'blur span' in pixels and 'blur angle' in 
   degrees. The initial angle estimation can be specified by shift + mouse drag 
   across the image in the blur direction (can be the same or opposite to the 
   actual camera motion). Input an estimate of the blur span by using 
   Tools > Show RGB to measure the width of blur along some bright image feature 
   edge. Adjust these inputs, press [apply], and watch the image to find optimum 
   settings. The response time may be slow for a large image. You can speed up 
   the process if you use \>SELECT AREA\> to select a small blurred area to 
   optimize span and angle, then clear the area to process the whole image using 
   the same settings. The algorithm produces "ringing" noise, which can be 
   suppressed using the input 'suppress ringing'. It works best to leave the 
   suppress value low to find the optimum span and angle, and then add 
   suppression as needed to reduce ringing. The Richardson-Lucy deconvolutioin 
   method is used.

   \bDigital Camera Blur
   Not all blurred photos are the kind of "pure" blur that is best suited for 
   this method. The image may be a superposition of multiple shorter exposures. 
   The entire image may not have been exposed at the same time and have the same 
   blur (mechanical or electronic moving shutter). This method may still produce 
   better results than nothing, or sharpen tools that work in all directions 
   (these make feature edges sharper but do nothing to recover lost detail). It 
   should work better on old photos made with film cameras.

BLUR
   +image: blur.jpg
   Choose a method with the corresponding check-box, input the required 
   parameters, press [apply]. If \>SELECT AREA\> is active, only the selected 
   areas are affected.

   \bNormal Blur
   Mix each pixel with surrounding pixels within radius. Closer pixels have a 
   higher weight. You can set the radius to 1 and press [apply] repeatedly to 
   increase the blur slowly while you monitor the image result. This method can 
   also be used with \>PAINT EDITS\> to paint blurred areas on the image using 
   the mouse.

   \bRadial Blur
   Mix each pixel with pixels along a line from a chosen center. Radius defines a 
   central area that is not blurred. Length sets the blur line range: 0-length 
   from center to edge. Choose the center by clicking on the image.

   \bDirected Blur
   Pull a position on the image using the mouse. The area around the mouse will 
   be blurred in this direction. Span determines the size of the area blurred. 
   Intensity determines the strength of the blur.

   \bGraduated Blur
   Only pixels with less contrast than the given contrast 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 to smooth skin tones without blurring hair or reducing the sparkle in 
   the eyes. Taken to extremes, it produces a "cartoon" effect.

   \bBackground Blur
   Blur background image areas while leaving the foreground sharp. Select one or 
   more areas that are to remain sharp (menu Areas > Select). After selecting the 
   foreground areas, invert the selection so that the background is now selected 
   (Areas > Invert). This is the area that will be blurred. There are two blur 
   methods available: Constant blur: a constant blur radius is used for all areas 
   blurred. Increase blur with distance: use the minimum blur radius for pixels 
   adjacent to the foreground and the maximum blur radius for pixels at the 
   maximum distance from the foreground. This requires that the edge distance for 
   all background pixels be calculated, which can take significant time for a 
   large image. Blur radius can be varied without recalculating edge distances. 
   Tilt-Shift Effect: You can do this by selecting a horizontal rectangular area 
   to remain sharp, and increasing the blur with increasing distance from this 
   area.

   \bAdd Motion Blur
   +image: add-motionblur1.jpg  +image: add-motionblur2.png
   This tool adds motion blur to an image. Motion blur is blur in a single 
   direction. Image feature edges perpendicular to this direction have maximum 
   blur. Those parallel to the blur direction remain sharp. Use \>SELECT AREA\> 
   to isolate image areas to blur separately from the unchanged background.

DENOISE
   +image: denoise.jpg
   This function reduces the noise in photos taken in low light conditions 
   (high ISO), making uniform surfaces appear speckled. Multiple methods are 
   provided because the best method varies with noise characteristics. Mixing 
   methods (using one and then another) can be helpful. Choose the method, set 
   the radius and threshold parameters, and press [apply]. Each new [apply] uses 
   the modified image from the previous [apply], so each use will have increasing 
   impact. With a large image, some methods may be slow. To save time, select a 
   small representative area and experiment with the different methods and 
   settings until you make a decision, then apply the chosen method to the entire 
   image. Remember also that you can apply different methods to different areas 
   of the image, and you can "paint" the image using different methods on 
   different areas (see \>PAINT EDITS\>).

   The threshold value is the pixel brightness difference above which no change 
   is made. The initial value is set from a preliminary noise analysis of the 
   image. Threshold regulates a tradeoff between noise removal and loss of 
   low-contrast details.

   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 
   are processed.
   
   The flat areas slider can be used to restrict the process to flatter image 
   areas, i.e. areas with low brightness/color variation. These are the areas 
   where noise is most visible. This also helps to preserve fine detail. 

   Here is a short technical description of each method:
      • Voodoo
        This is a fixed combination of the other methods to serve as a 
        one button" method. Try this first. It is adequate for many cases.
      • Chroma
        This works like Anneal, but uses the YCbCr color space instead of RGB.
      • Anneal
        Pixels are blended with surrounding pixels that have similar color and 
        brightness. This reduces noise with minimal blurring of feature edges.
      • Flatten
        Pixels are set to the mean of their best-matching opposing pairs of 
        neighbors at distanct = radius. Good for fine-grain noise. Good at 
        preserving detail.
      • Median
        Pixels are set to the median value of their neighbors within a radius.
        Good for 'salt and pepper' noise - set threshold high.
      • SNN (Symmetric Nearest Neighbor)
        For each target pixel, all pairs of opposing neighbors within radius are 
        compared and the best match from each pair is chosen. The target pixel is 
        replaced with the average of the chosen pairs. Threshold is not used.

   The [measure] button starts the lower dialog to measure the actual image noise 
   level. Move the mouse over the image to show the RGB noise levels within the 
   mouse circle (radius 10, about 300 pixels). This must be a featureless area 
   so that noise is the only variation present. An area that has a uniform 
   brightness and color and is also badly out of focus would be suitable. The 
   dots show individual pixel RGB values relative to the mean, represented by the 
   central solid line. The numbers at the bottom show the mean RGB brightness 
   and noise levels on the scale 0-255. To measure camera sensor noise, use a RAW 
   image, since JPEG images are processed inside the camera to reduce noise. More 
   information about camera noise in RAW images can be found in \>TECHNICAL TOPICS\>.

DEFOG
   +image: defog.png +image: defog2.png
   This function can be used to remove fog/haze in an image or selected area. 
   There are other tools for this (flatten, local contrast, gradients, retinex, 
   saturation), but fog/haze removal is secondary to their primary function. This 
   function attacks fog/haze directly: it removes equal amounts of R/G/B color, 
   and optionally adds-back the lost brightness, preserving the new RGB ratios. 
   It can also reduce blue if this becomes too dominant, as often happens with 
   distant haze. The edit curve Y-axis is fog/haze, from zero to max. removal. 
   The X-axis is pixel brightness, from dark to maximum brightness. Thus you can 
   vary fog/haze removal by pixel brightness. Move the curve and watch the image 
   result. Edit the curve to vary the effect for darker or lighter image areas. 
   Add brightness if the image becomes too dark, and reduce blue if the image is 
   dominated by blue. Juggling the curve and the two sliders is complex and you 
   may need time to find an optimum. You may need to use \>SELECT AREA\> or 
   \>PAINT EDITS\> to precisely target and optimize the desired areas. The above 
   example used two areas, the forground hills and the background mountain.

RED EYES
   +image: red-eyes1.png  +image: red-eyes2.png
   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 more 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.

SMART ERASE
   +image: smart-erase.png   +image: smart-erase2.png
   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. 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 unselects. 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 main menu 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. 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.

   For long thin objects (e.g. power lines), you can click on two ends and 
   everything in-between will be selected. The selection works in a straight 
   line, so for curving objects you will need to click at intervals to follow 
   the curve.

REMOVE HALO
   +image: remove-halo.png  +image: remove-halo2.png
   This function can remove halos left by sharpen, gradients, local contrast, 
   and some other edit functions. Often images from the internet will have this 
   problem because they were sharpened using the classic 'unsharp mask' method. 
   Left-drag the mouse over the halo area to darken the brightest pixels inside 
   the mouse, as shown in the above example image (exaggerated for clarity).

JPEG ARTIFACTS
   +image: jpeg-artifacts.png +image: jpeg-artifacts1.png
   JPEG images that have been highly compressed can show compression artifacts 
   in the form of small rectangular blocks. If dark areas of a photo have been 
   brightened, such blocks may become more visible because the brightness steps 
   are larger (e.g. RGB values of 11/12/13 brightened 5x to 55/60/65). This 
   function blurs the borders between the blocks to make them less visible. 
   
   'Match Limit' determines when adjecent pixels are treated as members of the 
   same pixel block. Most blocks will not have any pixel differences, but some 
   blocks will have a small 'slope' between opposite sides (a JPEG compression 
   method). Other differences may be caused by an image rescale, where pixel 
   interpolation causes adjacent tones to leak into the block. Match Limit can 
   be set to a lower value to get such blocks more completely mapped. 
   'Contrast Limit' serves to prevent blending of edges where contrast is high, 
   causing loss of detail. Change the two settings and press [apply]. View the 
   resulting image at >2x size and try different settings if optimization is 
   important.
   
   This function will be less effective on an image that has been rescaled. 
   Use \>SELECT AREA\> to selectively process problem areas. 
   
ANTI-ALIAS
   +image: anti-alias.png
   Sometimes photos show pixelation (or 'jaggies') along some high-contrast 
   feature edges. In the example above, you can see this around the bird's eye. 
   The anti-alias tool can elimnate some of this. The effect is minor on most 
   photos, where in-camera processing may have already taken care of the problem. 
   A secondary effect is that jpeg artifacts in highly compressed images are 
   somewhat smoothed over. Images that have been scaled-up in size will have more 
   prominent pixelations. These can be helped. 
   
   Use the [apply] button to suppress the pixels, multiple times if this seems 
   to help. 'Threshold' can be used to exclude low-contrast pixels from 
   processing. A value of 0.1 or less is usually best. 

   Another method to suppress pixelation is to use \>BLUR\> (normal blur) with 
   radius 1. This method will also slightly reduce the visibility of fine details. 
   
   Fotoxx uses the Scale3x algorithm, modified to use "similar" and "different" 
   color tones in place of "equal" and "not equal". 

ADJUST RGB
   +image: adjust-RGB.png
   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 same) 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 color and change the 
        complimentary color in the opposite direction
      • Contrast All
        Increase or decrease the overall image contrast
      • Contrast Red, Green, Blue
        Increase or decrease the contrast of individual RGB colors

ADJUST HSL
   +image: adjust-HSL.png
   Change a selected range of colors in an image using HSL (Hue, Saturation, 
   Lightness). This function can be used to fix a color caste or change one color 
   to another (e.g. an overexposed sky - too white). If you are not familiar with 
   the HSL color model, I suggest you read the Wikipedia article about this.

   Begin by selecting a target image color to match and adjust, using shift + 
   left-click on the image. This color will be the center of a range of colors 
   that will be selected for adjustment. Select what color attributes will be 
   matched using the checkboxes for hue, saturation, and lightness. Each of these 
   will narrow the range of selected colors. If none are checked, all colors are 
   selected. Match Level can be used to further widen the range of selected 
   colors. 100% means only closely matching colors are selected.

   The Output Color controls (hue, saturation, lightness) are used to set the new 
   output color which will replace or blend with the selected input colors. You 
   can also set this color from the image, using shift + right-click. The 
   resulting color will be a mix of the original color and the new color. The new 
   color fraction is set by the Adjustment slider, which can be set 0 to 100%. 
   Use the HSL checkboxes to determine which HSL components of input color are 
   replaced with the corresponding HSL components of the output color. Use the 
   sliders for output color HSL to adjust the new color. The output color is 
   shown in the smaller box on the left, which is updated as you move the sliders.

   Move the sliders and watch the live image updates to optimize the result. 
   This is not very intuitive, and practice will help.

   Hint: begin by matching on hue and saturation, and replacing only hue - this 
   means that the output color saturation and lightness will be copied from the 
   original image colors, and only the hue will be replaced.

   This function can be used with \>SELECT AREA\> to restrict the change to 
   selected image areas.

COLOR PROFILE
   Use this function to change the ICC color profile. If you have images with 
   Adobe RGB color, you can change to sRGB for better colors on a monitor, or 
   for uploading to a web site. Any EXIF embedded color profile is removed, and 
   the EXIF key "ICCProfileName" is set to the new profile. Because the relevant 
   metadata is changed, a new file version is created automatically, and the 
   input file is left unchanged with the old color profile. To view the color 
   changes, use the KB arrow keys to switch back and forth instantly between the 
   old and new images. The changes are usually very small.

   You may need to install ICC color profiles. In Ubuntu, the package names are 
   icc-profiles and icc-profiles-free.

REMOVE DUST
   +image: remove-dust.png  +image: remove-dust2.png
   Images made from dusty scanned slides can have many small dark spots - shadows 
   of the dust on the slides. Historical photos from the internet often have a 
   similar problem. 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 automatically removed, but Smart Erase 
   can be effective here.

CHROMATIC 1
   +image: chromatic1.png   +image: chromatic1A.png
   Fix lateral chromatic aberration - the type where color fringes appear mainly 
   in outer image areas. See below for axial chromatic aberration. If you are not 
   sure which function to use, try this one first since it is fast and easy 
   compared to the one below.

   The left image above is a magnified cutout of the top left corner of a photo 
   with lateral chromatic aberration. This was mostly eliminated in the processed 
   image to the right. 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. Press the [search] button. The red and blue color 
   planes are shifted to better align with the green plane, and the factors used 
   are stuffed into the dialog box. You may be able to improve the result by 
   revising the factors directly in the dialog: use the up/down arrow keys or 
   mouse wheel to change the factors while watching the color fringes on the 
   image. Modify the largest values (2.4 and 3 in the above example).

   Important: this function will not work well if the image has been cropped so 
   that the image center is no longer the same as the center of the original 
   photograph.

   \bMethod:
   The red and blue components of each pixel are shifted using the formula
       R2 = F1 * R1  +  F2 * R1 * R1  +  F3 * R1 * R1 * R1
   R2 is the shifted distance from the image center, R1 the original distance, 
   F1 - F3 are the factors to be discovered for each color red and blue. For a 
   perfect image, F1 = 1  and  F2 = F3 = 0. The algorithm tests a range of values 
   for F1 - F3, and retains the best values found. In each test, the image red or 
   blue plane is warped using the formula for R2, and the warped plane is 
   subtracted from the green plane. The best values for F1 - F3 are those where 
   the sum of the absolute pixel differences is minimum: the warped red and blue 
   planes overlap the green plane most accurately.

CHROMATIC 2
   +image: chromatic2.png  +image: chromatic2A.jpg
   Fix axial chromatic aberration - the type where a narrow color band runs along 
   dark/bright feature edges, or where narrow dark features are discolored by a 
   bright background. The cause can be camera lens aberration, light scattering, 
   or the camera sensor and its data processing.

   Select each of the three check buttons in turn, and click on the image to 
   select the corresponding color. Set the proximity value. Press [Apply]. 
   Pixels at or near the chromatic color will be replaced (hue only) with the 
   replacement color, but only where the background color (or near match) is 
   closer than the given proximity in pixels. The default 10 is normally OK. 
   The point here is to avoid changing unrelated pixels in other image areas. You 
   will normally have to select a new chromatic color and press [Apply] multiple 
   times, since only a narrow band of matching colors will be changed. Click the 
   chromatic color at any position that remains unchanged, and press [Apply] 
   again, until all the colored pixels have been replaced. In the above example, 
   with multiple shades of pink and green, 11 different selections were made over 
   a time of about 2 minutes. The [Undo] button will reverse the previous [Apply], 
   and can be repeated to reverse multiple changes. Color match level sets the 
   sensitivity of the color match. If unwanted pixels get changed, undo the 
   change and set a more exact match level, e.g. 80 instead of the default 70, 
   and repeat the [Apply] step. This match level is also used for matching the 
   background color.

   Tip: Use \>SELECT AREA\> to confine changes to an intended area. After 
   completing the edit, you can also use \>COPY PRIOR EDIT\> to remove changes 
   from unwanted areas.


REFINE MENU

+image: ug-refine.png

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

VOODOO 2
   This is an alternative automatic enhancement, using the flatten method 
   described below.

EDIT DIST
   +image: edit-dist.png   +image: RGB-dist.png
   Edit Brightness Distribution directly edits the shape of the brightness 
   distribution. Move the sliders and watch the image to find the optimum 
   settings.

   Cutoff: If the distribution is low or zero at the dark or bright end, you can 
   stretch the distribution to make it extend more into the dark or bright end, 
   or both.

   Flatten: This is a fast and easy way to compensate for a common limitation in 
   photos: the brightness range is inadequate and details are lost in image areas 
   having nearly the the same brightness. Pixel brightness is redistributed so 
   that each brightness level is more equally represented. Technically, the 
   brightness distribution is made more uniform (flatter). The selected 
   low/mid/high brightness region is flattened.

   Stretch: The selected low/mid/high brightness region is broadened, which 
   necessarily squeezes adjacent areas. For example, if you broaden the low 
   brightness region, darker areas of the image will have more contrast at the 
   expense of brighter areas.
   
   Low Cutoff Ramp-up: Pixels slightly above the low cutoff level are brightened, 
   so that detail in dark areas is preserved in spite of the low cutoff. This is 
   especially good for astronomical photos where the sky is gray from light 
   pollution and long exposure time. 

FLATTEN DIST
   +image: flatten1.png +image: flatten2.png
   Flatten Brightness Distribution increases visible detail in areas having poor 
   contrast. Pixels with little brightness difference compared to their 
   neighborhood are adjusted to increase the difference. Five zones can be 
   individually adjusted, e.g. only dark areas if this is where improvement is 
   needed. Use the 'all zones' slider to find an overall optimization, then 
   adjust individual zones to optimize further. A smaller radius will intensify 
   the effect. Adjust radius and press [apply] to updae the image.
   
   \bTechnical Explanation
   The brightness of a pixel is compared to the brightness distribution of the 
   surrounding area, and the brightness is adjusted up or down in the direction 
   that would flatten the distribution within this area (make a more uniform 
   distribution). This increases the mean brightness difference of pixels 
   compared to their neighborhoods. A smaller radius makes each pixel adjustment 
   depend on pixels closer to itself, and the effect on the image is more 
   dramatic.

LOCAL CONTRAST
   +image: localcon.png  +image: localcon2.png
   Local Contrast increases the contrast in every area of an image, using the 
   average brightness of an area to determine how much individual pixel 
   brightness values are to be increased or decreased. This function implements 
   a widely used textbook method. Radius controls the size of the area around 
   each pixel that is used for the average brightness value. Power determines the 
   strength of contrast change. Brighten is used to brighten the darker areas of 
   an image, which may become too dark after the contrast changes are made. 
   Color is used to increase the color saturation.

   Local Contrast can create "halos" under some circumstances:
   +image: localcon3.jpg
   The original image is on the left. The middle image had Local Contrast applied 
   at max. power. A halo can be seen along the border between the dark hills and 
   lighter sky. This can be fixed with a simple trick (right image). Select the 
   sky areas separately, using \>SELECT AREA\>. Apply Local Contrast to this area. 
   Invert the selection and apply Local Contrast to the rest of the image. 
   \>GRADIENTS\> was applied afterward to the entire image to increase details 
   in the darkened image.

GRADIENTS
   +image: gradients.png   +image: gradients2.jpg
   Gradients 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. Gradients increases the contrast between nearby pixels 
   without increasing the overall contrast. It relies on a characteristic of 
   human vision: contrast within a small angle is perceived more strongly than 
   contrast over a large angle. Gradients can bring out the subtle details 
   (low contrast) that would otherwise be hard to notice. Other methods can also 
   be used: \>RETOUCH\> can increase contrast for a selected brightness range 
   (at the expense of others). \>FLATTEN DIST\> can spread available contrast 
   more evenly. Gradients processes pixels relative to nearby surrounding pixels, 
   and is very 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 corresponds to 
   low-contrast pixels and the right end corresponds to high-contrast pixels. 
   Raise the left side of the curve to increase the contrast of low-contrast 
   pixels (but this will also increase low-level noise). The Amplify slider below 
   the curve regulates the 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 ugly artifacts, 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 
   may also need 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. conservative for sky, more aggressive for textured surfaces 
   like stone walls.

GLOBAL RETINEX
   +image: global-retx.png   +image: global-retx2.png
   Global Retinex can improve color and contrast for images with extreme fog/haze 
   or color cast (e.g. a 100 year-old photo). Try the [Auto] button first. The 
   image is searched to find the brightest and darkest RGB colors present. The 
   darkest RGB values are subtracted from all pixels and the resulting RGB values 
   are scaled up so that the maximum RGB values are near 255. Of course this may 
   not be initially optimum. The spin buttons are set to the dark and white RGB 
   limits found, and you can changes these to optimize the resulting image. You 
   can choose your own dark and bright points by selecting the corresponding 
   option in the dialog and clicking on the image. The multiplier spin buttons 
   are set to 1.0 by default, and you can change these values to adjust the 
   relative brightness of each RGB color. In the above example, the 1st image is 
   the original, the 2nd image was made using the [Auto] button, and the 3rd 
   image was made by selecting a bright spot on the turtle's shell as the bright 
   point and the shadow under the front left foot as the dark point. The 
   rightmost column of spin buttons will adjust all buttons in the same row 
   together - use the mouse wheel or the keyboard up/down arrow keys.

   The blend slider is used to mix the input image and the retinex image in any 
   ratio. The reduce bright slider is used to attenuate the effect for brighter 
   image areas, especially sky, where Retinex can produce strange looking 
   results.

   The algorithm was derived from concepts first published by Edwin Land in the 
   1970s. Search the web for 'retinex' to find more information.

LOCAL RETINEX
   +image: local-retx.png  +image: local-retx2.png
   Local Retinex can increase visible details in dark image areas and other areas 
   having low contrast. The brightness range of a zone around each pixel is used 
   to rescale the pixel brightness as though the entire zone were rescaled to 
   cover the entire 0-255 brightness range. Local Retinex can produce dramatic 
   results where Global Retinex is weak.

   The radius input determines the approximate zone size around each pixel. The 
   blend slider is used to mix the input image and the retinex image in any ratio. 
   The reduce bright slider is used to attenuate the effect for brighter image 
   areas, especially sky, where Retinex can produce strange looking results. The 
   reduce dark slider does the same for darker image areas. The example above is 
   about 60% original image + 40% retinex.

SATURATION
   +image: saturation.png
   This function is used to adjust color saturation based on pixel brightness. 
   The edit curve Y-axis is color saturation, from zero color (all RGB values 
   equal) to maximum color (lowest RGB value is zero). The curve X-axis is pixel
   brightness, from dark to maximum brightness. The neutral position (no color 
   change) is the midway value, which is also the initial value. Example: to 
   increase the color intensity of dark areas in the image, raise the left end 
   of the curve. The Saturation slider moves the entire curve up or down without 
   changing its shape.

SOFT FOCUS
   +image: soft-focus2.png   +image: soft-focus.png
   This function applies the classic "soft focus" effect to a photo. This is a 
   mixture of a sharp image and a slightly blurred image. Cameras from before 
   1900 had lenses with spherical aberration, producing a sharply focused image 
   from the central areas and an unfocused image from the periphery. This mixture 
   was sometimes seen as desirable and was done deliberately. Modern cameras may 
   use special lenses or filters for this effect. The Fotoxx function makes a 
   blurred image and mixes this with the input (sharp) image. The radius setting 
   determines the extent of blurring (pixel span), and the mix setting sets the 
   portion of the blurred image in the mixed output image, from 0 to 100 percent. 
   You can use \>PAINT EDITS\> with this function, to vary the effect for 
   different areas of the image.

MATCH COLORS
   +image: match-colors.png
   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. A common usage is to remove 
   a color cast from an image by marking a spot on the image that should have a 
   color taken from another image.

   Procedure: The dialog lists 5 steps to take in sequence.
      1  Set a radius for the spot sample.
         The resulting mouse circle 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 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 
         first image. The image colors will change within a second or two. You 
         can change the radius and click on another spot, and the colors will 
         change accordingly. Click the dialog [done] or [cancel] button to finish.

BRITE RAMP
   +image: brite-ramp1.png  +image: brite-ramp2.png
   This function varies brightness or color across the image. You can use this to 
   compensate for uneven lighting or a color cast that varies across the image. 
   The direction of change is determined by drawing a line on the image. Create 
   the line by clicking on the image, then drag either end to set the direction 
   wanted. In the example above, green is increased in the direction of the line. 
   Edit the All curve first to adjust overall brightness (all colors), then 
   adjust the individual RGB color curves if needed.

VIGNETTE
   +image: vignette.png +image: vignette2.png
   This function is used to correct the darkening sometimes seen in the corners 
   of a photo. It can also be 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 represent no change, and higher values add the chosen color to 
   the image. The highest value 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.

   \bIrregular Vignette
   +image: vignette3.png
   You can make a vignette with arbitrary shape as follows:
      • Select Area - select the image area to remain unchanged
      • Invert the area to select the areas outside the image
      • Paint Image - paint the outside areas with the desired color
      • Select > Area Blend, set the blend width to blend the edges with the 
        painted area


EFFECTS MENU

+image: ug-effects.png

SKETCH
   +image: sketch.jpg
   This function transforms a photo into something like a 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. Choose colors for foreground and 
   background. Two algorithms are provided. Results may look more interesting 
   with one or the other. Reducing the size of the input image may also give more 
   interesting results.

CARTOON
   +image: cartoon.png +image: cartoon2.jpg
   Transform a photo into a cartoon-like drawing. Black lines are drawn over 
   feature edges in the image, wherever the brightness or color changes abruptly. 
   Line Threshold sets the sensitivity for edge detection and line drawing, 
   causing fewer or more lines to be drawn. Line Width makes the lines thicker or 
   thinner. Blur Radius controls a blur function which can make the lines look 
   more curvy or less jagged. Kuwahara Depth controls a sharpen function which 
   can strengthen feature edges within the image.

   This function can be quite slow to respond (20+ seconds) if the image is large 
   and if kuwahara depth is set to a high value. I suggest you start with a small 
   value (2-3) for kuwahara depth, then adjust line threshold to optimize the 
   density of the drawn lines. Now change kuwahara in small steps and re-adjust 
   line threshold. If you are working with a large image, I suggest you select a 
   small but important area within the image so that optimization can proceed 
   faster. Then delete the area and do the entire image. You may be close to 
   optimum already. You can kill the process in mid-stream with the Escape key.

   Other edit functions, applied before or after Cartoon, may enhance the effect. 
   These include color saturation, gradients, color depth, texture, warp curved, 
   graduated blur (3rd image above). 'Copy in Image' is useful to remove minor 
   flaws manually. Shadows in the image are a particular problem, since they 
   cause lines to be drawn where not wanted.

DRAWING
   +image: drawing.png
   This function transforms a photo into a line drawing showing outlines of 
   objects within the image. Feature edges (sharp transitions in brightness or 
   color) are converted into color or black-white lines.

   There are two sliding controls.
      • Threshold: how bright a feature edge must be in order to get enhanced, 
        from "no edges" at the low end to "all edges" at the high end.
      • Line Width: width of the enhanced edges, from 1-pixel to about 5 pixels.

   The black/white checkbox converts the image from color to black and white, and 
   the negative checkbox makes a color or black-white negative image.

EMBOSS
   +image: emboss2.jpg    +image: emboss.png
   Transform an image into a simulated relief or embossed image (a 3D effect). 
   Feature edges are made brighter on one side and darker on the opposite, as if 
   raised up and illuminated from the side. The radius setting determines the 
   width of the effect, and the depth setting determines the intensity. The 
   Light Source setting determines the angle from which the apparent illumination 
   is coming. This can be varied to maximize the effect for feature edges most 
   perpendicular to this angle. The image is modified in real time as the 
   settings are adjusted. If the computer is slow and/or the image is large, 
   there will be a small delay in the image update.

TILES1
   This function transforms an image into an array of 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, e.g. a face.

TILES2
   +image: tiles2a.png  +image: tiles2b.png
   This function transforms an image into irregular tiles that roughly conform 
   to the colors and contours of the image.
   
   \bbase size
   The tile base size, which is the unit tile size used to make larger tiles.
   
   \bcolor depth
   Number of colors to use: 1 = 8 colors, 2 = 64 colors ... 8 = 16 million colors.

   \btile area goal
   The upper limit of tile size (area in pixels). 
   
   \breq. color match
   Set 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 (minimum consolidation).

PAINTING
   +image: painting1.png  +image: painting2.png
   This function transform an image into something similar to 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.
   
   \bblur radius
   Blur the image before processing. This results in smoother boundaries.

   \bcolor depth
   Number of colors to use: 1 = 8 colors, 2 = 64 colors ... 8 = 16 million colors.

   \bpatch area goal
   Set 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.

   \brequired color match
   Set 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 (minimum consolidation).

   \bborders
   Determines whether the colored areas will be delineated with a thin black 
   border, like irregular tiles in a mosaic. After using this function, using 
   \>EMBOSS\> can add interesting texture to the image.
   
   \bperformance
   This function can take a long time if the image is very large or the computer 
   is slow. To speed up the process of trying out many options, select a small 
   but important area (\>SELECT AREA\>) and zoom-in on this area. When done 
   experimenting, clear the area and process the entire image with the chosen 
   settings.

TEXTURE
   +image: texture2.png    +image: texture.png
   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
   +image: pattern2.jpg    +image: pattern1.png
   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 wall. 
   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 web search for "pattern image". Download some of these and crop them if 
   needed to a size around 200-500 pixels. For convenience, add these to the 
   supplied pattern files in <fotoxx-home>/patterns.

   Use the [Browse] button to select a pattern file. The selected pattern will 
   be tiled to cover the base image. The pattern is partly transparent so that 
   the base image shows through. Use Zoom to grow or shrink the pattern size. 
   There are two methods to mix the pattern with the base image. The pattern 
   opacity can be set 0-100%. The base image is used to fill the unused opacity 
   - e.g. if the opacity is set to 30%, then the final image will be 30% pattern 
   and 70% base image. Contrast is used to modify the base image brightness using 
   the pattern brightness as a template. The two parameters can both be used and 
   mixed in any ratio.

   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. 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 Emboss or Gradients to add a 3-D effect to the pattern.

   The checkbox "Grayscale" will convert a color pattern to grayscale.

   Useful pattern files in LibreOffice: 
      /usr/lib/libreoffice/share/gallery/www-back

DITHER
   +image: dither1.png  +image: dither2.png
   +image: dither3.jpg
   This function provides several ways to dither an image - convert into dots.
      • dither 0 - colored round dots in the style of Roy Lichtenstein
      • dither 1 - pure bright RGB dots with optimized distribution
      • dither 1 - black/white dots with optimized distribution
      • dither 2 - classic dither using all RGB colors within limited bit depth
      • dither 3 - classic dither using a custom palette of colors

   The classic dithers use the Floyd-Steinberg method of compensating for color 
   errors: mismatch between an input image color and the closest color from the 
   palette. Dots with nearby colors are mixed-in as needed so that the average 
   over an area more closely matches the input color. The error compensation can 
   be turned off if wanted, to get distinct color bands or contours.

ENGRAVE
   +image: engrave.png  +image:engrave2.png
   Convert an image into black & white lines roughly conforming to brightness.
   
   The Size input determines line thickness and how many vertical image pixels 
   are used for each vertical pixel column in the output lines. The line pixel 
   columns are split into black and white parts with their proportion roughly 
   matching the mean brightness of the input pixels.
   
   The Bias input can be used to make the overall image darker or brighter, 
   whatever gives the most pleasing result. Negative/positive values make the 
   image darker/brighter. 
   
   The Color input (0-100%) can be used to add color to the white parts.

MOSAIC
   +image: mosaic2.jpg  +image: mosaic1.png
   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 needs time 
   (100K/min. on a strong computer). If you change the tile dimensions, press 
   [Tiles] again to regenerate the tiles. After the tiles are created, press 
   [Image] to convert the current image into a mosaic using these tiles. This 
   takes only a few seconds. 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. 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 will not work. Regenerating the mosaic is quite fast, so 
   do this if you want the popups to work.

ADD NOISE
   +image: add-noise.png
   Add random color noise to an image. Set a target spot size 1-10 and noise 
   level 0-100%. At 100%, random noise in the range -127 to +127 is added to each 
   RGB value of each pixel. The mean value is zero. Overflows outside the range 
   0-255 are truncated. Average color over a large area is preserved, with the 
   noise superimposed. You can use Add Noise with Select Area or Paint Edits to 
   add noise to selected areas.

   \bSuppression of 'banding'
   In image areas where the brightness distribution has been 'stretched', visible 
   'banding' can occur in areas of uniform color. I have noticed this in sky and 
   especially in very dark image areas. You can reduce this problem by adding 
   noise to affected areas and also adding blur afterwards. If the edges of 
   visible bands are made irregular, they become less visible to the human eye.

COLOR DEPTH
   +image: color-depth2.png  +image: color-depth1.png
   This function changes the normal 16 bits per RGB color to any value between 
   1 and 16 bits per color. At 8 bits per color, there are 16.8 million colors 
   (256 x 256 x 256).

SHIFT COLORS
   +image: shift-colors.png
   This function can be used to correct colors or convert 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. 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.

ALIEN COLORS
   +image: alien-colors1.png    +image: alien-colors2.png
   Repaint an image or selected area with random alien colors. You can control 
   the rough pattern size and the intensity (from barely visible to dominant).

COPY COLORS
PASTE COLORS
   +image: copy-paste-colors.png
   These functions can be used to select and edit single RGB colors, or move 
   selected RGB colors from one image to another. Copy Colors: The selected RGB 
   colors are copied from the current image. If all three colors are selected, 
   you get a duplicate of the current image. Save the image as a new file to be 
   used as input. Paste Colors: The selected RGB colors from the selected image 
   are pasted into the current image. Colors not selected are left in place. 
   If all three colors are selected, you get a duplicate of the selected image. 
   If no colors are selected, you get a duplicate of the current image.

CUSTOM KERNEL
   +image: custom-kernel.png
   Apply a custom convolution kernel to an image. The underlying technology is 
   explained in Wikipedia. Input a kernel size, a multiply factor, an add factor, 
   and fill-in the table values. The values can be saved into a file and 
   retrieved later by using the [Save] and [Load] buttons. [Apply] applies the 
   kernel to the image. [Reset] restores the original image status. Several 
   kernel example files are available initially. You can modify these and save 
   with a custom name.

   Math: the brightness values for each N-by-N block of pixels in the image are 
   multiplied by the corresponding values in the kernel matrix and added 
   together. This number is multiplied by the multiply factor, and the add factor 
   is added to it. This final value becomes the new brightness level for the 
   image pixel at the center of the N x N block.


WARP MENU

+image: ug-warp.png

UNBEND
   +image: unbend1.png  +image: unbend2.png
   Panoramas of nearby subjects (typically buildings or interior rooms) may show 
   straight lines that are curved, or buildings that are slanted. Warping the 
   images was necessary in the panorama process in order for the images to fit 
   together. The Unbend function can be used afterwards to straighten the 
   panorama image if needed. 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. If values in the four input controls are changed, the image 
   is warped in the manner indicated by the corresponding four images. Increase 
   or decrease the values and repeat until satisfied. Move the axes to change 
   the centers of warping.

   See also \>WARP IMAGE\> for another method of correcting image curving and 
   perspective.

PERSPECTIVE
   +image: perspective2.png  +image: perspective1.png
   This function can be used to straighten a photo made from an offset angle. 
   The image on the left is the original photo, taken from right of center to 
   avoid reflections. The image on the right is the straightened version. This 
   function can also be used to straighten a high building photographed from 
   street-level or from the side.

   Click on the four corners of the tetrahedron 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 marked with small white boxes containing "A, B, C, D". 
   The upper left corner of each box precisely marks the image position. Clicking 
   near a box will move it to the new position. The [Crop] button will 
   automatically crop the image at the selected corners. The crop and straighten 
   can be undone in sequence with the undo button. You can use the keyboard arrow 
   keys to move the corner markers in 1-pixel steps. The arrow keys work on the 
   last corner clicked or moved.

WARP IMAGE
   +image: warps4.jpg

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.

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. This function works over a 
   broader area than the curved warp and causes less image curvature. To minimize 
   the addition of curvature, drag only from 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". Details 
   can be found with a web search.

AREA RESCALE
   +image: area-rescale.png    +image: area-rescale2.png
   This function rescales an image to a smaller size, leaving selected areas 
   unchanged. The goal is to increase the relative size of the area of interest. 
   The image above was reduced, but the boat in the foreground was left unchanged.

   First, select the areas that are to be preserved using \>SELECT AREA\>. Press 
   the [proceed] button. The selected area is erased and the mouse cursor changes 
   into a drag cursor. Pull the image inward from the upper left corner. This 
   operation may be repeated as needed until you are satisfied. Press the [done] 
   button. This function works best when the selected area(s) are small in 
   comparison to the entire image. The pixel rows and columns that intersect the 
   selected areas are not changed. Other areas are compressed as the image is 
   pulled inward.

UNWARP CLOSEUP
   +image: unwarp-closeup1.png  +image: unwarp-closeup2.png
   Closeup face photos are often distorted, because areas closer to the camera 
   are larger in the photo than areas farther away. This function can be used to 
   reverse the distortion. Use Select Area to select the face first (does not 
   need to be accurate). Click the image near the center of distortion (above 
   example: between the eyes). Move the slider to optimize. If the face is turned 
   away from the camera, experiment to find the best center.

MAKE WAVES
   +image: make-waves2.jpg +image: make-waves1.png
   This function distorts an image into a wave pattern, as if 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 edit functions, 
   this function also works within a selected area. The flood above is fake.

TWIST
   +image: twist1.png  +image: twist2.png
   This function twists the image around a point chosen with a mouse click or 
   drag. Click the desired position and move the Twist slider the amount wanted. 
   You can also drag the mouse around the image to change the center of twisting. 
   The Center slider untwists the central area relative to the rest. The Angle 
   slider rotates the image.

SPHERE
   +image: sphere2.jpg    +image: sphere.png
   Make a spherical projection of an image. Drag the mouse on the image to change 
   the center of the projection (defaults to midpoint). The flatten control 
   modifies the projection gradually from a sphere (right) to a flat image (left). 
   The magnify slider magnifies the resulting image up to 2x. If you want the 
   margins to be transparent, be sure to save the file as .png instead of .jpg 
   (JPEG files do not support transparency).

STRETCH
   +image: stretch.png
   Add or remove barrel or pincushion distortion. Barrel distortion is often 
   seen in RAW images that have not been processed to remove this distortion. 
   Left click to choose a central point where changes will be centered - normally 
   the center of the image. This is the default. Modify the 'stretch' slider to 
   bend the image.

INSIDE-OUT
   +image: inside-out2.png  +image: inside-out1.png
   This function inverts the center-edge distances of each pixel. You can click 
   or drag the mouse to vary the center point.

TINY PLANET
   +image: tiny-planet.jpg
   Wrap an image around a circle.
   If the image is a 360 degree panorama, there will be no visible seam.
      • Center Hole: the image is wrapped around a central hole. Size may be zero.
      • Cut Top: remove a top margin from the input image before conversion.
      • Cut Bottom: remove a bottom margin from the input image before conversion.
      • Reverse R: mirror the input image vertically.
      • Reverse Theta: mirror the input image horizontally.
      • Rotate: turn the output image around the center.

ESCHER SPIRAL
   +image: escher-spiral.png    +image: escher-spiralA.png
   Transform an image into an endless inward spiral like the famous clock of 
   M.C.Escher. Width determines the starting width of the outermost layer. Rim 
   determines the starting width of the border separating layers, and Color 
   determines its color. The default center is the center of the image. Click 
   on the image to set a new center.

FLATTEN PHOTO
   +image: flatten-photo2.png  +image: flatten-photo1.png
   This function can flatten a photo of an image on a surface that is curved, 
   e.g. around a column, or a page from an open thick book, where the pages curve 
   inward at the center binding. The curvature of the top and bottom edges of the 
   surface provide information about the amount of curvature and the amount of 
   stretching needed to appear flat. The example above is a thick book. Other 
   rounded surfaces can be corrected, e.g. a poster on a round column.

   Procedure: Click the mouse along the top edge, creating a visible marker dot 
   at each clicked point. 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 curved edge. Repeat for the bottom edge. Press 
   [flatten] to flatten the page. The edges should now be straight (or straight 
   enough). Use the [stretch] slider to stretch the sides of the image as needed, 
   to compensate for the lateral compression caused by the curvature. Use the 
   Widen control to widen the image as needed to restore the correct width/height 
   ratio. The [undo] button restores the unmodified image, keeping the marker 
   dots, which can then be adjusted for a revised attempt. The [clear] button 
   deletes the marker dots.

   If another image is processed with the same dimensions, the marker dots are 
   kept as a starting point. A series of photographed book pages can be more 
   rapidly processed if the camera and book are fixed so that many pages have 
   nearly the same position in the photos. Photograph a series of odd pages, then 
   a series of even pages. It might be possible to keep the total time within 
   2-4 minutes per page with this process (photo time + Fotoxx time).


COMBINE MENU

+image: ug-combine.png

   These are functions which combine multiple image files. In the case of 
   overlapping images, corresponding features in each image are made to coincide, 
   with single-pixel accuracy. This may need significant time if there are many 
   large images or the computer is slow. If you see this alignment process going 
   wrong, you can use the Escape key to kill the process.

HDR
   \bHigh Dynamic Range
   +image: HDR-adjust.png  +image: HDR.jpg
   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 
   input images can be tolerated. If things move between shots, ghosting cannot 
   be avoided.

   Select the HDR menu function and select up to 9 images (\>SELECT IMAGE FILES\>), 
   which must all have nearly the same pixel dimensions. The images are aligned 
   and combined automatically. This needs 10-30 seconds per image, depending on 
   image size and CPU speed. When done, the combined image is shown, along with a 
   dialog for 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 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 remaining images 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 
   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. The above example shows two input images 
   and their output image. The curves were adjusted to optimize the brightness 
   for both the foreground and background buildings. It is often useful to apply 
   the gradient function after HDR, to increase the perceived brightness range.

HDF
   \bHigh Depth of Field
   +image: HDF.png
   Combine (overlay) multiple photos of the same subject with different focus 
   settings from close to distant. 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 if the subject is very close. 
   Camera movement can cause scaling and parallax problems (close objects shifted 
   against distant objects). Such problems may be fixable later in Fotoxx, but 
   this may require considerable time. It is better to avoid the problems.

   +image: HDF-paint.png
   Processing the photos: in Fotoxx, choose the HDF menu function and select up 
   to 9 images (\>SELECT IMAGE FILES\>). The images will now be aligned as well 
   as possible. This needs 10-30 seconds 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" it with 
   the mouse on any area of the output image. This converts the original image 
   mix to the single 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 combined 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 are aligned.

   Suggested Workflow: Using paint mode, choose each image in sequence and paint 
   all areas that look sharp in that image. Any boundaries that are not aligned
   well 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
   +image: stack-paint.png
   +image: stack-paint2.jpg
   Stack (overlay) multiple photos of the same subject taken at different times. 
   Remove tourists and cars that come and go between shots.

   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 two or 
   more photos for each area of the subject not obstructed by the transient 
   objects. Hold the camera steady and aim at the same point, so that the images 
   will align accurately.

   Processing the photos: In Fotoxx, choose the Stack/Paint menu function and 
   select up to 9 images (\>SELECT IMAGE FILES\>). The images will now be aligned 
   as well as possible. This may need 10-30 seconds per image, depending on image 
   size and CPU speed. The output image (lower left) is an even mix of the 
   aligned input images (top row). When the alignment is complete, the dialog 
   shown above starts. You can select any input image and "paint" with the mouse 
   on any area of the output image. The single selected image is used for area 
   being painted. For each area in the image, choose an input image that is free 
   from the transient objects. The radius of the paintbrush can set larger or 
   smaller, so you can paint large areas quickly and control fine detail when 
   needed.

   Automatic operation: press the [Hide] button to see if transient objects can 
   be removed automatically. This will work for areas in the image where multiple 
   photos of the unobstructed background are available (lower middle image). To 
   show all of the transient objects, press the [Show] button (lower right image). 
   This generally works, but not perfectly. Slight image misalignments or 
   lighting differences (esp. moving shadows) may cause the algorithm to select 
   background pixels instead of foreground pixels. You can use the paint method 
   described above to repair the errors manually.

STACK/NOISE
   +image: stack-noise2.png  +image: stack-noise.png
   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.

   Processing the photos: In Fotoxx, chose the Stack/Noise function and select up 
   to 9 images (\>SELECT IMAGE FILES\>). They will be combined automatically and 
   shown, and 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 RGB values for the 
   corresponding input pixels. The following alternatives 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 averaging. This may get noise spikes removed from the 
   mix. This has no effect if the median method is selected.

STACK/VERSIONS
   +image: stack-versions.png
   Use this function to combine different edited versions of an image, where you 
   can determine which version is shown in selected image areas. Any images can 
   be combined that have the same pixel dimensions.

   Select up to 9 images of identical size. The initial output image is a blend 
   of all input images. Select an image and use the [Fill] button to fill the 
   entire output with the chosen image. Select an image and use the mouse to 
   'paint' that image locally in areas dragged by the mouse. The paint area is a 
   circle with Paint Radius around the pointer. The paint speed is controlled by 
   the Opacity settings for the center and edge of the mouse. Use low numbers to 
   paint gradually.

STACK/SPLIT
   +image: stack-split2.png  +image: stack-split.png
   Two images may be selected. The two images are overlapped and displayed with a 
   movable boundary. The first image is left of the boundary, the 2nd image is 
   right. Move the boundary line by dragging with the mouse. This function is one 
   way to show differences between an original and edited image.

PANORAMA
   +image: pano-align1.png   +image: pano-align2.jpg
   This function stitches 2-6 images together to make a wide-angle image or 
   panorama. The images must overlap by 10% or more, so that the program can find 
   where they match and join them together. Start by selecting 2-6 image files 
   (\>SELECT IMAGE FILES\>). It is helpful to select the images in left-to-right 
   order, to make the initial rough alignment easier. The images are initially 
   joined and shown with a small transparent overlap. A pre-align dialog (above) 
   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 image center. 
   After the images are in 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 necessary. The images should be correctly curved and 
   fit together well. If they do not, then 'lens mm' (focal length, 35mm 
   equivalent) needs adjustment. Image curvature changes as lens mm is adjusted. 
   The initial value is obtained from EXIF data if available, and this is 
   normally good enough. If the images have no curvature (e.g. scanned images), 
   use the 'no curve' checkbox to set 'lens mm' effectively to infinity.

   If an image was cropped so that the greater dimension (width or height) was 
   reduced, then the EXIF focal length is no longer valid. Fotoxx assumes that 
   the greater image dimension is '35' on the same scale as '35mm equivalent 
   focal length' and calculates image curvature on this basis. If the image was 
   cropped, the calculated curvature will be too great. Compensate by increasing 
   'lens mm' to reduce curvature. Increase this parameter until the images fit 
   together reasonably well.

   The 'no auto warp' checkbox is normally unchecked. Its purpose is described 
   below.

   The 'manual align' checkbox will use the manual pre-alignment as the final 
   alignment. This is for images that have no clear features to match and 
   automatically align the images. This option also allows the images to have 
   zero overlap.

   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 alignment is found. This may need a minute or more, depending 
   on CPU speed and image size. You can speed up the process greatly if you 
   reduce the input images to 2/3 or 1/2 size. Do this also if the process fails 
   for lack of memory. Panoramas with 6 large images can require 16+ GB of memory 
   during processing. It may also be helpful to increase the size of your swap
   file or swap partition. This may make a large panorama successful (after 
   taking a long time to complete).

   +image: pano-adjust.png
   When fine alignment is complete, the combined image is displayed. The above 
   dialog is started for fine adjustments of brightness. You may see a border 
   between images if they do not have the same brightness. Choose an image to 
   adjust using the radio buttons at the top. Adjust the brightness control to 
   match the image to its neighbors left and right. Do this for all images 
   needing adjustment. The match does not have to be very good, since 
   'Blend Width' (next) will mask remaining differences. Use the 'File Color' 
   button to restore brightness levels from the underlying image files. 
   
   The 'Blend Width' control governs how the images are blended together: at the 
   image overlaps, brightness is changed over this many pixels, to mask 
   imbalances that cannot be fully corrected. The default is 1 pixel, which makes 
   any brightness difference look obvious.

   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. Select 'Mouse Warp' and 
   select one of the images with the radio buttons. Then drag the mouse along the 
   edge of the image where it should align with its neighbor, moving the image 
   into alignment. The image is moved locally around the mouse while more distant 
   parts stay fixed. Images with parallax shifting will require a compromise, 
   since it is impossible to keep both foreground and background in alignment.

   The flatten image control can be used to "unbend" the image, which will 
   straighten curved lines (e.g. curved buildings). A value of zero has no effect 
   and a value of 1.0 will fully flatten the image.

   When done, use \>UNBEND\>, \>WARP IMAGE\>, \>CROP\> etc. for final adjustments.

   \bScanned images
   Scanned images can be combined if there is enough overlap. Check 'no curve' 
   since there is no curvature.

   \bAuto Warping
   The images are slightly warped in various directions during alignment to find 
   the best match. This is to compensate for shifts in camera horizon 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, making
   alignment very poor. By selecting no auto warp you may be able to get the 
   alignment to succeed or have a smaller error. Another option is to select 
   manual align.

   \bCombining Panoramas
   You can make a panorama of up to 6 images in one pass. You can also combine 
   panoramas that fit together at the sides, e.g. combine a 4-image panorama with 
   another 4-image panorama to make an 8-image panorama. You must stop the normal 
   image curving when you combine panoramas, since the panorama images are curved 
   already (assuming you have not used the 'flatten' option in the final panorama 
   dialog). Stop image curving by checking the box 'no curve' in the pre-align 
   dialog.

   \bPanorama Limitations
   Panoramas including nearby objects can be tricky: when making the photos, 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.
   
   \bVertical Panorama
   This can be done by rotating the input images 90 deg. so that top is on the 
   left. In Panorama, choose the images in order top to bottom, so that the top 
   image is on the left and bottom is on the right. Do the panorama normally. 
   Rotate the output image clockwise so that left becomes top. 

SHOW CIM FILES
   Show the input files for the current or latest combined image, in a popup 
   window. Only the current or latest set is remembered here. If you need a 
   permanent memory, you can copy and paste the text into a separate text file.

MASHUP
   +image: mashup.jpg
   Arrange multiple images and text in a layout. 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.

   +image: mashup1.png
   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.

   +image: mashup2.png
   The 2nd Mashup dialog is a choice: edit images, edit text, edit lines and 
   arrows, rescale to a larger size, save the completed combined 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.

   +image: mashup3.png
   Use this dialog to select and place images on the layout and revise their 
   appearance: size, rotation, position, transparency. An image may be partly or 
   wholely transparent, overall or within specified areas. This means that the 
   background image or overlapped image can show through transparent areas. The 
   Add Image button leads to a gallery file selection dialog (\>SELECT IMAGE FILES\>). 
   Selected images are placed on the layout. After the images are added, click on 
   any image to select for modifications. Drag the image from the middle to 
   position 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 'Prev' and 'Next' 
   buttons 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 rescales 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 shown below. The [warp] button is used to bend or warp an 
   image, using the Warp dialog shown below. The 'black margins' checkbox can be 
   used to remove black margins left by other edit functions, e.g. warp. These 
   will be made transparent. The 'Image is fixed' button will prevent the image 
   from being moved by the mouse or KB. This is helpful when images are being 
   fine-aligned and accidental movement should be prevented (can happen when 
   working fast with mouse clicks and drags). The Margins controls can be used to 
   make image edges transparent. The Hard margins cut off image edges. The Blend 
   margins make the edges partly transparent to blend them into the background or 
   other overlapped images.

   +image: mashup4.png
   "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 regulate the change rate.

   +image: mashup5.png
   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].

   +image: mashup6.png
   The Edit Text dialog is used for placing text on the layout. Enter some text 
   and press Add. You are asked to click on the layout where the text will be 
   added. 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.

   +image: mashup7.png
   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. 
   You are asked to click on the layout where the line will be added. 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 set the position of 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 position 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 also 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 'saved_areas'. Open any of the .png images found there. 
   The original area outline is used, and area blending works from these edges.

   \bMashup 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 in the project 
   file: image and text locations, scales, transparency, etc.

   \bMashup Rescale
   Working with a very large layout (over 20 megapixels) can be quite slow, 
   especially if the PC 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 rescale it up to 
   160 megapixels when done. The larger layout can still be worked on directly 
   afterwards, but it will be much slower.

IMAGE ARRAY
   +image: image-array.jpg
   Select many images and join them into a compact array format within a colored 
   frame.

   The first dialog is shown at upper left. Background Color is the color of the 
   outline frame and the spaces between the contained images. Array Width is the 
   overall width of the output array, and Margin is the width of the outer margin 
   surrounding all images. Array height is determined by the number of selected 
   image files and the space required to fit them in the frame. Image Columns 
   specifies the number of image columns (6 in the above example). The number of 
   rows depends on the number of image files selected. The Separation values set 
   the horizontal and vertical space between the contained images.

   Select the image files (\>SELECT IMAGE FILES\>), then press [Proceed] when 
   done. The resulting image will be made in a few seconds (up to a minute for 
   hundreds of images). This image will typically have a very uneven bottom 
   margin, as shown by the top right image above. The sequence of images in the 
   array is determined by the selection order. The top row is filled first, left 
   to right, then the 2nd row, etc.

   The Optimize dialog begins automatically. It can rearrange the images so that 
   the bottom margin is more even. Press Start and wait for the image to optimize. 
   You can watch the progress. The function will exit if an optimum is found that 
   makes the bottom margin even within 2 pixels. It may continue to search 
   indefinitely if this goal is not reached. Press Stop to force the optimize 
   function to exit with the best solution found so far. If optimization is 
   successful, you will get even columns as shown in the lower right image. If 
   the bottom edge is still uneven after optimization, you will be asked if you 
   want to add margins to some of the images to make the bottom edge even. This 
   will result in an even bottom edge, but the vertical spacings will no longer 
   be equal.

   TIP: Optimization works best if the number of images per column is at least 
   four (better more). This gives the optimizer enough flexibility to find a 
   solution with an even bottom edge.

   The last dialog appears, shown at lower left. You must now assign a unique 
   name to your array, one that does not conflict with other arrays you have made 
   before. A file save dialog is started, and you can save the new array file 
   anywhere you wish. If the map option is selected, a map of the included images 
   is also created. This map allows you to click on any image in the array to get 
   a larger popup image which can be zoomed up to the full size of the original 
   image, using the mouse wheel or F11. This will work now and at any time later, 
   even if the array file is moved, presuming the map file and the original 
   images are still available.

   The saved file must have a name indicating that this is an array image. The 
   full file name is: array: <your assigned name>.jpg. If the map option is not 
   selected, "array:" is not included in the name. The map files are at 
   <fotoxx home>/image_array_maps/.

   Note that the popup image feature is not standard and will not work outside 
   of Fotoxx.


BATCH MENU

+image: ug-batch.png

   These are functions that process multiple selected image files, a few or 
   thousands. These functions can be canceled in mid-process using the Escape key, 
   but this will leave some files processed and some not. There is a popup report 
   showing file names as they are processed.

BATCH CONVERT
   +image: batch-convert.png
   This function is used to rename, convert, rescale and move multiple image 
   files at once.

   Dialog Inputs
      • Select Files - Select files to convert (\>SELECT IMAGE FILES\>).
      • Replace Text - replace text string in file names (see Replace Text below).
      • New Name - Optional new name, optional inserted text (see Plugins below).
      • Sequence Numbers - Starting sequence number and adder for each output file.
      • New Location - Optional new folder location for the converted files.
      • new file type - File type for converted images, or "no change".
      • color depth - specify 8 or 16 bits for tif or png output.
      • max. width, height - Output images will fit within these limits.
      • delete originals - Delete input files after successful conversion.
      • copy metadata - Copy all EXIF and IPTC metadata to the output files.
      • sharpen - Sharpen output images using the two supplied parameters.

   \bReplace Text
   If text is entered here, file names are scanned for this text, and if found, 
   the given replacement text is substututed. The replacement text can have a 
   different length and can also be empty, in which the text is removed from the 
   file name.

   \bNew Name and Plugins
   The new file name may have inserted text: a photo date (from EXIF metadata), 
   a sequence number, or the original file name. Specify what and where to insert 
   as follows:
      • $oldname - The original file name is inserted here
      • $sss - A running sequence number is inserted here. See below.
      • $yyyy $mm $dd - The photo date is inserted at these positions.

   Example: San Francisco $yyyy-$mm-$dd $oldname $sss
   The input file "Golden Gate Bridge.jpg", with a photo date of May 12, 2014, 
   would convert to the output file name 
     "San Francisco 2014-05-12 Golden Gate Bridge 123.jpg".

   For "$sss", specify the length of the field with the number of 's' characters, 
   e.g. "$ss" will be adequate for sequence numbers up to 99. Leading zeros are 
   added for sequence numbers with fewer digits. Sequence numbers not fitting in 
   the specified length will be as long as needed. Keep in mind that the file 
   name sort order in the galleries is strictly ascii order, so the sequence of 
   numbers 1, 2 ... 9, 10 will sort as 1, 10, 2 ... 9. You can keep the numeric 
   order by specifying a field length of 2 ($ss), resulting in the sequence 
   01, 02 ... 09, 10.

   Either "$oldname" or "$s..." must be present to insure output file names are 
   unique. If New Location is missing or unchanged, 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.

   \bAlbums
   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 file names and folder locations.

   \bPreserving File Sequence
   If you specify a leading sequence number ($s...), the input file selection 
   sequence will be preserved at the output location. Thus you can select image 
   files in a desired order, or use an album with ordered images, and preserve 
   this sequence in the output.

BATCH COPY/MOVE
   +image: batch-copy-move.png
   Copy or move selected image file to a new location. Select the input files 
   (\>SELECT IMAGE FILES\>) from any folders known to Fotoxx. If "Delete Originals" 
   is selected, then the input files will be deleted after successfully moving 
   them to the new folder. In this case, any albums referencing the now deleted 
   input files will be updated with the new file locations.

BATCH UPRIGHT
   +image: batch-upright.png
   This function uprights image files rotated or flipped (mirrored). It depends 
   on EXIF data to know if a file is rotated/flipped and in what direction. It is 
   much faster than Batch Convert. You can simply select all candidate files and 
   let it find the ones needing a fix. The search speed is about 3000 image files 
   per minute on a strong PC. There are two options to specify the files to 
   search. The [Select Files] button leads to a gallery file selection dialog 
   (\>SELECT IMAGE FILES\>). If 'Survey all files' is checked, all image files in 
   your database will be searched.

BATCH DELETE/TRASH
   +image: batch-delete-trash.png
   Select the files (\>SELECT IMAGE FILES\>). Select the option: delete or move 
   to trash. [Proceed]. Files are listed in a popup report as they are deleted or 
   moved to trash. After all files are deleted/trashed, albums are scanned and 
   deleted files removed.

BATCH RAW
   +image: batch-raw.png
   This function converts selected RAW image files to JPG, PNG, or TIF format. 
   PNG and TIFF formats have either 8 or 16 bits per color. RAW files generally 
   have 8-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 edit 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 
   gallery windows (\>SELECT IMAGE FILES\>). 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 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 30 files per minute using Dcraw and TIFF-16 output). PNG-16 produces 
   smaller files than TIFF-16 but the time to compress is greater.

BATCH OVERLAY
   +image: batch-overlay.png
   A small overlay image can be added at a selected position on the selected 
   input images. This can be used to add a credit line, copyright, etc. on top 
   of the images.

   Prepare the overlay image as follows: Use New Blank Image to create a base 
   image to hold the text. The scale does not matter, so make it larger than 
   needed, say 1000 pixels wide. Use Paint Transparency to paint the entire base 
   image transparent. Use \>MARKUP\> > draw text to put the desired text on the 
   base image, using font, color, and other attributes as desired. Scale the text 
   to fill most of the base image. The base image (background) is transparent. 
   Remove excess margins with \>CROP\> if needed. Save the final image. A 
   convenient location is <fotoxx home>/saved_areas, but any folder can be used. 
   This image can now be used as an overlay image for Batch Overlay.

   Use the \bSelect host image files\b button to select the host image files to 
   receive the overlay image. Use the \bSelect overlay file\b button to select 
   the overlay image file.

   The two \bOverlay position\b inputs determine where the overlay image is 
   positioned on the host image, from 1-99% of the distance from top to bottom, 
   and 1-99% of the distance from left to right. 0/0 means the top left corner, 
   99/99 means the bottom right corner. The overlay image will not extend beyond 
   the host image edges.

   Specify \bOverlay width\b as a percent of the host image width. The height 
   will be set to conserve the width/height ratio. If \bMake width constant for 
   window size\b is checked, the overlay image visual size will be made constant 
   for the window size specified below. Without this, a "tall" image that 
   displays with large left and right margins would have a visually smaller 
   overlay image. The initial window size is the current window. You can input 
   any size. Press \brefresh\b to set the current window if this has changed.

   If \bReplace host files\b is selected, the input host files are replaced with 
   the output overlaid host files. If \bMake new versions\b is selected, new 
   versions of the input host files are created.

BATCH TAGS
   +image:  batch-tags.png
   Add, remove, or change the tags for a large number of image files at once.

   Use the [select files] button to select the image files (\>SELECT IMAGE FILES\>).

   The dialog shows two lists of tags: those to add to the selected files, and 
   those to remove. Available tags are shown in the Defined Tags window below. 
   One of these can be  added to the currently selected tag list (add or remove) 
   by clicking it. A tag can be deleted from either tag list by clicking it. To 
   replace tags, specify the new tags in the add tags list and the old tags in 
   the remove tags list.

   If the list of defined tags is long, it may be easier to type the desired tag 
   into Enter New Tag. Existing tags matching what you have typed so far will 
   appear in Matching Tags, and you can point and click one of these to add the 
   tag to the image. If the input tag is new (no matching tag is shown), press 
   [Add] when the tag is complete. It will be added to the selected tag list and 
   to the list of defined tags under the category "nocatg".

   If you are using tag categories, you can select a category, and only those 
   tags will be shown in the list of defined tags. If your tags list is huge, 
   this can reduce the list to a manageable size for pointing and clicking.

   The [manage tags] button can be used to define tags with categories, as 
   described in \>EDIT META\>.

   To get a list of images having specific tags which you want to remove or 
   replace, use \>SEARCH IMAGES\> to find the images, then start this function 
   and use [select files] to add all the image files that you just found, or 
   select any subset.

BATCH RENAME TAGS
   +image: batch-rename-tags.png
   With this function, you can rename any number of tags and apply these changes 
   to your entire image collection. Click on a tag to rename from the list of 
   defined tags, enter a new name in the Rename to box, then click on the arrow 
   button to add this pair of names to the list on the right side. Repeat for 
   each tag to rename. If you make a mistake or change your mind, click on the 
   pair of names in the list to remove them. Press [Proceed] when done.

   A popup window shows the number of image files containing the affected tag 
   names. Press [Yes] to proceed. The update rate is around 500/minute on a 
   strong computer. The next time Fotoxx is started, the index file function will 
   update all thumbnails for the same images, because the file modification date 
   has changed.

BATCH PHOTO DATE
   +image: batch-photo-date1.png  +image: batch-photo-date2.png
   This function lets you quickly fix a batch of photos that have no photo 
   date/time or an incorrect one. Use the [select files] button to open a gallery 
   window where you can select the image files to process (\>SELECT IMAGE FILES\>).

   There are two ways to change photo date/times:
      • Set a new date/time (right image above)
        enter a new year only (yyyy) - only the year is replaced in the files.
        enter a date only (yyyy-mm-dd) - the date is replaced but not the time.
        enter a full date/time (yyyy-mm-dd hh:mm:ss) - both are replaced.
      • Shift existing date/time (left image)
        Enter + or - values into any of the 6 fields: years, months, days, hours, 
        minutes, seconds. Dates/times will be shifted by the entered values.

   Shifted date/time values propagate to the next higher value when necessary:
      Time 08:30 shifted by -50 minutes results in 07:40
      Date 2016-10-20 shifted by +6 months and -30 days results in 2017-03-21 
      (March has 31 days).

   If the checkbox 'test' is selected, a report of the old and new date/times for 
   the selected files is produced for your inspection. No changes to the files 
   are made. If you are satisfied that the results are correct, remove the 
   checkbox and run again to update the files. The same set of files is already 
   selected.

BATCH CHANGE META
   +image: batch-change-meta.png
   This function can revise metadata for multiple image files. You can add new 
   metadata, revise existing metadata, and delete metadata. Use the [select files] 
   button to open a gallery window from which you select files to process 
   \>SELECT IMAGE FILES\>). Enter metadata key names and values to be assigned, 
   or leave the value blank to delete the key. Press [apply]. You will get a 
   confirmation message and you can proceed or cancel at this time. A list of 
   commonly used key names is provided on the left. Click one of these to insert 
   it into the first empty key name field in the dialog. This list comes from the 
   file <fotoxx-home>/metadata_picklist, which you can edit to add other keys to 
   the list. The [Full List] button provides information on how to get a list of 
   all available key names.

BATCH REPORT META
   +image: add-meta-items.png  +image: batch-report-meta.png
   This function can report any metadata for any number of images. The output is 
   a text file which is displayed in the default text editor for your system 
   (e.g. Gedit for a Gnome desktop). You can use the search features of the text 
   editor to find images matching desired metadata, or you can use the text file 
   as input to other programs. Use the [select files] button to open a gallery 
   window to select the files to be processed (\>SELECT IMAGE FILES\>). You can 
   navigate through any number of galleries and select any number of image files 
   in each. The [edit] button opens a new dialog (right) where you can select the 
   metadata items to be reported. Click an item in the left column to add it to 
   the right column and to the report. Click an item in the right column to 
   remove it. Click the last item in the left column, "Other Item ...", to 
   type-in any item name not appearing in the list, which contains only the most 
   likely needed items.

BATCH MOVE META
   +image: batch-move-meta.png
   Review the topic \>METADATA STANDARDS CHAOS\> to understand the point of this 
   function.

   Using this function, you can consolidate metadata from multiple keys into a 
   single key. For example, if you have files with descriptions present in 
   various keys, you can consolidate these into the single key 'description'. 
   This would make searching images based on words in their descriptions much 
   easier. In general, you can move and aggregate any metadata containing 
   user-defined text.

   Use the [select files] button to select the files to be processed from a 
   gallery window (\>SELECT IMAGE FILES\>), or check 'select all files'. Enter 
   the input keys that will be aggregated and moved, separated by commas, and 
   enter the one output key to receive the aggregated inputs. The output key 
   may be one of the inputs. If A + B + C are the input keys, and B is the output 
   key, the resulting B key will contain A + B + C in that order. This is usually 
   immaterial, since only one of the many alternatives will be used in a given 
   image file. The result for one file would be one of A → B, B → B, C → B.

   Use the checkbox 'report only' to view what will be done, before you commit to 
   changing the file data. If you want to undo your mistake, this could be very 
   difficult. Make a backup before doing anything that could go wrong. If 
   thousands of files are processed, this may need significant time. If you are 
   using the 'report only' mode, you can use the Escape key to stop the report 
   instantly and inspect the results up to this point.

BATCH GEOTAGS
   +image: batch-geotags.png
   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 (\>SELECT IMAGE FILES\>). Then get the location data as 
   described in \>EDIT META\>, using the buttons [Find] and [Lookup], or click on 
   a map marker. Press [proceed] to start the update process. Use this function 
   also to fix inconsistencies in location spelling or latitude/longitude data. 
   If location and/or country is left blank, they are not updated. To erase 
   location or country, input the name "null". If latitude and longitude are left 
   blank, they are not updated. To erase latitude and longitude, input "0" for 
   both values. You can update location/country only, latitude/longitude only, or 
   all items. In practice, you may find that the camera GPS inserts latitude and 
   longitude without location and country, or it uses an unwanted language, or 
   all capital letters, or some other value needing repair.

EXPORT FILE LIST
   +image: export-file-list.png
   This function is used to create a file containing a list of image files. These 
   are fully qualified file names, one per line in the text output file. This has 
   no use inside Fotoxx. If you need to select images to feed into a shell script 
   or another program, this is the way. The [Select Files] button starts a dialog 
   for selecting files (\>SELECT IMAGE FILES\>). Use the Browse button to select 
   or define the output file.

EXPORT FILES
   +image: export-files.png
   This function copies selected image files to another folder. This could be 
   used for copying files to a thumb drive, uploading files to a photo web 
   service, etc. Select image files by clicking gallery thumbnails 
   (\>SELECT IMAGE FILES\>). Select a folder where the image files will be 
   copied. If 'export metadata' is selected, a limited set of metadata is also 
   copied (relevant for a photo web services like Flickr). These are: photo date, 
   keywords (tags), copyright, title, description, and geotag data (location). 
   Privacy notice: others would be able to find your location by date if this 
   metadata is included in uploaded files.

SCRIPT FILES
   Menu Functions:
   • Edit Script - Perform a set of edits on one image file, recording all 
                   functions and settings in a named script file.
   • Run Script - Run a script file using the current image file, like an 
                  edit function.
   • Batch Script - Select any number of image files and run a script file on 
                    all of them, in batch mode.

   Script files allow you to define a set of edits once, and repeat them on 
   single or multiple image files at a later time. This can be useful when many 
   photos of the same subject were made under the same lighting. You can choose 
   one photo and edit it to perfection, recording every function used and 
   adjustment made in the dialogs. Then you can apply these edits to the entire 
   batch of photos. Certainly this will not be as good as editing each photo 
   individually, but it is much faster, and you can always go back and make 
   additional adjustments after viewing the results.

   \bScriptable Edit Functions
   Some edit functions use mouse drags on the image, e.g. all warping functions. 
   These are not scriptable because mouse drags are not recorded. If you try to 
   use one of these while building the script, you are told this is not possible.

   The following functions are currently scriptable:

      Edit     Retouch           brightness/contrast/color adjustments
               Rescale           change the pixel dimensions of an image
               Margins           add margins to image, any color or transparency
               Color Mode        convert to black/white, color negative, sepia

      Repair   Sharpen           sharpen fuzzy edges
               Denoise           reduce image noise
               Adjust RGB        adjust colors using RGB or CMY sliders
               Color Profile     change color profile, e.g. Adobe RGB <-> sRGB

      Refine   Voodoo 1          automatic image enhancement tool
               Voodoo 2          automatic image enhancement tool
               Edit Dist         reshape the brightness distribution
               Flatten Dist      increase contrast in areas with low contrast
               Local Contrast    add contrast adjusted for area brightness
               Gradients         increase local contrast where weak
               Global Retinex    increase color and contrast globally
               Local Retinex     increase color and contrast locally
               Saturation        adjust color saturation based on brightness
               Soft Focus        produce a mixed sharp and blurred image
               Brite Ramp        ramp brightness or color across an image

      Effects  Sketch            convert image into a simulated sketch
               Cartoon           convert image into a cartoon
               Drawing           convert image into a color line drawing
               Emboss            add a 3D relief effect to an image
               Tiles1            convert image into square tiles
               Tiles2            convert image into irregular matching tiles
               Painting          convert image into a simulated painting
               Texture           add texture to an image (image on tapestry)
               Pattern           add pattern to an image (image on brick wall)
               Dither            convert image into dots - four styles
               Engrave           convert image into black & white lines
               Color Depth       reduce color depth for poster effect
               Shift Colors      tune colors using a slider
               Alien Colors      add strange coloring to an image
               Custom Kernel     apply a custom convolution kernel to the image

EDIT SCRIPT
   In the dialog, press [start]. Choose a file name for the script. Begin editing 
   the current image file. Use all desired edit functions in any sequence. Each 
   edit is recorded in the script file along with all the dialog settings used. 
   When finished, press [close] to close the script file and save it with the 
   given file name.

RUN SCRIPT
   Choose one of your saved script files from the popup menu. The script is 
   executed using the current image file, like a normal edit function.

BATCH SCRIPT
   In the dialog, press [Select Files]. Select the files to edit using the 
   standard file selection dialog (\>SELECT IMAGE FILES\>). When done, press 
   [Select Script]. Choose a script file from the popup menu. The script is now 
   executed on all of the chosen files. All modified images are saved as new 
   versions, so the original files are not lost. Those you do not want can be 
   quickly removed using \>BATCH DELETE/TRASH\>. If RAW files are processed, the 
   corresponding outputs are TIFF-16 files.


TOOLS MENU

+image: ug-tools.png

INDEX FILES
   +image: index-files1.png
   Fotoxx needs to know where all your image files are located (folder and 
   file names) and their embedded metadata (dates, tags (keywords), geotags, 
   titles, descriptions, ratings). This data is indexed for fast searching. 
   Fotoxx also creates thumbnail images so that the gallery windows (thumbnail 
   pages) will work fast. Fotoxx does not modify or copy your image files - it 
   only reads them to make the index and thumbnails. These are typically 2% as 
   large as the JPEG files from a modern camera.

   The Index Files function runs whenever Fotoxx is started. 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 files. The speed can range from 300 to 
   >20K files/minute, depending on computer speed, disk speed, and average file 
   size (the big number is for a 4 GHz CPU with 8 cores and a PCIe SSD). If there 
   are few or no new files, indexing completes quickly. Indexing can also be 
   started manually from the Tools menu.

   NOTE about indexing speed: The rates stated above are for JPEG files around 
   3 MB. Larger JPEGs and TIFFs are slower. RAW files and large PNG files may be 
   very slow, 200 per minute or less. You can find out more about performance 
   limitations in the \>FOTOXX PERFORMANCE\> topic.

   Image files modified or moved within Fotoxx are taken care of automatically. 
   The Index function is used only for new image files created from outside 
   Fotoxx (e.g. a new batch of photos was added), and for files modified, moved 
   or renamed from outside Fotoxx.

   Enter your top image folders (e.g. /home/<user>/Pictures). Use the [browse] 
   button to locate and add folders. These folders and any subfolders 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 folder, but 
   it is better to separate the image files from the 100,000 other files that may 
   be under /home/<user>. Delete an entry by clicking the corresponding X.

   Enter the thumbnails folder where thumbnail files will be stored. Use the 
   supplied default /home/<user>/.fotoxx/thumbnails, or set your own location. 
   The folder name must end with /thumbnails, and this will be added to your 
   selection if needed. The folder is created if not already present.

   If you have used folder or file names to classify your images, you can make 
   immediate use of these in the \>SEARCH IMAGES\> function. If you have saved 
   dates, tags, geotags, titles, or ratings in your image metadata (using other 
   applications), these will also be searchable. After the images are indexed, 
   searching them by any of these items is almost instantaneous. Other items in 
   the image metadata can also be searched, but at a slower speed. 
   See \>SEARCH IMAGES\> for details.

   \bIndex Metadata Items
   +image: index-files2.png
   You may add up to 10 other metadata items to the image file index. These are 
   in addition to the standard items mentioned above. Metadata in this list can 
   be searched as fast as the standard items. You may not need this, but if you 
   sometimes need to search non-standard metadata items, you can add them here 
   and the search speed will be almost instantaneous. Press the [select] button 
   for "extra metadata" to get the above dialog. Click on items in the left list 
   to add them to the right list - the items to be added to the index. Click on 
   an item in the right list to remove it. Press [done] to commit the changes. 
   If you make any changes to this list, your entire image collection will need 
   to be indexed again. This will proceed much faster than the initial indexing, 
   because the thumbnails are already there and do not need to be created. Only 
   the image file index will be refreshed.

   \bFotoxx Startup Time
   If you have a huge image collection, the first startup after a reboot may need 
   some time, even if there are no new image files. Subsequent startups are 
   faster because file folders are now cached in memory. If startup time is still 
   a problem, you can bypass the indexing. This may be especially useful if you 
   use a file manager (like Nautilus) to start Fotoxx with a selected image file, 
   and you want the image to open instantly. See the \>SETTINGS\> topic 
   immediately below for more information.

   \bAccessing non-indexed Files and Folders
   A non-indexed image file or folder is one that is not included within your 
   declared top image folders (subfolders of your declared image folders are 
   always included). You can navigate to such a folder and view the thumbnails 
   normally, and you can view and edit such files normally. There are limitations 
   that you should understand.
     • These files will be missing from any search results and map views.
     • Thumbnails are created at the time of viewing - gallery paging may be slow.
   If you access a portable (slow) storage device (e.g. camera SD card), you will 
   have this situation and you will notice the balky performance. Thumbnails will 
   be created as needed, and they will remain after the device is removed. I 
   recommend that you first copy the files to a declared Fotoxx folder or 
   subfolder, and do whatever Fotoxx processing you need from this location. 
   The performance will be much better.

   \bRemovable Disks
   Run the Index function with the removable drive mounted, add the desired top 
   image folders from this drive, and let the indexing process run to completion. 
   This is no different from the procedure with permanent, fixed storage. After 
   this, Fotoxx can be used with the removable drive mounted or not mounted, and 
   nothing will be lost. If you operate Fotoxx without the drive mounted, the 
   image files on this drive will disappear from Fotoxx view. When the removable 
   drive is mounted again, and Fotoxx is started (or the index function is run 
   manually), the last status is restored. If any image files were modified in 
   the interim, this is detected and the index data and thumbnails are updated 
   in the usual manner.

QUICK INDEX
   Perform a quick incremental index in the current Fotoxx session with no user 
   inputs. If image files are updated while Fotoxx is running, the Fotoxx index 
   is no longer up to date. The new or modified files may not appear in Gallery 
   View, and are excluded from reports and maps. If they appear in Gallery View, 
   they are marked "not indexed". Use Tools > Quick Index to update the Fotoxx 
   index. The time needed will depend on the number of new or modified files 
   present within or underneath your top folders. For 100 files or less, it 
   should be a matter of a few seconds.

SETTINGS
   +image: settings.jpg

   Various user preferences and settings are collected in this dialog. 
   They are also saved in the file <fotoxx-home>/parameters. Most changes 
   are made immediately. Some will cause Fotoxx to restart.

   • Startup View - initial display when Fotoxx is started
      • Recent Files Gallery: the most recently seen image files
      • Newest Files Gallery: image files most recently added or modified
      • Specific Gallery: the specified folder gallery
      • Album Gallery: the specified album gallery
      • Previous Gallery: the gallery last used in the prior Fotoxx session
      • Previous File: the file last viewed in the prior Fotoxx session
      • Specific File: the specified image file
      • Blank Window: start with a blank window
      • Browse button: dialog to select a folder, album, or image file
   • Background - background colors for File and Gallery View windows
   • Menu Style - menu display style: icons, text, or both
   • Menu Colors - menu text color and background color
   • Dialog Font - font for menus and dialogs (Bold, Italic, etc. are ignored)
   • Zoom Speed - Choose 1-8 clicks or [+] keys per 2x image size increase
   • Pan Mode - Drag: image moves with the dragged mouse
              - Scroll: image moves against the mouse (like scroll bars)
              - Fast: image moves 2x more than mouse
   • JPEG files - quality level 1-100, quality/file size tradeoff, default 90
   • TIFF files - select a compression method to use
   • Curve Node - minimum node separation for edit curves, % of scale
        The default is 5% of scale, allowing up to 20 nodes in a curve
        (also mouse capture threshold when a node is clicked or dragged)
        Use a higher value if you use a touchpad (less precise control)
   • Map Markers - pixel size of the red dots marking image locations
   • Overlay Text - line wrap limits for titles/captions displayed on image
   • Image Position - if window is wider, position the image left/center/right
   • Confirm Exit - a popup dialog will ask if you really want to quit Fotoxx
   • Set Threads - set a fixed number of parallel compute threads - see below
   • Index Level - set the index level depending on how Fotoxx was started
        Default values in parentheses - See below for a full explanation
   • Log Level - quantity of activity log messages (in terminal or log file):
        error messages only, + information messages, + dialog inputs
        The latter will log details of dialogs opened, buttons pressed, etc.
   • RAW Loader - shell command for loading RAW files - see below.
   • RAW Options
        edit commands - change or add shell commands - see below.
        use embedded image color - use camera maker colors - see below.
   • RAW Files - customize this list to match the RAW file types you use
   • Video Files - customize this list to match the video file types you use
   • Video App - the shell command for playing video files - see below

   \bFile Quality and Compression
   JPEG file quality level: use 70 or higher for good image quality (default 90).
   TIFF file compression: reduce file size at a cost of longer file save time.
   PNG file compression level is '1' and is not adjustable. This reduces file 
   size by about 50% and slightly increases file save time. Higher values seem 
   to do nothing but increase the file save time (libpng used).

   \bOverlay Text
   When filenames/titles/captions are displayed over the image (see \>CAPTIONS\>) 
   these numbers control line wrapping for long paragraphs of text. Lines will 
   wrap at the last space character found between the lower and upper limit, or 
   unconditionally at the upper limit if there are no spaces. Deliberate line 
   breaks made when editing metadata are also recognized. Choose values that are 
   appropriate for your monitor size.

   \bImage Position
   If the window is wider than the image (i.e. window width/hight ratio > image), 
   the image can be shifted to the left side, centered, or to the right side. 
   If left or right, the unused margin is maximized, which may be more convenient 
   to position dialog boxes.
   
   \bSet Threads
   Use of SMP E-cores (slow and energy efficient) can actually make some image 
   editing processes run slower. Parallel threads compete for memory bandwidth, 
   which can also be counterproductive. This setting allows you to set lower 
   thread counts than the default of 2 per P-core + 1 per E-core. \bSet to '0'\b
   to use the hardware default thread count, otherwise set to a lower number. 
   Clock some long-running functions to find the best value for your CPU.

   \bImage Index Level
   These two parameters ('command' and 'file manager') govern a tradeoff between 
   startup time and completeness of the image index. A complete image index is 
   required for accurate results when using image search and map functions. 
   Building a complete image index may need substantial time if your image 
   collection is huge or if there are many new or modified files since the last 
   Fotoxx startup.

   Fotoxx startup time depends on the following factors:
      • If there are new or modified image files that have not yet been indexed, 
        they must be found and added to the image index. New and modified files 
        are processed at 300-10000 per minute, depending on computer speed and 
        file size.
      • The first startup after a reboot needs more time than following startups, 
        which are faster because the index file and image folders are now cached 
        in memory. First startup time with a 5400 rpm disk is roughly 2 seconds 
        per 10K image files. Following startups are roughly 3x faster. First 
        startup with an SSD disk is roughly 1 second per 20K image files (on a 
        strong PC). These numbers assume zero new (not yet indexed) image files.

   If you start Fotoxx by clicking on a file listed by your file manager, you 
   likely want to see the image instantly, not wait for indexing. You can control 
   this with the parameters 'command' and 'file manager'.
      • The 'command' parameter controls how Fotoxx indexes when started from a 
        menu, launcher or command. The 'file manager' parameter controls how 
        Fotoxx indexes when started by clicking on a file name displayed in 
        Nautilus or other file manager.
      • A value of '0' means no indexing at all. Startup is very fast. Image 
         search and map functions are disabled. Viewing and editing images and 
         metadata is normal.
      • A value of '1' means load the old index file but do not search for new
        files to update the index. Startup time is moderately fast. Image search 
        and map functions work normally, but any new (not yet indexed) image 
        files are ignored.
      • A value of '2' means full indexing: load the old index file, search for 
        new fies (not yet indexed) and update the index file. Startup time 
        depends on how many new image files must be indexed and the speed of your 
        computer. Image search and map functions produce complete results.

   You can also start the index process manually (\>QUICK INDEX\>) if you want to 
   use search and map functions with complete results. You do not have to change 
   parameters.

   \bRAW Loader
   The RAW loader is the command used to read a RAW file and convert it to TIFF 
   with 16-bit color depth. It is used when a RAW file is viewed. You can use the 
   Fotoxx edit functions to edit and optimize the file, e.g. reduce noise, adjust 
   color, fix barrel distortion, etc. The default RAW loader is dcraw using the 
   sRGB color space. A few other options using dcraw or rawtherapee are supplied 
   in the pick list. These commands are kept in the file 'raw_loader_commands' in 
   the Fotoxx home folder. Edit this file to change these or add new options 
   (see below). You may want to prepare multiple commands for multiple cameras or 
   multiple in-camera processing options. If you prefer to use a RAW editor 
   interactively, create a plugin command for this (see \>PLUGINS\>). 

   \bRAW Options
      • edit commands: press the button to edit the list of RAW loader commands.
        A text editor will start in a new window, with the current commands.
      • match embedded image color: use the RAW file embedded image as a guide to 
        map the RAW image colors to the converted TIFF image. This is the camera
        maker's interpretation of the RAW data - a good place to start if the RAW 
        loader conversion needs help. The embedded image is usually the same as 
        the camera output JPEG file.

   \bVideo App
   Enter a shell command to start a video playback app.
   Use '%s' to mark where the video file name is inserted in the command line.
   Here are some examples:
      ffplay -loglevel 8 -autoexit %s
      mpv -really-quiet %s
      totem %s
      vlc -q %s
      firefox %s

KB SHORTCUTS
   +image: KB-shortcuts.png +image: KB-shortcuts2.png
   This function is used to view or change custom keyboard shortcuts. Currently 
   assigned shortcuts are shown in the first window. If you press the [Edit] 
   button, the second dialog is shown, where you can add and change keyboard 
   shortcuts. 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 one of Ctrl/Alt/Shift: Press and hold ONE of Ctrl/Alt/Shift, then press 
   the key, then release both. Select one of the available menu assignments from 
   the list on the right. Remove a shortcut by selecting it and pressing [Delete]. 
   Press [Done] when you are finished. [Cancel] will discard all changes.

   At the end of the list are shortcuts for the most common dialog completion 
   buttons (OK, Cancel, etc.). Always use  Ctrl+ or Alt+  for these keys, since 
   single keys are reserved for text inputs into dialog widgets.

RGB DISTRIBUTION
   +image: RGB-dist.png
   This function opens a small window that shows a brightness distribution graph 
   of the current image in File view, 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. Use the 
   buttons [All] [Red] [Green] [Blue] to select the colors to show.

MAGNIFY IMAGE
   +image: magnify-image.jpg
   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.

FIND DUPLICATES
   +image: find-dups.png
   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 differences 
   that do not show up in the thumbnails. An image copy that was reduced in size 
   is likely be classified as a duplicate. Thumbnail size can be set from 32 to 
   512 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 64 needs about 880 MB, whereas size 256 
   needs about 14 GB. memory required is roughly:
       size x size x 0.75 x 3 x (image count)
   Press the calculate button to calculate the largest thumbnail size (for the 
   shown file count) that can fit within the free memory available.

   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 = 2 and pixel count = 10, then images are 
      classified as duplicates if fewer than 10 pixels differ by 2 or less.

   The output is a Gallery View, showing each set of duplicate images. If two 
   images are duplicates, the two images will appear in the output. The output 
   gallery is saved as album "Duplicate Images". You can use Batch Delete/Trash 
   together with this album to choose which duplicates to delete.

   \bCurrent Gallery option
   You can confine the search to image files in the current gallery. This can 
   also be the output of the \>SEARCH IMAGES\> function. Use this method to 
   select some subset of your image collection, using folder/file names, a 
   photo date range, etc.

   Performance (measured with a 4 GHz computer)
      Find 114 duplicates from 13K images, SSD disk:  17 seconds
      Find 762 duplicates from 56K images, SSD disk:  1.1 minutes
      Find 12K duplicates from 215K images, 5400 rpm disk:  13 minutes

MEASURE IMAGE
   +image: measure-image.png
   Click any two positions within an image to measure the pixel distance between 
   the points. The clicked positions are labeled A and B on the image. These 
   labels always show last two points clicked. The dialog is updated with the 
   distances separating these two points:
      X-distance (horizontal distance)
      Y-distance (vertical distance)
      H-distance (total distance)

SHOW RGB
   +image: show-RGB.png
   When a point on the image is clicked, the RGB values are shown in a dialog 
   window. The last 9 clicked points are displayed. 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. The outputs 
   are updated in real time if the image is being edited. If "labels" is checked, 
   the points are labeled on the image with letters A-I, corresponding to the 
   letters A-I in the dialog window. If "delta" is checked and the image is being 
   edited, then RGB changes are shown instead of the absolute values.

   If you open another image (e.g. to compare with the prior image), the 
   positions are kept and updated if they are within the new image boundaries. 
   This facilitates the comparison of images at the level of pixel RGB values.

POPUP TEXT
   Show a popup window with special characters and text strings to insert into 
   the currently focused dialog and edit widget. Click on the widget to insert, 
   if it is not the currently focused widget, then click on the character or text 
   string to insert into the widget. The text is inserted at the cursor location 
   in the widget. A default set of special characters is provided (see below). 
   You can add and remove whatever characters or text strings you need: use the 
   [Edit] button to make changes. 
   Some characters in this file: Ä Ë Ö Ü ä ë ö ü ß € ° ® ± ⁕ ‣ ▪ ➤ ᴧ ← ↑ → ↓

CALIBRATE PRINTER
   +image: printer-calibrate-chart.png  +image: calibrate-printer.png
   This utility may be able to improve the color accuracy of printed images.

   \bHow It Works
   A chart of colors is printed on the target printer. Some of the printed colors 
   will be slightly wrong due to printer imperfections. This printed page is 
   scanned into a file, and the colors in this file are compared to the original 
   colors that were printed. Any differences are errors that are now known. When 
   an image file is printed, these errors are subtracted from the image colors 
   before printing. The printer adds the errors back, leaving a result that is 
   theoretically correct. My own result was a modest improvement, detailed below.

   Hopeful Assumptions
      • Your scanner produces accurate colors. Scanners are generally more 
        accurate than printers.
      • The printer color errors are small enough that negating them before 
        printing will cancel most of the error. This is less likely if the 
        errors are large.
      • The limited set of colors in the chart (1728) can be used to calculate 
        all other colors (each color adjustment is interpolated from nearby 
        colors in the chart).

   Perform the following steps in sequence, as listed by the dialog window. 
   Each step has instructions to perform the step. All files normally reside in 
   the folder <fotoxx-home>/printer_color/.
      1. Generate and print the color chart file (printchart.png) on the printer 
         to be calibrated. Use large paper size, vertical orientation, no margins.
      2. Scan the printed chart into a PNG file. Use 300 dpi or more.
      3. Edit the PNG image to crop margins left by the scanner. Save the edited 
         image. The file name should contain printer settings and paper type.
      4. Process the edited chart file to create a color map file.
         Use a name indicating the printer settings and paper type.
      5. Print a color-adjusted image. Supply the color map file from step 4.

   After making the color map file, you can print any image using step 5 only.
   There is also menu function to do step 5 only: \>PRINT CALIBRATED\>.

   Precautions For Best Results
      • Use a large paper size for printing the chart to make the color tiles as 
        big as possible.
      • Clean the scanner glass before scanning the color chart. Smudges will 
        falsify colors.
      • Scan with a high DPI setting (300+) to make a large chart file. 
        This will make the next step more accurate.
      • Scanners can skew a scanned image into a slightly non-rectangular form. 
        If this happens, you will notice it when trying to crop the margins: the 
        fat green margin lines will not align perfectly with the crop rectangle, 
        even after slightly rotating the image for best fit. If his happens, use 
        \>PERSPECTIVE\> to square the image first, then crop the margins.
      • When editing the scanned chart image, be sure the darkest row is at the 
        top. Crop the margins surrounding the color tiles. Use the fat green 
        margin line surrounding the color tiles as a guide: cut off this line 
        exactly, leaving only the tiles. Work with 2x magnification while 
        adjusting the crop rectangle. Accurate cropping is critical. The tile 
        positions are calculated from the final image dimensions, assuming 35 
        equal columns and 50 equal rows. If some edge tiles are cut short, or if 
        margins are left, then the calculated tile positions will be offset, and 
        the measured colors will be wrong. A small error of 1-2 pixels is 
        tolerated, because the outer 20% of each tile is not used to read the 
        tile color. You can use the keyboard arrow keys to make 1-pixel movements 
        in the crop rectangle. The last corner pulled with the mouse is the 
        corner that the arrow keys will move.
      • If you notice any black or white spots in the scanned chart image 
        (from dust), fix them with \>COPY IN IMAGE\>.
      • The output color map file can be used only for the paper, ink, and 
        printer settings used for the calibration. Any other combination needs 
        its own calibration and color map file. Use the name of the color map 
        file to include this information, e.g. cmyk-glossypaper.dat.

   \bResults (my Canon printer)
   +image: printer-calibrate.png  +image: printer-cal-study.png
   The chart above is a photo of three images:
      upper left: a printout of a photo of a standard color chart
      upper right: a calibrated printout of the same photo
      bottom: the color chart itself

   You may be able to find a real ICC color profile for your printer and its 
   proprietary inks and photo paper. Using this would most likely produce better 
   results. Check the installation CD supplied with your printer, and the 
   manufacturer's web site. There are also professional services to generate an 
   ICC color profile. The procedure is similar to the one described above: you 
   print a color chart supplied by the service, send the printed chart back to 
   them (along with some money), and receive an ICC profile, a file which you can 
   install. Try a web search for "icc profile service".

GRID SETTINGS
   +image: grid-lines.png
   There are two grid line functions: Grid Settings sets all grid parameters. 
   Toggle Grid sets the grid lines on or off (showing or not showing in the image 
   window). Grid lines are horizontal and vertical lines at regular intervals 
   across the image. These lines can be useful alignment guides when an image is 
   unbent or warped to straighten walls or other objects in the image. The 
   settings for x- and y-spacing set the spacing (pixels) between lines. If the 
   controls for x- and y-count are NOT zero, the x- and y-spacing values are 
   ignored and the number of lines will be set from these counts. Example: set 
   x-count and y-count to 2 lines each in order to divide the image into thirds, 
   both horizontally and vertically. The x- and y-offset controls can be used to 
   shift the grid lines to intersect a desired point in the image. The x-enable 
   and y-enable checkboxes can be used to enable or disable the vertical and 
   horizontal lines separately. Use Toggle Grid to turn the grid lines on or off. 
   A keyboard shortcut (default 'G') can be assigned to Toggle Grid, so the grid 
   lines can be turned on or off with one keystroke. If an image is printed with 
   grid lines enabled, the grid lines are also printed.

LINE COLOR
   Some functions draw lines over the image (Crop, Select Area, 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 conveniently switch 
   among available colors (black, white, red, green).

DARK/BRIGHT PIXELS
   This function is used to highlight the darkest and 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 check 
   for brightness clipping.

MONITOR COLOR
   +image: moncolor-small.png
   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).

SHOW RESOURCES
   The following data is output to a popup report:
      • process time: CPU time used, since the last report
      • current main memory in use by Fotoxx
      • current space used for cached map tiles in ~/.cache/champlain/*


HELP MENU

+image: ug-help.png
   • User Guide - table of contents
   • Video Tutorial - Show a Fotoxx video tutorial on YouTube.
   • All Edit Funcs - Short descriptions of all edit functions in one place.
   • Outboard Programs - List optional outboard programs and provided functions.
   • Command Params - Show all available command line parameters
   • Change Log - Show additions, changes, and bug fixes in the current release.
   • Log File - Display the log file containing informational and error messages
                (same data visible if Fotoxx is started with a terminal command).
   • License - Shows the text of the Fotoxx usage and copy license (GNU GPL3).
   • Privacy - Shows a privacy policy summary, with a link to the full document.
   • About - Show installed and latest release numbers, contact, executable.
   • Uninstall - Delete all application files and optionally user data files.
                 If installed at /usr/bin etc. then sudo password is required.


OTHER TOPICS

VIDEO FILES
   Video files (.mpeg, .mp4, etc.) may be mixed-in with your image files. They 
   will show as image files in both file and Gallery View. The image shown is the 
   frame 1 second from the start. In File View, the keyboard is used to control 
   the video. The 'P' key will start, pause, and resume the video, or replay a 
   video that has ended. The 'Q' key will quit the video and close the window. 
   These keys cannot be customized. Use the \>SETTINGS\> menu to select the 
   application for playing video files. The thumbnail will show the 1-second 
   frame by default, but this can be customized to show any frame. Use the 
   function "Thumbnail Frame" from the right-click popup menu, from either the 
   full size image or the gallery thumbnail. Insert the playback time (minutes, 
   seconds) for the frame you wish to show in the thumbnail image.

WEB UPLOAD
   Most photo websites have the ability to upload multiple image files from a 
   single folder, using only a web browser. Use one of the Fotoxx functions 
   listed below to select and copy image files to the desktop or any other folder. 
   From there, use the photo website's native browser interface to upload the 
   image files.

   \>EXPORT FILES\> - copy selected files from many locations to a single folder
   \>BATCH CONVERT\> - same functionality plus many more options (see below)

   The first function is simple to use and can only downsize and copy image files.
   The second function can also downsize and copy, but it has many more features:
      • rename the files (combine old/new names, sequence numbers, photo dates)
      • convert to another file type
      • upright images turned 90 degrees
      • remove metadata
      • sharpen
      • add an overlay image (e.g. copyright text) at designated position

   \bPrivacy Warning
   Photos contain metadata you may not want to make available to others.
   Please review the information at 
      \_https://gitlab.com/fotoxx/fotoxx/wikis/privacy.

MOVE FOTOXX HOME
   The default location for 'fotoxx home' is  /home/<user>/.fotoxx (like most 
   Linux apps). This folder is where Fotoxx data is kept, including index data 
   and user settings. If you have multiple Linux systems on your computer, and 
   you want them to share the same Fotoxx data, or if you want your Fotoxx data 
   to be retained after a "clean install" of Linux, you can move Fotoxx data from 
   /home/<user>/.fotoxx to another folder, typically on a mounted volume.
   
   NOTE: this may clash with security restrictions you may not be aware of. User 
   files outside the normal user home folder (/home/<user>) may be inaccessible 
   unless you take extra measures. 
   
   In the following, "/<mount-point>/fotoxx" means the new Fotoxx home folder. 
   
   1. Set the current folder to your normal home folder:
         $ cd $HOME                                       # /home/<user> 
   2. Create the new Fotoxx home folder: 
         $ sudo mkdir /<mount-point>/fotoxx
         $ sudo chown user:user /<mount-point>/fotoxx     # user = your username
   3. Copy Fotoxx files to the new home folder: 
         $ cp -p -R  .fotoxx/* /<mount-point>/fotoxx
   4. Edit the file /<mount-point>/fotoxx/image_index_*/image_folders
         from: /home/<user>/.fotoxx/thumbnails            # fix thumbnails folder
           to: /<mount-point>/fotoxx/thumbnails
   5. Create a pointer file to the new home folder:
        - gedit .fotoxx-home                              # use any text editor
        - file content (1 line only): /<mount-point>/fotoxx
   6. Rename the old Fotoxx home folder (to disable it) and test Fotoxx:
        $ mv .fotoxx .fotoxx-old
   7. After testing that everything works, remove the old home folder and files:
        $ rm -R .fotoxx-old

   See \>COMMAND PARAMETERS\> -home parameter 
   if you want multiple image collections, managed separately.

ORGANIZING IMAGES
   The goal is to find all images for given criteria, e.g. photos of a given 
   person at a given place and/or time range, all photos of a given person, 
   photos from a specified location or event, etc. There are several ways to 
   organize an image collection to accomplish this, with advantages and 
   disadvantages you need to understand. The methods listed here (except for 
   albums) are standards compliant and will work with other programs that support 
   the same methods. These are (1) searching based on metadata (dates, ratings, 
   tags (keywords), geotags (locations), titles and descriptions, and (2) 
   searching based on folder and file names or partial names.

   \bRelevant links
   \>EDIT META\>  \>BATCH TAGS\>  \>BATCH RENAME TAGS\>  \>BATCH GEOTAGS\>  
   \>BATCH CONVERT\>   \>SEARCH IMAGES\>  \>PLACES/DATES\>  \>TIMELINE\>  
   \>INDEX FILES\>  \>MANAGE ALBUMS\>

   Fotoxx can search using the following image metadata: photo date, file date, 
   rating (0-5 stars), tags (keywords), geotags (location names geocoordinates), 
   and text appearing in titles and descriptions. Searching based on file and 
   folder names can also be combined with metadata searching. Any other metadata 
   can also be searched, although not nearly as fast as the items listed, which 
   are duplicated in a special index file for fast searching. A strong computer 
   can search for the listed metadata items and file folders/names at a speed 
   exceeding 10K images per second.

   All of the search methods described below can be used in combination. The 
   output of a search function can be the input of another search function (to 
   further narrow the search), and search outputs can be added to prior searches.

   The following is an overview of different ways images can be made searchable.

   \bFolder and File Names
   These can be used as a basic organization that will enable you to find images 
   even if more effective organizations are not used. The highest physical 
   organization should be by time, because this will naturally group photos 
   together that are related. I suggest using one subfolder per year named 2001, 
   2002, etc. This will also prevent any one subfolder from getting too big. 
   Optionally, image files may be further organized in time sequence by using 
   MM.DD as the start of the file name. The rest of the name can be a topic, 
   location, or event, and a sequence number.
       Example:  /images/2011/08.20 Spitzbergen 23.jpg
   This very basic organization allows Fotoxx to find files by searching for 
   years and topics (in file names). In the above example, a search for 
   "spitzbergen" or even "spitz" will produce all the images of Spitzbergen. 
   Years can be also be searched and combined with topic searches, e.g. 
   "2012 Paris". The Batch Convert function lets you rename a batch of photos 
   taken at one location or event by specifying a template name like this:
      "$mm.$dd Spitzbergen $ss"
   Month and day (from the EXIF photo date) replace $mm and $dd. "Spitzbergen" 
   replaces the camera file name (P00123456), and a sequence number replaces $ss.

   \bTitles and Descriptions
   A simple method of organization is to use image titles and descriptions. These 
   are arbitrary text strings that can be added to a series of images in rapid 
   sequence: Start Edit Meta, open an image, input text, press [apply], press 
   [next], input text ... Titles and descriptions are two separate inputs but 
   treated logically the same. They are searchable: words appearing in titles and 
   descriptions can be searched. You can specify persons, location, topic, etc. 
   for each image and then find them again quickly.

   \bTags (EXIF keywords)
   The most powerful tool is tags, but this also requires the most 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 using AND/OR combinations of tags, also in 
   combination with other criteria. Tagging is generally fast, needing a few 
   seconds per image. Fotoxx has two methods of adding tags, a "managed" system 
   and a "random" system. In the managed system, you define tag category names 
   and the tags within each category. When adding tags to images, you can point 
   and click from a list of tags organized by category and alphabetically within 
   category. In the random system, you simply create tags as needed while you tag 
   your images, following no particular system and without categories. When you 
   enter the first few characters of a tag, existing tags that match these few
   initial characters are shown in a pick-list which you can click to complete 
   adding the tag. If there is no match, a new tag is created. Recently used tags 
   are also shown in a list that can be clicked. Photos made at the same time 
   will normally be tagged in sequence, and will also share many of the same tags. 
   The recent tags list helps to speed the tagging process. Use Batch Add/Remove 
   Tags to add the same tags to many images. Batch Rename Tags can be used to 
   rename tags in selected (or all) images. Tags can be searched in combination 
   with other search criteria such as a date range or location(s).

   Note that images downloaded from the Internet may have many tags adhering to 
   no system. You will need to clean these out or redo them to stop them from 
   cluttering your list of defined tags. If you see undesired tags in your list 
   of defined tags, it is easy to find the offending image files and purge or 
   change their tags: use the Search Images function to find the images, using 
   the unwanted tags as search criteria, and feed this list to Batch Add/Remove 
   Tags or Batch Rename Tags. Tags from downloaded files will have no category, 
   which keeps them separate from tags you define (if you are using the managed 
   tags method). Still, you should avoid accumulating thousands of random tags, 
   and it is easy enough to get rid of them whenever they appear.

   \bGeotags
   Use geotags to assign a city or location and country to your images, and 
   optionally latitude/longitude. This enables all images for a location to be 
   quickly found. If you use a camera with a GPS receiver, geotags are added to 
   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 in-camera GPS is that the location 
   names are chaotic and you may want to sanitize them (mixed upper/lower case, 
   with/without states or other subdivisions, mixed languages, etc.). You can fix 
   the mess with a little effort: search for the location name you want to change 
   (e.g. MUENCHEN, BAYERN, DEUTSCHLAND), then process the resulting images with 
   the \>BATCH GEOTAGS\> function to change location names (e.g. Munich, Germany). 
   Location names can be searched in any combination.

   When you add geotags to an image manually, it is usually sufficient to enter 
   just the city or location name and then press [Find]. If the location has been 
   entered sometime in the past, it will be recalled and all geotag data will be 
   filled-in automatically (city/location name, country, latitude, longitude). 
   This will also work if only a few characters of the name is entered, e.g. 
   "hono" will recall the data for Honolulu, if available. When a location is 
   entered for the first time, enter the city or location name and country, and 
   press the [Lookup] button. The location coordinates are found from an internal 
   table. If still not found, you can use Wikipedia or other web service to find 
   the location coordinates and enter them manually.

   Images with geotags are also searchable by clicking markers on a world map. 
   The markers are automatically added to the map for all images containing 
   geotag coordinates. The map can be zoomed to any scale from street-level to 
   planet level.

   \bAlbums
   Another method of organization is to use Albums. Choose a name for each album 
   and assign any desired images to the album by clicking thumbnails in gallery 
   pages. The images are not duplicated: the album is simply an ordered list of 
   file names. Albums can be selected by name and viewed as a gallery of 
   thumbnails. These can be rearranged via thumbnail drag and drop. The images 
   can then be viewed sequentially using keyboard arrow keys, randomly by 
   clicking thumbnails, or as a slide show with animated transitions between 
   images. Albums are also implemented in some other photo management apps, but 
   each one is different and incompatible.

   The image search function can be used to find images to start a new album, 
   and then images can be added, removed, and rearranged as needed. Images can 
   be added simply by clicking gallery thumbnails as you browse your image 
   collection.

   \bSummary
   The following is a summary of some ways to organize a large image collection, 
   with factors to consider when choosing which methods you want to use. In the 
   list below, "search by" specifies which search criteria can be used with each 
   option. Many of the methods below can be combined, and the possible search 
   criteria increases accordingly. Searching by folder and file name and by photo 
   date (EXIF) is available with any organization.

   Images Organized by Topic
      • images are in a topic-named folder (a very common practice)
      • e.g. /.../Susan 8th birthday/P0123456.jpg    (file names from camera)
      • e.g. /.../Paris 2014/Notre Dame 12.jpg       (meaningful file names)
      • fast implementation: no work if this is your starting point
      • Gallery View is by topic only (poor overview if very many topics)
      • search by: topic (using file names)
      • no overview of available search topics

   Images Organized by Year and Topic
      • e.g. /.../2014/Italy/Rome-12.jpg
      • e.g. /.../2014/Susan Wedding/P123456.jpg
      • fast implementation: move your topic folders into year folders
      • Gallery View by year and by topic within year
      • search by: topic (using file names)
      • no overview of available search topics

   Images Organized by Year, Month, Day and Topic
      • e.g. /.../2014/08.22 Rome-12.jpg
      • use Batch Convert to format new names from existing groups of image files
      • natural grouping of related images
      • gallery overview by year, in time order, with topics visible
      • search by: topic (using file names)
      • no overview of available search topics

   Image Folder and File Names Contain Topics
      • e.g. /.../travel/2014/Italy/Rome-Susan-Coliseum.jpg
      • many folks have done this, to search images using a file search utility
      • you may end up with hundreds of galleries with a few images each
      • search by: topic (using folder and file names)
      • no overview of available search topics

   Titles and Descriptions
      • e.g. "Susan 2014, Coliseum in background"
      • simple and easy to use
      • moderately fast implementation: 10+ seconds per image
      • risk inconsistent names, unreliable search (e.g. search "Rome" fails)
      • search by: title and description (any contained word or words)
      • no overview of available search topics

   Managed Tags
      • e.g. "Rome, Italy, Susan, birthday"
      • point and click in a tag list to add tags to images
      • tags have categories for faster visual location of tags to click
      • typing a few characters is usually enough to retrieve a defined tag
      • recent tags are also available for easy re-use while tagging images
      • no inconsistent or redundant tags, no typos to make searches unreliable
      • requires careful planning of tags - later revisions are cumbersome
      • batch add/delete/rename is available for tag revisions
      • search by: tags in any combination
      • good overview of available search topics (tags organized by category)
      • tag categories are not standard and will not be visible in other apps

   Random Tags
      • no tag organizing system, tags created as needed while tagging images
      • legacy tags can be kept unchanged
      • typing a few characters can retrieve a tag that has been used before
      • recent tags are also available for easy re-use while tagging images
      • risk inconsistent tags (scenery/landscape, Susan/Susy) and typos (scnery)
      • search by: tags in any combination
      • overview of search topics: one large pile of tags in alphabetic order

   Geotags
      • e.g. Rome, Italy, 41.89 N, 12.48 E
      • cameras with GPS store this data automatically in images
      • you can manually add locations (5-10 seconds per image)
      • you can \>BATCH GEOTAGS\> many images at a time
      • inconsistent location names from cameras (fixable with effort)
      • map markers are generated automatically from image geotag data
      • search by: location (city, park, monument ...) and country
      • click on a map marker to show a gallery of images at location

   Albums
      • album names like this: favorites, best scenery, Italy 2014, Susan
      • albums are a list of contained image files, which are not duplicated
      • make albums using any criteria, containing any images
      • images can be in multiple albums or multiple times within an album
      • images can be arranged in an album by dragging thumbnails to position
      • add images by selecting / dragging gallery thumbnails to album gallery
      • albums are the basis for the slide show function
      • overview of available albums - click on album name to view gallery
      • albums are only usable within Fotoxx (there is no standard for albums)

PRIVACY
   \bSummary: Fotoxx does not collect or share personal data.

   \bImage Metadata
   To enable fast image searching based on metadata, Fotoxx saves image file 
   metadata separately from the image files themselves. This is within your own 
   computer and not accessible to others unless you allow this. If your images 
   have greater security needs, consider using security tools to block malware, 
   prevent intrusion through the network, and restrict access to sensitive files.

   If you upload your image files to a web application (e.g. Facebook, Instagram), 
   embedded metadata is exposed to the web application and others who download 
   your images. For example, others could find out where you have been and at 
   what time, from GPS metadata inserted automatically into your photos by your 
   camera, or added later using Fotoxx or other tools. To prevent this, you can 
   use Fotoxx to clear metadata from images before uploading them.

   \bYour Public IP Address
   If you download a Fotoxx installation package from the Fotoxx hosting web 
   server (kornelix.net), your IP address will remain in the server log files up 
   to one month. Your internet service provider can identify you from this IP 
   address. Normally this is restricted by law to authorized government agents.

   More information:
   \_https://gitlab.com/fotoxx/fotoxx/-/wikis/privacy

PROBLEM REPORTING
   If something does not work, or if Fotoxx crashes, there are two ways to 
   clarify the problem or provide information for the Fotoxx author to fix the 
   problem. These are the Fotoxx activity log file and the crash report file. 
   These are ordinary text files which can be sent to the Fotoxx author by e-mail: 
   mkornelix@gmail.com. If you do this, it would be helpful to describe what you 
   were attempting to do when the problem happened. My best chance to fix the 
   problem is when I can reproduce it. Send the problem image file also, if this 
   is relevant. 

LOG FILE
   Fotoxx outputs an activity file or log file which traces user and program 
   actions. The level of detail can be set by the user (see \>SETTINGS\>). You 
   can view this file during a Fotoxx session using the menu Help > Log File. 
   The file is replaced with each new Fotoxx startup. 
      To view after a Fotoxx session: $ cat $HOME/.fotoxx/fotoxx*.log.
   If you are having problems with a particular image file, you may be able to 
   get some clarification by looking in the log file. Programs used by fotoxx, 
   such as exiftool and libtiff, write error messages to this log file. If a 
   particular image file is causing a problem, I suggest you move this file to 
   your blacklist folder to stop it from making problems.
   
   If Fotoxx crashes, it is usually able to produce a backtrace dump before 
   exiting. This is a file named "zappcrash". Fotoxx adds this file to the Log 
   file and copies them to your $HOME folder to make them easier to find. Look 
   for "fotoxx-*.log" in your home folder and send this to mkornelix@gmail.com.

QUESTIONS, SUGGESTIONS
   If you have a question or a suggestion for improvement, you can contact me 
   by e-mail: mkornelix@gmail.com


TECHNICAL TOPICS
   Additional technical topics can be found on the Fotoxx web site:
      \_https://kornelix.net

FOTOXX LIMITATIONS
   • 1 million indexed image files - Fotoxx has been tested with 680K image files.
   • image size - The max. supported image width or height is 50K pixels.
     The maximum image size is 2048 megapixels (32 GB unpacked in memory).
     (images edited in memory use 4 floats (16 bytes) per pixel, RGB + alpha).
   • image versions - up to 99 versions for undo/redo and file version naming.
   • image tags - 10K total tags. 1000 characters for a single image.
     These are compile time limits and could be easily increased.
   • Galleries are generally limited to 100K image files, so you should not have 
     folders containing more than 100K files. The gallery size limit can be less 
     than 100K if the currently selected thumbnail size is larger than 256 pixels. 
     Gallery size limits also apply to search results, albums, and reports. 
     You are notified with a popup message if a gallery is truncated. 
     The limits for 360 and 512 pixel thumbnails are 64K and 35K files.

RUNNING OUT OF MEMORY
   Fotoxx can require a huge amount of main memory to edit a large image. A 20 
   megapixel image requires 640 megabytes for the simplest edits, and much more 
   for complex edits. Images in memory are not compressed. Each image pixel is 
   represented by four 'float' numbers (16 bytes total) for red/green/blue/alpha. 
   HDR, Panorama and other combine functions hold all images in memory during 
   alignment and post-process tuning. If you push the memory limits on a small 
   PC, the Linux kernel may kill the Fotoxx process without warning and with no 
   message (this is to keep the operating system itself from crashing). What you 
   see is that the Fotoxx window vanishes. Fotoxx tries to anticipate when it is 
   about to run out of memory, and makes a graceful exit with a popup message. 
   This is not always successful. If the Fotoxx window vanishes, check the log 
   file after restarting, and check for the message "killed", which is all you 
   get from the Linux OS.

   Fotoxx memory footprint
      • View 30 megapixel image              324 MB
      • Retouch 30 megapixel image           670 MB
      • Rotate 30 megapixel image            980 MB
      • Rescale (down) 30 megapixel image    1.4 GB
      • Local Retinex 30 megapixel image     3.5 GB
      • Panorama, 50 megapixel output        4.8 GB

   Bottom line: If you edit large images, you need a minimum of 8 GB of main 
   memory, and 16 GB is recommended. If Fotoxx exceeds physical memory and 
   requires the swap file during processing, this may work acceptably, may get 
   killed by the OS, or may take so long that you give up and kill the process.

RUNNING OUT OF DISK SPACE
   During a series of image edits, each edit step is saved on disk, and the 
   before/after results can be viewed with the Undo/Redo button. These images 
   use 32-bit floating point numbers for color values and are not compressed. 
   A 30 megapixel image makes a 480 MB file. If there are 10 edit steps in the 
   undo/redo stack, the required disk space is 4.8 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 Fotoxx home folder 
   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.

SYMBOLIC LINKS
   Symbolic links are supported in a limited manner. Take the time to understand 
   these limits if you are using symbolic links. This is complicated, and it is 
   easy to make mistakes if you are not aware of the pitfalls.

   The image index and thumbnail files are only created and maintained for the 
   real path. For a given image file, only one index entry and thumbnail can 
   exist. If a symlink path is used to access and modify an image file, the 
   symlink is converted into a real path before use. If a new file version is 
   created, it will exist in the same real path as the original file. If there is 
   a symlink to a parent folder of the original file, the new file version will 
   also exist in that same path, just like the original file. If the symlink is 
   direct to the file that was modified, and a new version is created, the new 
   file version will be only in the real path of the original file. No parallel 
   symlink is created like the one that links to the original file. On that path, 
   only the original file is visible.

   The Image Search function finds real paths only.

   Symlinks direct to an image file may have \bno extension or a misleading 
   extension (e.g. /.../filename.png links to /.../filename.jpg). Technically, 
   this works because the real path is used to choose the library function to 
   read and write the file.

   Good advice: never use symlinks direct to image files - use folder links only 
   (and this should also be avoided because you will some day outsmart yourself 
   and make a catastrophic error).

   \bHard Links
   Fotoxx does not know about these and processes them like normal folders or 
   files. The result is that duplicate index entries and thumbnails are created. 
   If an image file having multiple hard links is modified in Fotoxx, only the 
   index entry and thumbnail for the access path that was used is updated. 
   Others become invalid.

PREVIEW MODE
   Some edit functions use a reduced image size for a faster interactive response 
   time. This is shown on the top panel as "(reduced)". When [done] is pressed, 
   the full-size image is then processed. This is why [done] sometimes takes 
   noticeable time. An image sized for the monitor (2-4 megapixels) is much 
   faster to process than a 20+ megapixel image (the original camera file). This 
   method is used whenever the preview edits can be applied to the full-size 
   image without visible impact (e.g. Crop, Rotate, Warp, and all brightness and 
   color related functions). It cannot be used for some other functions (e.g. 
   sharpen, Gradients) because the results cannot be rescaled for a larger image.

SUPPORTED FILE TYPES
   Fotoxx uses Linux library functions to support reading and writing of image 
   files: the GDK pixbuf library, libjpeg, libpng, libtiff. The file types that 
   can be read and written include JPG/JPEG, PNG, and TIF/TIFF. Three RGB colors 
   with 8 bits per color are supported for all types. PNG and TIFF also support 
   16 bits per color and an alpha channel (opacity level). Fewer than 8 bits per 
   color and grayscale images are partly supported, and are converted to RGB 
   internally. Some other file types are partly supported: they are indexed and 
   thumbnailed and can be viewed and edited normally, but modified files are 
   saved as .jpg files with a version number. These file types are: .heic .webp 
   .jp2 .avif. Adobe files (.pdf/.ps/.eps/.psd) can be converted into jpeg image 
   files using the function \>CONVERT ADOBE\>.

INDEX DATA FILES
   These files can be found in the folder <fotoxx-home>/image_index_*/
   image_folders: a list of the top image folders and the thumbnails folder
   image_index: image file pathnames and indexed metadata items
   meta_index: optional metadata items that have been added to the image index.

COLOR DEPTH ISSUES
   8-bit color (256 brightness levels), as supported by JPEG files, is the norm 
   for image files and is generally adequate. A difference of one brightness step 
   (0.4% of entire range) cannot be seen. A greater color depth than 8 bits can 
   be useful if some part of the brightness range in an image has been greatly 
   expanded by editing. This can lead to visible "banding" or "posterization". 
   If the RAW image is edited instead of the JPEG (and if the RAW image really 
   has more than 8 bits of low-noise color), this problem can be reduced, even if 
   the edited image is converted back to JPEG for final storage. Currently, only 
   expensive cameras with large sensors produce RAW files with more than 8 bits 
   of low-noise color at normal exposure levels (ISO <1000). 

   The image below changes gradually from black to white. The color depth is 
   6 bits (64 brightness levels). The brightness steps are barely visible.
   +image: brightness-steps.png

NOISE MEASUREMENT
   This is how the \>DENOISE\> function measures the noise level of an image file. 
   An area of radius 10 pixels around the clicked position is sampled. The RGB 
   brightness levels reported (0-255) are the averages for this area. Within this 
   area, every pixel is measured and compared with the mean of the surrounding 
   5x5 block of pixels. The RGB noise levels reported are the average differences. 
   If the sampled area has a small gradient in brightness, the measurement is not 
   sensitive to this. If a RAW image is measured, a 16-bit TIFF made from the RAW 
   is used. The graph scale is -10 to +10 and the dotted lines are at -5 and +5. 
   These values are relative to a total brightness range of 0-255. Noise in the 
   9th or 10th bit would be 0.5 or 0.25 on this scale. The accuracy of this 
   method depends on selecting a "flat" image area such as a badly out of focus 
   area or a very uniform area like a gray cloud. Inspect the image at 400%
   magnification to be sure you are seeing noise and not real image texture.

RAW IMAGE NOISE
   You may be surprised at the typically high noise levels in RAW images. Cameras 
   filter out this noise when making a JPEG image. Expensive cameras with large 
   sensors may have more than 8 bits of low noise color, especially if the image 
   is well exposed at low ISO levels. The bit-depth claims are exaggerations, 
   since noise will predominate at the deeper bit levels. When you use Fotoxx or 
   any other tool to filter noise from a RAW image, you are competing with the 
   camera maker's electronics and software used to produce the camera JPEG. It 
   might be a challenge to do better.

SLIDES AND NEGATIVES
   It is quite easy to capture slides or color negatives and create images with 
   good color. The initial image can best be captured with a slide scanner. You 
   can also use a camera, especially one that can focus very close to create a 
   large enough image (>1000 pixels). Many consumer cameras with zoom lenses can 
   do this. Use a light box to illuminate the slide or negative. Lacking this, 
   you can use a blue sky as the light source (example below). A slide photo may 
   need minor color adjustments. To process a color negative, you must first make 
   a positive (\>COLOR MODE\>). The result may be already good. If the image is 
   foggy, select the image only, excluding the film edges, and then use 
   \>GLOBAL RETINEX\> to eliminate the fog. Set the white and black points by 
   clicking on the image if needed to further reduce fog. The result is usually 
   good, but you can still tweak the Retinex controls to fine tune the color if 
   needed. The image here was hand held to photograph, and the single image frame 
   was selected for processing. 
   +image: color-negative.jpg

HIGH QUALITY IMAGE UPSCALE
   +image: upscale+sharpen.jpg
   Here is a method to upscale an image by 2x while retaining the best quality 
   (minimize jaggies and blur). The left image is a cutout from a 2x upscale of a 
   NASA image of an asteriod. The upscale has added jaggies to high-contrast 
   feature edges and increased blur everywhere. The right image was made with two 
   more edits: Anti-Alias (1 iteration) cleaned up the jaggies. The image was 
   then sharpened using the Richardson-Lucy method (radius 1.4, iterations 4). 

ROTATE PERFORMANCE
   Interactive rotations (via mouse drag or the [degrees] spin button) update the 
   image 20 times per second or more. Two special methods are used to recalculate 
   the rotated image faster: (1) a smaller image is used, which is scaled up to 
   full size when the [OK] button is pressed. (2) a fast rotate method is used 
   having lower image quality, followed by a high-quality method applied one 
   second after all image rotation motion has ceased. If you zoom the image to 
   2x or more and use the spin button to rotate the image, you can see pixelation 
   on sharp feature edges which disappears in one second.

ALIGNMENT ALGORITHM
   Combined images for panorama, HDR, etc. must be accurately aligned to avoid 
   fuzziness in the output image. Relatively few high-contrast or "feature edge" 
   pixels are used to control alignment. These pixels 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 camera lenses are not geometrically perfect.

ALPHA CHANNELS
   Images having alpha channels (transparency information) can be edited, and the 
   alpha channel is preserved if the image is saved as a PNG or TIFF file. JPEG 
   files do not support alpha channels, and transparent areas are black when 
   saved as JPEG. 

IMAGE DETERIORATION FROM REPEATED EDITS
   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 file is first processed, to minimize image deterioration 
   (or go back to the original if you still have this). Any function that changes 
   image size or shape will reduce  resolution about 1/2 pixel. These are rescale, 
   rotate, warp, and all combine functions. Rotating 90 degrees does not affect 
   resolution. When downsizing an image, using ratios 1/2, 1/3, 1/4 will give the 
   best resolution. Functions that change brightness and color do not affect 
   resolution.

INTERPOLATION METHOD
   +image: interpolation.png
   When an image is rescaled, rotated, or warped, the resulting output pixels 
   must be "interpolated" from corresponding input pixels. In the illustration 
   above, the large red box represents an output pixel in an image downsized to 
   about 1/3 size. The small black boxes represent the input pixels contributing 
   to the output pixel. The output pixel is overlayed over its input pixels, with 
   the red dot marking the center of the output pixel. The most common method of 
   constructing the output pixels is "bilinar interpolation". In this method, 4 
   input pixels (A/B/C/D) near the center of the output pixel are mixed to 
   provide the RGB alues of the output pixel. The weight of each input pixel is 
   inversly proportional to its distance from the center. Note that the nearest 
   input pixel, the one with the red dot, is not included. The results are OK for 
   small changes of scale (about 1/3 to 3x) and increasingly worse for large 
   changes. Fotoxx uses a more precise method that works for any scale. ALL input 
   pixels contribute to the output pixel (16 in the example). Their weights are 
   proportional to their area of overlap with the output pixel. This is not as 
   fast as bilinear. Multiple execution threads are used for maximum speed. On my 
   strong computer, downsizing a 200 megapixel image to 1/4 size takes about 0.24 
   elspsed seconds, so not a problem here. A slower computer could need a second 
   or more for this. 

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 an image quickly to 
   be ready for the next photo, so the processing time available for compression 
   is limited. The CPU of a typical PC is 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 JPEG SAVES
   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 file. Differences can be seen if you look hard enough. The 
   images are 2x size and the insets are 5x.
   +image: jpeg-quality.png

METADATA ERRORS
   Cameras (esp. older ones) do not always produce structurally correct metadata, 
   and the program exiftool (used by Fotoxx to manipulate metadata) may produce 
   error messages. I have been able to fix these cases by saving the image file 
   on top of itself, which replaces the metadata with whatever exiftool was able 
   to read correctly. If desired  metadata gets lost, you can restore it manually 
   using the Edit Any Meta function.

NEWLINE CHARACTERS IN METADATA
   When editing metadata image descriptions, if you need to align text columns, 
   you can use the [enter] key to force new lines. These are converted to 
   backslash + 'n' before being stored in image metadata, since newline 
   characters are not allowed (they are converted to periods). If the text is 
   viewed or edited again, these substitutions 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 with other image viewers. 
   If this is a requirement, then don't use the enter key to make new lines when 
   entering long text - just let the text overflow to the next line by itself. 
   In this case, column alignment is not possible.

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 used. This works, mostly. Sometimes the window manager decides some 
   other position.

FOTOXX PERFORMANCE
   Fotoxx has four significant performance limitations:
     • Indexing newly added image files found at Fotoxx startup time
     • Startup time for a large image database on a slow disk drive
     • Search time for non-indexed metadata
     • Editing very large images (>100 megapixels)

   At startup time, Fotoxx searches all declared top image folders to update 
   thumbnails and the metadata index. The processing speed for NEW image files 
   can range from as low as 300/minute for a slow computer and slow spinning 
   disk, up to 20K/minute for a fast computer and fast SSD disk. File size is 
   also a factor: large RAW files (20-50 MB) are much slower than ordinary JPEG 
   files (1-5 MB).

   The search for new image files needs time, even if there are no new files to 
   process. The speed can range from 8K files/sec. for a slow spinning disk, up 
   to 30K/sec. for a fast SSD disk. This is for the first Fotoxx startup after a 
   computer reboot. Subsequent startups are about 2x faster, because some folder 
   and file data is cached in memory. You can omit the automatic search for new 
   files if wanted, to keep Fotoxx startup time under 1 second (see \>SETTINGS\>). 
   Use this option for files clicked in a file manager (Nautilus etc.), to make 
   the file display instantly.

   Searching for metadata that is indexed is almost instantaneous. Metadata that 
   is often used for searching (e.g. tags, locations, image titles) is indexed by 
   default, and you can add other items if wanted (see \>INDEX FILES\>). The 
   search speed for non-indexed metadata can range from 3K to 100K files/minute, 
   depending on computer and disk speed. For 100K files on an SSD disk, searching 
   for non-indexed metadata would require about 1-2 minutes, whereas searching 
   for indexed metadata is under 1 second. Metadata items you need to search 
   often should be included in the list of indexed metadata.

   Fotoxx can edit images up to about 2048 megapixels if sufficient memory is 
   available. On a strong computer, response time for most edit functions is 
   below 1 second for images up to 30 megapixels or so. Beyond this, expect 
   responsiveness to decline. 
   
   Here are some benchmarks comparing old laptop with a strong desktop computer.
      laptop:  Core-i5 2430    2.4-3.0 GHz  4 cores      5400 rpm rotating disk
      desktop: Core-i5 13600K  3.5-5.1 GHz  6 P-cores    SSD disk 
      test database: 13677 mostly jpeg files, 35 GB total
      test image file: 41 megapixel jpeg
   
   \bbenchmark                                         old laptop     new desktop
   index + thumbnail creation, 13677 files            26 min         0.7 min
   startup time, no index                             0.6 sec        0.4 sec
   startup time, use existing index                   0.7 sec        0.4 sec
   startup time, use index + search for updates       2.4 sec        1.2 sec
   sharpen, kuwahara 5                                85 sec         7.0 sec
   sharpen, Richardson-Lucy, R=5, I=5                 345 sec        23 sec
   normal blur, R=30                                  12.5 sec       2.9 sec
   make simulated painting                            15.7 sec       6.5 sec
   find duplicate images                              50 sec         6.4 sec
   search indexed metadata for given text             <1 sec         <1 sec
   search non-indexed metadata for given text         264 sec        9.6 sec
   view 335 megapixel image via thumbnail click       3.8 sec        1.4 sec
   
   Note that some benchmarks match the CPU performance, others the disk 
   performance. Some are mysterious, e.g. the above sharpen benchmarks. 

GTK TIMEOUT PROBLEM
   GTK applications try to detect endless loops with a timeout timer. If the 
   timer is not reset within a time limit, the application is thought to be 
   looping, and a popup dialog will offer the options of killing the application 
   or allowing it to continue. Fotoxx sometimes does things that take a long time, 
   and the timer is not reset fast enough (e.g. using libpng to read a huge .png 
   file can require >20 sec). Fotoxx sets this timer to a large value to reduce 
   the possibility that this confusing annoiance happens. This timer affects all
   GTK applications.

FOTOXX PACKAGES
   Installed files from source package ($ sudo make install)
      /usr/bin/                           executable file (fotoxx)
      /usr/share/applications/            desktop file
      /usr/share/fotoxx/                  user guide, images, default data, etc.
      /usr/share/doc/fotoxx/              change log, license, copyright, etc.
      /usr/share/man/man1/                man page

   Installed files from binary package ($ install.sh) 
      $HOME/.local/bin/                   executable file (fotoxx + fotoxx.x) 
      $HOME/.local/share/applications/    desktop file
      $HOME/.local/share/doc/fotoxx/      change log, license, copyright, etc.
      $HOME/.local/share/fotoxx/          user guide, images, default data, etc.
      $HOME/.local/share/fotoxx/lib/      some library files for portability

   The binary package includes some libraries used by Fotoxx, but only those 
   likely to vary depending on Linux flavor and release date. This package should 
   run OK on most recent flavors of Linux. 

FOTOXX HOME FOLDER
   • Fotoxx Home: folder for user preferences, settings and general Fotoxx data
   • Default Fotoxx home location:  /home/<user>/.fotoxx/
   • If Fotoxx home was moved elsewhere (see \>MOVE FOTOXX HOME\>), the file
        /home/<user>/.fotoxx-home  contains the location of the new Fotoxx home.
   • The files in Fotoxx home are preserved across a new release of Fotoxx.

   \bFiles in Fotoxx home
      albums/              image albums from Manage Albums function
      custom_kernel/       saved custom kernel data files
      custom scripts/      saved script files for custom edits or batch edits
      file_maps/           map files for both downloaded maps and custom maps
      image_index_*/       top folders, thumbnail folder, image index file
      image_array_maps/    saved image array maps (embedded image locations)
      markup/              saved text strings for markup->draw text
      mashup/              saved mashup project files
      palettes             color palettes used by the Dither function
      patterns/            saved background patterns
      printer_color/       saved printer color calibration files
      retouch/             saved settings for the Retouch function
      saved_areas/         "cutout" files saved from Select Area > Save dialog
      saved_curves/        saved node points for saved edit curves (e.g. retouch)
      saved_searches/      saved settings for the Search Images function
      slideshows/          user settings from Slide Show function
      slideshow_trans/     saved slide show transition parameters
      temp/                temporary files for current sessions
      thumbnails/          thumbnail files (default location, user can change)
      blacklist            list of files with internal errors - not usable
      bookmarks            bookmark names and image file locations
      capskeys             metadata keys for captions shown at top of image
      colorwheel.jpg       color selection palette for Paint Image function
      custom_menu          list of functions included in custom user menu
      drag_from_folder     memory used by 2 fotoxx processes to drag/drop files
      folder.png           optional, from user: customize gallery folder icon
      fotoxx-NN.N.log      activity log - may be relevant for diagnosing problems
      gallery_memory       saved sort order and position for gallery windows
      KB-shortcuts_*       user-defined keyboard shortcuts
      meta_picklist_*      metadata key names for GUI pick lists
      meta_report_items    list of metadata items reported by Batch Report Meta
      meta_view_extra      extra custom items for the metadata short report
      netmap_locations     saved locations in net map view
      pagesetup            saves page setup data for print function
      parameters           parameters that are saved across Fotoxx sessions
      plugins              saves the plugins menu contents
      popup_text           collection of special characters for text widget input
      printsettings        saves print settings data for print function
      recent_files         list of the last 1000 files opened by Fotoxx
      recent_topics        recent topics viewed in the user guide
      search_results       output of image search function, list of image files
      slideshow-tone.oga   a short music tone for slide show
      tags_defined         list of all categories and tags currently in use
      userguide            text file copy of user guide without images
      wallpaper            fotoxx wallpaper tool - last used wallpaper file
      widgets.css          styling changes to standard GTK widgets
      worldcities.txt      geocoordinates for all significant world cities
      zdialog_geometry     saved dialog window positions (within main window)
      zdialog_inputs       saved dialog data for dialogs that recall prior inputs

IMAGE METADATA USAGE
   The following metadata items (stored inside image files) are used by Fotoxx. 
   These items (like any metadata) can be viewed or edited using Fotoxx. Images 
   can be searched using these items (or any metadata) as selection criteria. 
   Those marked "indexed" can be searched very fast, others more slowly.

   \bMetadata section and name        Usage                         Source  Indexed
    IPTC  Keywords                  tags (keywords)                user      yes
    IPTC  Rating                    0-5 stars                      user      yes
    IPTC  Title                     image title                    user      yes
    IPTC  Description               image description              user      yes
    IPTC  Creator                   photographer, author           user      no
    EXIF  ImageSize                 pixels, e.g. 12345x6789        auto      yes
    EXIF  DateTimeOriginal          date/time photo was made       camera    yes
    EXIF  ImageHistory              history of edits by Fotoxx     Fotoxx    no
    EXIF  FocalLengthIn35mmFormat*  focal length, 35mm equivalent  camera    no
    EXIF  City, Country             city/location and country      camera*   yes
    EXIF  GPSLatitude/Longitude     earth coordinates              camera*   yes
    EXIF  RollAngle                 camera tilt angle              camera    no

   (*) camera - camera GPS, or added by user
   (*) FocalLengthIn35mmFormat - 'FocalLength' in some cameras

FOTOXX SOURCE CODE
   The C++ source code is in the source package at \_https://kornelix.net. 
   The 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: 
      mkornelix@gmail.com.

FOTOXX FOR WINDOWS 11
   The starting point is Windows with WSL2 and some Linux flavor installed 
   (e.g. Ubuntu). This is done entirely within Windows. Instructions for 
   installing Fotoxx can be found here: 
      \_https://kornelix.net/fotoxx_topics/win11/install.html.

   Fotoxx on Windows 11 is usable with limitations. Performance is very slow for 
   startup, indexing, gallery display, and image search. Image edit functions, 
   which are CPU bound, run about as fast as on native Linux. The poor file 
   performance comes from the Windows NTFS file system (or its interface to the 
   Linux VM). If you use the Linux file system included in WSL2, the performance 
   will be fine, and these files are also usable in Windows. This makes Fotoxx on 
   Windows a reasonable proposition for those with some courage and technical 
   knowledge. The downside is having to move your image library to the Linux 
   file system (and Windows access is not impared). 

ACKNOWLEDGEMENTS
   Some methods were adapted from "Introduction to Image Processing and Analysis" 
   by Russ and Russ. Other libraries and utilities used by Fotoxx include libgtk, 
   libjpeg, libtiff, libpng, libchamplain, liblcms, dcraw, exiftool, and many 
   others available in Gnu/Linux. Development was started in 2008. Many users 
   have contributed ideas and help with testing and debugging. As of 2023 Fotoxx
   has about 110K lines of C/C++ code. The primary author is Michael Cornelison.


ALL TOPICS INDEX

\>ACKNOWLEDGEMENTS\>
\>ADD NOISE\> - add random noise to an image
\>ADD SUBFOLDER\> - add new subfolder to existing image folder
\>ADJUST HSL\> - select and change colors using HSL colors
\>ADJUST RGB\> - adjust image colors using RGB or CMY colors
\>ALBUM MASS UPDATE\> utilities for mass update of multiple album files
\>ALIEN COLORS\> - add random strange colors to an image
\>ALIGNMENT ALGORITHM\> - how images are aligned (panorame, HDR, etc.)
\>ALL TOPICS INDEX\> alphabetical index of all topics in this document
\>ALPHA CHANNELS\> - how alpha channels are handled
\>ANTI-ALIAS\> - suppress pixelation (jaggies) along image feature edges
\>AREA BLEND\> - mouse-blend edits made within a selected area
\>AREA OVERVIEW\> - select area - concepts and usage
\>AREA RESCALE\> - rescale an image down, leaving selected area at full scale
\>AUTOSEARCH\> - script files can use the Search function to screen files
\>BATCH CHANGE META\> - add or revise metadata for selected or image files
\>BATCH CONVERT\> - copy, move, rescale, rename, convert, add text ...
\>BATCH COPY/MOVE\> - copy/move selected imge files to a new folder
\>BATCH DELETE/TRASH\> - delete or trash selected image files
\>BATCH GEOTAGS\> - add or revise geotags for selected or all image files
\>BATCH MENU\>
\>BATCH MOVE META\> - move metadata between keywords - fix irregular usage
\>BATCH OVERLAY\> - add overlay image (copyright ...) to selected host images
\>BATCH PHOTO DATE\> - change photo dates or times, or shift time zone
\>BATCH PROCESSING\> - overview of batch processing functions
\>BATCH RAW\> - convert RAW files to JPEG/PNG/TIFF, 8 or 16 bit color
\>BATCH RENAME TAGS\> - rename tags for selected or all image files
\>BATCH REPORT META\> - report metadata for selected or all image files
\>BATCH SCRIPT\> - execute script on all selected image files
\>BATCH TAGS\> - add or remove tags for selected image files
\>BATCH UPRIGHT\> - scan for rotated image files and upright them
\>BLANK IMAGE\> - create a new blank image file with specified size and color
\>BLUR\> - blur an image or image area, multiple methods
\>BOOKMARKS\> - add bookmarks, view list of bookmarks, go to bookmark
\>BRITE RAMP\> - add a brightness/color ramp across an image
\>CALIBRATE PRINTER\> - calibrate printer color - compensate for color shifts
\>CAPTIONS\> - show file name, title, description in top left image corner
\>CARTOON\> - convert an image to a cartoon-like drawing
\>CHANGE ALPHA\> - add or remove alpha channel for an image file
\>CHOOSE MAP\> - choose from available maps (USA, France, NYC, etc.)
\>CHROMATIC 1\> - fix chromatic aberration (color fringes in periphery)
\>CHROMATIC 2\> - fix chromatic aberration (color bands along bright edges)
\>CLEAR AREA\> - remove an area
\>COLLECTION MANAGEMENT\> - collection management and image searching
\>COLOR DEPTH\> - reduce the number of colors (posterize)
\>COLOR DEPTH ISSUES\> - meaning and limitations
\>COLOR MODE\> - convert to black & white, color, negative, positive, sepia
\>COLOR PROFILE\> - convert color profile (e.g. sRGB <--> Adobe RGB)
\>COMBINE MENU\>
\>COMMAND PARAMETERS\> - Fotoxx startup options using command line parameters
\>CONVERT ADOBE\> - convert Adobe files (.pdf/.ps/.eps/.psd) to jpeg image files
\>COPY COLORS\> - copy selected colors from current image
\>COPY FROM IMAGE\> - copy pixels from another image using the mouse
\>COPY IN IMAGE\> - copy pixels within an image using the mouse
\>COPY META\> - copy metadata from one image file to another
\>COPY/MOVE\> - copy or move an image file to another folder
\>COPY/PASTE AREA\> - copy an area and insert somewhere else later
\>COPY PRIOR EDIT\> - copy pixels from prior edits using the mouse
\>COPY TO CLIPBOARD\> - copy an image file to the clipboard
\>COPY TO DESKTOP\> - copy an image file to the desktop
\>CROP\> - crop (trim) image margins
\>CURVE EDITING\> - how to manipulate curves used in edit functions
\>CUSTOM DIALOG WIDGETS\> - how to use custom dialog widgets
\>CUSTOM KERNEL\> - edit and apply a custom convolution kernel to an image
\>CUSTOM MENU\> - custom user menu for frequently used functions
\>CYCLE 2\> - cycle through the two most recently seen image files
\>CYCLE 3\> - cycle through the three most recently seen image files
\>DARK/BRIGHT PIXELS\> - tool to highlight clipping
\>DEFOG\> - add or remove fog/haze from an image or selected area
\>DELETE META\> - delete specified metadata or all metadata
\>DELETE/TRASH\> - delete or trash an image files
\>DENOISE\> - reduce image noise (small random specks)
\>DIALOG BUTTONS\> - dialog completion options
\>DIALOG WINDOW POSITIONING\> - description
\>DITHER\> - different ways to pixelize or posterize an image
\>DOWNLOAD MAPS\> - download geographic map files for use with Fotoxx
\>DRAG AND DROP\> - file drag and drop methods
\>DRAWING\> - convert an image to a simulated line drawing
\>EDIT ANY META\> - edit any metadata (add, change)
\>EDIT DIST\> - edit brightness distribution, rebalance dark and bright areas
\>EDIT FUNCTIONS\>
\>EDIT MENU\>
\>EDIT META\> - edit commonly used metadata
\>EDIT PROCEDURES\> - how to edit image files
\>EDIT SCRIPT\> - record multiple edits in a script, execute on many files
\>EDIT TEMPLATE\> - coding template for new edit functions
\>EDIT WORKFLOW\> - alternative edit methods - simple and complex
\>EFFECTS MENU\>
\>EMBOSS\> - convert an image to a simulated embossing (3D effect)
\>ENABLE/DISABLE AREA\> - enable or disable an area for editing
\>ENGRAVE\> - convert an image into black & white lines
\>ESCHER SPIRAL\> - transform an image into an endless inward spiral
\>EXPORT FILE LIST\> - make a list of selected files (e.g. for shell script)
\>EXPORT FILES\> - export selected files to a folder (e.g. for web upload)
\>FILE MAP\> - use local map files instead of internet map
\>FILE MENU\>
\>FILE SAVE\> - save an image file (replace, new version, new file name)
\>FILE VIEW\> - File View window (view single image file)
\>FIND AREA GAP\> - find gap in hand-drawn area outline
\>FIND DUPLICATES\> - find duplicate images in a gallery or entire collection
\>FIRST INDEX\> - information for when Fotoxx is started for the first time
\>FIRST STARTUP\> - information for when Fotoxx is started for the first time
\>FIX META\> - repair malformed metadata preventing metadata edits
\>FLATTEN DIST\> - flatten brightness distribution to improve details
\>FLATTEN PHOTO\> - flatten a photo of a curved surface
\>FOLDER TREE\> - show all image file folders in a tree structure
\>FOTOXX CAPABILITIES\> - summary of Fotoxx functions and tools
\>FOTOXX FOR WINDOWS 11\> - installing Fotoxx on Windows 11 WSL
\>FOTOXX HOME FOLDER\> - user data files in Fotoxx home folder
\>FOTOXX LIMITATIONS\> - size and performance limits
\>FOTOXX OVERVIEW\> - description, prerequisites, license, downloads
\>FOTOXX PACKAGES\> - package file contents
\>FOTOXX PERFORMANCE\> - methods and limitations, benchmarks
\>FOTOXX SOURCE CODE\> - how to access Fotoxx source code
\>GALLERY END\> - jump to gallery end
\>GALLERY HOME\> - jump to gallery start
\>GALLERY MENU\>
\>GALLERY SCREEN\> - select newest, oldest, matching pattern ...
\>GALLERY SORT\> - change the sort order of a gallery
\>GALLERY TO ALBUM\> - save current gallery as an album with assigned name
\>GALLERY VIEW\> - Gallery View window (view thumbnails)
\>GLOBAL RETINEX\> - rescale RGB values to remove color cast and fog/haze
\>GRADIENTS\> - increase contrast where it is weakest
\>GRID SETTINGS\> - show or remove grid lines, set line count or spacing
\>GTK TIMEOUT PROBLEM\> - description
\>HDF\> - combine images with varying focus depth for extended depth of field
\>HDR\> - combine images with varying ISO for an extended brightness range
\>HELP MENU\> - user guide, tutorial, change log, about Fotoxx, uninstall
\>HIGH QUALITY IMAGE UPSCALE\> - how to upscale 2x with best quality
\>IMAGE DETERIORATION FROM REPEATED EDITS\> - analysis
\>IMAGE DETERIORATION FROM REPEATED JPEG SAVES\> - analysis
\>IMAGE FOLDER\> - open corresponding Gallery View from current image file
\>IMAGE METADATA USAGE\> - description and limitations
\>IMAGE ARRAY\> - join many images into a compact array format
\>INDEX DATA FILES\> - index data files and contents
\>INDEX FILES\> - 1-time job to find and index all image files
\>INSIDE-OUT\> - invert the center-edge distance of each pixel
\>INSTALLATION\> - Fotoxx software installation, dependencies
\>INTERPOLATION METHOD\> - technical description
\>INVERT AREA\> - invert an area (exchange outside/inside areas)
\>JPEG ARTIFACTS\> - suppress jpeg artifacts in highly compressed image files
\>JPEG COMPRESSION\> - technical description
\>KB SHORTCUTS\> - show and revise keyboard shortcuts for menu functions
\>KEYBOARD ENTER KEY\> - functions of Enter key
\>KEYBOARD ESCAPE KEY\> - functions of the Escape key
\>KEYBOARD SHORTCUTS\> - keyboard shortcuts for file/gallery/map views
\>LINE COLOR\> - set color for select area outlines
\>LOAD/SAVE AREA\> - load an area from a file or save an area to a file
\>LOCAL CONTRAST\> - add contrast adapted to brightness of each image area
\>LOCAL RETINEX\> - rescale RGB values to remove color cast and fog/haze
\>LOG FILE\> - Fotoxx log file and crash report file (zappcrash)
\>MAGNIFY IMAGE\> - turn mouse into a magnifying glass over image
\>MAKE WAVES\> - warp an image with a wave pattern
\>MANAGE ALBUMS\> - create and arrange user-defined image collections
\>MANAGE TAGS\> - manage user-defined tags
\>MAPS MENU\>
\>MAP VIEW\> - map view window (view map with location markers)
\>MARGINS\> - add margins to an imqage, using any color or transparency
\>MARKERS\> - show map markers for all images or only current gallery
\>MARKUP\> - draw on image: text, line/arrow, box, oval
\>MASHUP\> - arrange multiple images and formatted text in a custom layout
\>MATCH COLORS\> - match the colors in one image to those in another image
\>MEASURE IMAGE\> - measure pixel distances within an image
\>MENU SHORTCUTS\> - popup menus, keyboard shortcuts, custom user menu
\>MENU SUMMARY\> - outline of menu groups and contents
\>METADATA ERRORS\> - description and handling
\>METADATA MENU\>
\>META VIEW\> - Gallery View with thumbnail and basic metadata used by Fotoxx
\>MONITOR COLOR\> - tool to adjust monitor brightness and contrast
\>MOSAIC\> - convert an image into a mosaic using tiles made from all images
\>MOUSE ALTERNATE RIGHT-BUTTON\> - mouse right-button for touchpads/screens
\>MOUSE FUNCTIONS\> - mouse functions for file/gallery/map views
\>MOUSE OWNERSHIP\> - dialog-mouse control and interaction
\>MOVE FOTOXX HOME\> - move fotoxx home folder to a new location
\>NET MAP LOCS\> - define or go to named map location (position and scale)
\>NET MAP\> - use zoomable internet map
\>NEWEST FILES\> - open Gallery View of newest image files in the collection
\>NEWLINE CHARACTERS IN METADATA\> - description and handling
\>NEW SESSION\> - start new Fotoxx session in a separate window
\>NOISE MEASUREMENT\> - how is noise measured
\>OPEN IMAGE FILE\> - open an image file for view or edit
\>ORGANIZING IMAGES\> - organizing image files for effective searching
\>OTHER TOPICS\>
\>OUTBOARD PROGRAMS\> - required and optional programs used by Fotoxx
\>PAINT EDITS\> - mouse-paint an edit function locally and gradually
\>PAINT IMAGE\> - mouse-paint with a color, brush size, and opacity
\>PAINTING\> - convert an image into a simulated painting
\>PAINT TRANSP\> - paint increasing transparency using the mouse
\>PANORAMA\> - stitch together a series of images horizontally
\>PASTE COLORS\> - paste selected colors from selected image
\>PATTERN\> - add a background pattern to an image
\>PERMISSIONS\> - view and set permissions for an image file
\>PERSPECTIVE\> - straighten an object photographed from an obtuse angle
\>PLACES/DATES\> - list image locations and date groups, click for gallery
\>PLUGINS\> - start a plugin edit function, open plugin output file
\>POPUP REPORTS\> - keyboard navigation for text-based popup reports
\>POPUP TEXT\> - show popup window with texts to insert into edit widgets
\>PREVIEW MODE\> - method for higher interactive performance
\>PRINT CALIBRATED\> - print an image file using color calibration data
\>PRINT\> - print an image file
\>PRIVACY\> - privacy policy and privacy considerations
\>PROBLEM REPORTING\> - how to analyze and report problems
\>QUESTIONS, SUGGESTIONS\> - how to contact the Fotoxx author
\>QUICK INDEX\> - quick incremental index with no user interaction
\>QUIT\> - exit from Fotoxx
\>RAW IMAGE NOISE\> - noise in RAW image files
\>RECENT FILES\> - open Gallery View of most recently seen image files
\>RED EYES\> - remove red eyes from flash photos
\>REFINE MENU\>
\>REMOVE DUST\> - remove dust spots on images scanned from old photos
\>REMOVE HALO\> - remove halos left by sharpen and other edit functions
\>RENAME FOLDER\> - rename current folder (file gallery)
\>RENAME\> - rename an image file
\>REPAIR MENU\>
\>RESCALE\> - change the image pixel dimensions
\>RETOUCH\> - edit brightness, contrast, color, saturation
\>RGB DISTRIBUTION\> - show a brightness distribution graph for current image
\>RIGHT-CLICK MENUS\> - popup menu functions for File View and Gallery View
\>ROTATE\> - rotate or level an image
\>ROTATE PERFORMANCE\> - interactive rotation performance
\>RUNNING OUT OF DISK SPACE\> - disk space requirements
\>RUNNING OUT OF MEMORY\> - memory limits and performance
\>RUN SCRIPT\> - execute script on current image file (custom edit function)
\>SATURATION\> - adjust color saturation, optionally based on brightness
\>SCRIPT FILES\> - script files (macros) overview
\>SEARCH IMAGES\> - search using any metadata or folder/file names
\>SELECT AREA\> - selecting an image feature or area for separate editing
\>SELECT FILES\> - select files for input to batch, script or album
\>SELECT IMAGE FILES\> - image file selection procedure used everywhere
\>SELECT MENU\>
\>SETTINGS\> - user preferences and settings for Fotoxx operation
\>SET WALLPAPER\> - set desktop wallpaper from the current image file (Gnome)
\>SHARPEN\> - sharpen a blurred image, multiple methods
\>SHIFT COLORS\> - gradually shift RGB colors to GBR or BRG
\>SHOW CIM FILES\> - show input files for the current/latest combined image
\>SHOW/HIDE AREA\> - show or hide area outlines
\>SHOW ON MAP\> - show an image file position in Net Map View
\>SHOW RESOURCES\> - show CPU time and current memory usage
\>SHOW RGB\> - show RGB values at mouse position or for selected points
\>SKETCH\> - convert an image into a simulated sketch
\>SLIDE SHOW\> - create a slide show with animated transitions and zooms
\>SLIDES AND NEGATIVES\> - how to capture slides and film negatives
\>SMART ERASE\> - remove power lines, trash, signs, other small spoilers
\>SOFT FOCUS\> - apply classic "soft focus" effect to an image
\>SPHERE\> - curve an image into a spheroid shape
\>STACK/VERSIONS\> - combine image versions, select/paint area/version
\>STACK/NOISE\> - combine images to reduce noise by averaging
\>STACK/PAINT\> - combine images to remove transient cars, tourists, etc
\>STACK/SPLIT\> - show two images overlapped with a movable boundary line
\>STRETCH\> - add or remove barrel or pincushion distortion
\>SUPPORTED FILE TYPES\> - what image file types are supported
\>SYMBOLIC LINKS\> - how these are handled and what to avoid
\>TAGS OVERVIEW\> - image tags (keywords) used for image searching
\>TECHNICAL TOPICS\>
\>TEXTURE\> - add texture to an image or selected area
\>THUMB VIEW\> - Gallery View with large thumbnails and file names only
\>TILES1\> - convert an image into square tiles with 3D effect
\>TILES2\> - convert an image into irregular tiles matching image
\>TIMELINE\> - table of image counts by year and month, click for gallery
\>TINY PLANET\> - wrap a panorama image around a circle
\>TOOLS MENU\>
\>TOP PANEL DATA\> - details of information in the File View top panel
\>TWIST\> - twist an image around a chosen center point
\>UNBEND\> - straighten images having curved lines, esp. panoramas
\>UNDO/REDO BUTTON\> - sequential undo or redo edits to current image
\>UNWARP CLOSEUP\> - remove distortion from close-up face photo (big nose)
\>UPDATE ALBUMS\> - update album files for updated image files (new versions)
\>UPRIGHT\> - upright a rotated or mirrored image
\>USER GUIDE\> ← \bclick here\b - how to use this user guide browser
\>VIDEO FILES\> - video files, thumbnails, playing
\>VIEW 360° PANO\> - view a 360° panorama image with rotating viewpoint
\>VIEW ALL META\> - list all image metadata
\>VIEW META\> - list main image metadata
\>VIGNETTE\> - change brightness or color radially around a chosen center
\>VOODOO 1\> - automatic 1-click enhancement that may work OK
\>VOODOO 2\> - automatic 1-click enhancement that may work OK
\>WARP AFFINE\> - warp image by mouse drag - parallel lines preserved
\>WARP AREA\> - warp a selected image area by pulling with the mouse
\>WARP CURVED\> - warp entire image or area using the mouse - curvy warp
\>WARP LINEAR\> - warp image by mouse drag - straight lines preserved
\>WARP MENU\>
\>WEB UPLOAD\> - uploading image files to the internet
\>WINDOW VIEWS AND MENUS\> - top-level windows and associated menus
\>ZOOM\> - left/right click or [+-] button to zoom image or thumbnail in/out


EOF   (nothing shows beyond this line)

=================================================================================

   following are tests for audit_docfile() function
   run test as follows: $ fotoxx -m "audit user guide"

   \>DELIBERATE BAD TOPIC 1\> xxxxxx \>DELIBERATE BAD TOPIC 2\>
   +image: deliberate-badfile1.png  +image: deliberate-badfile2.jpg

=================================================================================

Following is the file generated by /fotoxx-nn.n/UG-topics
---------------------------------------------------------

UG-topics $: ./UG-topics 
source folder: /home2/mico/programs/fotoxx-23.74/*.cc 
file: /home2/mico/programs/fotoxx-23.74/f.refine.cc 
   topic: \>VOODOO 1\> 
   topic: \>VOODOO 2\> 
   topic: \>EDIT DIST\> 
   topic: \>FLATTEN DIST\> 
   topic: \>LOCAL CONTRAST\> 
   topic: \>GRADIENTS\> 
   topic: \>GLOBAL RETINEX\> 
   topic: \>LOCAL RETINEX\> 
   topic: \>SATURATION\> 
   topic: \>SOFT FOCUS\> 
   topic: \>MATCH COLORS\> 
   topic: \>BRITE RAMP\> 
   topic: \>VIGNETTE\> 
file: /home2/mico/programs/fotoxx-23.74/UG-topics/UG-topics.cc 
file: /home2/mico/programs/fotoxx-23.74/f.edit.cc 
   topic: \>PAINT EDITS\> 
   topic: \>ROTATE\> 
   topic: \>UPRIGHT\> 
   topic: \>CROP\> 
   topic: \>RETOUCH\> 
   topic: \>RESCALE\> 
   topic: \>MARGINS\> 
   topic: \>MARKUP\> 
   topic: \>COLOR MODE\> 
   topic: \>PAINT IMAGE\> 
   topic: \>PAINT TRANSP\> 
   topic: \>COPY IN IMAGE\> 
   topic: \>COPY FROM IMAGE\> 
   topic: \>COPY FROM IMAGE\> 
   topic: \>COPY PRIOR EDIT\> 
   topic: \>PLUGINS\> 
   topic: \>PLUGINS\> 
   topic: \>PLUGINS\> 
   topic: \>EDIT TEMPLATE\> 
file: /home2/mico/programs/fotoxx-23.74/f.widgets.cc 
   topic: \>CUSTOM MENU\> 
file: /home2/mico/programs/fotoxx-23.74/f.batch.cc 
   topic: \>BATCH CONVERT\> 
   topic: \>BATCH COPY/MOVE\> 
   topic: \>BATCH UPRIGHT\> 
   topic: \>BATCH DELETE/TRASH\> 
   topic: \>BATCH RAW\> 
   topic: \>BATCH OVERLAY\> 
   topic: \>EXPORT FILE LIST\> 
   topic: \>EXPORT FILES\> 
   topic: \>SCRIPT FILES\> 
   topic: \>SCRIPT FILES\> 
   topic: \>SCRIPT FILES\> 
   topic: \>SCRIPT FILES\> 
file: /home2/mico/programs/fotoxx-23.74/f.file.cc 
   topic: \>NEW SESSION\> 
   topic: \>OPEN IMAGE FILE\> 
   topic: \>CYCLE 2\> 
   topic: \>CYCLE 3\> 
   topic: \>VIEW 360° PANO\> 
   topic: \>RENAME\> 
   topic: \>PERMISSIONS\> 
   topic: \>CHANGE ALPHA\> 
   topic: \>ZOOM\> 
   topic: \>BLANK IMAGE\> 
   topic: \>COPY/MOVE\> 
   topic: \>COPY TO DESKTOP\> 
   topic: \>COPY TO CLIPBOARD\> 
   topic: \>DELETE/TRASH\> 
   topic: \>CONVERT ADOBE\> 
   topic: \>SET WALLPAPER\> 
   topic: \>PRINT\> 
   topic: \>HELP MENU\> 
   topic: \>HELP MENU\> 
   topic: \>FILE SAVE\> 
file: /home2/mico/programs/fotoxx-23.74/fotoxx.cc 
   topic: \>OUTBOARD PROGRAMS\> 
   topic: \>FIRST INDEX\> 
   topic: \>UNDO/REDO BUTTON\> 
file: /home2/mico/programs/fotoxx-23.74/f.warp.cc 
   topic: \>UNBEND\> 
   topic: \>PERSPECTIVE\> 
   topic: \>WARP AREA\> 
   topic: \>WARP CURVED\> 
   topic: \>WARP LINEAR\> 
   topic: \>WARP AFFINE\> 
   topic: \>AREA RESCALE\> 
   topic: \>UNWARP CLOSEUP\> 
   topic: \>MAKE WAVES\> 
   topic: \>TWIST\> 
   topic: \>SPHERE\> 
   topic: \>STRETCH\> 
   topic: \>INSIDE-OUT\> 
   topic: \>TINY PLANET\> 
   topic: \>ESCHER SPIRAL\> 
   topic: \>FLATTEN PHOTO\> 
file: /home2/mico/programs/fotoxx-23.74/f.meta.cc 
   topic: \>VIEW META\> 
   topic: \>VIEW META\> 
   topic: \>EDIT META\> 
   topic: \>EDIT ANY META\> 
   topic: \>DELETE META\> 
   topic: \>COPY META\> 
   topic: \>FIX META\> 
   topic: \>MANAGE TAGS\> 
   topic: \>CAPTIONS\> 
   topic: \>CAPTIONS\> 
   topic: \>BATCH TAGS\> 
   topic: \>BATCH RENAME TAGS\> 
   topic: \>BATCH PHOTO DATE\> 
   topic: \>BATCH CHANGE META\> 
   topic: \>BATCH REPORT META\> 
   topic: \>BATCH MOVE META\> 
   topic: \>BATCH GEOTAGS\> 
   topic: \>PLACES/DATES\> 
   topic: \>TIMELINE\> 
   topic: \>SEARCH IMAGES\> 
   topic: \>MARKERS\> 
   topic: \>DOWNLOAD MAPS\> 
   topic: \>FILE MAP\> 
   topic: \>CHOOSE MAP\> 
   topic: \>NET MAP\> 
   topic: \>SHOW ON MAP\> 
   topic: \>NET MAP LOCS\> 
file: /home2/mico/programs/fotoxx-23.74/f.tools.cc 
   topic: \>INDEX FILES\> 
   topic: \>QUICK INDEX\> 
   topic: \>SETTINGS\> 
   topic: \>KB SHORTCUTS\> 
   topic: \>RGB DISTRIBUTION\> 
   topic: \>MAGNIFY IMAGE\> 
   topic: \>FIND DUPLICATES\> 
   topic: \>MEASURE IMAGE\> 
   topic: \>SHOW RGB\> 
   topic: \>POPUP TEXT\> 
   topic: \>CALIBRATE PRINTER\> 
   topic: \>CALIBRATE PRINTER\> 
   topic: \>PRINT CALIBRATED\> 
   topic: \>GRID SETTINGS\> 
   topic: \>GRID SETTINGS\> 
   topic: \>LINE COLOR\> 
   topic: \>DARK/BRIGHT PIXELS\> 
   topic: \>MONITOR COLOR\> 
   topic: \>SHOW RESOURCES\> 
file: /home2/mico/programs/fotoxx-23.74/f.select.cc 
   topic: \>SELECT AREA\> 
   topic: \>FIND AREA GAP\> 
   topic: \>AREA BLEND\> 
   topic: \>SHOW/HIDE AREA\> 
   topic: \>SHOW/HIDE AREA\> 
   topic: \>ENABLE/DISABLE AREA\> 
   topic: \>ENABLE/DISABLE AREA\> 
   topic: \>INVERT AREA\> 
   topic: \>CLEAR AREA\> 
   topic: \>COPY/PASTE AREA\> 
   topic: \>LOAD/SAVE AREA\> 
   topic: \>LOAD/SAVE AREA\> 
   topic: \>COPY/PASTE AREA\> 
file: /home2/mico/programs/fotoxx-23.74/f.mashup.cc 
   topic: \>MASHUP\> 
   topic: \>IMAGE ARRAY\> 
file: /home2/mico/programs/fotoxx-23.74/f.effects.cc 
   topic: \>SKETCH\> 
   topic: \>CARTOON\> 
   topic: \>DRAWING\> 
   topic: \>EMBOSS\> 
   topic: \>TILES1\> 
   topic: \>TILES2\> 
   topic: \>PAINTING\> 
   topic: \>TEXTURE\> 
   topic: \>PATTERN\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>ENGRAVE\> 
   topic: \>MOSAIC\> 
   topic: \>ADD NOISE\> 
   topic: \>COLOR DEPTH\> 
   topic: \>SHIFT COLORS\> 
   topic: \>ALIEN COLORS\> 
   topic: \>COPY COLORS\> 
   topic: \>PASTE COLORS\> 
   topic: \>CUSTOM KERNEL\> 
file: /home2/mico/programs/fotoxx-23.74/f.gallery.cc 
   topic: \>ZOOM\> 
   topic: \>ZOOM\> 
   topic: \>THUMB VIEW\> 
   topic: \>META VIEW\> 
   topic: \>RECENT FILES\> 
   topic: \>NEWEST FILES\> 
   topic: \>GALLERY SORT\> 
   topic: \>GALLERY SCREEN\> 
   topic: \>IMAGE FOLDER\> 
   topic: \>FOLDER TREE\> 
   topic: \>SELECT IMAGE FILES\> 
   topic: \>RENAME FOLDER\> 
   topic: \>ADD SUBFOLDER\> 
   topic: \>BOOKMARKS\> 
   topic: \>BOOKMARKS\> 
   topic: \>VIDEO FILES\> 
file: /home2/mico/programs/fotoxx-23.74/f.pixmap.cc 
file: /home2/mico/programs/fotoxx-23.74/f.repair.cc 
   topic: \>SHARPEN\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>DENOISE\> 
   topic: \>DEFOG\> 
   topic: \>RED EYES\> 
   topic: \>SMART ERASE\> 
   topic: \>REMOVE HALO\> 
   topic: \>JPEG ARTIFACTS\> 
   topic: \>ANTI-ALIAS\> 
   topic: \>ADJUST RGB\> 
   topic: \>ADJUST HSL\> 
   topic: \>COLOR PROFILE\> 
   topic: \>REMOVE DUST\> 
   topic: \>CHROMATIC 1\> 
   topic: \>CHROMATIC 2\> 
file: /home2/mico/programs/fotoxx-23.74/f.comb.cc 
   topic: \>HDR\> 
   topic: \>HDF\> 
   topic: \>STACK/PAINT\> 
   topic: \>STACK/NOISE\> 
   topic: \>STACK/VERSIONS\> 
   topic: \>STACK/SPLIT\> 
   topic: \>PANORAMA\> 
   topic: \>SHOW CIM FILES\> 
file: /home2/mico/programs/fotoxx-23.74/f.albums.cc 
   topic: \>MANAGE ALBUMS\> 
   topic: \>UPDATE ALBUMS\> 
   topic: \>GALLERY TO ALBUM\> 
   topic: \>ALBUM MASS UPDATE\> 
   topic: \>SLIDE SHOW\> 

