R: Generate SVG output from a grid graphic

grid.export {gridSVG}

R Documentation

Generate SVG output from a grid graphic

Description

Produces an SVG version of the current grid page.

Usage

grid.export(name = "Rplots.svg",
            exportCoords = c("none", "inline", "file"),
            exportMappings = c("none", "inline", "file"),
            exportJS = c("none", "inline", "file"),
            res = NULL,
            prefix = "",
            addClasses = FALSE,
            indent = TRUE,
            htmlWrapper = FALSE,
            usePaths = c("vpPaths", "gPaths", "none", "both"),
            uniqueNames = TRUE,
            annotate = TRUE,
            progress = FALSE,
            compression = 0,
            strict = TRUE,
            rootAttrs = NULL,
            xmldecl = xmlDecl())

Arguments

`name`	The name of the SVG file to produce. If this parameter is `NULL` or `""`, a list containing the SVG document, coordinate information, and JavaScript utility functions are returned.
`exportCoords`	If this parameter is not `none` a coordinates file is exported. If this parameter is `file`, the coordinates information is written to a file, while `inline` will include the contents within the SVG document.
`exportMappings`	If this parameter is not `none` a mapping file is exported. If this parameter is `file`, the mapping information is written to a file, while `inline` will include the contents within the SVG document.
`exportJS`	If this parameter is not `none` a JavaScript file is written out. This contains useful functions for manipulating gridSVG plots in the browser, including unit conversion functions. If this parameter is `file`, the JavaScript file is written to a file, while `inline` will include the contents within the SVG document.
`res`	The device resolution to print at (in DPI). If `NULL`, this is automatically calculated to be the resolution of the current device. Typically the PDF device would be used, and this uses a resolution of 72, i.e. 72 DPI.
`prefix`	A prefix to apply to all generated SVG ID attributes. Useful for ensuring unique IDs when many SVG images exist within the same HTML document. If a valid prefix has been given, the root `<svg>` element will be given an ID attribute with the prefix as its value.
`addClasses`	If `TRUE`, adds an SVG class attribute to all grobs and viewports which holds the value of the class of the grob or viewport. If the class attribute already exists (via `grid.garnish` or `grid.element`), the resulting SVG class attribute will be the union of the existing class attribute and the grob/viewport classes.
`indent`	Determines whether the resulting SVG document will be exported with indentation present. Indentation makes the document more readable, but when `indent` is set to `FALSE`, parsing the SVG in JavaScript is easier because there are no empty text nodes.
`htmlWrapper`	If `TRUE`, saves a wrapping HTML file. This file contains a snippet of HTML which links to the exported SVG file.
`usePaths`	If this parameter is set to `vpPaths`, then when writing out viewports gridSVG will set the SVG element ID to the current `vpPath` instead of the current viewport name. If this parameter is set to `gPaths`, gridSVG will set the names of grobs to be the current `gPath` instead of the current grob name. When `none`, viewports and grobs will not incorporate paths. When `both`, viewports and grobs will both use paths.
`uniqueNames`	If `TRUE`, gridSVG will make an attempt to produce unique grob names. Unique `id` attributes are required for valid SVG. It is highly recommended that mapping information is used when this parameter is `TRUE`.
`annotate`	If `TRUE`, an SVG metadata element will be introduced directly below the root `<svg>` element. This element contains XML that describes the information that gridSVG used to draw the image (mostly arguments to `grid.export`). This output may be useful for debugging purposes.
`progress`	If `TRUE`, messages will be displayed in the console that show how quickly gridSVG is progressing when exporting an SVG image. This is particularly useful when there are large images being exported so we have a reasonable estimate of how long exporting will take.
`compression`	An integer between 0 and 9 indicating the level of (gzip) compression applied to the SVG image when it is saved to a file. Higher values of `compression` indicate smaller file sizes at the expense of increased computation.
`strict`	A logical indicating whether checks should be made that all attributes added to SVG elements are valid. If this is `TRUE` and invalid attributes are detected, those attributes are removed, with a warning.
`rootAttrs`	A named character vector containing attributes for the top-level `<svg>` element.
`xmldecl`	This parameter sets the XML declaraction that will be applied to the SVG document. By default this parameter simply declares that the document is XML version 1.0, along with the character encoding that was used to export the SVG document. If `xmldecl` is `NULL`, then no XML declaration is printed. This may be useful when you want only the SVG document and nothing more.

Details

The uniqueNames parameter is set to TRUE by default in order to ensure that each SVG element ID is unique. This is a requirement of XML (which SVG is based on). This differs from usePaths because usePaths can still generate names that are not unique (there are several ways for this to happen). uniqueNames modifies grob and viewport names with a numeric suffix to ensure uniqueness. When FALSE, only grob names will be kept unmodified because modifying viewport names would affect coordinate information.

Occasionally the XML package can report warnings, despite valid SVG being produced. If spurious warnings are being produced, set options(gridSVGWarnings = FALSE) to ignore them.

See the files in the directory gridSVG/tests for examples of things that can be done. See the file gridSVG/doc/overview.tex for limitations.

Value

When name has a valid filename the side effect is to produce an SVG file of the specified name.

Optionally a JavaScript file containing coordinate transformation information is also exported.

Optionally a JavaScript file containing name mapping information is also exported.

Optionally a JavaScript file containing utility JavaScript functions is also exported.

When name has a filename with zero characters, a named list is returned with four elements. svg is the SVG root node (and all its children, see the XML package for more information on how to use this. coords contains the list of coordinate information for exported viewports. mappings is a list containing information on how names have been modified during the exporting process. utils is a character vector containing JavaScript code to manipulate gridSVG plots in the browser.

This list is always returned but when a valid filename is given, it is returned invisibly.

Author(s)

Paul Murrell