#### 15.2.9 Printing and Saving Plots

The `print` command allows you to send plots to you printer and to save plots in a variety of formats. For example,

    print -dpsc

prints the current figure to a color PostScript printer. And,

    print -deps foo.eps

saves the current figure to an encapsulated PostScript file called `foo.eps`.

The current graphic toolkits produce very similar graphic displays, but differ in their capability to display unusual text and in their ability to print such text. In general, the `"tex"` interpreter (default) is the best all-around performer for both on-screen display and printing. However, for the reproduction of complicated text formulas the `"latex"` interpreter is preferred. The `"latex"` interpreter will not display symbols on-screen, but the printed output will be correct. When printing, use one of the `standalone` options which provide full access to LaTeX commands.

A complete example showing the capabilities of text printing using the `-dpdflatexstandalone` option is:

    x = 0:0.01:3;
    hf = figure ();
    plot (x, erf (x));
    hold on;
    plot (x, x, "r");
    axis ([0, 3, 0, 1]);
    text (0.65, 0.6175, ...
          ['$\displaystyle\leftarrow x = {2 \over \sqrt{\pi}}'...
           '\int_{0}^{x} e^{-t^2} dt = 0.6175$'],
          "interpreter", "latex");
    xlabel ("x");
    ylabel ("erf (x)");
    title ("erf (x) with text annotation");
    print (hf, "plot15_7.pdf", "-dpdflatexstandalone");
    system ("pdflatex plot15_7");
    open plot15_7.pdf

The result of this example can be seen in Figure 15.7

Figure 15.7: Example of inclusion of text with use of `-dpdflatexstandalone`

print ()
print (options)
print (filename, options)
print (hfig, …)
rgb = print (`"-RGBImage"`, …)

  Format a figure for printing and either save it to a file, send it to a printer, or return an RGB image.

  filename defines the name of the output file. If the filename has no suffix then one is inferred from the specified device and appended to the filename. When neither a filename nor the `"-RGBImage"` option is present, the output is sent to the printer. The various options and filename arguments may be given in any order, except for the figure handle argument hfig which must be first if it is present.

  Example: Print to a file using PDF and JPEG formats.

      figure (1);
      clf ();
      surf (peaks);
      print figure1.pdf    # The extension specifies the format
      print -djpg figure1  # Will produce "figure1.jpg" file

  If the first argument is a handle hfig to a figure object then it specifies the figure to print. By default, the current figure returned by `gcf` is printed.

  For outputs to paged formats, for example, PostScript and PDF, the page size is specified by the figure’s `papersize` property together with the `paperunits` property. The location and size of the plot on the page are specified by the figure’s `paperposition` property. The orientation of the page is specified by the figure’s `paperorientation` property.

  For non-page formats—for example, image formats like JPEG—the width and height of the output are specified by the figure’s `paperposition(3:4)` property values.

  The `print` command supports many options:

  `-fh`

    Specify the handle, h, of the figure to be printed.

    Example: Print figure 1.

        figure (1);
        clf ();
        surf (peaks);
        figure (2);
        print -f1 figure1.pdf
        ## Equivalent functional form:
        print (1, "figure1.pdf")

  `-Pprinter`

    Set the printer name to which the plot is sent if no filename is specified.

    Example: Print to printer named PS_printer using PostScript format.

        clf ();
        surf (peaks);
        print -dpswrite -PPS_printer

  `-RGBImage`

    Return an M-by-N-by-3 RGB image of the figure. The size of the image depends on the formatting options. This is similar to taking a screen capture of the plot, but formatting options may be changed such as the resolution or monochrome/color.

    Example: Get the pixels of a figure image.

        clf ();
        surf (peaks);
        rgb = print ("-RGBImage");

  `-opengl`
  `-painters`

    Specifies whether the opengl (pixel-based) or painters (vector-based) renderer is used. This is equivalent to changing the figure’s `"Renderer"` property. When the figure `RendererMode` property is `"auto"` Octave will use the `"opengl"` renderer for raster formats (e.g., JPEG) and `"painters"` for vector formats (e.g., PDF). Those options are only supported for the "qt" graphics tookit.

  `-svgconvert`

    For OpenGL-based graphic toolkits, this enables a different backend toolchain with enhanced characteristics. The toolchain adds support for printing arbitrary characters and fonts in PDF outputs; it avoids some anti-aliasing artifacts in the rendering of patch and surface objects (particularly for 2-D scenes); and it supports transparency of line, patch, and surface objects.

    This option only affects PDF outputs, unless it is combined with `-painters` option, in which case raster outputs are also affected.

    Caution: `-svgconvert` may lead to inaccurate rendering of image objects.

  `-portrait`
  `-landscape`

    Specify the orientation of the plot for printed output. For non-printed output the aspect ratio of the output corresponds to the plot area defined by the `"paperposition"` property in the orientation specified. This option is equivalent to changing the figure’s `"paperorientation"` property.

  `-fillpage`
  `-bestfit`

    When using a page-based format (PDF, PostScript, printer) ignore the `"paperposition"` property and have the plot occupy the entire page. The option `-fillpage` will stretch the plot to occupy the page with 0.25 inch margins all around. The option `-bestfit` will expand the plot to take up as much room as possible on the page without distorting the original aspect ratio of the plot.

  `-color`
  `-mono`

    Color or monochrome output.

  `-solid`
  `-dashed`

    Force all lines to be solid or dashed, respectively.

  `-noui`

    Don’t print uicontrol objects such as pushbuttons which may overlay the plot. This is the default behavior and it is not possible to include uicontrol objects in the output without using an external screen capture tool.

  `-rNUM`

    Resolution of bitmaps in dots per inch (DPI). For both metafiles and SVG the default is the screen resolution; for other formats the default is 150 DPI. To specify screen resolution, use `"-r0"`.

    Example: high resolution raster output.

        clf ();
        surf (peaks (), "facelighting", "gouraud");
        light ();
        print ("-r600", "lit_peaks.png");

  `-Sxsize,ysize`

    Plot size in pixels for raster formats including PNG, JPEG, PNG, and (unusually (SVG)). For all vector formats, including PDF, PS, and EPS, the plot size is specified in points. This option is equivalent to changing the width and height of the output by setting the figure property `paperposition(3:4)`. When using the command form of the print function you must quote the xsize,ysize option to prevent the Octave interpreter from recognizing the embedded comma (’,’). For example, by writing "-S640,480".

  `-tight`
  `-loose`

    Force a tight or loose bounding box for EPS files. The default is tight.

  `-preview`

    Add a preview to EPS files. Supported formats are:

    `-interchange`

      Provide an interchange preview.

    `-metafile`

      Provide a metafile preview.

    `-pict`

      Provide a pict preview.

    `-tiff`

      Provide a TIFF preview.

  `-append`

    Append PostScript or PDF output to an existing file of the same type.

  `-Ffontname`
  `-Ffontname:size`
  `-F:size`

    Use fontname and/or fontsize for all text. fontname is ignored for some devices: dxf, fig, hpgl, etc.

  `-ddevice`

    The available output format is specified by the option device, and is one of the following (devices marked with a "*" are only available with the Gnuplot toolkit):

    Vector Formats

    `pdf`
    `pdfcrop`

      Portable Document Format. The `pdfcrop` device removes the default surrounding page.

      The OpenGL-based graphics toolkits have limited support for text. Limitations include using only ASCII characters (e.g., no Greek letters) and support for just three base PostScript fonts: Helvetica (the default), Times, or Courier. Any other font will be replaced by Helvetica.

      For an enhanced output with complete text support and basic transparency, use the `-svgconvert` option.

    `ps`
    `ps2`
    `psc`
    `psc2`

      PostScript (level 1 and 2, mono and color). The OpenGL-based graphics toolkits always generate PostScript level 3.0 and have limited support for text.

    `eps`
    `eps2`
    `epsc`
    `epsc2`

      Encapsulated PostScript (level 1 and 2, mono and color). The OpenGL-based toolkits always generate PostScript level 3.0 and have limited support for text.

    `pslatex`
    `epslatex`
    `pdflatex`
    `pslatexstandalone`
    `epslatexstandalone`
    `pdflatexstandalone`

      Generate a LaTeX file `filename.tex` for the text portions of a plot and a file `filename.(ps|eps|pdf)` for the remaining graphics. The graphics file suffix .ps|eps|pdf is determined by the specified device type. The LaTeX file produced by the ‘`standalone`’ option can be processed directly by LaTeX. The file generated without the ‘`standalone`’ option is intended to be included from another LaTeX document. In either case, the LaTeX file contains an `\includegraphics` command so that the generated graphics file is automatically included when the LaTeX file is processed. The text that is written to the LaTeX file contains the strings exactly as they were specified in the plot. If any special characters of the TeX mode interpreter were used, the file must be edited before LaTeX processing. Specifically, the special characters must be enclosed with dollar signs (`$ … $`), and other characters that are recognized by LaTeX may also need editing (e.g., braces). The ‘`pdflatex`’ device, and any of the ‘`standalone`’ formats, are not available with the Gnuplot toolkit.

    `epscairo*`
    `pdfcairo*`
    `epscairolatex*`
    `pdfcairolatex*`
    `epscairolatexstandalone*`
    `pdfcairolatexstandalone*`

      Generate output with Cairo renderer. The devices ‘`epscairo`’ and ‘`pdfcairo`’ are synonymous with the ‘`epsc`’ device. The LaTeX variants generate a LaTeX file, `filename.tex`, for the text portions of a plot, and an image file, `filename.(eps|pdf)`, for the graph portion of the plot. The ‘`standalone`’ variants behave as described for ‘`epslatexstandalone`’ above.

    `svg`

      Scalable Vector Graphics

    `canvas*`

      Javascript-based drawing on an HTML5 canvas viewable in a web browser.

    `cdr*`
    `corel*`

      CorelDraw

    `cgm*`

      Computer Graphics Metafile, Version 1, ANSI X3.122-1986

    `dxf`

      AutoCAD

    `emf`
    `meta`

      Microsoft Enhanced Metafile

    `fig`

      XFig. For the Gnuplot graphics toolkit, the additional options `-textspecial` or `-textnormal` can be used to control whether the special flag should be set for the text in the figure. (default is `-textnormal`)

    `hpgl`

      HP plotter language

    `ill`
    `aifm`

      Adobe Illustrator (obsolete for Gnuplot versions > 4.2)

    `latex*`
    `eepic*`

      LaTeX picture environment and extended picture environment.

    `mf*`

      Metafont

    `tikz`
    `tikzstandalone*`

      Generate a LaTeX file using PGF/TikZ format. The OpenGL-based toolkits create a PGF file while Gnuplot creates a TikZ file. The ‘`tikzstandalone`’ device produces a LaTeX document which includes the TikZ file.

    Raster Formats

    `png`

      Portable Network Graphics

    `jpg`
    `jpeg`

      JPEG image

    `tif`
    `tiff`
    `tiffn`

      TIFF image with LZW compression (tif, tiff) or uncompressed (tiffn).

    `gif`

      GIF image

    `pbm`

      PBMplus

    `dumb*`

      ASCII art

    If the device is omitted, it is inferred from the file extension, or if there is no filename then it is sent to the printer as PostScript.

  `-dghostscript_device`

    Additional devices are supported by Ghostscript. Some examples are:

    `ljet2p`

      HP LaserJet IIP

    `pcx24b`

      24-bit color PCX file format

    `ppm`

      Portable Pixel Map file format

    For a complete list of available formats and devices type `system ("gs -h")`.

    When Ghostscript output is sent to a printer the size is determined by the figure’s `"papersize"` property. When the output is sent to a file the size is determined by the plot box defined by the figure’s `"paperposition"` property.

  `-Gghostscript_command`

    Specify the command for calling Ghostscript. For Unix the default is `"gs"` and for Windows it is `"gswin32c"`.

  `-TextAlphaBits=n`
  `-GraphicsAlphaBits=n`

    Octave is able to produce output for various printers, bitmaps, and vector formats by using Ghostscript. For bitmap and printer output anti-aliasing is applied using Ghostscript’s TextAlphaBits and GraphicsAlphaBits options. The default number of bits are 4 and 1 respectively. Allowed values for N are 1, 2, or 4.

  See also: saveas, hgsave, getframe, orient, figure.

saveas (h, filename)
saveas (h, filename, fmt)

  Save graphic object h to the file filename in graphic format fmt.

  All device formats accepted by `print` may be used. Common formats are:

  `ps`

    PostScript

  `eps`

    Encapsulated PostScript

  `pdf`

    Portable Document Format

  `jpg`

    JPEG Image

  `png`

    Portable Network Graphics image

  `emf`

    Enhanced MetaFile

  `tif`

    TIFF Image, compressed

  If fmt is omitted it is extracted from the extension of filename. The default format when there is no extension is `"pdf"`.

      clf ();
      surf (peaks);
      saveas (1, "figure1.png");

  See also: print, hgsave, orient.

orient (orientation)
orient (hfig, orientation)
orientation = orient ()
orientation = orient (hfig)

  Query or set the print orientation for figure hfig.

  Valid values for orientation are `"portrait"`, `"landscape"`, and `"tall"`.

  The `"landscape"` option changes the orientation so the plot width is larger than the plot height. The `"paperposition"` is also modified so that the plot fills the page, while leaving a 0.25 inch border.

  The `"tall"` option sets the orientation to `"portrait"` and fills the page with the plot, while leaving a 0.25 inch border.

  The `"portrait"` option (default) changes the orientation so the plot height is larger than the plot width. It also restores the default `"paperposition"` property.

  When called with no arguments, return the current print orientation.

  If the argument hfig is omitted, then operate on the current figure returned by `gcf`.

  See also: print, saveas.

`print` and `saveas` are used when work on a plot has finished and the output must be in a publication-ready format. During intermediate stages it is often better to save the graphics object and all of its associated information so that changes—to colors, axis limits, marker styles, etc.—can be made easily from within Octave. The `hgsave`/`hgload` commands can be used to save and re-create a graphics object.

hgsave (filename)
hgsave (h, filename)
hgsave (h, filename, fmt)

  Save the graphics handle(s) h to the file filename in the format fmt.

  If unspecified, h is the current figure as returned by `gcf`.

  When filename does not have an extension the default filename extension `.ofig` will be appended.

  If present, fmt must be one of the following:

  - `-binary`, `-float-binary`
  - `-hdf5`, `-float-hdf5`
  - `-V7`, `-v7`, `-7`, `-mat7-binary`
  - `-V6`, `-v6`, `-6`, `-mat6-binary`
  - `-text`
  - `-zip`, `-z`

  The default format is `-binary` to minimize storage.

  Programming Note: When producing graphics for final publication use `print` or `saveas`. When it is important to be able to continue to edit a figure as an Octave object, use `hgsave`/`hgload`.

  See also: hgload, hdl2struct, savefig, saveas, print.

h = hgload (filename)
[h, old_prop] = hgload (filename, prop_struct)

  Load the graphics objects in filename into a vector of graphics handles h.

  If filename has no extension, Octave will try to find the file with and without the default extension `.ofig`.

  If provided, the elements of structure prop_struct will be used to override the properties of top-level objects stored in filename, and the saved values from filename will be stored in old_prop. old_prop is a cell array matching the size of h; each cell contains a structure of the existing property names and values before being overridden.

  See also: openfig, hgsave, struct2hdl.

openfig
openfig (filename)
openfig (…, copies)
openfig (…, visibility)
h = openfig (…)

  Read saved figure window(s) from filename and return graphics handle(s) h.

  By default, filename is `"Untitled.fig"`. If a full path is not specified, the file opened will be the first one encountered in the load path. If filename is not found and does not have an extension, a search will take place for the first file in the load path with extension `".fig"` or `".ofig"`, in that order.

  copies is an optional input indicating whether a new figure should be created (`"new"`) or whether an existing figure may be reused (`"reuse"`). An existing figure may be reused if the `"FileName"` property matches the specified input filename. When a figure is reused it becomes the active figure and is shown on top of other figures. If the figure was offscreen, it is re-positioned to be onscreen. The default value for copies is `"new"`.

  visibility is an optional input indicating whether to show the figure (`"visible"`) or not (`"invisible"`). When visibility is specified as an input to `openfig` it overrides the visibility setting stored in filename.

  See also: open, hgload, savefig, struct2hdl.

savefig ()
savefig (h)
savefig (filename)
savefig (h, filename)
savefig (h, filename, `"compact"`)

  Save figure windows specified by graphics handle(s) h to file filename.

  If unspecified, h is the current figure returned by `gcf`.

  If unspecified, filename is set to `"Untitled.fig"`. If filename does not have an extension then the default extension `".fig"` will be added.

  If the optional third input `"compact"` is present then the data will be compressed to save more space.

  See also: hgsave, hdl2struct, openfig.