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

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

FOTOXX USAGE
   \>INSTALLATION\> - Fotoxx software installation, dependencies
   \>FIRST STARTUP\> - information for when Fotoxx is started for the first time
   \>OUTBOARD PROGRAMS\> - required and optional programs used by Fotoxx
   \>FIRST INDEX\> - locating and indexing image files for fast searching
   \>USER GUIDE\> ← \bclick here\b - how to use this user guide browser
   \>WINDOW VIEWS AND MENUS\> - top-level windows and associated menus
   \>FILE VIEW\> - File View window (view single image file)
   \>GALLERY VIEW\> - Gallery View window (view thumbnails)
   \>MAP VIEW\> - map view window (view map with location markers)
   \>MENU SUMMARY\> - outline of menu groups and contents
   \>DRAG AND DROP\> - file drag and drop methods
   \>EDIT PROCEDURES\> - how to edit image files
   \>EDIT WORKFLOW\> - alternative edit methods - simple and complex
   \>MOUSE OWNERSHIP\> - dialog-mouse control and interaction
   \>MOUSE ALTERNATE RIGHT-BUTTON\> - 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 image file
   \>CYCLE 2\> - cycle through the two most recently seen image files
   \>CYCLE 3\> - cycle through the three most recently seen image files
   \>VIEW 360° PANO\> - view a 360° panorama image with rotating viewpoint
   \>RENAME\> - rename an image file
   \>PERMISSIONS\> - view and set permissions for an image file
   \>CHANGE ALPHA\> - add or remove alpha channel for an image file
   \>BLANK IMAGE\> - create a new blank image file with specified size and color
   \>COPY/MOVE\> - copy or move an image file to another folder
   \>COPY TO DESKTOP\> - copy an image file to the desktop
   \>COPY TO CLIPBOARD\> - copy an image file to the clipboard
   \>DELETE/TRASH\> - delete or trash an image files
   \>CONVERT ADOBE\> - convert Adobe files (.pdf/.ps/.eps/.psd) to jpeg images
   \>SET WALLPAPER\> - set 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 image file
   \>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 image files using any metadata or folder/file names

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

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

EDIT FUNCTIONS

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

\>REPAIR MENU\>
   \>SHARPEN\> - sharpen a blurred image, multiple methods
   \>BLUR\> - blur an image or image area, multiple methods
   \>DENOISE\> - reduce image noise (small random specks)
   \>DEFOG\> - add or remove fog/haze from an image or selected area
   \>RED EYES\> - remove red eyes from flash photos
   \>SMART ERASE\> - remove power lines, trash, signs, other small image spoilers
   \>REMOVE HALO\> - remove halos left by sharpen and other edit functions
   \>JPEG ARTIFACTS\> - suppress jpeg artifacts in highly compressed image files
   \>ANTI-ALIAS\> - suppress pixelation (jaggies) along image feature edges
   \>ADJUST RGB\> - adjust image colors using RGB or CMY colors
   \>ADJUST HSL\> - select and change colors using HSL colors
   \>COLOR PROFILE\> - convert color profile (e.g. sRGB <--> Adobe RGB)
   \>REMOVE DUST\> - remove dust spots on images scanned from old photos
   \>CHROMATIC 1\> - fix chromatic aberration (color fringes, 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)
   \>TILES1\> - convert an image into square tiles with 3D effect
   \>TILES2\> - convert an image into irregular tiles matching image
   \>PAINTING\> - convert an image into a simulated painting
   \>TEXTURE\> - add texture to an image or selected area
   \>PATTERN\> - add a background pattern to an image
   \>DITHER\> - different ways to pixelize or posterize an image
   \>ENGRAVE\> - convert an image into black & white lines
   \>MOSAIC\> - convert an image into a mosaic using tiles made from all images
   \>ADD NOISE\> - add random noise to an image
   \>COLOR DEPTH\> - reduce the number of colors (posterize)
   \>SHIFT COLORS\> - gradually shift RGB colors to GBR or BRG
   \>ALIEN COLORS\> - add random strange colors to an image
   \>COPY COLORS\> - copy selected colors from current image
   \>PASTE COLORS\> - paste selected colors from selected image
   \>CUSTOM KERNEL\> - edit and apply a custom convolution kernel to an image

\>WARP MENU\>
   \>UNBEND\> - straighten images having curved lines, esp. panoramas
   \>PERSPECTIVE\> - straighten an object photographed from an obtuse angle
   \>WARP AREA\> - warp a selected image area by pulling with the mouse
   \>WARP CURVED\> - warp entire image or area using the mouse - curvy warp
   \>WARP LINEAR\> - warp image by 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/VERSIONS\> - combine image versions, select/paint area/version
   \>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
   \>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 ARRAY\> - join many images into a compact array format

\>BATCH MENU\>
   \>BATCH CONVERT\> - copy, move, rescale, rename, convert, add text ...
   \>BATCH COPY/MOVE\> - copy/move selected image files to a new folder
   \>BATCH UPRIGHT\> - scan for rotated image files and upright them
   \>BATCH DELETE/TRASH\> - delete or trash selected image files
   \>BATCH RAW\> - convert RAW files to JPEG/PNG/TIFF, 8 or 16 bit color
   \>BATCH OVERLAY\> - add overlay image (copyright ...) to selected host images
   \>BATCH TAGS\> - add or remove tags for selected image files
   \>BATCH RENAME TAGS\> - rename tags for selected or all image files
   \>BATCH PHOTO DATE\> - change photo dates or times, or shift time zone
   \>BATCH CHANGE META\> - add or revise metadata for selected or all image files
   \>BATCH REPORT META\> - report metadata for selected or all image files
   \>BATCH MOVE META\> - move metadata between keywords - fix irregular usage
   \>BATCH GEOTAGS\> - add or revise geotags for selected or all image files
   \>EXPORT FILE LIST\> - 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, about Fotoxx, uninstall

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

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

\>ACKNOWLEDGEMENTS\>

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

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

   \bHardware Requirements
   Fotoxx works best on a strong computer, e.g. a 3+ GHz multi-core CPU with 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.

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

   \bPackages by 3rd Parties
   Installable packages for many popular Linux distributions can be found here:
      \_https://repology.org/metapackage/fotoxx/packages
   Some of these are 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 fixed within 
   a few days of being known, and a new release is published on the kornelix.net web site. Fotoxx is also 
   available on many other web sites and package repositories. These may not be updated for 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 be frustrated 
   and may conclude that Fotoxx is hard to use. You would be wrong. To avoid getting stuck, please read the 
   introductory sections of this user guide. Help for individual functions can be referenced as needed during
   Fotoxx use, by pressing the F1 key. Fotoxx has deep functionality. Do not expect to master Fotoxx in a few 
   minutes.

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

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

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

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

      \boptional
      ffmpeg             video thumbnails, extract frame image     ffmpeg
      dwebp              read WEBP image files (.webp)             webp 
      heif-convert       read Apple iPhone files (.heic .avif)     heif-examples
      opj_decompress     read jpeg2000 image files (.jp2)          libopenjp2-tools
      gs command         Adobe doc files (.pdf/.ps/.eps) >> .jpg   ghostscript
      convert command    Adobe image files (.psd) >> .jpg          imagemagick
      vlc                play videos, slide-show music             vlc 

   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 .avif)
   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. This also works for .avif files.

   \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.
   
   \bAdobe document files (.pdf .ps .eps)
   If the gs command (ghostscript) is installed, Adobe text files (.pdf .ps .eps) can be converted to JPEG 
   files, one file per document page. Use the menu function File > Convert Adobe.
   
   \bAdobe (Photoshop) image files (.psd)
   If the convert command (imagemagick) is installed, Adobe Photoshop files (.psd) can be converted into a 
   JPEG file. Use the menu function File > Convert Adobe.

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

   \bUpgrade from a Fotoxx prior release
   Normally the index file is not affected, so that no re-indexing is required. 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 7000 large JPEG images per 
   minute.

   +image: index-files1.png

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

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

   \bMetadata Items
   The following metadata is included in the image index by default: folder and file names, photo date/time, 
   file modification date/time, title, description, rating (0-5 stars), tags (keywords for image contents), 
   geotags (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 image 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 may need some time. The speed can range from 
   a few hundred to a few thousand files per minute, depending on processor speed, disk speed, and average 
   image file type and size:
     slow case: laptop, 1 GHz, spinning disk, images >30 megapixels, many RAW or PNG files
     fast case: desktop, 4 GHz, 4+ CPU cores, SSD disk, images <10 megapixels, mostly JPEG files

   Here are a few real-world index benchmarks. Files were mostly JPEG averaging 2.3 MB.
      \bCPU    GHz   cores   disk type          files/minute
      Intel  3.5    6      SSD PCIe           19758
      Intel  3.5    6      SSD PCIe           58462   (small jpeg ca. 0.2 MB)
      Intel  3.5    6      SSD USB-C          9287
      Intel  3.5    6      7200 rpm USB-C     1511
      Intel  3.5    6      5400 rpm USB-C     1090
      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.

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

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 same dialog. Press again for the next 
   occurrence. The keyboard 'F' key also opens the search dialog.

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

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

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

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

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

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

GALLERY VIEW
   All image files in the current folder are shown as thumbnails. This may be hundreds or thousands of images. 
   You can scroll through the thumbnails and navigate to other folders. Use the vertical scroll bar to scroll 
   up and down within a gallery. The keyboard keys can also be used: the arrow up/down keys scroll rows, the 
   page up/down keys scroll pages, and the home and end keys jump to the beginning (top) and end (bottom) of 
   the gallery. You can also scroll the gallery up/down with the mouse wheel. Use the \>ZOOM\> menu button or 
   the keyboard [+] and [–] keys to change the thumbnail size. Clicking on a thumbnail will change to File 
   View and display the image full size. This image is now the "current image". Pressing the F3 key or the
   'gallery' menu button will return to Gallery View, with the current image scrolled to the top row. The 
   folder path is shown at the top of the gallery window, with one button per folder level. Click on a folder 
   button to 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 its 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 service. Initially a world map is displayed. Use the 
   mouse wheel to zoom-in/out at any location. Left/right mouse clicks also zoom in and out. Shift the map 
   center using mouse drag. The entire world can be viewed at any scale down to street-level.

   File maps are locally stored data files containing map images. A set of maps for the world, all continents, 
   and many countries can be downloaded and installed using the Download Maps menu. Use the Choose Map menu to 
   select a map file. A left click on any map area will expand that area to a much larger size, and a right 
   click will return to the whole map view. The mouse wheel also works. Markers are shown where there are any
   images with geotags. Clicking a marker shows a Gallery View of corresponding images.

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

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

EDIT PROCEDURES
   The image in File View mode (the current image) can be modified with the edit functions in the menus Edit, 
   Repair, Refine, Effects, Warp and Combine. These functions modify the current image in memory and in the 
   window. You can use these functions in any order, and edits are accumulated. When finished editing, use 
   the [Save] menu (button) 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, buttons,
   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 computer. 

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

EDIT WORKFLOW
   You can speed the editing of multiple photos/images if you understand the following:
      • Choosing a new edit function automatically completes an active edit. 
        The new edit starts with the result of the prior edit, and an undo/redo position is created.
      • Opening a new image file during an edit function will automatically cancel the edit. 
        The edit function is restarted with the new image.
      • The [Save] button can be used during an active edit to save the current image status (replace, new
        version, or new file). The edit function restarts, and an undo/redo position is created.
      • Some frequently used functions have a [Prev] button to recall previous settings, making it easier to 
        process multiple photos needing similar adjustments.

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

   \bSimple Workflow
   Most of the time you can just edit the JPEG file that comes out of the camera. Use the following more 
   complex procedure only if you see "color bands" or "posterization" after editing the image, an indication
   that JPEG 8-bit color is limiting the visible image quality.

   \bComplex Workflow
   To edit with deep color (more than 8 bits), you can start with RAW files from your camera. 
   There are two options for processing RAW files:
      • Click the RAW file gallery thumbnail. The RAW file may now be edited like any other image file. 
        Fotoxx edit functions work with 24 bits per 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 image as TIFF or PNG is also slower than JPEG.
      • Use the menu Batch > Batch RAW. You can select many RAW files and convert all of them to type TIFF 
        or PNG with 8- or 16-bit color, or JPEG with 8-bit color. You may then select and edit these files 
        as needed with Fotoxx.
   Fotoxx can do all the things you can also do with a RAW editor. The key is to start with the RAW file or
   a derived file with 16-bit color depth, so that nothing is lost. When you open a RAW file in Fotoxx, the
   chosen RAW loader (see \>SETTINGS\>) is used with default settings. 

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

MOUSE OWNERSHIP
   Some edit dialogs use the mouse to reference or alter the image in the main window. There may be more than 
   one such dialog active at the same time. The mouse is also used to zoom and scroll the image, and you may 
   need to do this while using an edit dialog. Therefore it is important to understand who owns the mouse 
   (which dialog or main window) and how to change the ownership:
      • For dialogs using the mouse on the image (to paint, select color, select area ...), the mouse is owned 
        by the dialog that was last used and now retains KB focus. Mouse actions on the image are inputs to 
        this dialog and DO NOT zoom or scroll the image.
      • If you hold the CTRL key down while clicking or dragging the mouse on the image, the image will zoom 
        or pan/scroll. Active dialogs are not affected.
      • The mouse wheel can always be used to zoom-in/out any part of the image as long as the mouse is on the 
        image and not on a dialog widget (which may be modified by the mouse wheel). 

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

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

KEYBOARD ENTER KEY
   Many applications handle this key as 'done', meaning that input is complete and the function can be 
   executed. Fotoxx does NOT follow this convention.
   The Enter key action depends on which dialog widget 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 clicking the button.

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

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

CURVE EDITING
   +image: retouch.png
   Some image edit functions use editable curves. You can manipulate the curves to change some property of 
   the image depending on some other property. The example here shows a 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
      • Rescale files (e.g. reduce for web upload or e-mail)
      • Copy or move files to another location
      • Convert RAW files to tiff, png, or jpeg
      • Add/change/remove image tags or geotags
      • Report or revise metadata items
      • Set image dates/times or shift times to change the time zone
      • Delete files or move them to Trash
      • Script Files: perform multiple edits on one image, save as a script file
        which can then be applied to any number of image files in batch mode.
      • Find duplicate image files.

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

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

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

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

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

MENU SHORTCUTS
   Fotoxx menus are large. You may need time to get used to them and remember where functions are located. 
   There are three shortcut methods for frequently used functions:
      • Right-click the main window or gallery window thumbnail.
        A popup menu appears with some commonly used menu functions.
      • Keyboard shortcuts - these are documented below. 
        You can change the shortcut keys and add shortcuts for functions you choose.
      • Custom menu - collect frequently used functions in one menu. See \>CUSTOM MENU\>.

COLLECTION MANAGEMENT
   You can use Fotoxx to manage a huge image collection and still be able to quickly find wanted images.
   Some effort to organize your images is required. Search methods include folder and file names or partial 
   names, photo dates, file dates, image ratings, tags (labels for persons, places, objects, events ...),
   words in title and description, and geotags (location names and latitude/longitude). Any available image
   metadata can be used for image searching. Options for how to organize a large 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
      • Rescale - Rescale the image pixel width and height
      • Sharpen - Sharpen a blurred image, multiple methods
      • Blur - Blur the image, multiple methods
      • Denoise - Filter noise from low-light photos
      • Voodoo 1 / Voodoo 2 - Limited automatic image enhancement methods
      • Edit Dist - Edit the brightness distribution (histogram shape)
      • Flatten 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

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

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

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

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

NUMERIC KEYPAD
   +image: number-keys.png
   The numeric keypad can be used for navigation with or without 'num-lock' 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 - see \>SETTINGS\>)
      • mouse + Ctrl key - Mouse acts on main window instead of active dialog

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

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

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

COMMAND PARAMETERS
   The following parameters can be used if Fotoxx is started 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 = 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 (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:
      2866x1917x8       current image width x height x depth (bits per color)
      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
      working 45%       some long-running functions show this progress indicator

   \bBit Depth\b
   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.


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

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

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

RENAME
   +image: rename.png
   Rename the current file (File View), or the file of a clicked thumbnail (Gallery View). Enter a new name 
   and press [apply]. This function can also automate the process of renaming a series of image files using 
   a root name (e.g. an event or place name) and a sequence number. Open the first image file in the series, 
   input a new name, and press the [apply] button. Use the [next] button to move to the next file if wanted. 
   You can use the same name again by pressing the [previous name] button and then add a suffix or sequence 
   number. Press the [add 1] button to increment the sequence number. File version numbers (.vNN) are not 
   copied and are otherwise not affected.

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

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

BLANK IMAGE
   +image: blank-image.png
   Create a blank image with specified pixel dimensions and color. This can be used as a background for 
   cutouts taken from other images (via Select Area) and annotation text (via \>MARKUP\> draw text). Input a 
   file name, choose a background color, and set the desired pixel dimensions. See also \>MASHUP\>.

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

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

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

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

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

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

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

PRINT
   +image: print-setup.png  +image: print-margins.png
   The print menu brings up a standard Page Setup dialog where you can select a printer, a paper size, and
   orientation. After using the [apply] button, another dialog starts for entering paper margins and image 
   scale. The margins can be used to shrink the image or shift it on the page. Image scale can be set in the 
   range 5-100%, where 100% means print the maximum size image that fits within the margins. Smaller values 
   will shrink the image proportionally. The actual print size (image width and height) is updated in the 
   dialog as margins and scale are changed, and this can be used to reach a desired 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, press the [Yes] button or the 'Y' key or the Enter key. To 
   continue Fotoxx, press the [No] button or the 'N' key or Escape. If there are unsaved file changes, or 
   if a long-running function is still running, you are warned and given the chance to cancel or quit anyway.


GALLERY MENU

+image: ug-gallery.png

GALLERY OVERVIEW
   +image: image-management.png
   A gallery of thumbnail images can represent a file folder, the output of an image search 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.png
   Choose the sort key and ascending or descending order. 
   The Reset checkbox resets all galleries to file name ascending.

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

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

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

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

GALLERY SCREEN
   +image: gallery-screen.png
   Select a simple subset of the current gallery and create an album "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 (if 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 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.png
   All top image folders are shown initially. Click on [+] to unfold subfolders, or on [-] to fold them back 
   in. You can click on any folder to get a gallery of the images in that folder. Keep the window open to 
   navigate anywhere in your image collection. This function is also available using the [TOP] button in the 
   gallery top panel.

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

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

ADD SUBFOLDER
   +image: add-subfolder.png
   Add a new subfolder to an existing image folder. Navigate to the 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.png
   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.png
   After starting Edit Bookmarks, click on a gallery thumbnail to add this location to the bookmark list. The 
   assigned bookmark name will initially be the file name corresponding to the thumbnail. This name appears in 
   an edit field where you can assign another name. If you select an existing bookmark with a mouse click, its 
   name is shown in the input field. You can change the name or press [delete] to remove the bookmark. New 
   bookmarks are inserted after the last bookmark location selected.

MANAGE ALBUMS
   +image: manage-albums.png
   An album is an arbitrary sequence of images that is manually assembled from existing images. An album is a 
   list of its member image files. The image files themselves are not copied or changed. A given image file 
   can be a member of multiple albums, or may be present more than once within an album. Albums can be used to 
   group images with some shared attributes, such as photos of a given person taken at different times or 
   events, a "best photos" collection, etc. You can add and remove images in an album or rearrange 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.png
   Replace specified album files with specified replacements, or add specified new files after specified 
   existing files. Select one or more albums to be processed. In gallery view, click on two thumbnails to 
   specify 'old file' and 'new file' in the above dialog. Select the option: 'new file' replaces 'old file' 
   wherever found, or 'new file' is added to 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.png
   This is a utility for some of the mass updates that you may need after creating new versions for many 
   image files and needing to update one or more albums to the new versions. This does not cover every need, 
   which is likely impossible, but my hope is that it will help reduce the need to change one file at a time.

   Select one or more albums and then select one of the processing options:
      • Replace all with newest version only
        All albums are updated to have only the newest file versions.
      • Replace all versions with newest version
        All file versions are replaced with only the newest version.
        The original file, if present, is NOT replaced.
      • Add newest versions to existing versions
        The newest version is added to existing versions, if not already 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: 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. Zoom-in to expand the scale and possibly separate one dot into multiple dots.

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.png
   You can save a map location (map center and zoom level) with a given name, and recall the map location 
   later with one click. To save a map location, navigate 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 < 200 MB. 
   No user inputs are needed. The prior method for doing this, the fotoxx-maps package, is now obsolete for 
   fotoxx-22.30 and later. The downloaded map files are located in <fotoxx home>/file_maps.

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

   File Map Navigation
      • left click: zoom map to full size, right click: reduce 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 list of available maps.

   \bCustom Map Files
   Obtain the map from any suitable source, e.g. Google Maps or Open Street Map. You need to get the map as a 
   JPEG or PNG file. You can use a screen capture function to create the map file. You can use the Mashup tool 
   to stitch many maps together to make a huge map. You can also use a scanner to capture one or more paper 
   maps and accurately stitch them together with Mashup.

   To install a map, put the map file into the folder <fotoxx-home>/file_maps. In this folder you will also 
   find a text file: maps_index. Each map requires a line in this file which specifies the map 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:
       New York City.jpg,  29.479,  30.053, -95.786, -94.905
       France.jpg,         42.074,  51.283,  -5.142,   8.613

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

   If you make a custom map, getting accurate latitude and longitude values for the map edges can be tricky. 
   Use the Open Street Map "export" option to view maps with an overlay rectangle labeled with latitude and 
   longitude. Adjust the rectangle to match a corner of a map you have created and record the latitude and 
   longitude values. You need accurate latitude and longitude data for the upper left and lower right corners 
   of the completed map. The precision should be suitable for the scale of the map. 1 degree of latitude 
   corresponds to about 110 km on the earth's surface. 0.001 degree corresponds to 110 meters.

   If you have added lines to maps_index and you use the function DOWNLOAD MAPS again (to get maps that were 
   added later), the maps_index file 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 last 
   entry in the menu, Edit Menu, opens a text editor for editing the menu list itself. Add or remove the menu 
   names you want, anywhere in the list. The menu names must exactly match the names in the Fotoxx menus, but 
   case is not significant. Custom notes and tips can be added by using the '#' character. Use "-f filename" 
   to open a specified image file to process with a given menu function.

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


ZOOM

   +image: ug-zoom.png

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


FILE SAVE

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

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

   \bNew Version
   Save the current image file with a new version number. File names with version numbers are formatted 
   "filename.vNN.ext" where NN is a number 01 to 99. The 4 characters ".vNN" are inserted between the file 
   name and extension. If the file name has no versions, version .v01 will be created. If file versions are 
   already present on disk, then the next higher version number is used. If the file is a JPEG file, the 
   default quality is used (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 TOPICS\> section 
   describes potential loss of image quality from repeated open, edit and save of JPEG images. At the default
   quality of 90 this issue can be generally ignored.

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

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

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


METADATA MENU

+image: ug-metadata.png

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

   Fotoxx can search your image collection using any metadata, along with folder and file names or partial 
   names, producing a gallery of matching images. In most cases, the search is almost instantaneous. There are 
   several alternatives for organizing a large image collection so that it can be easily searched. It would be 
   good to review these before choosing an organization system for file and folder names and metadata tags,
   titles, ratings, etc. See \>ORGANIZING IMAGES\>.

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

VIEW META
VIEW ALL META
   +image: view-metadata.jpg
   The View Meta functions displays commonly useful metadata for the current image file. This includes the 
   date and time of a photo, shutter speed, focal length, image size, ISO, etc. Digital cameras store this 
   data 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.png
   The Edit Metadata function is used to add basic metadata to an image. Please read Tags Overview and Geotags 
   Overview (above) before using Edit Metadata.

   Edit Metadata is used to edit the most frequently used metadata: image date and time, rating, title, 
   description, location data, and tags. The dialog initially shows data for the current image. After making 
   additions or changes, press [Apply] to update the image file. There is no automatic file versioning for 
   metadata changes, but 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.png
   This is a dialog for editing any metadata for the current image file. The most common keys for editing are 
   listed on the left. Press the [Full List] button to get a list of all available keys for the current image 
   file (there may be hundreds of them). Press [Short List] to go back to the common keys list. Click an item 
   in the list to retrieve the current key value. Change the value if wanted and press [update]. The metadata 
   is updated. To edit a key name not in the list, enter the key name and press [fetch] to retrieve the 
   present value, if any. Then enter or change the value and press [update]. To delete a key, press [delete]. 
   You may enter the key name in lower case and with or without spaces, e.g. "Subject Distance" and 
   "subjectdistance" will both work. Some keys cannot be changed, e.g. 'image width' is the image pixel width, 
   which can only be changed by changing the image size. The source for the short list is the text file 
   "metadata_picklist" in the Fotoxx home folder (/home/<user>/.fotoxx). You can add or remove items from 
   this list 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 metadata by default. Use 
   this function to copy metadata from one of the input images, or any other image. Use the [Browse] buttons 
   to choose a file to source the metadata and a file to receive the metadata ("target file" in the dialog).

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

MANAGE TAGS
   +image: manage-tags.png
   Create tags (keywords) and optionally group them into categories. You can assign categories to tags to help 
   organize them and locate them more quickly when adding tags to images. They are optional and they play no 
   role in tag searching: only the tag is stored in an image, not its category. Typical categories are people, 
   places, things, events, scenery, buildings, art, etc. To add a new tag with a new category, enter the
   category and the tag, then click [create]. If the category is blank, the tag will be assigned to "nocatg". 
   To assign a tag to a different category, click a category (bold text) or enter a new one, click the tag, 
   and press [create]. The tag will move from the old to the new category. To delete a tag, click the tag and 
   press [delete]. Tags used in images but not assigned to a category will appear under "nocatg". A Category 
   with no tags assigned can be deleted - click the category, clear the tag name if present, press [delete].

   Note: a newly created tag is appended to the end of the tag list for its category. The next time Fotoxx is 
   started, all categories and their tag lists are sorted alphabetically, except that "nocatg" is always last.

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

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

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

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

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

AUTOSEARCH
   This function can be used by shell script files to extract image files meeting any of the selection 
   criteria available in the Search Images function (see below). First, use the Search Images function to 
   set 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 user 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 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 images), use "null" in the first date input.

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

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

   Image title and description may be searched. Enter the words to search for in the dialog search text field, 
   separated by blanks. These will be matched to every word in the title and description of all images, and 
   matching images are selected. Case does not matter. Search words may also have wildcards, e.g. 'veni*' 
   matches both 'Venice' and 'Venizia'.

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

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

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

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

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

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

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

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

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

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

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


SELECT MENU

+image: ug-select.png

AREA OVERVIEW
   Edit functions normally apply to the entire image, but it is possible to edit part of an image (an "area") 
   and leave the rest unchanged. If an image area has been selected, then most edit functions will work only 
   within this area. Some functions (e.g. Rescale) ignore a selected area. An area may be selected before 
   starting an edit function, or while an edit function is active. The selected area is immediately active, 
   prior edits are retained, and future edits will apply only within the area. If another edit is started, 
   the selected area remains active, so it is possible to carry out a series of edits on one area.

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

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

   \bMethods
   The following methods are used to enclose one or more image spaces that will belong to the final area. 
   These methods may be used in any sequence to define spaces that are either joined or detached.
      • Rectangle - drag to outline a rectangular area
      • Ellipse  - drag to outline a circular or elliptical area
      • Freehand Draw - outline area by drawing (dragging) with the mouse
      • Follow Edge - outline by following image feature edges
      • Select area within mouse - select all pixels within a circle centered on the mouse pointer. 
        Drag the mouse to extend the selection to areas moved over.
      • Select one color within mouse - works as above, but selects only pixels matching
        a given color within a given match level (0-100%). 
      • Select all colors within mouse (flood) - select all pixels within the mouse, and extend the 
        selection into adjacent areas with colors matching the colors within the mouse circle 
        (this is called 'flood' in some image editors). 

   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 a position slightly behind the mouse.
   For very irregular edges (hair, foliage), see Select/Deselect below.

   \bMouse Radius and Color Match Level
   These two controls apply only to the 'select within mouse' methods described below. Mouse radius defines 
   the size of a circle around the mouse pointer. Pixels within the circle are selected, or they provide a 
   set of colors for matching and selecting pixels. Match level defines a required match level (0-100%) to 
   select pixels based on their color and brightness. 0 means anything matches, and 100 means a perfect match 
   is required.

   \bSelect area within mouse
   Left click or drag will select the pixels enclosed by the mouse circle. A right click will unselect the 
   last selection (repeat to unselect more). A right drag will unselect the enclosed pixels.

   \bSelect one color within mouse
   Click on the image to select a color. The color is shown on the color button. You can also use the button 
   to set a color directly. Left/right drag to select/unselect pixels within the mouse circle that match the 
   selected color within the match level. Adjust the match level down/up to match a greater/lesser range of 
   colors. Click as needed on the image to change the color to be matched.
   
   \bOptional deselect color
   This applies only to 'select one color' above. Shift + click on the image to set a deselect color. When 
   the box is checked, the deselect color is active. If a pixel matches the deselect color better than the 
   select color, the pixel is unselected. When selecting along a feature edge with a low color contrast 
   compared to an adjacent area that should remain unselected, set the deselect color from the adjacent area. 
   This is helpful for accurate selection of a complex edge, like hair or foliage.

   \bSelect all colors within mouse\b (flood)
   This is called 'flood' in some editors. Left/right drag to select/unselect pixels inside the mouse circle. 
   Pixels beyond the mouse circle are also included if they meet these two conditions: 1) their color matches 
   any color inside the mouse circle, within the current match level. 2) they are within the search range of 
   the mouse pointer. This is a factor of mouse radius, e.g. if mouse radius is 20 and search range is 3, then 
   the search range is 60 pixels from the mouse pointer. Drag the mouse over new areas you want to include. 
   Watch the selected area expand into areas with colors matching those inside the mouse circle. If you go too 
   far, right click to remove the last selection. Repeat if needed to remove more previous selections. Reduce 
   the radius or increase the match level to gain finer control - the selection will expand more slowly and 
   stay closer to the mouse circle. A small radius and high match level can be used to follow along an image 
   feature edge and select pixels up to the edge with good precision. Change to a larger radius and/or lower 
   match level to select larger areas after the fine work is complete, or use the select area within mouse 
   method as described above. Right drag acts as an unselect: pixels inside the mouse circle and matching 
   pixels within the search range are unselected. If a selection goes too far, it is often easier to correct 
   this by unselecting from outside the selected area instead of selecting from inside the selected area. 
   You may need some practice to get a feeling for this and be able to work efficiently.

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

   \bEdge creep
   An area that has been finished (see below) can be expanded or contracted in 1-pixel steps. This can be 
   helpful to reduce edge effects when an area selected by matching colors is edited in a way that changes its 
   brightness. Selection by color may leave a narrow band of underselected or overselected pixels along an 
   edge where feature color transitions to background. Expanding or contracting the area 1-2 pixels can 
   produce a cleaner looking edge. The area remains finished after creep.

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

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

   \bFinish
   +image: select-area-finish.png
   An area is not effective for edits until it is successfully finished. Finish validates drawn outlines and 
   colors the enclosed pixels for visual 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 the 'select within mouse' methods are automatically finished. These areas are mapped 
   during the selection process, whereas areas selected with rectangle, ellipse, or one of the line-drawing 
   methods are mapped only when you click inside them. If you use only the 'select in mouse' methods, you can 
   cancel the finish dialog without clicking any of the selected areas.

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

   \bClear
   Discard the current area permanently.

FIND AREA GAP
   If an area outline was created by freehand drawing using multiple strokes, it is easy to leave small gaps 
   in the outline that are not visible below 4x zoom. An attempt to finish such an area will fail because the 
   mapping of the interior pixels will leak out through the gap and cover areas outside the intended area. If 
   the Finish function fails, 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).

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

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

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

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

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

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

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

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

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

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


UNDO/REDO BUTTON

+image: ug-undo-redo.png

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

   If no edit function is active, but some edits were made to the current image:
      • left mouse click will undo one edit step per click
      • right mouse click will redo one edit step per click
      • if combined with the A-key, undo/redo ALL edits (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.png
   To level a slanted image, use the mouse to drag the right or left side of the image up or down until image 
   looks level. A left-click on the image will add vertical and horizontal guide lines to help with image 
   leveling. Use right-click to remove them.
   
   Use the 90º and 180º buttons to upright an image made with the camera turned. The input widget can be used 
   to enter any angle - this spin button responds to the mouse wheel and the up/down arrow keys.
   
   The mirror buttons flips the image left-right or up-down. Photos will never be inverted in this manner, 
   but the user can do this if wanted.

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

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

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

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

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

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

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

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

RETOUCH
   +image: retouch.png
   Adjust image brightness and color.
      • auto black level - set black point using % darkest RGB values found
      • auto white balance - set white point using % brightest RGB values found
      • click gray spot for white balance - press button, click gray spot 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.

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

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

MARKUP
   +image: markup.jpg
   This is a menu containing the image markup functions:
      draw text, draw line/arrow, draw box, draw oval
   These are described immediately below. All of these functions have an [apply] button which commits the 
   current edit and lets you begin a new one (new text, line, box, oval) within the same edit dialog. Press 
   [done] to commit the last edit and close the dialog. The logical next step would be to save as new 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 faintly readable. Use the emboss controls to make the text appear to be recessed into the image.

   +image: draw-line.png
   This function draws lines or arrows directly on the image. Enter a line length and width into the dialog, 
   and select an arrow head if wanted. Left-click the mouse where you want to place it on the image. Drag the 
   ends of the line/arrow to position it on the image. Right click to remove it. Drag from the middle of the 
   line to move without changing the angle or length. The dialog controls allow you to provide a background
   color, an outline color, and a shadow effect. You can select color and transparency for all of these. The 
   width control adjusts the width of outlines and shadows. The shadow angle control sets the slant angle of 
   the shadow. To keep a drawn line and begin another one, press [apply].

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

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

COLOR MODE
   +image: color-mode.png  +image: color-mode2.png
   Use this function to make a black and white or color negative, or convert a negative image into a positive 
   image, or convert to sepia coloring (for an aged photo effect).

   Select one of the buttons:
      • reset - return the image to the original state
      • black/white positive - convert a color image to black and white
      • black/white negative - convert to black and white and invert brightness
      • color negative - replace each RGB color with its compliment
      • RGB -> GBR - red/green/blue colors are replaced with green/blue/red 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 (like spray painting from a distance). 
   Erase also works this way: use 100% opacity to erase rapidly, and a low value to erase gradually.

   NOTE: zoom the image to 100% or more when using a small brush. If the mouse steps are larger than the image 
   pixels and a small brush is being used, some pixels may be skipped by the mouse and cannot be painted.

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

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

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

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

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

PAINT EDITS
   +image: paint-edits.png
   Use this function in combination with some other edit function. Start an edit function and leave the 
   controls in a neutral position. Then start Paint Edits. Specify a mouse radius and power factors for the 
   mouse center and radius edge. The mouse pointer will be surrounded by a circle with the specified radius. 
   When the mouse is left-dragged over an area of the image, the current edit function is applied within the 
   circle. The strength of the function is regulated by the center and edge power factors. Usually you will 
   use a high value at the center and zero at the edge, meaning that the strength of the edit will be maximum 
   at the center, changing gradually to zero at the edge of the circle. As you drag the mouse over the same 
   area repeatedly, the edits are slowly accumulated. For example, if the edit function is Retouch, and 
   brightness is increased, then the image will brighten within the mouse area as the mouse is dragged.

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

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

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

   See the following functions for alternative methods to perform localized edits:
   \>SELECT AREA\> - perform edits confined within a pre-selected image area.
   \>STACK/VERSIONS\> - 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.png  +image: paint-transp2.png
   Paint transparent or semi-transparent areas on an image. Such areas are useful in the Fotoxx Mashup 
   function, where images or background underneath a transparent area can show through. Other image editors 
   can also use transparent areas.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


REPAIR MENU

+image: ug-repair.png

SHARPEN
   +image: sharpen.png

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

   \bSharpen - General Blur
   Choose the method, set the parameters, press [apply] and wait a few seconds to see the result. Make changes 
   and repeat the process until satisfied. You can go back and forth among the methods to compare which is 
   best for a given image. Use \>SELECT AREA\> to operate on different parts of an image with different 
   methods and parameters.

   For all methods, choose a small radius for images that are slightly blured and a larger values for poorer 
   images. Amount controls the strength of the modification. Threshold suppresses changes to low-contrast 
   pixels: a higher values reduces the amplification of low-level irregularities (image noise, uneven skin 
   tones, etc.).

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

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

   Kuwahara: small neighborhoods of pixels above, below, left and right of each pixel are compared to 
   each-other. The pixel is given the mean color of the neighborhood with the smallest difference in 
   brightness. This forces pixels on a blurry edge to move to one side of the edge or the other. Edges are 
   made very sharp. Image may appear 'blocky' if a large radius is used. Subtle details can be lost.

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

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

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

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

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

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

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

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

   \bGraduated Blur
   Only pixels with less contrast than the given contrast limit are blurred, and the blur radius ranges from 
   1 to the given value for pixels with a corresponding contrast ranging from the given limit to zero. 
   In short: low-contrast pixels are blurred more than high-contrast pixels. This can be used to smooth skin 
   tones without blurring hair or reducing the sparkle in the eyes. Taken to extremes, it produces a "cartoon" 
   effect.

   \bBackground Blur
   Blur background image areas while leaving the foreground sharp. Select one or more areas that are to remain 
   sharp (menu Areas > Select). After selecting the foreground areas, invert the selection so that the 
   background is now selected (Areas > Invert). This is the area that will be blurred. There are two blur 
   methods available: Constant blur: a constant blur radius is used for all areas blurred. Increase blur with 
   distance: use the minimum blur radius for pixels adjacent to the foreground and the maximum blur radius for 
   pixels at the maximum distance from the foreground. This requires that the edge distance for all background 
   pixels be calculated, which can take significant time for a large image. Blur radius can be varied without 
   recalculating 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.png
   This tool adds motion blur to an image. Motion blur is blur in a single direction. Image feature edges 
   perpendicular to this direction have maximum blur. Those parallel to the blur direction remain sharp. 
   Use \>SELECT AREA\> to isolate image areas to blur separately from the unchanged background.

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

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

   The dark areas slider can be used to restrict the process to darker image areas, which are most prone to 
   noise. If left at the right end, all areas are processed.
   
   The flat areas slider can be used to restrict the process to flatter image areas, i.e. areas with low 
   brightness/color variation. These are the areas where noise is most visible. This also helps to preserve 
   fine detail. 

   Here is a short technical description of each method:
      • Voodoo
        This is a fixed combination of the other methods to serve as a "one button" method. 
        Try this first. It 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 pairs. 
        Threshold is not used.

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

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

RED EYES
   +image: red-eyes1.png  +image: red-eyes2.png
   This function reduces the red-eye effect from electronic flash photos. Two methods are provided. The first 
   is faster but may not handle difficult cases. The second method is more robust but also needs more time and 
   care. To use the first function, left-click on a red-eye one or more times until satisfied. If the darkened 
   area is too small or off-center, do a right-click to undo the change and then left-click more precisely on
   the center of the red-eye. If a red-eye cannot be fixed correctly, right-click to undo the change and then 
   use the second method. The second method can better handle more difficult cases where the red-eye is only 
   slightly red and the color difference with the eyelids is too little for the automatic algorithm to 
   distinguish. Place the cursor over the center of the red eye. Hold the left mouse button and drag the 
   cursor down and to the right. A dotted ellipse will appear enclosing the red eye. Repeat if needed to get 
   the red eye centered in the ellipse (roughly). Note that the shape of the ellipse depends on the direction 
   of the drag, which can allow more precise enclosure of only the red-eye. Left-click inside the ellipse 
   repeatedly while watching the red eye darken, and stop when it is dark enough. If you go too far, the 
   eyelids may start to darken. Right-click to undo and repeat if necessary.

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

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

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

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

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

ADJUST RGB
   +image: adjust-RGB.png
   This function is used to change overall brightness and contrast, or that of selected colors. The settings 
   are retained within and across Fotoxx sessions, so this function can be used to process multiple photos 
   made under the same lighting conditions and needing the same (or nearly same) adjustments. Use the [reset] 
   button to restore all inputs to neutral values.
      • Brightness
        Increase or decrease overall image brightness
      • +Red -Cyan  etc.
        Increase or decrease the brightness of one color and change the complimentary color 
        in the opposite direction
      • Contrast All
        Increase or decrease the overall image contrast
      • Contrast Red, Green, Blue
        Increase or decrease the contrast of individual RGB colors

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

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

   The Output Color controls (hue, saturation, lightness) are used to set the new output color which will 
   replace or blend with the selected input colors. You can also set this color from the image, using 
   shift + right-click. The resulting color will be a mix of the original color and the new color. The new 
   color fraction is set by the Adjustment slider, which can be set 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 can be used with \>SELECT AREA\> to restrict the change to selected image areas.

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

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

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

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

   The left image above is a magnified cutout of the top left corner of a photo with lateral chromatic 
   aberration. This was mostly eliminated in the processed image to the right. Color fringes can appear along 
   high-contrast edges, especially in the outer image areas where lens distortions are usually greatest. To 
   get rid of them, zoom the image to a maximum size and center on an area with color fringes. Press the 
   [search] button. The red and blue color planes are shifted to better align with the green plane, and the 
   factors used are stuffed into the dialog box. You may be able to improve the result by revising the factors 
   directly in the dialog: use the up/down arrow keys or mouse wheel to change the factors while watching the 
   color fringes on the image. Modify the largest values (2.4 and 3 in the above example).

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

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

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

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

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


REFINE MENU

+image: ug-refine.png

VOODOO 1
   This is a fast automatic image enhancement with limited capability. This is sometimes effective and 
   "good enough" for rapidly processing many photos. There is no dialog - the modification is simply done 
   when the menu is selected. Reject the change with the [undo] button if desired. The modification consists 
   of a slight flattening of the brightness distribution, an expansion of the brightness range if less than 
   the full range is used, and a slight increase in the color saturation, more for darker areas of the image 
   than brighter areas. The effect is sometimes minimal or even negative.

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

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

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

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

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

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

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

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

GRADIENTS
   +image: gradients.png   +image: gradients2.jpg
   Gradients increases the apparent brightness range of an image by increasing local contrast. It is 
   especially useful to improve HDR images, but can also be applied to any image. Gradients increases the 
   contrast between nearby pixels without increasing the overall contrast. It relies on a characteristic of 
   human vision: contrast within a small angle is perceived more strongly than contrast over a large angle. 
   Gradients can bring out subtle details (low contrast) that would otherwise be hard to notice. Other methods 
   can also be used: \>RETOUCH\> can increase contrast for a selected brightness range (at the expense of 
   others). \>FLATTEN DIST\> can spread available contrast more evenly. Gradients processes pixels relative 
   to nearby surrounding pixels, and is very effective at enhancing detail and the perceived brightness range.

   In the dialog, the graphic curve determines how much local contrast is increased depending on initial local 
   contrast. The left end corresponds to low-contrast pixels and the right end corresponds to high-contrast 
   pixels. Raise the left side of the curve to increase the contrast of low-contrast pixels (but this will 
   also increase low-level noise). The Amplify slider below the curve regulates the calculation, from no 
   contrast amplification on the left to full amplification on the right. If moved too far to the right, the 
   image may show ugly artifacts, so push it back until these disappear. The curve can be dragged with the 
   mouse and its effect on the image will show up in a second or so (depending on image size and CPU speed). 
   The Amplify slider may also need time to show up in the image. If more contrast is wanted, raise the curve. 
   If uniform areas (e.g. sky) become mottled, pull the left end of the curve down to reduce amplification for 
   low-contrast pixels. In some cases it will be best to select different areas of the image and process them 
   separately, e.g. conservative for sky, more aggressive for textured surfaces like stone walls.

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

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

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

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

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

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

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

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

   Procedure: The dialog lists 5 steps to take in sequence.
      1  Set a radius for the spot sample.
         The resulting mouse circle is the spot area that will be sampled.
      2  Open the 1st image (press the [open] button for a file open dialog).
         If the current image is already the one you want, this 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,
         and the colors will change accordingly. Click the dialog [done] or [cancel] button to finish.

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

VIGNETTE
   +image: vignette.png +image: vignette2.png
   This function is used to correct the darkening sometimes seen in the corners of a photo. It can also be 
   used to highlight or colorize an object or area within an image.

   Click or drag the mouse on the image to change the vignette center, which is initially at the center of 
   the image.

   Select 'Brightness' to change the brightness of the image in a radial pattern: Adjust the left or right
   end of the curve to change the brightness of the center and edges of the image respectively. You can give 
   a dark surround to a portrait face, or you can fix an image with darkened corners. The curve middle level 
   corresponds to no change. Use lower values to darken and higher values to brighten. The example above 
   gradually darkens the periphery of the image while leaving a broad central area unchanged.

   Select 'Color' to add a chosen color to the image in a radial pattern. Curve values of zero represent no 
   change, and higher values add the chosen color to the image. The highest value corresponds to 100% color. 
   Use this function to add a color surround to an image, e.g. surround a face with a gradually increasing 
   color.

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


EFFECTS MENU

+image: ug-effects.png

SKETCH
   +image: sketch.jpg
   This function transforms a photo into something like a sketch. Dark pixels are aggregated into fewer 
   pixels, leaving vacated areas brighter. Contrast can also be used as a proxy for dark pixels. Threshold 
   can be used to filter the input image by brightness. Clip Level is used to filter the output to further 
   reduce isolated or marginally dark pixels. Choose colors for foreground and background. Two algorithms
   are provided. Results may look more interesting with one or the other. Reducing the size of the input 
   image may also give more interesting results.

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

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

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

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

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

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

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

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

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

   \btile area goal
   The upper limit of tile size (area in pixels). 
   
   \breq. color match
   Set the minimum color match required for a smaller area to be consolidated into an adjacent larger area: 
   0 = don't care (maximum consolidation), 100 = perfect match required (minimum consolidation).

PAINTING
   +image: painting1.png  +image: painting2.png
   This function transform an image into something similar to a painting. It reduces the number of colors, 
   maps each contiguous pixel area having the same color, and then consolidates smaller areas into adjacent 
   larger areas having the best color match.
   
   \bblur radius
   Blur the image before processing. This results in smoother boundaries between colors.

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

   \bpatch area goal
   Set a lower limit for areas that will have their own color: areas smaller than this number of pixels will 
   be absorbed into an adjacent area with the nearest color match.

   \brequired color match
   Set the minimum color match required for a smaller area to be consolidated into an adjacent larger area: 
   0 = don't care (maximum consolidation), 100 = perfect match required (minimum consolidation).

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

TEXTURE
   +image: texture2.png    +image: texture.png
   This function adds a textured surface to an image or selected areas within an image. Radius determines the 
   texture pattern size. Strength determines the intensity of the pattern, from almost invisible to dominant.

PATTERN
   +image: pattern2.jpg    +image: pattern1.png
   Add a background pattern to an image. A small image file (pattern file) is used to cover the current image 
   by duplicating the file, like a tiled wall. This file can be a real pattern (e.g. an image of canvas cloth, 
   a brick wall, a repeating geometry ...), or any other kind of image. The pattern is made semi-transparent, 
   so that the base image appears to be printed over the pattern, or the pattern over the image. Many pattern 
   files can be found using a web search for "pattern image". Download some of these and crop them if needed 
   to a size around 200-500 pixels. For convenience, add these to the supplied pattern files in 
   <fotoxx-home>/patterns.

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

   If the pattern file contains an image that repeats at fixed intervals both horizontally and vertically, the 
   [Calculate] button can be used to set width and height to match. The result will be a continuous pattern 
   without any edge effects.

   If the pattern is irregular and edge effects appear where the duplicated patterns are joined, you may be 
   able to improve this. The two Overlap values determine how much the duplicated patterns overlap at the 
   edges, horizontally and vertically. Add some overlap to mask edge effects.

   Select Area can be used to apply a pattern to part of an image, or different patterns to different parts. 
   After applying a pattern to an image, it might be interesting to use Emboss or Gradients to add a 3-D 
   effect to the pattern.

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

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

DITHER
   +image: dither1.png  +image: dither2.png
   +image: dither3.jpg
   This function provides several ways to dither an image - convert into dots.
      • dither 0 - colored round dots in the style of Roy Lichtenstein
      • dither 1 - pure bright RGB dots with optimized distribution
      • dither 1 - black/white dots with optimized distribution
      • dither 2 - classic dither using all RGB colors within 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.

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

MOSAIC
   +image: mosaic2.jpg  +image: mosaic1.png
   Create a mosaic image using tiles made from all your images.

   Specify the tile size in pixels (e.g. 36 x 24) and press [Tiles]. Tiles will be created from all of your 
   images (actually the thumbnail images are used since their small size makes the process run much faster). 
   This needs time (100K/min. on a strong computer). If you change the tile dimensions, press [Tiles] again 
   to regenerate the tiles. After the tiles are created, press [Image] to convert the current image into a 
   mosaic using these tiles. This takes only a few seconds. Tiles are chosen by matching the average tile 
   color to the average image color at the tile position. If thousands of images are available and if the 
   range of colors is good enough, the mosaic will turn out quite good. Zoom-in on any part of the image to 
   see the tile images.

   The Tile blending slider will cause the image to be blended with the tiles, making it look better if the 
   tiles are a bad color match. If the blending is less than about 50%, the tiles remain almost as clear as 
   before (the eye compensates the false tint).

   After a mosaic is created, you can click on any tile to get a larger popup image. This is the full image 
   for the tile, so you can drag the window as large as you like and it will remain sharp. A mosaic image can 
   be saved like any other edited image, but if a saved mosaic is opened, clicking the tiles for a bigger 
   image will not work. Regenerating the mosaic is quite fast, so do this if you want the popups to work.

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

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

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

SHIFT COLORS
   +image: shift-colors.png
   This function can be used to correct colors or convert an image into false colors. Choose any of the 
   three RGB colors and move the slider left or right from the center. One of the two other colors will be 
   substituted in a graduated manner. For example, you can gradually substitute green or blue for the color 
   red. The All slider shifts all colors together. Do this first to find a first optimum, then shift the RGB 
   colors individually.

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

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

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

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


WARP MENU

+image: ug-warp.png

UNBEND
   +image: unbend1.png  +image: unbend2.png
   Panoramas of nearby subjects (typically buildings or interior rooms) may show straight lines that are 
   curved, or buildings that are slanted. Warping the images was necessary in the panorama process in order 
   for the images to fit together. The Unbend function can be used afterwards to straighten the panorama image 
   if needed. Vertical and horizontal dotted lines are drawn over the image, showing the unbend axes. Click or
   drag the mouse near the end of a line to move it. If values in the four input controls are changed, the 
   image is warped in the manner indicated by the corresponding four images. Increase or decrease the values 
   and repeat until satisfied. Move the axes to change the centers of warping.

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

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

   Click on the four corners of the tetrahedron that you want to make into a rectangle (in the above case, 
   the four corners of the painting or frame), then select [Apply]. Use [Reset] to go back and try again if 
   needed. The clicked corners are marked with small white boxes containing "A, B, C, D". The upper left 
   corner of each box precisely marks the image position. Clicking near a box will move it to the new position.
   The [Crop] button will automatically crop the image at the selected corners. The crop and straighten can 
   be undone in sequence with the undo button. You can use the keyboard arrow keys to move the corner markers 
   in 1-pixel steps. The arrow keys work on the last corner clicked or moved.

WARP IMAGE
   +image: warps4.jpg

WARP AREA
   This function can be used to make distortions within an image. You can select an image area and drag the 
   mouse to stretch this area with respect to the rest of the image. The image is like rubber. If the mouse 
   drag begins within the selected area, then the area is warped within its current boundaries - the movement 
   is maximum at the mouse pointer and declines to zero at the edges of the selected area. If the mouse drag
   begins outside the selected area, the area edges near the mouse can be pulled out beyond the original area 
   boundary. Many mouse drags of different lengths and directions can be combined to achieve the desired 
   results. When finished, you can select another area and do some more warping, or select [done] to exit the 
   function.

WARP CURVED
   This function is useful to correct perspective problems (see also Unbend). Drag the image from any 
   position, using the mouse. The entire image will be pulled or pushed in the direction of the mouse, but 
   areas near the mouse are moved more than more distant areas. You can straighten curved lines or 
   deliberately curve the image. The control warp span determines the radius of warping around the mouse. 
   1.0 means the full image is warped, and smaller values confine the warp to smaller areas around the mouse.

WARP LINEAR
   This function is useful to correct perspective problems (see also Unbend). Drag the image from any
   position, using the mouse. This function works over a broader area than the curved warp and causes less 
   image curvature. To minimize the addition of curvature, drag only from the image corners.

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

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

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

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

MAKE WAVES
   +image: make-waves2.jpg +image: make-waves1.png
   This function distorts an image into a wave pattern, as if viewed through turbulent water. The dialog 
   allows you to change the mean horizontal and vertical wavelengh, amplitude and variance. The "perspective" 
   input allows the wavelengths to gradually lengthen from top to bottom. Like most edit functions, this 
   function also works within a selected area. The flood above is fake.

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

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

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

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

TINY PLANET
   +image: tiny-planet.jpg
   Wrap an image around a circle.
   If the image is a 360 degree panorama, there will be no visible seam.
      • Center Hole: the image is wrapped around a central hole. 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.png
   Transform an image into an endless inward spiral like the famous clock of M.C.Escher. Width determines the 
   starting width of the outermost layer. Rim determines the starting width of the border separating layers, 
   and Color determines its color. The default center is the center of the image. Click on the image to set a 
   new center.

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

   Procedure: Click the mouse along the top edge, creating a visible marker dot at each clicked point. After 
   4 points are available, a curved line is drawn through the points. Add more points and drag the points as 
   needed to make the line conform closely to the curved edge. Repeat for the bottom edge. Press [flatten] to 
   flatten the page. The edges should now be straight (or straight enough). Use the [stretch] slider to 
   stretch the sides of the image as needed, to compensate for the lateral compression caused by the 
   curvature. Use the Widen control to widen the image as needed to restore the correct width/height ratio. 
   The [undo] button restores the unmodified image, keeping the marker dots, which can then be adjusted for a 
   revised attempt. The [clear] button deletes the marker dots.

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


COMBINE MENU

+image: ug-combine.png

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

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

   Select the HDR menu function and select up to 9 images (\>SELECT IMAGE FILES\>), which must all have nearly 
   the same pixel dimensions. The images are aligned and combined automatically. This needs 10-30 seconds per 
   image, depending on image size and CPU speed. When done, the combined image is shown, along with a dialog 
   for adjustments. The contributions from the input images are shown as a series of editable curves. The 
   horizontal scale represents pixel brightness, from dark to bright. Each curve represents an image which 
   contributes to the pixels. The image contribution at a given brightness level is proportional to the height 
   of its curve at that level. The initial curve for the brightest image will be high on the left and low on 
   the right, meaning 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.png
   Combine (overlay) multiple photos of the same subject with different focus settings from close to distant. 
   Different parts of the subject are in sharp focus in each image. Combine the images so that all parts of 
   the subject are sharp. This technique is most useful for extreme close-ups.

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

   +image: HDF-paint.png
   Processing the photos: in Fotoxx, choose the HDF menu function and select up to 9 images 
   (\>SELECT IMAGE FILES\>). The images will now be aligned as well as possible. This needs 10-30 seconds per 
   image, depending on image size and CPU speed. The output image is an even mix of the aligned input images. 
   A small amount of camera movement between the photos is compensated, but this is limited, and parallax 
   shifts are not compensated at all. When the alignment is complete, a dialog opens. You can select any input 
   image and "paint" it with the mouse on any area of the output image. This converts the original image mix 
   to the single selected image for the area being painted. For each area or object in the image, choose an 
   input image that is sharp in that area. The radius of the paintbrush can set larger or smaller, so you can 
   paint large areas quickly and control fine detail when needed. If you have overlapping near and far 
   objects, time and patience will be needed to make all of them sharp. Misalignments can be corrected by 
   selecting the warp option in the dialog. The underlying images can then be dragged and warped with the 
   mouse, and the combined output image is changed accordingly. The warp is limited to the area around the 
   mouse. When a painted area is dragged, the corresponding image is automatically selected and dragged, while 
   areas painted with other images remain fixed. Areas that have not been painted cannot be dragged. Move 
   around to different areas and make incremental drags until all 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.png
   +image: stack-paint2.jpg
   Stack (overlay) multiple photos of the same subject taken at different times. 
   Remove tourists and cars that come and go between shots.

   Making the photos: Aim the camera at the same distant point and take multiple photos as tourists or cars 
   move in front of the subject. Try to get two or more photos for each area of the subject not obstructed by 
   the transient objects. Hold the camera steady and aim at the same point, so that the images will align 
   accurately.

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

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

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

   Making the photos: Choose a point for the center of the image. Take several photos using the same center 
   and being careful not to shift or rotate the camera too much. The more photos the better. Up to nine can 
   be used with Fotoxx, but you can take more in order to have some to discard if they are not sharp, a common 
   problem with low light conditions and long exposure times.

   Processing the photos: In Fotoxx, chose the Stack/Noise function and select up to 9 images 
   (\>SELECT IMAGE FILES\>). They will be combined automatically and shown, and a dialog will open. The 
   initial output image is a combination of all the selected input images, averaged together. This means that 
   the RGB values for each output pixel are the average of RGB values for the corresponding input pixels. The 
   following alternatives can be used to possibly reduce the remaining noise a little more. The use median 
   button will change the output pixels from an average of the input pixels to the median of the input pixels 
   (1-3 middle RGB values are averaged, depending on the number of images). This may or may not be better, so 
   switch back and forth to compare (the screen update may need several seconds). The checkboxes for omit low 
   pixel and omit high pixel will cause the lowest and highest RGB input values to be discarded before 
   averaging. This may get noise spikes removed from the mix. This has no effect if the median method is
   selected.

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

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

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

IMAGE DIFFS
   +image: image-diffs.png
   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: pano-align1.png   +image: pano-align2.jpg
   This function stitches 2-6 images together to make a wide-angle image or panorama. The images must overlap 
   by 10% or more, so that the program can find where they match and join them together. Start by selecting 
   2-6 image files (\>SELECT IMAGE FILES\>). It is helpful to select the images in left-to-right order, to 
   make the initial rough alignment easier. The images are initially joined and shown with a small transparent
   overlap. A pre-align dialog (above) asks you to drag the images into rough alignment. Drag the images into 
   the correct left to right order. The image to drag may overlap other images. To be clear about which image 
   is being dragged, drag from near the image center. After the images are in correct order, align each image 
   to its left neighbor. It works best to proceed from left to right. Move an image horizontally and vertically
   into rough alignment with its neighbor to the left, then rotate the image if needed by dragging the bottom 
   edge left or right - the image pivots around the mid-point of its overlap with the image to the left. The 
   fastest method is to align the overlap middle region first, then rotate the right image if needed to bring 
   the upper and lower overlap regions into alignment. Extreme accuracy is NOT necessary. The images should be 
   correctly curved and fit together well. If they do not, then 'lens mm' (focal length, 35mm equivalent)
   needs adjustment. Image curvature changes as lens mm is adjusted. The initial value is obtained from EXIF 
   data if available, and this is normally good enough. If the images have no curvature (e.g. scanned images), 
   use the 'no curve' checkbox to set 'lens mm' effectively to infinity.

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

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

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

   Press [proceed] when pre-alignment is finished, and the program will do fine alignment and join the images. 
   Internally, the images are shifted and rotated and the degree of match is evaluated. This is done with 
   increasing image sizes until the best alignment is found. This may need a minute or more, depending on CPU 
   speed and image size. You can speed up the process greatly if you reduce the input images to 2/3 or 1/2 
   size. Do this also if the process fails for lack of memory. Panoramas with 6 large images can require 16+ 
   GB of memory during processing. It may also be helpful to increase the size of your swapfile or swap 
   partition. This may make a large panorama successful (after taking a long time to complete).

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

   If the images do not align perfectly, you may be able to improve the alignment by using the mouse to push 
   the images into alignment. Select 'Mouse Warp' and select one of the images with the radio buttons. Then 
   drag the mouse along the edge of the image where it should align with its neighbor, moving the image into 
   alignment. The image is moved locally around the mouse while more distant parts stay fixed. Images with
   parallax shifting will require a compromise, since it is impossible to keep both foreground and background
   in alignment.

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

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

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

   \bAuto Warping
   The images are slightly warped in various directions during alignment to find the best match. This is to 
   compensate for shifts in camera horizon or rotation, causing image distortions that reduce the quality of 
   fit. If the overlap area of two images includes a large object that moved in or out between the two photos, 
   the alignment process may go crazy trying to match the images, 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.

   \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 image curving by 
   checking the box 'no curve' in the pre-align dialog.

   \bPanorama Limitations
   Panoramas including nearby objects can be tricky: when making the photos, be careful to turn the camera on 
   an axis through the lens, with minimum lateral movement, otherwise the images may align poorly because 
   foreground objects are shifted against the background (parallax). This is not an issue when the subject is 
   50+ meters away, since a small lateral movement has little impact on the image. Keep the camera level to 
   avoid a large vertical shift (horizon shift), which can cause image distortions that may not be fully 
   corrected. Avoid rotating the camera for the same reason.
   
   \bVertical Panorama
   This can be done by rotating the input images 90◦ so that top is on the left. In Panorama, choose the 
   images in order top to bottom, so that the top image is on the left and bottom is on the right. Do the 
   panorama normally. Rotate the output image clockwise so that left becomes top. 

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

MASHUP
   +image: mashup.jpg
   Arrange multiple images and text in a layout. Images can be added, resized, rotated and moved around by 
   dragging with the mouse. Images can be made entirely or partly transparent in selected areas. Text can be 
   added, moved, resized and rotated. Text attributes can be specified: font, size, color, outline, shadow, 
   transparency. Lines and arrows can be added. The example here shows some of the possibilities.

   +image: mashup1.png
   In the first Mashup dialog, choose a background or layout image where other images will be placed. Choose 
   an existing image or create a new monotone image with a specified size and color. You may also open a 
   previously saved mashup project and continue editing.

   +image: mashup2.png
   The 2nd Mashup dialog is a choice: edit images, edit text, edit lines and arrows, rescale to a larger size, 
   save the completed combined image (Done) or abandon the image (Cancel). The first three choices lead to 
   dialogs to perform the respective edits. Each of these return to this dialog when done, so you can add or 
   modify images, text, and lines/arrows in any sequence. Rescale is explained below.

   +image: mashup3.png
   Use this dialog to select and place images on the layout and revise their appearance: size, rotation, 
   position, transparency. An image may be partly or 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 rescales 
   the image. Angle rotates the image. The Stacking Order buttons raise or lower an image relative to other 
   images - this determines which overlapping image will be on top. Base Transparency is used to make an 
   entire image partly transparent. The [paint] button is used to make any part of an image partly or fully 
   transparent, using the Paint dialog shown below. The [warp] button is used to bend or warp an image, using
   the Warp dialog shown below. The 'black margins' checkbox can be used to remove black margins left by other 
   edit functions, e.g. warp. These will be made transparent. The 'Image is fixed' button will prevent the 
   image from being moved by the mouse or KB. This is helpful when images are being fine-aligned and 
   accidental movement should be prevented (can happen when working fast with mouse clicks and drags). The
   Margins controls can be used to make image edges transparent. The Hard margins cut off image edges. The 
   Blend margins make the edges partly transparent to blend them into the background or other overlapped 
   images.

   +image: mashup4.png
   "Paint" more or less transparency for selected image areas. Click on an image to select it. The mouse will 
   have a circle around it to show the range of action. Use radius to adjust the size of the circle. Left-drag 
   the mouse over the image to make it transparent in the areas covered by the circle. Right-drag to make it 
   opaque. If Gradual is checked, transparency changes are made slowly as the mouse is dragged. Specify a 
   power value for the mouse center and edges to regulate the change rate.

   +image: mashup5.png
   Click this dialog to insure it is active, and click on an image to select it. Drag the image with the mouse
    - the image will warp or stretch locally in the direction of the mouse (like sheet rubber). The area of 
    warping is roughly given by warp span, which is a fraction of the image size. Each drag is a step that 
    adds to previous steps. Recent steps can be reversed with [undo last], and the unbent image can be 
    restored with [undo all].

   +image: mashup6.png
   The Edit Text dialog is used for placing text on the layout. Enter some text and press Add. You are asked 
   to click on the layout where the text will be added. Drag it into position, then use the dialog controls 
   to set font, size, color, angle, background color, outline size and color, shadow size and color, and 
   transparencies for each of these. Drag the text to a new position at any time. Click on any existing text 
   to show its properties in the dialog and revise them. Click on a text and press Delete to remove it. When 
   done editing, press Done to return to the 2nd Mashup dialog.

   +image: mashup7.png
   The Edit Line/Arrow dialog is used for placing lines or arrows on the layout. It works very much like 
   adding text. Enter a length and width and press Add. You are asked to click on the layout where the line 
   will be added. A line is placed on the layout, or an arrow if one of the Arrow head options is checked. 
   Drag the line/arrow to the desired position. Adjust length, width, angle and attributes (background, 
   outline, shadow) using the dialog. You can also drag either end of the line/arrow to set the position of 
   that end, while leaving the other end fixed.

   You can use the mouse to move and resize objects in the layout:
      • click the object to select it - it flashes to confirm the selection.
      • drag from the approximate center to position the object.
      • drag the image or text lower right corner to resize.
      • for a line/arrow, drag either end to move that end only.

   The keyboard arrow keys can also be used to move the currently selected object in 1-pixel steps.

   You can also add images saved by \>SELECT AREA\>. In the Edit Images dialog, press [Add] to start the file 
   selection dialog. Use the [Top] button in the gallery window, select 'saved_areas'. Open any of the .png 
   images found there. The original area outline is used, and area blending works from these edges.

   \bMashup project files
   You can save a project and open it later to continue editing. However, the project file will open 
   successfully only if the layout image and all the overlay images are still available in their original 
   locations. The Mashup project is rebuilt using these images and some saved metadata in the project file: 
   image and text locations, scales, transparency, etc.

   \bMashup Rescale
   Working with a very large layout (over 20 megapixels) can be quite slow, especially if the PC is not very 
   strong. Dragging a large overlay image can be slow and jerky. You can work much faster if you use a smaller 
   layout to build the project, and then make it larger after you are finished. There is no loss of resolution 
   in the final image, since the overlay images and text are regenerated from the inputs (e.g. an image that 
   was scaled to 0.2x in the initial layout is rescaled to 0.6x if the layout is magnified by 3x). The 
   original full size image file is used for this rescale. The Rescale button allows you to magnify the 
   project by 2x, 3x or 4x (4x, 9x or 16x by area). There is also a reset option to restore the original 
   smaller project size. With this method, you can work with a 10 megapixel layout and rescale it up to 160 
   megapixels when done. The larger layout can still be worked on directly afterwards, but it will be much
   slower.

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

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

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

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

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

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

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

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


BATCH MENU

+image: ug-batch.png

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

BATCH CONVERT
   +image: batch-convert.png
   This function is used to rename, convert, rescale, 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.png
   Copy or move selected image file to a new location. Select the input files (\>SELECT IMAGE FILES\>) from 
   any folders known to Fotoxx. If "Delete Originals" is selected, then the input files will be deleted after 
   successfully moving them to the new folder. In this case, any albums referencing the now deleted input 
   files will be updated with the new file locations.

BATCH UPRIGHT
   +image: batch-upright.png
   This function uprights image files rotated 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.png
   Select the files (\>SELECT IMAGE FILES\>). Select the option: delete or move to trash. [Proceed]. Files are 
   listed in a popup report as they are deleted or moved to trash. After all files are deleted/trashed, albums 
   are scanned and deleted files removed.

BATCH RAW
   +image: batch-raw.png
   This function converts selected RAW image files to JPG, PNG, or TIF format. PNG and TIFF formats have 
   either 8 or 16 bits per color. RAW files generally have 8-12 bits per color, and noise beyond that. 
   Therefore use a 16-bit format to keep all of the data available from a RAW file. The difference between 
   8- and 16-bit color is rarely visible, but a higher color depth provides a greater margin for edit 
   functions that can radically shift the brightness distribution, causing a problem known as "banding"
   or "posterization".

   Use the [Select Files] button to choose one or more RAW image files from gallery windows 
   (\>SELECT IMAGE FILES\>). Choose one of the output formats. Choose one of the downsize options if wanted, 
   and set the auto sharpen parameters if wanted. See the \>SHARPEN\> function for an explanation of these 
   parameters.

   The image files are converted one at a time and displayed in the main window. Depending on the number of 
   files, this can take a long time (a strong PC does about 30 files per minute using Dcraw and TIFF-16 
   output). PNG-16 produces smaller files than TIFF-16 but the time to compress is greater.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

   There are two ways to change photo date/times:
      • Set a new date/time (right image above)
        enter a new year only (yyyy) - only the year 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.png
   This function can revise metadata for multiple image files. You can add new metadata, revise existing 
   metadata, and delete metadata. Use the [select files] button to open a gallery window from which you select 
   files to process (\>SELECT IMAGE FILES\>). Enter metadata key names and values to be assigned, or leave the 
   value blank to delete the key. Press [apply]. You will get a confirmation message and you can proceed or 
   cancel at this time. A list of commonly used key names is provided on the left. Click one of these to 
   insert it into the first empty key name field in the dialog. This list comes from the file 
   <fotoxx-home>/metadata_picklist, which you can edit to add other keys to the list. The [Full List] button 
   provides information on how to get a list of all available key names.

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

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

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

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

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

BATCH GEOTAGS
   +image: batch-geotags.png
   With this function, you can select many images and add the same location data to all of them. Use the 
   [select files] button to select the image files from a gallery window (\>SELECT IMAGE FILES\>). Then get 
   the location data as described in \>EDIT META\>, using the buttons [Find] and [Lookup], or click on a map 
   marker. Press [proceed] to start the update process. Use this function also to fix inconsistencies in 
   location spelling or latitude/longitude data. If location and/or country is left blank, they are not 
   updated. To erase location or country, input the name "null". If latitude and longitude are left blank, 
   they are not updated. To erase latitude and longitude, input "0" for both values. 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.

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

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

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

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

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

   The following functions are currently scriptable:

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

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

      Refine   Voodoo 1          automatic image enhancement tool
               Voodoo 2          automatic image enhancement tool
               Edit Dist         reshape the brightness distribution
               Flatten Dist      increase contrast in areas with low contrast
               Local Contrast    add contrast adjusted for area brightness
               Gradients         increase local contrast where weak
               Global Retinex    increase color and contrast globally
               Local Retinex     increase color and contrast locally
               Saturation        adjust color saturation based on brightness
               Soft Focus        produce a mixed sharp and blurred image
               Brite Ramp        ramp brightness or color 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
               Tiles1            convert image into square tiles
               Tiles2            convert image into irregular tiles matching image
               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
               Engrave           convert image into black & white lines
               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.png
   Fotoxx needs to know where all your image files are located (folder and file names) and their embedded 
   metadata (dates, tags (keywords), geotags, titles, descriptions, ratings). This data is indexed for fast 
   searching. Fotoxx also creates thumbnail images so that the gallery windows (thumbnail pages) will work 
   fast. Fotoxx does not modify or copy your image files - it only reads them to make the index and 
   thumbnails. These are typically 2% as large as the JPEG files from a modern camera.

   The Index Files function runs whenever Fotoxx is started. This function will create missing thumbnails, 
   replace outdated ones, and refresh the metadata index using current data from your image files. This may 
   need significant time if you have many thousands of new files. The speed can range from 300 to >20K 
   files/minute, depending on computer speed, disk speed, and average file size (the big number is for a 
   4 GHz CPU with 8 cores and a PCIe SSD). If there are few or no new files, indexing completes quickly.
   Indexing can also be started manually from the Tools menu.

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

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

   Enter your top image folders (e.g. /home/<user>/Pictures). Use the [browse] button to locate and add 
   folders. These folders and any subfolders containing images will be processed. It does not matter if other 
   files are mixed with the images. The simplest way is to use  /home/<user>  as the only top folder, but it 
   is better to separate the image files from the 100,000 other files that may be under /home/<user>. Delete 
   an entry by clicking the corresponding X.

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

   If you have used folder or file names to classify your images, you can make immediate use of these in the 
   \>SEARCH IMAGES\> function. If you have saved dates, tags, geotags, titles, or ratings in your image 
   metadata (using other applications), these will also be searchable. After the images 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.png
   You may add up to 10 other metadata items to the image file index. These are in addition to the standard 
   items mentioned above. Metadata in this list can be searched as fast as the standard items. You may not 
   need this, but if you sometimes need to search non-standard metadata items, you can add them here and the 
   search speed will be almost instantaneous. Press the [select] button for "extra metadata" to get the above
   dialog. Click on items in the left list to add them to the right list - the items to be added to the index. 
   Click on an item in the right list to remove it. Press [done] to commit the changes. If you make any 
   changes to this list, your entire image collection will need to be indexed again. This will proceed much 
   faster than the initial indexing, because the thumbnails are already there and do not need to be created. 
   Only the image file index will be refreshed.

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

   \bAccessing non-indexed Files and Folders
   A non-indexed image file or folder is one that is not included within your declared top image folders 
   (subfolders of your declared image folders are always included). You can navigate to such a folder and 
   view the thumbnails normally, and you can view and edit such files normally. There are limitations that 
   you should understand.
     • These files will be missing from any search results and map views.
     • Thumbnails are created at the time of viewing - gallery paging may be slow.
   If you 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 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.

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

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

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

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

   \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 2 seconds per 10K image files. Following startups are roughly 3x faster. First startup 
        with an SSD disk is roughly 1 second per 20K image files (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, not wait for indexing. You can control this with the parameters 'command' and 'file manager'.
      • The 'command' parameter controls how Fotoxx indexes when started from a menu, launcher or command. 
        The 'file manager' parameter controls how Fotoxx indexes when started by clicking on a file name 
        displayed in Nautilus or other file manager.
      • A value of '0' means no indexing at all. Startup is very fast. Image search and map functions are 
        disabled. Viewing and editing images and metadata is normal.
      • A value of '1' means load the old index file but do not search for new files to update the index. 
        Startup time is moderately fast. Image search and map functions work normally, but any new 
        (not yet indexed) image files are ignored.
      • A value of '2' means full indexing: load the old index file, search for new fies (not yet indexed) 
        and update the index file. Startup time depends on how many new image files must be indexed and the 
        speed of your computer. Image search and map functions produce complete results.

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

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

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

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

KB SHORTCUTS
   +image: KB-shortcuts.png +image: KB-shortcuts2.png
   This function is used to view or change custom keyboard shortcuts. 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.png
   This function opens a small window that shows a brightness distribution graph of the current image in File 
   view, or the currently selected area of the image. This graph updates immediately for new images or as edit 
   functions change the image. There are four graphs in four colors: red, green, blue graphs are for the 
   respective colors. The black graph is for overall brightness. Use the buttons [All] [Red] [Green] [Blue]
   to select the colors to show.

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

FIND DUPLICATES
   +image: find-dups.png
   Find duplicated image files anywhere within your image database. A duplicate image file can be an image 
   file that exactly duplicates another image file, or an image file that "almost" duplicates another. For the 
   sake of speed, thumbnail images are compared in memory. Hence it is possible that identical thumbnails are 
   found for which the main images have some minor (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 is roughly:
       size x size x 0.75 x 3 x (image count)
   Press the calculate button to calculate the largest thumbnail size (for the shown file count) that can 
   fit within the free memory available.

   Two parameters are used to set the sensitivity for detection of identical or nearly identical images: 
   pixel difference is the RGB value difference below which pixels are considered equal. Set to 1 to detect 
   any pixel difference. Pixel count is the number of different pixels below which two images are classified 
   as duplicates.
      example: if pixel difference = 2 and pixel count = 10, then images are classified as duplicates if 
      fewer than 10 pixels 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.png
   Click any two positions within an image to measure the pixel distance between the points. The clicked 
   positions are labeled A and B on the image. These labels always show last two points clicked. The dialog 
   is updated with the distances separating these two points:
      X-distance (horizontal distance)
      Y-distance (vertical distance)
      H-distance (total distance)

SHOW RGB
   +image: show-RGB.png
   When a point on the image is clicked, the RGB values are shown in a dialog window. The last 9 clicked 
   points are displayed. The values have the format xxx.dd, where xxx is the upper 8 bits of the color value 
   and .dd is the lower 8 bits. The range is 0.00 to 255.99. The lower 8 bits are zero unless the image is 
   being edited or the image is a 16-bit TIFF or PNG file. The outputs are updated in real time if the image 
   is being edited. If "labels" is checked, the points are labeled on the image with letters A-I, 
   corresponding to the letters A-I in the dialog window. If "delta" is checked and the image is being edited, 
   then RGB changes are shown instead of the absolute values.

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

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

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

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

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

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

   \bResults (my Canon printer)
   +image: printer-calibrate.png  +image: printer-cal-study.png
   The chart above is a photo of three images:
      upper left: a printout of a photo of a standard color chart
      upper right: a calibrated printout of the same photo
      bottom: the color chart itself
   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.png
   There are two grid line functions: Grid Settings sets all grid parameters. Toggle Grid sets the grid lines 
   on or off (showing or not showing in the image window). Grid lines are horizontal and vertical lines at 
   regular intervals across the image. These lines can be useful alignment guides when an image is unbent or 
   warped to straighten walls or other objects in the image. The settings for x- and y-spacing set the spacing 
   (pixels) between lines. If the controls for x- and y-count are NOT zero, the x- and y-spacing values are 
   ignored and the number of lines will be set from these counts. Example: set x-count and y-count to 2 lines 
   each in order to divide the image into thirds, both horizontally and vertically. The x- and y-offset 
   controls can be used to shift the grid lines to intersect a desired point in the image. The x- 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 with a terminal command).
      • License - Shows the text of the Fotoxx usage and copy license (GNU GPL3).
      • Privacy - Shows a privacy policy summary, with a link to the full document.
      • About - Show installed and latest release numbers, contact, executable.
      • Uninstall - Delete all application files and optionally user data files.
                    If installed at /usr/bin etc. then sudo password is required.


OTHER TOPICS

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

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

   \>EXPORT FILES\> - copy selected files from many locations to a single 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 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

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

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

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


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

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

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

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

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

RUNNING OUT OF DISK SPACE
   During a series of image edits, each edit step is saved on disk, and the before/after results can be viewed 
   with the Undo/Redo button. These images use 32-bit floating point numbers for color values and are not 
   compressed. A 30 megapixel image makes a 480 MB file. If there are 10 edit steps in the undo/redo stack, 
   the required disk space is 4.8 GB. If disk space runs out during an edit session, the program terminates 
   with a message. To avoid this, be sure there is plenty of disk space wherever your Fotoxx home folder 
   resides. When you open a new image or quit Fotoxx, the disk space is recovered. If Fotoxx crashes, the 
   space is recovered the next time Fotoxx is started.

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

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

   The Image Search function finds real paths only.

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

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

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

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

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

INDEX DATA FILES
   These files can be found in the folder <fotoxx-home>/image_index_*/
   image_folders: 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.

COLOR DEPTH ISSUES
   8-bit color (256 brightness levels), as supported by JPEG files, is the norm for image files and is 
   generally adequate. A difference of one brightness step (0.4% of entire range) cannot be seen. A greater 
   color depth than 8 bits can be useful if some part of the brightness range 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, only expensive 
   cameras with large sensors produce RAW files with more than 8 bits of low-noise color at normal exposure 
   levels (ISO <1000).

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

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

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

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

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

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

ALIGNMENT ALGORITHM
   Combined images for panorama, HDR, etc. must be accurately aligned to avoid fuzziness in the output image. 
   Relatively few high-contrast or "feature edge" pixels are used to control alignment. These pixels are 
   shown in red during the alignment process, which is also more entertaining. Each image in succession is 
   systematically warped various small amounts and the fit with other images is tested. This is done because 
   two photos made with slightly different horizons or rotations will not fit perfectly with simple 
   translation and rotation. Also camera lenses are not geometrically perfect.

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

IMAGE DETERIORATION FROM REPEATED EDITS
   If you save an edited image file and then use this file later to perform additional edits, pixel resolution 
   may be lost. It is better if you do all edits when the image file is first processed, to minimize image 
   deterioration (or go back to the original if you still have this). Any function that changes image size or 
   shape will reduce  resolution about 1/2 pixel. These are rescale, rotate, warp, and all combine functions. 
   Rotating 90 degrees does not affect resolution. When downsizing an image, using ratios 1/2, 1/3, 1/4 will 
   give the best resolution. Functions that change brightness and color do not affect resolution.

INTERPOLATION METHOD
   +image: interpolation.png
   When an image is rescaled, rotated, or warped, the resulting output pixels must be "interpolated" from 
   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 "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, so not a problem here.
   A slower computer could need a second or more for this. 

JPEG COMPRESSION
   If a JPEG file from a digital camera is saved with Fotoxx, you will likely notice a large reduction in file 
   size, even if a high JPEG quality level is used. This is because Fotoxx can afford to invest more 
   processing power in the compression. A camera CPU is not very fast and must save an image quickly to be 
   ready for the next photo, so the processing time available for compression is limited. The CPU of a typical 
   PC is much faster and has more time, so the compression level is higher. The smaller file size does not 
   mean that the quality is less.

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

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

NEWLINE CHARACTERS IN METADATA
   When editing metadata image descriptions, if you need to align text 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.
   THIS IS NOT STANDARD, so don't expect the text to remain aligned if viewed with other image viewers. If 
   this is a requirement, then don't use the enter key to make new lines when entering long text - just let 
   the text overflow to the next line by itself. In this case, column alignment is not possible.

DIALOG WINDOW POSITIONING
   For commonly used dialogs, Fotoxx saves the dialog window position (relative to the main window) and tries 
   to restore the same position the next time the dialog is used. This works, mostly. Sometimes the window 
   manager decides some other position.

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

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

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

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

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

GTK TIMEOUT PROBLEM
   GTK applications try to detect endless loops with a timeout timer. If the timer is not reset within a time 
   limit, the application is thought to be looping, and a popup dialog will offer the options of killing the 
   application or allowing it to continue. Fotoxx sometimes does things that take a long time, and the timer 
   is not reset fast enough (e.g. calling a library function to read a huge image file can require >10 sec).
   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).

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

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

   The binary package includes some libraries used by Fotoxx, but only those likely to vary depending on Linux 
   flavor and release date. This package should run OK on most recent flavors of Linux. The binary package has 
   a very fast startup time (< 0.02 secs. to load and start the executable on my strong desktop computer). 

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

   \bFiles in Fotoxx home
      albums/              image albums from Manage Albums function
      custom_kernel/       saved custom kernel data files
      custom scripts/      saved script files for custom edits or batch edits
      file_maps/           map files for both downloaded maps and custom maps
      image_index_*/       top folders, thumbnail folder, image index file
      image_array_maps/    saved image array maps (embedded image locations)
      markup/              saved text strings for markup->draw text
      mashup/              saved mashup project files
      palettes             color palettes used by the Dither function
      patterns/            saved background patterns
      printer_color/       saved printer color calibration files
      retouch/             saved settings for the Retouch function
      saved_areas/         "cutout" files saved from 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
      temp/                temporary files for current sessions (can be more than 1)
      thumbnails/          thumbnail files (default location, user can change this)
      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
      drag_from_folder     memory used by 2 fotoxx processes to drag/drop files
      folder.png           optional, from user: customize gallery folder icon
      fotoxx-NN.N.log      activity log - may be relevant for diagnosing problems
      gallery_memory       saved sort order and position for gallery windows
      KB-shortcuts_*       user-defined keyboard shortcuts
      meta_picklist_*      metadata key names for GUI pick lists
      meta_report_items    list of metadata items reported by Batch Report Meta
      meta_view_extra      extra custom items for the metadata short report
      netmap_locations     saved locations in net map view
      pagesetup            saves page setup data for print function
      parameters           parameters that are saved across Fotoxx sessions
      plugins              saves the plugins menu contents
      popup_text           collection of special characters for text widget inputs
      printsettings        saves print settings data for print function
      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
      userguide            text file copy of user guide without images
      wallpaper            fotoxx wallpaper tool - last used wallpaper file
      widgets.css          styling changes to standard GTK widgets
      worldcities.txt      geocoordinates for all significant world cities
      zdialog_geometry     saved dialog window positions (relative to main window)
      zdialog_inputs       saved dialog data for dialogs that recall prior inputs

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

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

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

FOTOXX SOURCE CODE
   The C++ source code is contained in the source package at \_https://kornelix.net. The code is heavily 
   commented in the hope that others can understand and use the code for their own projects. If you have a 
   technical question about how something works, or a better idea to pass along, you may contact me: 
      mkornelix@gmail.com.

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

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

ACKNOWLEDGEMENTS
   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 110K lines 
   of C/C++ code. The primary author is Michael Cornelison.


ALL TOPICS INDEX

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


EOF   (nothing shows beyond this line)

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

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

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

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

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

UG-topics $: ./UG-topics 
source folder: /home2/mico/programs/fotoxx-23.72/*.cc 
file: /home2/mico/programs/fotoxx-23.72/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.72/UG-topics/UG-topics.cc 
file: /home2/mico/programs/fotoxx-23.72/f.edit.cc 
   topic: \>PAINT EDITS\> 
   topic: \>ROTATE\> 
   topic: \>CROP\> 
   topic: \>RETOUCH\> 
   topic: \>RESCALE\> 
   topic: \>MARGINS\> 
   topic: \>MARKUP\> 
   topic: \>COLOR MODE\> 
   topic: \>PAINT IMAGE\> 
   topic: \>PAINT TRANSP\> 
   topic: \>COPY IN IMAGE\> 
   topic: \>COPY FROM IMAGE\> 
   topic: \>COPY FROM IMAGE\> 
   topic: \>COPY PRIOR EDIT\> 
   topic: \>PLUGINS\> 
   topic: \>PLUGINS\> 
   topic: \>PLUGINS\> 
   topic: \>EDIT TEMPLATE\> 
file: /home2/mico/programs/fotoxx-23.72/f.widgets.cc 
   topic: \>CUSTOM MENU\> 
file: /home2/mico/programs/fotoxx-23.72/f.batch.cc 
   topic: \>BATCH CONVERT\> 
   topic: \>BATCH COPY/MOVE\> 
   topic: \>BATCH UPRIGHT\> 
   topic: \>BATCH DELETE/TRASH\> 
   topic: \>BATCH RAW\> 
   topic: \>BATCH OVERLAY\> 
   topic: \>EXPORT FILE LIST\> 
   topic: \>EXPORT FILES\> 
   topic: \>SCRIPT FILES\> 
   topic: \>SCRIPT FILES\> 
   topic: \>SCRIPT FILES\> 
   topic: \>SCRIPT FILES\> 
file: /home2/mico/programs/fotoxx-23.72/f.file.cc 
   topic: \>NEW SESSION\> 
   topic: \>OPEN IMAGE FILE\> 
   topic: \>CYCLE 2\> 
   topic: \>CYCLE 3\> 
   topic: \>VIEW 360° PANO\> 
   topic: \>RENAME\> 
   topic: \>PERMISSIONS\> 
   topic: \>CHANGE ALPHA\> 
   topic: \>ZOOM\> 
   topic: \>BLANK IMAGE\> 
   topic: \>COPY/MOVE\> 
   topic: \>COPY TO DESKTOP\> 
   topic: \>COPY TO CLIPBOARD\> 
   topic: \>DELETE/TRASH\> 
   topic: \>CONVERT ADOBE\> 
   topic: \>SET WALLPAPER\> 
   topic: \>PRINT\> 
   topic: \>HELP MENU\> 
   topic: \>HELP MENU\> 
   topic: \>FILE SAVE\> 
file: /home2/mico/programs/fotoxx-23.72/fotoxx.cc 
   topic: \>OUTBOARD PROGRAMS\> 
   topic: \>FIRST INDEX\> 
   topic: \>UNDO/REDO BUTTON\> 
file: /home2/mico/programs/fotoxx-23.72/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.72/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.72/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.72/f.select.cc 
   topic: \>SELECT AREA\> 
   topic: \>FIND AREA GAP\> 
   topic: \>AREA BLEND\> 
   topic: \>SHOW/HIDE AREA\> 
   topic: \>SHOW/HIDE AREA\> 
   topic: \>ENABLE/DISABLE AREA\> 
   topic: \>ENABLE/DISABLE AREA\> 
   topic: \>INVERT AREA\> 
   topic: \>CLEAR AREA\> 
   topic: \>COPY/PASTE AREA\> 
   topic: \>LOAD/SAVE AREA\> 
   topic: \>LOAD/SAVE AREA\> 
   topic: \>COPY/PASTE AREA\> 
file: /home2/mico/programs/fotoxx-23.72/f.mashup.cc 
   topic: \>MASHUP\> 
   topic: \>IMAGE ARRAY\> 
file: /home2/mico/programs/fotoxx-23.72/f.effects.cc 
   topic: \>SKETCH\> 
   topic: \>CARTOON\> 
   topic: \>DRAWING\> 
   topic: \>EMBOSS\> 
   topic: \>TILES1\> 
   topic: \>TILES2\> 
   topic: \>PAINTING\> 
   topic: \>TEXTURE\> 
   topic: \>PATTERN\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>DITHER\> 
   topic: \>ENGRAVE\> 
   topic: \>MOSAIC\> 
   topic: \>ADD NOISE\> 
   topic: \>COLOR DEPTH\> 
   topic: \>SHIFT COLORS\> 
   topic: \>ALIEN COLORS\> 
   topic: \>COPY COLORS\> 
   topic: \>PASTE COLORS\> 
   topic: \>CUSTOM KERNEL\> 
file: /home2/mico/programs/fotoxx-23.72/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.72/f.pixmap.cc 
file: /home2/mico/programs/fotoxx-23.72/f.repair.cc 
   topic: \>SHARPEN\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>BLUR\> 
   topic: \>DENOISE\> 
   topic: \>DEFOG\> 
   topic: \>RED EYES\> 
   topic: \>SMART ERASE\> 
   topic: \>REMOVE HALO\> 
   topic: \>JPEG ARTIFACTS\> 
   topic: \>ANTI-ALIAS\> 
   topic: \>ADJUST RGB\> 
   topic: \>ADJUST HSL\> 
   topic: \>COLOR PROFILE\> 
   topic: \>REMOVE DUST\> 
   topic: \>CHROMATIC 1\> 
   topic: \>CHROMATIC 2\> 
file: /home2/mico/programs/fotoxx-23.72/f.comb.cc 
   topic: \>HDR\> 
   topic: \>HDF\> 
   topic: \>STACK/PAINT\> 
   topic: \>STACK/NOISE\> 
   topic: \>STACK/VERSIONS\> 
   topic: \>STACK/SPLIT\> 
   topic: \>PANORAMA\> 
   topic: \>SHOW CIM FILES\> 
file: /home2/mico/programs/fotoxx-23.72/f.albums.cc 
   topic: \>MANAGE ALBUMS\> 
   topic: \>UPDATE ALBUMS\> 
   topic: \>GALLERY TO ALBUM\> 
   topic: \>ALBUM MASS UPDATE\> 
   topic: \>SLIDE SHOW\> 

