OpenPrinting CUPS Filters v2.0.1 - 2024-08-15

Looking for compile instructions? Read the file "INSTALL" instead...

INTRODUCTION

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.

This package contains backends, filters, and other software that was once part of the core CUPS distribution, but during the time when CUPS was developed at Apple, Apple stopped maintaining these parts as they were not needed by Mac OS.

In addition it contains more filters and software developed independently of Apple, especially filters for the PDF-centric printing workflow introduced by OpenPrinting.

Since CUPS 1.6.0 cups-filters is required for using printer drivers (and also driverless printing) with CUPS under Linux. This version of cups-filters is only for CUPS 2.2.2 or newer. Please use the cups-filters 1.x line for older CUPS versions.

CUPS 3.x has a vastly changed architecture (what we call the New Architecture for printing) being all-IPP, only supporting driverless IPP printers and no PPD files and classic CUPS drivers any more. It will not use external filters any more and so will not need this package. This package retro-fits the filter functions of libcupsfilters and libppd to CUPS 2.x.

For compiling and using this package CUPS (2.2.2 or newer), libcupsfilters 2.x, and libppd are needed. It is highly recommended, especially if non-PDF printers are used, to have at least one of Ghostscript (preferred), Poppler, or MuPDF installed.

It also needs gcc (C compiler), automake, autoconf, autopoint, and libtool. On Debian, Ubuntu, and distributions derived from them you could also install the "build-essential" package to auto-install most of these packages.

If Ghostscript is used (via the "gsto..." or the "universal" CUPS filters), Ghostscript 10.00.0 is required (10.01.0 is highly recommended) and it has to be built at least with the "pdfwrite", "ps2write", "cups", "pwgraster", "appleraster", "pclm", "pclm8", "pdfimage24", "pdfimage8", "pxlcolor", and "pxlmono" output devices. libcups of CUPS 2.2.2 or newer is required to build Ghostscript this way.

If you use MuPDF as PDF renderer make sure to use at least version 1.15, as the older versions have bugs and so some files get not printed correctly.

CUPS, this package, and Ghostscript contain some rudimentary printer drivers and especially the filters needed for driverless printing (currently PWG Raster, Apple Raster, PCLm, and PDF output formats, for printers supporting IPP Everywhere, AirPrint, Wi-Fi Direct, and other standards). See the links to the Printer Applications below and also http://www.openprinting.org/drivers/ for a comprehensive set of printer drivers for Linux.

Report bugs to

https://github.com/OpenPrinting/cups-filters/issues

See the "COPYING", "LICENCE", and "NOTICE" files for legal information. The license is the same as for CUPS, for a maximum of compatibility.

LINKS

cups-filters

• Short history
• cups-filters 2.x development
• PDF-based printing workflow

The New Architecture of Printing and Scanning

• The New Architecture - What is it?
• Ubuntu Desktop Team Indaba on YouTube

DOCUMENTATION FROM CUPS-FILTERS 1.x

Most of this is still valid for the current version of cups-filters.

IMAGE PRINTING DEFAULT CHANGED TO "SCALE TO FIT"

Compared to the PostScript-based original CUPS filters there is a change of defaults: The imagetopdf and imagetoraster filters print in "print-scaling=fit" or "scale-to-fit" mode (image is scaled to fill one page but nothing of the image being cut off) by default.

This is done to support photo printing via AirPrint. The photo apps on Apple's iOS devices send print jobs as JPEG images and do not allow to set any options like "print-scaling" or the page size. With "scale-to-fit" mode set by default, the iOS photos come out on one page, as expected.

To get back to the old behavior, supply one of the options "print-scaling=none", "nofitplot", "filplot=Off", "nofit-to-page", or "fit-to-page=Off".

GHOSTSCRIPT RENDERING OF FILLED PATHS

When Ghostscript is rendering PostScript or PDF files into a raster format the filled paths are ususally rendered with the any-part-of-pixel method as it is PostScript standard. On low-resolution printers, like label printers with 203 dpi, graphics output can get inaccurate and so for example bar codes do not work any more. This problem can be solved by letting Ghostscript use the center-of-pixel method.

This can be done by either supplying the option "-o center-of-pixel" or "-o CenterOfPixel" on the command line when printing or by adding a "CenterOfPixel" option to the PPD file and set it to "true", for example by adding the following lines to the PPD file of the print queue (usually in /etc/cups/ppd/):

*OpenUI *CenterOfPixel/Center Of Pixel: PickOne
*OrderDependency: 20 AnySetup *CenterOfPixel
*DefaultCenterOfPixel: true
*CenterOfPixel true/true: ""
*CenterOfPixel false/false: ""
*CloseUI: *CenterOfPixel

This option can be used when the print queue uses the gstoraster filter.

GHOSTSCRIPT RENDERING: HALFTONING AND DITHERING

When using gstoX filters, it's possible to control halftone screens and dithering using "-o halftone-type=XXX" command line job option or "cupsHalftoneType" PPD option.

Ghostscript uses the following default auto-detection:

• DPI < 150: 8x8 ordered dithering
• DPI >= 150: Horn's cosine line halftoning with screen angle 45 deg

with "-o halftone-type=XXX", you can use other algorithms with additional options.

Algorithms available:

• -o halftone-type=bi-level, simple black-or-white threshold, best suited for label printers
• -o halftone-type=stochastic (also =yes), stochastic threshold-array halftoning
• -o halftone-type=foo2zjs, high-quality per-color halftone screen, best for laser/ink printers, with the following configuration:
  Frequency=150,
  Angle=105 (Cyan), 165 (Magenta), 30 (Yellow), 45 (Black), 37 (def),
  Spot Function=CosineDot
• -o halftone-type=dithering, forces 8x8 ordered dithering
• -o halftone-type=genordered[-frequency][-angle][-dotshape][-gamma]
• -o halftone-type=spot[-frequency][-angle][-dotshape][-gamma]

genordered is a halftone+ordered dithering algorithm,
  frequency - line-per-inch, number of halftone cells per inch.
              Lower produces larger dots, higher - smaller.
              Values good for 203DPI label printer: 50-60
                              600DPI laser printer: 106-150
  angle - screen orientation, in degrees.
  dotshape - one of:
    0=CIRCLE, 1=REDBOOK, 2=INVERTED, 3=RHOMBOID, 4=LINE_X, 5=LINE_Y,
    6=DIAMOND1, 7=DIAMOND2, 8=ROUNDSPOT
  gamma - value from 1 to 99, fraction of exponent gamma (pix ^ 0.xx)

spot is a halftone algorithm from PDF specification,
  frequency, angle, gamma - same as for genordered
  dotshape - one of:
    0=SimpleDot 1=InvertedSimpleDot 2=DoubleDot 3=InvertedDoubleDot
    4=CosineDot 5=Double 6=InvertedDouble 7=Line 8=LineX 9=LineY 10=Round
    11=Ellipse 12=EllipseA 13=InvertedEllipseA 14=EllipseB 15=EllipseC
    16=InvertedEllipseC 17=Square 18=Cross 19=Rhomboid 20=Diamond

Algorithm could be selected per-queue, for example:
  lpadmin -p printer -o halftone-type-default=genordered-150-45

POSTSCRIPT PRINTING RENDERER AND RESOLUTION SELECTION

If you use CUPS with this package and a PostScript printer then the included pdftops filter converts the print job data which is in PDF format into PostScript. By default, the PostScript is generated with Ghostscript's "ps2write" output device, which generates a DSC-conforming PostScript with compressed embedded fonts and compressed page content. This is resource-saving and leads to fast wire transfer of print jobs to the printer.

Unfortunately, Ghostscript's PostScript output is not compatible with some printers due to interpreter bugs in the printer and in addition, processing (by Ghostscript or by the printer's interpreter) can get very slow with high printing resolutions when parts of the incoming PDF file are converted to bitmaps if they contain graphical structures which are not supported by PostScript. The bitmap problem especially occurs on input files with transparency, especially also the ones produced by Cairo (evince and many other GNOME/GTK applications) which unnecessarily introduces transparency even if the input PDF has no transparency.

Therefore there are two possibilities to configure pdftops at runtime:

1. Selection of the renderer: Ghostscript, Poppler, pdftocairo, Adobe Reader, or MuPDF

Ghostscript has better color management and is generally optimized more for printing. Poppler produces a PostScript which is compatible with more buggy built-in PostScript interpreters of printers and it leads to a somewhat quicker workflow when graphical structures of the input PDF has to be turned into bitmaps. Adobe Reader is the PDF renderer from Adobe, the ones who created PDF and PostScript. pdftocairo is a good choice for the PDF output of Cairo (for example when printing from evince). It is less resource-consuming when rasterizing graphical elements which cannot be represented in PostScript (like transparency). Note that pdftocairo only supports PDF input using DeviceRGB, DeviceGray, RGB or sGray and is not capable of generating PostScript level 1. So its support is only experimental and distributions should not choose it as default.

Poppler does not explicitly support turning colored PDF files into grayscale PostScript, that's why grayscale/monochrome printing could result in color output.
Use alternative backends, such as Ghostscript or MuPDF, if this is the case with your printer.

The selection is done by the "pdftops-renderer" option, setting it to "gs", "pdftops", "pdftocairo", "acroread", "mupdf", or "hybrid":

Per-job: lpr -o pdftops-renderer=pdftops ... Per-queue default: lpadmin -p printer -o pdftops-renderer-default=gs Remove default: lpadmin -p printer -R pdftops-renderer-default

By default, pdftops uses Ghostscript if this does not get changed at compile time, for example by the Linux distribution vendor.

Hybrid means Ghostscript for most printers, but Poppler's pdftops for Brother, Minolta, and Konica Minolta. Printer make and model information comes from the PPD or via the "make-and-model" option.

2. Limitation of the image rendering resolution

If graphical structures of the incoming PDF file have to be converted to bitmaps due to limitations of PostScript, the conversion of the file by pdftops or the rendering by the printer can get too slow if the bitmap resolution is too high or the printout quality can degrade if the bitmap resolution is too low.

By default, pdftops tries to find out the actual printing resolution and sets the resolution for bitmap generation to the same value. If it cannot find the printing resolution, it uses 300 dpi. It never goes higher than a limit of 1440 dpi. Note that this default limit can get changed at compile time, for example by the Linux distribution vendor.

The resolution limit for bitmaps can be changed to a lower or higher value, or be set to unlimited. This is done by the option "pdftops-max-image-resolution", setting it to the desired value (in dpi) or to zero for unlimited. It can be used per-job or as per-queue default as the "pdftops-renderer" option described above.

The "pdftops-max-image-resolution" option is ignored when Adobe Reader is selected as PDF renderer.

POSTSCRIPT PRINTING DEBUG MODE

Sometimes a PostScript printer's interpreter errors, crashes, or somehow else misbehaves on Ghostscript's output. To find workarounds (currently we have already workarounds for Brother and Kyocera) it is much easier to work with uncompressed PostScript. To get uncompressed PostScript as output, send a job with the "psdebug" option, with commands like the following:

lpr -P <printer> -o psdebug <file>
lp -d <printer> -o psdebug <file>

If you want to send your job out of a desktop application, run

lpoptions -p <printer> -o psdebug

to make "psdebug" a personal default setting for you.

To extract the PostScript output for a developer to analyse it, clone your print queue to a one which prints into a file:

cupsctl FileDevice=yes
lpadmin -p test -E -v file:/tmp/printout \
  -P /etc/cups/ppd/<name of original queue>.ppd

and print into this queue as described above. The PostScript output is in /tmp/printout after the job has completed.

This option does not change anything if Poppler's pdftops is used as renderer.

CUPS FILTERS FOR PDF AS STANDARD PRINT JOB FORMAT

Here is documentation from the former CUPS add-on tarball with the filters for the PDF-based printing workflow: imagetopdf, texttopdf, pdftopdf, and pdftoraster

The original filters are from http://sourceforge.jp/projects/opfc/

NOTE: the texttops filter shipping with this package is a simple wrapper script for backward compatibility with third-party PPD files and custom configurations. It is not referred to in the cupsfilters.convs file and therefore not used by the default configuration. Direct conversion of text to PostScript is deprecated in the PDF-based printing workflow. So do not use this filter when creating new PPD files or custom configurations. The parameters for this filter are the same as for texttopdf (see below) as the texttops filter calls the texttopdf filter plus Ghostscript's pdf2ps.

Tool FOOMATIC-HASH and allowing values for foomatic-rip filter

Several CVEs for printing stack exploited a different security issue to craft a PPD which would call the filter foomatic-rip, and provided malicious values for PPD options FoomaticRIPCommandLine, FoomaticRIPCommandLinePDF, and FoomaticRIPOptionSetting, because the filter constructs a command out of the values and runs it in shell under user lp.

To mitigate the issue, foomatic-rip now allows only values which are allowed by admin, and the tool foomatic-hash was invented. The tool scans PPD file or a path for drivers with affected values, and generates two files - the first with found values for admin to review, and the second with hashes of unique values present in the scanned file or path. If admin reviews the found values and finds them correct, the found values will be allowed once the file with hashes is moved into the directory /etc/foomatic/hashes.d.

The filter foomatic-rip reads files with allowed hashes from two directories - /etc/foomatic/hashes.d and /usr/share/foomatic/hashes.d. The former is meant for hashes allowed by the local admin, the latter is for printer driver projects to put there files with hashes of values which are present in their project after the values are reviewed.

Filters

IMAGETOPDF

1. INTRODUCTION

This program is "imagetopdf". "imagetopdf" is a CUPS filter which reads a single image file, converts it into a PDF file and outputs it to stdout.

This program accepts the following image file format;

gif, png, jpeg, tiff, photocd, portable-anymap, portable-bitmap,
portable-graymap, portable-pixmap, sgi-rgb, sun-raster, xbitmap,
xpixmap, xwindowdump

xbitmap, xpixmap and xwindowdump images are converted into png images by the "convert" command. Other kinds of image file format can be supported if the "convert" command support them.

Output PDF file format conforms to PDF version 1.3 specification, and input image is converted and contained in the output PDF file as a binary format non-compression image.

"imagetopdf" may outputs multiple pages if the input image exceeds page printable area.

2. COMMAND LINE

"imagetopdf" is a CUPS filter, and the command line arguments, environment variables and configuration files are in accordance with the CUPS filter interface.