Looking for compile instructions? Read the file "INSTALL" instead...
CUPS is a standards-based, open-source printing system used by Apple's Mac OS® and other UNIX®-like operating systems, especially also Linux. CUPS uses the Internet Printing Protocol ("IPP") and provides System V and Berkeley command-line interfaces, a web interface, and a C API to manage printers and print jobs.
CUPS 1.0 was released in early 2000 and since then and until CUPS 2.x (at least) conversion of the data format of incoming print jobs to the format the printer needs was done by external filter executables, each taking an input format on stdin and producing an output format on stdout. Depending on conversion needs one or more of them were run in a chain.
The filters for common formats were part of CUPS and later on, when Apple was maintaining CUPS and using their own, proprietary filters for Mac OS, transferred to OpenPrinting as the cups-filters package.
In the New Architecture for printing we switch to an all-IPP workflow with PPD files and printer driver executables being abolished and classic CUPS printer drivers replaced by Printer Applications (software emulation of driverless IPP printers).
To conserve the functionality of the CUPS filters which got developed over the last 20+ years into a PPD-less, IPP-driven world without having to maintain and include the legacy PPD support in OS distributions and other system environments, the original cups-filters package got split into 5 separate packages: libcupsfilters, libppd, cups-filters, braille-printer-app, and cups-browsed, with libcupsfilters and braille-printer-app not containing PPD file support code any more and cups-browsed being planned to drop explicit use of PPD files.
This package provides the libcupsfilters library, which in its 2.x version contains all the code of the filters of the former cups-filters package as library functions, the so-called filter functions.
The call scheme of the filter functions is similar to the one of the
CUPS filter executables (see cupsfilters/filter.h), but
generalized. In addition, it accepts printer and job IPP attributes
but not PPD files any more. The PPD file interfacing for retro-fitting
got moved to libppd.
The filter functions are principally intended to be used for the data format conversion tasks needed in Printer Applications. They are already in use (together with libppd and pappl-retrofit) by the CUPS-driver retro-fitting Printer Applications from OpenPrinting.
In addition to the filter functions libcupsfilters also contains several API functions useful for developing printer drivers/Printer Applications, like image and raster graphics handling, make/model/device ID matching, ...
For compiling and using this package see the INSTALL file.
Report bugs to
https://github.com/OpenPrinting/libcupsfilters/issues
See the "COPYING", "LICENCE", and "NOTICE" files for legal information. The license is the same as for CUPS, for a maximum of compatibility.
Scans delivered as PDF by IPP Scan or a Scanner Application are
raster images in a PDF container, nothing in them can be searched or
selected. The filter function cfFilterGhostscriptOCR() turns such a
PDF (or PostScript, or anything the other filter functions convert to
PDF) into a searchable PDF: the pages stay as they are and an
invisible text layer with the recognized text is added. The work is
done by the pdfocr8/pdfocr24 output devices of Ghostscript, which
run the Tesseract OCR engine.
- Ghostscript built with Tesseract (
gs -hlists thepdfocr8device). The Ghostscript packages of the usual distributions have it. - The Tesseract language data for the languages to recognize (for
example the
tesseract-ocr-eng,tesseract-ocr-deupackages). The filter function searches the data in the directory given by the caller, inTESSDATA_PREFIX, and in the usual directories of the distributions, and passes the location to Ghostscript. This is needed as Ghostscript's compiled-in default is often not where the packages install the data.
#include <cupsfilters/filter.h>
cf_filter_ghostscript_ocr_params_t params =
CF_FILTER_GHOSTSCRIPT_OCR_PARAMS_INITIALIZER;
params.language = "deu"; // Tesseract language code(s)
params.fallback = 1; // Raster-only PDF if OCR fails
ret = cfFilterGhostscriptOCR(inputfd, outputfd, 1, &data, ¶ms);
data is the usual cf_filter_data_t with the job options, logging
function, and (optionally) the job and printer IPP attributes. Every
field of the parameter struct left at NULL/-1 is taken from the
job options or from the defaults:
| Field | Job option | Default |
|---|---|---|
language |
ocr-language |
eng |
engine |
ocr-engine |
Ghostscript's default (LSTM) |
pdfa |
ocr-pdfa |
0 (plain PDF), 2 or 3 for PDF/A |
fallback |
ocr-fallback |
1 |
resolution |
ocr-resolution |
300 dpi (or printer-resolution) |
tessdata_dir |
ocr-tessdata-dir |
auto-detected |
extra_args/num_extra_args pass additional Ghostscript command
line arguments through, for example "-dJPEGQ=75".
So a Scanner Application which maps its IPP scan attributes to job
options only has to call cfFilterGhostscriptOCR() with NULL as
parameters. With the output type application/vnd.cups-pdf-ocr,
cfFilterUniversal() does the same for any input format, including
JPEG, PNG, TIFF, PWG/Apple Raster, and PostScript.
char tessdata[1024];
if (cfFilterGhostscriptOCRAvailable(&data, NULL, tessdata,
sizeof(tessdata)))
// offer searchable PDF, language data is in tessdata
else
// Ghostscript without Tesseract or language data missing
The check uses the language from the parameters or the job options
in data (default eng), so it can be called per language. data
can be NULL.
If OCR is not possible (no pdfocr8 device, language data missing)
or Ghostscript fails or produces no output, the function produces a
raster-only PDF without text layer and logs a warning, so that no
scan is lost. With fallback set to 0 it logs an error and returns 1
instead. Ghostscript writes into a temporary file first, so a failed
OCR run never leaves partial output on the output file descriptor,
and non-seekable input is buffered so that it can be read a second
time.
Tesseract language codes are three letters (eng, deu, fra,
chi_sim, ...), several can be combined with +. Combining languages
did not always give the expected result with Ghostscript 10.02 in our
tests, so prefer the main language of the document. Recognition is
done at the rendering resolution, 300 dpi is a good value for OCR.
This repository uses a custom GitHub Actions workflow for CodeQL static analysis located at .github/workflows/static-analysis.yml. To ensure accurate analysis and avoid conflicts with GitHub's default settings, the following repository configurations are required:
- Enable Advanced Setup:
- Go to Settings -> Code security and analysis.
- Under Code scanning, locate CodeQL analysis.
- If "Default" is enabled, click the three dots (...) and select Switch to advanced.
- Disable Default Setup:
- The "Default" setup must be disabled for the custom workflow to upload results successfully.
- Custom Workflow Dependencies:
- Our custom workflow is designed to install specific project dependencies and perform a manual build before the analysis. This ensures that CodeQL has a complete build graph for the C sources in this repository.
Note: If the Default setup is active, GitHub may reject the results uploaded by the manual workflow, causing the CI job to fail.
- All free drivers in a PPD-less world - OR - All free drivers in Snaps
- Current activity on Printer Applications
- PostScript Printer Application (Snap Store): Printer Application Snap for PostScript printers which are supported by the manufacturer's PPD files. User can add PPD files if the needed one is not included or outdated.
- Ghostscript Printer Application (Snap Store): Printer Application with Ghostscript and many other drivers, for practically all Linux-supported printers which are not PostScript and not supported by HPLIP or Gutenprint.
- HPLIP Printer Application (Snap Store): HPLIP in a Printer Application Snap. Supports nearly every HP printer ever made. Installing HP's proprietary plugin (needed for a few printers) into the Snap is supported and easily done with the web interface.
- Gutenprint Printer Application (Snap Store): High quality output and a lot of knobs to adjust, especially for Epson and Canon inkjets but also for many other printers, in a Printer Application Snap.
- Legacy Printer Application (not available as Snap): It is a part of the pappl-retrofit package and it makes drivers classically installed for the system's classically installed CUPS available in a Printer Application and this way for the CUPS Snap. It is especially helpful for drivers which are not (yet) available as Printer Application.
- PAPPL: Base infrastructure for all the Printer Applications linked above.
- PAPPL CUPS driver retro-fit library: Retro-fit layer to integrate CUPS drivers consisting of PPD files, CUPS filters, and CUPS backends into Printer Applications.
- Printer Applications 2020 (PDF)
- Printer Applications 2021 (PDF)
- CUPS 2018 (PDF, pages 28-29)
- CUPS 2019 (PDF, pages 30-35)
- cups-filters 2018 (PDF, page 11)
- cups-filters 2019 (PDF, pages 16-17)
- cups-filters 2020 (PDF)
- cups-filters 2021 (PDF)
- cups-filters 2022 (PDF)