/ 
Ham-Resources-Utils-0.04
River stage zero No dependents
/ Ham::Resources::Utils

NAME

Ham::Resources::Utils - Calculation of distance and course beetwen two points on Earth (through coordinates or grid locator), and Sunrise, Sunset and Midday time for these locations (in UTC). Also sexagesimal degrees and decimal degrees convertion and grid location. For use mainly for Radio Amateurs.

VERSION

Version 0.04

SYNOPSIS

This module calculates the distance and course between two points on the Earth. Also Sunrise, Sunset and Midday time for both locations.

The data of the locations may be in terrestrial coordinates or through 'Maidenhead Locator System' (grid Locator) notacion.

The module offer the possibility to access to some methods that uses it, for example conversions between sexagesimal degrees into decimal degrees or conversion between grid locator to sexagesimal degrees.

Also access to convert decimal degrees to compass names, and more.

use Ham::Resources::Utils;

my $foo = Ham::Resources::Utils->new();
...

SUBROUTINES/METHODS

new

This is the constructor.

my $foo = Ham::Resources::Utils->new();

data_by_coordinates

Gets a string with the date and a hash with the coordinates in sexagesimal values from point A and point B and returns a hash with all previous data and Distance, course and compass values and Sunrise, Sunset and Midday times for both locations if needed.

 my $date = "14-03-2012";
 my %coordinates = ( lat_1 => "41N23", 
 			long_1 => "2E11", 
 			lat_2 => "30S0", 
 			long_2 => "10W45");

 my %data = $foo->data_by_coordinates{$date, %coordinates};
 print Dumper(%data);

The $date argument is necessary for the Sun time calculations (Sunrise, Sunset and Midday).

Distances are in kilometers (km) and Miles (mi). Times are in UTC (Universal Time).

An output example:

 DATA_BY_COORDINATES()
   compass: S                       # compass direction to point B or destination
   course_dec: 190.94              # direction to destination in decimal degree
   course_sexag: 190.56          # direction to destination in sexagesimal degree
   date: 14-3-2012                 # date of event (for Sun calculation porpouses)
   distance_km: 9377.83            # distance to destination in kilometers
   distance_mi: 17367.74           # distance to destination in miles
   lat_1: 41N23"              # Latitude of point A or origin in sexagesinal notation
   lat_1_dec: 41.3833333333333     # Latitude of origin in decimal notation
   lat_2: 41S54"              # Latitude of point B or destination in sexagesimal notation
   lat_2_dec: -41.9                # Latiude of destination in decimal notation
   locator_1: JN11cj               # Grid Locator of origin point
   locator_2: IE38sc               # Grid Locator of destination point
   long_1: 2E12"              # Longitude of point A or origin in sexagesimal notation
   long_1_dec: 2.2                 # Longitude of origin in decimal notation
   long_2: 12W30"             # Longitude of point B or destination in sexagesimal notation
   long_2_dec: -12.5               # Longitude of destination in decimal notation
   midday_arrive: 12h 1m           # Midday time on point B (destination) in UTC
   midday_departure: 12h 1m        # Midday time on point A (origin) in UTC
   sunrise_arrive: 6h 5m           # Sun rise time on point B (destination) in UTC
   sunrise_departure: 6h 5m        # Sun rise time on point A (origin) in UTC
   sunset_arrive: 17h 58m          # Sun set time on point B (destination) in UTC
   sunset_departure: 17h 58m       # Sun set time on point A (origin) in UTC

data_by_locator

Gets a string with the date and a string with the locator of point 'A' and an string with a locator for point 'B'. Returns a hash with the data shown it in the previous method.

my $date = "14-03-2012"; # date in 'dd-mm-yyyy' format
my $locator_dep = "JN11cj";
my $locator_arr = "IJ90ca";

my %data = $foo->data_by_locator($date,$locator_dep,$locator_arr);
print Dumper(%data);

loc2degree

Gets a string with grid locator value and returns an array with the latitude and longitude in sexagesimal degrees form.

degree2loc

Gets a string with the latitude and a string with the longitude, in sexagesimal notation, of a point on Earth and returns a string with the grid locator notation.

my $lat = "41N23";
my $long = "2E11";
my $locator = $foo->degree2loc($lat, $long);

compass

Gets an integer with a decimal degree and returns a string with its equivalent value in a compass (North, East, ...). It uses a separation of 11.25 degrees for each position, 32 cardinal positions of total. Values range must be between 0 to 360 degrees.

my $compass = $foo->compass("-90.0"); # returns "W" (west)
my $compass = $foo->compass("270.0"); # returns "W" (west)

dec2sexag

Gets an integer with a decimal degree value and returns a string with its equivalence to sexagesimal degree form. Only returns degrees and minutes.

sexag2dec

Gets a hash with sexagesimal value (maximun four) and returns a hash with its decimal values.

Range of values are -90 to 90 for latitudes, and -180 to 180 for longitudes.

Values must be a pair, longitude and latitude. Two values for one point or four values (two pairs) for two points.

There is not mandatory send a complete hash (4 values), but you will receive a hash with the four.

You can use it like this:

    my %coord = (
	Long_1 => "41N23.30",
      	Lat_1  => "2E11.10"
    );
    my %sexag = $foo->sexag2dec(%coord);
    foreach my $key (sort keys %sexag) {
      say $key." = ".$sexag{$key} if ($sexag{$key});
    }

The index send it, you will receive with '_dec' suffix, ie, you send 'latitude' and receive 'latitude_dec'

cicle_sun

Gets three strings with latitude, longitude, in decimal degrees, and date, in 'dd-mm-yyyy' format and returns a hash with Sunrise time, Sunset time and Midday time in hours and minutes format in Universal Time (UTC).

my %sun = $foo->cicle_sun($lat,$long,$date);

date_split

Gets a string with date in format 'dd-mm-yyyy' and check it if value is a valid date.

Returns an array with the day, month and year ... or error message.

Internals subs

data_constructor

Internal function used by data_by_coordinates() and data_by_locator() to call the others functions and create a response.

NESW

Internal function to convert degrees to radians.

check_error

Internal function to check errors in data_by_coordinates() or data_by_locator().

is_date

Internal function to check if a date is valid.

Cheking Errors

In functions that return only a string or an array, errors will detect to match /Error/ word. In complex functions, like data_by_coordinates, that responses with a hash, you check the '_error' index, i.e:

    %data = $foo->data_by_locator($date,$locator_1,$locator_2);
    if (!$data{_error}) {
	    foreach my $key (sort keys %data) {
		    say $key.": ".$data{$key};
	    }
    } else {
	    say $data{_error};
    }

... or something like this :p

AUTHOR

CJUAN, <cjuan at cpan.org>

BUGS

Please report any bugs or feature requests to bug-ham-resources-utils at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Ham-Resources-Utils. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Ham::Resources::Utils

You can also look for information at:

TODO

  • Add long path course and distances from point A to B

  • Add a function to calculate X and Y coordinates based on real coordinates for use it on a geographical projection (or Plate Carree)

LICENSE AND COPYRIGHT

Copyright 2012-2016 CJUAN.

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.