NAME

    Graphics::Grid - An incomplete port of the R "grid" library to Perl

VERSION

    version 0.0000_02

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'));

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
      relative to those of the parent viewport. So when defining a grob,
      for example a rectangle, usually you do not specify its (x, y)
      position or width or height in absolute values, instead you specify
      its relative position, and width and height in ratio to the viewport
      on which the rectangle is drawn. 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 except for
    the grid-layout system.

    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.

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

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

    Graphics::Grid::Functions

    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 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.

