Class "Picture"

Description

A collection of paths (polylines or polygons) that together describe a picture.

Objects from the Class

Objects can be created by calls of the form new("Picture", ...). ~~ describe objects here ~~

Slots

paths:

A list of objects of class "PictureStroke" (polylines) or "PictureFill" (polygons).

summary:

Object of class "PictureSummary"

Methods

[

signature(x = "Picture"): subset the paths of a picture to produce a new picture (includeing a new, updated summary).

[[

signature(x = "Picture"): extract either a single path or, more usefully, the sub-paths of a "PictureText" object, to produce a new picture (includeing a new, updated summary).

grobify

signature(object = "Picture"): convert a picture into a grid grob (for use as a one-off image).

symbolize

signature(object = "Picture"): convert a picture into a grid grob (for use as a plotting symbol).

Author(s)

Paul Murrell

See Also

readPicture, grid.picture, grid.symbols and PictureStroke-class PictureFill-class PictureSummary-class.

Class "PictureChar"

Description

A description of a polygon path that describes the outline of a character (and might be part of a larger picture).

Slots

x:

Object of class "numeric"

y:

Object of class "numeric"

rgb:

Object of class "character" that specifies the fill colour for the polygon.

lwd:

Object of class "numeric" that specifies the line width of the polygon (only used if the character outline is stroked).

char:

Object of class "character" that specifies the character that this path represents.

Extends

Class "PictureOp", directly.

Methods

grobify

signature(object = "PictureChar"): convert to a grid grob (for one-off drawing). Use argument fillText to fill the text rather than just stroke the outline. In that case, the first path for this character is filled in the appropriate colour and all subsequent paths are filled using a colour controlled by the bgText argument (default is white).

symbolize

signature(object = "PictureChar"): convert to a grid grob (for drawing as a data symbol). Currently draws nothing.

drawPath

signature(object = "PictureChar"): draws a traced character path as part of the current plot.

Author(s)

Paul Murrell

See Also

Picture-class, PictureStroke-class, and grid.picture, grid.symbols.

Class "PictureFill"

Description

A description of a polygon path (that might be part of a larger picture).

Slots

x:

Object of class "numeric"

y:

Object of class "numeric"

rgb:

Object of class "character" that specifies the fill colour for the polygon.

lwd:

Object of class "numeric" that specifies the line width of the polygon (not typically used because the polygon is meant to be filled not stroked).

rule:

Object of class "character" with the value evenodd or nonzero indicating the fill rule for the path.

Extends

Class "PictureOp", directly.

Methods

grobify

signature(object = "PictureFill"): convert to a grid grob (for one-off drawing). There is a logical argument use.gc which can be used to turn off the graphics context coming from the object so that a different one can be specified via the gp argument.

symbolize

signature(object = "PictureFill"): convert to a grid grob (for drawing as a data symbol).

drawPath

signature(object = "PictureFill"): draws a traced polygonx as part of the current plot.

Author(s)

Paul Murrell

See Also

Picture-class, PictureStroke-class, and grid.picture, grid.symbols.

Class "PictureOp"

Description

A virtual class from which "PictureStroke" and "PictureFill" are derived.

Slots

x:

Object of class "numeric"

y:

Object of class "numeric"

rgb:

Object of class "character" giving colour information for the path.

lty:

Object of class "numeric" giving line type information for the path.

lwd:

Object of class "numeric" giving line width information for the path.

lineend:

Object of class "numeric" giving the type of line end style (round, butt, square).

linejoin:

Object of class "numeric" giving the type of line join style (round, mitre, bevel).

linemitre:

Object of class "numeric" giving the line mitre limit (as a number greater than 1).

Author(s)

Paul Murrell

See Also

PictureStroke-class and PictureFill-class.

Class "PictureStroke"

Description

A polyline path (that might be part of a larger picture).

Slots

x:

Object of class "numeric"

y:

Object of class "numeric"

rgb:

Object of class "character" giving the colour of the polyline.

lwd:

Object of class "numeric" giving the width of the polyine.

Extends

Class "PictureOp", directly.

Methods

grobify

signature(object = "PictureStroke"): convert into a grid grob (for one-off drawing). There is a logical argument use.gc which can be used to turn off the graphics context coming from the object so that a different one can be specified via the gp argument.

symbolize

signature(object = "PictureStroke"): convert into a grid grob (for drawing as a data symbol)).

drawPath

signature(object = "PictureStroke"): draws a traced line as part of the current plot.

Author(s)

Paul Murrell

See Also

Picture-class, PictureFill-class, and grid.picture, grid.symbols.

Class "PictureSummary"

Description

Summary information about a picture such as the number of paths and bounding box information.

Slots

numPaths:

Object of class "numeric"

xscale:

Object of class "numeric" range of x-values in picture.

yscale:

Object of class "numeric" range of y-values in picture.

Author(s)

Paul Murrell

See Also

Picture-class

Class "PictureText"

Description

A description of a piece of text to draw, at a particular location and a particular size (and it might be part of a larger picture).

Slots

string:

Object of class "character"

x:

Object of class "numeric"

y:

Object of class "numeric"

w:

Object of class "numeric"

angle:

Object of class "numeric"

rgb:

Object of class "character" that specifies the fill colour for the polygon.

lwd:

Object of class "numeric" that specifies the line width of the polygon (only used if the character outline is stroked).

Extends

Class "PictureOp", directly.

Methods

grobify

signature(object = "PictureText"): convert to a grid grob (for one-off drawing). In addition to a use.gc argument, there is a fillText argument to specify whether to stroke or fill text paths. Filling text paths is not necessarily a good idea because some characters have holes (e.g., the letter ‘o’). The bgText argument can be used to specify a colour to use to fill these holes; this argument can actually be a named vector of colours so that, e.g., the hole in an ‘o’ is filled white, but the dot on an ‘i’ is filled black. Finally, there is a sizeByWidth argument which controls whether text is sized based on the traced width or based on the traced height of the original text.

symbolize

signature(object = "PictureText"): convert to a grid grob (for drawing as a data symbol). Currently draws nothing.

drawPath

signature(object = "PictureText"): draws a traced piece of text as part of the current plot.

Author(s)

Paul Murrell

See Also

Picture-class, PictureChar-class, and grid.picture, grid.symbols.

Convert PostScript file to RGML file

Description

Converts a PostScript file into an RGML file, which is an XML document describing an image that can be read into R.

Usage

PostScriptTrace(file, outfilename,
                       charpath=TRUE, charpos=FALSE,
                       setflat=NULL, defaultcol="black",
                       encoding="ISO-8859-1", scaleEPS=.01)

Arguments

Details

This function calls ghostscript to do the conversion, so will only work if ghostscript is installed on your system.

If text is converted to outlines, it can be drawn as outlines, or filled using a crude algorithm which may or may not work (see grid.picture). On the other hand, if text is left as just text, font information is not stored so the text may not end up looking much like the original.

Ghostscript is only going to emit text in a single-byte encoding, so the RGML file should have an explicit encoding (otherwise XML parsers are likely to assume UTF-8 and barf on any non-ASCII text). The default encoding used is ISO-8859-1 (ISOLatin1), but you can specify another if you know that the source file has text that ghostscript will emit in a different encoding. There may have to be a bit of guesswork, or inspection of the source PostScript file.

References

https://www.ghostscript.com/

Draw a Picture Object

Description

This is a generic function that does the hard work for picture when drawing paths of a "Picture" object as part of the current plot.

Usage

drawPath(p, trans, ...)

Arguments

Author(s)

Paul Murrell

See Also

picture and grid.picture

Explode Complex Picture Paths

Description

This function converts complex paths within a "Picture" object (paths that contain more than one move operation) into multiple simple paths (paths with only one move operation).

Usage

explodePaths(picture)

Arguments

Value

A "Picture" object.

Author(s)

Paul Murrell

See Also

grid.picture

Draw a Picture Object

Description

These function take a "Picture" object and either draw the picture or create a grid graphical object representing the picture.

Usage

grid.picture(...)
pictureGrob(picture, x = 0.5, y = 0.5,
            width = 1, height = 1, just = "centre",
            exp = 0.05, xscale = NULL, yscale = NULL,
            distort = FALSE,
            FUN = grobify, ..., name = NULL, gp = gpar())

Arguments

Value

A grid gTree.

Author(s)

Paul Murrell

See Also

grobify and grid.symbols

Draw a Picture Object

Description

These function take a "Picture" object and either draw the picture at several locations or create a grid graphical object representing the picture (drawn at several locations).

Usage

grid.symbols(...)
symbolsGrob(picture, x = unit(0.5, "npc"), y = unit(0.5, "npc"),
            size = unit(1, "npc"), units = "npc", ...,
            name = NULL, gp = gpar())

Arguments

Value

A grid gTree.

Author(s)

Paul Murrell

See Also

symbolize and grid.picture

Convert a Picture into a Grid Grob

Description

Converts an entire "Picture" object, or a path element thereof, into an appropriate grid grob. Not usually called directly by the user; usually called by grid.picture.

Usage

grobify(object, ...)

oldGrobify(object, ...)

Arguments

Value

A grid gTree (when given a whole "Picture") or an appropriate grid grob (when given a single picture path).

Author(s)

Paul Murrell

See Also

grid.picture and symbolize

Draw a Picture Object

Description

This function take a "Picture" object and draw it in the current plot region.

Usage

picture(picture, xleft, ybottom, xright, ytop, ...)

Arguments

Details

The positions supplied, i.e., xleft, ..., are relative to the current plotting region. If the x-axis goes from 100 to 200 then xleft should be larger than 100 and xright should be less than 200.

Author(s)

Paul Murrell

See Also

readPicture and grid.picture

Draw Individual Picture Paths

Description

This function individually draws each path from a "Picture" object.

Usage

picturePaths(picture, nr, nc,
             col = "black",
             fill = "light grey",
             freeScales = FALSE,
             xscale = NULL, yscale = NULL,
             label = function(n) {
               tg <- textGrob(n, x = 0, y = 0,
                              just = c("left", "bottom"),
                              gp = gpar(fontsize = 6))
               grid.rect(x = 0, y = 0,
                         height = unit(6, "points"),
                         width = grobWidth(tg),
                         just = c("left", "bottom"),
                         gp = gpar(fill = "white"))
               grid.draw(tg)
             }, use.gc = TRUE)

Arguments

Author(s)

Paul Murrell

See Also

grid.picture

Import an RGML file

Description

This function reads in an RGML file (produced by PostScriptTrace) and creates a "Picture" object.

Usage

readPicture(rgmlFile, tidy = TRUE, ...)

Arguments

Value

An object of class "Picture".

Author(s)

Paul Murrell

See Also

PostScriptTrace

Convert a Picture into a Grid Grob

Description

Converts an entire "Picture" object, or a path element thereof, into an appropriate grid grob. Not usually called directly by the user; usually called by grid.picture.

Usage

symbolize(object, x = unit(0.5, "npc"), y = unit(0.5, "npc"),
          size = unit(1, "npc"), units = "npc", ...)

Arguments

Value

A grid gTree (when given a whole "Picture") or a "symbolFill" or "symbolStroke" object (when given a single picture path).

Author(s)

Paul Murrell

See Also

grid.picture and symbolize