1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
|
=encoding UTF-8
=head1 NAME
Chart::Manual::Methods - user API
=head1 OVERVIEW
This are all methods for the chart user.
=head1 ALPHABETICALLY
=head2 add_datafile
Loads all data of a chart (one or more data sets) from a file.
(Works only if no data yet added.) You have to either provide a filename
or filehandle (OLD_SCHOOL or $scalar).
$graph->add_dataset( 'file.tsv' );
$graph->add_dataset( $file_handle );
$graph->add_dataset( FILE_HANDLE );
An optional second argument, which defaults to C<'set'> can change the
file format if set to C<'pt'>. In C<'set'> mode every row of the
file content is fed to L</add_dataset>, in C<'pt'> every row get loaded
like via L</add_pt>. In other words: C<'pt'> transposes the data table.
$graph->add_dataset( 'file.tsv', 'pt' );
The arbitrary named text files have to contain one or several rows of numbers.
The numbers need to be separated by spaces or tabs (\t) (mixing allowed).
Perl style comments or empty lines will be ignored, but rows containing
different amount of numbers will cause problems.
=head2 add_dataset
Adding a list of values as one data set. That is one row in the overall
data table. The first data set are usually x-axis labels (domain set).
Make sure all sets have the same length.
$graph->add_dataset( 1, 2, 3, ... );
$graph->add_dataset( [1, 2, 3, ...] );
For instances with L<Points|Chart::Manual::Types/Points>,
L<Lines|Chart::Manual::Types/Lines> or
L<Bars|Chart::Manual::Types/Bars> one data set is represented by a set
of graphic items (points, bars or line) of one color.
=head2 add_pt
Adds (appends) to each already existing data set one value. That is
a column in the overall data table. In this example it adds to set 0
the value 3, to set 1 the 6 and so forth. Make sure that the list lengths
matches the number of already existing data sets.
$graph->add_pt( 3, 6, 9, ... );
$graph->add_pt( [3, 6, 9, ...] );
=head2 cgi_jpeg
Creates same JPEG image as L</jpeg>, but outputs to STDOUT. Since no file
name or handle needed, only the optional data argument is acceptable.
$graph->cgi_jpeg( );
my @data = ([1, 2, 3], # data set 0
[3, 4, 5]); # data set 1
$graph->cgi_jpeg( \@data );
=head2 cgi_png
Creates same PNG image as L</png>, but outputs to STDOUT. Since no file
name or handle needed, only the optional data argument is acceptable.
$graph->cgi_png( );
my $data = [[1, 2, 3], # data set 0
[3, 4, 5] ]; # data set 1
$graph->cgi_png( $data );
=head2 clear_data
Needs no arguments and deletes all so far added data.
=head2 get_data
Return all data (array of arrays) given to a graph.
=head2 imagemap_dump
When creating a chart for web purposes by L</cgi_jpeg> or L</cgi_png>,
you maybe want the information, where the areas of interests in the
image are located, that should react to a users click. (HTML tag map).
These areas are bounding boxes around the drawn bars or points.
You will get per box the values: x1, y1, x2, y2 in one array.
These arrays are again in an Array holding, all boxes from one data set.
The highest level array again holds all arrays of all data sets,
beginning with index C<1>.
This method can only be called, if the functionality is activated by
setting the property: L<imagemap|Chart::Manual::Properties/imagemap> to C<'true'>.
$graph->set( imagemap => 'true');
my $image_map = $graph->imagemap_dump();
say "coordinates of first bar, first data set:";
say for @{$image_map->[1][0]};
=head2 jpeg
Creates an JPEG image from given data and properties. Accepts a file name
or a file handle (raw or in a SCALAR). The method closes the file handle.
$graph->jpeg( 'image.jpg' );
$graph->jpeg( $file_handle );
$graph->jpeg( FILE_HANDLE );
$graph->jpeg( 'image.jpg', $data );
$graph->jpeg( 'image.jpg', 'data_file.tsv' );
$graph->jpeg( 'image.jpg', $file_handle );
$graph->jpeg( 'image.jpg', FILE_HANDLE );
The second, optional argument is the data in form of an array of arrays
reference. This only works, if there is no data already given to the object.
Alternatively the data can also be loaded from a file, just provide
the filename or filehandle (modern in SCALAR or old school).
Read more about the file format at L</add_datafile> and note that
this method has another option for loading transposed data tables.
=head2 new
Creates a new chart object. Takes two optional arguments,
which are the width and height of the to be produced image in pixels.
Defaults for that are 400 x 300.
my $graph = Chart::Bars->new ( );
my $graph = Chart::Bars->new (600, 700);
Instead of Bars, you can also use: Composite, Direction, ErrorBars,
HorizontalBars, Lines, LinesPoints, Mountain, Pareto, Pie, Points, Split
and StackedBars. To know more about them read L<Chart::Manual::Types>.
=head2 png
Creates an PNG image from given data and properties. Accepts a file name
or a file handle (raw or in a SCALAR). The method closes the file handle.
$graph->png( 'image.png' );
$graph->png( $file_handle );
$graph->png( FILE_HANDLE );
$graph->png( 'image.png', $data );
$graph->png( 'image.png', 'data_file.tsv' );
$graph->png( 'image.png', $file_handle );
$graph->png( 'image.png', FILE_HANDLE );
The second, optional argument is the data in form of an array of arrays
reference. This only works, if there is no data already given to the object.
Alternatively the data can also be loaded from a file, just provide
the filename or filehandle (modern in SCALAR or old school).
Read more about the file format at L</add_datafile> and note that
this method has another option for loading transposed data tables.
=head2 scalar_jpeg
Creates same JPEG image as L</jpeg> but returns the image binary into a
variable, not to STDOUT or a file.
my $image_binary = $graph->scalar_jpeg();
my $image_binary = $graph->scalar_jpeg( $data );
=head2 scalar_png
Creates same PNG image as L</png> but returns the image binary into a
variable, not to STDOUT or a file.
my $image_binary = $graph->scalar_png();
my $image_binary = $graph->scalar_png( $data );
=head2 set
Method to change one or more chart properties in hash form.
$chart->set ( property_name => 'new value', ... );
$chart->set ( %properties );
Different chart types react to different properties, which are all listed
and explained under L<Chart::Manual::Properties>.
=head1 COPYRIGHT & LICENSE
Copyright 2022 Herbert Breunung.
This program is free software; you can redistribute it and/or modify it
under same terms as Perl itself.
=head1 AUTHOR
Herbert Breunung, <lichtkind@cpan.org>
=cut
|
