Converter Chains

This section should help to isolate the source of trouble. Trouble here means the printing result isn't the expected one.

CUPS uses a chain of filters to convert a to be printed document into the data the printer device requires. In order to print a portable document format (PDF) the following filter chain could be used:

or

Each filter touches the document somehow. So, if the print result isn't the expected one, we need to examine what happens to the document at which filter.

List the used converter chain

The used filters are a result of some configurations and availability of filter programs. To see, what will be used to print a PDF one can run the cupsfilter tool:

Generic call:

$ cupsfilter -p <some ppd file> -o <some printing params> -m printer/foo -e --list-filters <pdf file>

Note: The cupsfilter tool is part of the cups package; In the following examples the file test/DK1209.pdf is used, which is part of the package.; The DK1209 roll provides portrait orientation pre-cut labels of the size 29 mm x 62 mm. And the same document would perfectly fit in landscape orientation to a DK2251 roll with an endless label of a width of 62 mm. But see below what happens...

Example:

$ cupsfilter -p ql800.ppd -m printer/foo --list-filters -e  ~/example.pdf
pdftopdf
pdftoraster
rastertoql

Selection of filters

Why these filters are used or how they are selected?

The document to print has a MIME type of:

$ file --mime-type --brief test/DK1209.pdf
application/pdf

Now we can take a look into the configuration files in /usr/share/cups/mime and into the used PPD file. In the PPD file we can find the data MIME type, the printer converter expects. In our rastertoql it is application/vnd.cups-raster. If we grep for this string in /usr/share/cups/mime it lists (at least on my host) the filters mupdftoraster, gstoraster and pdftoraster capable to produce this MIME type.
On the other hand all of these filters accept the MIME type application/vnd.cups-pdf as their input. Since they all do the same job, the cost value selects one of these (the lowest cost wins) - in my case pdftoraster.
But there is still a missing link from the input document's type application/pdf to the required MIME type application/vnd.cups-pdf. If we now grep for application/pdf we find pdftopdf for exact this conversion. So, now the chain is complete:

A real example

Lets print a so called small adress label of the size 62 mm x 29 mm. We can find the corresponding PDF in test/DK1209.pdf. We can print it on various DK rolls:

DK1209: 29 mm x 62 mm portrait oriented pre-cut labels
DK11209: 62 mm x 29 mm landscale oriented pre-cut labels
DK2211: 29 mm endless label
DK2606: 62 mm endless label
DK2251: 62 mm endless label, bi-colour

In the following example, I tried it with the DK2251 roll.

With the tool cupsfilter we can now use the full chain to get the printer data, or we can stop earlier to get the data of each single filter to examine it. pdfinfo is a nice tool to examine one of the conversion results (in this case the PDF related MIMEs):

$ pdfinfo test/DK1209.pdf
Creator:        Writer
Producer:       LibreOffice 7.0
CreationDate:   Tue Nov  2 08:37:14 2021 CET
Tagged:         no
UserProperties: no
Suspects:       no
Form:           none
JavaScript:     no
Pages:          1
Encrypted:      no
Page size:      175.748 x 82.2047 pts
Page rot:       0
File size:      13630 bytes
Optimized:      no
PDF version:    1.6

The important information for us here are the "Page size" and "Page rot" lines.

To get the result of the pdftopdf filter we stop at the application/vnd.cups-pdf MIME type:

$ cupsfilter -p ql800.ppd -o "PageSize=DK2251" -m application/vnd.cups-pdf test/DK1209.pdf > processed.pdf
$ pdfinfo processed.pdf
[…]
Page size:      175.748 x 82.2047 pts
Page rot:       90
[…]

As we can see, "Page rot" is now 90 ° which means pdftopdf has rotated this landscape document into portrait mode. This for example is wrong, since the document fits perfectly onto the DK2251 label roll.

Note: pdftopdf uses the format of the specified roll to guess its orientation. And an endless label always seems like a portrait orientation for this filter. That's why it rotates our test document.

Lets have a look to the next filter stage. This time we stop at the application/vnd.cups-raster MIME type:

$ cupsfilter -p ql800.ppd -o "PageSize=DK2251" -m application/vnd.cups-raster test/DK1209.pdf > raster.raw

In this case the simple file tool gives us the information we need.

$ file raster.raw
raster.raw: Cups Raster version 3, Little Endian, 300x300 dpi, 343x732 pixels 8 bits/color 8 bits/pixel ColorOrder=Chunky ColorSpace=gray

Here we can see, the raster has a size of 343x732 pixels and thus, is in portrait orientation.

And with the full filter chain, rastertoql provides the remaining information about the raster.

$ cupsfilter -p ql800.ppd -o "PageSize=DK2251" -m printer/foo -e test/DK1209.pdf > printer.data
[…]
DEBUG: Page size requested: DK2251
DEBUG: Use settings from roll 'DK2251'
DEBUG: (cups-rastertoql:ql_dk_information_get:286) Inherit settings from roll 'full_size_large_margin'
DEBUG: Continuous length label medium detected.
DEBUG: Bi-colour capable medium detected.
DEBUG: Left hardware margin: 2.0 mm.
DEBUG: mediaBox = [ 0.000000 0.000000 175.748031 82.204724 ]; rotate = 90
DEBUG: size = DK1209
WARNING: 'pdftoraster' has guessed a bad page format. Your print will fail somehow
WARNING: requested print page is: 'DK2251', but the CUPS raster is made for: 'DK1209'
DEBUG: cupsInteger0 (1684302196) value ignored, yet
DEBUG: Intended print size: 28.9 mm (82 pts) x 62.1 mm (176 pts)
DEBUG: Monochrome raster detected
DEBUG: PPD reported page size is: 175.7 points x 2834.6 points
DEBUG: (cups-rastertoql:ql_input_raster_crop:386) Raster width: 343 dots, raster height: 732 dots
DEBUG: (cups-rastertoql:ql_input_raster_crop:387) Media width: 732 dots, media height: 11811 dots
DEBUG: (cups-rastertoql:ql_input_raster_crop:429) Left skip: 0 dots, left_keep: 343 dots
DEBUG: (cups-rastertoql:ql_input_raster_crop:430) Top skip: 0 dots, top_keep: 732 dots
DEBUG2: (cups-rastertoql:cups_ql_monochome_page_print:208) Entering monochrome page print
INFO: pdftoraster (PID 187309) exited with no errors.
DEBUG2: (cups-rastertoql:cups_ql_monochome_page_print:274) Monochrome page print done
[…]

We can see here, we requested for DK2251 roll, but the filter stage for application/vnd.cups-raster generation decided to change it. The print will fail or at least we get a result we don't expect (which also means it has failed).

Some suggestions:

the printing parameter pdfAutoRotate=off prevents pdftopdf doing annoying rotations.
deteting the currently not used roll definitions from the PPD file prevents pdftoraster from accidently guessing a different roll and adapting the print to it
if you don't want to touch the PPD but print on endless labels, avoid label formats which are also available as pre-cut labels.
define a different pre-cut roll type of the same size as a printing parameter when printing on endless labels. Use one, which has the same orientation. In our landscape oriented example test/DK1209.pdf to print in landscape orientation use the DK11209 instead of the really loaded DK2251 for example (the latter one will not work, if you want to print in bi-colour mode, since only the DK2251 roll has this feature and the rastertoql filter will check for it to switch to a different data format on request).