hpoj reference: libsane-hpoj

libsane-hpoj is a major improvement over the two separate scanning solutions used in some previous hpoj versions (SANE hp backend and hpoj "ptal-hp scan" command-line utility), because it provides a common interface for all supported models, is better suited to the unique capabilities of HP multi-function peripherals, has better ADF (automatic document feeder) and scrollfed-scanner support, is much more robust in general, and doesn't require the sane-backends package to be recompiled for hpoj support.

See the hpoj Supported devices page for the most up-to-date list of models with which libsane-hpoj supports scanning.

Depending on your model, libsane-hpoj supports the HP SCL (Scanner Control Language) and PML (Peripheral Management Language) scanning protocols, with or without MFPDTF (Multi-Function Peripheral Data Transfer Format) packetized encoding. If necessary it performs JPEG decompression in color and grayscale scan modes, and MH, MR, and MMR decompression in lineart (bi-level, black-and-white) scan mode.

Supported options

The following basic options are in the "Scan mode" group:

• mode (string list) -- Scan mode. Possible values, depending on the model:
  • Lineart -- 1-bit black-and-white (bi-level)
  • Grayscale -- 8-bit grayscale
  • Color -- 24-bit color
  Higher bit depths are not currently supported.

• resolution (integer list or range) -- Scan resolution in dots-per-inch for both the X and Y directions. For some models, Lineart mode is limited to 300 DPI. Separate resolution settings for the X and Y directions are not currently supported.

• contrast (integer range) -- Contrast. Not available on all models. On some models this setting only affects Lineart and/or Grayscale but not Color scan modes.

• compression (string list) -- Compression method. Possible values, depending on the model and scan mode:
  • None -- Not available if model requires compression for current scan mode.
  • MH -- Lineart only.
  • MR -- Lineart only.
  • MMR -- Lineart only.
  • JPEG -- Grayscale and Color only.
  Enabling compression if possible may increase scan speed. However, JPEG compression is lossy, meaning that some image quality is lost.

• jpeg-compression-factor (integer range) -- Only available if compression is set to JPEG. Higher numbers mean more compression and faster scans but worse image quality. The default is 10 for certain models (OfficeJet 500/600/700 and PSC 300 series) to prevent intermittent device lockups while scanning, but 0 otherwise.

• batch-scan (boolean) -- Guarantees that a "no documents" condition is returned after the last scanned page, to prevent endless flatbed scans after a batch ADF scan. Not available on the OfficeJet LX and 300 series. For some models, changes to certain options in the middle of a batch scan don't take effect until after the last page has been scanned, unless you toggle this option off and back on. Avoids delay between pages on the OfficeJet 600 series. For LaserJet 1220, 3200, and 3300 series, causes next page to start scanning immediately after the previous page finishes, before the frontend starts it.

• source (was adf-mode in hpoj-0.90) (string list) -- Possible values, depending on the model:
  • Auto -- Auto-detects whether to scan from the glass or ADF.
  • Flatbed -- Only scans from the glass, even if ADF is loaded.
  • ADF -- Only scans from the ADF, fails if ADF not loaded.

• duplex (boolean) -- Enables scanning on both sides of the page through the ADF. Currently only available on the OfficeJet D series, and highly experimental (translation: may not work in all cases and may be removed from future versions if it doesn't work correctly). For pages printed in "book"-style duplex mode, one side will be scanned upside-down.

• length-measurement (string list) -- Selects how the scanned image length is measured and reported, which is impossible to know in advance for scrollfed scans. Possible values:
  • Unknown -- "Unknown" length (-1) is always reported to the frontend. Some frontends (such as xscanimage) and image reader/editor applications don't handle this well. Longer-than-expected images are truncated.
  • Unlimited -- Not supported on all models. Same as Unknown, except length is not arbitrarily limited in software (the device may still impose its own length limit). Disables the br-y option.
  • Approximate -- Length is estimated (usually accurate for flatbed scans), but end-of-file condition may be returned early. Longer-than-expected images are truncated. Some image reader/editor applications don't handle it well when the file header's length field isn't correct.
  • Padded (default) -- Length is estimated (usually accurate for flatbed scans), and if necessary bottom of image is padded with white data before returning end-of-file condition. Longer-than-expected images are truncated. Should work properly with all frontend and image reader/editor applications.

• tl-x, tl-y, br-x, br-y (fixed-precision range) -- Top-left and bottom-right X and Y coordinates of desired scan area. Set to the device for some models, but simulated in the backend for others.

Environment variables

• SANE_HPOJ_RESET_SCAN_TOKEN -- As an alternative to power cycling the device, forcibly resets the device's scanner-lock token if this variable is set (regardless of value), in case it failed to get released due to a SANE crash, for example. Only relevant on the LaserJet 1220, 3200 and 3300 series. Don't set this environment variable unless absolutely necessary, because the scanner-lock token is the only thing preventing multiple instances of libsane-hpoj from interfering with each other on these models, especially in a networked environment.

• SANE_HPOJ_SAVE_COMPRESSED -- For debugging. Sets filename to which to save (possibly compressed) image data after MFPDTF overhead has been removed.

• SANE_HPOJ_SAVE_MFPDTF -- For debugging. Sets filename to which to save all scan data received from the device, including MFPDTF overhead and (possibly compressed) image data.