Ĝan Ŭesli Starling > Chart-EPS_graph-0.01d > Chart::EPS_graph

Download:
Chart-EPS_graph-0.01d.tar.gz

Dependencies

Annotate this POD

View/Report Bugs
Module Version: 0.01   Source  

NAME ^

Chart::EPS_graph.pm

VERSION ^

Version 0.01

SYNOPSIS ^

        # Create anew a 600 x 600 points (not pixels!) EPS file
        my $eps = Chart::EPS_graph->new(600, 600);

        # Choose minimum required display info
        $eps->set(
                label_top => 'Graph Main Title',
                label_y1  => 'Y1 Axis Measure (Units)',
                label_y2  => 'Y2 Axis Measure (Units)',
                label_x   => 'X Axis Measure (Units)',
        );

        # Choose 6 of 13 named chans, 4 at left, 2 at right
        $eps->set(
                names => \@all_13_name_strings,
                data  => \@all_13_data_arefs,
                y1    => [7, 8, 10, 11],
                y2    => [9, 12],
        );


        # Choose  optional graph features
        $eps->set(
                label_y1_2 => 'Extra Y1 Axis Info',
                label_y2_2 => 'Extra Y2 Axis Info',
                label_x_2  => 'Extra X Axis Info',

                # Any common browser color no matter how hideous.
                bg_color   => 'DarkOliveGreen',
                fg_color   => 'HotPink',
                web_colors => ['Crimson', 'Lime', 'Indigo', 'Gold', 'Snow', 'Aqua'],

                # Any known I<PostScript> font no matter how illegible
                font_name  => 'ZapfChancery-MediumItalic',
                font_size  => 18,

                # See POD about this one. But in brief:
                # If set to "1" channel innumeration gaps will be closed.
                # If set to "0" (the default) they will be left as they are.
                close_gap  => 0,

                # If the 0th channel is not for the X axis (the default) then the
                # data point count is used as the X axis, which you may scale.
                # So if X were Time in seconds, with no 0th channel having acutally
                # recorded it, but each data point were known to be 0.5 seconds...
                $self->{x_is_zeroth} = 0;   # Boolean, so '1' or '0'.
                $self->{x_scale}     = 2;   # Have 10th datapoint show as 20, etc.
        );

        # Write output as EPS
        $eps->write_eps( cwd() . '/whatever.eps' ); # Write to a file.

        # View, convert or edit the EPS output
        $eps->display();       # Display in viewer (autodetects 'gv' or 'gsview.exe').
        $eps->display('GS');   # Convert to PNG via Ghostscript.
        $eps->display('GIMP'); # Open for editng in The GIMP.

DESCRIPTION ^

Creates line graphs in PostScript as *.eps format.

Viewing accomplished via calls to Ghostscript and/or to gv on unix and/or to GSView.exe on Win32.

Coversion to *.png accomplished via system calls to Ghostscript on Unix and/or to GSView.exe on Win32.

MAIN FEATURES ^

Dual Y Axes

You may have two Y axes, one each to left and right. The PostScript code will auto-reconcile a grid for optimum alignment between both of these Y axes. By optimum I mean that scales will be adjusted such that curves traverse the entirety of available Y-axis space.

143 Colors

You may use as many of the named colors from the W3C table at http://www.w3schools.com/html/html_colornames.asp as you like in any order that you like.

Display, Convert or edit EPS Graph

Asked to display an EPS graph, a 3rd party viewer (gv on UNIX, gsview.exe on Win32), coverter Ghostscript or editor The GIMP will be called up to display, convert or edit the EPS graph.

Channel Innumeration Gaps

These you may either close or leave open. For example, suppose you have ten channels total but only wish to graph five of them. And suppose those channels are staggerd thus: 1, 3, 5, 6, 9. Closing the innumeration gap would make those channels appear on the graph as if they were numbered 1, 2, 3, 4, 5. They would also display in the first five colors, those which are most appealing and afford the best contrast.

Closing the innumeration gap makes a stand-alone graph easier to read. Should you, however, have more than one graph, with different channel sets on each, then it is a bad idea. Better in such a case that each color be true to a channel than easier upon the eye.

Closing the gap will also reduce file size considerably, as detailed next.

When you call $foo->set{close_gap => 0};

Data arrays for all channels, even those not to be shown, will be embeded into the PostScript output file. Traces which are shown will display their true channel numbers and be colorized in accordance with that true number.

Say, for instance, you are only showing Channel 12. It will be labeled as trace number 12 and display in the 12th color. This makes a lot of sense when you have a dozen graphs layed out on a table for none-too-bright customers to argue over.

Why do this? The PostScript program was originally written to run stand- alone. This feature makes it easy to have one file and, with a minor hand edit, generate any number of subsets for all all possible graphs by simply editing the /not_shown array.

When you call $foo->set{close_gap => 1};

Data arrays for only those channels assigned to a Y axis will be embeded into the PostScript output file. Traces which are shown will display new channel numbers (1 thru N) without any gaps and be colorized in accordance with that new number.

SUBROUTINES/METHODS ^

These are pretty much fully covered in the synopsis.

DIAGNOSTICS ^

A separate test module exists to fully test this one. See POD at head of that module for full details. But in short, you may call the full test on a single line, or broken over two, as below...

        perl -e "use Chart::EPS_graph::Test; \ 
        Chart::EPS_graph::Test->full_test('/some/dir');"

...and thereby obtain a multi-step report as below...

        Testing Chart::EPS_graph.pm in path '/some/dir/'
        Okay! File 'foo.eps' has expected first two lines.
        Okay! File 'foo.eps' looks fresh: 0 seconds old.
        Okay! File 'foo.eps' looks big enough, 28319 bytes.
        Okay! Ghostscript created 'foo.eps.png'.
        Okay! File 'foo.eps.png' looks fresh: 1 seconds old.
        Okay! File 'foo.eps.png' looks big enough, 105828 bytes.
        Glad Tidings! All tests okay for Chart::EPS_graph.

Had there been a problem of any kind, one or more of the above lines would have begun as Oops! followed by a few terse details.

You can also inspect the example files personally via The GIMP or ImageMagick as you choose. You can, that is, unless it was the CPAN build proccess which made the call; in which case those files will have been deleted immediately after each was measured.

CONFIGURATION AND ENVIRONMENT ^

This module requires no configuration. It auto-searches for its dependencies by calling to File::Find.

My goal, as always, is OS-independence, but only have recources to design and test on these two platforms only:

NetBSD 2.0.2 running Perl 5.8.7

Which I am happy to run on my P4 tower and both of my laptops at home.

WinXP SP2 running ActiveState Perl 5.8.0.

Which I am saddled with having to suffer the use of at work.

DEPENDENCIES ^

Because output is to PostScript most users will want to convert the output to some other graphics format. Built-in methods for converting to *.png are provided. The method of choice, of course, is Ghostscript.

Ghostscript

The Ghostscript interpreter for PostScript files is free and available for all platforms. This is what will make sense of your *.eps files and convert them for viewing on screen. But since it is command-line only (no GUI) most folks talk to it only through GUI-enabled viewer programs. This module avoids all that, just talking to Ghostscript for you. Nevertheless, you may wish to employ a GUI-enabled viewer.

http://www.ghostscript.com/

Other PostScript Viewers

These too are free. They generally work by interfacing with Ghostscript on your behalf, saving you the hassle of having to deal with Ghostscript's command-line (non-GUI) interface. These are all much more user-friendly.

FOR WINDOWS ONLY

The program GSView.exe will display *.eps files and also convert them to to other formats. Conversion from *.eps to *.png is excellent.

FOR UNIX ONLY

The program gv will display *.eps files very well. It will not, however convert them to any other formats.

FOR ALL

The Gnu Image Management Program (aka The GIMP) is a full-bodied graphic image editor which, among its many other features, can also read in *.eps files via Ghostscript. And any format it can read it, it can also convert and write out. The GIMP is, of course, both free and open-source.

http://www.gimp.org/

When you open an *.eps file in The GIMP it will pop up a menu for how you want the *.eps file to be read in. Select the Try Bounding Box checkbox. Then note the two antialiasing radio buttons. Select weak for text and strong for graphics. This will make bring up an image which looks just like the default both which gv and GSView provide.

INCOMPATIBILITIES ^

None known as yet.

BUGS AND LIMITATIONS ^

Owing to inbuilt addressing limitations of PostScript, data sets may not exceed 65,535 data points.

This program, being free software, carries absolutely no warranties or guarantees of any kind, neither expressed, implied, or even vaguely hinted at.

SCRIPT HISTORY ^

The PostScript definitions herein embeded derive from a standalone PostScript program named OmniGraph.ps which I wrote sometime circa 1992. This I did in response to frustrations over an upgrade by Measurments Group to the software in their System 5000 strain gage instrument versus the graphing feature in their older System 4000.

I'd already gotten kind of handy in PostScript from wrangling with the PostScript prolog files of Amiga 2000 programs like Excellence! and Gold Disk so as to publish in Esperanto for which I could find no fonts. But that I was able to deal with on my own in due course, and for several platforms besides my own beloved Amiga.

As an aside I cannot refrain from relating that this particular frustration also proved to be the font (pun intended) of my initial anger and dismay at Microsoft. Since once I had learnt how to solve this problem for both the Amiga and for the Macintosh I next turned, as a community service, to do so for MS Word and found it imposible. How so? Entirely because Mr. Gates had done two things to thwart me: First he'd encrypted MS Word's PostScript prolog file for no good reason. And second, once I had managed to decrypt said prolog, I next found the fiend to have therein called the PostScript 'exitserver' command entirely contrary to warnings forbidding such in the official PostScript docs. My Microsoft-ish experiences since have only deepened that sentiment further.

As an aside, you may further wish to know that the reason folks now publish telephone numbers as 123.555.1212 versus the more traditional 123-555-1212 may also be blamed on Mr. Gates. MSWord sorely frustrated users for lack of a non-breaking hyphen (which Amiga, Apple, NEXT and several others all had). So to keep telphone numbers from wrapping on a line, poor sods stuck with MSWord started using periods. But I digress...

From there I went kind of wild with PostScript, using it in all manner of ways for which it was probably not intended. This I could in no wise have done without the continuing example of Don Lancaster, noted PostScript guru, for his many excellent articles in Publish magazine and elsewhere.

Ref. http://www.tinaja.com

Most of those ancient efforts have now lain fallow many a year. But once again, this time in frustration over a (for most folks, trifling) lack in the Perl module GD::Graph::lines, I have resurrected my old, trusty OmniGraph.ps and grafted it piecemeal, with some changes, into this new module Chart::EPS_graph.pm so as to work around that specific issue where GD::Graph::lines chokes on dual Y axes needing multiple channels.

AUTHOR ^

Gan Uesli Starling <gan@starling.us>

LICENSE AND COPYRIGHT ^

This program is free software; you may redistribute and/or modify it under the same terms as Perl itself.

Copyright (c) 2006 Gan Uesli Starling. All rights reserved.

syntax highlighting: