FOTOXX USER GUIDE  v.23.2
   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\>
   \>USER GUIDE\> ← \bclick here\b - how to use this user guide browser
   \>INSTALLATION\> - Fotoxx software installation, dependencies
   \>FIRST STARTUP\> - information for when Fotoxx is started for the first time
   \>INDEX FUNCTION\> - locating and indexing image files for fast searching
   \>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\> - alternate 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 for many functions
   \>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 File View image
   \>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
   \>REMOVE ALPHA\> - apply alpha to RGB values and remove alpha channel
   \>BLANK IMAGE\> - create a new blank image file with specified size and color
   \>BLANK WINDOW\> - blank or restore (toggle) the current image window
   \>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 the 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 printer 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 (2)\> - open corresponding Gallery View from current File View image
   \>FOLDER TREE\> - show all image file folders in a tree structure
   \>SELECT FILES\> - select files for an album, or input to batch or script function
   \>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 the 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 [+-] button to increase/decrease image or thumbnail size
\>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 images 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
   \>EDGE BLEND\> - mouse-blend edges of 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
   \>COPY/COMPLEX\> - select and copy area with complex edges (e.g. hair)

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

EDIT FUNCTIONS

\>EDIT MENU\>
   \>ROTATE\> - rotate or level an image
   \>CROP\> - crop (trim) image margins
   \>RETOUCH\> - edit brightness, contrast, color, saturation
   \>RESIZE\> - change the image pixel dimensions
   \>UPRIGHT\> - upright a rotated image (automatic or ±90 degrees)
   \>MIRROR\> - mirror (or flip) an image horizontally or vertically
   \>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\> - use another image edit application as a Fotoxx edit function
   \>RAW THERAPEE\> - (RAW files only) start special RAW edit program
   \>DARKTABLE\> - (RAW files only) start special RAW edit program
   \>EXTRACT MPO FILES\> - (MPO files only) extract left/right files from 3D pair

\>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 image spoilers
   \>REMOVE HALO\> - remove halos left by sharpen and other edit functions
   \>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, mainly image periphery)
   \>CHROMATIC 2\> - fix chromatic aberration (color bands along bright/dark 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)
   \>TILES\> - convert an image into simulated square tiles
   \>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
   \>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 pulling with the mouse - straight lines preserved
   \>WARP AFFINE\> - warp image by pulling with the mouse - parallel lines preserved
   \>AREA RESCALE\> - rescale an image down, leaving selected area at full scale
   \>UNWARP CLOSEUP\> - remove distortions of a close-up face photo (e.g. 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/LAYER\> - combine images, select/paint which image to show in each area
   \>STACK/SPLIT\> - show two images overlapped with a movable boundary line
   \>IMAGE DIFFS\> - subtract two images (with offsets) for artistic effect
   \>PANORAMA\> - stitch together a series of images horizontally
   \>VERT. PANORAMA\> - stitch together a series of images vertically
   \>SHOW CIM FILES\> - show the input files for the current/latest combined image
   \>MASHUP\> - arrange multiple images and formatted text in a custom layout
   \>IMAGE TABLE\> - join many images into a compact table format

\>BATCH MENU\>
   \>BATCH CONVERT\> - copy, move, resize, rename, convert, add text ...
   \>BATCH COPY/MOVE\> - copy/move selected files to a new folder
   \>BATCH UPRIGHT\> - scan for rotated images and upright them
   \>BATCH DELETE/TRASH\> - delete or trash selected images
   \>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 images
   \>BATCH RENAME TAGS\> - rename tags for selected or all images
   \>BATCH PHOTO DATE\> - change photo dates or times, or shift time zone
   \>BATCH CHANGE META\> - add or revise metadata for selected or all images
   \>BATCH REPORT META\> - report metadata for selected or all images
   \>BATCH MOVE META\> - move metadata between keywords - fix irregular usage
   \>BATCH GEOTAGS\> - add or revise geotags for selected or all images
   \>BURN DVD/BRD\> - create a DVD or BlueRay disc with selected image files
   \>EXPORT FILE LIST\> - create a list of selected files (e.g. for a shell script)
   \>EXPORT FILES\> - export selected files to a folder (e.g. for web upload)
   \>SCRIPT FILES\> - script files (macros) overview
   \>EDIT SCRIPT\> - record a series of edits in a script file, execute on many files
   \>RUN SCRIPT\> - execute script on current image file (a 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
   \>MOVE FOTOXX HOME\> - move fotoxx home folder to a new location
   \>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 the current image
   \>MAGNIFY IMAGE\> - turn mouse into a magnifying glass over image
   \>FIND DUPLICATES\> - find duplicate images in a gallery or entire image 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 characters/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, privacy policy, about Fotoxx

\>OTHER TOPICS\> -
   \>VIDEO FILES\> - show and play video clips included in image collection
   \>WEB UPLOAD\> - how to select and upload a batch of images to Flickr, etc.
   \>ORGANIZING IMAGES\> - options for image organization and efficient searching
   \>PRIVACY\> - Fotoxx privacy policy
   \>TECHNICAL NOTES\> - some technical information about Fotoxx

\>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. Image modifications are displayed instantly in
   a full-size image, allowing quick interactive optimization. Finding desired images can
   be made fast and easy, even for a collection over 100K images. 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 8+ GB RAM.
   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 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.

   \bGitLab link
   GitLab is used for general information, contributors, issues tracking, and a source
   code repository where development history is kept: \_https://gitlab.com/fotoxx.

   \bDownloads
   Fotoxx source code (tarball) is available at \_https://kornelix.net. Building from
   source is not difficult and instructions are provided. A binary package is also
   provided with instructions. This package runs OK on most recent (>2020) flavors of 
   Linux. It includes library files used during the build which may not be available on 
   newer releases of Linux. If some other library is missing, an error message is shown
   when the program is started. Find and install the missing library.

   \bPackages
   Installable packages for many popular Linux distributions can be found here:
      \_https://repology.org/metapackage/fotoxx/packages
   Some of these are quite 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 corrected 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 or may not be updated for recent 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 become 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
   • Organize and manage a very large photo/image collection.
   • 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, save with 8 or 16 bits/color.
   • Edit RAW files directly using RawTherapee, Darktable, or Fotoxx.
   • 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 edits, go back and forth to compare original and edited versions.
   • Conventional edit functions include: brightness, contrast, color, rotate,
     saturation, crop, resize, sharpen, denoise, blur, paint, fix red eyes,
     markup (text/line/arrow/box/oval), fix perspective, fix lens distortion,
     warp/unwarp, smart erase (remove spoilers), HDR, stack/layer edit,
     panorama, photo montage ...
   • Advanced edit functions to bring out details and add flair to an image:
     Local Contrast, Remove Fog/Haze, Retinex, Edit Distribution, Gradients ...
   • A large set of creative special effects and arty transforms is available:
     sketch, cartoon, drawing, emboss, soft focus, tiles, dither, painting,
     mosaic, sphere, tiny planet, Escher spiral, custom convolution kernels ...
   • Most edit functions can be 'painted' locally and gradually with 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.
   • 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 other edit apps (e.g. Gimp) as a plug-in edit function.
   • Batch tools for renaming, resizing, converting, processing RAW files,
     adding/revising/reporting metadata, and executing custom edit scripts.
   • 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 image locations and date groups, click for image gallery.
   • Show an image calendar, click on year or month for a gallery of images.
   • Click markers on a scalable internet map for gallery of images at location.
   • Also use file maps: world, continents, nations, cities, custom maps.
   • View 360 degree panorama image (Google Street View format).
   • Show video files as thumbnails (using desired frame), play video.
   • Show animated GIF files (first frame) in thumbnails, play animation.
   • Bookmarks: assign names to file locations, list names, goto name (gallery).
   • Create albums with chosen images (no duplication). Arrange by drag & drop.
   • Slide show: show album images with animated transitions and pan/zoom.
   • Print an image at any scale. Printer color calibration tool is available.
   • Custom keyboard shortcuts can be assigned to most functions.
   • Cycle wallpaper images from a Fotoxx album or any folder of image files.
   • Comprehensive user guide and popup context help via F1 key.


FOTOXX USAGE

USER GUIDE
   +image: userguide.jpg
   Open the user guild from the Fotoxx 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 dialog. Press again for the next occurrence. The keyboard 'F'
   key also opens the search dialog. Use the [Hide] button to hide the User Guide window.
   With [Hide], the User Guide window will display instantly if the User Guide is needed
   again. With [OK] or [x], the window may need a few seconds to display, especially when
   using a slow spinning disk.

   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 by clicking on links. 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.

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 binary package from the kornelix.net download page. 
        Follow the instructions on the download page to install the package.
      • Use the source code package (tarball) from the kornelix.net download page.
        Follow the instructions on the download page to build Fotoxx from source.
        This will work where no Linux package is available and the binary package
        does not work. This also has a performance advantage if you use compiler
        optimization for the target machine (-march=native).
   Download page: \_https://kornelix.net/downloads/downloads.html

   \bFotoxx outboard programs
   These are separate programs to extend the functionality of Fotoxx. Some are required
   and some are optional. The optional ones must be installed only if you want to use the
   corresponding functionality. This can be decided later. Some of these programs may be
   already installed. To install any others, use your package manager. When Fotoxx is
   started the first time, all outboard programs are listed with the functionality they
   provide. If any required programs are missing, Fotoxx exits with a message asking you
   to install them. You can also view the list using the menu Help > Outboard Programs.
      \brequired          Debian package          function
      exiftool          libimage-exiftool-perl  read and write image metadata
      dcraw             dcraw                   RAW file read, index (\>SETTINGS\>)
      addr2line         binutils                fatal error report (crash backtrace)
      \boptionial
      ffmpeg            ffmpeg                  video thumbnails, extract frame image
      dwebp             webp                    read WEBP image files (.webp)
      heif-convert      heif-examples           read Apple iPhone files (.heic)
      opj_decompress    libopenjp2-tools        read jpeg2000 image files (.jp2)
      gs command        ghostscript             Adobe doc. files (.pdf/.ps/.eps) >> .jpg
      convert command   imagemagick             Adobe image files (.psd) >> .jpg
      rawtherapee       rawtherapee             edit RAW images within Fotoxx
      rawtherapee-cli   rawtherapee             read RAW files (\>SETTINGS\>)
      darktable         darktable               edit RAW images within Fotoxx
      darktable-cli     darktable               read RAW files (\>SETTINGS\>)
      growisofs         grwoisofs               copy images to DVD or BlueRay disc
      vlc               vlc                     play videos, slide-show music

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

   Fedora notes:
     • Packages: openjpeg2-tools libheif libheif-devel (heif is non-free)
     • Fotoxx build: \_https://apps.fedoraproject.org/packages/fotoxx/sources/spec/
     • How to use non-free repository: \_https://rpmfusion.org/Configuration/

   \bWEBP files (.webp)
   If the converter 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)
   Apple iPhones can produce image files with the extension .heic as an option to .jpg.
   If the converter 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.

   \bJPEG-2000 files (.jp2)
   If the converter 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.

   \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 it to
   a mounted volume. See \>MOVE FOTOXX HOME\>.

FIRST STARTUP
   +image: outboard-programs.jpg
   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.

   +image: first-startup.jpg
   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 about
   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. Both the
   old and new Fotoxx versions can be used without interference. 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 indexes at a speed of about 6000 large JPEG images per minute.

INDEX FUNCTION
   +image: index-files1.jpg

   \bTop image Folders
   These are the topmost folders containing your image files, e.g. /home/<user>/Pictures.
   Subfolders underneath 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 simpler access to the
   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, especially if rotating discs are used.

   \bMetadata Items
   The following metadata is included in the index by default: folder and file names,
   photo date/time, file creation or modification date/time, title, description, rating
   (0-5 stars), tags (keywords for image content), geotags (country and city/location
   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 index. These will also
   be almost instantaneous to search. You may not need this. You can skip 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 function may need some
   time. The speed can range from 300 to 10K files per minute, depending on processor
   speed, disk speed, and average image file type and size:
     slow case: laptop, 1 GHz, slow disk, images >30 megapixels, RAW or PNG files
     fast case: desktop, 4 GHz, 4 cores, SSD disk, images <10 megapixels, JPG files

   Here are a few real-world index benchmarks. Files were mostly JPEG averaging 2.6 MB.

      \bCPU    GHz   cores   disk type          files/minute
      Intel  3.5    6      SSD PCIe           19364
      Intes  3.5    6      SSD USB-C          9287
      Intel  3.5    6      7200 rpm USB-C     1511
      Intel  3.5    6      5400 rpm USB-C     1207
      ARM    1.2    4      micro-SD card      870

   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 temporarily disappeared. When the removable drive is
   mounted again, and Fotoxx is started, the last status is restored. If any image 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 one or more 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 top image folders declared for Fotoxx.

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 menu (File View, Gallery View, Map View) will set the corresponding view
   mode if not already set. The keyboard keys F2/F3/F4 can also be used for this.

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-to-window and 1x (100%) image size (1 image
   pixel is 1 screen 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 (\>SETTINGS\>). The movement may be 1:1 with the
   mouse, or may be magnified for faster movement. The mouse wheel can also be used to
   zoom an image in or out. The middle mouse button (wheel) will make a zoomed image
   re-center at the mouse position. Use the menu buttons (Edit, Refine, Warp, etc.) to
   modify the image. Use the File Save button to save a modified file (replace file,
   create a new version, or create a new file).

   \bShow Previous or Next Image
   If the mouse is moved into the upper left corner of the window, left and right arrow
   icons will appear. Click on one of these to move to the previous or next image in the
   current gallery.

   \bKeyboard Navigation Options
   The keyboard arrow keys (left, right, up, down) 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 go to the previous or next gallery by pressing the key again. The UP
      key goes backwards, the DOWN key forwards (next file, next 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 (right side) to scroll up and down within the
   gallery. The keyboard keys can also be used: the up and down arrow keys scroll rows,
   the page up and 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, or show the gallery in \>META VIEW\> format with basic metadata.
   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 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 get a
   gallery for that folder. Its subfolders will be shown as folder thumbnails. Click one
   of them to get a gallery for that folder. Click the [TOP] button to choose another top
   image folder (if more than one), the root folder ( / ) your home folder, your Desktop
   folder, a gallery of the most recently viewed images, or a gallery of the 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 parent folders are shown in the top panel. The other gallery types have
   only the buttons for Album (select an album) and TOP (go to 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. Many 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 map service. The functionality is
   similar and superior to File Map, but depends on having a fast and reliable internet
   connection. Initially a world map is displayed. Use the mouse wheel (or double-click)
   to zoom-in to any location. Shift the map center using mouse drag. The entire world is
   represented and 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 will show a popup menu with all of the functions for this
   menu group. The top three icons also respond to a right-click by changing to the view
   mode appropriate for the menu. Many 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, Warp, Effects, 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 finished editing, use [Save] to save the modified image
   back to the same file, save to a new file version (e.g. filename.v01.jpg), or input a
   new file name and/or folder. Image edit dialogs have sliders, spin buttons, or editable
   curves that immediately update the image. The reaction time depends on the size of the
   image, the complexity of the function and the speed of your PC. This is typically less
   than second for most edit functions on a strong PC.

   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 go back to prior edit steps or forward to the last edit 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 then be re-edited from this step.

EDIT WORKFLOW
   You can speed the editing of multiple photos/images if you understand the following:
      • 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. 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 edge
      4. Press [crop] button, crop image margins by dragging edges
      5. Press [Save] button and choose "new version".
      6. Press [Next] button to edit the next file. Press [Next] again to skip.
      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 image quality.

   \bComplex Workflow
   To edit with deep color (more than 8 bits), you can start with RAW files from your
   camera. There are three options for processing RAW files:
      • 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 RGB 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-bit color. You cannot
        save the edited image as a RAW file type. Opening a RAW file may need several
        seconds, especially on a weak computer. Saving an edited image as TIFF or PNG
        is also slower than JPEG.
      • Use one of the popup menus 'RAW Therapee' or 'Darktable" which are available for
        RAW files in File View or Gallery View. This opens a specialized RAW file editor.
        Save the output file as a TIFF-16 file, which will pass back to Fotoxx for further
        editing if wanted.
      • 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-bit color.
        You may then select and edit these files with Fotoxx.

   RAW files may have more color depth than 8 bits, especially if the camera is new and
   expensive. Conversion into a PNG or TIFF file with 16-bit color will preserve the
   additional color depth 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 any difference between a 16-bit TIFF or PNG file and a high quality JPEG made from
   that same file. To preserve the possibility of re-editing the image later, keep the
   RAW file, which is usually much smaller than the TIFF or PNG file.

   There are three programs available for loading RAW files for viewing and editing in
   Fotoxx: Dcraw, RawTherapee, and Darktable. Dcraw is the fastest, which saves time if
   you are viewing many RAW images. RawTherapee or Darktable may sometimes provide a
   better initial image, which may not matter, since any differences are easily fixed.
   In User Settings (/>SETTINGS/>), select which program to use. These programs are
   installed separately from Fotoxx. Dcraw is always used to make RAW image thumbnails.

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 a dialog.
   Therefore it is important to understand who owns the mouse (which dialog, or main
   window) and how to change the ownership:
      • The mouse is owned by the dialog that was last clicked or used. Mouse 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. Active dialogs are not affected.
      • The mouse wheel can always be used to zoom-in/out any part of the image.

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
   (or Return 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 or control has the input 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 mouse click.

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 active, ask if it should be terminated
         • 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
      • dialog window has focus: exit the dialog (same as [x] button)
      • others: cancel popup image, exit 360 panorama viewer, hide the User Guide window,
        interrupt or exit Slide Show. Some long-running functions can be canceled with
        the escape key. Details are explained in the respective topics.

CUSTOM DIALOG WIDGETS
   +image: custom-widgets.jpg
   A few non-standard smaller widgets are used to reduce the size of dialogs (and amount
   of image area covered). 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 index 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 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.
   A few standard GTK widgets have also been downsized 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 would be automatically replaced.

CURVE EDITING
   +image: retouch.jpg
   Some image edit functions use editable curves. You can manipulate the curves to change
   some property of the image depending on some other property. The example here shows a
   brightness curve, whereby you can change brightness depending on brightness (e.g.
   brighten dark image areas without changing bright areas). Generally, the X-axis of the
   curve represents the input property (brightness in this example) and the Y-axis the
   output property (also brightness). The curves can be moved (pulled) with the mouse.
   "Up" increases the effect and "down" decreases the effect. An anchor point (black dot)
   is added to the curve wherever it is pulled, and this point remains fixed for
   subsequent pulls: the curve will continue to go through this point as other parts of
   the curve are pulled. Anchor points can also be dragged. Delete an anchor point by
   right-clicking it.

BATCH 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 using any mix of old name, new name, sequence number, photo date
      • Convert file types (e.g. .png to .jpeg)
      • Find and upright photos made with the camera turned 90 degrees
      • Resize files (e.g. reduce for web upload or e-mail)
      • Copy or move files to another location
      • Convert RAW files to tiff, png, or jpeg
      • Add/change/remove 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 image, save as a script file
        which can then be applied to any number of images in batch mode.
      • Burn selected image files to a DVD or BlueRay disc.
      • Find duplicate image files.

SELECT IMAGE FILES
   +image: gallery-select.jpg
   This procedure is used for all functions operating on multiple image files:
      • batch functions - resize, 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 the first thumbnail, shift-click the last thumbnail
      • a file may be added multiple times to the list
      • you can navigate to other galleries to select more files as needed
      • files are added initially at the end of the list
      • click a list position: thumbnail is shown and a new list position is set
      • new files are added after the current (last clicked) list position
      • delete a file from the list, 2 methods:
         • right-click the file's gallery thumbnail
         • click a list position and press [delete] button
      • move one or more files to a new position:
         • click each list position and press [remove] - the files are saved internally
         • click the new position and press [insert] - the next saved file is inserted
           (repeat to insert each saved file at a new position)
      • add all images in the gallery to the list: press [add all] button
      • clear the list: press [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

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
   the images you want. Some effort to organize the images is required. Search methods
   include folder and file names (or partial names), image (photo) dates, file dates,
   image ratings, tags (keywords: labels for persons, places, objects, events ...),
   words in title and description, and geotags (location names and latitude/longitude).
   This is done in a standards-compliant manner so that this data can be shared with other
   image processing applications. Options for how to organize a large image collection can
   be found in 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
      • Resize - Resize (rescale) the image pixel width and height
      • Upright - Auto upright a rotated image based on EXIF orientation data
      • 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 Dist - Flatten distribution to 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
      • Upright - Auto upright a rotated image based on EXIF data

   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

   RAW files have the following menu additions:
      • Raw Therapee - edit using this specialized RAW image editor
      • Darktable - edit using this specialized RAW image editor

   MPO files have the following menu addition:
      • Extract MPO files - for .MPO 3D files: extract left and right images

   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 all shortcuts and make custom additions.
   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: scroll 1 row up/down, hold down for slow scroll
                       Report: scroll report up/down one row at a time
      • Page Up/Down   Gallery: scroll 1 page up/down, hold down for fast scroll
                       Report: scroll report up/down one page at a time
      • Home/End       Gallery: go to first/last page in gallery
                       Report: go to report start/end

NUMERIC KEYPAD
   +image: number-keys.jpg
   The numeric keypad can be used for navigation with or without 'num-lock' engaged.
   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 on image - Pan/scroll zoomed image, same direction or
                             magnified opposite direction (like scroll bars)
      • 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 with 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 from 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 command line parameters can be used to override the setting in \>SETTINGS\>.
      -x0   no index - very fast startup with reduced functionality
      -x1   use existing index only - fast startup omitting new and revised image files
      -x2   use existing index + search for and integrate new and revised image files

   Note: the first Fotoxx startup after a reboot may be slow if your image collection is
   very large. Subsequent startups will be much 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 to 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, settings and data 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 also \>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 through 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 (if the 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 new 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:
      CPU: 34%          current CPU load (max. for 4 processor cores is 400%)
      2866x1917x8       current image width x height x depth (bits per color)
      0.87MB            image file size (updated when a modified image is saved)
      41%               zoom status, image % size (window pixels / image pixels)
      edits: 2          current image 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
      BUSY 45%          some long-running functions show this progress indicator


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 navigator 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 keyboard shortcut key [2] is assigned by default.

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, but the wrap-around will show a
   false joining of the two ends.

RENAME
   +image: rename.jpg
   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.jpg
   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.

REMOVE ALPHA
   +image: remove-alpha.jpg
   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 edit transaction and no new version - the current file is
   updated on disk. If you want to keep the original file with an alpha channel, save a
   new version and remove the alpha channel for the new version. The opacity values in the
   alpha channel are applied to the RGB values before the alpha channel is removed. The
   RGB values are multiplied by the alpha value / 256. Completely transparent areas are
   made black (RGB 0), and partly transparent areas will become darker.

BLANK IMAGE
   +image: blank-image.jpg
   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 the \>MASHUP\> function.

BLANK WINDOW
   Blank the File View window. If already blanked, restore the current image file. Assign
   a keyboard shortcut to have a "one button" blank and restore function (boss button).

COPY/MOVE
   +image: copy-move.jpg
   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].

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.jpg
   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 uses the Linux
   desktop 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 updates itself. In Gallery View, if another thumbnail is
   clicked, the dialog updates itself.

CONVERT ADOBE
   +image: convert-adobe.jpg
   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. The output file pixel size depends on the 'paper size' of
   the document file (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 likely does not work for other windowing 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.jpg  +image: print-margins.jpg
   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 an image scale. The margins can be used to shrink the
   image or shift it on the page. Image scale can be set in the range 5-100%, where 100%
   means print the maximum size image that fits within the margins. Smaller values will
   shrink the image proportionally. The actual print size (image width and height) is
   updated in the dialog as margins and scale are changed, and this can be used to reach
   a desired printed image size. After the margins dialog, a Print dialog starts for the
   actual printing. This includes paper type and 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 function is used to exit Fotoxx. A popup dialog will ask for confirmation, if this
   option has been selected in \>SETTINGS\>. To exit Fotoxx, pres 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.jpg
   A gallery of thumbnail images can represent a file folder, the output of an image
   search function, one of the built-in galleries (recent files, newest files), or an
   album (an ordered list of image files with a given name). Folders in Fotoxx 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 a height of 7 million pixels
   (internal GTK limit). If 'normal' thumbnails are used (256x256) and if there are six
   thumbnails per row, about 140K files can fit in the scrolling window.

   \bScrolling the Gallery
   The gallery can be scrolled up and down using the keyboard up and down arrow keys or
   the 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 the newest images. If the EXIF
   date is chosen, image files having 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.jpg
   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 "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\> function, 'metadata report'
   option, and if you added optional metadata items to the standard report, you can sort
   the gallery by these metadata items. For example, you can sort the gallery by camera
   make, lens info, ISO level, exposure time ... any available metadata.

GALLERY SCREEN
   +image: gallery-screen.jpg
   Select a simple subset of the current gallery and create an album "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 (original when 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 oldest existing versions
   (when original is 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 the 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 (2)
   This is a duplicate of the \>IMAGE FOLDER\> function in File View.

FOLDER TREE
   +image: folder-tree.jpg
   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.jpg
   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.jpg
   Add a new subfolder to an existing image folder. Navigate to the desired 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.jpg
   View existing bookmarks. Bookmarks are chosen file 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.jpg
   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.jpg
   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
   the order of the images. 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.

   To edit an album, right-click on 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 side to add before, or right side to add after.
      • Add current file here - the current file (File View) is added at this position.
      • Remove from album - the clicked image file is removed from the album.
   To add files to an empty album:
      • Gallery View > Album button -> select the empty album (a blank window shows).
      • Manage Albums > Select Files: select initial files for the album. When you exit
        Select Files with the [done] button, the selected files are added to the album.

   \bDrag and Drop
   You can rearrange images within an album by dragging thumbnails with the mouse. Drag
   the thumbnail until the mouse cursor changes to a small 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 also be an album
   or any other 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, don't just 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 all albums containing them.

   \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.jpg
   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 the 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.jpg
   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 present.
        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 existing versions.
      • Replace all with original version and newest version
        All album files are replaced with the original file and the 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 present.
        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 the 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 considered 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. This allows you to select images from anywhere in your collection
   and order them as desired. 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 the image with 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, leaving black margins for difference in
        aspect ratio. Images with difference < clip limit are clipped to have no margins.
      • 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 a random sequence - otherwise in album sequence.

   Keyboard keys can be used to control the slide show. Press the button [KB controls]
   to show the current assignments or to change them (Keyboard Preferences, bottom right).
   The following actions can be assigned:
      • Blank the current image and pause the slide show, or restore the image (toggle).
        Default 'B'.
      • Show the next image, including the 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: If a transition or zoom is in-progress, jump immediately to final status.
      • Escape: Otherwise, 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 the space bar (blank)
   can also be used. Do this by replacing the key name in the dialog with another key.

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

NET MAP
   The Net Map functions use an internet service to provide maps from any location at any
   scale. The Net Map offers superior functionality, but depend on having a fast reliable
   internet connection. Markers (red dots) will show the locations for your images having
   geotags. Use the mouse wheel or left-clicks to zoom-in on any location. Drag the map to
   change the center. Click on a 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 the images of the contained markers. Left-click with
   the shift key held down to see the geocoordinates of the clicked location.

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

NET MAP LOCS
   +image: netmap-locs.jpg
   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 the map to a
   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 included 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-in. The download is currently < 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.

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 are from the optional package fotoxx-maps.

   File Map Navigation
      • left click: zoom map to full size, right click: reduce size to fit window
      • mouse wheel: zoom-in or zoom-out. zoom-in allows greater image 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 available maps. An initial set of world and continental
   maps can be installed with the package fotoxx-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. These work well with Fotoxx pan and zoom. 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 file 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:
       Houston.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 will be 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 both 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 functions to include are listed in a text file: [fotoxx-home]/custom_menu.
   Edit this file to define the functions you want. The names must exactly match the names
   in the Fotoxx menus, but case is not significant.


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\>, this button does nothing.


FILE SAVE

   +image: ug-file-save.jpg
   +image: ug-file-save-as.jpg

   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 (this can be set in \>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 generally hard to distinguish from 100 (highest quality, largest file size). PNG
   files are compressed without any loss of quality and are larger than JPEG files of the
   highest quality. TIFF files are 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 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 (i.e. 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 NOTES\> 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 relatively strong 4 GHz 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-meta.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 inside 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 to the image.

   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 the following 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 date/time
      Rating                  Edit Meta - rating - 0 to 5 stars
      Geotags                 Edit Meta - location - may come from the camera GPS
      Tags                    Edit Meta - image tags (identifiers added by a 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 largely 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 names 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 the 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', 'scenery', 'scenrey')
     • 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 the tag in the long list (possibly in a scrolled window). This problem
   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 needing tag deletion or renaming.

   \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
   a limited 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
   "lan" and a list of existing matching tags is shown: 'landscape', 'landscapes',
   'Langley' ...  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 all 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 best to deal with
   this is discussed below.

EDIT META
   +image: edit-metadata.jpg
   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 if you
   want a new version, use File Save > New Version.

   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 used
   as a low limit for searching, or 12/31 when used as 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 the 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. Tags recently added 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
   newly associated geocoordinate.

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

   Summary
      • Enter (or change) a location name (possibly abbreviated) in the dialog.
      • Use [Find] to find the 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 and try again.
      • 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 location available for future use.
      • 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 for this location.

EDIT ANY META
   +image: edit-any-metadata.jpg
   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 between the words, 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 if you wish.

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 might be present. Some keys are
   not deletable, e.g. File Name.

COPY META
   Combined images created with Fotoxx (HDR, panorama, mashup ...) will not contain any
   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.jpg
   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, and 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.jpg
   \_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 in the Search Images function (see below).
   First, use the Search Images function to set up the 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> is the name you assigned to your search criteria. The output is
   the file /fotoxx-home/search_results, where /fotoxx-home/ is the location for Fotoxx
   data files (default: /home/<user>/.fotoxx/). The settings file is an ordinary text
   file which can be edited or created/modified using a shell script. You can use shell
   text manipulation utilities to modify fields in this file.

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 (the entire image database) or
   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 or downloaded 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 with parent
   folders. 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 key values - no matching is done
      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. Resize)
   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 are accumulated. An outline of the
   selected image area(s) is shown as you add or remove areas from the selection. The
   [Finish] button is used to make the area ready for subsequent image edits within the
   area. The [Hide] button 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 an existing area or start a new one.

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

   \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
      • Draw/Replace - adjust a previous outline by drawing over to shift its position
      • Select area in mouse - select pixels within a circle centered at mouse pointer
      • Select one color in mouse - select pixels within mouse, but only colors matching
                                    a given color within a given match level
      • Select all colors in mouse - select pixels within mouse, and spread the selection
                                     into adjacent areas with colors matching mouse colors
                                     (this is called 'flood' in some image editors)
      • Select and deselect parallel - select pixels better matching a given color and
                                       deselect pixels better matching a 2nd color
                                       (forground/background colors for a complex edge)

   The following paragraphs explain the details of each method.

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

   \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 (curvy) line, or left-click to
   connect a straight line from the last point drawn to the point clicked. Continue
   around the target area until it is surrounded with connected curves and lines. Right
   click to remove previous lines (mistakes). A right click will remove the previous
   clicked or dragged line, up to 50 pixels. Right click repeatedly to remove more.
   A new clicked line will always connect to the end of the previous line. A new dragged
   line will connect to the previous line if it is started close to the end of that line.
   If it is started elsewhere, a disconnected line will be drawn. You can start a new
   drag from far away and draw back to meet the previous line. If a clicked line connects
   to an undesired point (i.e. you don't want to connect to the last line drawn), right
   click to erase it and then use drag to start a new sequence of lines. A right-button
   drag can be used to erase 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 slightly behind the mouse position.
   For very irregular edges (hair, foliage), see Select/Deselect below.

   \bDraw/Replace
   Drag the mouse near and along an existing area edge-line. The line will be erased and
   redrawn at the mouse pointer. This is a fast way to make a small adjustment to an
   existing line.

   \bMouse Radius and Match Level
   These two controls apply only to the 'select in 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 in 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 in 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/up to match a greater/lesser range of colors. Click repeatedly
   on the image to change the color to be matched.

   \bSelect all colors in 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 change to the select area in mouse method 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 in mouse - summary
      • left drag      select pixels inside mouse circle and those with
                       matching colors within search range
      • right click    undo previous selection, repeat to unselect more
      • right drag     unselect pixels inside mouse circle and those with
                       matching colors within search range

   \bBlend Width
   Edits made within an area can be blended with the unmodified image over a distance
   called 'blend width'. The 'strength' of the edit function will ramp from zero at the
   edge of the selected area to 100% at a distance of 'blend width' from the area edge.
   Use the Blend Width control to set the blend width for the current or subsequent edit
   functions. Zero blend width gives a hard edge to the area edit. Increasing blend width
   makes the edges of the edit more gradual and harder to distinguish from the original
   image. Changing the blend width value for the first time after editing an area will
   cause the edge distance to be calculated for each pixel in the area. This is normally
   fast (a few seconds), but it may take minutes if the area is large and has a complex
   geometry (i.e. a very long edge). Whenever an area is re-edited or inverted, the edge
   calculation is discarded and must be repeated if blending is wanted. If the edge of a
   selected area runs along an image edge, it is not considered an edge for blending.
   A long edge calculation can be canceled with the Escape key.

   \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, but blend width is no
   longer valid and is discarded.

   \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.jpg
   An area is not effective for edits until it is successfully finished. Finish validates
   drawn outlines and colors the enclosed pixels for visual verification. 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 one of the 'select in 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, use this function to 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).

EDGE BLEND
   +image: edge-blend.jpg +image: edge-blend2.jpg
   Edits made within a selected area will often have unnatural edges at the seam between
   edited and unedited areas. One way to blend these transitions is to use the blend width
   tool in \>SELECT AREA\>, which blends all edges equally. This may not be desired, e.g.
   you may want to retain the edits in some parts of the area edge and gradually blend
   them in other parts. You can do this manually using the mouse. After the area-confined
   edit is completed, start the Edge Blend edit function. The previous edit is selected by
   default as the source for blending, but you can use the 'prior edit step' dropdown list
   to select any prior edit step that has matching image dimensions. Set 'mouse radius'
   to roughly match the desired width of blending. Left-drag the mouse along the area edge
   and watch the hard boundary blend in. The 'blend rate' input controls the speed. A low
   value will work slowly and require many mouse drags to make the boundary fade. A high
   value will work fast but with less control. Right-drag the mouse over a blended area to
   gradually restore the original edit (and the edge).

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 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 resize, rotate, and
   change the brightness of the pasted area. The edge blend control allows you to blend
   the area edges into the background image if wanted.

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 resize, rotate, and change the brightness of the pasted area. The edge blend
   control allows you to blend the area edges into the background image if wanted.

COPY/COMPLEX
   +image: copy-complex.jpg
   This is an area select and copy function for complex boundary cases like hair or trees,
   where selection by color may not work well, and manual selection would be very tedious.
   The objective is to deselect background pixels, making them transparent, while keeping
   foreground pixels opaque. The resulting "cutout" can be copied and pasted where needed,
   without the background. This function is not easy, but practice can make it effective.

   Follow these steps:
      • Use Select Area to select the entire area, including the complex edge and its
        background areas, but no more than needed. [finish] the area.
      • Start this function, Copy/Complex.
      • Set a transparency color that contrasts with the area to be deselected.
        In the example above, black contrasts the blond hair.
      • Set a suitable mouse radius for painting over the edge boundary areas.
      • Left-click on a background area to choose colors to be deselected. These are
        shown in the "deselected colors" widget. The colors to deselect can be changed
        at any time by left click on the image.
      • Left drag over the boundary to deselect background pixels. Deselected pixels
        become transparent and the chosen background color will show through.
      • Right drag to restore the original pixels, to correct errors.
      • If the background color changes as you drag the mouse, deselection will cease,
        because the color no longer matches. Click again on the new color to match, and
        deselection will continue with the next mouse drag. Proceed around the complex
        edge with click and drag, click and drag ... until all background is deselected.
      • The deselect slider determine the delection sensitivity. Move right for a more
        narrow match to the colors shown in the box, move left to select similar colors
        more widely. If the foreground and background colors are close, you will need to
        use narrow color matching to separate them.
      • Pixels not deselected (the fine hairs in the example) may be partly colored with
        the background color, because of the finite pixel size and edge effects. This can
        be countered by using the optional 'retouch color' to shift the color of these
        pixels in a desired direction. Set the retouch color with shift+left-click on the
        image. This can be repeated as needed. Check the 'activate' button to enable the
        color shifting, or uncheck to disable this.
      • When done, save the completed area with the [Copy] or [Save] button.
      • To paste the area into another position or another image, use Select > Paste or
        Select > Load (see \>COPY/PASTE AREA\> and \>LOAD/SAVE AREA\>).

   When the area is pasted into the target image, the paste dialog can be used to further
   blend the edges if needed. The pasted area remains active and can be edited.


UNDO/REDO BUTTON

+image: ug-undo.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 (see original and 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.jpg
   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. Use the 90º buttons to upright an image made with the
   camera turned. The 'Rotate Degrees' control can be used to set any angle. When dragging
   the image with the mouse, a faster but less precise rotate method is used to keep good
   responsiveness. When there is no more mouse movement, a precise and slower method is
   used and replaces the last rotation step.

   A left-click on the image will add vertical and horizontal guide lines to help with
   image leveling. Use right-click to remove them.

   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 rotated 90 degrees, if the camera recorded 'orientation' in the EXIF metadata.

   If the rotation is exactly 90 degrees, no resolution is lost. For other angles, loss
   of resolution is under 1/2 pixel.

CROP
   +image: crop.jpg  +image: crop-buttons.jpg
   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.jpg
   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 in the image
      • click dark spot for black level - press button, click dark spot in the image
      • click for RGB distribution - press button for popup window with RGB distribution
      • brightness - moves the entire 'all' curve up or down (all RGB colors change)
      • contrast - moves the 'all' curve lower and upper parts in opposite directions
      • color saturation - change saturation (black & white <--> intense colors)
      • color temperature - change RGB balance to match illumination (warm <--> cool)
      • settings file - load or save dialog settings for use with another image file

   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.

RESIZE
   +image: resize.jpg
   This function resizes 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. The image file size in the top panel is not updated until the modified
   image is saved. 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 resized to
   2x needs 1.6 GB memory, in addition to the 0.8 GB for the original image.

UPRIGHT
   The popup menus for File View and Gallery View include this function for uprighting an
   image that is turned 90 degrees. If the camera was rotated 90 degrees (roughly) when
   the photo was made, the image EXIF data will indicate 90 degree rotation clockwise or
   counterclockwise. Fotoxx uses this data to upright the image file. The EXIF data is
   erased to prevent another rotation. If there is no EXIF rotation data, a popup dialog
   is shown with buttons for [-90°] [+90°] and [180°].

MIRROR
   +image: mirror2.jpg  +image: mirror1.jpg
   Choose either horizontal or vertical mirror from the dialog. The image is reversed
   (mirrored) vertically or horizontally. Repeating the mirror restores the original
   image. Doing both a horizontal and vertical mirror is the same as 180 degree rotation.

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 version 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 faint but readable. Use the emboss controls to make the
   text appear to be embossed into the image.

   +image: draw-line.jpg
   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.jpg
   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.jpg
   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.jpg  +image: color-mode2.jpg
   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 colors
      • RGB -> BRG - red/green/blue colors are replaced with blue/red/green colors
      • 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% (no change) 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 (analogous to 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.jpg
   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: Retouch, Gradients,
   Flatten Dist, Local Contrast, Sharpen (most methods), Denoise, Adjust RGB, Adjust HSL,
   Saturation, Color Depth.

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

PAINT TRANSP
   +image: paint-transp.jpg  +image: paint-transp2.jpg
   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.jpg

   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.jpg  +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.jpg
   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. Select Area can blend the edges of the area
   to make the transition invisible, but this is sometimes not adequate. You may want a
   hard edge where there is a hard image feature edge, and a blended edge elsewhere.
   Select Area cannot do this. To fix the problem, you can omit edge blending in Select
   Area, and then use this function to add blended edges where wanted.

PLUGINS
   +image: plugins.jpg  +image: edit-plugins.jpg
   An example Plugins menu is on the left. The top entry "Edit Plugins" starts the text
   edit application on the right. Use the editor to define menu names and the associated
   commands to start other image edit programs from Fotoxx. This file is the basis for the
   Plugins menu. The top example shown is a menu named "Gimp" which starts the command
   "gimp %s". The "%s" is a placeholder where Fotoxx will insert the name of a copy of the
   current image file in Fotoxx. The called edit program must process the file and replace
   it with the edited version. Normally this is done by using the programś "File > Save"
   menu. Afterwards, you can use the Fotoxx [Undo] and [Redo] buttons to check results,
   perform additional edits with Fotoxx, or use [Save] to save the edited image. The image
   passed by Fotoxx to the external program is a TIFF file with 16 bits per color. Most
   programs can read this file but may use only 8 bits. When finished using the external
   program, save the image back to itself using the File > Save menu, and then exit the
   program. Fotoxx will pick up the revised file and use it like any edit done in Fotoxx.
   Note that in Gimp you must use the "File > Export" menu to replace the original input
   file ("File > Save" produces a .xcf file).

   To add a new plugin, add a text line formatted "menuname = command %s". The file to
   edit is inserted at '%s' in the command line. Some commands may expect both input and
   output files to be specified. In this case supply '%s' in both positions (output file
   replaces the input file). You may omit '%s' if the command does not edit an image file.

RAW THERAPEE
DARKTABLE
   These functions are available in the popup menu when a RAW file type is right-clicked.
   These programs are specialized for editing RAW image files. Fotoxx starts the selected
   editor with the RAW file loaded. When you are finished editing, 'export' the output
   file with type .jpg or .png or .tif, with 8 or 16 bits per color, then exit. Fotoxx
   resumes and opens the output file, if one is found. Fotoxx finds the output file by
   searching for an image file (.jpg etc.) with a file creation date/time AFTER the time
   the special editor was started. This is valid as long as no other processes are
   creating files in the interim. Fotoxx assumes that the output file is saved somewhere
   within your declared top image folders. There is no need for the file name to match
   the RAW file name.

EXTRACT MPO FILES
   This function is available in the popup menu when an .MPO file is right-clicked, in
   either F-view or G-view. An .MPO file is a 3D image comprising left and right image
   files. The two image files are extracted and saved, using file names <filename>.L.jpg
   and <filename>.R.jpg, where <filename> is from the input .MPO file.


REPAIR MENU

+image: ug-repair.png

SHARPEN
   +image: sharpen.jpg

   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 variance in brightness. This forces pixels on a blurry edge to move to one
   side of the edge or the other. Edges are made very sharp. 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.jpg  +image: fix-motion-blur1.jpg  +image: fix-motion-blur2.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.

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

   \bPaint Blur
   Blend image pixels together by painting with the mouse. Radius sets a circle
   around the mouse pointer which shows the image area being blended. Use left drag
   to blend, right drag to restore. Power determines how fast the image is blended
   or restored, at the center and edges of the circle.

   \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 the 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.jpg
   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) is often 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.

   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 should be adequate for most 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 pixels. 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 the
   \>TECHNICAL NOTES\>.

DEFOG
   +image: defog.jpg +image: defog2.jpg
   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.jpg  +image: red-eyes2.jpg
   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.jpg   +image: smart-erase2.jpg
   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.jpg  +image: remove-halo2.jpg
   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).

ADJUST RGB
   +image: adjust-RGB.jpg
   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 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.jpg
   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 from 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 (like most others) 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.jpg  +image: remove-dust2.jpg
   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.jpg   +image: chromatic1A.jpg
   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\b (optional, for geeks):
   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.jpg  +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.jpg   +image: RGB-dist.jpg
   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.

FLATTEN DIST
   +image: flatten1.jpg +image: flatten2.jpg
   Flatten Brightness Distribution increases visible detail in areas having poor contrast.
   The revised brightness for a pixel is based on the brightness distribution for nearby
   areas, as determined by the 'radius' input. Flatten controls the strength of the effect
   and deband moderates darker or brighter image areas. This function can amplify noise in
   uniform areas like sky. If the deband controls are inadequate, use \>SELECT AREA\> and
   \>DENOISE\>. Alternatively, use Select Area beforehand to select sky (or other areas)
   to omit, and then invert the selection prior to using Flatten Distribution.

   \bTechnical Explanation\b (optional)
   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.jpg  +image: localcon2.jpg
   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.jpg   +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 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 and vegetation.

GLOBAL RETINEX
   +image: global-retx.jpg   +image: global-retx2.jpg
   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.jpg  +image: local-retx2.jpg
   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.jpg
   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.jpg   +image: soft-focus.jpg
   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.jpg
   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 step can be skipped.
      3  Click on the image to take a color sample from the spot area enclosed by the
         mouse circle. You can change the radius and click again if wanted.
      4  Open the 2nd image by pressing the [open] button.
      5  Click on the image at the spot you want to match the spot color from the first
         image. The image colors will change within a second or two. You can change the
         radius and click on another spot - 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. The image reacts quickly to both line changes and curve edits.

VIGNETTE
   +image: vignette.jpg +image: vignette2.jpg
   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.jpg
   You can make a vignette with arbitrary shape as follows:
      • Select Area - select the image area to remain visible
      • Invert the area to select the areas outside the image
      • Set a blend width value for the edge fade-out width
      • Keep the Select Area dialog active
      • Paint Image - paint the outside areas with the desired color
         (the image edges will fade-out over blend width pixels)
      • Adjust the blend width value and paint again until satisfied


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.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
   the blur and kuwahara controls are set to high values. It works faster and better on
   smaller images, around 2 megapixels or less. I suggest you start with small values
   (2-3) for kuwahara and blur, then adjust line threshold to optimize the density of the
   drawn lines. Now change kuwahara and blur 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.jpg
   This function transforms a photo into a line drawing showing outlines of objects within
   the image. Feature edges (sharp transitions in brightness or color) in the image are
   brightened, and the rest of the image is darkened.

   There are three sliding controls.
      • Threshold: how bright a feature edge must be in order to get enhanced, from
        "no edges" at the low end to "all edges" (even faint ones) at the high end.
      • Width: width of the enhanced edges, from 1-pixel to about 5 pixels.
      • Brightness: brightness of the image itself, from dark (show only outlines)
        to full brightness.

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

EMBOSS
   +image: emboss2.jpg    +image: emboss.jpg
   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. The upper 60% of the example
   image was embossed.

TILES
   This function transforms a photo into an array of large monocolor tiles. You can
   control the tile size and the thickness of the gap between tiles. This is also called
   "pixelate" or "pixelize". Use Select Area to confine the transform to a limited area,
   such as a face.

PAINTING
   +image: painting1.jpg  +image: painting2.jpg
   This function transform a photo into something looking more like a painting. It reduces
   the number of colors, maps each contiguous pixel area having the same color, and then
   consolidates smaller areas into adjacent larger areas having the best color match.

   \bcolor depth
   Set the number of colors to use: 1 = 8 colors, 2 = 64 colors ... 5 = 32768 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.

TEXTURE
   +image: texture2.jpg    +image: texture.jpg
   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.jpg
   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 before using it.

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

DITHER
   +image: dither1.jpg  +image: dither2.jpg
   +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 a 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.

MOSAIC
   +image: mosaic2.jpg  +image: mosaic1.jpg
   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.jpg
   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.jpg  +image: color-depth1.jpg
   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.jpg
   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.jpg    +image: alien-colors2.jpg
   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.jpg
   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 in subsequent edits.
   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.jpg
   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.jpg  +image: unbend2.jpg
   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.jpg  +image: perspective1.jpg
   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.jpg    +image: area-rescale2.jpg
   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.jpg  +image: unwarp-closeup2.jpg
   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.jpg
   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.jpg  +image: twist2.jpg
   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.jpg
   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.jpg
   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.jpg  +image: inside-out1.jpg
   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. The 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.jpg
   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.jpg  +image: flatten-photo1.jpg
   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-comb.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.jpg  +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 a
   high contribution to dark pixels and a low contribution to bright pixels. The darkest
   image will be low on the left and high on the right, and 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.jpg
   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.jpg
   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 areas 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 well-aligned will show up
   clearly as shifts in the edges of objects in the image. Some of these can be made
   unimportant by changing the image used for painting (if more than one image is sharp
   enough). Using warp mode, make fine adjustments as needed to eliminate visible shifts.

STACK/PAINT
   +image: stack-paint.jpg
   +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.jpg  +image: stack-noise.jpg
   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/LAYER
   +image: stack-layer.jpg
   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.jpg  +image: stack-split.jpg
   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.

IMAGE DIFFS
   +image: image-diffs.jpg
   This tool shows the differences between two images by subtracting the RGB values.
   The pixels in one image are subtracted from the pixels in the other image, and
   negative values are inverted. Where the pixels exactly match, the result is black.
   The two images can be fine-aligned with the X- and Y-align values. If one image was
   made by editing the other one, without cropping, rotating or resizing, then align
   values of zero will show the image differences. The align values can be deliberately
   offset to produce an arty effect. See also Duplicate Images.

PANORAMA
   +image: panorama.jpg   +image: panorama1.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. Use the [resize]
   button to get a bigger combined image after moving them closer together. The images
   should be correctly curved and fit together well. If they do not, then the lens mm
   parameter (focal length, 35mm equivalent) needs adjustment. Image curvature changes
   as lens mm is adjusted. The initial value is obtained from EXIF data if available,
   and this is normally good enough. You can measure lens mm manually using the [search]
   button described below. If the images have no curvature (e.g. scanned images), use
   the 'no curve' checkbox to set the 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 the 'lens mm' value to reduce the curvature.
   Increase this parameter until the images fit together reasonably well, or use the
   [search] button to make a more precise determination (described below).

   The 'no auto warp' 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. Color matching is not
   done in this case, since there is no overlapping area to provide colors for comparison.

   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 swapfile or swap partition. This may make a large panorama successful (after
   taking a long time to complete) if the memory requirement is much greater than real
   available memory.

   +image: panorama2.jpg
   When fine alignment is complete, the combined image is displayed. The above dialog is
   started for fine adjustment of brightness and color match. You may see a sharp border
   between images if the images do not have the same brightness and color balance. Use
   the [auto color] button to perform an automatic color match, which is often adequate
   by itself. Use this button multiple times to get improved matching at the expense of
   greater color shifts that could add a false color tint. Restore the original image
   colors with [file color]. The image selected with the Select Image radio buttons is
   the starting image for the auto color matching. Reset using [file color] and select
   a different starting image to see results that may be slightly different. The RGB and
   brightness color controls allow you to make additional changes to better match the
   images. Select one of the images with the radio buttons, change the brightness and
   color values, and press the [apply] button to see the results. Use [auto color] to
   match the other images to the one changed. Use [file color] to restore the original
   values from the input images. The blend width input governs how the images are blended
   together: at the image overlaps, the color balance is gradually shifted over this many
   pixels, to mask imbalances that cannot be fully corrected. The default is 1 pixel,
   which makes any brightness or color differences look obvious.

   If the images do not align perfectly, you may be able to improve the alignment by using
   the mouse to push the images into alignment. In the final dialog, select mouse warp,
   select which one of the images with the radio buttons, and then drag the mouse 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. Parallax shifting will require a compromise, since it is generally not possible
   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, resulting in alignment that is 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.

   \bSetting lens mm Automatically
   The [search] button in the panorama pre-alignment dialog initiates an automated search
   for optimum lens mm. Use a suitable image pair: the subject is 50+ meters away, the
   images have a low horizon difference and little relative rotation, and there is plenty
   of high-contrast detail in the overlap area. Input your nominal lens focal length for
   lens_mm. After doing a decent pre-align, press the [search] button and wait a while for
   the results. Do this a second time and compare. If lens mm remains consistent, you can
   use it for your panoramas. The search function steps through a range of values for
   lens_mm and the image alignment offsets for x, y, and theta. It searches for the lens
   value that give the best alignment results for the given images. The process needs a
   minute or more, but you only need to do this once to characterize a given camera lens
   and focal length (zoom setting). Use the [save] button in the 1st dialog to put the
   focal length back into the image EXIF data.

   \bSetting lens mm Manually
   Make a panorama image of a brick wall (or any wall with lots of detail). The wall
   should be 5+ meters away. Take two photos with about 40% overlap. Within the panorama
   pre-align process, adjust lens_mm until overlapping bricks coincide. When making the
   two images, be sure to turn the camera on a vertical axis through the lens, minimizing
   lateral movement and rotation in other axes - otherwise your lens mm may not be
   optimal. The result should roughly correspond to the nominal focal length of your lens
   (35mm equivalent). It may be off somewhat (my 27mm lens works best with a lens_mm
   setting of 29-30mm). I speculate that this is because wide-angle camera lenses are not
   ideal lenses (pinhole equivalent). Most panoramas will still work well even if the
   lens_mm setting is off by 10%.

   \bColor Matching Problems
   If the images in a panorama have a large brightness difference, the automatic color
   matching may not work well enough. The most common problem is false sky colors. You
   may be able to improve this by brightening or darkening an input image to more closely
   match its neighbors. Sky can be easy to fix by selecting the false areas and copying
   sky from elsewhere in the image (\>COPY IN IMAGE\>). It seems to work better if you
   brighten the darker image instead of darkening the brighter one. You can do this in
   the final dialog as described above, or you can do this before starting the panorama.

   \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 already curved (assuming you have not
   used the 'flatten' option in the final panorama dialog). Stop the 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.

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

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.jpg
   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.jpg
   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.jpg
   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 wholly 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 resizes the image. Angle rotates the image. The Stacking Order buttons raise or
   lower an image relative to other images - this determines which overlapping image will
   be on top. Base Transparency is used to make an entire image partly transparent. The
   [paint] button is used to make any part of an image partly or fully transparent, using
   the Paint dialog 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 and loose with mouse clicks and drags). The
   Margins controls can be used to make image edge areas 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.jpg
   "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.jpg
   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.jpg
   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.jpg
   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 edge 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 resize it up to 160 megapixels when done.
   The larger layout can still be worked on directly afterwards, but it will be much
   slower.

IMAGE TABLE
   +image: image-table.jpg
   Select many images and join them into a compact table 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. Table Width is the overall width of
   the output table, and Margin is the width of the outer margin surrounding all images.
   Table 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 table 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
   table, one that does not conflict with other tables you have made before. A file save
   dialog is started, and you can save the new table 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 table 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 table file is moved, presuming the map file and
   the original images are still available.

   The saved table file is given a special suffix to make it recognizable as a Fotoxx
   table file. The full file name is: your-assigned-name (image table).jpg. If the map
   option is not selected, "(image table)" is not included in the name. The map files are
   stored in [fotoxx home]/image_table_maps/.

   Note that the popup image feature is not standard and will not work outside of Fotoxx.
   The image table file is a normal .jpg or .png file.


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.jpg
   This function is used to rename, convert, resize, upright and move multiple image
   files at once.

   Dialog Inputs
      • Select Files - Select files to convert from gallery windows (\>SELECT IMAGE FILES\>).
      • Replace Text - replace text string in file names (see Replace Text below).
      • New Name - Optional new name with 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.
      • upright - If an image is rotated 90 degrees, upright it (based on EXIF data).
      • 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 (year, month, day) 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.jpg
   Copy or move selected image file to a new location or folder. 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.jpg
   This function uprights image files rotated 90 degrees. It depends on EXIF data to know
   if a file is rotated. It is much faster than Batch Convert. You can simply select all
   candidate files and let it find the ones that are rotated. 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.jpg
   Select the files (\>SELECT IMAGE FILES\>). Select the option to 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.jpg
   This function converts selected RAW image files to JPG, PNG, or TIF format, using Dcraw,
   Raw Therapee, or Darktable (\>SETTINGS\>). The 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.jpg
   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.jpg
   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.jpg
   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.jpg  +image: batch-photo-date2.jpg
   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 will be replaced in the image files.
        enter a date only (yyyy-mm-dd) - the date will be replaced but not the time.
        enter a full date/time (yyyy-mm-dd hh:mm:ss) - the date/times are fully replaced.
      • Shift existing date/time (left image)
        Enter + or - values into any of the 6 fields: years, months, days, hours,
        minutes, seconds. Image file date/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.jpg
   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.jpg  +image: batch-report-meta.jpg
   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.jpg
   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.jpg
   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.
   This allows you to 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.

BURN DVD/BRD
   +image: burn-DVD.jpg
   Select any number of image files and copy them to a DVD or BlueRay optical disc.
      • Insert a blank disc and wait for the initial clatter to finish. A message may
        appear asking you what to do with the blank disc, or a program may start which
        the window manager thinks you want to run. Dismiss this window or program.
      • Start the Fotoxx Burn function.
      • The [Select Files] button starts a dialog for selecting image files to be copied
        (\>SELECT IMAGE FILES\>). Keep within disc capacity (DVD 4.7 GB, BlueRay 25 GB).
      • Select a DVD/BlueRay disc drive to use from the drop-down list (even if only one).
      • Press the Start button. The list of selected image files is sent to growisofs.
        (an optical disc recording utility).
      • Progress is shown in a popup window, along with any growisofs error messages.
        The job will fail right away if the selected files do not fit on the disc.

   The resulting disc is frozen. Leftover space cannot be used later to add more images.

EXPORT FILE LIST
   +image: export-file-list.jpg
   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.jpg
   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
               Resize            change the pixel dimensions of an image
               Mirror            mirror image horizontally or vertically
               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 up/down 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
               Tiles             convert image into tiles
               Painting          convert image into a simulated painting
               Texture           add texture to an image (e.g. image on tapestry)
               Pattern           add pattern to an image (e.g. image on brick wall)
               Dither            convert image into dots - four styles
               Color Depth       reduce color depth (bits/color) 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.jpg
   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
   \>TECHNICAL NOTES\> 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. Indexing will run faster if this is on a
   separate physical disk from the image files.

   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 have been 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.jpg
   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 use Fotoxx to access a portable USB storage device (e.g. a 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.

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 use this function.

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

   Use the dialog to select or create a new folder for Fotoxx home. I suggest you use the
   name /fotoxx or /.fotoxx as the lowest folder level. This folder would typically be on
   a mounted volume to keep it isolated from Linux installs and shareable with multiple
   Linux systems. Putting /home on a separate volume is a common method to do this, but
   there are risks if multiple Linux systems share this same /home folder: applications
   with different release versions may have data file and format differences, which can
   lead to application failures and even crashes.

   All user data will be moved automatically. No new indexing of the image files is
   required. A file is created in the user home folder: /home/<user>/.fotoxx-home. This
   is a one-line text file which contains the file name of the new fotoxx home folder.
   When fotoxx starts, fotoxx will look here first for its home folder. If there are
   multiple Linux systems, this file needs to be duplicated in each of the /home/<user>
   folders.

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 an application 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 Image File: the file last viewed in the prior Fotoxx session
      • Specific Image 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
   • 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 log messages (in terminal or in log file):
        error messages only, add information messages, add dialog inputs
        The latter will log details of dialogs opened, buttons pressed, etc.
   • RAW Loader - loader to use for RAW files - See \>EDIT WORKFLOW\>
   • RAW Options - auto brighten dim images, match colors from embedded image
   • RAW Files - customize this list to match the RAW files you actually have
   • Video App - set the shell command for playing video files, e.g. "totem %s"
                 (see additional information below)

   \bFile Quality and Compression
   JPEG file quality level: use 70 or higher for good image quality (default is 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 no more
   than increase the file save time (libpng is 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.

   \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 and disk 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 1 second per 10K image files.
        Following startups are roughly 3x faster. First startup with an SSD disk is
        roughly 1 second per 20K image files (for 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, and not wait for indexing.
   You can control this with the two 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 image
        files to update the index. Startup time is moderately fast. Image search and
        map functions work OK, 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
   Choose one of the 3 RAW loaders, or "Custom Command". In the latter case, you must
   enter a command line below, containing "%s" as a place marker for the input RAW file.
   The output file should be the same as the RAW file name, with extension ".tif".

   \bRAW Options
      • auto brighten - expand the brightness range for images not using the full range
      • embedded image profile - use the RAW file embedded image as a guide to map the
        RGB color values from the RAW file to the displayed image. This is the camera
        maker's interpretation of the RAW data. This is likely a good place to start if
        you want to refine the image using Fotoxx edits.
   These two options are mutually-exclusive. If neither is used, you get the default RAW
   file processing from the selected RAW file loader.

   \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.jpg +image: KB-shortcuts2.jpg
   This function is used to view or change custom keyboard shortcuts. The 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.jpg
   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.jpg
   Find duplicated image files anywhere within your image database. A duplicate image
   file can be an image file that exactly duplicates another image file, or an image file
   that "almost" duplicates another. For the sake of speed, thumbnail images are compared
   in memory. Hence it is possible that identical thumbnails are found for which the main
   images have some minor (likely invisible) differences that do not show up in the
   thumbnails. An image copy that was reduced 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, 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 are different 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 2.8 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.jpg
   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.jpg
   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.jpg  +image: calibrate-printer.jpg
   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 a large paper size, vertical orientation, no margins.
      2. Scan the printed chart into a PNG file. Use 300 dpi or more to make a large file.
      3. Edit the PNG image to crop margins left by the scanner. Save the edited image
         as <chosen-name>.png. The name should contain printer settings and paper type.
      4. Process the edited chart file to create a color map file <chosen-name>.dat.
         Use a name indicating the printer settings and type of paper used.
      5. Print a color-adjusted image. You are asked for the color map file from step 4.

   Once you have made 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 (A4 or US Letter) to make the color
        tiles as big as possible.
      • Clean the scanner glass before scanning the color chart. Dust spots or smudges
        will falsify the 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 this 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.jpg  +image: printer-cal-study.jpg
   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
   Look for tiles in the upper left image that least match those in the bottom image.
   Look at these same tiles in the upper right image. The match is mostly better.

   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.jpg
   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- 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 count and 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 as 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.


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

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 and earth coordinates), 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 the 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 (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 is also the most demanding of organizational
   care. You can go through your images sequentially and add tags by clicking on a list of
   defined tags. New tags can be defined as needed. Images can have many tags, and can be
   searched 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 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
   any combination, combined 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 the location name (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 the 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 for 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" would miss the example above)
      • 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 applications

   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 available 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 using Search and Batch Tags)
      • map markers are generated automatically from image geotag data
      • search by: location (city, park, monument ...) and country
      • good overview of available search topics: clickable list of locations and dates
      • click on a map marker to show a gallery of images at location

   Albums
      • album names like this: favorites, best scenery, Italy 2014, Susan childhood
      • 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


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

   \bFotoxx Limitations
      • 1 million indexed image files - Fotoxx has been tested with 500K image
        files and the performance remained good.
      • image size - The max. supported image width or height is 40K pixels.
        The maximum image size is 256 megapixels (4 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.

   \bGallery Size Limits
   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 by a size limitation. The limits for 512 pixel and 360 pixel
   thumbnails are respectively 35K and 64K files.

   \bRunning 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
      • Resize (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 crash, or may take so long that you
   give up and kill the process.

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

   \bzappcrash\b - backtrace dump after a fatal error
   If Fotoxx has a fatal error, it attempts to intercept the error and produce a backtrace
   dump which is copied to the desktop. Please send this file to mkornelix@gmail.com so I
   can find and fix the error. A description of what you did immediately before the crash
   would be helpful, since I may not be able to fix the error unless I can reproduce it.
   zappcrash requires the utility program 'addr2line' (in package binutils) to add source
   code line numbers to the report.

   \bSymbolic Links in Fotoxx
   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 (which
   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.

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

   \bBit Depth\b (as shown in top panel)
   This shows the bits per channel (RGB color) of the file being viewed or edited. 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.
   If a RAW file is edited, this is done in 24-bit precision, regardless of the bit depth
   of the input file.

   \bFile Size\b (as shown in top panel)
   When an image file is edited, the file size shown on the top panel is the original
   (unedited) file size. The file size for an edited image is not known until the image
   is saved on disk. In memory the size is (pixels x 16). A 40 megapixel image is 640 MB
   in memory and typically less than 4 megabytes on disk (high quality JPEG). When the
   edited image is saved, the correct file size is updated on the top panel.

   \bFile Types Supported
   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. Adobe files (.pdf/.ps/.eps/.psd) can be converted into jpeg image
   files using the function \>CONVERT ADOBE\>.

   \b.MPO Files
   These are containers for the left and right images of a 3D image pair. In Fotoxx, .MPO
   files are treated mostly as RAW files. For .MPO files to be recognized, the .MPO type
   must be entered in the list of RAW file types in the Tools > Settings function. The
   left image is used for the thumbnail and file view. A function is available to extract
   the left and right images as JPEG files: right-click the thumbnail for a menu.

   \bIndex Data Files
   These can be found in the folder [fotoxx-home]/image_index_*/
   image_folders: contains a list of the top image folders. These are searched for new
   image files whenever Fotoxx starts up. The last entry is the thumbnails folder.
   image_index: contains image file pathnames and metadata items that are indexed for
   fast searching (dates, ratings, tags, titles, descriptions, geotags, optional items).
   meta_index: optional metadata items that have been added to the image index.

   \bColor Depth
   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 within 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 (2021), 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 only 6 bits
   (64 brightness levels). Note that the brightness steps are barely visible.
   +image: brightness-steps.png

   \bDenoise Function - noise measurement
   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.

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

   \bRotate Function
   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 make the image move faster
   and smoother: (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 rotation 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 after one second.

   \bAlignment Algorithm (HDR, HDF, Stack, Panorama)
   Relatively few high-contrast or "feature edge" pixels are used to control alignment.
   The actual pixels used are shown in red during the alignment process, which is also
   more entertaining. Each image in succession is systematically warped various small
   amounts and the fit with other images is tested. This is done because two photos made
   with slightly different horizons or rotations will not fit perfectly with simple
   translation and rotation. Also camera lenses are not geometrically perfect.

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

   \bImage Deterioration From Repeated Editing
   If you save an edited image file and then use this file later to perform additional
   edits, pixel resolution may be lost. It is better if you do all edits when the image
   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 the resize, rotate, warp, and all combine
   functions. Rotating 90 degrees does not affect resolution. When downsizing an image,
   using the ratios 1/2, 1/3, 1/4 will give the best resolution. Functions that change
   brightness and color do not affect resolution.

   \bInterpolation Method
   +image: interpolation.jpg
   When an image is resized, rotated, or warped, the resulting output pixels must be
   "interpolated" from their 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 called
   "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 values 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 4 GHz 6-core computer, downsizing a 200
   megapixel image to 1/4 size takes about 0.24 elspsed seconds.

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

   \bImage Deterioration From Repeated Saving of JPEG files
   Reading a compressed JPEG image and saving it again can lead to loss of detail and
   increased image artifacts. The effect seems to be negligible if JPEG "quality" is set
   to a high value when the image is saved. The image below was saved 10 times using
   quality=90 (Fotoxx default), each time opening and saving the previous image file.
   Differences can be found if you look hard enough. The images are 2x size and the
   insets are 5x.
   +image: jpeg-quality.jpg

   \bMetadata 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 using the Edit Any Meta function.

   \bNewline characters in image descriptions
   When editing metadata image descriptions, if you need to align text in 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.
   \bThis is not standard\b, 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.

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

   \bFotoxx 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 image folders to update thumbnails and
   the metadata index. The processing speed for NEW image files can range from 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 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 10K files/sec. for a slow spinning disk, up to 30K/sec. for
   a fast SSD disk. This is for the first Fotoxx startup after the computer was booted.
   Subsequent startups are about 2-3x 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 4K 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. If there is some
   metadata you need to search often, include this in your list of indexed metadata.

   Fotoxx can edit images up to about 256 megapixels. On a strong computer, responsiveness
   for most edit functions is below 1 second for images up to 30 megapixels or so. Beyond
   this, expect responsiveness to decline. The following table shows the time in seconds
   to open and view the image, start an edit function, and respond to the dialog controls.
   The computer used was my fairly strong desktop - 4 GHz, 16 GB, SSD disk. The long open
   time for the 754 megapixel image was due to >1 million page faults to allocate 12 GB.

                                             edit - unsharp mask
      image size     megapixels  open file    startup  response
      8K x 6.7K          54         0.4         1.9       0.8
      10K x 8.4K         84         0.8         3.2       1.2
      12K x 10.0K       120         1.3         4.4       1.9
      16K x 13.4K       214         1.8         7.4       2.7
      20K x 16.8K       335         2.7        too large to edit
      30K x 25.1K       754        11.2        too large to edit

   \bGTK 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. calling a library function to read a huge image file can require >10 seconds).
   Fotoxx sets this timer to a large value to reduce the possibility that this confusing
   annoiance happens. This timer is system-wide, so GTK applications that run later are
   also affected (i.e. their timeout timer is also larger).

   \bFotoxx binary package
   This package contains the fotoxx binary executable with libraries used by Fotoxx, but 
   only those likely to differ depending on Linux flavor and release date. This package 
   should run OK on most recent flavors of Linux. 

   \bUninstall Fotoxx
   Uninstalling Fotoxx depends on how it was installed:
   Source tarball: command:  $ sudo make uninstall
   Debian package: command:  $ sudo apt remove fotoxx
   Binary package: delete all 'fotoxx' files under $HOME/.local/*

   \bInstalled Files
      Debian package or build from source tarball:
         /usr/bin/fotoxx            the executable program file
         /usr/share/fotoxx/*        user guide, icons, default data, etc.
         /usr/share/doc/fotoxx/*    change log, man page, license, copyright
      binary package: 
         $HOME/.local/bin/fotoxx and fotoxx.x
         $HOME/.local/share/applications/fotoxx.desktop
         $HOME/.local/share/icons/fotoxx.png
         $HOME/.local/share/doc/fotoxx/*
         $HOME/.local/share/fotoxx/*

   \bFotoxx Folders and Files
      • Fotoxx Home: folder for user preferences, settings and general Fotoxx data
      • Default Fotoxx home location:  /home/<user>/.fotoxx/
      • If Fotoxx home was moved elsewhere by the Move Fotoxx Home function,
        the file  /home/<user>/.fotoxx-home  contains the location of Fotoxx home.
      • The files in Fotoxx home are preserved when a new release of Fotoxx is installed.

   The folder "image_index_*" (within Fotoxx home) contains the following files:
      • image_folders: top folders for indexed image files, and thumbnails folder
      • image_index: large text file containing image file names and indexed metadata
      • meta_index: list of optional metadata items that are indexed

   \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_table_maps/     saved image table maps
      • 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 the 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
      • blacklist             list of files with internal errors - not usable by Fotoxx
      • 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
      • gallery_memory        saved sort order and position for gallery windows
      • image_folders         list of top image folders
      • KB-shortcuts_*        user-defined keyboard shortcuts
      • logfile               outputs that may be relevant for diagnosing problems
      • 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            setup parameters that are saved across Fotoxx sessions
      • plugins               saves the plugins menu contents
      • popup_text            collection of special characters for text widget inputs
      • printsettings         saves print settings data for print function
      • README                text file - how to install Fotoxx from source tarball
      • recent_files          list of the last 1000 files opened by Fotoxx
      • recent_topics         recent topics seen in the user guide (for quick reference)
      • 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
      • temp/                 temporary files for current sessions (can be more than 1)
      • thumbnails/           thumbnail files (default location, user can change this)
      • 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
      • zdialog_geometry      saved dialog window positions (relative to main window)
      • zdialog_inputs        saved dialog data for dialogs that recall prior inputs

   \bMetadata used by Fotoxx
   The following metadata items (stored inside the image files) are used by Fotoxx. These
   items (and any other metadata) can be viewed or edited using Fotoxx. Images can be
   searched using these items (or any other 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 entered by user
      (*) FocalLengthIn35mmFormat - some cameras use 'FocalLength' for the same thing

   \bFotoxx Source Code
   The C++ source code is available at the author's web site: \_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.

   \bQuestions, Problems, Bugs
   If you have a question or a problem, you may contact me: mkornelix@gmail.com.
   If you get a crash with a traceback dump (zappcrash file), please send this to me.
   Please explain how to produce the error, if you can.

   \bFotoxx for Microsoft 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 Windows NTFS file system is much slower than
   the Linux ext4 file system. If you use the Linux file system included in WSL2, the
   performance will be good, but these files are not accessible from Windows. More
   information is available in the above link.

   \bAcknowledgements
   Several edit 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 115K lines of C/C++ code.
   The primary author is Michael Cornelison.


ALL TOPICS INDEX
   \>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
   \>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 all images
   \>BATCH CONVERT\> - copy, move, resize, rename, convert, add text ...
   \>BATCH COPY/MOVE\> - copy/move selected files to a new folder
   \>BATCH DELETE/TRASH\> - delete or trash selected images
   \>BATCH GEOTAGS\> - add or revise geotags for selected or all images
   \>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 images
   \>BATCH REPORT META\> - report metadata for selected or all images
   \>BATCH SCRIPT\> - execute script on all selected image files
   \>BATCH TAGS\> - add or remove tags for selected images
   \>BATCH UPRIGHT\> - scan for rotated images and upright them
   \>BLANK IMAGE\> - create a new blank image file with specified size and color
   \>BLANK WINDOW\> - blank or restore (toggle) the current image window
   \>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
   \>BURN DVD/BRD\> - create a DVD or BlueRay disc with selected image files
   \>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
   \>CHOOSE MAP\> - choose from available maps (USA, France, NYC, etc.)
   \>CHROMATIC 1\> - fix chromatic aberration (color fringes, mainly image periphery)
   \>CHROMATIC 2\> - fix chromatic aberration (color bands along bright/dark edges)
   \>CLEAR AREA\> - remove an area
   \>COLLECTION MANAGEMENT\> - collection management and image searching
   \>COLOR DEPTH\> - reduce the number of colors (posterize)
   \>COLOR MODE\> - convert to black & white, color, negative, positive, sepia
   \>COLOR PROFILE\> - convert color profile (e.g. sRGB <--> Adobe RGB)
   \>COMMAND PARAMETERS\> - Fotoxx startup options using command line parameters
   \>CONVERT ADOBE\> - convert Adobe files (.pdf/.ps/.eps/.psd) to jpeg images
   \>COPY COLORS\> - copy selected colors from current image
   \>COPY/COMPLEX\> - select and copy area with complex edges (e.g. hair)
   \>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
   \>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
   \>DARKTABLE\> - (RAW files only) start special RAW edit program
   \>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, esp. in dark areas)
   \>DIALOG BUTTONS\> - dialog completion options
   \>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
   \>EDGE BLEND\> - mouse-blend edges of edits made within a selected area
   \>EDIT ANY META\> - edit any metadata (add, change)
   \>EDIT DIST\> - edit brightness distribution, rebalance dark and bright areas
   \>EDIT META\> - edit commonly used metadata
   \>EDIT PROCEDURES\> - how to edit image files
   \>EDIT SCRIPT\> - record a series of edits in a script file, execute on many files
   \>EDIT WORKFLOW\> - alternative edit methods - simple and complex
   \>EMBOSS\> - convert an image to a simulated embossing (3D effect)
   \>ENABLE/DISABLE AREA\> - enable or disable an area for editing
   \>ESCHER SPIRAL\> - transform an image into an endless inward spiral
   \>EXPORT FILE LIST\> - create a list of selected files (e.g. for a shell script)
   \>EXPORT FILES\> - export selected files to a folder (e.g. for web upload)
   \>EXTRACT MPO FILES\> - (MPO files only) extract left/right files from 3D pair
   \>FILE MAP\> - use local map files
   \>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 image collection
   \>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 OVERVIEW\> - description, prerequisites, license, downloads
   \>GALLERY END\> - jump to gallery end
   \>GALLERY HOME\> - jump to gallery start
   \>GALLERY SCREEN\> - select newest, oldest, matching pattern ...
   \>GALLERY SORT\> - change the sort order of a gallery
   \>GALLERY TO ALBUM\> - save the 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 local contrast to improve details
   \>GRID SETTINGS\> - show or remove grid lines, set line count or spacing
   \>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, privacy policy, about Fotoxx
   \>IMAGE DIFFS\> - subtract two images (with offsets) for artistic effect
   \>IMAGE FOLDER (2)\> - open corresponding Gallery View from current File View image
   \>IMAGE FOLDER\> - open corresponding Gallery View from current File View image
   \>IMAGE TABLE\> - join many images into a compact table format
   \>INDEX FILES\> - 1-time job to find and index all image files
   \>INDEX FUNCTION\> - locating and indexing image files for fast searching
   \>INSIDE-OUT\> - invert the center-edge distance of each pixel
   \>INSTALLATION\> - Fotoxx software installation, dependencies
   \>INVERT AREA\> - invert an area (exchange outside/inside areas)
   \>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
   \>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
   \>MAP VIEW\> - map view window (view map with location markers)
   \>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
   \>META VIEW\> - Gallery View with thumbnail and basic metadata used by Fotoxx
   \>MIRROR\> - mirror (or flip) an image horizontally or vertically
   \>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\> - alternate 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
   \>NEW SESSION\> - start new Fotoxx session in a separate window
   \>OPEN IMAGE FILE\> - open an image file for view or edit
   \>ORGANIZING IMAGES\> - options for image organization and efficient searching
   \>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\> - use another image edit application as a Fotoxx edit function
   \>POPUP REPORTS\> - keyboard navigation for text-based popup reports
   \>POPUP TEXT\> - show popup window with characters/texts to insert into edit widgets
   \>PRINT CALIBRATED\> - print an image file using printer color calibration data
   \>PRINT\> - print an image file
   \>PRIVACY\> - Fotoxx privacy policy
   \>QUICK INDEX\> - quick incremental index with no user interaction
   \>QUIT\> - exit from Fotoxx
   \>RAW THERAPEE\> - (RAW files only) start special RAW edit program
   \>RECENT FILES\> - open Gallery View of most recently seen image files
   \>RED EYES\> - remove red eyes from flash photos
   \>REMOVE ALPHA\> - apply alpha to RGB values and remove alpha channel
   \>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
   \>RESIZE\> - change the image pixel dimensions
   \>RETOUCH\> - edit brightness, contrast, color, saturation
   \>RGB DISTRIBUTION\> - show a brightness distribution graph for the current image file
   \>RIGHT-CLICK MENUS\> - popup menu functions for File View and Gallery View
   \>ROTATE\> - rotate or level an image
   \>RUN SCRIPT\> - execute script on current image file (a custom edit function)
   \>SATURATION\> - adjust color saturation, optionally based on brightness
   \>SCRIPT FILES\> - script files (macros) overview
   \>SEARCH IMAGES\> - search images using any metadata or file name data
   \>SELECT AREA\> - selecting an image feature or area for separate editing
   \>SELECT FILES\> - select files for an album, or input to batch or script function
   \>SELECT IMAGE FILES\> - image file selection procedure used for many functions
   \>SETTINGS\> - user preferences and settings for Fotoxx operation
   \>SET WALLPAPER\> - set the 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 the 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
   \>SMART ERASE\> - remove power lines, trash, signs, other small image spoilers
   \>SOFT FOCUS\> - apply classic "soft focus" effect to an image
   \>SPHERE\> - curve an image into a spheroid shape
   \>STACK/LAYER\> - combine images, select/paint which image to show in each area
   \>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
   \>TAGS OVERVIEW\> - image tags (keywords) used for image searching
   \>TECHNICAL NOTES\> - some technical information about Fotoxx
   \>TEXTURE\> - add texture to an image or selected area
   \>THUMB VIEW\> - Gallery View with large thumbnails and file names only
   \>TILES\> - convert an image into simulated square tiles
   \>TIMELINE\> - table of image counts by year and month, click for gallery
   \>TINY PLANET\> - wrap a panorama image around a circle
   \>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 distortions of a close-up face photo (e.g. big nose)
   \>UPDATE ALBUMS\> - update album files for updated image files (new versions)
   \>UPRIGHT\> - upright a rotated image (automatic or ±90 degrees)
   \>USER GUIDE\> - comprehensive Fotoxx usage guide (this document)
   \>VERT. PANORAMA\> - stitch together a series of images vertically
   \>VIDEO FILES\> - show and play video clips included in image collection
   \>VIEW 360° PANO\> - view a 360° panorama with a rotating viewpoint and wrap-around
   \>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 pulling with the mouse - 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 pulling with the mouse - straight lines preserved
   \>WEB UPLOAD\> - how to select and upload a batch of images to Flickr, etc.
   \>WINDOW VIEWS AND MENUS\> - top-level windows and associated menus
   \>ZOOM\> - increase/decrease image/thumbnail size, \>FILE VIEW\>, \>GALLERY VIEW\>

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

UG-topics $: ./UG-topics 
source folder: /home2/mico/programs/fotoxx-23.2/*.cc 
file: /home2/mico/programs/fotoxx-23.2/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.2/UG-topics/UG-topics.cc 
file: /home2/mico/programs/fotoxx-23.2/f.edit.cc 
   topic: \>PAINT EDITS\> 
   topic: \>ROTATE\> 
   topic: \>CROP\> 
   topic: \>RETOUCH\> 
   topic: \>RESIZE\> 
   topic: \>UPRIGHT\> 
   topic: \>MIRROR\> 
   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: \>RAW THERAPEE\> 
   topic: \>DARKTABLE\> 
   topic: \>EXTRACT MPO FILES\> 
file: /home2/mico/programs/fotoxx-23.2/f.widgets.cc 
   topic: \>CUSTOM MENU\> 
   topic: \>CUSTOM MENU\> 
file: /home2/mico/programs/fotoxx-23.2/f.batch.cc 
   topic: \>BATCH CONVERT\> 
   topic: \>BATCH COPY/MOVE\> 
   topic: \>BATCH UPRIGHT\> 
   topic: \>BATCH DELETE/TRASH\> 
   topic: \>BATCH RAW\> 
   topic: \>BATCH OVERLAY\> 
   topic: \>BURN DVD/BRD\> 
   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.2/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: \>REMOVE ALPHA\> 
   topic: \>ZOOM\> 
   topic: \>BLANK IMAGE\> 
   topic: \>BLANK WINDOW\> 
   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: \>FILE SAVE\> 
file: /home2/mico/programs/fotoxx-23.2/fotoxx.cc 
   topic: \>FIRST STARTUP\> 
   topic: \>UNDO/REDO BUTTON\> 
file: /home2/mico/programs/fotoxx-23.2/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.2/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.2/f.tools.cc 
   topic: \>INDEX FILES\> 
   topic: \>QUICK INDEX\> 
   topic: \>MOVE FOTOXX HOME\> 
   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.2/f.select.cc 
   topic: \>SELECT AREA\> 
   topic: \>FIND AREA GAP\> 
   topic: \>EDGE BLEND\> 
   topic: \>COPY/COMPLEX\> 
   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.2/f.mashup.cc 
   topic: \>MASHUP\> 
   topic: \>IMAGE TABLE\> 
file: /home2/mico/programs/fotoxx-23.2/f.effects.cc 
   topic: \>SKETCH\> 
   topic: \>CARTOON\> 
   topic: \>DRAWING\> 
   topic: \>EMBOSS\> 
   topic: \>TILES\> 
   topic: \>PAINTING\> 
   topic: \>TEXTURE\> 
   topic: \>PATTERN\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   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.2/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.2/f.pixmap.cc 
file: /home2/mico/programs/fotoxx-23.2/f.repair.cc 
   topic: \>SHARPEN\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>DENOISE\> 
   topic: \>DEFOG\> 
   topic: \>RED EYES\> 
   topic: \>SMART ERASE\> 
   topic: \>REMOVE HALO\> 
   topic: \>ADJUST RGB\> 
   topic: \>ADJUST HSL\> 
   topic: \>COLOR PROFILE\> 
   topic: \>REMOVE DUST\> 
   topic: \>CHROMATIC 1\> 
   topic: \>CHROMATIC 2\> 
file: /home2/mico/programs/fotoxx-23.2/f.comb.cc 
   topic: \>HDR\> 
   topic: \>HDF\> 
   topic: \>STACK/PAINT\> 
   topic: \>STACK/NOISE\> 
   topic: \>STACK/LAYER\> 
   topic: \>STACK/SPLIT\> 
   topic: \>IMAGE DIFFS\> 
   topic: \>PANORAMA\> 
   topic: \>VERT. PANORAMA\> 
   topic: \>SHOW CIM FILES\> 
file: /home2/mico/programs/fotoxx-23.2/f.albums.cc 
   topic: \>MANAGE ALBUMS\> 
   topic: \>UPDATE ALBUMS\> 
   topic: \>GALLERY TO ALBUM\> 
   topic: \>ALBUM MASS UPDATE\> 
   topic: \>SLIDE SHOW\> 

