columbus3 0.5.1 → 0.6.0

data/lib/columbus3/cli/command_syntax.rb

@@ -18,34 +18,107 @@ module Columbus3
     def self.version_opts
       opts = Slop::Options.new
       opts.banner = "version -- print version information"
-      return { :version => [opts, :version] }
+      help = <<EOS
+NAME
+   #{opts.banner}
+
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   return version information
+
+EXAMPLES
+   columbus3 version
+   columbus3 version #{VERSION}
+EOS
+      return { :version => [opts, :version, help] }
     end
 
     def self.console_opts
       opts = Slop::Options.new
       opts.banner = "console [options] -- Enter the console"
-      opts.string "-f", "--filename", "Password file to encrypt. Write to <file>.enc"
-      return { :console => [opts, :console] } 
+      help = <<EOS
+NAME
+   #{opts.banner}
+
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   Invoke a console, from which you can more easily run
+   columbus3 commands.
+
+EXAMPLES
+   columbus3 console
+   columbus3:000> process 11010101.CSV
+   columbus3:001> show 11010101.CSV
+   columbus3:002>
+EOS
+       return { :console => [opts, :console, help] } 
     end
 
     def self.man_opts
       opts = Slop::Options.new
       opts.banner = "man -- print a manual page"
-      return { :man => [opts, :man] }
+      help = <<EOS
+NAME
+   #{opts.banner}
+
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   Print the README file of this gem
+
+EXAMPLES
+   columbus3 man
+EOS
+      return { :man => [opts, :man, help] }
     end
 
     def self.help_opts
       opts = Slop::Options.new
       opts.banner = "help [command] -- print usage string"
-      return { :help => [opts, :help] }
+      help = <<EOS
+NAME
+   #{opts.banner}
+
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   Print help about a command
+
+EXAMPLES
+   columbus3 help
+   columbus3 help process
+EOS
+      return { :help => [opts, :help, help] }
     end
 
     def self.process_opts
       opts = Slop::Options.new
       opts.banner = "process [track ...] -- generate sidecar files for given tracks"
       opts.boolean "-f", "--force", "Overwrite existing sidecar file"
-      
-      return { process: [opts, :process] }
+      help = <<EOS
+NAME
+   #{opts.banner}
+
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   Generate a sidecar file for the track(s) passed as input.
+
+   Once created a sidecar file usually does not need to be regenerated.  You can
+   use the `--force` option to cause the sidecar file to be rewritten.
+
+EXAMPLES
+   columbus3 process 11010101.CSV 11010201.CSV
+   columbus3 process *
+EOS
+      return { process: [opts, :process, help] }
     end    
 
     def self.search_opts
@@ -54,10 +127,81 @@ module Columbus3
 
       opts.boolean "--debug", "Show how the query is processed"
       opts.boolean "-r", "--recurse", "Recurse in subdirectories"
-      opts.string "-d", "--dir", "Directory to search"
+      opts.string "-d", "--dir", "Directory to search (default to current directory)"
       opts.array "--fields", "Comma separated list of fields to print"
+      help = <<EOS
+NAME
+   #{opts.banner}
+
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   Search a directory for tracks matching your search criteria.  
+
+   By default columbus3 searches in the current dir; use the `--dir`
+   option to choose a different directory.
+
+   Use `--recurse` to recurce in subdirectories as well.
+
+   Use `--fields` to choose what information is displayed in the output.
+
+   Terms you can search for:
+
+     location, start_location, end_location
+     date, start_date, end_date
+     year
+     duration
+     max_speed
+     min_height
+     max_height
+
+   Numerical operators:  
 
-      return { search: [opts, :search] }
+     <, <=, ==, >=, >
+
+   String operators (locations):
+ 
+     ~ (contains), == (is exactly)
+
+   Complex Terms:
+
+     Use "and" and "or" to build complex queries
+
+   Examples of simple searches
+
+     'location ~ "USA"'     any track whose start or end location contains USA
+     'date > 2015-02-14'    any track whose start or end date is after Feb 14, 2015
+     'year == 2015'         any track whose start or end date is in 2015
+     'duration <= 01:02:03' any track with a duration of less than 1h, 2min, and 3secs
+     'max_speed > 120'      any track with a max speed greater than 120 km/h
+     'min_height == 10'     any track with a min height lower than 10 meters
+
+   Examples of complex searches
+     'location ~ "USA" and start_date >= 2015-01-01' tracks in the USA after or on Jan 1, 2015
+     'start_location ~ "Trenton" and end_location ~ "New York"'  trips from Trenton to New York
+
+   List of supported fields in the output list:
+
+     yaml           -> full pathname of the YAML metadata file
+     path           -> full pathname of the CSV file
+     filename       -> basename of the CSV file
+     start_location -> start location
+     end_location   -> end location
+     start_date     -> start date (and time)
+     end_date       -> end date (and time)
+     duration       -> duration in seconds
+     min_speed      -> minimum speed in km/h
+     max_speed      -> maximum speed in km/h
+     min_height     -> minimum height in meters
+     max_height     -> maximum height in meters
+
+EXAMPLES
+
+     columbus3 search 'location ~ "USA"'
+     columbus3 search 'location ~ "USA" and speed < 10' --fields path | columbus3 show
+EOS
+      return { search: [opts, :search, help] }
     end
 
     def self.show_opts
@@ -66,9 +210,21 @@ module Columbus3
 
       opts.string "-f", "--filename=", "Output filename (default is _show.html)"
       opts.boolean "--force", "Force rewriting of the js file, even if it already exists"
-      opts.boolean "--sidecar", "Pass sidecar files rather than CSV files (use it when piping searches)"
+      help = <<EOS
+NAME
+   #{opts.banner}
+
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   Generate an html file which shows the track on a map.
 
-      return { show: [opts, :show] }
+EXAMPLES
+   columbus3 show 11010101.CSV 11010201.CSV
+     columbus3 search 'location ~ "USA" and speed < 10' --fields path | columbus3 show --filename "us_tracks.html"
+EOS
+      return { show: [opts, :show, help] }
     end
 
     def self.graph_opts
@@ -76,18 +232,61 @@ module Columbus3
       opts.banner = "graph [--filename filename] [--force] track -- plot speed and height profile of track"
 
       opts.boolean "--force", "Force rewriting of the js file, even if it already exists"
+      help = <<EOS
+NAME
+   #{opts.banner}
 
-      return { graph: [opts, :graph] }
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   Plot speed and height profile of a single track.
+
+EXAMPLES
+   columbus3 graph 11010101.CSV
+EOS
+      return { graph: [opts, :graph, help] }
     end
 
     def self.convert_opts
       opts = Slop::Options.new
       opts.banner = "convert track -- convert a GPX into a set of CSV files"
-      opts.boolean "--force", "Force rewriting of the csv files, even if it already exists"
+      opts.boolean "--force", "Force rewriting of the csv files, even if they already exist"
+      help = <<EOS
+NAME
+   #{opts.banner}
 
-      return { convert: [opts, :convert] }
-    end
+SYNOPSYS
+   #{opts.to_s}
+
+DESCRIPTION
+   Convert a GPX track to a CSV track
+
+   The command is useful if you are using different loggers for generating your
+   tracks:
+
+      columbus3 convert file.gpx
 
+   will generate
+
+      file-1.csv
+      file-2.csv
+      ...
+
+   one per track in the GPX file.
+
+EXAMPLES
+   columbus3 convert track.gpx
+
+BUGS AND LIMITATIONS
+
+  The Columbus V900 format has fields with fixed width, and uses ^@ as a filler.
+  The CSV file generated by the convert command generates fields of variable width
+  (standard CSV files, I dare say).  The heading field is not computed
+  and the field is filled with -1.
+EOS
+      return { convert: [opts, :convert, help] }
+    end
 
     # def self.split_opts
     #   opts = Slop::Options.new

data/lib/columbus3/metadata/sidecar.rb

@@ -21,6 +21,11 @@ module Columbus3
       @metadata.keys
     end
 
+    # it always works because initialization requires a filename
+    def filename
+      @metadata[:filename] + ".yaml"
+    end
+
     def load
       @metadata = YAML.load(File.read(@metadata[:filename] + ".yaml"))
     end
@@ -47,7 +52,7 @@ module Columbus3
     end
 
     def load array
-      @metadata = array.each.map { |x| YAML.load(File.read(x)).merge({ :path => x }) }
+      @metadata = array.each.map { |x| YAML.load(File.read(x)).merge({ path: x.gsub(/\.yaml$/, ''), yaml: x }) }
     end
 
     def search term

data/lib/columbus3/renderer/flot_renderer.rb

@@ -5,9 +5,14 @@ require 'columbus3/renderer/sanitizer'
 module Columbus3
   # make a track into a flot graph (speed and height)
   module FlotRenderer
-    # apply the ERB in html/flot.html.erb
-    # and save it in the current directory, under _flot.html
-    def self.show filename, file
+    OUTPUT_FILENAME = "_graph.html"
+    
+    # apply the ERB in html/flot.html.erb and save it in the current directory
+    # use filename if provided or the default OUTPUT_FILENAME
+    def self.show hash
+      filename = hash[:filename] || OUTPUT_FILENAME
+      files = hash[:files] || []
+
       template = File.join(File.dirname(__FILE__), "/../../html/flot.html.erb")
       renderer = ERB.new(File.read(template))
       
@@ -19,7 +24,7 @@ module Columbus3
                   File.join(bower_dir, 'flot/jquery.flot.time.js'),
                   File.join(bower_dir, 'flot/jquery.flot.selection.js')                  
                  ]
-      @file = file
+      @file = files[0]
       # TODO: manage the case of sidecar not existing
       @track_info = Sidecar.new @file
       @track_info.load
@@ -34,8 +39,8 @@ module Columbus3
     end
 
     # make a v900 track into a graph layer cached to disk
-    def self.to_graph_data filename, force = false
-      target = to_graph_filename filename
+    def self.to_javascript_file filename, force = false
+      target = to_javascript_filename filename
 
       if force or not File.exists? target
         track = V900Track.new filename: filename
@@ -50,10 +55,9 @@ height_#{id} = #{track.range.each.map { |i|[track[i].time.to_i * 1000, track[i].
 EOS
         end
       end
-
     end
 
-    def self.to_graph_filename filename
+    def self.to_javascript_filename filename
       filename + "_graph.js"
     end
 

data/lib/columbus3/renderer/leaflet_renderer.rb

@@ -6,9 +6,14 @@ module Columbus3
   # renderer controls the transformation of a V900 tracks into a displayable format,
   # whatever this means
   module LeafletRenderer
+    OUTPUT_FILENAME = "_show.html"
+
     # apply the ERB in html/show.html.erb (which includes all the tracks to display)
     # and save it in the current directory, under _show.html
-    def self.show filename, files
+    def self.show hash
+      filename = hash[:filename] || OUTPUT_FILENAME
+      files = hash[:files] || []
+      
       template = File.join(File.dirname(__FILE__), "/../../html/show.html.erb")
       renderer = ERB.new(File.read(template))
       
@@ -25,10 +30,9 @@ module Columbus3
       end
     end
 
-    # make a v900 track into a leaflet layer cached to disk
-    def self.to_leaflet filename, force = false
-
-      target = to_geojson_filename filename
+    # make a v900 track into a geojson file 
+    def self.to_javascript_file filename, force = false
+      target = to_javascript_filename filename
 
       if force or not File.exists? target
         # load the template
@@ -47,15 +51,15 @@ module Columbus3
 
     end
 
-    def self.to_geojson_filename filename
+    def self.to_javascript_filename filename
       filename + ".js"
     end
 
     def self.to_leaflet_layername filename
-      to_varname "layer_", Sanitizer::sanitize(filename)
+      to_javascript_varname "layer_", Sanitizer::sanitize(filename)
     end
     
-    def self.to_varname prefix, filename
+    def self.to_javascript_varname prefix, filename
       prefix + Sanitizer::sanitize(filename)
     end
   end

data/lib/columbus3/version.rb

@@ -1,3 +1,3 @@
 module Columbus3
-  VERSION = "0.5.1"
+  VERSION = "0.6.0"
 end

data/lib/html/flot.html.erb

@@ -35,7 +35,7 @@
             <% end %>
         </div>
 
-        <script src="<%= to_graph_filename @file %>"></script>
+        <script src="<%= to_javascript_filename @file %>"></script>
         <script>
          // required by plot for tooltips (it moves the tooltip, appending it directly to body
          $("<div id='tooltip'></div>").appendTo("body");

data/lib/html/show.html.erb

@@ -38,7 +38,7 @@
         
         <%# insert the requested GPX Tracks (in json format) %>
         <% @files.each do |file| %>
-            <script src="<%= to_geojson_filename file %>"></script>
+            <script src="<%= to_javascript_filename file %>"></script>
         <% end %>
 
         <%# make each track into a layer%>

data/lib/html/track.js.erb

@@ -1,4 +1,4 @@
-var <%= to_varname "track_", @filename %> =
+var <%= to_javascript_varname "track_", @filename %> =
 { "type": "FeatureCollection",
   "features": [
       { "type": "Feature",
@@ -39,7 +39,7 @@ var <%= to_varname "track_", @filename %> =
   ]
 };
 
-<%= to_leaflet_layername @filename %> = L.geoJson(<%= to_varname "track_", @filename %>, {
+<%= to_leaflet_layername @filename %> = L.geoJson(<%= to_javascript_varname "track_", @filename %>, {
     onEachFeature: function onEachFeature(feature, layer) {
         if (feature.properties && feature.properties.name) {
             layer.bindPopup(feature.properties.name);
@@ -58,4 +58,4 @@ var <%= to_varname "track_", @filename %> =
     }
     */
 });
-    <%= to_leaflet_layername @filename %>.addTo(map);
+<%= to_leaflet_layername @filename %>.addTo(map);