Differences between revisions 27 and 28
Revision 27 as of 2019-12-04 19:29:45
Size: 11038
Editor: Brian Potkin
Comment: Superfluous indefinite article.
Revision 28 as of 2022-02-21 17:54:06
Size: 12083
Editor: Brian Potkin
Comment: Review, reassess and revevise.
Deletions are marked like this. Additions are marked like this.
Line 15: Line 15:
DebianMan:cupsfilter comes with the DebianPkg:cups package. The idea behind it is to use the filter subsystem (provided on stretch and buster in the DebianPkg:cups, DebianPkg:cups-server-common, DebianPkg:cups-daemon, DebianPkg:cups-filters and DebianPkg:cups-filters-core-drivers packages) to convert a file to a specific format. The processing is identical to that done by CUPS and the filter subsystem when a file makes its way to the printer and ink or toner is put on paper; except there is no paper output.

We can use cupsfilter to examine the state of the filter conversions at each stage of the filtering process and determine whether behaviour is reasonable and correct. The filters in ''/usr/lib/cups/filter'' can also be used as standalone programs to examine the conversions but this is not generally encouraged. Please see the ''WARNING'' or ''NOTES'' section in the [[DebianMan:7/filter|filter]] manual.

When tracking down a problem with printing the cupsfilter utilty is a useful tool to complement what is produced by an [[DissectingandDebuggingtheCUPSPrintingSystem#errorlog|error_log]].
DebianMan:cupsfilter comes with the DebianPkg:cups package. The idea behind it is to use the filter subsystem (provided in the DebianPkg:cups, DebianPkg:cups-server-common, DebianPkg:cups-daemon, DebianPkg:cups-filters and DebianPkg:cups-filters-core-drivers packages) to convert a file to a specific format. The processing is identical to that done by CUPS and the filter subsystem when a file makes its way to the printer and ink or toner is put on paper; except there isn't paper output.

We can use cupsfilter to examine the state of the filter conversions at each stage of the filtering process and determine whether behaviour is reasonabl and correct. The filters in ''/usr/lib/cups/filter'' can also be used as standalone programs to examine the conversions but this is not generally encouraged. Please see the ''WARNING'' or ''NOTES'' section in the [[DebianMan:7/filter|filter]] manual.

When tracking down a problem with printing the cupsfilter utilty is a useful tool to complement what is produced by an [[CUPSDebugging#errorlog|error_log]].

{{{#!wiki note
A user can access much of what cupsfilter offers when it is executed as `/usr/sbin/cupsfilter`. However, when a [[#ppd|PPD is called for]], as it is with the ''-e'' option, root privileges may be required.
}}}
Line 24: Line 28:
The ease of examining the output from cupsfilter at a particular stage of a filtering process depends on the file type produced. PDF and !PostScript can be viewed by DebianPkg:gv, DebianPkg:xpdf, DebianPkg:mupdf, DebianPkg:evince, DebianPkg:okular etc. CUPS, PWG and Apple raster output viewing is a little harder to accomplish because there is [[DebianBug:803789|no Debian package]] for the viewer. !RasterView will handle [[DriverlessPrinting#pdls|PWG and Apple raster]] files because the PWG format is based on [[https://www.cups.org/doc/spec-raster.html|CUPS raster]] and Apple Raster is very similar to PWG raster.

The source code for !RasterView can be downloaded from the [[https://www.msweet.org/rasterview/|principal CUPS developer's web site]]. For successful compiling you are advised to obtain source code which has a version greater than v1.5. The following command would do this for you:

{{{
wget https://github.com/michaelrsweet/rasterview/releases/download/v1.7.1/rasterview-1.7.1.tar.gz
The ease of examining the output from cupsfilter at a particular stage of a filtering process depends on the file type produced. PDF and !PostScript can be viewed by DebianPkg:gv, DebianPkg:xpdf, DebianPkg:mupdf, DebianPkg:evince, DebianPkg:okular or DebianPkg:zathura. CUPS, [[CUPSDriverlessPrinting#pdls|PWG and Apple]] raster output viewing is handled by DebianPkg:rasterview. The PWG format is based on [[https://www.cups.org/doc/spec-raster.html|CUPS raster]] and Apple Raster is very similar to PWG raster.

The source code for !RasterView may be downloaded from the [[https://www.msweet.org/rasterview/|principal CUPS developer's web site]]. For successful compiling you are advised to obtain source code which has a version greater than v1.5. The following command would do this for you:

{{{
wget https://github.com/michaelrsweet/rasterview/releases/download/v1.8/rasterview-1.8.tar.gz
Line 36: Line 40:
mv rasterview-1.7.1.tar.gz rasterview mv rasterview-1.8.tar.gz rasterview
Line 38: Line 42:
tar zvxf rasterview-1.7.1.tar.gz tar zvxf rasterview-1.8.tar.gz
Line 47: Line 51:
Viewing the file which is actually sent to the printer (the printer-ready file) may or may not be possible because it depends on whether it is !PostScript, PDF, PCL, [[DriverlessPrinting#rasters|raster data]] or vendor-specific data. [[http://www.ghostscript.com/download/gpcldnld.html|ghostPCL]] is a PCL viewer. It is sufficient to put the `pcl6-916-linux_x86` binary in ''/usr/local/bin'' for it to function. Often the only way to view a file which is classified by the [[DebianMan:1/file|file]] utility as data is to send it to the printer without passing through the filtering system. One way is: Viewing the file which is actually sent to the printer (the printer-ready file) may or may not be possible because it depends on whether it is !PostScript, PDF, PCL, [[CUPSDriverlessPrinting#rasters|raster data]] or vendor-specific data. [[https://www.ghostscript.com/releases/index.html|Ghostpcl]] is a PCL viewer. It is sufficient to put the binary in ''/usr/local/bin'' for it to function. Often the only way to view a file which is classified by the [[DebianMan:1/file|file]] utility as data is to send it to the printer without passing through the filtering system. One way is:
Line 53: Line 57:
The use examples described on this page use the stretch version of cupsfilter and its [[DebianMan:cupsfilter|documentation]], but there is very little difference in the utility's behaviour on stretch and buster. The use examples described on this page use the Debian 11 (bullseye) version of cupsfilter and its [[DebianMan:cupsfilter|documentation]], but there is very little difference in the utility's behaviour on previous distributions.
Line 82: Line 86:
You almost certainly want to use a PPD file with cupsfilter to test the operation of a particular print queue. As root on stretch and buster you will have access to the PPD for the queue in ''/etc/cups/ppd''; as a user you will not because the PPD files in ''/etc/cups/ppd/'' are, by default, not world-readable. If you want to test the filtering of an installed print queue as a user you can, however, get its PPD file using DebianMan:cups-driverd. You almost certainly want to use a PPD file with cupsfilter to test the detailed operation of a particular print queue. As root you will have access to the PPD for the queue in ''/etc/cups/ppd''; as a user you will not because the PPD files in ''/etc/cups/ppd/'' are, by default, not world-readable. If you want to test the filtering of an installed print queue as a user you can, however, get its PPD file using DebianMan:cups-driverd.

 * This technique applies only to legacy printing. That is, printing with those printers having print queues set up with vendor drivers.
Line 103: Line 109:

For a [[CUPSDriverlessPrinting|modern printer]] a PPD may be obtained from

{{{
driverless <URI>
}}}

The command

{{{
driverless
}}}

gives the URI.
Line 160: Line 180:
A number of the [[#dest|previous commands]] have relied solely on the ''*.convs'' files in ''/usr/share/cups/mime'' to determine the filters used in the filtering chain. But filters can also be specified in the PPD file with a ''*cupsFilter'' line. This will be the last filter applied in the filter chain; laserjet2200.ppd has A number of the [[#dest|previous commands]] has relied solely on the ''*.convs'' files in ''/usr/share/cups/mime'' to determine the filters used in the filtering chain. But filters can also be specified in the PPD file with a [[https://openprinting.github.io/cups/doc/spec-ppd.html#cupsFilter|*cupsFilter]] or [[https://openprinting.github.io/cups/doc/spec-ppd.html#cupsFilter2|*cupsFilter2]] line. This will be the last filter applied in the filter chain; laserjet2200.ppd has
Line 204: Line 224:
As another example: the [[CUPSDriverlessPrinting#generator1|everywhere PPD]] for an HP ENVY 4500 contains the lines

{{{
*cupsFilter2: "image/jpeg image/jpeg 0 -"
*cupsFilter2: "image/urf image/urf 100 -"
}}}

and

{{{
/usr/sbin/cupsfilter -p ENVY4500.ppd -m printer/foo -e /etc/services --list-filters
}}}

shows all the filters to be employed:

{{{
texttopdf
pdftopdf
gstoraster
rastertopwg
}}}

The output of the final filter is [[CUPSDriverlessPrinting#pdls|Apple raster]], viewable with [[#viewers|RasterView]].
Line 209: Line 253:

Translation(s): none


cupsfilter uses the CUPS printing system filters to convert a file to another format.

Introduction

cupsfilter comes with the cups package. The idea behind it is to use the filter subsystem (provided in the cups, cups-server-common, cups-daemon, cups-filters and cups-filters-core-drivers packages) to convert a file to a specific format. The processing is identical to that done by CUPS and the filter subsystem when a file makes its way to the printer and ink or toner is put on paper; except there isn't paper output.

We can use cupsfilter to examine the state of the filter conversions at each stage of the filtering process and determine whether behaviour is reasonabl and correct. The filters in /usr/lib/cups/filter can also be used as standalone programs to examine the conversions but this is not generally encouraged. Please see the WARNING or NOTES section in the filter manual.

When tracking down a problem with printing the cupsfilter utilty is a useful tool to complement what is produced by an error_log.

A user can access much of what cupsfilter offers when it is executed as /usr/sbin/cupsfilter. However, when a PPD is called for, as it is with the -e option, root privileges may be required.

File Viewers

The ease of examining the output from cupsfilter at a particular stage of a filtering process depends on the file type produced. PDF and PostScript can be viewed by gv, xpdf, mupdf, evince, okular or zathura. CUPS, PWG and Apple raster output viewing is handled by rasterview. The PWG format is based on CUPS raster and Apple Raster is very similar to PWG raster.

The source code for RasterView may be downloaded from the principal CUPS developer's web site. For successful compiling you are advised to obtain source code which has a version greater than v1.5. The following command would do this for you:

wget https://github.com/michaelrsweet/rasterview/releases/download/v1.8/rasterview-1.8.tar.gz

The executable can be compiled after installing the g++ and libfltk1.3-dev packages and doing

mkdir rasterview
mv rasterview-1.8.tar.gz rasterview
cd rasterview
tar zvxf rasterview-1.8.tar.gz
./configure
make

The rasterview executable produced would be put in /usr/local/bin.

Using RasterView isn't too hard. Zooming in and out is mouse-driven with its left and right buttons; or the - and = keys can be used. The bottom left of the window has buttons < and > for moving forwards and backwards in a document; or use the SPACE and BACK keys from the keyboard. The ESC key exits the program.

Viewing the file which is actually sent to the printer (the printer-ready file) may or may not be possible because it depends on whether it is PostScript, PDF, PCL, raster data or vendor-specific data. Ghostpcl is a PCL viewer. It is sufficient to put the binary in /usr/local/bin for it to function. Often the only way to view a file which is classified by the file utility as data is to send it to the printer without passing through the filtering system. One way is:

lp -d <print_queue> -o raw <final_file>

The use examples described on this page use the Debian 11 (bullseye) version of cupsfilter and its documentation, but there is very little difference in the utility's behaviour on previous distributions.

The pdfinfo Utility

pdfinfo is in the poppler-utils package. It is a useful tool for examining information extracted from a PDF submited to CUPS and comparing it to a PDF produced by the filtering system. The pdftopdfandPageRotation wiki page uses this technique to track rotation of pages in a PDF document from the Page rot: attribute.

By default pdfinfo <PDF> will display only information about the first page in a PDF file. The -f and -l options specify the range of pages to examine.

For the number of pages, N, in a file:

pdfinfo <PDF> | grep Pages

For information on a range of pages in the file:

pdfinfo -f 4 -l 12 <PDF>

For information on all the pages in the file:

pdfinfo -l N <PDF>

Using a PPD File with cupsfilter

You almost certainly want to use a PPD file with cupsfilter to test the detailed operation of a particular print queue. As root you will have access to the PPD for the queue in /etc/cups/ppd; as a user you will not because the PPD files in /etc/cups/ppd/ are, by default, not world-readable. If you want to test the filtering of an installed print queue as a user you can, however, get its PPD file using cups-driverd.

  • This technique applies only to legacy printing. That is, printing with those printers having print queues set up with vendor drivers.

Let's suppose the print queue is for a LaserJet 2200 using the Gutenprint PPD. A searchable list of PPDs on the system is available to a user with

/usr/sbin/lpinfo -m | less

and the URI for the PPD is

gutenprint.5.2://hp-lj_2200/expert

Then

/usr/lib/cups/daemon/cups-driverd cat gutenprint.5.2://hp-lj_2200/expert > laserjet2200.ppd

gives you the PPD.

For a modern printer a PPD may be obtained from

driverless <URI>

The command

driverless

gives the URI.

Commands using /usr/sbin/cupsfilter are intended for a user who has obtained a PPD as described above. For a user with root privileges the command cupsfilter would suffice. In this case the -p option would be /etc/cups/ppd/<PPD> because <PPD> is readable by such a user.

Specifying the Destination File Type

The cupsfilter -m option allows files at each stage of the filtering process to be produced and examined. application/pdf is the default output without anything for -m specified, but, depending on the filtering chain,

  • application/postscript

  • application/vnd.cups-pdf

  • application/vnd.cups-postscript

  • application/vnd.cups-raster

are also possibly wanted for this option.

In other words:

/usr/sbin/cupsfilter -p laserjet2200.ppd -m application/vnd.cups-raster -o number-up=2 test.ps > out.ps 2> log

would give a raster file output if that was appropriate for the print queue. The filters used with a particular queue may be obtained with (see below):

/usr/sbin/cupsfilter -p laserjet2200.ppd -m printer/foo -e --list-filters

vnd.cups-* indicates a printer-ready file; that is, a file which has print options using the -o option incorporated in it. Print options, for example, N-up, scaling and rotation, are applied to the pages in the submitted file by a filter, usually pdftopdf.

Here is a small PostScript file,test.ps, which you can use. As a user:

/usr/sbin/cupsfilter -p laserjet2200.ppd -m application/postscript -o number-up=2 test.ps > out.ps 2> log

You should find out.ps looks no different from test.ps. In fact, it is also the same size as test.ps. The log shows the only filter which runs is gziptoany. gziptoany is designed to Copy (and uncompress) files to stdout. The result is not unexpected because conversion is from MIME meda type PostScript to MIME media type PostScript. The -o option has not been applied. Nothing much has happened here.

How about

/usr/sbin/cupsfilter -p laserjet2200.ppd -m application/pdf -o number-up=2 test.ps > out.ps 2> log ?

From the log we see Ghostscript converting PostScript to PDF with pstopdf. The output looks no different from the input though. Again, the -o has not been taken account of. That's to be expected for conversion to MIME media type application/pdf. Progessing to

/usr/sbin/cupsfilter -p laserjet2200.ppd -m application/vnd.cups-pdf -o number-up=2 test.ps > out.pdf 2> log

to convert to a file suitable to be sent to a printer, probably after some further processing. pstopdf is invoked again but it is followed by pdftopdf. The latter filter performs the very important task of page management; the application of N-up is obvious in a PDF viewer.

Obtaining the File which is Sent to the Printer

A number of the previous commands has relied solely on the *.convs files in /usr/share/cups/mime to determine the filters used in the filtering chain. But filters can also be specified in the PPD file with a *cupsFilter or *cupsFilter2 line. This will be the last filter applied in the filter chain; laserjet2200.ppd has

*cupsFilter "application/vnd.cups-raster 100 rastertogutenprint 5.2"

To use this filter with cupsfilter

  • the -e option to cupsfilter is required and
  • the destination file type has to indicate that conversion to a format suitable to be sent to the printer is necessary.

The command to ascertain which filters will be used:

/usr/sbin/cupsfilter -p laserjet2200.ppd -m printer/foo -e -o number-up=2 --list-filters test.ps

The outcome:

gstopdf
pdftopdf
gstoraster
rastertogutenprint.5.2

Or diagramatically:

         +---------+     +----------+              +------------+                 +------------------------+
         |         | pdf |          | vnd.cups-pdf |            | vnd.cups-raster |                        |  
test.ps=>| gstopdf |====>| pdftopdf |=============>| gstoraster |================>| rastertogutenprint.5.2 |=>PCL
         |         |     |          |              |            |                 |                        |                           
         +---------+     +----------+              +------------+                 +------------------------+

An output file and a log of the process is obtained with:

/usr/sbin/cupsfilter -p laserjet2200.ppd -m printer/foo -o number-up=2 test.ps -e > out.pcl 2> log

out.pcl, identified as HP PCL printer data by file, should be viewable with ghostpcl. The file outputs for the intermediate stages can be obtained as indicted earlier and are viewable with a PDF viewer and RasterView.

As another example: the everywhere PPD for an HP ENVY 4500 contains the lines

*cupsFilter2: "image/jpeg image/jpeg 0 -"
*cupsFilter2: "image/urf image/urf 100 -"

and

/usr/sbin/cupsfilter -p ENVY4500.ppd -m printer/foo -e /etc/services --list-filters

shows all the filters to be employed:

texttopdf
pdftopdf
gstoraster
rastertopwg

The output of the final filter is Apple raster, viewable with RasterView.

See Also


CategoryPrinter