view release on metacpan or  search on metacpan

README.plot  view on Meta::CPAN

NAME
    DBD::Chart::Plot - Graph/chart Plotting engine for DBD::Chart

SYNOPSIS
        use DBD::Chart::Plot; 
    
        my $img = DBD::Chart::Plot->new(); 
        my $anotherImg = DBD::Chart::Plot->new($image_width, $image_height); 
    
        $img->setPoints(\@xdataset, \@ydataset, 'blue line nopoints');
    
        $img->setOptions (
            horizMargin => 75,
            vertMargin => 100,
            title => 'My Graph Title',
            xAxisLabel => 'my X label',
            yAxisLabel => 'my Y label' );
    
        print $img->plot;

DESCRIPTION
    DBD::Chart::Plot creates images of various types of graphs for 2 or 3
    dimensional data. Unlike GD::Graph, the input data sets do not need to
    be uniformly distributed in the domain (X-axis), and may be either
    numeric, temporal, or symbolic.

    DBD::Chart::Plot supports the following:

    - multiple data set plots
    - line graphs, areagraphs, scatter graphs, linegraphs w/ points,
    candlestick graphs, barcharts (2-D, 3-D, and 3-axis), histograms,
    piecharts, box & whisker charts (aka boxcharts), and Gantt charts
    - optional iconic barcharts or datapoints
    - a wide selection of colors, and point shapes
    - optional horizontal and/or vertical gridlines
    - optional legend
    - auto-sizing of axes based in input dataset ranges
    - optional symbolic and temproal (i.e., non-numeric) domain values
    - automatic sorting of numeric and temporal input datasets to assure
    proper order of plotting
    - optional X, Y, and Z axis labels
    - optional X and/or Y logarithmic scaling
    - optional title
    - optional adjustment of horizontal and vertical margins
    - optional HTML or Perl imagemap generation
    - composite images from multiple graphs
    - user programmable colors
PREREQUISITES
    GD.pm module minimum version 1.26 (available on CPAN)
        GD.pm requires additional libraries:

    libgd
    libpng
    zlib
USAGE
  Create an image object: new()

            use DBD::Chart::Plot; 

            my $img = DBD::Chart::Plot->new; 
            my $img = DBD::Chart::Plot->new ( $image_width, $image_height ); 
            my $img = DBD::Chart::Plot->new ( $image_width, $image_height, \%colormap ); 
            my $anotherImg = new DBD::Chart::Plot; 

        Creates an empty image. If image size is not specified, the default
        is 400 x 300 pixels.

  Graph-wide options: setOptions()

            $img->setOptions (_title => 'My Graph Title',
                xAxisLabel => 'my X label',
                yAxisLabel => 'my Y label',
                xLog => 0,
                yLog => 0,
                horizMargin => $numHorPixels,
                vertMargin => $numvertPixels,
                horizGrid => 1,
                vertGrid => 1,
                showValues => 1,
                legend => \@plotnames,
                genMap => 'a_valid_HTML_anchor_name',
                mapURL => 'http://some.website.com/cgi-bin/cgi.pl',
                icon => [ 'redstar.png', 'bluestar.png' ]
                symDomain => 0
             );

        As many (or few) of the options may be specified as desired.

    width, height
        The width and height of the image in pixels. Default is 400 and 300,
        respectively.

    genMap, mapType, mapURL, mapScript
        Control generation of imagemaps. When genMap is set to a legal HTML
        anchor name, an image map of the specified type is created for the
        image. The default type is 'HTML' if no mapType is specified. Legal
        types are 'HTML' and 'PERL'.

        If mapType is 'PERL', then Perl script compatible text is generated
        representing an array ref of hashrefs containing the following
        attributes:

        plotnum => the plot number to which this hashref applies (to support
        multi-range graphs), starting at zero.

        x => the domain value for the plot element

        y => the range value for the plot element

        z => the Z axis value for 3-axis bar charts, if any

        shape => the shape of the hotspot area of the plot element, same as
        for HTML: 'RECT', 'CIRCLE', 'POLY'

        coordinates => an arrayref of the (x,y) pixel coordinates of the
        hotspot area to be mapped; for CIRCLE shape, its (x-center,
        y-center, radius), for RECT, its (upper-left corner x, upper-left
        corner y, lower-right corner x, lower-right corner y), and for POLY
        its the set of vertices (x,y)'s.

        If the mapType is 'HTML', then either the mapURL or mapScript (or
        both) can be specified. mapURL specifies a legal URL string, e.g.,
        'http://www.mysite.com/cgi-bin/plotproc.pl?plotnum=:PLOTNUM&X=:X&Y=:
        Y', which will be added to the AREA tags generated for each mapped
        plot element. mapScript specifies any legal HTML scripting tag,
        e.g., 'ONCLICK="alert('Got X=:X, Y=:Y')"' to be added to each
        generated AREA tag.

        For both mapURL and mapScript, special variables :PLOTNUM, :X, :Y,
        :Z can be specified which are replaced by the following values when
        the imagemap is generated.

        Refer to the IMAGEMAP description at
        www.presicient.com/dbdchart#imagemap for details.

    horizMargin, vertMargin
        Sets the number of pixels around the actual plot area.

    xAxisLabel, yAxisLabel, zAxisLabel
        Sets the label strings for each axis.

    xLog, yLog
        When set to a non-zero value, causes the associated axis to be
        rendered in log10 format. Z axis plots are currently only symbolic,
        so no zLog is supported.

    title
        Sets a title string to be rendered at the bottom center of the image
        in bold text.

    signature
        Sets a string to be rendered in tiny font at the lower right corner
        of the image, e.g., 'Copyright(C) 2001, Presicient Corp.'.

    legend
        Set to an array ref of domain names to be displayed in a legend for
        the various plots. The legend is displayed below the chart, left
        justified and placed above the chart title string. The legend for
        each plot is printed in the same color as the plot. If a point shape
        or icon has been specified for a plot, then the point shape is
        printed with the label; otherwise, a small line segment is printed
        with the label. Due to space limitations, the number of datasets
        plotted should be limited to 8 or less.

    showValues
        When set to a non-zero value, causes the data points for each
        plotted element to be displayed next to hte plot point.

    horizGrid, vertGrid
        Causes grid lines to be drawn completely across the plot area.

    xAxisVert
        When set to a non-zero value, causes the X axis tick labels to be
        rendered vertically.

    keepOrigin
        When set to a non-zero value, forces the (0,0) data point into the
        graph. Normally, DBD::Chart::Plot will heuristically clip away from
        the origin is the plot never crosses the origin.

    bgColor
        Sets the background color of the image. Default is white.

    threed
        When set to a non-zero value for barcharts, causes the bars to be
        rendered in a 3-D effect.

    icons
        Set to an arrayref of image filenames. The images will be used to
        plot iconic barcharts or individual plot points, if the 'icon' shape
        is specified in the property string supplied to the setPoints()
        function (defined below). The array must match 1-to-1 with the
        number of plots in the image; icons and predefined point shapes can
        be mixed in the same image by setting the icon arrayref entry to
        undef for plots using predefined shapes in the properties string.

    symDomain
        When set to a non-zero value, causes the domain to be treated as
        discrete symbolic values which are evenly distributed over the
        X-axis. Numeric domains are plotted as scaled values in the image.

    timeDomain
        When set to a valid format string, the domain data points are
        treated as associated temporal values (e.g., date, time, timestamp,
        interval). The values supplied by setPoints will be strings of the
        specified format (e.g., 'YYYY-MM-DD'), but will be converted to
        numeric time values for purposes of plotting, so the domain is
        treated as continuous numeric data, rather than discrete symbolic.
        Note that for barcharts, histograms, candlesticks, or piecharts,
        temporal domains are treated as symbolic for plotting purposes, but
        are sorted as numeric values.

    timeRange
        When set to a valid format string, the range data points are treated
        as associated temporal values (e.g., date, time, timestamp,
        interval). The values supplied by setPoints will be strings of the
        specified format (e.g., 'YYYY-MM-DD'), but will be converted to
        numeric time values for purposes of plotting, so the range is