NAME

GPS::Tracer - A processor of geographical route information

SYNOPSIS

# with having an account with Guardian Mobility
my $tracer = new GPS::Tracer (user => 'my.name', passwd => 'my.password');
my @files = $tracer->create_all;
map { print "Created file: ", $_, "\n" } @files;

# with your own input file
my $tracer = new GPS::Tracer (input_data => 'my-data.csv');
my @files = $tracer->create_all;
map { print "Created file: ", $_, "\n" } @files;

# create only OziExplorer waypoint file
my $tracer = new GPS::Tracer (input_data => 'my-data.csv');
my $data = $tracer->get_data;
print "Created file: ", $tracer->convert2oziwpt ($data), "\n";

DESCRIPTION

This module reads geographical location data (longitude, latitude and time) and converts them into various other formats and pre-processed files that can be used to display route information, for example using Google Maps.

The module was developed primarily to read data from the secure web site provided by Guardian Mobility (http://www.guardianmobility.com) for their product "Tracer" (data are published there after they are collected from the Globastar satellites). However, it was made flexible enough that it can also read data from a simple CSV format instead from their web site.

Some of the files created by this module were designed to be read by JavaScript in order to create/update web pages. Example of such usage is on the pages of the Arctic student expedition FrozenFive (http://frozenfive.org) - for whom the module was actually created in the first place, and also in the examples folder of this module distribution.

One scenario is to use this module in a periodically and automatically repeated script (on UNIX machine called a 'cronjob') and let the web pages read data from output files anytime they are accessed. This is the way how it was used for the FrozenFive expedition.

Input format

The input data are comma-separated values (CSV) (the first line being a header line). The only extracted values are those representing longitude, latitude, elevation and time. They are expected to be in the following format:

latitude  = 78.21582
longitude = 15.73496
time      = 2007-03-29 11:32:32
elevation = 532

If no format of the input data is specified, only the following field indexes are used (indexes starts from 0):

index    field contents
-----------------------
  6      time
  7      longitude
  8      latitude
  9      elevation

At the moment, Guardian Mobility data do not record any elevation - therefore the ninth field is extracted but not used (an therefore also not much tested).

Example of the Guarding Mobility raw input file is in 'examples' (file trout-guardian.csv).

If you use your own input data, you specify your input data file by using parameter input_data, and you can specify your own indexes for the mentioned fields, as a comma-separated list of four numbers, by using parameter input_format. For example, if your data are in file my-input.csv with this contents:

Time,Longitude,Latitude,Altitude
2007-04-21 12:48:27,16.78029,76.66666,
2007-04-21 12:36:05,16.78040,76.66668,
2007-04-21 12:06:11,16.78067,76.66664,

then you create a Tracer object by:

my $tracer = new GPS::Tracer (input_data   => 'my-input.csv',
                              input_format => '0,1,2,3');

Outputs

All outputs are created, under various file names, in the current directory, or in the directory given by the parameter result_dir. Part of the file names is hard-coded, but you can specify how all the file names will start by using parameter result_basename (default value is simply output).

The method create_all creates all of them - but you can also use other methods (see below) for selecting only some outputs. All created files (showing them with the default prefix output) are:

output-guardian-raw.csv

This is the copy of the data fetched from the Guardian web site. Such file is not created when you use your own inputs.

output-all.xml

An XML file containing all geographical points from the input. The format is easy-to-process by AJAX-based JavaScript page (see examples sub-directory):

<markers>
  <marker elevation="" lat="78.21582" lng="15.73496" time="2007-03-29 11:32:32" type="1" />
  <marker elevation="" lat="78.21057" lng="15.76251" time="2007-03-29 11:47:32" type="0" />
  <marker elevation="" lat="78.20559" lng="15.80085" time="2007-03-29 12:22:58" type="0" />
  ...
</markers>

The attribute type has value 1 for the first point in a day, otherwise value 0.

output-oneperday.xml

An XML file - using the same format as output-all.xml described above - containing only one point per day (the first one recorder each day). Plus the last point (if it is far enough from the first point of the last day - see below about what "far enough" means).

output-distance.xml

Another XML file - again using the same format as output-all.xml described above - containing points that are "far enough" from each other, but always also the first point for every day. The "far enough" is defined in metres by parameter min_distance (default value is 500).

output-summary.xml

A very simple XML file containing just a number of days and the total distance (in kilometres) of the whole recorded route. For example:

<summary>
  <total days="23" kms="302.676710159346" />
</summary>

output.csv

It contains daily total distances in a comma-separated value format. The headers are Date and Metres. For example:

Date,Metres
2007-03-29,8189.15115656143
2007-03-30,16177.7833535657
2007-03-31,15906.9657189604
2007-04-01,16826.279102736
2007-04-02,1032.79778451296

output-ozi.wpt

It contains points that are "far enough" (see above) in the format of OziExplorer (http://www.oziexplorer.com/) waypoints. For example:

OziExplorer Waypoint File Version 1.1
WGS 84
Reserved 2
magellan
-1, Mar-29/11:32, 78.21582, 15.73496, , 10, 1, 4, 0, 4227327, 2007-03-29 11:32:32, 0, 0, 0, -777, 8, 0, 17
-1, 11:47, 78.21057, 15.76251, , 2, 1, 4, 0, 5450740, 2007-03-29 11:47:32, 0, 0, 0, -777, 6, 0, 17
-1, 12:22, 78.20559, 15.80085, , 2, 1, 4, 0, 5450740, 2007-03-29 12:22:58, 0, 0, 0, -777, 6, 0, 17
-1, Mar-30/09:26, 78.15688, 15.82510, , 10, 1, 4, 0, 4227327, 2007-03-30 09:26:08, 0, 0, 0, -777, 8, 0, 17
-1, 13:47, 78.09275, 15.78624, , 2, 1, 4, 0, 5450740, 2007-03-30 13:47:26, 0, 0, 0, -777, 6, 0, 17
-1, Mar-31/08:53, 78.01713, 15.83664, , 10, 1, 4, 0, 4227327, 2007-03-31 08:53:31, 0, 0, 0, -777, 8, 0, 17
-1, 09:24, 78.00934, 15.84894, , 2, 1, 4, 0, 5450740, 2007-03-31 09:24:43, 0, 0, 0, -777, 6, 0, 17

output-chart.png

This is a graph showing daily distances. See an example in examples.

METHODS

new

use GPS::Tracer;
my $tracer = new GPS::Tracer (@parameters);

The recognized parameters are name-value pairs. The names are:

`user`, `passwd`, `login_url`, `data_url`

These are used to access Guardian web site. login_url is a URL of the main page where user and passwd are used to authenticate to get data from the data_url. Look into the source code how these parameters are used.

`from_date`, `to_date`

These parameters specify the time range of the data they will go to the outputs. Their format is YYYY-MM-DD hh:mm:ss and default values allow all data to be processed:

from_date: '0000-00-00 00:00:00'
to_date:   '9999-99-99 23:59:59'

`result_dir`, `result_basename`

The result_dir defines a directory name where all output files will be created (default is an empty value which indicates the current directory). All files are created with the names starting by result_basename.

`min_distance`

Its value (in metres) defines the minimal distance between points in some outputs (other outputs ignore this parameter and process all points). Default is 500.

`input_data`

It is a name of the input file. If it is not given, the program will try to fetch data from the Guardian web site (which will fail if other parameters (user, passwd, login_url, and data_url) are not given.

`input_format`

A string with four digits, separated by commas, each of them indicating an index (column) in the input CSV file. The four indexes should indicate columns with time, longitude, latitude, and elevation. The first column in the file has index 0. Default value is '6,7,8,9'.

All described parameters can be also set by the "set" methods and read by the "get" methods. The method names are the same as the parameter names. If it has a parameter, it is a "set" method, otherwise it is a "get" method:

user

my $tracer = new GPS::Tracer;
$tracer->user ('my.username');
print "My user name is: ", $tracer->user, "\n"

passwd

from_date

to_date

login_url

data_url

min_distance

result_dir

result_basename

input_data

input_format

create_all

It creates all outputs from the given data. This is the most common way to use the GPS::Tracer:

my $tracer = new GPS::Tracer (input_data => 'my-data.csv');
my @files = $tracer->create_all;
map { print "Created file: ", $_, "\n" } @files;

The method returns a list of created file names.

get_data

This method returns a reference to an array with elements being references to hashes, each such hash containing one route point. Key names are elevation, lat, lng, type and time. For example, this code:

my $tracer = new GPS::Tracer (input_data => 'testing-data/small.csv');
my @files = $tracer->get_data;
require Data::Dumper;
print Data::Dumper->Dump ( [$data], ['DATA']);

prints this:

$DATA = [
          {
            'elevation' => '',
            'lat' => '76.66664',
            'time' => '2007-04-21 12:06:11',
            'type' => 1,
            'lng' => '16.78067'
          },
          {
            'elevation' => '',
            'lat' => '76.66668',
            'time' => '2007-04-21 12:36:05',
            'type' => 0,
            'lng' => '16.78040'
          },
          {
            'elevation' => '',
            'lat' => '76.66666',
            'time' => '2007-04-21 12:48:27',
            'type' => 0,
            'lng' => '16.78029'
          }
        ];

This method is the first step if you wish to create only some outputs. Each output has its own method whose single parameters is the structure produced by get_data method. All of these methods returns a created file name:

convert2xml

Creates output output-all.xml.

summary2csv

Creates output output.csv.

summary2xml

Creates output output-summary.xml.

summary2graph

Creates output output-chart.png.

oneperday2xml

Creates output output-oneperday.xml.

min_distance2xml

Creates output output-distance.xml.

convert2oziwpt

Creates output output-ozi.wpt.

SUPPORTING FILES

The distribution of the GPS::Tracer has a script fetch_and_create.pl that can be used to produce just described outputs from the command-line parameters:

./fetch_and_create.pl -h

will produce a short help. Assuming that you are fetching data from Guardian, you can use:

./fetch_and_create -u your.user.name -p your.password

which will create all output files in the data sub-directory. However, more often you would need to define a range of data for which you are creating "route" files:

./fetch_and_create -u your.user.name -p your.password \
                   -b '2007-29-03 00:00:00'           \
                   -e '2007-15-06 23:59:59'

Or, you can pass your own input file, and its CSV format (column indexes):

./fetch_and_create -i data/otherfields.csv \
                   -f '0,1,2,3'

Other supporting files and HTML documenttaion are in the docs directory. They show how to use output files together with JavaScript to create and enhance web pages.

MISSING FEATURES

There could/should be an easier way how to read input data in more formats. At the moment, you need to overwrite the full get_data or even fetch_data method.
Sometimes, it would be beneficial to have more filtering options then just from_date and to_date. For example, for the FrozenFive expedition we had to ignore days when they made trips on snow mobiles, not on skis.
There should be a way how to pass user-defined properties for the created graph.
Similarly, there should be a way how to pass user-defined properties for the created OziExplorer waypoints (such as what symbols to use). As it is already now for the waypoint name (method wpt_name).

DEPENDENCIES

The GPS::Tracer module uses the following modules:

Text::CSV::Simple
XML::Simple
LWP::UserAgent
File::Temp
File::Spec
Date::Calc
GD::Graph

AUTHORS

Martin Senger <martin.senger@gmail.com>, Kim Senger <senger.kim@gmail.com>

COPYRIGHT

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

DISCLAIMER

This software is provided "as is" without warranty of any kind.

To install GPS::Tracer, copy and paste the appropriate command in to your terminal.

cpanm

cpanm GPS::Tracer

CPAN shell

perl -MCPAN -e shell
install GPS::Tracer

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

SYNOPSIS

DESCRIPTION

Input format

Outputs

output-guardian-raw.csv

output-all.xml

output-oneperday.xml

output-distance.xml

output-summary.xml

output.csv

output-ozi.wpt

output-chart.png

METHODS

new

user, passwd, login_url, data_url

from_date, to_date

result_dir, result_basename

min_distance

input_data

input_format

user

passwd

from_date

to_date

login_url

data_url

min_distance

result_dir

result_basename

input_data

input_format

create_all

get_data

convert2xml

summary2csv

summary2xml

summary2graph

oneperday2xml

min_distance2xml

convert2oziwpt

SUPPORTING FILES

MISSING FEATURES

DEPENDENCIES

AUTHORS

COPYRIGHT

DISCLAIMER

Module Install Instructions

`user`, `passwd`, `login_url`, `data_url`

`from_date`, `to_date`

`result_dir`, `result_basename`

`min_distance`

`input_data`

`input_format`