fScanX Command-Line Utility

The command line utility supports scanning via scripts from any tool or environment that allows execution of a UNIX command-line process--any reasonably recent tool or environment. This is different than most scanning software in that you do not run the scanning application and have the user interact with it. Instead you provide all options to the utility and it runs in the background, which means you have full control over the user interface.

You let the user set whatever options (including none at all) are appropriate for the task, and present them integrated in your software. (You can even receive page preview images and display them as pages are scanned!)

There are several examples available in the installation disk image:

  • A simplified stand-alone scanning utility implemented in AppleScript Studio.
  • A minimal FileMaker integration example.
  • The sources (Cocoa/Objective-C) to the fScanX stand-alone application and Automator action.

The utility takes a number of options, followed by a file name. The options all have reasonable defaults: monochrome scanning, 300dpi, 8.5x11 inch page with no margins, multi-page TIFF output. So the command: 

fscanx myfile.tif

will scan all the pages on the scanner's document feeder and create myfile.tif in the current directory. This assumes that fscanx is located where it will be found in the search path, if not you'll have to either use the full path, or be in the directory where the utility is located. For instance:

/Users/me/myscanstuff/fscanx myfile.tif

or:

cd /Users/me/myscanstuff
./fscanx myfile.tif

The rest of the examples will assume the utility is on the search path, as is the case with the default location /usr/sbin.

Note that trying the command fscanx with no arguments will in typical UNIX fashion give you a concise summary of the options: 

Build 1.8.14 2020-05-30 usage:

  fscanx --enumerate
    scan the USB bus for all supported scanners and list them

  fscanx --capabilities location
    given a usb location (from --enumerate), list the scanner capabilities

  fscanx --info location
    given a usb location (from --enumerate), list the scanner information

  fscanx --register name email license
    add the license

  fscanx --registrations
    list all licenses

  fscanx --unregister
    remove all licenses

  fscanx options filename
    scan pages into file 'filename' where possible options are:

  --append to, rather than overwrite, an existing file
  --adf to scan from automatic document feeder, --flatbed to scan from flatbed
    default is adf
  --tiff to create TIFF file, --pdf to create PDF file, default is tiff
  --compress option, where only option is zlib for gray & color TIFF
  --duplex to scan front and back, otherwise scan front only
  --rotate-f-b where f stands for rotation of front side, b stands for rotation of
    back side, possible values are 'n' for none, 'f' for 180 degrees flip, 'l' for
    90 degrees left, and 'r' for 90 degrees right; --rotate-r-l is equivalent to
    --landscape; allowable values are --rotate-n-n, --rotate-n-f, --rotate-f-n,
    --rotate-f-f, --rotate-l-l, --rotate-l-r, --rotate-r-l, and --rotate-r-r,
    remember that width & height are specified in terms of how one reads the
    document, in other words 11 wide by 8.5 high for US letter-size & landscape
  --mono, --gray, --rgb, default is --mono
  --resolution xxx, dots per inch, from 50-600 in 1 dpi increments,
    default is 300
  --paper-width xxx, --paper-height xxx, size of document in units of
    1/1200 inch, default is 8.5 x 11 inches
  --auto-length, if specified, automatically detect length of paper up
    to length specified in paper-height, and create output image of
    actual length (does not work with landscape scanning); if no paper-height is
    given, then the scanner's maximum (for the scan's resolution) will be used
  --left xxx, --top xxx, --width xxx, --height xxx, scan area in units
    of 1/1200 inch, centered on scan area, default is the entire page
  --threshold xxx, is 1-254, applies to mono, ignored for gray & color,
    default of 128
  --dtc x, where x is d, 1, or 2 for scanner's best, full, or simplified
    dynamic thresholding, respectively
  --density x, where x is floating point value from 0.1 to 10.0; adjusts the
    threshold calculation to darken or lighten the result; 1.0 should be close to
    accurate reproduction, with 1.1 slightly more legible on screen for typical
    documents; 0.5 is a good guess for very dark originals, and 2.0 a good guess
    for very light originals
  --despeckle xxx, is 0-100, applies to mono, ignored for gray & color,
    default is 0, reasonable values are: 92 @ 600dpi, 60 @ >= 400dpi,
    39 @ >= 300dpi, 32 @ >= 200dpi, 15 @ >= 150dpi, 7 @ < 150dpi
  --bits x, bit depth of output, 1-8, applies to gray & color, ignored
    for mono, default is 6
  --black xxx, --white xxx, specify endpoints for contrast stretch,
    defaults are: 16 & 231 for 3-7 bits out, 0 & 255 for 8-bits out
  --over-sample, applies to gray & color only, up to 300dpi only;
    scan at 2x resolution and scale to 1x resolution for
    output; the use of an advanced scaling algorithm can result in
    slightly higher quality than scanning at 1x resolution, but with
    the same file size
  --turbo x.x, applies to black-and-white only; for some combinations of scanner
    and resolution, speeds up the scanning, generally specify 0 as the value
    in order to let the software figure it out based on scanner & resolution,
    because the factors that affect it are complex; turbo also allows for
    resolution to specified up to 1200dpi for black-and-white scans
  --no-jpeg, disallows use of JPEG compression for communication with scanner;
    JPEG compression is normally used when available, otherwise high-end scanners
    will produce data faster than USB 2 can transfer it; the degree of compression
    used is very light so most documents will not be degraded; but if you have an
    unusual document or concern about lossy compression, use this option
  --images-per-file xx, is 1 or more, scan into multiple files with xx
    images per file, file number is inserted before last "." character
    if any, otherwise at end of file name, default is to put all pages
    into a single file
  --double-feed option
    option is n for none, t for overlap/thickness variance, l for length
    variance, tl for both overlap/thickness & length, default is t
  --location location
    use the scanner at the specified USB location rather than the first
    matching scanner, locations can be found by using the --enumerate
    option, or in System Profiler, or using IORegistryExplorer
  --preview width height
    output preview images as pages are scanned, scaled proportionally to fit in
    the given dimensions; for black & white or grayscale scan, the output is
    grayscale, for color scans it is RGB; in all cases it is binary data so this
    option is not suitable for use from the terminal; after launch the phrase
    "preview fifo:" will be written to stdout followed by a space and the path
    of the pipe from which the previw pages can be read; for each page, a line
    with "preview w x h (d, rb)" where w is width, h is height, d is depth, rb
    is row bytes, followed by w*rb*d bytes of image data followed by a single
    newline character.

returns 0 for success, 1 for argument error, 2 for failure to find
    scanner (or failure to validate license), 3 for failure to start scan,
    4 for unspecified error during scan, 5 for failure to create or open file,
    6 for paper feed failure, 7 for failure to create preview fifo,
    8 for user interrupt, 9 for expiration of pre-release, 10 for file limit
    exceeded (4GiB for TIFF, 10GB for PDF), 11 for disk full error, 12 for other
    file write error

(c) 2004-2020 Elevated Software Development, Inc. All Rights Reserved.
http://www.elevated-dev.com/Products/fScanX/

Thanks to libtiff.org for the libtiff library, portions of which
  are (C) 1988-1997 Sam Leffler and (C) 1991-1997 Silicon Graphics Inc.
Thanks to the Indpendent JPEG Group for the libjpeg library, (C) 1991-2010 Thomas
  G. Lane and Guido Vollbeding.
Thanks for zlib, (C) 1995-2004 Jean-loup Gailly and Mark Adler

Command-Line Examples

The output above is a complete list of the options; following are some examples to help you figure out the options.

This command is the same as using the default options, they're just spelled out:
fscanx --mono --resolution 300 --left 75 --top 75 --width 10050 --height 13050 --threshold 128 myfile.tif

This command would be good to scan a form with gray backgrounds:
fscanx --gray myfile.tif

This command would be good to scan a form with colored text and/or backgrounds:
fscanx --rgb myfile.tif

The threshold option is good for adjusting for light or dark originals when scanning in black and white. For dark originals try lower values and for light originals try higher values. The despeckle option controls how aggressively the software tries to remove "specks", isolated pixels not part of larger groups. A setting of 0 doesn't remove any specks, a setting of 100 removes any pixel that's not completely surrounded by adjacent pixels.

These two settings do interact. To deal with problematic originals, try a 2-step process. First adjust the threshold until the density of text is correct, that is until the thickness of strokes of letters is not too thin (look at letters "l" and "t") but small interior spaces (as in "e") are not filled in. Second, adjust the despeckling to reduce specks. Note that for a good quality original on clean paper, the despeckling settings will not make a visible difference. For really bad originals, the best thing to do may be to scan to 2- 3- or 4-bit grayscale.

The contrast stretch options, --black and --white are good for adjusting the contrast of forms. Blank paper is not quite white, it's typically seen by the scanner as a light gray and likewise printed black may be a dark gray. The contrast stretch options let you specify a cutoff below which all grays will be pushed to black, and one above which all values will be pushed to white. The default values are good for a wide variety of inputs. But if you have problem originals (streaky, blotchy, stained, light printing, smeared backgrounds) you may be able to improve the scans by using these options.

The default reduction of output to 6-bit gray or 6-6-6 rgb works well for forms. This provides enough colors to match form colors well enough, and dropping the less significant bits reduces noise that would otherwise show up as inconsistent shades. It also results in files that compress better.

Stretching light and dark grays to white and black and throwing away half the color information produces poor results for photographs. The Fuji scanners are document scanners and documents are the focus of this software, but there are options that won't mess up photos.

This would be better to scan a black & white photograph:
fscanx --gray --bits 8 myfile.tif

This would be better to scan a color photograph, and would type the file to be opened by GraphicConverter:
fscanx --rgb --bits 8 --fcreator GKON myfile.tif

This would scan into multiple files, 1 per page, named test1.tiff and so on:
fscanx --images-per-file 1 test.tiff

The --duplex option scans both sides of each page. With this option, the images-per-file option counts each side separately. So images-per-file 2 would put 2 images into each file, the front and back side of a single page.

The --pdf option creates a PDF file instead of a TIFF. PDF documents are good for printing; the Adobe Reader application has an option in the print dialog to not scale the pages when printing, which provides good print quality. (See the next section for more information.)