Columbus3

A ruby gem to show, organize, and search GPS tracks generated by the Columbus V900 and V990 GPS trackers.

The gem works by allowing you to associate a "sidecar" file to each Columbus track. The sidecar file, in YAML fromat, contains information such as the start and end location, the maximum speed, the maximum elevation of the track.

The information stored in the sidecar files can then be used to search tracks. Them gem allows you, for instance, to perform complex queries such as: "get the tracks whose max speed less than 10 kilometers per hours and whose start location is in the USA".

Tracks can be shown on a map. The application is pipe "friendly", so that, for instance, you can pipe the output of a search to the show command to view all the tracks matching your search.

Installation

Add this line to your application's Gemfile:

ruby
gem 'columbus3'

And then execute:

$ bundle

Or install it yourself as:

$ gem install columbus3

Usage

Generate the sidecar files for your tracks with the process command:

columbus3 process 11010101.CSV # generate the sidecar file for 11010101.CSV

notice that you can pass * as argument to process all your tracks at once. The process command reverse geocodes the first and last point of the track and stores other information about the track.

cat 11010101.CSV
---
:start_date: 2011-01-01 22:15:58.000000000 Z
:end_date: 2011-01-02 03:06:57.000000000 Z
:duration: 17459.0
:size: 17440
:start_location: University of California, Santa Barbara, Ocean Road, Isla Vista, CA 93117, USA
:end_location: 500-524 Matadero Avenue, Palo Alto, CA 94306, USA
:min_speed: 0
:max_speed: 138
:min_height: -9
:max_height: 432
:bearing: NW
:distance: 885.6399415490763
:distance_aerial: 392.2223148453187
:filename: 11010101.CSV

Once you have the sidecar files, you can search, show, and display detailed information about your tracks.

For instance:

columbus3 search 'location ~ "USA"'

returns all tracks in the current directory, whose start or end location has "USA" in the address field. Notice the usage of the single quote to protect the ~ from expansion.

The command:

columbus3 show 11010101.CSV 11010201.CSV

shows tracks on a map (you need to open _show.html in a browser to view the map), while

columbus3 graph 11010101.CSV

shows info about a single track (you need to open _graph.html in a browser to view the info).

Piping also works. For instance:

columbus3 search 'location ~ "USA"' --fields path | colmumbus3 show

gets all tracks whose start or end location has "USA" in the address field and diplays them on a map.

GPX files can also be managed, although it is first necessary to convert them to V900 tracks with the following command:

columbus3 convert file.gpx

makes file.gpx into a V900 CSV track.

If you do not want to type columbus3 every time, you can invoke a console:

columbus3 console
columbus3:000> process 11010101.CSV
columbus3:001> show 11010101.CSV
columbus3:002>

More information with:

columbus3 help                          # get list of available commands
columbus3 help process                  # get help about the process command    
columbus3 man

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in `version.rb`, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/avillafiorita/columbus3.

License

The original code of this gem is available as open source under the terms of the MIT License.

The gem ships wih the following Javascript libraries, which are distributed according to their licenses:

Version History

0.6.0

More informative output from commands
The help command is now more informative
The path field in the search command now returns the path of the CSV file (and not that of the YAML sidecar file), simplifying piping searches to the show command
When searching, a new field yaml returns the name of the sidecar file associated to a track
New behaviour of show and graph commands: the _show.html and _graph.html are always created, even if a file with the same name already exists in the current directory (previous versions required to specify the --force option to achieve the same behaviour); a backup copy of the files which are overwritten is always created. The --force option forces rewriting of the javascript files; backup copies of existing files are created.
The number of tile providers has been significantly reduced
Some code has been refactored to improve readability
Added -h and --help (in addition to the help command)
Updates to the documentation
Bumped version of gems used in production
Bumped version of gems used for development

0.5.0

Fixed a bug with searches on dates
Added converter from GPX to Columbus V900
Bumped leaflet and leaflet providers; updated map layers used by the show command
More informative messages when running commands
Added a console: launch it with columbus3 console
Fixed a bug with graph (call to sanitize failed)
Added Changelog File, which I am using to help maintaning this list of changes

0.4.0

Improved syntax for search:
- new option -r searches in sub-directories
- new option --fields allows to specify the to look for

0.3.0

Added documentation for search command; added this README file
New command graph plots data about a track (look for _graph.html in the current directory)
Added --force option to process
Internals: fixes to the sidecar class

0.2.1

Fixed bug in time parsing

0.2.0

Fixes to syntax
Print man page if not arguments are provided
Added --filename option to show command

0.1.0

Initial release