File: userguide

package info (click to toggle)
fotoxx 24.70-1
links: PTS, VCS
area: main
in suites: trixie
size: 21,888 kB
sloc: cpp: 78,255; makefile: 116; xml: 52
file content (4260 lines) | stat: -rw-r--r-- 391,228 bytes

TOPIC: FOTOCX USER GUIDE  v.24.70
  View using the Fotocx menu Help > User Guide

TOPIC: INTRODUCTION 
  {FOTOCX OVERVIEW} - description, prerequisites, license, downloads
  {FOTOCX CAPABILITIES} - summary of Fotocx functions and tools

TOPIC: FOTOCX USAGE
  {INSTALLATION} - Fotocx software installation, dependencies
  {FIRST STARTUP} - information for Fotocx first startup
  {OUTBOARD PROGRAMS} - required and optional programs used by Fotocx
  {FIRST INDEX} - locating and indexing image files for fast searching
  {USER GUIDE} ← ^click here^ - 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 image 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 ALT-RIGHT-BUTTON} - mouse right-button for touchpads/screens
  {DIALOG BUTTONS} - dialog completion options
  {KEYBOARD ENTER KEY} - functions of Enter key
  {KEYBOARD ESCAPE KEY} - functions of the Escape key
  {CUSTOM DIALOG WIDGETS} - how to use custom dialog widgets
  {CURVE EDITING} - how to manipulate curves used in edit functions
  {BATCH PROCESSING} - overview of batch processing functions
  {SELECT IMAGE FILES} - image file selection procedure
  {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 and Gallery View
  {KEYBOARD SHORTCUTS} - keyboard shortcuts for file/gallery/map views
  {NUMERIC KEYPAD} - navigation using numeric keypad
  {MOUSE FUNCTIONS} - mouse functions for file/gallery/map views
  {COMMAND PARAMETERS} - Fotocx command line parameters
  {TOP PANEL DATA} - details of information in the File View top panel

{FILE MENU}
  {NEW SESSION} - start new Fotocx session in a separate window
  {OPEN IMAGE FILE} - open an image file for view or edit
  {CYCLE 2 FILES} - cycle through the two most recently seen image files
  {CYCLE 3 FILES} - cycle through the three most recently seen image files
  {VIEW 360° PANO} - 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 blank image 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
  {SET WALLPAPER} - wallpaper from the current image file (Gnome)
  {PRINT IMAGE} - print an image file
  {PRINT CALIBRATED} - print using color calibration data
  {CALIBRATE PRINTER} - calibrate printer color - compensate color shifts
  {QUIT} - exit from Fotocx

{GALLERY MENU}
  {GALLERY OVERVIEW}
  {THUMB VIEW} - Gallery View with thumbnails and file names
  {META VIEW} - Gallery View with thumbnail and basic metadata
  {RECENT FILES} - Gallery View of most recently seen image files
  {NEWEST FILES} - Gallery View of newest image files
  {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
  {CURRENT FOLDER} - set current gallery from current file folder
  {RECENT FOLDERS} - open Gallery View of last used file folder
  {FOLDER TREE} - show all image file folders in a tree structure
  {SELECT FILES} - select files for input to batch, script or album
  {RENAME FOLDER} - rename current folder (file gallery)
  {ADD SUBFOLDER} - add new subfolder to existing image folder
  {BOOKMARKS} - view list of bookmarks, go to bookmark
  {EDIT BOOKMARKS} - add, remove, arrange bookmarks
  {MANAGE ALBUMS} - create and arrange user-defined image collections
  {UPDATE ALBUMS} - update albums for updated image files
  {ALBUM MASS UPDATE} mass update of multiple album files
  {GALLERY TO ALBUM} - save current gallery as a named album
  {SLIDE SHOW} - slide show with animated transitions and pan/zooms

{MAPS MENU}
  {WORLD MAP} - internet world map overview
  {MAP REGIONS} - define custom map region names, goto map region
  {MAP LOCATION} - find location name from partial input, goto map location
  {MAP MARKERS} - show map markers for all images or current gallery
  {SHOW ON MAP} - show an image file position in Map View

{CUSTOM MENU} - custom user menu for frequently used functions
  {SCRIPT FILES} - script files overview
  {EDIT SCRIPT} - record edits in a script to make a custom edit function
  {RUN SCRIPT} - execute script on current image
  {BATCH SCRIPT} - execute script on selected image files
  {PLUGINS} - start a plugin edit function, open plugin output file

{ZOOM} - left/right click or [+-] button to zoom image or thumbnail
{FILE SAVE} - save image file (replace, new version, new file name)

{METADATA MENU}
  {VIEW MAIN META} - list main image metadata
  {VIEW ALL META} - list all image metadata
  {METADATA STANDARDS CHAOS} - multiple conflicting standards
  {TAGS OVERVIEW} - image tags (keywords) used for image searching
  {EDIT MAIN META} - edit commonly used metadata
  {EDIT ANY META} - edit any metadata (add, remove, 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 image corner
  {PLACES/DATES} - list image locations/dates, click for gallery
  {TIMELINE} - show image counts by year/month, click for gallery
  {AUTOSEARCH} - scripted Search function to find files
  {SEARCH IMAGES} - search using any metadata or folder/file names

{SELECT MENU}
  {AREA OVERVIEW} - select area - concepts and usage
  {SELECT AREA} - select 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 or paste area into current image
  {LOAD/SAVE AREA} - load an area from a file or save to a file

{UNDO/REDO BUTTON} - sequential undo or redo edits to current image

{EDIT MENU}
  {ROTATE} - rotate or level an image
  {UPRIGHT} - upright a rotated or mirrored image
  {CROP} - crop (trim) image margins
  {RETOUCH} - edit brightness, contrast, color, saturation
  {RESCALE} - change the image pixel dimensions
  {MARGINS} - add margins to an imqage, any color or transparency
  {MARKUP} - draw on image: text, line/arrow, box, oval
  {COLOR MODE} - convert to black & white, color, negative, positive
  {PAINT EDITS} - mouse-paint an edit function locally and gradually
  {PAINT IMAGE} - mouse-paint with a color, brush size, and opacity
  {PAINT TRANSP} - paint increasing transparency using the mouse
  {AREA FILL} - fill selected areas or transparent areas with a color
  {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
  {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, signs, other small spoilers
  {REMOVE HALO} - remove halos left by sharpen and other functions
  {JPEG ARTIFACTS} - suppress artifacts in highly compressed files
  {ANTI-ALIAS} - suppress pixelation (jaggies) along feature edges
  {ADJUST RGB} - adjust image colors using RGB or CMY colors
  {ADJUST HSL} - select and change colors using HSL colors
  {REMOVE DUST} - remove dust spots on images from old photos
  {FRINGES} - fix pheripheral color fringes (chromatic aberration)

{REFINE MENU}
  {EDIT HISTOGRAM} - edit brightness histogram for better detail
  {FLATTEN HISTOGRAM} - flatten brightness histogram for better detail
  {LOCAL CONTRAST} - add contrast adapted to local area brightness
  {AMPLIFY CONTRAST} - amplify existing contrast to enhance details
  {GLOBAL RETINEX} - rescale RGB values for greater range
  {LOCAL RETINEX} - rescale RGB values for greater range
  {SATURATION} - adjust color saturation based on brightness
  {SOFT FOCUS} - apply classic "soft focus" effect to an image
  {MATCH COLORS} - match the colors in one image to another image
  {BRIGHTNESS RAMP} - add a brightness/color ramp across an image
  {VIGNETTE} - change brightness/color radially around chosen center

{EFFECTS MENU}
  {OUTLINES} - convert an image into an outline drawing
  {SKETCH} - convert an image into a simulated sketch
  {CARTOON} - convert an image to a cartoon-like 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 image into a mosaic using tiles made from images
  {ADD NOISE} - add random noise to an image
  {SET COLORS} - 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
  {CUSTOM KERNEL} - edit and apply a custom convolution kernel

{WARP MENU}
  {UNBEND} - straighten images having curved lines, esp. panoramas
  {PERSPECTIVE} - straighten object photographed from an obtuse angle
  {WARP AREA} - warp a selected image area by pulling with the mouse
  {WARP CURVED} - warp image by mouse drag - curvy warp
  {WARP LINEAR} - warp image by mouse drag - straight lines preserved
  {WARP AFFINE} - warp image by mouse drag - parallel lines preserved
  {WARP RADIAL} - add or remove barrel or pincushion distortion
  {UNWARP CLOSEUP} - remove close-up face photo distortion (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
  {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 dark/bright images for an extended brightness range
  {HDF} - combine close/far focused images 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/LAYERS} - combine image versions, select/paint area/version
  {STACK/SPLIT} - show two images overlapped with movable boundary line
  {PANORAMA} - combine a series of images horizontally
  {SHOW CIM FILES} - show input files for current/latest combined image
  {MASHUP} - arrange 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 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 image files
  {BATCH REPORT META} - report metadata for selected or all image files
  {BATCH MOVE META} - move metadata between keywords - standardize usage
  {BATCH GEOTAGS} - add or revise geotags for selected or all image files
  {EXPORT FILE LIST} - make a list of selected files (e.g. shell script)
  {EXPORT FILES} - export selected files to a folder (e.g. web upload)

{TOOLS MENU}
  {INDEX FILES} - 1-time job to find and index all image files
  {QUICK INDEX} - quick incremental index with no user interaction
  {SETTINGS} - user preferences and settings for Fotocx operation
  {KB SHORTCUTS} - show and revise keyboard shortcuts for menu functions
  {RGB HISTOGRAM} - brightness histogram graph for current image
  {MAGNIFY IMAGE} - turn mouse into a magnifying glass over image
  {MEASURE IMAGE} - measure pixel distances within image (mouse clicks)
  {SHOW RGB} - show RGB values at mouse position or for selected points
  {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
  {FIND DUPLICATES} - find duplicate images in a gallery or all images
  {SHOW RESOURCES} - show CPU time and current memory usage

{HELP MENU} - user guide, tutorial, change log, about Fotocx, uninstall

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

{TECHNICAL TOPICS}
  {FOTOCX 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
  {JPEG IMAGE DETERIORATION} - analysis
  {METADATA ERRORS} - description and handling
  {NEWLINE CHARACTERS IN METADATA} - description and handling
  {DIALOG WINDOW POSITIONING} - description
  {FOTOCX PERFORMANCE} - methods and limitations, benchmarks
  {E-CORES AND HYPERTHREADS} - how useful are these?
  {FOTOCX PACKAGES} - package file contents
  {FOTOCX HOME FOLDER} - user data files in Fotocx home folder
  {IMAGE METADATA USAGE} - description and limitations
  {FOTOCX SOURCE CODE} - how to access Fotocx source code
  {FOTOCX FOR WINDOWS 11} - installing Fotocx on Windows 11 WSL

{ACKNOWLEDGEMENTS}

{ALL TOPICS INDEX} alphabetical index of all topics in this document


TOPIC: FOTOCX OVERVIEW

^Description
Fotocx is a free Linux program for editing photos or other images and managing a large collection. Navigate the collection using a thumbnail browser, click on an image to view or edit. Import RAW files and edit with deep color. Fotocx has powerful tools to correct and enhance photos. Images can be altered with special effects, and arranged in a montage with text and creative artwork. Select an object or area within an image (freehand draw, follow edges, flood matching tones...), apply edit functions, copy and paste, resize, blend, warp, etc. Edit functions have fast feedback using the full image or a selected zoom-in area. View and edit metadata (dates, tags, titles, descriptions, ratings, location, camera data - any metadata). Quickly find desired images within a huge collection, based on folder and file names or embedded metadata. Click a marker on a scalable world map to view all photos from that location. Batch functions are available to rename, add/revise metadata, copy/move, resize, convert format.

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

^Software Requirements
Most recent Linux distributions can be used to host Fotocx.
Windows WSL works with limitations. See ^https://kornelix.net/fotocx_topics/

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

^Contact
If you have a question, suggestion, or problem, contact me at
   ^mkornelix@gmail.com

^Downloads
Fotocx source and binary packages are available at
   ^https://kornelix.net
Both package types are easy to install and instructions are provided. The source package is like Debian source packages ($ sudo make install). The binary package works on most recent (>2022) flavors of Linux. To avoid compatibility problems, it includes library files which may be missing or incompatible depending on your flavor and release of Linux. If some other library is missing, an error message is shown when the program is started (start from a terminal to see this). Find and install the missing library using your package manager.

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

^Updates and Bug Fixes
Fotocx 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. Fotocx is also available on many other web sites and package repositories. These may not be updated for new releases. Some of these are years out of date and should be avoided.

^User Guide
Fotocx is easy to use but unconventional. If you try to use Fotocx while ignorant, you will be frustrated and may conclude that Fotocx 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 Fotocx use, by pressing the F1 key. Fotocx has deep functionality. Do not expect to master Fotocx in a few minutes.

TOPIC: FOTOCX CAPABILITIES
Here is a summary of what Fotocx 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 - compare original/edited versions (instant replace). 
 • Conventional edit functions: rotate, upright, crop, rescale, add margins,
   retouch: brightness/color/contrast/saturation/temperature/white balance,
   markup: text (decorative features)/lines/arrows/boxes/circles/ellipses,
   edit colors using RGB or HSL, convert B&W/color/negative/positive/sepia.
 • Repair functions: sharpen, blur selected areas, denoise, defog, red eyes,
   smart erase (remove spoilers), remove halos, suppress JPEG artifacts,
   anti-alias (suppress jaggies), remove dust spots, fix color fringes.
 • Refine functions: edit or flatten brightness histogram (enhance detail),
   increase local contrast (enhance detail), match colors to master image, 
   add soft focus, amplify existing contrast, global and local retinex,
   add brightness ramp in any direction, add/remove vignette (via curve edit).
 • Special effect conversions: sketch, outlines, cartoon, emboss, painting,
   tiles, texture, pattern, dither (5 modes), engrave, mosaic, shift colors,
   add noise (hide color bands), set no. of colors (per RGB), alien colors.
 • Warp image: unbend (wide-angle photos, panoramas), warp selected area,
   fix perspective (photo from an angle), warp image (linear/curved/affine),
   unwarp closeup (fix balloon face), add waves, twist image, make sphere, 
   turn inside-out, tiny planet, escher spiral, flatten curved horizon,
   flatten photo of curved surface (thick book page, poster on a column).
 • Edit functions can be 'painted' locally and gradually, using the mouse.
 • Copy areas within and across images by mouse painting and blending.
 • Create or maintain transparent image areas while editing.
 • Combine images: HDR (combine bright/dark images, adjust contributions), 
   HDF (combine different focus depths), stack/layer combinations by area,
   panorama (2-6 images), make an array or matrix of many images.
 • Mashup: arrange images and text in an arbitrary layout using the mouse.
   (objects can be resized, rotated, overlapped with transparent areas ...)
 • Custom user menu: collect frequently used functions into one menu.
 • Plugins: use Gimp, Imagemagic ... as embedded Fotocx edit functions.
 • Scripts: record image edits, package as an edit function to re-use.
 • 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).
 • 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 list 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.
 • Add location names and geocoordinates to an image by clicking on the map.
 • View 360 degree panorama image (Google Street View format).
 • Show video files as thumbnails (using any video 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 is available.
 • Custom keyboard shortcuts can be assigned to chosen functions.
 • Cycle wallpaper images from a Fotocx album or any folder of image files.
 • Source and binary packages are installable on most recent Linux flavors.
 • Gnu GPL3 license (everything is free to use as you please). 

TOPIC: INSTALLATION
There are three variations of Fotocx installation:
  • Use the package from your Linux repository (which may be quite old).
  • Use the distro-agnostic binary package from the kornelix.net website.
    Follow the instructions on the download page to install the package.
  • Use the source code package (tarball) from the kornelix.net website.
    Follow the build instructions (basically $ sudo make install).
    This has a performance advantage if you add compiler optimization
    for your target machine ($ gcc -march=native).
Download page: ^https://kornelix.net/downloads/downloads.html

TOPIC: 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

TOPIC: OUTBOARD PROGRAMS
+image: outboard-programs.png

When Fotocx is started for the first time, the above report is presented, listing the required and optional outboard programs that Fotocx 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, Fotocx will exit when the dialog is closed. After installing the required programs, start Fotocx again. You can show this list at any time with the menu Help > Outboard Programs. You can decide later if you need to install optional outboard programs to handle image files other than those supported by default: JPEG, PNG, TIFF and most RAW formats.

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

^WEBP files (.webp)
If the program dwebp is installed, Fotocx 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.

^Apple iPhone HEIF files (.heic .avif)
Apple iPhones can produce image files with the extension .heic. If the program heif-convert is installed, Fotocx 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.

^JPEG-2000 files (.jp2)
If the program opj_decompress is installed, Fotocx 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.

^Adobe document files (.pdf .ps .eps)
If the gs command (ghostscript) is installed, these files can be converted to
JPEG files, one per document page. Use the menu function File > Convert Adobe.

^Adobe (Photoshop) image files (.psd)
If the convert command (imagemagick) is installed, these files can be converted into JPEG files.
Use the menu function File > Convert Adobe.

TOPIC: FIRST INDEX
+image: first-index.png

When Fotocx 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 >20K files per minute, depending on image types, sizes and computer speed. Fotocx does not modify or copy your image files - it only reads them to make the metadata index and thumbnails. The additional file space is typically 2% of your total image collection size.

^Upgrade from a Fotocx prior release
Normally the index file is not affected, so that no re-indexing is required. If the index file format in the new release 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 (Intel ultra 7-265K) indexes about 23K jpeg images per minute (mean size 2.7 MB). 

+image: index-files1.png

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

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

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

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

^Index Time Required
If you have many thousands of image files, the initial index may need time. The speed can range from a few hundred to >20K files per minute, depending on processor speed, disk speed, and average file type and size. See {FOTOCX PERFORMANCE} for more information.

When you add new image files to your collection, the next Fotocx 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.

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

^Blacklist Folders
You may have some files that cannot be read by Fotocx 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 Fotocx or one of its tools crashes on such a file, there is a way to move it out of the way and stop Fotocx from trying to deal with it. Using a text editor, list the file names or folder names containing the problem files. Save this file with the name "blacklist" in your Fotocx home folder, e.g. /home/<user>/.fotocx/blacklist. The character '*' may be used as a wildcard that matches any number of characters. Here are some examples:
  exclude an entire folder: /folder/path/name/*
  exclude a single file: /folder/path/name/filename.jpg
  exclude files containing "asdfg" anywhere in path/file name: *asdfg*
  exclude files containing "asdfg" in any folders in the path: *asdfg*/*
Another way: move the problem files out of declared top image folders.

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

TOPIC: USER GUIDE
+image: userguide.jpg

Open the user guide from the menu Help > User Guide. While using Fotocx, 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.

TOPIC: WINDOW VIEWS AND MENUS
+image: fotocx-views.jpg

^Menu Buttons
The icons in the left side panel are menus. When one is clicked, a popup menu appears. These are functions for image viewing and editing, searching, reports and utilities. The top three menus (File, Gallery, Maps) set the corresponding view mode if not already set. The keyboard keys F2/F3/F4 can also be used.

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

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

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

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

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

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

Popup Image Manipulation:
  • Click thumbnail with middle mouse button: popup image appears
  • Click thumbnail with shift + left mouse: 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

TOPIC: 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. 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.

TOPIC: 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.

TOPIC: DRAG AND DROP
Fotocx 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.

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

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

TOPIC: EDIT WORKFLOW
You can speed the editing of multiple photos/images if you understand the following rules and methods:
  • Choosing a new edit function automatically completes an active
    edit. The new edit starts with the result of the prior edit,
    and an undo/redo position is created.
  • Opening a new image file during an edit function cancels the
    edit. The edit function is restarted with the new file.
  • 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 by dragging 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.

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

^Complex Workflow
To edit with deep color (over 8 bits), start with the camera RAW file.
There are two options for processing RAW files:
  • Click the RAW file gallery thumbnail. The RAW file may now be edited
    like any other image file. Fotocx edit functions work with 24 bits
    per color, so the full color depth of the RAW file is preserved.
    Save the edited file as type TIFF or PNG with 8 or 16-bit color,
    or JPEG with 8 bits. You cannot save an edited image as a RAW file.
    Opening a RAW file may need several seconds. Saving an image as
    PNG is much slower than JPEG or TIFF.
  • Use the menu Batch > Batch RAW. You can select many RAW files and
    convert all of them as described above. You can then select and
    edit these files as needed with Fotocx.
Fotocx can do most things you can do with a RAW editor. The key is to start with the RAW file or a derived file with 16-bit color depth, so that nothing is lost. When you open a RAW file in Fotocx, the chosen RAW loader is used with parameters you can change (see {SETTINGS}).

RAW files may have more color depth than 8 bits, especially if the camera is new and expensive. Converting into a PNG or TIFF file with 16-bit color will preserve whatever color depth is available in the RAW file. The higher color depth reduces the risk of visible color bands if your edits radically shift the brightness histogram. When finished editing, convert the final file to JPEG (quality level 70 or greater) to reduce the final file size to 10% or less. Note that editing in deep color is far more important than having deep color in the final image. It is nearly impossible to see a difference between a 16-bit TIFF or PNG file and a quality JPEG made from that same file. To preserve the ability to re-editing the image later, keep the RAW file, which is usually much smaller than the TIFF or PNG file.

Dcraw is the default RAW file loader. You can also use a more complex RAW editor like Raw Therapee if you prefer (see {SETTINGS}). Dcraw is simple and fast in comparison. The many options in a RAW editor can usually be done more easily with Fotocx edits.

TOPIC: 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 an image (paint, select area ...),
    the mouse is owned by the dialog that was last used and now
    retains KB focus. Mouse actions on the image are inputs to
    this dialog and DO NOT zoom or scroll the image.
  • If you hold the CTRL key down while clicking or dragging
    the mouse on the image, the image will zoom or pan/scroll.
    Open 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).

TOPIC: MOUSE ALT-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.

TOPIC: DIALOG BUTTONS
These mostly work as follows:
  [Reset]     undo changes, return to initial status
  [Apply]     apply dialog settings 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
  [X]         close dialog 

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

TOPIC: KEYBOARD ESCAPE KEY
This key has multiple uses. It affects only the window that has current keyboard focus. This can be the main Fotocx 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, restore prior size
     • if the current view is gallery or map, change to file view
     • none of the above: exit Fotocx
  • 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.

TOPIC: CUSTOM DIALOG WIDGETS
+image: custom-widgets.png

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

TOPIC: CURVE EDITING
+image: retouch.png

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

TOPIC: BATCH PROCESSING
There are several batch functions in the {BATCH MENU} to speed some common tasks. You can select many image files and execute the batch function for all of them. Batch functions can be used for the following tasks:
  • Rename files and add sequence numbers or photo dates to the names
  • Convert file types (e.g. .png to .jpeg)
  • Find and upright photos made with the camera turned 90 degrees
  • Rescale files (e.g. reduce for web upload or e-mail)
  • Copy or move files to another location
  • Convert RAW files to tiff, png, or jpeg
  • Add/change/remove image tags or geotags
  • Report or revise metadata items
  • Set image dates/times or shift times to change the time zone
  • Delete files or move them to Trash
  • Find duplicate image files.

TOPIC: 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 a file to the list: left-click gallery thumbnails
  • add multiple files: click first thumbnail, shift-click last
  • add all images in the gallery: press the [Add All] button
  • add the current image: press the [Add Current] button
  • a file may be added multiple times to the list
  • 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 list, view thumbnails
  • the KB page up/down and home/end keys also work

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

TOPIC: 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.

TOPIC: MENU SHORTCUTS
Fotocx 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}.

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

TOPIC: 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.

^File View popup menu
Right click on current image in File View mode to get the following menu:
  • View Main Meta - Show short form metadata report
  • View All Meta - Show all available metadata
  • Edit Main Meta - Edit main metadata items: photo date/time, tags ...
  • Rename - Change the file name
  • Delete/Trash - Delete the image file or move it to trash
  • Copy/Move - Copy or move the image file to another 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 ...
  • 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
  • Edit Histogram - Edit the brightness histogram
  • Flatten Histogram - Flatten the brightness histogram
  • Local Contrast - Add contrast adjusted for local image area
  • Amplify Contrast - Amplify existing contrast to enhance details
  • Saturation - Adjust saturation, optionally based on brightness

^Gallery View popup menu
Right click on thumbnail image to get the following menu:
  • Popup Image - Show image in a new window - zoomable, movable.
    Zoom in/out using the mouse wheel. Zoom down to disappear.
  • View Main Meta - Show short form metadata report
  • View All Meta - Show all available metadata
  • Edit Main Meta - Edit main metadata items: photo date/time, tags ...
  • Rename - Change the file name
  • Delete/Trash - Delete the image file or move it to trash
  • Copy/Move - Copy or move the image file to another 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
    (select video frame at minutes/seconds position)

TOPIC: 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:
  • [+] [=] key    Zoom image or thumbnails larger
  • [-] key        Zoom image or thumbnails smaller
  • Z key          Toggle image between 1x (full size) and fit window
  • F1 key         Display user guide for current or prior function
  • F2/F3/F4 key   Change to File/Gallery/Map view mode
  • F10 key        Toggle main window full-screen and back
  • F11 key        Same as F10, without menus, title bar and top panel
  • Escape key     Kill running function, Exit active dialog
  • Arrow ←/→      Show previous/next image file in current gallery
  • Arrow ↑/↓      File view: like ←/→ but show only last versions
                   Gallery view: scroll one row up/down
                   Report: scroll report up/down one row at a time
  • Page Up/Down   Gallery view: scroll one page up/down
                   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
  • K key          KB Shortcuts - dialog to view or change shortcuts
  • H key (help)   Display user guide for current or prior function
                   (Ctrl+H within dialogs does the same)

TOPIC: NUMERIC KEYPAD
+image: number-keys.png

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

TOPIC: MOUSE FUNCTIONS
File View
  • left click - Zoom-in: magnify image, center at click position
  • right click - If image is zoomed: restore to window size
                  If not, popup menu with common functions
  • mouse wheel - Zoom image in or out depending on wheel direction
  • left drag image - Pan/scroll zoomed image (see {SETTINGS})
  • Ctrl + mouse - Mouse acts on image 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 images at map location

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

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

^-x0 -x1 -x2  parameter^  (set index level at startup)
These parameters can be used to override the value in {SETTINGS}.
  -x0   no index: very fast startup with reduced functionality
  -x1   existing index: fast startup, omit new/modified images
  -x2   existing index: find and add new/modified images

Note: the first Fotocx startup after a reboot may be slow if your image collection is very large. Subsequent startups will be faster since folders are now cached in memory. For very fast startup, you can bypass indexing entirely with the command "fotocx -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}.

^-home^  parameter  (alternate Fotocx home folder)
The default location for 'fotocx home' is: /home/<user>/.fotocx. This is where user preferences and settings are kept (tag names, bookmarks, defaults ...). Image index data is also kept here. The command "fotocx -home <foldername>" expects 'fotocx home' to be in the designated folder. This enables multiple image collections to be managed separately. If Fotocx 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>/.fotocx  to the new home folder before starting fotocx with the new -home parameter. See {MOVE FOTOCX HOME}.

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

TOPIC: TOP PANEL DATA
+image: top-panel.png

The top panel has status information about Fotocx and the current image file. The following strings can be present, in approximately the following order:
  2000x1243x8       current image width x height x depth (bits/color)
  69%               zoom status, image size (window/image pixels)
  edits: 1          current edits, reversible with [undo/redo] button
  blocked           some functions blocked until current function done
  area active       edits are confined within the active selected area
  dialog open       an active dialog is waiting for user input
  working 45%       progress indicator for long-running function

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


TOPIC: FILE MENU

+image: ug-file.png

TOPIC: NEW SESSION
Start a new Fotocx 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.

TOPIC: OPEN IMAGE FILE
Select an image file to view or edit, using a conventional file open dialog with folders and lists of files. Click on a file name to select and open. Unlike normal usage for Fotocx, 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.

TOPIC: CYCLE 2 FILES
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].

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

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

TOPIC: 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.

TOPIC: 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.

TOPIC: CHANGE ALPHA
+image: change-alpha.png

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

TOPIC: 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}.

TOPIC: 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.

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

TOPIC: 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.

TOPIC: 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. Fotocx assumes the standard for trash (~/.local/share/Trash). Because GTK cannot trash files on mounted volumes, files are moved to ~/Desktop first, and then to trash. If such a file is restored from trash, it will show up on the desktop. If you have multiple files to remove, you can leave the dialog open to speed the process. If another file is opened, the file name in the dialog is updated. In Gallery View, if another thumbnail is clicked, the dialog is updated.

TOPIC: 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.

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

TOPIC: PRINT IMAGE
+image: print-setup.png  +image: print-margins.png

The print image menu brings up a standard Page Setup dialog where you can select a printer, a paper size, and orientation. After using the [apply] button, another dialog starts for entering paper margins and image scale. The margins can be used to shrink the image or shift it on the page. Image scale can be set in the range 5-100%, where 100% means print the maximum size image that fits within the margins. Smaller values will shrink the image proportionally. The actual print size (image width and height) is updated in the dialog as margins and scale are changed, and this can be used to reach a desired print image size. After the margins dialog, a Print dialog starts for the actual printing. This includes paper type and quality inputs, and a preview of the printed layout which can be accepted or rejected. If grid lines are shown on the image, the printed image will also have the grid lines, although much thinner.

If the image has select area(s), you are asked if only the select area(s) should be printed. These will be printed using the minimum rectangle needed to enclose the areas, and areas outside the selections are not printed (white paper). 

TOPIC: 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} (below) for details on how to create a calibration file.

TOPIC: CALIBRATE PRINTER
+image: printer-calibrate-chart.png  +image: calibrate-printer.png

This utility may be able to improve the color accuracy of printed images.

^How 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 <fotocx-home>/printer_color/.
  1. Generate and print the color chart file (printchart.png) on
     the printer to be calibrated. Use large paper size, vertical
     orientation, no margins.
  2. Scan the printed chart into a PNG file. Use 300 dpi or more.
  3. Edit the PNG image to crop margins left by the scanner.
     Save the edited image file.
  4. Process the edited image file to create a color map file.
     Use a name indicating the printer settings and paper type,
     so the file can be matched to future print jobs.

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

Precautions For Best Results
  • Use a large paper size for printing the chart to make the color
    tiles as big as possible.
  • Clean the scanner glass. 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 crop
    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 for 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 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 and
    printer settings used for the calibration. Any other combination
    needs its own calibration and color map file.

^Results^ (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

TOPIC: QUIT

+image: quit.png

This is used to exit Fotocx. A popup dialog will ask for confirmation if this option was selected in {SETTINGS}. To exit Fotocx, press the [Yes] button or the 'Y' key or the Enter key. To continue Fotocx, 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.

TOPIC: GALLERY MENU

+image: ug-gallery.png

TOPIC: GALLERY OVERVIEW
+image: image-management.png

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

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

TOPIC: 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.

TOPIC: META VIEW
+image: meta-view.jpg

Image files in the current gallery are shown together with the basic metadata used by Fotocx. If custom indexed metadata items are present, these are shown following the standard items.

TOPIC: 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 {CURRENT FOLDER}.

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

TOPIC: GALLERY SORT
+image: gallery-sort.png

Choose the sort key and ascending or descending order. The Reset checkbox resets all galleries to file name ascending.

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

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

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

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

TOPIC: GALLERY SCREEN
+image: gallery-screen.png

Select a subset of the current gallery and create an album named "gallery_screen" containing the selected image files. 
Selection options:
  all files       select all image files
  originals       original files (no version number)
  versions        versioned files (have been edited)
  last versions   last versions (or originals with no version)
  rating range    files with rating within the given range
  tag names       files having any of the given tags (comma separated)
  filename text   files with any of the given text strings (comma separated)

If "filename text" 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). See also {SEARCH IMAGES} for a more complete (and complex) image search tool.

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

TOPIC: CURRENT FOLDER
Set the current gallery from the file folder of the current image file. This is handy if you want to return to the current file gallery after displaying an album or performing a search.

TOPIC: RECENT FOLDERS
Set the current gallery from a recently used gallery. This lets you more easily go back and forth among recent galleries.

TOPIC: 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.

TOPIC: 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}.

TOPIC: 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 Fotocx 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.

TOPIC: ADD SUBFOLDER
+image: add-subfolder.png

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

TOPIC: BOOKMARKS
+image: bookmarks.png

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

TOPIC: 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.

TOPIC: MANAGE ALBUMS
+image: manage-albums.png

An album is an arbitrary sequence of images that is manually assembled from existing images. An album is a list of its member image files. The image files themselves are not copied or changed. A given image file can be a member of multiple albums, or may be present more than once within an album. Albums can be used to group images with some shared attributes, such as photos of a given person taken at different times or events, a "best photos" collection, etc. You can add and remove images in an album or rearrange their order. Once an album is made, you can call it up by name and it shows as a gallery. Keep in mind that editing an image in an album will edit the underlying image file, so any other way to view this image will show the same changes.

^Create
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.

^Rename
Choose an existing album and enter a new name.

^Delete
Choose an existing album and delete it permanently.

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

Edit an album: right-click an album thumbnail and select from the popup menu:
  • Add selected files here - previously selected files are added
    before or after the thumbnail, depending on whether the left
    or right side of the thumbnail was clicked.
  • Add current file here - works the same way.
  • Remove from album - the clicked file is removed from the album.

Add files to an empty album (no thumbnails):
  • Gallery View > Album button -> select the empty album.
  • Manage Albums > Select Files: select initial files for the album.
    When you exit Select Files with the [OK] button, the selected
    files are added to the album.

^Drag and Drop
You can rearrange images in an album by dragging thumbnails with the mouse. Drag the thumbnail until the mouse cursor changes to a small thumbnail image. Continue dragging this image to the position where it should be inserted, and release the mouse button. Position the mouse roughly between the thumbnails where the dragged image is to be inserted. If the drag approaches the top or bottom edge of the window, the gallery will scroll to bring more images into view. You can use two Fotocx sessions to make the selection or movement of many images faster. Drag and drop images from any source gallery on to a target album gallery. The source gallery can be an album or any gallery.

TIP: If image files are renamed or moved using Batch Convert, and if deletion of the original image files was also specified, then all albums containing any of the files are updated to the new file names and locations. Therefore, do not rename folders if they contain images in albums, or manually move image files among folders. Instead, use Batch Convert to move the image files to the new folder, then delete the old folder if empty. To delete image files, use Batch Delete/Trash. This will also purge deleted files from albums.

^Desktop Wallpaper
See {COMMAND PARAMETERS} ^-cwp parameter^ to use Fotocx for cycling the desktop wallpaper image using a Fotocx album or any folder with image files.

TOPIC: UPDATE ALBUMS
+image: album-replace-file.png

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

TOPIC: 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 missing.
  • Replace all with original and all versions
    All files are replaced with the original file and all versions.
  • Replace all with original version and newest version
    All files are replaced with the original file and newest version.
  • Replace all with selected versions (*)
    All files are replaced with the selected versions only.
    This includes the original (unversioned) file.
  • Replace all versions with selected versions (*)
    All 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 missing.
  • Replace all with original and selected versions (*)
    All files are replaced with original files and selected versions.

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

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

TOPIC: 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].

TOPIC: SLIDE SHOW
+image: slide-show.jpg

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

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

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

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

Main Dialog Controls
  • Caption Time
    The default time to display title and description, in seconds.
  • Image Time
    The default time to show the image alone, seconds.
  • Clip Limit %
    Images are scaled to fit window, with margins for different
    aspect ratio. If difference < clip, crop for no margins.
  • Music File
    Music file to play during the slide show (VLC required).
  • Full Screen
    If checked, images are shown full-screen without menu etc.
  • Auto-replay
    If checked, the slide show will start over after the end.
  • Random Image
    If checked, use random order. Otherwise album order.

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

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

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

Press [transitions] to start a dialog (Transition Preferences, bottom left) to select and customize the transitions between images. These include instant replacement, fade-out/fade-in, and many animated methods of image replacement (e.g. the new image expands from the center to replace the old image). Select the transitions to be used and whether they are used randomly or in sequence. The time parameter sets the duration of the transition. Times less than 2 seconds may cause problems with slow computers or large monitors. If you see fleeting gaps in the image, you need to increase the time. The preference parameters specify a relative preference which will influence how frequently the transition is used when random sequence is selected.

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

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

^Preference:^ If random image sequence is chosen, this number gives a relative preference for the image. The neutral value is 10. Enter a new value to increase or decrease the probability that this file is chosen in the random sequence of images. A value of 20 would double its frequency of choice, a value of 5 would halve the frequency. The max. value of 99 would make the probability almost 10x. A value of zero would prevent the image from being shown. This probability is moderated by logic to prevent the same image from being shown again shortly after it was shown before. The image is inhibited for a count of 1/3 the images in the album, or 10, whichever is smaller.

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 the reverse, over the
    specified time. If neither option is selected, there is no zoom.
      • zoom-in: start at normal size, magnify the image while moving
        the center to the specified position
      • zoom-out: start at magnified size at the specified center,
        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 is the main dialog 'image time' setting)
  • transition to the next image, using the specified transition
    or 'next' to indicate no preference (randomly selected).


TOPIC: MAPS MENU

+image: ug-maps.png

TOPIC: WORLD MAP
+image: map-click.jpg

This is an internet world map that can be scaled (zoomed in and out) from street level to contenent level. The map has markers (red dots) corresponding to images having geocoordinates in their metadata. Click on a marker to get a Gallery View of all the images at this location. 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 marker into multiple nearby markers. Use the mouse wheel or left/right clicks to zoom the map in/out. Drag the map to change the center. 

TOPIC: MAP REGIONS
+image: map-regions.png

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

TOPIC: MAP LOCATION
+image: map-location.png +image: map-location2.png
Input a location name (city/location and/or country) or a few leading characters, press [OK]. A picklist with matching locations will appear. Choose a location. The map will move to that location and zoom-in. If there are too many matches for the given input, add more characters to narrow the search. 

TOPIC: MAP 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.

TOPIC: SHOW ON MAP
Change to Map View and show the location of the current image. If the map area has been seen before and is now cached, the reponse time is instant. Otherwise there may be an internet delay. 


TOPIC: CUSTOM MENU

+image: ug-custom.png

+image: custom-menu.png

This enables you to collect frequently used functions from multiple menus into a single custom menu. You can also add entries to open specific image files or albums. The menu also includes script functions and plugin functions (see below). 

The last entry in the menu, Edit Menu, opens a text editor for editing the menu list itself. The menu names must exactly match the names in the Fotocx menus, but case is not significant. Custom notes and tool tips can be added by using the '#' character. 

Menu entries can take the following formats:
  # comment                     a comment that does nothing
  menuname  # comment           fotocx menu name and optional tool tip
  file filename                 open a file (e.g. $HOME/pictures/somefile.jpg)
  album albumname               open named album (gallery)

The following entries are present by default and you should not change or remove them:
   Edit Script       see below
   Run Script        see below
   Batch Script      see below
   Plugins           see below
   Edit Menu         edit this menu

TOPIC: 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.

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

The following functions are currently scriptable:

  Edit
      Retouch            brightness/contrast/color adjustments
      Rescale            change the pixel dimensions of an image
      Margins            add margins to image
      Color Mode         convert to black/white or color negative
      Area Fill          fill selected or transparent areas with color

  Repair
      Sharpen            sharpen fuzzy edges
      Denoise            reduce image noise
      Defog              remove fog/haze from an image
      JPEG Artifacts     suppress JPEG artifacts (compressed image) 
      Anti-Alias         reduce pixelation of upscaled images
      Adjust RGB         adjust colors using RGB or CMY sliders

  Refine
      Edit Histogram     edit the brightness histogram
      Flatten Histogram  flatten the brightness histogram
      Local Contrast     add contrast based on area brightness
      Amplify Contrast   amplify existing contrast to enhance details
      Global Retinex     increase color and contrast globally
      Local Retinex      increase color and contrast locally
      Saturation         adjust saturation based on brightness
      Soft Focus         produce a mixed sharp and blurred image
      Brightness Ramp    ramp brightness or color across an image

  Effects
      Outlines           convert image into an outline drawing
      Sketch             convert image into a simulated sketch
      Cartoon            convert image into a cartoon
      Emboss             add a 3D relief effect to an image
      Tiles1             convert image into square tiles
      Tiles2             convert into irregular matching tiles
      Painting           convert image into a simulated painting
      Texture            add texture to an image
      Pattern            add pattern to an image
      Dither             convert image into dots
      Engrave            convert image into black & white lines
      Set Colors         set no. colors used for each RGB color
      Shift Colors       tune colors using a slider
      Custom Kernel      apply a custom convolution kernel

TOPIC: 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.

TOPIC: 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.

TOPIC: 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.

TOPIC: PLUGINS
+image: plugins.png  +image: plugins-edit.jpg

Plugin functions are a way to use other image editors within Fotocx. You can use the image and collection management functions of Fotocx with other programs that also do edits, e.g. Gimp. You can use a RAW image editor like Rawtherapee and then perform additional edits using Fotocx.

The usage procedure is:
  1. Open the file to be processed in Fotocx (the current file).
  2. Start the plugins menu and select desired program, e.g. Gimp
  3. The plugin program starts and opens the file passed from Fotocx
  4. Perform the desired edits using the plugin program
  5. When done, save the output file with the same name as the
     input file (fotocx-plugin-file). The file .ext can change,
     e.g. .jpg --> .tiff. The parent folder should not change.
  6. Close the plugin program.
  7. Fotocx 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.

^Select 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 Fotocx, unselected areas are restored to the original state.


TOPIC: ZOOM

+image: ug-zoom.png

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


TOPIC: FILE SAVE

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

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

^New Version
Save the current image file with a new version number. File names with version numbers are formatted "filename.vNN.ext" where NN is a number 01 to 99. The 4 characters ".vNN" are inserted between the file name and extension. If the file name has no versions, version .v01 will be created. If file versions are already present on disk, then the next higher version number is used. If the file is a JPEG file, the default quality is used (see {SETTINGS}). A keyboard shortcut can be assigned to this function if desired.

^New File
The 2nd dialog shown above will open to save the current image to a selected file, which can be the original file, another existing file, or a new file. An edited image file can be saved in formats JPEG, PNG and TIFF. JPEG is normally the best option, since these are compressed to reduce space. You can choose a JPEG quality value in the range 1-100. Lower values give smaller files and less image quality. Values above 70 are hard to distinguish from 100 (highest quality, largest file size). PNG files are compressed without any loss of quality and are larger than JPEG files of the highest quality. TIFF files are compressed and larger than JPEG or PNG. TIFF and PNG files may be saved with 8 or 16 bits per color. The 16-bit formats only makes sense for files converted from a RAW format having more than 8 bits per color. It is rare that the difference between 8 and 16 bits per color can be seen with the eye. However, an image with greater bits per color has more latitude if an edit function radically alters the brightness histogram. PNG-16 files are smaller than TIFF-16 but slower to save due to the slow compression process. Saving a file as TIFF or PNG can be quite slow for a large image and a slow computer. If an image has transparent areas (e.g. a Warp function creates a non-rectangular image shape with transparent margins), you should save the image as a PNG file if you want the transparent areas to be preserved. If you use JPEG, these areas will be black and opaque. JPEG does not support transparency.

^Replace File
Save the current image file back to itself. If a JPEG file, the default quality is used (this value can be set in {SETTINGS}).

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

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

The ^permissions^ 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.

^Rough 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.

  ^file 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


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

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

TOPIC: VIEW MAIN META
TOPIC: VIEW ALL META
+image: view-metadata.jpg

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

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

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

The [Extras] button on the View Main 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.

Fotocx uses these metadata items (keys) for image editing and searching:
  Title                 short title of image
  Description           description of image
  Date/Time Original    photo date/time - normally from camera
  Rating                image rating - 0 to 5 stars
  Geotags               image location - may be from camera GPS
  Tags                  image tags (identifiers from user, for searching)
These items are edited using the function {EDIT MAIN META}

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

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

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

TOPIC: 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 Fotocx). 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.

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

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

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

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

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

^Random 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: Fotocx has a function to mass convert tag names). In this case, you can simply type tags into your images, creating new tags as needed. There is still some capability to keep tags organized: existing tags matching the characters you input are shown as soon as there are only a few possible matches. Example: you type "new" and a list of tags is shown: New York, Newman ...  If one of these is your intention, you click on it to select the tag. If not, you keep on typing and eventually press Enter to create a new tag. When searching images for tags, you can type desired tag names or pick them from the list of available tags. Available tags matching the first few letters you type are shown, and you can pick from this list. You cannot enter a search tag that does not exist somewhere in your images.

^Geotags
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 MAIN 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}
  Search by location name (also multiple names, partial matches).
  {PLACES/DATES}
  Search by country, country/location, or country/location/date group.
  Images by Map Location:
  Click on a map marker to show all images at the marker location.

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

TOPIC: EDIT MAIN META
+image: edit-meta.jpg

The Edit Main Meta function is used to add basic metadata to an image. Please read Tags Overview and Geotags Overview (above) before using Edit Main Meta.

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

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

The date of the image, if available, is shown as Image Date. This may be entered if missing, or changed. You can enter a full date in the format yyyy-mm-dd or a shorter format yyyy or yyyy-mm. A missing month/day is logically equivalent to 01/01 when compared with a low limit for searching, or 12/31 when compared with a high limit. The [Prev] button fills-in the date from the previous data entered. This is to allow easy dating of a series of images. If time is important, you can include a time using format hh:mm[.ss].

You may enter a title, description, and a rating (0-5 stars) for the image. To edit the title or description, press the corresponding [edit] button. This will pop-up a text editor with a large limit on the size of the text.

Existing tags are shown in Image Tags. Available tags are shown in the Defined Tags window below. One of these tags can be added to the image by clicking it. A tag can be deleted from the image by clicking it in Image Tags. Recently added tags are shown in Recent Tags. This is a convenience to make adding tags to a new batch of images easier, since many of the same tags will be used again. Point and click the same way.

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

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

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

The [Prev] button (at the dialog bottom) 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.

^Adding Geotags
There are several ways to add location names and geocoordinates in the {EDIT MAIN META} dialog.

Camera GPS
Your camera GPS sensor may have inserted location data, possibly incomplete. The language may not be the one you want, or all-capital letters may be used, or some other nonsense. Use the [clear] button to start over, or just re-enter the text needing revision.

[Prev] Button
If the image being edited has the same location data as the previously edited image, press [Prev] to fill the location data used before.

[Find] Button
To use a location aleady present in other image files, enter a few leading characters into Location and press [Find]. A pick-list of matching location names will pop-up. Choose one. Data for this location will be inserted. If there are multiple geocoordinates present for the same location name, the internet world map will appear showing multiple red dots. Click the red dot for the location you want.

[Lookup] Button
Fotocx comes with a file of over 40K known locations (worldcities.txt). One of these may be the one you need. Enter a few characters and press [Lookup]. A pick-list of matching names will pop-up. Choose one. Data for this location will be inserted.

Click Map Location
Use the Maps menu to open up the internet world map. Zoom-in on the location you want, and left-click with the mouse. If you click on one of the red dots marking your image locations, data from this location will be inserted. If you click on some other location, the latitude/longitude will be inserted. If the location is within 10 km of a known location (worldcities.txt), the locatioin name and country will also be inserted. Edit the text manually if correction is necessary.

Batch Geotags
You can use {BATCH GEOTAGS} to add location data to many image files at once.

TOPIC: 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 Fotocx home folder (/home/<user>/.fotocx). You can add or remove items from this list.

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

TOPIC: COPY META
Combined images created with Fotocx (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).

TOPIC: 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.

TOPIC: 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 Fotocx is started, all categories and their tag lists are sorted alphabetically, except that "nocatg" is always last.

TOPIC: 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.

TOPIC: 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.

TOPIC: 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.

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

TOPIC: 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

^Search Dialog
+image: search-images.jpg

In the dialog, select which images to search, either all (all images) or the current set, meaning the images in the current gallery list, which can be a folder, album, or the results of a prevous image search. Next, choose what to do with the matching images found: 'new set' means replace the current set with the images found, 'add' means add them to the current set (gallery), and 'remove' means remove them from the current set. To remove images, you must search the current set.

For files matching the select criteria, you may additionally specify which versions are selected: last version only, original + last version, original + all versions, or no change. 'no change' ignores file versions and selects all files meeting selection criteria - originals and/or versions. Thus you can get multiple versions of the same file in the output report. The version options depend on the Fotocx 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.

^Search 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 <fotocx home>/metadata_picklist. You can add items to this file if wanted.

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

^Wildcard 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.

^Dialog 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.

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

^search_results^ (album)
The output of Search Images is saved in the album "search_results". 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" until you do another seaarch. Rename this album if you want to keep a later search 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.


TOPIC: SELECT MENU

+image: ug-select.png

TOPIC: 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.

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

TOPIC: SELECT AREA
+image: select-area.jpg

The Select Area dialog starts with the menu Select > Select Area. Select one of the methods explained below. Each method selects image areas in a different way. You can change methods at any time, and the selected areas accumulate. An outline of the selected image area(s) is shown as you add or remove areas from the selection. The [Finish] button is used to map the image pixels within the area outlines, making them ready to apply subsequent edit functions. The [Hide] button hides the area outline, giving you better visibility of edits and possible area edge effects. Use the [Show] button to show the area outline. The [Clear] button removes all area selections. The select area dialog can be exited and re-started later to modify existing areas or add new ones.

^Methods
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 with the mouse
  • Follow Edge - outline by following image feature edges
  • Select area within mouse - select all pixels within a circle
    around the mouse. Drag the mouse to extend the selection.
  • Select one color within mouse - works as above, but selects only
    pixels matching a given color within a given match level (0-100%).
  • Select all colors within mouse (flood) - select all pixels within
    the mouse, extend the selection into adjacent areas with colors
    matching the mouse colors (this is sometimes called 'flood').

The following paragraphs explain the details of each method.

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

^Ellipse
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.

^Freehand Draw
Drag the mouse (left button down) to draw a freehand line, or left-click to connect a straight line from the last point drawn to the point clicked. Continue around the target area until it is surrounded with connected curves and lines. Right click to remove previous lines (mistakes). A right click will remove the previous clicked or dragged line, up to 50 pixels. Right click repeatedly to remove more. A new clicked line will always connect to the end of the previous line. A new dragged line will connect to the previous line if it is started close to the end of that line. If it is started elsewhere, a disconnected line will be drawn. You can start a new drag from far away and draw back to meet the previous line. If a clicked line connects to an undesired point (you don't want to connect to the last line drawn), right click to erase it and then use drag to start a new sequence of lines. A right-button drag can be used to erase line segments: right-drag closely along a line to erase it, then left-drag to re-draw the line. At the end, an area must be fully enclosed, with no gaps. Lines that overlap a little at the ends are OK. Gaps can be difficult to find and correct, so work at 100% image size or greater and be careful. A series of lines automatically connected with left clicks will not leave gaps, but deviation from this sequence is likely to create gaps. To reduce the possibility of gaps, use deliberate overlaps when manually connecting lines. There is a gap detection utility described below - {FIND AREA GAP}. If an area edge is also an image edge, you do not have to draw this portion of the area. Draw the line off the image edge, and draw it back onto the image at another position along the image edge.

^Follow 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.

^Mouse 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.

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

^Select one color within mouse
Click on the image to select a color. The color is shown on the color button. You can also use the button to set a color directly. Left/right drag to select/unselect pixels within the mouse circle that match the selected color within the match level. Adjust the match level down or up to match a greateror lesser range of colors. Click as needed on the image to change the color to be matched.

^Optional 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.

^Select all colors within mouse^ (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.

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

^Edge 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.

^Area 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.

^Show/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.

^Finish
+image: select-area-finish.png

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

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

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

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

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

^Clear
Discard the current area permanently.

TOPIC: FIND AREA GAP
If an area outline was created by freehand drawing using multiple strokes, it is easy to leave small gaps in the outline that are not visible below 4x zoom. An attempt to finish such an area will fail because the mapping of the interior pixels will leak out through the gap and cover areas outside the intended area. If the Finish function fails, this function can find the gap. Click somewhere on the outline of the failed area. The outline will be slowly re-drawn in one direction from the clicked position, until an "end pixel" is found. This is where the gap is. The outline is then drawn in the opposite direction until the gap is encountered again. The gap is where the drawing stopped. 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 can be active.

TOPIC: AREA BLEND
+image: area-blend.png +image: area-blend2.jpg

Three functions are present in this tool: mouse blend, edge blend, and edge blur. 

^Mouse Blend
Any part of the area can be mouse-painted to blend with the original or any 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.

^Edge Blend
All 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'. 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.

^Edge Blur
All edges of an edited select-area can be blurred to soften a hard or unnatural-looking edge. The 'blur width' value determines the extent of the blur. 

TOPIC: 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.

TOPIC: 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.

TOPIC: 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.

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

TOPIC: 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.

TOPIC: 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 <fotocx-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.


TOPIC: UNDO/REDO BUTTON

+image: ug-undo-redo.png

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

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


TOPIC: EDIT FUNCTIONS

TOPIC: EDIT MENU

+image: ug-edit.png

TOPIC: ROTATE
+image: rotate.png

To level a slanted image, use the mouse to drag the right or left side of the image up or down until image looks level. A left-click on the image will add vertical and horizontal guide lines to help with image leveling. Use right-click to remove them.

Use the 90º and 180º buttons to upright an image made with the camera turned. The input widget can be used to enter any angle - this spin button responds to the mouse wheel and the up/down arrow keys.

The mirror buttons flips the image left-right or up-down. Photos will never be inverted in this manner, but the user can do this if wanted.

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

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

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

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

TOPIC: RETOUCH
+image: retouch.png

Adjust image brightness and color.
  • auto black level - set black point using % darkest pixels
  • auto white balance - set white point using % brightest pixels
  • click gray spot for white balance - click gray spot on image
  • click dark spot for black level - click dark spot on image
  • click for popup graph of RGB histograms 
  • brightness - moves the 'all' curve up or down (all colors change)
  • contrast - changes the slope of the 'all' curve
  • color saturation - black/white <--> intense colors
  • color temperature - illumination balance (warm <--> cool)
  • settings file - load or save dialog settings, assign a name

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.

^Buttons
Reset - set all controls back to a neutral position - image is also reset
Prev - set all controls to the values used for the previous image
Done - finish the edit, close the dialog, save the control settings
Cancel - cancel the edit, reset the image, close the dialog

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

TOPIC: RESCALE
+image: rescale.png

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

TOPIC: 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.

TOPIC: 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
  • +Version - image with added text is saved as a new version
  • Next - open next file, put the same text at the same position
  • Apply - commit the current edit and reset for new text entry
  • 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.

TOPIC: 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 image to black and white
  • black/white negative - convert to black and white negative
  • color negative - replace each RGB color with its compliment
  • RGB -> GBR - replace red/green/blue colors with green/blue/red
  • RGB -> BRG - replace red/green/blue colors with blue/red/green
  • sepia - convert to modified black/white for an aged photo effect

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

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

TOPIC: 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 mouse over desired image areas, check results
  (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 Histogram, Flatten Histogram, Local Contrast,
           Amplify Contrast, Local Retinex, Saturation, Soft Focus
  Effects > Emboss, Texture, Set Colors, Shift Colors, Custom Kernel

See the following functions for alternative methods to make localized edits:
  {SELECT AREA}      edits confined within pre-selected areas
  {STACK/LAYERS}     combine multiple image versions in any ratio,
                     'paint' different combinations in any output area
  {COPY IN IMAGE}    copy from one image area into another area by
                     'painting' with the mouse.
  {COPY FROM IMAGE}  same as above, but source is another image,
                     and scale of transfer can be varied.

TOPIC: 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.

^Wacom 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.

TOPIC: 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 Fotocx 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.

TOPIC: AREA FILL
+image: area_fill.png
Fill all selected areas or all transparent areas with a chosen overlay color. If an area is partly transparent, the overlay color will replace the transparent fraction of the image: e.g. if the alpha channel is 100, the overlay color will have a brightness of 100/255 and the image will have the remaining 155/255. The 'Blend' slider can be used to select any mix of the original image and the overlay color.

TOPIC: 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 balloon 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 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
  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.

TOPIC: 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 Fotocx 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.

TOPIC: 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.

TOPIC: 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.


TOPIC: REPAIR MENU
+image: ug-repair.png

TOPIC: 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.

^Sharpen - 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.

Amplify Contrast: amplify existing contrast, somewhat like the Amplify Contrast 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.

^Fix 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.

^Digital 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.

TOPIC: 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.

^Normal 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.

^Radial 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.

^Directed 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.

^Graduated 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.

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

^Add Motion Blur
+image: add-motionblur1.jpg

This tool adds motion blur to an image. Motion blur is blur in a single direction. Image feature edges perpendicular to this direction have maximum blur. Those parallel to the blur direction remain sharp. Use {SELECT AREA} to isolate image areas to blur separately from the unchanged background.

TOPIC: DENOISE
+image: denoise.jpg

This function reduces the noise in photos taken in low light conditions (high ISO), making uniform surfaces appear speckled. Two methods are provided, Median and Smooth. The best method varies with noise and image characteristics. Mixing methods (using one and then another) can be helpful. The Radius value defines the pixel neighborhood that will be used to compare and adjust a given pixel. A large value (Radius > 2) will reduce the noise more effectively but may also cause loss of detail. The Limit value prevents pixels with higher contrast than this value (i.e. likely not noise) from being processed. This is automatically estimated from the image characteristics, and can be altered if needed.

Set a Radius value and press one of the method buttons. Each iteration uses the previous image as a starting point, so multiple iterations will gradually suppress the noise and possibly blur some details. Use [reset] to start over. Median with Radius 1, followed by Median with Radius 2, is a good compromise between suppressing noise and preserving detail. If you see noise that is not being suppressed, try setting a higher Limit value.

You can apply different methods and limits to different areas of the image (see {SELECT AREA}, and you can "paint" the image using different methods and limits on different areas (see {PAINT EDITS}).

Technical descriptions:
  Radius: pixels within this distance (pixels) of the pixel 
          being processed are used to compute a new RGB value
   Limit: initially: statistical variance from a sample of 
          adjacent pixel differences - can be altered
  Median: pixels are set to the median value of all pixels 
          within radius of the pixel being processed
  Smooth: pixels are set to the mean of the best-matching 
          opposing pair of pixels at distance = radius

Each RGB color is processed independently, e.g. a pixel R value is set from the R values of the chosen neighbor pixels. There is no separate processing of chroma or lightness.

The [measure] button starts the right side 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} section.

TOPIC: 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, amplify contrast, 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.

TOPIC: 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.

TOPIC: 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.

TOPIC: REMOVE HALO
+image: remove-halo.png  +image: remove-halo2.png

This function can remove halos left by sharpen, amplify contrast, 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. Select the type of halo: bright (most common) or dark. Left-drag the mouse over the halo area alter the pixels inside the mouse, as shown in the example. For a bright halo, the brightest pixels will darken as the mouse is dragged over them. For a dark halo, the pixels will brighten. Use a mouse radius larger than the width of the halo, as shown in the example. Right-drag the mouse to restore the original pixels, in case you go too far and need to do over. 

TOPIC: 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.

TOPIC: 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 reduce 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, especially in the case of a 2x upscale.

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.

Fotocx uses the Scale3x algorithm, modified to use "similar" and "different" color tones in place of "equal" and "not equal".

TOPIC: 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 Fotocx 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

TOPIC: ADJUST HSL
+image: adjust-HSL.png

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

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

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

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

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

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

TOPIC: 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.

TOPIC: FRINGES
+image: fringes.png   +image: fringesA.png

Fix pheripheral color fringes (lateral chromatic aberration) - where color fringes appear mainly in outer image areas.

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.

^Method:
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 is the original distance from center
  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.


TOPIC: REFINE MENU

+image: ug-refine.png

TOPIC: EDIT HISTOGRAM
+image: edit-hist.png   +image: RGB-hist.png

Edit Brightness Histogram directly edits the shape of the brightness histogram. Move the sliders and watch the image to find the optimum settings.

Cutoff: If the histogram is low or zero at the dark or bright end, you can stretch the histogram 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 histogram is made 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.

TOPIC: FLATTEN HISTOGRAM
+image: flatten1.png +image: flatten2.png

Flatten Brightness Histogram increases visible detail in areas having poor contrast. Pixels with little brightness difference compared to their neighborhood are adjusted to increase the difference. A smaller radius will intensify the effect. Adjust radius and press [apply] to updae the image. Use the flatten slider to adjust the overall intensity of the effect. The moderate slider can be used to soften the most extreme changes. If some areas (esp. sky) become mottled, use {SELECT AREA} or {PAINT EDITS} to restrict the area being flattened.

^Technical Explanation
The brightness of a pixel is compared to the brightness histogram of the surrounding area, and the brightness is adjusted up or down in the direction that would flatten the histogram 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 a smaller area, and the effect on the image is more dramatic.

TOPIC: LOCAL CONTRAST
+image: localcon.jpg  +image: localcon2.jpg

Local Contrast increases the contrast in every area of an image, using the average brightness of an area to determine how much individual pixel brightness values are to be increased or decreased. This function implements a widely used textbook method. Radius controls the size of the area around each pixel that is used for the average brightness value. Power determines the strength of contrast change. Color is used to increase the color saturation. The resulting image may become too dark in the darkest areas. You can use the editable curve to brighten the output image for any selected brightness range. The example shows brightening of the darker areas of the image. 

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.

TOPIC: AMPLIFY CONTRAST
+image: amplify-contrast.png   +image: amplify-contrast2.jpg

Amplify Contrast 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. Amplify Contrast 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. Amplify Contrast can bring out the subtle details (low contrast) that would otherwise be hard to notice. Other methods can also be used: {RETOUCH} can increase contrast for a selected brightness range (at the expense of others). {FLATTEN HISTOGRAM} can spread available contrast more evenly. Amplify Contrast 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.

TOPIC: 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.

TOPIC: 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.

TOPIC: 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.

TOPIC: 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 Fotocx 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.

TOPIC: 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 area.
     The resulting mouse circle is the spot area to be sampled.
  2  Open the 1st image by pressing the [open] button. If the
     current image is the one you want, this can be skipped.
  3  Click on the image to take a color sample.
     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.

TOPIC: BRIGHTNESS 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.

TOPIC: 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.

^Irregular 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


TOPIC: EFFECTS MENU

+image: ug-effects.png

TOPIC: OUTLINES
+image: outlines1.png +image: outlines2.jpg

This function transforms a photo into an outline drawing. High-contrast pixels are intensified and low contrast pixels are suppressed. The threshold setting sets the contrast thresholds. Lines below the minimum are not shown, and those higher than the maximum will have maximum brightness. The 'black/white' checkbox converts colored lines to black over white or white over black, depending on the 'negative' checkbox. Use 'Low Amplify' to brighten faded lines if wanted. 'Mode B' results in a more uniform line brightness compared to 'Mode A'. 

TOPIC: 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. Reducing the size of the input image may give interesting results. It may be important to minimize noise ({DENOISE}) before conversion into a sketch. 

TOPIC: CARTOON
+image: cartoon.jpg

Transform a photo into a cartoon-like drawing. Black lines are drawn over feature edges in the image, wherever the brightness or color changes abruptly. Line Threshold sets the sensitivity for edge detection and line drawing, causing fewer or more lines to be drawn. Line Width makes the lines thicker or thinner. 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, amplify contrast, set colors, texture, warp curved. '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.

TOPIC: 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.

TOPIC: 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.

TOPIC: 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.

^base size
The tile base size, which is the unit tile size used to make larger tiles.

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

^tile area goal
The upper limit of tile size (area in pixels).

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

TOPIC: 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.

^blur radius
Blur the image before processing. This results in smoother boundaries.

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

^patch 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.

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

^borders
Determines whether the colored areas will be delineated with a thin black border, like irregular tiles in a mosaic. After using this function, using {EMBOSS} can add interesting texture to the image.

^performance
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.

TOPIC: 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.

TOPIC: 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 <fotocx-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 to add a 3-D effect to the pattern.

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

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

TOPIC: DITHER
+image: dither1.png

+image: dither2.jpg

This function provides several ways to dither an image - convert into dots.
  0 - colored dots in the style of Roy Lichtenstein
  1 - pure R/G/B or black/white with random or optimized spacial distribution
  2 - RGB mix using a given bit depth
  3 - classic dither using a custom color palatte
  4 - condense image into blobs with mean color 

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.

Blobs: Image pixels undergo a kind of "gravitational collapse", converging into clumps around local centers of mass. 'Mass' is defined as pixel brightness. The 'radius' control roughly defines the range of attraction. Press [apply] to make the pixels converge a small amount. Do this multiple times, until equilibrium is reached with the blobs roughly the size of the 'radius' input. If radius is large and the image is large, considerable time may be needed.

TOPIC: ENGRAVE
+image: engrave.png  +image:engrave2.png

Convert an image into black & white lines roughly conforming to brightness.

The Size input determines line thickness and how many vertical image pixels are used for each vertical pixel column in the output lines. The line pixel columns are split into black and white parts with their proportion roughly matching the mean brightness of the input pixels.

The Bias input can be used to make the overall image darker or brighter, whatever gives the most pleasing result. Negative/positive values make the image darker/brighter.

The Color input (0-100%) can be used to add color to the white parts.

TOPIC: MOSAIC
+image: mosaic1.png  +image: mosaic2.jpg

Create a mosaic image using tiles made from all your images.

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

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

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

TOPIC: 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.

^Suppression 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.

TOPIC: SET COLORS
+image: set-colors1.jpg +image: set-colors2.jpg

You can reduce the number of colors used in the image to create a poster effect. Set each RGB color separately, or adjust the total colors up or down. The latter will add or remove colors from each RGB color equally. Color bit depth is not used for this. Some other functions in Fotocx use bit depth, limiting available colors to 2, 4, 8, 16, etc. for each RGB color. This function is not limited in this respect. You can choose any number of colors: 1, 3, 9, 13, etc. for each RGB color. The example above uses 8 red, 5 green, and 3 blue colors. 

TOPIC: 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.

TOPIC: 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). Press [Apply] to get a new color distribution. Press [OK] when done, or [X] to quit.

TOPIC: 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.


TOPIC: WARP MENU

+image: ug-warp.png

TOPIC: 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.

TOPIC: 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.

TOPIC: WARP IMAGE
+image: warps4.jpg

TOPIC: 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.

TOPIC: 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.

TOPIC: WARP LINEAR
This function is useful to correct perspective problems (see also Unbend). Drag the image from any position, using the mouse. The entire image will be pulled or pushed in the direction of the mouse, but areas near the mouse are moved more than more distant areas. The control 'warp span' determines the reach of image warping. 1.0 means the full image is warped, and smaller values confine the warp to smaller areas. The warping is linear: the image is squeezed in a way that straight lines remain straight. The 'curl' factor (0.1 to 20) multiplies the warp amount by this power (neutral value = 1). Values > 1 make the warp greater near the mouse and less at increasing distance. Values < 1 do the opposite.

TOPIC: 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.

TOPIC: WARP RADIAL
+image: warp_radial.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.

TOPIC: 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.

TOPIC: 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.

TOPIC: 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.

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

TOPIC: 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.

TOPIC: 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.
  • Cut Top: remove a top margin from the input image.
  • Cut Bottom: remove a bottom margin from the input image.
  • Reverse R: mirror the input image vertically.
  • Reverse Theta: mirror the input image horizontally.
  • Rotate: turn the output image around the center.

TOPIC: 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.

TOPIC: FLATTEN PHOTO
+image: flatten-photo1.png  +image: flatten-photo2.jpg

{Book page or other curved surface
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.

Select the upper trace option to trace the upper edge of the curved page. Click the mouse along the edge, creating a 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 edge. Select the lower trace option and trace the bottom edge in the same manner. When both are done, 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.

+image: flatten-photo3.jpg

{Curved horizon
A wide panorama, or a photo from a wide-angle lense, may have a horizon that is not straight or horizontal. The image can be straightened (or otherwise moved) by tracing a curve through the horizon or other areas that need to be aligned along a straight line. Select either the upper or lower trace option, depending on whether the horizon (or other image part) lies mostly above or below the image middle. The image will be warped to make this curve straight. One curve is enough. The other curve is added automatically to the opposite edge (top or bottom) of the image. If the result is not satisfactory, use the [undo] button, adjust the markers on either curve, and try again. You can also save the image and apply the function a second time, using the saved image as a starting point.


TOPIC: 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.

TOPIC: HDR
^High Dynamic Range
+image: HDR-adjust.png  +image: HDR.jpg

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

Select the HDR menu function and select up to 9 images ({SELECT IMAGE FILES}), which must all have nearly the same pixel dimensions. The images are aligned and combined automatically. This needs 10-30 seconds per image, depending on image size and CPU speed. When done, the combined image is shown, along with a dialog for adjustments. The contributions from the input images are shown as a series of editable curves. The horizontal scale represents pixel brightness, from dark to bright. Each curve represents an image which contributes to the pixels. The image contribution at a given brightness level is proportional to the height of its curve at that level. The initial curve for the brightest image will be high on the left and low on the right, meaning high contribution to dark pixels and a low contribution to bright pixels. The darkest image will be low on the left and high on the right, and remaining images in-between. The curves can be edited by dragging them with the mouse. The corresponding image contributions are changed accordingly, and you can see the results in real-time in the output image. In general, the brightest image should have a higher contribution to the darker pixels, and the darkest image a higher contribution to the brighter pixels. The above example shows two input images and their output image. The curves were adjusted to optimize the brightness for both the foreground and background buildings. It is often useful to apply the {AMPLIFY CONTRAST} function after HDR, to increase the perceived brightness range.

TOPIC: HDF
^High 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 Fotocx, but this may require considerable time. It is better to avoid the problems.

+image: HDF-paint.png

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

Suggested Workflow: Using paint mode, choose each image in sequence and paint all areas that look sharp in that image. Any boundaries that are not aligned well will show up clearly as shifts in the edges of objects in the image. Some of these can be made unimportant by changing the image used for painting (if more than one image is sharp enough). Using warp mode, make fine adjustments as needed to eliminate visible shifts.

TOPIC: 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 Fotocx, 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.

TOPIC: STACK/NOISE
+image: stack-noise2.jpg  +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 Fotocx, 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 Fotocx, 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.

TOPIC: STACK/LAYERS
+image: stack-layers.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 an equal blend of all input images. Image Ratios are the relative weights of the blended images. These can be adjusted to vary the weight of each image. Example: if 3 images are combined with relative weights of 3, 5, 7, then the combined image is 3/15 from image #1, 5/15 from #2, and 7/15 from #3. If the option "Paint entire image" is selected, the weights can be adjusted and the output image responds immediately. If the option "Paint within mouse" is selected, then the mouse can be dragged and only the area within the mouse circle is painted, using the image ratios currently active. The paint speed is controlled by the Power settings for the center and edge of the mouse. Use low numbers to paint gradually.

TOPIC: 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.

TOPIC: 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. Fotocx 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 'File Color' button to restore brightness levels from the underlying image files.

The 'Blend Width' control governs how the images are blended together: at the image overlaps, brightness is changed over this many pixels, to mask imbalances that cannot be fully corrected. The default is 1 pixel, which makes any brightness difference look obvious.

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

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

When done, use {UNBEND}, {WARP IMAGE}, {CROP} etc. for final adjustments.

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

^Auto Warping
The images are slightly warped in various directions during alignment to find the best match. This is to compensate for shifts in camera horizon or rotation, causing image distortions that reduce the quality of fit. If the overlap area of two images includes a large object that moved in or out between the two photos, the alignment process may go crazy trying to match the images, making alignment very poor. By selecting no auto warp you may be able to get the alignment to succeed or have a smaller error. Another option is to select manual align.

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

^Panorama 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.

^Vertical Panorama
This can be done by rotating the input images 90 deg. so that top is on the left. In Panorama, choose the images in order top to bottom, so that the top image is on the left and bottom is on the right. Do the panorama normally. Rotate the output image clockwise so that left becomes top.

TOPIC: 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.

TOPIC: MASHUP
+image: mashup.jpg

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

+image: mashup1.png

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

+image: mashup2.png

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

+image: mashup3.png

Use this dialog to select and place images on the layout and revise their appearance: size, rotation, position, transparency. An image may be partly or wholely transparent, overall or within specified areas. This means that the background image or overlapped image can show through transparent areas. The Add Image button leads to a gallery file selection dialog ({SELECT IMAGE FILES}). Selected images are placed on the layout. After the images are added, click on any image to select for modifications. Drag the image from the middle to position the image in the layout. Drag the lower right corner to resize the image. Use the dialog controls to adjust the image. The dialog controls operate on the last image added, clicked or dragged. The 'Prev' and 'Next' buttons cycle through the images one at a time, flashing the selected image. This can be used when overlapped images make it difficult to select the desired image by clicking it. Scale rescales the image. Angle rotates the image. The Stacking Order buttons raise or lower an image relative to other images - this determines which overlapping image will be on top. Base Transparency is used to make an entire image partly transparent. The [paint] button is used to make any part of an image partly or fully transparent, using the Paint dialog shown below. The [warp] button is used to bend or warp an image, using the Warp dialog shown below. The 'black margins' checkbox can be used to remove black margins left by other edit functions, e.g. warp. These will be made transparent. The 'Image is fixed' button will prevent the image from being moved by the mouse or KB. This is helpful when images are being fine-aligned and accidental movement should be prevented (can happen when working fast with mouse clicks and drags). The Margins controls can be used to make image edges transparent. The Hard margins cut off image edges. The Blend margins make the edges partly transparent to blend them into the background or other overlapped images.

+image: mashup4.png

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

+image: mashup5.png

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

+image: mashup6.png

The Edit Text dialog is used for placing text on the layout. Enter some text and press Apply. 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 OK 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.

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

^Mashup Rescale
Working with a very large layout (over 20 megapixels) can be quite slow, especially if the 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.

TOPIC: 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 <fotocx home>/image_array_maps/.

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


TOPIC: 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.

TOPIC: BATCH CONVERT
+image: batch-convert.png

This function is used to rename, convert, rescale and move multiple image files at once.

Dialog Inputs
  • Select Files - files to convert ({SELECT IMAGE FILES}).
  • Replace Text - replace text string in file names (see below).
  • New Name - Optional new name, inserted text (see below).
  • Sequence Numbers - Base number and adder for output file names.
  • New Location - Optional new folder location for output files.
  • new file type - File type for output files, or "no change".
  • color depth - specify 8 or 16 bits for tif or png output.
  • max. width, height - Size limits for output files.
  • delete originals - Delete input files if successful conversion.
  • copy metadata - Copy all metadata to the output files.

^Replace 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.

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

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

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

Either "$oldname" or "$s..." must be present to insure output file names are unique. If New Location is missing or unchanged, delete originals is ignored. If an output file already exists, the input file is not converted.

^Albums
If image files are renamed or moved using Batch Convert, and if deletion of the original image files was also specified, then all albums containing any of the input files are updated to reflect the new file names and folder locations.

^Preserving 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.

TOPIC: 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 Fotocx. 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.

TOPIC: BATCH UPRIGHT
+image: batch-upright.png

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

TOPIC: 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.

TOPIC: 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.

TOPIC: 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 <fotocx home>/saved_areas, but any folder can be used. This image can now be used as an overlay image for Batch Overlay.

Use the ^Select host image files^ button to select the host image files to receive the overlay image. Use the ^Select overlay file^ button to select the overlay image file.

The two ^Overlay position^ 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 ^Overlay width^ as a percent of the host image width. The height will be set to conserve the width/height ratio. If ^Make width constant for window size^ 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 ^refresh^ to set the current window if this has changed.

If ^Replace host files^ is selected, the input host files are replaced with the output overlaid host files. If ^Make new versions^ is selected, new versions of the input host files are created.

TOPIC: 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 MAIN 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.

TOPIC: 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 Fotocx is started, the index file function will update all thumbnails for the same images, because the file modification date has changed.

TOPIC: BATCH PHOTO DATE
+image: batch-photo-date1.png  +image: batch-photo-date2.png

This function lets you quickly fix a batch of photos that have no photo date/time or an incorrect one. Use the [select files] button to open a gallery window where you can select the image files to process ({SELECT IMAGE FILES}).

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

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

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

TOPIC: 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 <fotocx-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.

TOPIC: 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.

TOPIC: 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.

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

TOPIC: 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 Fotocx. 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.

TOPIC: EXPORT FILES
+image: export-files.png

This function copies selected image files to another folder. The intended use is for copying files to share with others, e.g. uploading files to a photo web site. The output files are JPEG. Options: downsize, export metadata. 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. These are: photo date, keywords (tags), copyright, title, description. 

TOPIC: TOOLS MENU

+image: ug-tools.png

TOPIC: INDEX FILES
+image: index-files1.png

Fotocx 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. Fotocx also creates thumbnail images so that the gallery windows (thumbnail pages) will work fast. Fotocx 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 Fotocx 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 a few hundred to >20K files per minute, depending on computer speed, disk speed, and average file size. 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 {FOTOCX PERFORMANCE} topic.

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

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>/.fotocx/thumbnails, or set your own location. The folder name must end with /thumbnails, and this will be added to your selection if needed. The folder is created if not already present.

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

^Index 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.

^Fotocx 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 data is 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 Fotocx with a selected image file, and you want the image to open instantly. See the {SETTINGS} topic immediately below for more information.

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

^Removable 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, Fotocx can be used with the removable drive mounted or not mounted, and nothing will be lost. If you operate Fotocx without the drive mounted, the image files on this drive will disappear from Fotocx view. When the removable drive is mounted again, and Fotocx 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.

TOPIC: QUICK INDEX
Perform a quick incremental index in the current Fotocx session with no user inputs. If image files are updated while Fotocx is running, the Fotocx 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 Fotocx 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.

TOPIC: SETTINGS
+image: settings.jpg

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

  • Startup View - initial display when Fotocx is started
    • Recent Files Gallery: the most recently seen image files
    • Newest Files Gallery: files most recently added/modified
    • Specific Gallery: the specified folder gallery
    • Album Gallery: the specified album gallery
    • Previous Gallery: gallery last used in the prior session
    • Previous File: file last viewed in the prior 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
  • Zoom Speed - Choose 1-8 clicks or [+] keys per 2x image increase
  • Pan Mode - Drag: image moves with the dragged mouse
             - Scroll: image moves against the mouse
             - Fast: image moves 2x more than mouse
  • JPEG files - quality level 1-100, default 90, 70+ for good quality
  • 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 node is clicked or dragged)
      Use a higher value for touchpads, because less precise control
  • Map Markers - pixel size of the red dots marking image locations
  • Overlay Text - line wrap limits for text displayed on image
  • Image Position - position image left/center/right in wider window
  • Confirm Exit - popup dialog option: you really want to quit?
  • Index Level - set the index level depending on Fotocx context
       Default values in parentheses - See below for explanation
  • Log Level - quantity of log messages in terminal or log file:
       error messages only, + information messages, + dialog inputs
  • RAW Loader - shell command for loading RAW files - see below.
  • RAW Options
       edit commands - change or add shell commands - see below.
       use embedded image colors (camera maker colors) - see below.
  • RAW Files - customize this list to match RAW file types used
  • Video Files - customize this list to match video file types used
  • Video App - shell command for playing video files - see below

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

^Overlay 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.

^Image 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.

^Image 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 Fotocx startup.

Fotocx 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.
  • The first startup after a reboot needs more time than following
    startups, which are faster because data remains cached in memory.
    First startup time with a 5400 rpm disk is roughly 2 seconds
    per 10K image files. Following startups are 2-3x faster. First
    startup with an SSD disk is roughly 1 second per 20K image files
    (on a strong PC). These numbers assume zero new (not yet indexed)
    image files.

If you start Fotocx 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 Fotocx indexes when started
    from a menu, launcher or command. The 'file manager' parameter
    controls how Fotocx 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 not included.
  • 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.

^RAW 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 Fotocx edit functions to edit and optimize the file, e.g. reduce noise, adjust color, fix barrel distortion, etc. The default RAW loader is dcraw using the sRGB color space. A few other options using dcraw or rawtherapee are supplied in the pick list. These commands are kept in the file 'raw_loader_commands' in the Fotocx 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}).

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

^Video 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

TOPIC: KB SHORTCUTS
+image: KB-shortcuts.png +image: KB-shortcuts2.png

This function is used to view or change custom keyboard shortcuts. Currently assigned shortcuts are shown in the first window. If you press the [Edit] button, the second dialog is shown, where you can add and change keyboard shortcuts. Enter a new shortcut using the keyboard. You can use the keys A-Z, 0-9, F2-F9, and most of the symbols (% $ & * < etc.). You can combine a key with one of Ctrl/Alt/Shift: Press and hold ONE of Ctrl/Alt/Shift, then press the key, then release both. Select one of the available menu assignments from the list on the right. Remove a shortcut by selecting it and pressing [Delete]. Press [Done] when you are finished. [Cancel] will discard all changes.

TOPIC: RGB HISTOGRAM
+image: RGB-hist.png

This function opens a small window that shows a brightness histogram 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.

TOPIC: 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.

TOPIC: 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)

TOPIC: 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.

TOPIC: GRID SETTINGS
+image: grid-lines.png

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

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

TOPIC: DARK/BRIGHT PIXELS
+image: dark-bright-pixels.png

This function is used to highlight the darkest and brightest pixels in an image. Adjust the two spin controls 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 rapidly "blinked" to make them stand out. The image responds quickly to changes in the sliders. You can use this function in parallel with edit functions to check for brightness clipping.

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

TOPIC: FIND DUPLICATES
+image: find-dups.png

Find duplicated image files anywhere within your image database. A duplicate image file can be an image file that exactly duplicates another image file, or an image file that "almost" duplicates another. For the sake of speed, thumbnail images are compared in memory. Hence it is possible that identical thumbnails are found for which the main images have some minor differences that do not show up in the thumbnails. An image copy that was reduced in size is likely be classified as a duplicate. Thumbnail size can be set from 32 to 512 pixels (max. width or height). A larger size reduces the probability of false positives. The thumbnail size greatly affects the amount of main memory required - e.g. for 100K images, size 64 needs about 880 MB, whereas size 256 needs about 14 GB. memory required is roughly:
    size x size x 0.75 x 3 x (image count)
Press the calculate button to calculate the largest thumbnail size (for the shown file count) that can fit within the free memory available.

Two parameters are used to set the sensitivity for detection of identical or nearly identical images: pixel difference is the RGB value difference below which pixels are considered equal. Set to 1 to detect any pixel difference. Pixel count is the number of different pixels below which two images are classified as duplicates.
  example: if pixel difference = 2 and pixel count = 10, then images are
  classified as duplicates if fewer than 10 pixels differ by 2 or less.

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

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

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

TOPIC: SHOW RESOURCES
+image: resources.png

Report the computer resources used by Fotocx:
  • CPU time: usage since Fotocx startup or since the last sample
  • Real memory: the real memory currently in use (excluding swap)
  • Maps cache: cached map tiles and MB of disk storage used
  • Clear cache: delete all cached map tiles
  • [Sample] button: take a new sample and report the data
The [Sample] button resets the CPU time. The next sample will show only new accumulated CPU time. The CPU time is the time for all process threads. If a function uses multiple parallel threads executing on multiple CPU cores, the measured CPU time may greatly exceed the elapsed time. 4 parallel threads running on 4 CPU cores for 1 second accumulate 4 seconds of CPU time.


TOPIC: HELP MENU

+image: ug-help.png

  • User Guide
      table of contents
  • Video Tutorial
      Show a Fotocx video tutorial on YouTube.
  • Outboard Programs
      List optional outboard programs and provided functions.
  • Log File
      Display log file with information and error messages
      (same data visible if Fotocx is run in a terminal).
  • Command Params
      Show available command line parameters
  • Change Log
      Show additions and bug fixes in the current release.
  • Copyright
      Show copyrights and licenses relevant for Fotocx
  • Privacy
      Privacy policy
  • About
      Show installed release number, contact, executable.
  • Home Page
      Show the Fotocx home page on https://kornelix.net
  • Uninstall
      Delete application files and optionally user data files.


TOPIC: OTHER TOPICS

TOPIC: 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.

TOPIC: 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 Fotocx functions listed below to select and copy image files to the desktop or any other folder. From there, use the photo website's native browser interface to upload the image files.

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

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

^Privacy Warning
Photos contain metadata you may not want to make available to others.
Please review the information at
   ^https://gitlab.com/fotocx/fotocx/wikis/privacy

TOPIC: MOVE FOTOCX HOME
The default location for 'fotocx home' is  /home/<user>/.fotocx (like most Linux apps). This folder is where Fotocx data is kept, including index data and user settings. If you have any of the following conditions, you will need to move 'fotocx home' to a folder outside of /home/<user>, typically on a mounted volume.
  • multiple installed Linux systems which need to share Fotocx data
  • multiple user accounts which need to share Fotocx data
  • Fotocx data should be retained after a new Linux install

In the following, "/<mount-point>/fotocx" means the new Fotocx home folder.

  1. Set the current folder to your normal home folder:
       $ cd $HOME
  2. Create the new Fotocx home folder:
       $ sudo mkdir /<mount-point>/fotocx
       $ sudo chown user:user /<mount-point>/fotocx
  3. Copy Fotocx files to the new home folder:
       $ cp -p -R  .fotocx/* /<mount-point>/fotocx
  4. Edit the file /<mount-point>/fotocx/image_index_*/image_folders
       from: /home/<user>/.fotocx/thumbnails
         to: /<mount-point>/fotocx/thumbnails
  5. Create a pointer file to the new home folder:
       - gedit .fotocx-home
       - file content (1 line only): /<mount-point>/fotocx
  6. Rename the old Fotocx home folder (to disable) and test Fotocx:
       $ mv .fotocx .fotocx-old
  7. After testing that everything works, remove the old home folder:
       $ rm -R .fotocx-old

See {COMMAND PARAMETERS} -home parameter if you want multiple Fotocx image collections, managed separately.

TOPIC: 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.

^Relevant links
{EDIT MAIN META}  {BATCH TAGS}  {BATCH RENAME TAGS}  {BATCH GEOTAGS}  {BATCH CONVERT}   {SEARCH IMAGES}  {PLACES/DATES}  {TIMELINE}  {INDEX FILES}  {MANAGE ALBUMS}

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

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

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

^Folder 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 Fotocx to find files by searching for years and topics (in file names). In the above example, a search for "spitzbergen" or even "spitz" will produce all the images of Spitzbergen. Years can be also be searched and combined with topic searches, e.g. "2012 Paris". The Batch Convert function lets you rename a batch of photos taken at one location or event by specifying a template name like this:
   "$mm.$dd Spitzbergen $ss"
Month and day (from the EXIF photo date) replace $mm and $dd. "Spitzbergen" replaces the camera file name (P00123456), and a sequence number replaces $ss.

^Titles 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 MAIN 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.

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

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

^Geotags
Use geotags to assign a city or location and country to your images, and optionally latitude/longitude. This enables all images for a location to be quickly found. If you use a camera with a GPS receiver, geotags are added to the image EXIF data, and location searching is available automatically. Since
image dates are also automatic (in EXIF), images can be searched by date range and location without you having to enter any data for each image. You can leave it at this, or add some of the above extras if you accept the extra effort required. My experience so far with in-camera GPS is that the location names are chaotic and you may want to sanitize them (mixed upper/lower case, with/without states or other subdivisions, mixed languages, etc.). You can fix the mess with a little effort: search for the location name you want to change (e.g. MUENCHEN, BAYERN, DEUTSCHLAND), then process the resulting images with the {BATCH GEOTAGS} function to change location names (e.g. Munich, Germany). Location names can be searched in any combination.

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

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

^Albums
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.

^Summary
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 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 using a file search utility
  • you may end up with hundreds of galleries with a few images each
  • search by: topic (using folder and file names)
  • no overview of available search topics

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

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

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

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

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

TOPIC: PRIVACY
^Summary: Fotocx does not collect or share personal data.

^Image Metadata
To enable fast image searching based on metadata, Fotocx saves key 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 Fotocx or other tools. To prevent this, you can use Fotocx to clear metadata from images before uploading them. See {DELETE META} and {BATCH CONVERT}. 

^Your Public IP Address
If you download a Fotocx installation package from the Fotocx 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/fotocx/fotocx/-/wikis/privacy

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

TOPIC: LOG FILE
Fotocx 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 Fotocx session using the menu Help > Log File. The file is replaced with each new Fotocx startup. To view after a Fotocx session: $ cat $HOME/.fotocx/fotocx*.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 fotocx, 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 Fotocx crashes, it is usually able to produce a backtrace dump before exiting. This is a file named "zappcrash". Fotocx adds this file to the Log file and copies them to your $HOME folder to make them easier to find. Look for "fotocx-*.log" in your home folder and send this to mkornelix@gmail.com.

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


TOPIC: TECHNICAL TOPICS
Additional technical topics can be found on the Fotocx web site: ^https://kornelix.net

TOPIC: FOTOCX LIMITATIONS
• 1 million indexed image files - Fotocx has been tested with 680K files.
• image size - The max. supported image width or height is 50K pixels.
  The maximum practical image size is 400 megapixels (6.4 GB memory).
  (images edited in memory use 4 floats (16 bytes) per pixel, RGBA).
• image versions - up to 99 versions for undo/redo and 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 currentl thumbnail size is larger than
  256 pixels. Gallery size limits also apply to search results, albums,
  and reports. You are notified with a popup message if a gallery is
  truncated. The limits for 360 and 512 pixel thumbnails are 64K and 35K
  files respectively.

TOPIC: RUNNING OUT OF MEMORY
Fotocx 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 Fotocx process without warning and with no message (this is to keep the operating system itself from crashing). What you see is that the Fotocx window vanishes. Fotocx 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 Fotocx window vanishes, check the log file after restarting, and check for the message "killed", which is all you get from the Linux OS.

Fotocx 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 Fotocx 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 yourself. 

TOPIC: 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 Fotocx home folder resides. When you open a new image or quit Fotocx, the disk space is recovered. If Fotocx crashes, the space is recovered the next time Fotocx is started.

TOPIC: 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 no 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).

^Hard Links
Fotocx 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 Fotocx, only the index entry and thumbnail for the access path that was used is updated. Others become invalid.

TOPIC: 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, amplify contrast) because the results cannot be rescaled for a larger image.

TOPIC: SUPPORTED FILE TYPES
Fotocx 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}.

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

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

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

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

TOPIC: 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 Fotocx 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.

TOPIC: 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

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

TOPIC: 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.

TOPIC: 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.

TOPIC: 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.

TOPIC: 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.

TOPIC: INTERPOLATION METHOD
+image: interpolation.png

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

TOPIC: JPEG COMPRESSION
If a JPEG file from a digital camera is saved with Fotocx, you will likely notice a large reduction in file size, even if a high JPEG quality level is used. This is because Fotocx 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.

TOPIC: JPEG IMAGE DETERIORATION
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 (Fotocx default), each time opening and saving the previous image file. There are small differences in the RGB values but they cannot be seen. The images are 1x size and the small cutouts are 3x.
+image: jpeg-quality.png

TOPIC: METADATA ERRORS
Cameras (esp. older ones) do not always produce structurally correct metadata, and the program exiftool (used by Fotocx to manipulate metadata) may produce error messages. I have been able to fix these cases by saving the image file over 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.

I have encountered some metadata (image descriptions, captions) with invalid utf8 characters. Invalid characters are automatically replaced with '?'.

TOPIC: NEWLINE CHARACTERS IN METADATA
When editing metadata image descriptions, if you need to align text columns, you can use the [enter] key to force new lines. These are converted to backslash + 'n' before being stored in image metadata, since newline characters are not allowed (they are converted to periods). If the text is viewed or edited again, these substitutions are converted back to new lines, so that the original text alignments are restored. THIS IS NOT STANDARD, so don't expect the text to remain aligned if viewed with other image viewers. If this is a requirement, then don't use the enter key to make new lines when entering long text - just let the text overflow to the next line by itself. In this case, column alignment is not possible.

TOPIC: DIALOG WINDOW POSITIONING
For commonly used dialogs, Fotocx 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.

TOPIC: FOTOCX PERFORMANCE
Fotocx was written in C/C++ for maximum execution speed. Every effort was made to develop fast algorithms. Classic methods were sometimes compromised to attain greater speed, but not if results are compromised. Time-consuming algorithms use multiple threads for greater speed. Using a fast CPU with many SMP cores is therefore important for performance.

Fotocx has four significant performance limitations:
  • Indexing new image files found at Fotocx 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, Fotocx searches all declared top image folders to update thumbnails and the metadata index. The processing speed for NEW image files can range from a few hundred files per minute for a slow computer and slow spinning disk, or >20K per minute for a fast computer and fast SSD disk. "NEW" means any file that was added or modified (not by Fotocx) since the last time Fotocx was started. 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, or >20K/sec. for a fast SSD disk. This is for the first Fotocx 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 Fotocx startup time under 1 second (see {SETTINGS}). Use this option for files selected in a file manager (Nautilus etc.), to display the file 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 needs 1-2 minutes, whereas searching for indexed metadata is under 1 second. Metadata items you need to search often should be included in the list of indexed metadata.

Fotocx can edit images up to about 400 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.

^Benchmarks

Computer: 6 P-cores + 8 E-cores, 4 GHz
Disk: HDD (5400 rpm) and SSD (>1 GB/sec) 
Image files: 72K files, 183 GB

^Test                          HDD         SSD
full image index              83 min      208 sec
initial startup -x1           5.5 sec     1.0 sec
subsequent startup            0.4 sec     0.4 sec
initial startup -x2           8.0 sec     3.3 sec
subsequent startup            2.3 sec     2.3 sec
initial metadata search (*)   19 min      30 sec 
subsequent search             28 sec      28 sec

Subsequent tests are faster because file data from the initial test is cached by the OS and is accessed much faster.

-x1: without search for new or modified files
-x2: include search for new or modified files
(*) Non-indexed metadata. Searching for indexed metadata is normally less than 1 second. 

Index, startup, and search times are nearly proportional to the number of image files, e.g. double the files means double the time.

TOPIC: E-CORES AND HYPERTHREADS
E-cores are marginally useful for Fotocx. Hyperthreads seem to be useless. Enabling E-cores (BIOS setting) added about 32% to indexing performance on my computer with 6 P-cores and 8 E-cores. Enabling hyperthreads added nothing more to this. The constant NSMP (set in fotocx.cc) determines the number of threads Fotocx uses for CPU-intensive functions.

TOPIC: FOTOCX PACKAGES
This is where Fotocx installs its files:
Source package ($ sudo make install)
  /usr/bin/                          executable file (fotocx)
  /usr/share/applications/           desktop file
  /usr/share/fotocx/                 user guide, images, default data
  /usr/share/doc/fotocx/             change log, license, copyright
  /usr/share/man/man1/               man page

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

The binary package is a distro-agnostic package which includes some libraries used by Fotocx, but only those likely to vary depending on Linux flavor and release date. This package should run OK on most recent flavors of Linux. If it fails to start, check the log file for missing library files and install them using your package manager. Start Fotocx from a terminal to see the log file.

TOPIC: FOTOCX HOME FOLDER
  • Fotocx Home: folder for user preferences, settings and general data
  • Default Fotocx home location:  /home/<user>/.fotocx/
  • If Fotocx home was moved (see {MOVE FOTOCX HOME}), the file
      /home/<user>/.fotocx-home  contains the location of Fotocx home.
  • The files in Fotocx home are preserved across a new release of
    Fotocx, but some may be replaced for compatibility reasons.

^Files in Fotocx 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
  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/         files saved from Select Area > Save dialog
  saved_curves/        saved node points for saved edit curves
  saved_searches/      saved settings for the Search Images function
  slideshows/          user settings from Slide Show function
  slideshow_trans/     saved slide show transition parameters
  temp/                temporary files for current sessions
  thumbnails/          thumbnail files (default location)
  blacklist            list of files with internal errors - not usable
  bookmarks            bookmark names and image file locations
  capskeys_*           metadata keys for captions shown at top of image
  CIE1931.jpg          color selection palette for Paint Image function
  custom_menu_*        list of functions included in custom user menu
  drag_from_folder     memory for 2 Fotocx processes to drag/drop files
  folder.png           optional: customize gallery folder icon
  fotocx-NN.N.log      activity log - 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    metadata items reported by Batch Report Meta
  meta_view_extra      extra custom items for the metadata short report
  map_regions_*        saved map regions in world map view
  pagesetup            saves page setup data for print image function
  parameters           parameters that are saved across Fotocx sessions
  plugins_*            saves the plugins menu contents
  printsettings        saves print settings data for print image function
  raw_commands_*       saved raw image processing commands
  recent_files         list of the last 1000 files opened by Fotocx
  recent_topics        recent topics viewed in the user guide
  search_results       output of image search function, list of files
  slideshow-tone.oga   a short music tone for slide show (freedesktop.org)
  tags_defined         list of all categories and tags currently in use
  userguide            text file copy of user guide without images
  wallpaper            Fotocx 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
  zdialog_inputs       saved dialog data to recall prior inputs

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

^Metadata 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 Fotocx edits      Fotocx    no
 EXIF  FocalLengthIn35mmFormat*  panorama                  camera    no
 EXIF  City, Country             city/location, 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

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

TOPIC: FOTOCX 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 Fotocx can be found here:
   ^https://kornelix.net/fotocx_topics/win11/install.html

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

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


TOPIC: 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} 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
{AMPLIFY CONTRAST} - amplify existing contrast to enhance details
{ANTI-ALIAS} - suppress pixelation (jaggies) along feature edges
{AREA BLEND} - mouse-blend edits made within a selected area
{AREA FILL} - fill selected areas or transparent areas with a color
{AREA OVERVIEW} - select area - concepts and usage
{AUTOSEARCH} - scripted Search function to find files
{BATCH CHANGE META} - add or revise metadata for selected image files
{BATCH CONVERT} - copy, move, rescale, rename, convert, add text ...
{BATCH COPY/MOVE} - copy/move selected image 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 - standardize usage
{BATCH OVERLAY} - add overlay image (copyright ...) to selected 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 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 blank image with specified size and color
{BLUR} - blur an image or image area, multiple methods
{BOOKMARKS} - view list of bookmarks, go to bookmark
{BRIGHTNESS RAMP} - add a brightness/color ramp across an image
{CALIBRATE PRINTER} - calibrate printer color - compensate color shifts
{CAPTIONS} - show file name, title, description in image corner
{CARTOON} - convert an image to a cartoon-like drawing
{CHANGE ALPHA} - add or remove alpha channel for an image file
{FRINGES} - fix pheripheral color fringes (chromatic aberration)
{CLEAR AREA} - remove an area
{COLLECTION MANAGEMENT} - collection management and image searching
{COLOR DEPTH ISSUES} - meaning and limitations
{COLOR MODE} - convert to black & white, color, negative, positive
{COMBINE MENU}
{COMMAND PARAMETERS} - Fotocx command line parameters
{CONVERT ADOBE} - convert Adobe files (.pdf/.ps/.eps/.psd) to jpeg
{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 or paste area into current image
{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
{CURRENT FOLDER} - open Gallery View from current image file
{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
{CUSTOM MENU} - custom user menu for frequently used functions
{CYCLE 2 FILES} - cycle through the two most recently seen image files
{CYCLE 3 FILES} - 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
{DRAG AND DROP} - file drag and drop methods
{E-CORES AND HYPERTHREADS} - how useful are these?
{EDIT ANY META} - edit any metadata (add, change)
{EDIT BOOKMARKS} - add, remove, arrange bookmarks
{EDIT HISTOGRAM} - edit brightness histogram for better detail
{EDIT MAIN META} - edit commonly used metadata
{EDIT MENU}
{EDIT PROCEDURES} - how to edit image files
{EDIT SCRIPT} - record edits in a script to make a custom edit function
{EDIT TEMPLATE} - coding template for new edit functions
{EDIT WORKFLOW} - alternative edit methods - simple and complex
{EFFECTS MENU}
{EMBOSS} - convert an image to a simulated embossing (3D effect)
{ENABLE/DISABLE AREA} - enable or disable an area for editing
{ENGRAVE} - convert an image into black & white lines
{ESCHER SPIRAL} - transform an image into an endless inward spiral
{EXPORT FILE LIST} - make a list of selected files (e.g. shell script)
{EXPORT FILES} - export selected files to a folder (e.g. web upload)
{FILE MENU}
{FILE SAVE} - save 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 all images
{FIRST INDEX} - locating and indexing image files for fast searching
{FIRST STARTUP} - information for Fotocx first startup
{FIX META} - repair malformed metadata preventing metadata edits
{FLATTEN HISTOGRAM} - flatten brightness histogram for better detail
{FLATTEN PHOTO} - flatten a photo of a curved surface
{FOLDER TREE} - show all image file folders in a tree structure
{FOTOCX CAPABILITIES} - summary of Fotocx functions and tools
{FOTOCX FOR WINDOWS 11} - installing Fotocx on Windows 11 WSL
{FOTOCX HOME FOLDER} - user data files in Fotocx home folder
{FOTOCX LIMITATIONS} - size and performance limits
{FOTOCX OVERVIEW} - description, prerequisites, license, downloads
{FOTOCX PACKAGES} - package file contents
{FOTOCX PERFORMANCE} - methods and limitations, benchmarks
{FOTOCX SOURCE CODE} - how to access Fotocx source code
{GALLERY END} - jump to gallery end
{GALLERY HOME} - jump to gallery start
{GALLERY MENU}
{GALLERY OVERVIEW}
{GALLERY SCREEN} - select newest, oldest, matching pattern ...
{GALLERY SORT} - change the sort order of a gallery
{GALLERY TO ALBUM} - save current gallery as a named album
{GALLERY VIEW} - Gallery View window (view thumbnails)
{GLOBAL RETINEX} - rescale RGB values for greater range
{GRID SETTINGS} - show or remove grid lines, set line count or spacing
{HDF} - combine close/far focused images for extended depth of field
{HDR} - combine dark/bright images for an extended brightness range
{HELP MENU} - user guide, tutorial, change log, about Fotocx, uninstall
{HIGH QUALITY IMAGE UPSCALE} - how to upscale 2x with best quality
{IMAGE ARRAY} - join many images into a compact array format
{IMAGE DETERIORATION FROM REPEATED EDITS} - analysis
{IMAGE METADATA USAGE} - description and limitations
{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} - Fotocx software installation, dependencies
{INTERPOLATION METHOD} - technical description
{INVERT AREA} - invert an area (exchange outside/inside areas)
{JPEG ARTIFACTS} - suppress artifacts in highly compressed files
{JPEG COMPRESSION} - technical description
{JPEG IMAGE DETERIORATION} - analysis
{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
{RECENT FOLDERS} - open Gallery View of last used file folder
{LINE COLOR} - set color for select area outlines
{LOAD/SAVE AREA} - load an area from a file or save to a file
{LOCAL CONTRAST} - add contrast adapted to local area brightness
{LOCAL RETINEX} - rescale RGB values for greater range
{LOG FILE} - Fotocx 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
{MAP LOCATION} - find location name from partial input, goto map location
{MAP MARKERS} - show map markers for all images or current gallery
{MAPS MENU}
{MAP REGIONS} - define custom map region names, goto map region
{MAP VIEW} - map view window (view map with image location markers)
{MARGINS} - add margins to an imqage, any color or transparency
{MARKUP} - draw on image: text, line/arrow, box, oval
{MASHUP} - arrange images and formatted text in a custom layout
{MATCH COLORS} - match the colors in one image to another image
{MEASURE IMAGE} - measure pixel distances within image (mouse clicks)
{MENU SHORTCUTS} - popup menus, keyboard shortcuts, custom user menu
{MENU SUMMARY} - outline of menu groups and contents
{METADATA ERRORS} - description and handling
{METADATA MENU}
{METADATA STANDARDS CHAOS} - multiple conflicting standards
{META VIEW} - Gallery View with thumbnail and basic metadata
{MONITOR COLOR} - tool to adjust monitor brightness and contrast
{MOSAIC} - convert image into a mosaic using tiles made from images
{MOUSE ALT-RIGHT-BUTTON} - mouse right-button for touchpads/screens
{MOUSE FUNCTIONS} - mouse functions for file/gallery/map views
{MOUSE OWNERSHIP} - dialog-mouse control and interaction
{MOVE FOTOCX HOME} - move Fotocx home folder to a new location
{NEWEST FILES} - Gallery View of newest image files
{NEWLINE CHARACTERS IN METADATA} - description and handling
{NEW SESSION} - start new Fotocx session in a separate window
{NOISE MEASUREMENT} - how is noise measured
{NUMERIC KEYPAD} - navigation using numeric keypad
{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 Fotocx
{OUTLINES} - convert an image into an outline drawing
{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} - combine a series of images horizontally
{PATTERN} - add a background pattern to an image
{PERMISSIONS} - view and set permissions for an image file
{PERSPECTIVE} - straighten object photographed from an obtuse angle
{PLACES/DATES} - list image locations/dates, click for gallery
{POPUP REPORTS} - keyboard navigation for text-based popup reports
{PREVIEW MODE} - method for higher interactive performance
{PRINT CALIBRATED} - print using color calibration data
{PRINT IMAGE} - print an image file
{PRIVACY} - privacy policy and privacy considerations
{PROBLEM REPORTING} - how to analyze and report problems
{QUESTIONS, SUGGESTIONS} - how to contact the Fotocx author
{QUICK INDEX} - quick incremental index with no user interaction
{QUIT} - exit from Fotocx
{RAW IMAGE NOISE} - noise in RAW image files
{RECENT FILES} - 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 from old photos
{REMOVE HALO} - remove halos left by sharpen and other 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 HISTOGRAM} - brightness histogram graph for current image
{RIGHT-CLICK MENUS} - popup menu functions for File and Gallery View
{ROTATE PERFORMANCE} - interactive rotation performance
{ROTATE} - rotate or level an image
{RUNNING OUT OF DISK SPACE} - disk space requirements
{RUNNING OUT OF MEMORY} - memory limits and performance
{RUN SCRIPT} - execute script on current image
{SATURATION} - adjust color saturation based on brightness
{SCRIPT FILES} - script files (macros) overview
{SEARCH IMAGES} - search using any metadata or folder/file names
{SELECT AREA} - select image feature or area for separate editing
{SELECT FILES} - select files for input to batch, script or album
{SELECT IMAGE FILES} - image file selection procedure
{SELECT MENU}
{SET COLORS} - reduce the number of colors (posterize)
{SET WALLPAPER} - wallpaper from the current image file (Gnome)
{SETTINGS} - user preferences and settings for Fotocx operation
{SHARPEN} - sharpen a blurred image, multiple methods
{SHIFT COLORS} - gradually shift RGB colors to GBR or BRG
{SHOW CIM FILES} - show input files for current/latest combined image
{SHOW/HIDE AREA} - show or hide area outlines
{SHOW ON MAP} - show an image file position in 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
{SLIDES AND NEGATIVES} - how to capture slides and film negatives
{SLIDE SHOW} - slide show with animated transitions and pan/zooms
{SMART ERASE} - remove power lines, signs, other small spoilers
{SOFT FOCUS} - apply classic "soft focus" effect to an image
{SPHERE} - curve an image into a spheroid shape
{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 movable boundary line
{STACK/LAYERS} - combine image versions, select/paint area/version
{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 thumbnails and file names
{TILES1} - convert an image into square tiles with 3D effect
{TILES2} - convert an image into irregular tiles matching image
{TIMELINE} - show image counts by year/month, click for gallery
{TINY PLANET} - wrap a panorama image around a circle
{TOOLS MENU}
TOPIC: FOTOCX USAGE
TOPIC: FOTOCX USER GUIDE  v.23.80
TOPIC: INTRODUCTION
{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 close-up face photo distortion (big nose)
{UPDATE ALBUMS} - update albums for updated image files
{UPRIGHT} - upright a rotated or mirrored image
{USER GUIDE} ← ^click here^ - how to use this user guide browser
{VIDEO FILES} - video files, thumbnails, playing
{VIEW 360° PANO} - 360° panorama image with rotating viewpoint
{VIEW ALL META} - list all image metadata
{VIEW MAIN META} - list main image metadata
{VIGNETTE} - change brightness/color radially around chosen center
{WARP AFFINE} - warp image by mouse drag - parallel lines preserved
{WARP AREA} - warp a selected image area by pulling with the mouse
{WARP CURVED} - warp image by mouse drag - curvy warp
{WARP LINEAR} - warp image by mouse drag - straight lines preserved
{WARP MENU}
{WARP RADIAL} - add or remove barrel or pincushion distortion
{WEB UPLOAD} - uploading image files to the internet
{WINDOW VIEWS AND MENUS} - top-level windows and associated menus
{WORLD MAP} - internet world map overview
{ZOOM} - left/right click or [+-] button to zoom image or thumbnail


EOF   (nothing shows beyond this line)

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

following are tests for audit_docfile() function
run test as follows: $ fotocx -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 /fotocx-nn.n/UG-topics
---------------------------------------------------------

UG-topics $: ./UG-topics 
source folder: /home2/mico/programs/fotocx-24.70/*.cc 
file: /home2/mico/programs/fotocx-24.70/f.refine.cc 
   topic: {EDIT HISTOGRAM} 
   topic: {FLATTEN HISTOGRAM} 
   topic: {LOCAL CONTRAST} 
   topic: {AMPLIFY CONTRAST} 
   topic: {GLOBAL RETINEX} 
   topic: {LOCAL RETINEX} 
   topic: {SATURATION} 
   topic: {SOFT FOCUS} 
   topic: {MATCH COLORS} 
   topic: {BRIGHTNESS RAMP} 
   topic: {VIGNETTE} 
file: /home2/mico/programs/fotocx-24.70/UG-topics/UG-topics.cc 
file: /home2/mico/programs/fotocx-24.70/f.edit.cc 
   topic: {ROTATE} 
   topic: {UPRIGHT} 
   topic: {CROP} 
   topic: {RETOUCH} 
   topic: {RESCALE} 
   topic: {MARGINS} 
   topic: {MARKUP} 
   topic: {COLOR MODE} 
   topic: {PAINT EDITS} 
   topic: {PAINT IMAGE} 
   topic: {PAINT TRANSP} 
   topic: {AREA FILL} 
   topic: {COPY IN IMAGE} 
   topic: {COPY FROM IMAGE} 
   topic: {COPY FROM IMAGE} 
   topic: {COPY PRIOR EDIT} 
   topic: {EDIT TEMPLATE} 
file: /home2/mico/programs/fotocx-24.70/f.widgets.cc 
   topic: {CUSTOM MENU} 
   topic: {SCRIPT FILES} 
   topic: {SCRIPT FILES} 
   topic: {SCRIPT FILES} 
   topic: {SCRIPT FILES} 
   topic: {PLUGINS} 
   topic: {PLUGINS} 
   topic: {PLUGINS} 
file: /home2/mico/programs/fotocx-24.70/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} 
file: /home2/mico/programs/fotocx-24.70/f.file.cc 
   topic: {NEW SESSION} 
   topic: {OPEN IMAGE FILE} 
   topic: {CYCLE 2 FILES} 
   topic: {CYCLE 3 FILES} 
   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 IMAGE} 
   topic: {PRINT CALIBRATED} 
   topic: {CALIBRATE PRINTER} 
   topic: {HELP MENU} 
   topic: {HELP MENU} 
   topic: {FILE SAVE} 
file: /home2/mico/programs/fotocx-24.70/f.warp.cc 
   topic: {UNBEND} 
   topic: {PERSPECTIVE} 
   topic: {WARP AREA} 
   topic: {WARP CURVED} 
   topic: {WARP LINEAR} 
   topic: {WARP AFFINE} 
   topic: {WARP RADIAL} 
   topic: {UNWARP CLOSEUP} 
   topic: {MAKE WAVES} 
   topic: {TWIST} 
   topic: {SPHERE} 
   topic: {INSIDE-OUT} 
   topic: {TINY PLANET} 
   topic: {ESCHER SPIRAL} 
   topic: {FLATTEN PHOTO} 
file: /home2/mico/programs/fotocx-24.70/f.meta.cc 
   topic: {VIEW MAIN META} 
   topic: {VIEW MAIN META} 
   topic: {EDIT MAIN 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: {WORLD MAP} 
   topic: {MAP REGIONS} 
   topic: {MAP LOCATION} 
   topic: {MAP MARKERS} 
   topic: {SHOW ON MAP} 
file: /home2/mico/programs/fotocx-24.70/fotocx.cc 
   topic: {OUTBOARD PROGRAMS} 
   topic: {FIRST INDEX} 
   topic: {UNDO/REDO BUTTON} 
file: /home2/mico/programs/fotocx-24.70/f.tools.cc 
   topic: {INDEX FILES} 
   topic: {QUICK INDEX} 
   topic: {SETTINGS} 
   topic: {KB SHORTCUTS} 
   topic: {RGB HISTOGRAM} 
   topic: {MAGNIFY IMAGE} 
   topic: {MEASURE IMAGE} 
   topic: {SHOW RGB} 
   topic: {GRID SETTINGS} 
   topic: {GRID SETTINGS} 
   topic: {LINE COLOR} 
   topic: {DARK/BRIGHT PIXELS} 
   topic: {MONITOR COLOR} 
   topic: {FIND DUPLICATES} 
   topic: {SHOW RESOURCES} 
file: /home2/mico/programs/fotocx-24.70/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/fotocx-24.70/f.mashup.cc 
   topic: {MASHUP} 
   topic: {IMAGE ARRAY} 
file: /home2/mico/programs/fotocx-24.70/f.effects.cc 
   topic: {OUTLINES} 
   topic: {SKETCH} 
   topic: {CARTOON} 
   topic: {EMBOSS} 
   topic: {TILES1} 
   topic: {TILES2} 
   topic: {PAINTING} 
   topic: {TEXTURE} 
   topic: {PATTERN} 
   topic: {DITHER} 
   topic: {DITHER} 
   topic: {DITHER} 
   topic: {DITHER} 
   topic: {DITHER} 
   topic: {DITHER} 
   topic: {ENGRAVE} 
   topic: {MOSAIC} 
   topic: {ADD NOISE} 
   topic: {SET COLORS} 
   topic: {SHIFT COLORS} 
   topic: {ALIEN COLORS} 
   topic: {CUSTOM KERNEL} 
file: /home2/mico/programs/fotocx-24.70/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: {CURRENT FOLDER} 
   topic: {RECENT FOLDERS} 
   topic: {FOLDER TREE} 
   topic: {SELECT IMAGE FILES} 
   topic: {RENAME FOLDER} 
   topic: {ADD SUBFOLDER} 
   topic: {BOOKMARKS} 
   topic: {BOOKMARKS} 
   topic: {VIDEO FILES} 
file: /home2/mico/programs/fotocx-24.70/f.pixmap.cc 
file: /home2/mico/programs/fotocx-24.70/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: {REMOVE DUST} 
   topic: {FRINGES} 
file: /home2/mico/programs/fotocx-24.70/f.comb.cc 
   topic: {HDR} 
   topic: {HDF} 
   topic: {STACK/PAINT} 
   topic: {STACK/NOISE} 
   topic: {STACK/LAYERS} 
   topic: {STACK/SPLIT} 
   topic: {PANORAMA} 
   topic: {SHOW CIM FILES} 
file: /home2/mico/programs/fotocx-24.70/f.albums.cc 
   topic: {MANAGE ALBUMS} 
   topic: {MANAGE ALBUMS} 
   topic: {MANAGE ALBUMS} 
   topic: {MANAGE ALBUMS} 
   topic: {MANAGE ALBUMS} 
   topic: {UPDATE ALBUMS} 
   topic: {GALLERY TO ALBUM} 
   topic: {ALBUM MASS UPDATE} 
   topic: {SLIDE SHOW}