print

Print figure or save to specific file format

collapse all in page

Syntax

print(filename,formattype)
print(filename,formattype,formatoptions)
print
print(printer)
print(driver)
print(printer,driver)
print('-clipboard',clipboardformat)
print(resize,___)
print(resolution,___)
print(renderer,___)
print('-noui',___)
print(fig,___)
cdata = print('-RGBImage');

Description

example

print(filename,formattype) saves the current figure to a file using the specified file format, such as print('BarPlot','-dpng'). If the file name does not include an extension, then print appends the appropriate one.

print(filename,formattype,formatoptions) specifies additional options that are available for some formats.

example

print prints the current figure to the default printer.

print(printer) specifies the printer. Specify the printer as a character vector or string containing the printer name preceded by -P, for example, '-Pmy printer'. The printer must be set up on your system.

print(driver) specifies the driver. Use this option if you want to ensure that the printed output is either black and white or color.

print(printer,driver) specifies the printer and the driver.

example

print('-clipboard',clipboardformat) copies the current figure to the clipboard using the format specified by clipboardformat. You can paste the copied figure into other applications.

example

print(resize,___) maximizes the figure size to fill the page. Specify resize as '-bestfit' to preserve the figure's aspect ratio or '-fillpage' to ignore the aspect ratio. These options are valid only when saving to a page format (PDF, and PS) or printing to a printer. Use this option with any of the input arguments from the previous syntaxes.

example

print(resolution,___) uses the specified resolution. Specify the resolution as a character vector or string containing an integer value preceded by -r, for example, '-r200'. Use this option with any of the input arguments from the previous syntaxes.

print(renderer,___) uses the specified renderer. Specify the renderer as either '-painters' or '-opengl'.

example

print('-noui',___) excludes user interface controls, such as push buttons and sliders, from the saved or printed output. It does not exclude user interface objects that can contain an axes, such as a uitab or uipanel.

example

print(fig,___) saves or prints the figure or Simulink® block diagram specified by fig.

example

cdata = print('-RGBImage'); returns the RGB image data for the current figure. This option differs from screen captures in that all printing features apply to the output. You can also specify the resolution, renderer, '-noui', and fig options with this syntax. However, you cannot specify a Simulink block diagram.

Examples

collapse all

Create a bar chart and print it to your system default printer. If you do not specify the figure to print, then print uses the current figure.

bar(1:10)
print

Create a plot and copy it to the system clipboard.

plot(1:10)
print('-clipboard','-dmeta')

You can paste the copied plot into other applications.

Create a plot and save it as a PNG image file.

bar(1:10)
print('BarPlot','-dpng')

print saves the plot as BarPlot.png.

Create a plot and save it as an Encapsulated PostScript® file.

bar(1:10)
print('BarPlot','-depsc')

print saves the plot as BarPlot.eps.

Save the current figure as an Encapsulated PostScript File and add a TIFF preview.

surf(peaks)
print('SurfacePlot','-depsc','-tiff')

Save a specific figure by passing its object variable to print.

fig = figure;
plot(1:10)
print(fig,'MySavedPlot','-dpng')

Alternatively, refer to a figure using the value of its Number property, which is the integer value that displays in the figure window title bar. For example, save the figure with Figure 2 displayed in the title bar. Precede the integer value by -f.

figure(2);
plot(1:10)
print('-f2','MySavedPlot','-dpng')

Save a surface plot to a PNG file. Set the PaperPositionMode property for the figure to 'auto' so that it saves at the size displayed on the screen. Use '-r0' to save it with screen resolution.

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

Save a figure that fills the page using the '-fillpage' option.

bar([1 10 7 8 2 2 9 3 6])
print('FillPageFigure','-dpdf','-fillpage')

Create a figure with a push button that clears the axes. Save the figure to a JPEG file without saving the push button.

surf(peaks)
uicontrol('Style','pushbutton','String','Clear',...
    'Position',[20 20 50 20],'Callback','cla');
print('SurfacePlot','-djpeg','-noui')

Return the RGB image data for a figure.

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

Display the image data at full resolution using imshow.

imshow(cdata)

Create a surface plot. Return the RGB image data for the figure and specify the image resolution. Then, convert the image data to a movie frame, F. 

surf(peaks)
cdata = print('-RGBImage','-r120');
F = im2frame(cdata);

Input Arguments

collapse all

File name, specified as a character vector or string containing the desired file name and path.

Example: 'My Saved Chart'

Example: 'Folder\My Saved Chart'

Example: "My Saved Chart"

The maximum file name length, including the path, is operating system and file format specific. Typically, the file name should be no more than 126 characters, or if you include the path, then no more than 128 characters.

Data Types: char | string

File format, specified as one of the options in these tables.

Bitmap Image File

Bitmap images contain a pixel-based representation of the figure. The size of the generated file depends on the figure, the format, and your system resolution. Bitmap images are widely used by Web browsers and other applications that display graphics. However, they do not support transparency or scale well and you cannot modify individual graphics objects, such as lines and text, in other graphics applications.

This table lists the supported bitmap image formats.

OptionBitmap Image FormatCorresponding File Extension
'-djpeg'JPEG 24-bit.jpg
'-dpng'PNG 24-bit.png
'-dtiff'TIFF 24-bit (compressed).tif
'-dtiffn'TIFF 24-bit (not compressed).tif
'-dmeta'Enhanced metafile (Windows only).emf
'-dbmpmono'BMP Monochrome .bmp
'-dbmp'BMP 24-bit .bmp
'-dbmp16m'BMP 24-bit .bmp
'-dbmp256'BMP 8-bit (256 color, uses a fixed colormap) .bmp
'-dhdf'HDF 24-bit.hdf
'-dpbm'PBM (plain format) 1-bit.pbm
'-dpbmraw'PBM (raw format) 1-bit.pbm
'-dpcxmono'PCX 1-bit.pcx
'-dpcx24b'PCX 24-bit color (three 8-bit planes).pcx
'-dpcx256'PCX 8-bit newer color (256 color).pcx
'-dpcx16'PCX older color (EGA/VGA 16-color).pcx
'-dpgm'PGM (plain format).pgm
'-dpgmraw'PGM (raw format).pgm
'-dppm'PPM (plain format).ppm
'-dppmraw'PPM (raw format).ppm

Vector Graphics File

Vector graphics files store commands that redraw the figure. This type of format scales well, but can result in a large file. Also, it might not produce the correct 3-D arrangement of objects in certain cases. Some applications support extensive editing of vector graphics formats. However, some applications do not support editing beyond resizing the graphic. In general, try to make all the necessary changes while your figure is still in MATLAB®.

If you set the Renderer property for the figure, then print uses that renderer when generating output. Otherwise, print chooses the appropriate renderer. Typically, print uses the Painters renderer when generating vector graphics files. For some complex figures, print uses the OpenGL® renderer instead. If it uses the OpenGL renderer, then the vector graphics file contains an embedded bitmap image, which might limit the extent to which you can edit the image in other applications. To ensure that print uses the Painters renderer, set the Renderer property for the figure to 'painters' or specify '-painters' as an input argument to print.

If you want output that has transparency, then create a vector graphics file using a Metafile, PDF, or SVG format. If you use a PS or EPS format, then transparency is only supported for the figure and axes backgrounds. Bitmap images do not support transparency, but will closely match what is shown on screen to give the appearance of transparency.

Note

The default figure renderer is OpenGL. If the figure renderer differs from the renderer used when generating output, some details of the saved figure can differ from the figure on the display. If necessary, you can make the displayed figure and the saved figure use the same renderer. Set the Renderer property for the figure or specify the renderer input argument to the print function.

This table lists the supported vector graphics formats.

OptionVector Graphics FormatCorresponding File Extension
'-dpdf'Full page Portable Document Format (PDF) color.pdf
'-deps'Encapsulated PostScript (EPS) Level 3 black and white.eps
'-depsc'Encapsulated PostScript (EPS) Level 3 color.eps
'-deps2'Encapsulated PostScript (EPS) Level 2 black and white.eps
'-depsc2'Encapsulated PostScript (EPS) Level 2 color.eps
'-dmeta'Enhanced Metafile (Windows® only).emf
'-dsvg'SVG (Scalable Vector Graphics).svg
'-dps'Full-page PostScript (PS) Level 3 black and white.ps
'-dpsc'Full-page PostScript (PS) Level 3 color.ps
'-dps2'Full-page PostScript (PS) Level 2 black and white.ps
'-dpsc2'Full-page PostScript (PS) Level 2 color.ps

You cannot save Simulink block diagrams in PostScript or EPS formats.

Note

Only PDF and full-page PS formats use the first two elements of the PaperPosition property. Other formats ignore these values.

Additional formatting options supported by some file formats, specified as one or more of these values:

  • '-tiff' — Include a TIFF preview. EPS files only.

  • '-loose' — Use a loose bounding box. EPS and PS files only.

  • '-cmyk' — Use CMYK colors instead of RGB colors. EPS and PS files only.

  • '-append' — Append the figure to an existing PS file. PS files only.

Example: print('my file','-deps','-tiff','-loose') saves the current figure to the file my file.eps using a loose bounding box and includes a TIFF preview.

Printer name, specified as a character vector or string containing -P and the printer name.

Example: '-Pmy local printer'

Example: "-Pmy local printer"

To view a list of available printers, use this command:

[~,printers] = findprinters

If you do not specify a printer, then print uses the system default printer. If you want to set up a new printer or select a different default printer, use the operating system printer management utilities. Restart MATLAB if you do not see a printer that is set up already.

Data Types: char | string

Printer driver, specified as '-dwin', '-dwinc', '-dprn', or '-dprnc'. If you do not specify a driver, then print uses the driver returned from the printopt function.

The option you use depends on your system, for example:

SystemDriverOutput
Windows'-dwin'Black and white
'-dwinc'Color
Linux® or Mac'-dprn' Black and white
'-dprnc'Color

Format copied to clipboard, specified as one of these options:

  • '-dmeta' — Enhanced metafile (Windows only)

  • '-dbitmap' — Bitmap image (Windows and Mac OS)

  • '-dpdf' — PDF file (Windows and Mac OS)

Option to expand figure to fill page, specified as one of these values:

  • '-fillpage' — Maximize the size of the figure to fill the page. Leave a .25 inch margin on all sides of the page. The tick marks, layout, and aspect ratio of the figure might change.

  • '-bestfit' — Maximize the size of the figure to fill the page, but preserve the aspect ratio of the figure. The figure might not fill the entire page. This option leaves a minimum page margin of .25 inches.

Both options are valid only when printing a figure to a printer or saving to a page format such as PDF and PS. They are not valid for Simulink block diagrams.

Resolution, specified as a character vector or a string containing -r and an integer value indicating the resolution in dots per inch. For example, '-r300' sets the output resolution to 300 dots per inch. To specify screen resolution, use '-r0'.

In general, using a higher resolution value yields higher-quality output, but at the cost of higher memory use and larger output files. The higher the resolution setting, the longer it takes to render your figure.

Specifying the resolution is useful when creating a bitmap image or when using the OpenGL renderer with a vector graphics file format (since OpenGL produces a bitmap image even with vector formats). Specifying the resolution has no effect when using the Painters renderer with a vector graphics file format, since Painters produces a true vector graphics file that contains the commands that redraw the figure.

Note

Simulink printing does not support the resolution option. For higher quality output of Simulink models, use a vector format such as SVG or PDF.

Data Types: char | string

Graphics renderer, specified as '-opengl' or '-painters'.

  • '-opengl' — OpenGL renderer. Use this renderer when saving bitmap images. OpenGL produces a bitmap image even with vector formats, which might limit the extent to which you can edit the image in other applications.

  • '-painters' — Painters renderer. Use this renderer when saving vector graphics files. If you save to a vector graphics file and if the figure RendererMode property is set to 'auto', then print automatically attempts to use the Painters renderer. If you want to ensure that your output format is a true vector graphics file, then specify the Painters renderer. For example:

    print('-painters','-deps','myVectorFile')

Note

Sometimes, saving a file with the '-painters' option can cause longer rendering times and, in rare cases, might not accurately arrange graphics objects in 3-D views. Also, the Painters renderer cannot print or save lines thinner than one pixel.

If you do not specify the renderer, then print automatically uses the appropriate renderer to produce the output format requested. However, if you set the Renderer property for the figure, then print uses that renderer when generating output.

Figure object or Simulink block diagram. You can refer to a figure using either its object variable name or using the figure number preceded by -f. For example, -f2 refers to the figure with a Number property value of 2. When specifying a Simulink block diagram, precede the model name with -s. Specify the current model using '-s'.

You cannot save Simulink block diagrams in PostScript or EPS formats.

Output Arguments

collapse all

Image data, returned as an n-by-m-by-3 array. The size of the image data array depends on the PaperPosition property of the figure and the output resolution.

Note

Starting in R2015b, if you use print with the '-r0' option on a high-resolution system, then the size of the cdata output array is larger than in previous releases or on other systems. Also, the number of elements in cdata might not match the size of the figure in pixels based on the figure’s PaperPosition property and the root’s ScreenPixelsPerInch property. For more information, see DPI-Aware Behavior in MATLAB.

Limitations

  • Starting MATLAB in no display mode on Linux or using the -noFigureWindows startup option on any platform has these limitations for print:

    • Printing or saving figures with visible uicontrols errors. To print or save the figure, hide the uicontrols by setting their Visible properties to 'off', or use the '-noui' option with the print function.

    • Always uses the painters renderer, even if you specify the '-opengl' option.

  • In MATLAB Online™, print only prints to PDF. For additional file format options, save the figure to a file by specifying a filename.

More About

collapse all

Current Figure

The current figure is typically the last figure that you create or click with the mouse. User interaction can change the current figure.

To print a specific figure, specify the figure as the first input argument. If you do not specify a figure, then the print function acts on the figure returned by gcbf. If gcbf returns empty, then print acts on the figure returned by gcf.

Compatibility Considerations

Starting in R2016a, printed and saved figures match the size of the figure on the screen by default. Previously, printed and saved figures were 8-by-6 inches by default.

Tips

  • You can set properties of the figure to control some printing and saving parameters. This table lists properties of the figure related to printing and saving.

    Figure PropertyDescription
    PaperPositionSize of the printed or saved figure. If printing to a printer or a full-page output format, then this property also determines the figure location on the page.
    PaperPositionModeSpecifies whether to use the PaperPosition property or the size of the figure on the screen to set the size of the printed or saved figure.
    InvertHardcopySpecifies whether to use the current background color of the figure or to change the background color to white when printing or saving the figure.
    PaperOrientationFigure orientation on printed page.
    PaperTypeStandard printer paper size.
    PaperSizeCustom width and height of printer paper.
    PaperUnitsUnits for the PaperSize and PaperPosition properties.

  • If you are using a Linux or Mac system and get an error about an invalid or unrecognized printer, then try specifying a PostScript driver for the driver option. If the printer supports PostScript level 3, try '-dps' for black and white or '-dpsc' for color. If the printer supports PostScript level 2, then try '-dps2' for black and white or '-dps2c' for color. For example:

    print('-dpsc','-Pmy printer')
    To use this driver as the default driver, edit the printopt file. Alternatively, print the figure to a PDF file. Then, print the PDF from an external PDF viewer.

  • If you print a figure that has a callback defined for the SizeChangedFcn property and if the output size differs from the size of the figure on the screen, then the print function displays a warning message. To avoid the warning message, set the PaperPositionMode property for the figure to 'auto'.

Alternative Functionality

Starting in R2020a, you can use the exportgraphics function to save the contents of any axes, figure, chart that can be a child of a figure, tiled chart layout, or container such as a panel. This function provides a better alternative to the print function when you want to:

  • Save graphics displayed in an app or in MATLAB Online

  • Minimize the white space around the content

  • Save a PDF fragment with embeddable fonts

  • Save a subset of the content in the figure

  • Control the background color without having to modify properties on the figure

The copygraphics function (also new in R2020a) provides much of the same functionality as the exportgraphics function, except that it copies the content to your system clipboard instead of saving it to a file. Use this function to copy and paste content from MATLAB into other applications.

See Also

| | | | |

Introduced before R2006a

MATLAB Documentation

Support