Author image James Lee Carpenter

NAME

Geo::GNUPlot - Perl extension for plotting position tracks onto a world map.

SYNOPSIS

        use Geo::GNUPlot;

        $option_HR={
                        'grid_file' => '/home/test/grid_file',
                        'map_file' => '/home/test/map_file',
                        'gnuplot' => '/usr/local/gnuplot',
                        };

        $plot_obj=Geo::GNUPlot->new($option_HR);

        $track_AR=[
                        [15, 50], #x,y pair
                        [5.3, 10.2],
                        [-2, -5]
                  ];

        or
        
        $track_AR=[
                        [50, N, 15, E], #latitude, lat. direction, longitude, long. direction
                        [10.2, N, 5.3, E],
                        [5, S, 2, W]
                  ];

        $output_file='/home/test/plot.gif';

        $plot_option_HR={
                        'x_pad' => 2, #default 0
                        'y_pad' => 3, #default 0
                        'x_scale' => 5, #default 1
                        'y_scale' => 4, #default 1
                        'title' => 'Example Plot', #default 'Storm Tracking Map'
                        'term' => 'gif', #default gif  {any valid gnuplot term argument}
                        'temp_dir' => '/home/tmp/', #default '/tmp/'
                        };

        #Create the plot.
        ($success, $error)=$plot_obj->plot_track($track_AR, $output_file, $plot_option_HR);

        ####
        #For diagnostic purposes, create a contour and surface plot of the radius function.

        $contour_plot='/home/test/radius_contour.gif';

        $surface_plot='/home/test/radius_surface.gif';

        #Only the temp_dir, and term option values will be used.
        ($success,$error)=$plot_obj->plot_radius_function($contour_plot, $surface_plot, $plot_option_HR);


        ####
        #Determine the radius function value at a given position.
        $position_AR=[5.3, 10.2];

        or

        $position_AR=[10.2, N, 5.3, E];

        ($function_value, $error)=$plot_obj->radius_function($position_AR);
        
        

DESCRIPTION

This program plots a set of latitude/longitude pairs as a track on a world map using gnuplot. The plot radius is determined by a user defined radius function.

IMPLEMENTATION

This program utilizes gnuplot by generating temporary gnuplot configuration files and then running gnuplot on these files. The knowledge of what xrange and yrange to use in the gnuplot configuration files is determined by a user defined radius function, an x and y padding, and an x and y scaling of the radius function.

The radius function is controlled by user defined node values on a user defined irregular grid. Values between the nodes are computed using two dimensional linear interpolation. I used Numerical Recipes in Fortran 77 page 117 equations 3.6.3, 3.6.4, and 3.6.5 as a reference. It is a simple formula and can be derived from scratch without too much effort. If you don't like this approach then simply override the radius_function method with your own. Better yet, provide your improved version to the current maintainer of this package. In the event Jimmy Carpenter (myself) is still the maintainer, offer to take over!

The irregular grid and node values are set in the grid_file file. An example is shown below:

        #xtics must be numerically ascending
        xtics: -170, -70, -50, -30, -10, 30, 180
        #ytics must be numerically descending
        ytics: 90, 80, 60, 40, 20, 0, -60, -90
        #       
        radius_grid:
        5       4       5       5       8       8       9
        5       4       5       5       8       8       9
        5       4       5       5       8       8       2
        5       6       5       5       6       3       9
        5       4       8       5       8       8       2
        5       3       5       5       7       8       9
        5       4       5       5       8       8       6
        5       4       5       5       8       8       9

To see what this looks like, just cut and paste this example into a file and generate a contour and surface plot using the plot_radius_function method. To see how this function affects the plot window try out the plot_track method for various positions.

The objective of the radius function approach is to allow the user to correlate interest level to plot zoom level. In the event you live in Houston you probably don't care too much about how close a hurricane is to some small deserted island in the Atlantic Ocean. Your concern will be how close the hurricane is to your home in Houston. It is also possible to create a radius function that insures a plot of a hurricane in the middle of the Atlantic Ocean has a wide enough plot window to show some land that provides context.

CONSTRUCTOR

new (HASH_REF)

Creates and returns a new Geo::GNUPlot object. If unsuccessful it returns an undefined value. The mandatory hash reference argument should contain the following keys and associated values:

        grid_file:  contains path to the grid file
        map_file:  contains a 2D map of the world (provided with bundle)
        gnuplot:  contains path to gnuplot executable

METHODS

plot_track(TRACK_ARRAY_REF, OUTPUT_FILE, OPTION_HASH_REF)

Creates a plot of the position track provided by the TRACK_ARRAY_REF and outputs it to the OUTPUT_FILE filename. The plot configuration options are contained in the OPTION_HASH_REF.

The plot_track method returns an array of the form (SUCCESS, ERROR). SUCCESS indicates if the method successfully generated a plot. ERROR contains the reason for any failure. If the method was successful ERROR will be undefined.

The TRACK_ARRAY_REF is an array of position arrays. The position arrays can be either x,y pairs, or an array of the form (LATTITUDE, LATTITUDE_DIR, LONGITUDE, LONGITUDE_DIR). The plot will be centered around the first position in the TRACK_ARRAY_REF.

The OUTPUT_FILE is the full path of the filename to use as output.

The OPTION_HASH_REF contains configuration options for the plot. The valid option keys, descriptions, and default values are given below.

        x_pad:          Determines the additional X padding for the plot.
                        Defaults to 1.

        y_pad:          Determines the additional Y padding for the plot.
                        Defaults to 1.

        x_scale:        Scales the radius value returned by the
                        radius_function method for use in determining
                        the xrange of the plot.
                        Defaults to 1.

        y_scale:        Scales the radius value returned by the
                        radius_function method for use in determining
                        the yrange of the plot.
                        Defaults to 1.

        title:          Sets the plot title.
                        Defaults to 'Storm Tracking Map'.

        term:           Sets the gnuplot terminal type.  See gnuplot
                        documentation for more details.
                        Defaults to 'gif'.

        temp_dir:       Sets the directory to use for writing temporary
                        configuration and data files.
                        Defaults to '/tmp/'.
plot_radius_function(CONTOUR_OUTPUT_FILE, SURFACE_OUTPUT_FILE, OPTION_HASH_REF)

Creates a 2D contour and 3D surface plot of the radius function. This enables the user to better visualize the radius function and how it is being interpolated from the provided node values. The 2D contour plot overlays the world map provided by the map_file during construction of the Geo::GNUPlot object.

The CONTOUR_OUTPUT_FILE is the full path of the filename to use for the contour plot.

The SURFACE_OUTPUT_FILE is the full path of the filename to use for the surface plot.

The OPTION_HASH_REF is identical in format to that used for the plot_track method, except only the temp_dir and term key value pairs are needed or required.

The plot_radius_function method returns an array of the form (SUCCESS, ERROR). SUCCESS indicates if the method successfully generated the plots. ERROR contains the reason for any failure. If the method was successful ERROR will be undefined.

radius_function(POSITION_ARRAY_REF)

Provides direct access to the radius_function internally used to compute plot window sizes. This can be useful for things such as sorting positions by interest level or debugging changes to the radius function.

The POSITION_ARRAY_REF has the same two possible forms as each element of the TRACK_ARRAY_REF argument of the plot_track method.

AUTHOR

James Lee Carpenter, Jimmy.Carpenter@chron.com

SEE ALSO

        Geo::StormTracker
        gnuplot
        perl(1).

ADDITIONAL REFERENCES

gnuplot
        http://www.cs.dartmouth.edu/gnuplot_info.html 
        http://members.theglobe.com/gnuplot/ 
        http://www.geocities.com/SiliconValley/Foothills/6647/
linear interpolation
        Numerical Recipes in Fortran 77
        Second Edition
        (The Art of Scientific Computing)
        Authors:  William H. Press
                  William T. Vettering
                  Saul A. Teukolsky
                  Brian P. Flannery
        Pub:  Cambridge University Press
        ISBN:  0-521-43064-X
        Relevant Page:  117