view release on metacpan or  search on metacpan

lib/Geo/GNUPlot.pm  view on Meta::CPAN

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

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

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

=head1 CONSTRUCTOR

=over 4

=item new (HASH_REF)

Creates and returns a new C<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

=back

=head1 METHODS

=over 4

=item plot_track(TRACK_ARRAY_REF, OUTPUT_FILE, OPTION_HASH_REF)