grid.export: Generate SVG output from a grid graphic

In gridSVG: Export 'grid' Graphics as SVG

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

See Also

grid.hyperlink, grid.animate, grid.garnish

gridSVG documentation built on March 31, 2023, 11:17 p.m.