print

Print figure or save to file

Syntax

print
print('argument1','argument2',...)
print(handle,'filename')
print argument1 argument2 ... argumentn
cdata = print('-RGBImage')
cdata = print(fig,'-RGBImage')

Description

print sends the contents of the current figure, including bitmap representations of any user interface controls, to the printer using the device and system printing command defined by printopt.

print('argument1','argument2',...) is the function form of print. It enables you to pass variables for any input arguments. This form is useful for passing file names and handles (for example, print(handle,'filename'). See Batch Processing for an example. Also see Specifying the Figure to Print for further examples.

    Note:   Print input only takes string variables and object handles as inputs. Strings passed in as cell array or structure inputs are not accepted.

print argument1 argument2 ... argumentn prints the figure using the specified arguments.

cdata = print('-RGBImage') return RGB image data for the current figure. Use the quoted string, '-RGBImage', in parentheses for this syntax.

cdata = print(fig,'-RGBImage') return RGB image data for the specified figure. Use the quoted string, '-RGBImage' in parentheses.

Using the '-RGBImage' option differs from screen captures in that all printing features apply to the output, such as setting the resolution or using InvertHardcopy.

The following arguments apply to both the function and the command form:

ArgumentDescription

handle

Print the specified object.

filename

Direct the output to the PostScript® file designated by filename. If filename does not include an extension, print appends an appropriate extension.

-ddriver

Print the figure using the specified printer driver, (such as color PostScript). If you omit -ddriver, print uses the default value stored in printopt.m. The table in Printer Drivers lists all supported device types.

-dformat

Copy the figure to the system Clipboard (Microsoft® Windows® platforms only). To be valid, the format for this operation must be either -dmeta (Windows Enhanced Metafile) or -dbitmap (Windows Bitmap).

-dformat filename

Export the figure to the specified file using the specified graphics format (such as TIFF). The table of Graphics File Formats lists all supported graphics file formats.

-smodelname

Print the current Simulink® model modelname.

-options

Specify print options that modify the action of the print command. (For example, the -noui option suppresses printing of user interface controls.) Printing Options lists available options.

Printer Drivers

The following table shows the more widely used printer drivers supported by MATLAB® software. If you do not specify a driver, the default setting shown in the previous table is used. For a list of all supported printer drivers, type print -d at the MATLAB prompt. Some things to remember:

  • As indicated in Description the -d switch specifies a printer driver or a graphics file format:

    • Specifying a printer driver without a file name or printer name (the -P option) sends the output formatted by the specified driver to your default printer, which may not be what you want to do.

        Note:   On Windows systems, when you use the -P option to identify a printer, if you specify any driver other than -dwin or -dwinc, MATLAB writes the output to a file with an appropriate extension but does not send it to the printer.

        However, if you setup a shared network printer and specify the printer with the network path in the print command, then you can print to that printer.

    • Specifying a -dmeta or a -dbitmap graphics format without a file name places the graphic on the system Clipboard, if possible (Windows platforms only).

    • Specifying any other graphics format without a file name creates a file in the current folder with a name such as figureN.fmt, where N is 1, 2, 3, ... and fmt indicates the format type, for example, eps or png.

  • Not all drivers are supported on all platforms. Support is noted in the first column of the table.

  • If you specify a particular printer with the -P option and do not specify a driver, a default driver for that printer is selected, either by the operating system or by MATLAB , depending on the platform:

    • On Windows, the driver associated with this particular printing device is used.

    • On Macintosh and UNIX® platforms, the driver specified in printopt.m is used

See Selecting the Printer in the Graphics documentation for more information.

Printer Driver

Print Command Option String

PostScript Level 3 black and white

-dps

PostScript Level 3 color

-dpsc

PostScript Level 2 black and white

-dps2

PostScript Level 2 color

-dpsc2

Windows color (Windows only)

-dwinc

Windows monochrome (Windows only)

-dwin

Graphics File Formats

To save a figure in a standard graphics format, specify a format option and file name. To set the resolution of the output file for a built-in MATLAB format, use the -r switch. (For example, -r300 sets the output resolution to 300 dots per inch.) The -r switch is also supported for Windows Enhanced Metafiles, JPEG, TIFF and PNG files.

For more information, see Printing and Exporting Without a Display and Resolution Considerations.

    Note:   When you print to a file, the file name must have fewer than 128 characters, including path name. When you print to a file in your current folder, the filename must have fewer than 126 characters, because MATLAB places './' or '.\'' at the beginning of the filename when referring to it.

The following table shows the supported output formats for exporting from figures and the option settings to use. All formats except for EMF are supported on both Windows and UNIX platforms.

Graphics Format

Bitmap or Vector

Print Command Option String

BMP monochrome BMP

Bitmap

-dbmpmono

BMP 24-bit BMP

Bitmap

-dbmp16m

BMP 8-bit (256-color) BMP (this format uses a fixed colormap)

Bitmap

-dbmp256

BMP 24-bit

Bitmap

-dbmp

EMF

Vector

-dmeta

EPS Level 3 black and white

Vector

-deps

EPS Level 3 color

Vector

-depsc

EPS Level 2 black and white

Vector

-deps2

EPS Level 2 color

Vector

-depsc2

HDF 24-bit

Bitmap

-dhdf

JPEG 24-bit

Bitmap

-djpeg

PBM (plain format) 1-bit

Bitmap

-dpbm

PBM (raw format) 1-bit

Bitmap

-dpbmraw

PCX 1-bit

Bitmap

-dpcxmono

PCX 24-bit color PCX file format, three 8-bit planes

Bitmap

-dpcx24b

PCX 8-bit newer color PCX file format (256-color)

Bitmap

-dpcx256

PCX Older color PCX file format (EGA/VGA, 16-color)

Bitmap

-dpcx16

PDF Color PDF file format

Vector

-dpdf

PGM Portable Graymap (plain format)

Bitmap

-dpgm

PGM Portable Graymap (raw format)

Bitmap

-dpgmraw

PNG 24-bit

Bitmap

-dpng

PPM Portable Pixmap (plain format)

Bitmap

-dppm

PPM Portable Pixmap (raw format)

Bitmap

-dppmraw

SVG Scalable Vector Graphics (For Simulink Models Only)

Vector

-dsvg

TIFF 24-bit

Bitmap

-dtiff or -dtiffn

TIFF preview for EPS files

Bitmap

-tiff

The TIFF image format is supported on all platforms by most word processors for importing images. The -dtiffn variant writes an uncompressed TIFF. JPEG is a lossy, highly compressed format that is supported on all platforms for image processing and for inclusion into HTML documents on the Web. To create these formats, MATLAB renders the figure using the opengl rendering method and the resulting bitmap is then saved to the specified file.

Printing and Exporting Without a Display

On a UNIX platform, where you can start in MATLAB -nodisplay mode (matlab -nodisplay), you can print using most of the drivers you can use with a display and export to most of the same file formats.

All the PostScript devices function in -nodisplay mode on UNIX platforms. The graphic devices -djpeg, -dpng, -dtiff (compressed TIFF bitmaps), and -tiff (EPS with TIFF preview) work.

The same is true for the -noFigureWindows startup option which suppresses figures on all platforms. On Windows platforms the -dwin, -dwinc, and -dsetup options operate as usual under -noFigureWindows. However, the printpreview GUI does not function in this mode. Naturally, the Windows only -dwin and -dwinc output formats cannot be used on UNIX or Mac platforms with or without a display.

The formats which you cannot generate in nodisplay mode on UNIX and Mac platforms are:

  • bitmap (-dbitmap) — Windows bitmap file

  • bmp (-dbmp...) — Monochrome and color bitmaps

  • hdf (-dhdf) — Hierarchical Data Format

  • svg (-dsvg) — Scalable Vector Graphics file

  • tiffn (-dtiffn) — TIFF image file, no compression

When you start MATLAB in -nodisplay or -noFigureWindows mode on any platform, MATLAB:

  • Does not print or export uicontrols.

  • Always uses the painters renderer, even if you specify the -opengl option with the print command.

Printing Options

This table summarizes options that you can specify for print. The second column links to tutorials that provide operational details. Also see Resolution Considerations for information on controlling output resolution.

Option

Description

-append

PostScript devices only ('-dps', '-dpsc', '-dpsc2', and '-dpsc2'). Append figure to existing PostScript file.

-cmyk

PostScript devices only. Print with CMYK colors instead of RGB. See "Setting CMYK Color".

-ddriver

Printing only. Printer driver to use. See Printer Drivers table.

-dformat

Exporting only. Graphics format to use. See "Graphics Format Files" table.

-fhandle

Handle of figure to print. Note that you cannot specify both this option and the -swindowtitle option. See "Which Figure Is Printed".

-loose

PostScript printing only. Use loose bounding box for PostScript output. See "Producing Uncropped Figures".

-noui

Suppress printing of user interface controls. See "Excluding User Interface Controls".

-opengl

Render using the OpenGL® renderer. Use this renderer when exporting to a bit-mapped format.

You cannot specify this method in conjunction with -painters.

-painters

Render using the Painter's algorithm. Use this renderer when exporting to a vector format, such as PostScript, PDF, and scalable vector graphics.

Note that you cannot specify this method in conjunction with -opengl.

-Pprinter

Specify name of printer to use. On Macintosh computers, printer names shown in the print dialog might not work when specified at the command line using the -P option. See "Selecting the Printer" for more information.

-rnumber

PostScript and built-in raster formats only. Specify resolution in dots per inch. Defaults to 90 for Simulink, 150 for figures in image formats and OpenGL, screen resolution for metafiles, and 864 otherwise. Use -r0 to specify screen resolution. For details, see Resolution Considerations and "Setting the Resolution".

-swindowtitle

Specify name of Simulink system window to print. Note that you cannot specify both this option and the -fhandle option. See "Which Figure Is Printed".

-v

Display the Java® Print dialog on all platforms.

Resolution Considerations

Use -rnumber to specify the resolution of the generated output. In general, using a higher value yields higher quality output but at the cost of larger output files. Resolution affects the resolution and output size of all MATLAB built-in raster formats.

    Note:   In headless (nodisplay) mode, writing to certain image formats is not done by built-in drivers, as it is when a display is being used. These formats are -djpeg, -dtiff, and -dpng. Furthermore, the -dhdf and -dbmp formats cannot be generated in headless mode (but you can substitute -dbmp16m for -dbmp). See Printing and Exporting Without a Display for details on printing when not using a display.

The effect of the -r option on output quality can be subtle at ordinary magnification when using the OpenGL renderer and writing to one of the MATLAB built-in raster formats, or when generating vector output that contains an embedded raster image (for example, PostScript or PDF). The effect of specifying higher resolution is more apparent when viewing the output at higher magnification or when printed, since a larger -r setting provides more data to use when scaling the image.

When generating fully vectorized output (as when using the painters renderer to output a vector format such as PostScript or PDF), the resolution setting affects the degree of detail of the output; setting resolution higher generates crisper output (but small changes in the resolution may have no observable effect). For example, the gap widths of lines that do not use a solid ('-') linestyle can be affected.

Paper Sizes

MATLAB printing supports a number of standard paper sizes. You can select from the following list by setting the PaperType property of the figure or selecting a supported paper size from the Print dialog box.

Property Value

Size (Width by Height)

usletter

8.5 by 11 inches

uslegal

8.5 by 14 inches

tabloid

11 by 17 inches

A0

841 by 1189 mm

A1

594 by 841 mm

A2

420 by 594 mm

A3

297 by 420 mm

A4

210 by 297 mm

A5

148 by 210 mm

B0

1029 by 1456 mm

B1

728 by 1028 mm

B2

514 by 728 mm

B3

364 by 514 mm

B4

257 by 364 mm

B5

182 by 257 mm

arch-A

9 by 12 inches

arch-B

12 by 18 inches

arch-C

18 by 24 inches

arch-D

24 by 36 inches

arch-E

36 by 48 inches

A

8.5 by 11 inches

B

11 by 17 inches

C

17 by 22 inches

D

22 by 34 inches

E

34 by 43 inches

Printing Tips

Setting Default Printer

You can edit the file printopt.m to set the default printer type and destination. If you want to set up a new printer, use the operating system printer management utilities. Restart MATLAB if you do not see a printer which is already setup.

Figures with Resize Functions

The print command produces a warning when you print a figure having a callback routine defined for the figure ResizeFcn. To avoid the warning, set the figure PaperPositionMode property to auto or select Auto (Actual Size, Centered) in the File > Print Preview dialog box.

Troubleshooting Microsoft Windows Printing

If you encounter problems such as segmentation violations, general protection faults, or application errors, or the output does not appear as you expect when using Microsoft printer drivers, try the following:

  • If your printer is PostScript compatible, print with one of the MATLAB built-in PostScript drivers. There are various PostScript device options that you can use with print, which all start with -dps.

  • The behavior you are experiencing might occur only with certain versions of the print driver. Contact the print driver vendor for information on how to obtain and install a different driver.

  • Copy the figure as a Windows Enhanced Metafile using the Edit > Copy Figure menu item on the figure window menu or the print -dmeta option at the command line. You can then import the file into another application for printing.

    You can set copy options in the figure's File > Preferences > Copying Options dialog box. The Windows Enhanced Metafile Clipboard format produces a better quality image than Windows Bitmap.

Printing MATLAB GUIs

You can generally obtain better results when printing a figure window that contains MATLAB uicontrols by setting these key properties:

  • Set the figure PaperPositionMode property to auto. This ensures that the printed version is the same size as the on-screen version. With PaperPositionMode set to auto MATLAB, does not resize the figure to fit the current value of the PaperPosition figure property value. This is particularly important if you have specified a figure ResizeFcn, because if MATLAB resizes the figure during the print operation, ResizeFcn is automatically called.

    To set PaperPositionMode on the current figure, use the command:

    set(gcf,'PaperPositionMode','auto')
    
  • Set the figure InvertHardcopy property to off. By default, MATLAB changes the figure background color of printed output to white, but does not change the color of uicontrols. If you have set the background color, for example, to match the gray of the GUI devices, you must set InvertHardcopy to off to preserve the color scheme.

    To set InvertHardcopy on the current figure, use the command:

    set(gcf,'InvertHardcopy','off')
    
  • Use a color device if you want lines and text that are in color on the screen to be written to the output file as colored objects. Black and white devices convert colored lines and text to black or white to provide the best contrast with the background and to avoid dithering.

  • Use the print command's -loose option to keep a bounding box from being too tightly wrapped around objects contained in the figure. This is important if you have intentionally used space between uicontrols or axes and the edge of the figure and you want to maintain this appearance in the printed output. PDF output ignores the -loose option.

If you print or export in nodisplay mode, none of the uicontrols the figure has will be visible. If you run code that adds uicontrols to a figure when the figure is invisible, the controls will not print until the figure is made visible.

Printing Interpolated Shading with PostScript Drivers

You can print MATLAB surface objects (such as graphs created with surf or mesh) using interpolated colors. However, only patch objects that are composed of triangular faces can be printed using interpolated shading.

Printed output is always interpolated in RGB space, not in the colormap colors. This means that if you are using indexed color and interpolated face coloring, the printed output can look different from what is displayed on screen.

PostScript files generated for interpolated shading contain the color information of the graphics object's vertices and require the printer to perform the interpolation calculations. This can take an excessive amount of time and in some cases, printers might time out before finishing the print job. One solution to this problem is to interpolate the data and generate a greater number of faces, which can then be flat shaded.

To obtain higher resolution (for example, to make text look better), use the -r option to increase the resolution. There is, however, a tradeoff between the resolution and the size of the created PostScript file, which can be quite large at higher resolutions. The default resolution of 150 dpi generally produces good results. You can reduce the size of the output file by making the figure smaller before printing it and setting the figure PaperPositionMode to auto, or by just setting the PaperPosition property to a smaller size.

Examples

Export Figure at Screen Size and Resolution

This example exports a surface plot to a .png file. Setting the current figure's (gcf) PaperPositionMode to 'auto' enables you to resize the figure window and print it at the size you see on the screen.

surf(peaks)
set(gcf,'PaperPositionMode','auto')
print('-dpng','-r0','PeaksSurface')

For additional details, see "Printing Images" in the MATLAB Graphics documentation.

Export to a Vector Format

Export a figure in a vector format using the painters renderer:

bar(1:10)
print -depsc -painters BarPlot

Specifying the Figure to Print

Pass a figure handle as a variable to the function form of print. For example:

h = figure; 
plot(1:4,5:8)
print(h)

Save the figure with the handle h to a PostScript file named Figure2, which can be printed later:

print(h,'-dps','Figure2.ps')

Pass in a file name as a variable:

filename = 'mydata';
print(h, '-dpsc', filename);

(Because a file name is specified, the figure will be printed to a file.)

Specifying the Model to Print

Print a noncurrent Simulink model using the -s option with the title of the window (in this case, f14):

print('-sf14')

If the window title includes any spaces, you must call the function form rather than the command form of print. For example, this command saves the Simulink window title Thruster Control:

print('-sThruster Control')

To print the current system, use:

print('-s')

For information about issues specific to printing Simulink windows, see the Simulink documentation.

Return Image RGB Data for Figure

Create an RGB image of the figure.

surf(peaks)
cData = print('-RGBImage');

Display the image data at full resolution using imshow.

imshow(cData)

Batch Processing

Use the function form of print to pass variables containing file names. For example, this for loop uses file names stored in a cell array to create a series of graphs and prints each one with a different file name:

fnames = {'file1', 'file2', 'file3'};
for k=1:length(fnames)
    surf(peaks)
    print('-dtiff','-r200',fnames{k}) 
end

fnames is a cell of string arrays so each element is a string.

Tiff Preview

The command

print('-depsc','-tiff','-r300','picture1')

saves the current figure at 300 dpi, in a color Encapsulated PostScript file named picture1.eps. The -tiff option creates a 72 dpi TIFF preview, which many word processor applications can display on screen after you import the EPS file. This enables you to view the picture on screen within your word processor and print the document to a PostScript printer using a resolution of 300 dpi.

Alternatives

Select File > Print from the figure window to open the Print dialog box and File > Print Preview to open the Print Preview GUI. For details, see "How to Print or Export".

Was this topic helpful?