gscan2pdf.1p - Man Page

If you are using Debian, you should find that sid <https://www.debian.org/releases/sid/> has the latest version already packaged.

If you are using a Ubuntu-based system, you can automatically keep up to date with the latest version via the ppa:

sudo apt-add-repository ppa:jeffreyratcliffe/ppa

If you are you are using Synaptic, then use menu Edit/Reload Package Information, search for gscan2pdf in the package list, and lo and behold, you can install the nice shiny new version.

From the command line:

sudo apt update

sudo apt install gscan2pdf

The source is hosted in the files section of the gscan2pdf project on Sourceforge (<https://sourceforge.net/projects/gscan2pdf/files/>).

gscan2pdf uses Git for its Revision Control System. You can browse the tree at <https://sourceforge.net/p/gscan2pdf/code/>.

Git users can clone the complete tree with git clone git://git.code.sf.net/p/gscan2pdf/code

New

Clears the page list.

Open

Opens any format that imagemagick supports. PDFs will have their embedded images extracted and imported one per page.

Note that files can also be imported by dragging them into the thumbnail list from a program like nautilus or konqueror.

Scan

Sets options before scanning via SANE.

Device

Chooses between available scanners.

# Pages

Selects the number of pages, or all pages to scan.

Source document

Selects between single sided or double sides pages.

This affects the page numbering. Single sided scans are numbered consecutively. Double sided scans are incremented (or decremented, see below) by 2, i.e. 1, 3, 5, etc..

Side to scan

If double sided is selected above, assuming a non-duplex scanner, i.e. a scanner that cannot automatically scan both sides of a page, this determines whether the page number is incremented or decremented by 2.

To scan both sides of three pages, i.e. 6 sides:

1. Select:

# Pages = 3 (or "all" if your scanner can detect when it is out of paper)

Double sided

Facing side

2. Scans sides 1, 3 & 5.

3. Put pile back with scanner ready to scan back of last page.

4. Select:

# Pages = 3 (or "all" if your scanner can detect when it is out of paper)

Double sided

Reverse side

5. Scans sides 6, 4 & 2.

6. gscan2pdf automatically sorts the pages so that they appear in the correct order.

Device-dependent options

These, naturally, depend on your scanner. They can include

Page size.

Mode (colour/black & white/greyscale)

Resolution (in PPI)

Batch-scan

Guarantees that a "no documents" condition will be returned after the last scanned page, to prevent endless flatbed scans after a batch scan.

Wait-for-button/Button-wait

After sending the scan command, wait until the button on the scanner is pressed before actually starting the scan process.

Source

Selects the document source. Possible options can include Flatbed or ADF. On some scanners, this is the only way of generating an out-of-documents signal.

Save

Saves the selected or all pages as a PDF, DjVu, TIFF, PNG, JPEG, PNM or GIF.

Metadata

Metadata are information that are not visible when viewing the PDF/DjVu, but are embedded in the file and so searchable and can be examined, typically with the "Properties" option of the document viewer.

The metadata are completely optional, but can also be used to generate the filename see preferences for details.

The date can be selected with use of the calendar widget. The displayed date can be incremented or decremented with use of the '+' and '-' keys.

DjVu

Both black and white, and colour images produce better compression than PDF. See <http://www.djvuzone.org/> for more details.

Email as PDF

Attaches the selected or all pages as a PDF to a blank email. This requires xdg-email, which is in the xdg-utils package. If this is not present, the option is ghosted out.

Print

Prints the selected or all pages.

Compress temporary files

If your temporary ($TMPDIR) directory is getting full, this function can be useful - compressing all images at LZW-compressed TIFFs. These require much less space than the PNM files that are typically produced by SANE or by importing a PDF.

Delete

Deletes the selected page.

Renumber

Renumbers the pages from 1..n.

Note that the page order can also be changed by drag and drop in the thumbnail view.

Select

The select menus can be used to select, all, even, odd, blank, dark or modified pages. Selecting blank or dark pages runs imagemagick to make the decision. Selecting modified pages selects those which have modified by threshold, unsharp, etc., since the last OCR run was made.

Properties

When an image is scanned, gscan2pdf attempts to extract the resolution from the scan options. This nearly always works without problem.

Importing an image can be trickier, however. Some image formats such as PNM do not encode metadata for resolution. In other cases, the data is incorrect. Edit/Properties allows the user to manually correct the metadata for a particular page, thus correcting the size of final PDF or DjVu. The image itself is otherwise not changed - it is not down- or upscaled.

Preferences

The preferences menu item allows the control of the default behaviour of various functions. Most of these are self-explanatory.

Frontends

gscan2pdf initially supported two frontends, scanimage and scanadf. scanadf support was added when it was realised that scanadf works better than scanimage with some scanners. On Debian-based systems, scanadf is in the sane package, not, like scanimage, in sane-utils. If scanadf is not present, the option is obviously ghosted out.

In 0.9.27, Perl bindings for SANE were introduced. These are called libsane-perl.

Before 1.2.0, options available through CLI frontends like scanimage were made visible as users asked for them. In 1.2.0, all options can be shown or hidden via Edit/Preferences, along with the ability to specify which options trigger a reload.

In 1.8.3, New Perl bindings for SANE were introduced. These are called libimage-sane-perl and are the preferred frontend.

In 1.8.5, support for libsane-perl was removed.

Device blacklist

Ignore listed devices.

Note that this is a device name regular expression, e.g. /dev/video, and not the name as listed in the scan window, e.g. Noname Integrated_Webcam_HD.

Default filename for PDF or DjVu files

All strftime codes (e.g. %Y for the current year) are available as variables, with the following additions:

%Da

author

%De

filename extension

%Dt

title

All document date codes use strftime codes with a leading D, e.g.:

%DY

document year

%Dm

document month

%Dd

document day

Zoom 100%

Zooms to 1:1. How this appears depends on the desktop resolution.

Zoom to fit

Scales the view such that all the page is visible.

Zoom in

Zoom out

Rotate 90° clockwise

The rotate options require the package imagemagick and, if this is not present, are ghosted out.

Rotate 180°

Rotate 90° anticlockwise

Threshold

Changes all pixels darker than the given value to black; all others become white.

Unsharp mask

The unsharp option sharpens an image. The image is convolved with a Gaussian operator of the given radius and standard deviation (sigma). For reasonable results, radius should be larger than sigma. Use a radius of 0 to have the method select a suitable radius.

Crop

unpaper

unpaper (see <https://www.flameeyes.eu/projects/unpaper>) is a utility for cleaning up a scan.

OCR (Optical Character Recognition)

The gocr, tesseract or cuneiform utilities are used to produce text from an image.

There is an OCR output buffer for each page and is embedded as plain text behind the scanned image in the PDF produced. This way, Beagle can index (i.e. search) the plain text.

In DjVu files, the OCR output buffer is embedded in the hidden text layer. Thus these can also be indexed by Beagle.

There is an interesting review of OCR software at <https://web.archive.org/web/20080529012847/http://groundstate.ca/ocr>. An important conclusion was that 400ppi is necessary for decent results.

Up to v2.04, the only way to tell which languages were available to tesseract was to look for the language files. Therefore, gscan2pdf checks the path returned by:

tesseract '' '' -l ''

If there are no language files in the above location, then gscan2pdf assumes that tesseract v1.0 is installed, which had no language files.

Variables for user-defined tools

The following variables are available:

%i

input filename

%o

output filename

%r

resolution

An image can be modified in-place by just specifying %i.

Possibly because SANE or your scanner doesn't support it.

If an option listed in the output of scanimage --help that you would like to use isn't available, send me the output and I will look at implementing it.

In Edit/Preferences, tick the box "Allow batch scanning from flatbed".

Some Brother scanners report "out of documents", despite scanning from flatbed. This can be worked around by ticking the box "Force new scan job between pages".

If you are lucky, you have an option like Wait-for-button or Button-wait, where the scanner will wait for you to press the scan button on the device before it starts the scan, allowing you to scan multiple pages without touching the computer.

If you are quick, you might be able to change the document on the flatbed whilst the scan head is returning.

Otherwise, you have to set the number of pages to scan to 1 and hit the scan button on the scan window for each page.

Probably because the package required for that option is not installed. Email as PDF requires xdg-email (xdg-utils), unpaper and the rotate options require imagemagick.

Generally for HP scanners with an ADF, to scan from the flatbed, you should set "# Pages" to "1", and possibly "Batch scan" to "No".

As far as I can tell, this is pulled from changelogs.ubuntu.com, and therefore only the changelogs from official Ubuntu builds are displayed.

If your scanner is not connected directly to the machine on which you are running gscan2pdf and you have not installed the SANE daemon, saned, gscan2pdf cannot automatically find it. In this case, you can specify the scanner device on the command line:

gscan2pdf --device <device>

pdftotext or djvutxt can extract the text layer from PDF or DJVU files. See the respective man pages for details.

Having opened a PDF or DJVU file in evince or Acrobat Reader, the search function will typically find the page with the requested text and highlight it.

There are various tools for searching or indexing files, including PDF and DJVU:

• (meta) Tracker (<https://projects.gnome.org/tracker/>)
• plone (<http://plone.org/>)
• pdfgrep (<http://pdfgrep.sourceforge.net/>
• swish-e (<http://www.swish-e.org/>)
• recoll (<http://www.lesbonscomptes.com/recoll/>)
• terrier (<http://www.lesbonscomptes.com/recoll/>)

Create a file called ~/.config/gtk-3.0/gtk.css with the following content:

 .rubberband,
 rubberband,
 flowbox rubberband,
 treeview.view rubberband,
 .content-view rubberband,
 .content-view .rubberband {
   border: 1px solid #2a76c6;
   background-color: rgba(42, 118, 198, 0.2); }

Create a file called ~/.config/gtk-3.0/gtk.css with the following content:

 #gscan2pdf-ocr-output {
   color: black;
 }