NAME
Graphics::Grid - An incomplete port of the R "grid" library to Perl
VERSION
version 0.001
SYNOPSIS
use Graphics::Grid;
use Graphics::Grid::GPar;
use Graphics::Grid::Viewport;
my $grid = Graphics::Grid->new();
$grid->push_viewport(
Graphics::Grid::Viewport->new(width => 0.5, height => 0.5));
$grid->rect(gp => Graphics::Grid::GPar->new(col => 'blue'));
$grid->write("foo.png");DESCRIPTION
This is alpha code. Before version 1.0 of this library, its API would change without any notice.
This library is an incomplete port of Paul Murrell's R "grid" library. The R "grid" library is a low level graphics system that provides full access to the graphics facilities in R. It's used by some other R plotting libraries including the famous "ggplot2".
With my (immature maybe) understanding the fundamental designs and features of the R "grid" library can be summarized as following:
It supports a few graphical primitives (called "grob") like lines, rectangles, circles, text, etc. And they can be configured via a set of graphical parameters (called "gpar"), like colors, line weights and types, fonts, etc. And, it also has a tree structure called "gTree" which allows arranging the grobs in a hierachical way.
It designs something called "viewport" which is basically an arbitrary rectangular region which defines the transform (position, coordinate scale, rotation) on the graphics device. There is a global viewport stack (actually it's a tree). Viewports can be pushed onto, or popped from the stack, and drawing always takes place on the "top" or "current" viewport. Thus for drawing each graphical primitive it's possible to have a specific transform for the graphics device context. Combined with its ability to define graphical primitives as mention above, the "grid" library enables the full possibilities of customization which cannot be done with R's standard "plot" system.
It has a "unit" system. a "unit" is basically a numerical value plus a unit. The default unit is "npc" (Normalised Parent Coordinates), which describes an object's position or dimension either in relative to those of the parent viewport or be absolute. So when defining a grob, for example for a rectangle you can specify its (x, y) position or width or heightha relative to a viewport, although absolute values are also possible and you can combine relative and absolute values. Beause of this design, it's easy to adapt a plot to various types and sizes of graphics devices.
Similar to many stuffs in the R world, parameters to the R "grid" library are vectorized. This means a single rectangular "grob" object can actually contain information for multiple rectangles.
It has a grid-based layout system. That's probably why the library got the name "grid".
The target of this Perl Graphics::Grid library, as of today, is to have most of the R "grid"'s fundamental features mentioned above.
This Graphics::Grid module is the object interface of this libray. There is also a function interface Graphics::Grid::Functions, which is more like the interface of the R "grid" library.
ATTRIBUTES
driver
Set the device driver. The value needs to be a consumer of the Graphics::Grid::Driver role. Default is a Graphics::Grid::Driver::Cairo object.
CLASS METHODS
singleton()
METHODS
current_vptree($all=true)
If $all is a true value, it returns the whole viewport tree, whose root node contains the "ROOT" viewport. If $all is a false value, it returns the current viewport tree, whose root node contains the current viewport.
current_viewport()
Get the current viewport. It's same as,
$grid->current_vptree(0)->node;push_viewport(@viewports)
Push viewports onto the global viewport tree, and update the current viewport.
pop_viewport($n=1)
Remove $n levels of viewports from the global viewport tree, and update to current viewport to the remaining parent node of the removed part of tree nodes.
if $n is 0 then only the "ROOT" node of the global viewport tree would be retained and set to current.
up_viewport($n=1)
This is similar to the pop_viewport method except that it does not remove the tree nodes, but only updates the current viewport.
down_viewport($from_tree_node, $name)
Start from a tree node, and try to find the first child node whose name is $name. If found it sets the node to current, and returns the number of tree leves it went down. So it's possible to do something like,
my $depth = downViewport(...);
upViewport($depth).$name can also be an array ref of names which defines a "path". In this case the top-most node in the "path" is set to current.
seek_viewport($from_tree, $name)
This is similar to the down_viewport method except that this always starts from the "ROOT" node.
draw($grob)
Draw a grob (or gtree) on the graphics device.
${grob_type}(%params)
This creates a grob and draws it. For example, rect(%params) would create and draw a rectangular grob.
$grob_type can be one of following,
circle
lines
points
polygon
polyline
rect
segments
text
null
zero
write($filename)
Write to file.
TODOS
Including but not limited to,
Support canvas resize.
Support R pch symbols for points grob.
Cache things to speed up the drawing.
ACKNOWLEDGEMENT
Thanks to Paul Murrell and his great R "grid" library, from which this Perl library is ported.
SEE ALSO
The R grid package https://stat.ethz.ch/R-manual/R-devel/library/grid/html/grid-package.html
Examples in the examples directory of the package release.
An article that explains a few concepts in the R "grid" package http://ww2.amstat.org/publications/jse/v18n3/zhou.pdf
AUTHOR
Stephan Loyd <sloyd@cpan.org>
COPYRIGHT AND LICENSE
This software is copyright (c) 2018-2023 by Stephan Loyd.
This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.