Open topic with navigation

Save Method

The Save method saves the window contents of an IDL Graphic to an image file.

Example

The following code sample creates a bar plot and saves the image to a PNG file.

x = FINDGEN(41)/10 - 2

gauss = EXP(-x^2)

p = BARPLOT(x, gauss, TITLE='Gaussian Distribution', $

XTITLE='$\it x$', YTITLE='$\it f(x)$', YRANGE=[0,1.1])

t = TEXT(0.75,0.85,'$\it f(x)=exp(-x^2)$', /DATA, FONT_SIZE=24)

p.Save, "gaussian.png", BORDER=10, RESOLUTION=300, /TRANSPARENT

Additional Examples

See Additional Examples for more code examples using the Save method.

Syntax

graphic.Save, Filename [, /APPEND] [, BIT_DEPTH={0|1|2}] [, /BITMAP] [, BORDER=integer] [, /CENTIMETERS] [, /CLOSE] [, /CMYK] [, COMPRESSION={0|1|2}] [, HEIGHT=integer] [, LANDSCAPE] [, PAGE_SIZE=value] [, RESOLUTION=integer] [, /REVERSIBLE] [, TRANSPARENT=array] [, WIDTH=integer] [, XMARGIN=integer] [, YMARGIN=integer]

Arguments

Filename

A string containing the full pathname of the file to which the graphic should be written.

The file format of the saved file is determined from the Filename file suffix. For example, if Filename is image.bmp, the file is saved in bitmap format.

The supported file formats are listed in the following table:

Keywords

APPEND

Note: This keyword is valid only for GIF and PDF files.

Set this keyword to keep the file open after writing out the graphics. The next call to the Save method will then append the new graphics onto the same file. In the final call to Save you should specify both /APPEND and /CLOSE to ensure that the file is closed. See Additional Examples for a code sample that uses APPEND.

Note: When creating multi-image GIF files, the Save method with /APPEND may be called either from the same graphics object or different graphics objects. In either case, you should ensure that the image dimensions are the same for each call to the Save method.

Note: When creating multi-page PDF files, the Save method with /APPEND may be called either from the same graphics object or different graphics objects. In either case, a new page will be added to the PDF file for each call to the Save method.

BIT_DEPTH

Note: This keyword is valid only for PICT, PNG, and TIFF files.

Set this keyword to one of the following values:

BITMAP

Note: This keyword is valid only for EMF, EPS, and PDF files.

For EMF, EPS, and PDF files, the default behavior is to output 2D graphics (such as PLOTs and CONTOURs) in vector format, and 3D graphics in bitmap format. Set this keyword to 1 to force output in bitmap format, or to 0 to force output in vector format. Files in bitmap format will be larger but may give more accurate output (especially for transparency and 3D graphics). Files in vector format will be smaller and allow the resulting file to be edited in external programs.

BORDER

By default, the saved graphic includes all of the background regions around the graphic, out to the edge of the window. Set this keyword to an integer defining the width of the border around the graphic. For example, setting BORDER=0 will trim the graphic so that there are no extra border pixels surrounding the graphic. This keyword is ignored if the output is in vector format (BITMAP=0).

CENTIMETERS

Note: This keyword is valid only for PDF files.

Set this keyword to indicate that the PAGESIZE, WIDTH, HEIGHT, XMARGIN, and YMARGIN values are in centimeters. The default is inches.

CLOSE

Note: This keyword is valid only for GIF and PDF files.

After writing multiple images with the APPEND keyword, use this keyword on the final call to the Save method. For GIF files, CLOSE saves the data and properly closes the file. For PDF files, CLOSE clears the buffer.

See Additional Examples for a code sample that uses CLOSE.

CMYK

Note: This keyword is valid only for EPS and TIFF files.

Set this keyword to save the output image in CMYK format. The default format is RGB. This keyword is ignored if TRANSPARENT is set.

COMPRESSION

Note: This keyword is valid only for TIFF files.

Set this keyword to 0 for no compression (the default), to 1 for Pack bits compression, or to 2 for JPEG compression.

HEIGHT

For image or bitmap files, set this keyword to the height in pixels of the output image. If this keyword is set, the RESOLUTION keyword is ignored and the width is automatically calculated from the window's aspect ratio.

For PDF files, set this keyword to the height in inches (or centimeters if CENTIMETERS is set) of the graphics output. If this keyword is set, the width is automatically calculated from the window's aspect ratio.

LANDSCAPE

Note: This keyword is valid only for PDF files.

Set this keyword to indicate that the PDF output should be drawn in landscape orientation. The default is portrait orientation.

PAGE_SIZE

Note: This keyword is valid only for PDF files.

Set this keyword to a string or a two-element vector [width, height] giving the page size in inches (or centimeters if CENTIMETERS is set). The default value is [8.5, 11]. Allowed string values are "Letter", "Legal", "A4", and "A5".

RESOLUTION

Set this keyword to the output resolution (in dots per inch) to use when saving the window to an image or bitmap file format. If this keyword is not supplied, a default value of 600 DPI is used. The maximum output dimensions are 8192 x 8192. If the output dimensions are larger than these values, the resolution will be automatically reduced. This keyword is ignored if the output is in vector format (BITMAP=0).

REVERSIBLE

Note: This keyword is valid only for JPEG2000 files.

Set this keyword to use reversible (lossless) compression. The default behavior is to use irreversible (lossy) compression.

TRANSPARENT

Note: This keyword is valid only for PNG and TIFF files.

Set this keyword to an RGB value (a three-element vector of the form [R, G, B]) indicating which pixels in the output image should be made transparent. If this keyword is set to 1, the color of the lower left pixel in the image is used as the transparent color.

WIDTH

For image or bitmap files, set this keyword to the width in pixels of the output image. If this keyword is set, the RESOLUTION keyword is ignored and the height is automatically calculated from the window's aspect ratio.

For PDF files, set this keyword to the width in inches (or centimeters if CENTIMETERS is set) of the graphics output. If this keyword is set, the height is automatically calculated from the window's aspect ratio.

XMARGIN

Note: This keyword is valid only for PDF files.

Set this keyword to the x-offset from the lower-left corner of the page in inches (or centimeters if CENTIMETERS is set). The default behavior is to center the graphics on the page.

YMARGIN

Note: This keyword is valid only for PDF files.

Set this keyword to the y-offset from the lower-left corner of the page in inches (or centimeters if CENTIMETERS is set). The default behavior is to center the graphics on the page.

Additional Examples

The following example uses three plot graphics to create a multi-page PDF file. Each time we call the Save method we use the /APPEND keyword, and on the last call we add the /CLOSE keyword to clear out the PDF buffer.

PRO appendPDF_ex

; Create an array of graphic pointers

p = OBJARR(3)

; Create three plots with random data

FOR i = 0, 2 DO BEGIN

  t = 0.1*FINDGEN(50)

  y = SMOOTH(RANDOMU(seed,50), 5)

  p[i] = PLOT(t,y,'b', SYMBOL='D', $

    TITLE='Observation'+STRING(i+1))

ENDFOR

; Build the multi-page PDF file, one page at a time

p[0].Save, 'data1.pdf', /APPEND

p[1].Save, 'data1.pdf', /APPEND

p[2].Save, 'data1.pdf', /APPEND, /CLOSE

END

Version History

See Also

Print Method, Using IDL Graphics