rozi 0.0.7 → 0.1.3

data/lib/rozi/name_search.rb

@@ -0,0 +1,176 @@
+
+require "rozi/file_wrapper_base"
+require "rozi/shared"
+
+module Rozi
+  ##
+  # Writes an enumerable of names to a file
+  #
+  # All keyword arguments are used as track properties.
+  #
+  # @param [Enumerable] enumerable
+  # @param [String] file_path
+  #
+  def write_nst(enumerable, file_path, **properties)
+    NameSearchTextFile.open(file_path, "w") { |nst|
+      nst.write_properties NameSearchProperties.new(**properties)
+
+      enumerable.each { |name|
+        nst.write_name name
+      }
+    }
+
+    return nil
+  end
+
+  ##
+  # This class represents a name in an Ozi Explorer name database.
+  #
+  # @note The +name+, +latitude+ and +longitude+ fields must be set, or runtime errors will
+  #   be raised when attempting to write to file.
+  #
+  class Name < DataStruct
+    PROPERTIES = [:name, :feature_code, :zone, :latitude, :longitude]
+  end
+
+  ##
+  # Represents the global properties of a name search text file
+  #
+  class NameSearchProperties < DataStruct
+    PROPERTIES = [
+      :comment, :datum, :latlng, :utm, :utm_zone, :hemisphere
+    ]
+
+    include Shared
+    include Shared::DatumSetter
+
+    def initialize(*args, **kwargs)
+      update(
+        comment: "",
+        datum: "WGS 84",
+        latlng: true,
+        utm: false,
+        utm_zone: nil,
+        hemisphere: nil
+      )
+
+      super
+    end
+  end
+
+  ##
+  # A thin layer above +File+ that handles reading and writing of names to name
+  # search text files
+  #
+  class NameSearchTextFile < FileWrapperBase
+    ##
+    # Writes an enumerable of {Rozi::Name} objects to the file
+    #
+    # @param [Enumerable] enumerable
+    # @return [nil]
+    #
+    def write(enumerable)
+      enumerable.each { |name|
+        write_name name
+      }
+
+      nil
+    end
+
+    ##
+    # Writes a {Rozi::Name} to the file
+    #
+    # @note If no properties have been written to the file before this method is
+    #   called, a default set of properties will be automatically written to the
+    #   file first
+    # @param [Rozi::Name] name
+    # @return [nil]
+    #
+    def write_name(name)
+      ensure_properties
+
+      @file.write serialize_name(name)
+      @file.write "\n"
+
+      nil
+    end
+
+    ##
+    # Writes name search properties to the file
+    #
+    # The file must be empty when this method is called!
+    #
+    # @raise [RuntimeError] if the file isn't empty
+    # @param [NameSearchProperties] properties
+    # @return [nil]
+    #
+    def write_properties(properties)
+      if @file.size > 0
+        raise "Can't write file properties, file is not empty"
+      end
+
+      @file.write serialize_properties(properties)
+      @file.write "\n"
+
+      nil
+    end
+
+    private
+
+    ##
+    # Ensures that properties have been written to the file
+    #
+    def ensure_properties
+      return if @properties_written
+
+      @properties_written = true
+
+      if @file.size == 0
+        write_properties NameSearchProperties.new
+      end
+    end
+
+    def serialize_name(name)
+      if not name.name or not name.latitude or not name.longitude
+        fail ArgumentError, "name, latitude and longitude must be set!"
+      end
+
+      feature_code = name.feature_code || ""
+
+      if name.name.include?(",") or feature_code.include?(",")
+        fail ArgumentError, "Text cannot contain commas"
+      end
+
+      "%s,%s,%s,%s,%s" % [
+        name.name, name.feature_code, name.zone,
+        name.latitude.round(6), name.longitude.round(6)
+      ]
+    end
+
+    def serialize_properties(properties)
+      out = ""
+
+      if properties.comment
+        properties.comment.each_line { |line|
+          out << ";#{line.chomp}\n"
+        }
+      end
+
+      out << "#1,"
+
+      if properties.utm
+        out << "UTM,#{properties.utm_zone}"
+
+        if properties.hemisphere
+          out << ",#{properties.hemisphere}"
+        end
+      else
+        out << ","
+      end
+
+      out << "\n#2,#{properties.datum}"
+
+      return out
+    end
+  end
+end

data/lib/rozi/{ozi_functions.rb → shared.rb}

@@ -1,24 +1,30 @@
 
 module Rozi
-
   ##
-  # Contains general functions for working with Ozi Explorer file formats.
+  # Contains general functions for working with Ozi Explorer file formats
   #
-  module OziFunctions
+  module Shared
     ##
-    # Escapes commas so the text can be used in Ozi file formats.
+    # Escapes commas so the text can be used in Ozi file formats
     #
     # @param [String] text
     # @return [String]
     #
     def escape_text(text)
-      text.gsub(/,/, 209.chr.encode("UTF-8", "ISO-8859-1"))
+      text.gsub(/,/, "Ñ")
     end
 
     ##
-    # Converts the input to an RGB color represented by an integer.
+    # Undoes the effect of {Rozi::Shared#escape_text}
     #
-    # @param [String, Integer] color Can be a RRGGBB hex string or an integer.
+    def unescape_text(text)
+      text.gsub(/Ñ/, ",")
+    end
+
+    ##
+    # Converts the input to an RGB color represented by an integer
+    #
+    # @param [String, Integer] color Can be a RRGGBB hex string or an integer
     # @return [Integer]
     #
     # @example
@@ -36,13 +42,34 @@ module Rozi
     end
 
     ##
-    # Checks if +datum+ is a valid datum according to Ozi Explorer.
+    # Checks if +datum+ is a valid datum according to Ozi Explorer
     #
     # @return [Boolean] true if +datum+ is valid
     #
     def datum_valid?(datum)
       Rozi::DATUMS.include? datum
     end
-  end
 
+    ##
+    # All data structures with a datum property should include this module
+    #
+    module DatumSetter
+      include Shared
+
+      ##
+      # Sets the datum property
+      #
+      # @param [String] datum
+      # @raise [ArgumentError] on invalid datum
+      # @return [void]
+      #
+      def datum=(datum)
+        if not datum_valid?(datum)
+          fail ArgumentError, "Invalid datum: #{datum}"
+        end
+
+        super datum
+      end
+    end
+  end
 end

data/lib/rozi/tracks.rb

@@ -0,0 +1,170 @@
+
+require "rozi/file_wrapper_base"
+require "rozi/shared"
+
+module Rozi
+  ##
+  # Writes an enumerable of track points to a file
+  #
+  # All keyword arguments are used as track properties.
+  #
+  # @param [Enumerable] enumerable
+  # @param [String] file_path
+  #
+  def write_track(enumerable, file_path, **properties)
+    TrackFile.open(file_path, "w") { |track_file|
+      track_file.write_track_properties TrackProperties.new(**properties)
+      track_file.write enumerable
+    }
+  end
+
+  ##
+  # Represents a point in an Ozi Explorer track
+  #
+  class TrackPoint < DataStruct
+    PROPERTIES = [
+      :latitude, :longitude, :break, :altitude,
+      :date, :date_string, :time_string
+    ]
+
+    def initialize(*args, **kwargs)
+      update(
+        break: false,
+        altitude: -777,
+        date: 0,
+        date_string: "",
+        time_string: ""
+      )
+
+      super
+    end
+
+    def break
+      super == 1
+    end
+
+    def break=(brk)
+      super(brk ? 1 : 0)
+    end
+  end
+
+  ##
+  # Represents the track properties at the top of an Ozi Explorer track file
+  #
+  class TrackProperties < DataStruct
+    PROPERTIES = [
+      :datum, :line_width, :color, :description, :skip_value,
+      :type, :fill_style, :fill_color
+    ]
+
+    include Shared
+    include Shared::DatumSetter
+
+    def initialize(*args, **kwargs)
+      update(
+        datum: "WGS 84",
+        line_width: 2,
+        color: 255,
+        description: "",
+        skip_value: 1,
+        type: 0,
+        fill_style: 0,
+        fill_color: 0
+      )
+
+      super
+    end
+
+    def color=(color)
+      super interpret_color(color)
+    end
+  end
+
+  ##
+  # A thin wrapper around a file object made for reading and writing tracks
+  #
+  class TrackFile < FileWrapperBase
+    include Shared
+
+    ##
+    # Writes track properties to the file
+    #
+    # The file must be empty when this method is called!
+    #
+    # @raise [RuntimeError] if the file isn't empty
+    # @param [TrackProperties] properties
+    # @return [nil]
+    #
+    def write_track_properties(properties)
+      if @file.size > 0
+        raise "Can't write file properties, file is not empty"
+      end
+
+      @file.write serialize_track_properties(properties)
+
+      nil
+    end
+
+    ##
+    # Writes a track point to the file
+    #
+    # @param [TrackPoint] track_point
+    # @return [nil]
+    #
+    def write_track_point(track_point)
+      ensure_track_properties
+
+      @file.write serialize_track_point(track_point)
+      @file.write "\n"
+
+      nil
+    end
+
+    ##
+    # Writes an enumerable of track points to the file
+    #
+    # @param [Enumerable] enumerable
+    #
+    def write(enumerable)
+      enumerable.each { |track_point|
+        self.write_track_point(track_point)
+      }
+
+      nil
+    end
+
+    private
+
+    ##
+    # Ensures that track properties has been written to the file
+    #
+    def ensure_track_properties
+      return if @properties_written
+
+      @properties_written = true
+
+      if @file.size == 0
+        write_track_properties TrackProperties.new
+      end
+    end
+
+    def serialize_track_properties(track_properties)
+      props = track_properties.to_a
+      props.delete_at(0)   # The datum isn't a part of this list
+      props.map! { |item| item.is_a?(String) ? escape_text(item) : item }
+
+      <<-TEXT.gsub(/^[ ]{8}/, "") % props
+        OziExplorer Track Point File Version 2.1
+        #{track_properties.datum}
+        Altitude is in Feet
+        Reserved 3
+        0,%d,%d,%s,%d,%d,%d,%d
+        0
+      TEXT
+    end
+
+    def serialize_track_point(track_point)
+      "  %.6f,%.6f,%d,%.1f,%.7f,%s,%s" % track_point.to_a
+    end
+  end
+end

data/lib/rozi/version.rb

@@ -1,4 +1,4 @@
 
 module Rozi
-  VERSION = "0.0.7"
+  VERSION = "0.1.3"
 end

data/lib/rozi/waypoints.rb

@@ -0,0 +1,315 @@
+
+require "rozi/file_wrapper_base"
+require "rozi/shared"
+
+module Rozi
+  ##
+  # Writes an enumerable of waypoints to a file
+  #
+  # @param [Enumerable] waypoints
+  # @param [String] file_path
+  # @param [Hash] properties Any extra keyword arguments are processed as
+  #   waypoint file properties
+  #
+  def self.write_waypoints(waypoints, file_path, **properties)
+    wpt_file = WaypointFile.open(file_path, "w")
+
+    wpt_file.write_properties(WaypointFileProperties.new(**properties))
+    wpt_file.write waypoints
+
+    wpt_file.close
+
+    nil
+  end
+
+  ##
+  # Represents a waypoint in Ozi Explorer
+  #
+  class Waypoint < DataStruct
+    PROPERTIES = [
+      :number, :name, :latitude, :longitude, :date, :symbol, :display_format,
+      :fg_color, :bg_color, :description, :pointer_direction, :altitude,
+      :font_size, :font_style, :symbol_size
+    ]
+
+    DISPLAY_FORMATS = {
+      :number_only => 0,
+      :name_only => 1,
+      :number_and_name => 2,
+      :name_with_dot => 3,
+      :name_with_symbol => 4,
+      :symbol_only => 5,
+      :comment_with_symbol => 6,
+      :man_overboard => 7,
+      :marker => 8
+    }
+
+    include Shared
+
+    def initialize(*args, **kwargs)
+      update(
+        number: -1,
+        name: "",
+        latitude: 0.0,
+        longitude: 0.0,
+        date: nil,
+        symbol: 0,
+        display_format: :name_with_dot,
+        fg_color: 0,
+        bg_color: 65535,
+        description: "",
+        pointer_direction: 0,
+        altitude: -777,
+        font_size: 6,
+        font_style: 0,
+        symbol_size: 17
+      )
+
+      super
+    end
+
+    ##
+    # Returns the value of the display format property
+    #
+    # @param [Boolean] raw If true, returns the raw value with no processing
+    #
+    def display_format(raw: false)
+      if raw
+        super
+      else
+        DISPLAY_FORMATS.invert[super]
+      end
+    end
+
+    def display_format=(display_format)
+      if display_format.is_a? Symbol
+        @data[:display_format] = DISPLAY_FORMATS[display_format]
+      else
+        @data[:display_format] = display_format
+      end
+    end
+
+    ##
+    # Sets the foreground color
+    #
+    def fg_color=(color)
+      @data[:fg_color] = interpret_color(color)
+    end
+
+    ##
+    # Sets the background color
+    #
+    def bg_color=(color)
+      @data[:bg_color] = interpret_color(color)
+    end
+  end
+
+  ##
+  # This class represents the waypoint file properties contained in the top 4
+  # lines of a waypoint file
+  #
+  class WaypointFileProperties < DataStruct
+    include Shared::DatumSetter
+
+    PROPERTIES = [:datum, :version]
+
+    def initialize(*args, **kwargs)
+      update(
+        datum: "WGS 84",
+        version: "1.1"
+      )
+
+      super
+    end
+  end
+
+  ##
+  # A thin layer above +File+ that handles reading and writing of waypoints to
+  # files
+  #
+  class WaypointFile < FileWrapperBase
+    include Shared
+
+    #@group Writing methods
+
+    ##
+    # Writes waypoints to the file
+    #
+    # @param [Enumerator<Waypoint>] waypoints
+    # @return [nil]
+    #
+    def write(waypoints)
+      waypoints.each { |wpt|
+        write_waypoint wpt
+      }
+
+      nil
+    end
+
+    ##
+    # Writes waypoint file properties to the file
+    #
+    # The file must be empty when this method is called!
+    #
+    # @raise [RuntimeError] if the file isn't empty
+    # @param [WaypointFileProperties] properties
+    # @return [nil]
+    #
+    def write_properties(properties)
+      if @file.size > 0
+        raise "Can't write file properties, file is not empty"
+      end
+
+      @file.write serialize_waypoint_file_properties(properties)
+      @file.write "\n"
+
+      nil
+    end
+
+    ##
+    # Writes a waypoint to the file
+    #
+    # @param [Waypoint] waypoint
+    # @return [nil]
+    #
+    def write_waypoint(waypoint)
+      ensure_file_properties
+
+      @file.write serialize_waypoint(waypoint)
+      @file.write "\n"
+
+      nil
+    end
+
+    #@group Reading methods
+
+    ##
+    # Reads and yields all waypoints
+    #
+    def each_waypoint
+      return to_enum(:each_waypoint) unless block_given?
+
+      @file.rewind
+
+      loop { yield read_waypoint }
+    rescue EOFError
+      return nil
+    end
+
+    ##
+    # Reads the waypoint file properties
+    #
+    # @raise [RuntimeError] If the file position isn't 0
+    # @return [WaypointFileProperties]
+    #
+    def read_properties
+      if @file.pos != 0
+        raise "File position must be 0 to read properties"
+      end
+
+      text = ""
+
+      4.times { text << @file.readline }
+
+      parse_waypoint_file_properties text
+    end
+
+    ##
+    # Reads the next waypoint
+    #
+    # @raise [EOFError] When EOF is reached
+    # @return [Waypoint]
+    #
+    def read_waypoint
+      if @file.pos == 0
+        read_properties
+      end
+
+      parse_waypoint @file.readline
+    end
+
+    #@endgroup
+
+    private
+
+    def parse_waypoint(text)
+      map = {
+        0  => {symbol: :number,            cast: method(:Integer)},
+        1  => {symbol: :name,              cast: method(:String)},
+        2  => {symbol: :latitude,          cast: method(:Float)},
+        3  => {symbol: :longitude,         cast: method(:Float)},
+        4  => {symbol: :date,              cast: method(:Float)},
+        5  => {symbol: :symbol,            cast: method(:Integer)},
+        7  => {symbol: :display_format,    cast: method(:Integer)},
+        8  => {symbol: :fg_color,          cast: method(:Integer)},
+        9  => {symbol: :bg_color,          cast: method(:Integer)},
+        10 => {symbol: :description,       cast: method(:String)},
+        11 => {symbol: :pointer_direction, cast: method(:Integer)},
+        14 => {symbol: :altitude,          cast: method(:Integer)},
+        15 => {symbol: :font_size,         cast: method(:Integer)},
+        16 => {symbol: :font_style,        cast: method(:Integer)},
+        17 => {symbol: :symbol_size,       cast: method(:Integer)},
+      }
+
+      text = text.strip
+      fields = text.split(",").map { |x| x.strip }
+
+      waypoint = Waypoint.new
+
+      map.each_pair { |index, data|
+        value = fields[index]
+
+        next if value.empty?
+
+        value = data[:cast].call(value)
+
+        if value.is_a? String
+          value = unescape_text(value)
+        end
+
+        waypoint.set(data[:symbol], value)
+      }
+
+      waypoint
+    end
+
+    def parse_waypoint_file_properties(text)
+      lines = text.lines
+
+      version = lines[0].strip[-3..-1]
+      datum = lines[1].strip
+
+      WaypointFileProperties.new(datum, version)
+    end
+
+    def serialize_waypoint(waypoint)
+      array = waypoint.to_a
+      array.map! { |item| item.is_a?(String) ? escape_text(item) : item }
+      array.map! { |item| item.nil? ? "" : item }
+      array.map! { |item| item.is_a?(Float) ? item.round(6) : item }
+
+      "%d,%s,%f,%f,%s,%d,1,%d,%d,%d,%s,%d,,,%d,%d,%d,%d" % array
+    end
+
+    def serialize_waypoint_file_properties(properties)
+      <<-TEXT.gsub(/^[ ]{8}/, "")
+        OziExplorer Waypoint File Version #{properties.version}
+        #{properties.datum}
+        Reserved 2
+      TEXT
+    end
+
+    ##
+    # Ensures that waypoint file properties has been written to the file
+    #
+    def ensure_file_properties
+      return if @properties_written
+
+      @properties_written = true
+
+      if @file.size == 0
+        write_properties WaypointFileProperties.new
+      end
+    end
+  end
+end