Translation(s): српски

An exploration of the imagetopdf and imagetoraster filters.

Contents

  1. Introduction
  2. Testing the Operation of imagetopdf and imagetoraster
  3. Image Size on Target Media
  4. Adjusting Scaling for an Image-1
  5. Adjusting Scaling for an Image-2
  6. Adjusting Scaling for an Image-3
  7. Adjusting Image Position on a Page
  8. Adjusting Page Margins
  9. Adjusting the Image Brightness
  10. Adjusting the Gamma (Luminance) Correction for an Image
  11. Adjusting the Hue (Tint) of an Image
  12. Adjusting the Saturation (Colour) of an Image
  13. imagetopdf or imagetoraster?
  14. Modern Printers and JPEG images
  15. Acknowledgements
  16. See Also

Introduction

As mentioned elsewhere, some filters originally distributed with CUPS were put under the OpenPrinting umbrella after the CUPS project decided maintenance of them was not in its future plans. These filters included those that took image files, such as JPEG and PNG, and processed them to be presented to a printer or another filter. imagetpdf and imagetoraster are the two major filters that undertake this task and they are included in cups-filters. Support for similar filters and some of the options associated with them were removed from CUPS.

The material on this page relies heavily on

Some text from the second source of information has simply been copied verbatim to this page.

Testing the Operation of imagetopdf and imagetoraster

Throughout this account a user will have the opportunity to test options passed to the filters using cupsfilter. A PPD may be obtained from /etc/cups/ppd if the user has root privileges. Alternatively, see this advice. It has been chosen to generate a PDF file with cupsfilter because most users will almost certainly have a PDF viewer available. Generating an output from cupsfilter with -m application/vnd.cups-pdf will require rasterview to examine it.

Image Size on Target Media

Information about an image can be obtained from the display command. The data available for a JPEG image might include: 

Geometry: 630x354+0+0
Resolution: 72x72
Print size: 8.75x4.91667
Unit: PixelsPerInch

The printed image size is projected in inches to be 8.75x4.91667. This is smaller than the dimensions of A4 paper but larger than A5.

Adjusting Scaling for an Image-1

The option used in the imagetopdf and imagetoraster filters that activates normal scaling of the input pages to fit the output page size is -o fit-to-page. By default, the image is scaled to fill one page with none of it being cut off. The image's aspect ratio is respected. This mode is regarded as a reasonable way to print photographs, especially from Apple's iOS devices, which send print jobs as JPEG images and which do not allow setting options like scaling or page size.

Options inherited from CUPS that change the size of a printed image are:

The scaling=percent value is a number from 1 to 800 specifying the size in relation to the page (not the image). A scaling of 100 percent will fill the page as completely as the image aspect ratio allows. A scaling of 200 percent will print on up to 4 pages. The default value is unspecified and the ppi option overrides the scaling option if specified.

The ppi=value value is a number from 1 to 1200 specifying the resolution of the image in pixels per inch. An image that is 3000x2400 pixels will print 10x8 inches at 300 pixels per inch, for example. If the specified resolution makes the image larger than the page, multiple pages will be printed to satisfy the request. The ppi attribute specifies the resolution of an image file in pixels per inch.The default value is the resolution included with the file or 128 if no resolution information is available.

The natural-scaling=percent value is a number from 1 to 800 specifying the size in relation to the natural image size. A scaling of 100 percent will print the image at its natural size, while a scaling of 50 percent will print the image at half its natural size. If the specified scaling makes the image larger than the page, multiple pages will be printed to satisfy the request. The ppi option can be used to override the natural resolution of the image, which controls the natural size.

All three options centre the printed image on the page. 

/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o  PageSize=A4 scaling=30 <image_file> > out.pdf
/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o  PageSize=A4 ppi=300 <image_file> > out.pdf
/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o  PageSize=A4 natural-scaling=50 <image_file> > out.pdf

Adjusting Scaling for an Image-2

Version 1.22.2 of cups-filters added two new page scaling options to the imagetopdf, imagetoraster and pdftopdf filters:

The intention of -o crop-to-fit is to allow fitting an input page of one size onto an output page of a different size without scaling. The size of the page content is maintained when the output paper size only slightly differs from the input paper size. The envisaged use is when A4 content is printed on Letter-sized paper or Letter content is printed on A4-sized paper. The page content is centred and may be cropped to fit the destination page. Whether there are any empty bordes depends on the PageSize option for the output.

-o fill scales the input page to fill completely the imageable area of the whole output page. However, the input and output pages may have different aspect ratios. In this case, the input page is cropped to fit the output aspect ratio, losing some content, and then is scaled. This would print a photo so that it potentially fully fills the destination page. This mode is intended mainly to print photos borderless on all 4 edges of the paper. A user's satisfaction with the result might depend on the degree of cropping. 

/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o PageSize=A5 -o crop-to-fit <image_file> > out.pdf
/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o PageSize=A4 -o fill <image_file> > out.pdf

Adjusting Scaling for an Image-3

Version 1.23.0 of cups-filters added support for the IPP print-scaling attribute to the imagetopdf, imagetoraster and pdftopdf filters:

-o print-scaling=fit scales the image to fill the largest possible portion of the imageable area of the destination page without cropping anything. It is identical to -o fit-to-page.

-o print-scaling=fill scales the image to fill the entire page, preserving the aspect ratio of the document data but potentially cropping portions of the image. It is identical to -o fill.

-o print-scaling=none does not scale the image to fit the requested media size. It is only centred and may be cropped to fit the output page. It is identical to -o crop-to-fit.

-o print-scaling=auto is a little complex in its operation as it depends on the image size in relation to the requested media size and whether the image has a margin.

-o print-scaling=auto-fit is implemented as follows: 

/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o PageSize=A5 -o print-scaling=fill <image_file> > out.pdf
/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o PageSize=A4 -o print-scaling=auto page-top=20 <image_file> > out.pdf

The print dialogs of applications such as Firefox, Evince, Okular and LibreOffice offer the fill, fit, none and auto options, provided

A print scaling option is not offered by the CUPS PPD generator.

Adjusting Image Position on a Page

The -o position=name option specifies the position of the image on the page: 

/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o 'position=bottom-left PageSize=A4 scaling=30' <image_file> > out.pdf
lp -d <printq_name>  o 'position=top PageSize=A4 natural-scaling=25' <image_file>

Adjusting Page Margins

Normally the page margins are set to the hard limits of the printer. Use the -o page-left=value, -o page-right=value, -o page-top=value, and -o page-bottom=value options to adjust the page margins: 

/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o 'page-left=20 \
 page-right=40  page-top=30 page-bottom=50' <image_file> > out.pdf

Adjusting the Image Brightness

The overall brightness of the printed output can be controlled using the -o brightness=percent option. The default is 100. Values greater than 100 will lighten the print, while values less than 100 will darken it. 

/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o brightness=150 <image_file> > out.pdf
lp -d <printq_name> -o brightness=600 <image_file>

Adjusting the Gamma (Luminance) Correction for an Image

The overall gamma correction of the printed output can be controlled by using the -o gamma=value option:

Values greater than 1000 will lighten the print, while values less than 1000 will darken it. The default gamma is 1000. 

/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o gamma=500 <image_file> > out.pdf

Adjusting the Hue (Tint) of an Image

The -o hue=value option will adjust the hue of the printed image.

Value is a number from -180 to 180 and represents the colour hue rotation. The following table summarizes the changes in different colours that might be seen:

Original

hue=-45

hue=45

Red

Purple

Yellow-orange

Green

Yellow-green

Blue-green

Yellow

Orange

Green-yellow

Blue

Sky-blue

Purple

Magenta

Indigo

Crimson

Cyan

Blue-green

Light-navy-blue

The default hue adjustment is 0. 

/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o hue=20 <image_file> > out.pdf

Adjusting the Saturation (Colour) of an Image

The -o saturation=percent option adjusts the saturation of the colours in an image.

The percent argument specifies the colour saturation from 0 to 200. A colour saturation of 0 produces an almost black-and-white print. A value of 200 will make the colours extremely intense.

The default saturation is 100. 

/usr/sbin/cupsfilter -p <PPD> -m application/pdf -o saturation=60 <image_file> > out.pdf

imagetopdf or imagetoraster?

Which of these filters is used in a particular work flow depends on what is given in a PPD by either a *cupsFilter: or *cupsFilter2: line. For example, it is common for an HP PPD to contain:

hpcups is the final filter used in the filter chain and it expects to be given a file with MIME type application/vnd.cups-raster. This means that the goal of all the previous filtering is to produce a file with this MIME type. The filters used to produce cups-raster can be discovered with 

/usr/sbin/cupsfilter -p <HP_PPD> -m application/vnd.cups-raster <image_file> --list-filters

and would show just imagetoraster. On the other hand, some Brother printers have a PPD with

The final filter, brother_lpdwrapper_mfcj880dw, requires to be given a PDF file. One of the filters run to do this is imagetopdf. 

/usr/sbin/cupsfilter -p <Brother_PPD> -m  application/vnd.cups-pdf <image_file> --list-filters

Actually, it doesn't matter whether imagetoraster or imagetopdf is employed because they both deal with the previously described options in exactly the same way.

Modern Printers and JPEG images

If a modern printer is being used with a print queue set up with with either a CUPS or cups-filters generated PPD, it will be observed that there aren't any filters whatsoever used when the input file is a JPEG image. This is because such files are sent directly to the printer and processed there. This is a requirement for the printer to be AirPrint compatible. A PNG file would have to be sent to discover that non-JPEG image files use the imagetoraster and rastertopwg filters.

It is possible, of course, to set up a print queue for a modern printer by employing legacy drivers. Every option described above is then applicable to any valid image type sent to the printer.

However, for the reson given earlier, a modern printer set up with a driverless print queue will not apply any of the imagetopdf and imagetoraster options when the print job is a JPEG image, apart from those options for print scaling. Even then, a print queue would have to be set up as indicated in the note at the end of a previous section.

Acknowledgements

Till Kamppeter <till.kamppeter SPAMFREE AT gmail DOT com> for driving the introduction of extra print scaling options and Dheeraj Yadav <dhirajyadav135 SPAMFREE AT gmail DOT com> for their implementation.

See Also

CategoryPrinter