schleyfox-ruby_kml 0.1.1

data/lib/kml/lat_lon_box.rb

@@ -0,0 +1,36 @@
+module KML #:nodoc:
+  # Specifies where the top, bottom, right, and left sides of a bounding box for the ground overlay are aligned. Values for 
+  # +north+, +south+, +east+, and +west+ are required.
+  #
+  # * +north+ (required) Specifies the latitude of the north edge of the bounding box, in decimal degrees from 0 to ±90.
+  # * +south+ (required) Specifies the latitude of the south edge of the bounding box, in decimal degrees from 0 to ±90.
+  # * +east+ (required) Specifies the longitude of the east edge of the bounding box, in decimal degrees from 0 to ±180. 
+  #   (For overlays that overlap the meridian of 180° longitude, values can extend beyond that range.)
+  # * +west+ (required) Specifies the longitude of the west edge of the bounding box, in decimal degrees from 0 to ±180. 
+  #   (For overlays that overlap the meridian of 180° longitude, values can extend beyond that range.)
+  # * +rotation+ (optional) specifies a rotation of the overlay about its center, in degrees. Values can be ±180. The 
+  #   default is 0 (north). Rotations are specified in a clockwise direction.
+  
+  class LatLonBox < KML::Object
+    attr_accessor :north
+    attr_accessor :south
+    attr_accessor :east
+    attr_accessor :west
+    attr_accessor :rotation
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      raise InvalidKMLError, "LatLonBox.north is required" if north.nil?
+      raise InvalidKMLError, "LatLonBox.south is required" if south.nil?
+      raise InvalidKMLError, "LatLonBox.east is required" if east.nil?
+      raise InvalidKMLError, "LatLonBox.west is required" if west.nil?
+      
+      xm.LatLonBox {
+        xm.north(north)
+        xm.south(south)
+        xm.east(east)
+        xm.west(west)
+        xm.rotation unless rotation.nil?
+      }
+    end
+  end
+end

data/lib/kml/line_string.rb

@@ -0,0 +1,40 @@
+module KML #:nodoc:
+  # Defines a connected set of line segments. Use LineStyle to specify the color, color mode, and width of the line. 
+  # When a LineString is extruded, the line is extended to the ground, forming a polygon that looks somewhat like a wall. 
+  # For extruded LineStrings, the line itself uses the current LineStyle, and the extrusion uses the current PolyStyle. 
+  # See the <a href="http://earth.google.com/kml/kml_tut.html">KML Tutorial</a> for examples of LineStrings (or paths).
+  class LineString < Geometry
+    
+    # Two or more coordinate tuples, each consisting of floating point values for longitude, latitude, and altitude. 
+    # The altitude component is optional.
+    def coordinates
+      @coordinates
+    end
+    
+    # Set the coordinates. When specifying as a String, insert a space or linebreak between tuples.  Do not include spaces 
+    # within a tuple.
+    def coordinates=(c)
+      case c
+      when String
+        @coordinates = c.split(/\s+/).collect { |coord| coord.split(',') }
+      when Array
+        c.each do |coord_array|
+          unless coord_array.is_a?(Array)
+            raise ArgumentError, "If set with an array, coordinates must be specified as an array of arrays"
+          end
+        end
+        @coordinates = c
+      else
+        raise ArgumentError, "Coordinates must either be a String or an Array of Arrays"
+      end
+    end
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      raise ArgumentError, "Coordinates required" if coordinates.nil?
+      xm.LineString {
+        super
+        xm.coordinates(coordinates.collect { |c| c.join(',') }.join(" "))
+      }
+    end
+  end
+end

data/lib/kml/line_style.rb

@@ -0,0 +1,15 @@
+module KML
+  # Specifies the drawing style (color, color mode, and line width) for all line geometry. Line geometry includes the 
+  # outlines of outlined polygons and the extruded "tether" of Placemark icons (if extrusion is enabled).
+  class LineStyle < ColorStyle
+    # Width of the line, in pixels.
+    attr_accessor :width
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.LineStyle {
+        super
+        xm.width(width) unless width.nil?
+      }
+    end
+  end
+end

data/lib/kml/linear_ring.rb

@@ -0,0 +1,49 @@
+# Source code for producing a LinearRing element:
+#
+# <LinearRing id="ID">
+#   <!-- specific to LinearRing -->
+#   <extrude>0</extrude>                       <!-- boolean -->
+#   <tessellate>0</tessellate>                 <!-- boolean -->
+#   <altitudeMode>clampToGround</altitudeMode> 
+#     <!-- kml:altitudeModeEnum: clampToGround, relativeToGround, or absolute -->
+#   <coordinates>...</coordinates>             <!-- lon,lat[,alt] tuples --> 
+# </LinearRing>
+
+module KML #:nodoc:
+  # Defines a closed line string, typically the outer boundary of a Polygon. Optionally, a LinearRing can also 
+  # be used as the inner boundary of a Polygon to create holes in the Polygon. A Polygon can contain multiple 
+  # LinearRing instances used as inner boundaries.
+  class LinearRing < Geometry
+    # Four or more tuples, each consisting of floating point values for longitude, latitude, and altitude. 
+    # The altitude component is optional. Do not include spaces within a tuple. The last coordinate must be 
+    # the same as the first coordinate. Coordinates are expressed in decimal degrees only.
+    def coordinates
+      @coordinates
+    end
+    
+    # Set the coordinates
+    def coordinates=(c)
+      case c
+      when String
+        @coordinates = c.split(/\s+/).collect { |coord| coord.split(',') }
+      when Array
+        c.each do |coord_array|
+          unless coord_array.is_a?(Array)
+            raise ArgumentError, "If set with an array, coordinates must be specified as an array of arrays"
+          end
+        end
+        @coordinates = c
+      else
+        raise ArgumentError, "Coordinates must either be a String or an Array of Arrays"
+      end
+    end
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      raise ArgumentError, "Coordinates required" if coordinates.nil?
+      xm.LinearRing {
+        super
+        xm.coordinates(coordinates.collect { |c| c.join(',') }.join(" "))
+      }
+    end
+  end
+end

data/lib/kml/link.rb

@@ -0,0 +1,51 @@
+module KML #:nodoc:
+  # Link specifies the location of any of the following:
+  #
+  # * KML files fetched by network links
+  # * Image files used by icons in icon styles, ground overlays, and screen overlays
+  # * Model files used in the Model element
+  # 
+  # The file is conditionally loaded and refreshed, depending on the refresh parameters supplied here. 
+  # Two different sets of refresh parameters can be specified: one set is based on time (+refresh_mode+ and 
+  # +refresh_interval+) and one is based on the current "camera" view (+view_refresh_mode+ and 
+  # +view_refresh_time+). In addition, Link specifies whether to scale the bounding box parameters that 
+  # are sent to the server (+view_bound_scale+ and provides a set of optional viewing parameters that can 
+  # be sent to the server (+view_format+) as well as a set of optional parameters containing version and 
+  # language information.
+  # 
+  # When a file is fetched, the URL that is sent to the server is composed of three pieces of information:
+  # 
+  # * the +href+ (Hypertext Reference) that specifies the file to load.
+  # * an arbitrary format string that is created from (a) parameters that you specify in +view_format+ or 
+  #   (b) bounding box parameters (this is the default and is used if no +view_format+ is specified).
+  # * a second format string that is specified in +http_query+.
+  # 
+  # If the file specified in +href+ is a local file, +view_format+ and +http_query+ are not used.
+  class Link < KML::Object
+    attr_accessor :href
+    attr_accessor :refresh_mode
+    attr_accessor :refresh_interval
+    attr_accessor :view_refresh_mode
+    attr_accessor :view_refresh_time
+    attr_accessor :view_bound_scale
+    attr_accessor :view_format
+    attr_accessor :http_query
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      raise InvalidKMLError, "Link.href must be specified" if href.nil?
+      xm.Link {
+        self.elements.each do |a|
+          xm.__send__(a, self.__send__(a)) unless self.__send__(a).nil?
+        end
+      }
+    end
+    
+    protected
+    def elements
+      [
+        :href, :refresh_mode, :refresh_interval, :view_refresh_mode, :view_refresh_time, 
+        :view_bound_scale, :view_format, :http_query
+      ]
+    end
+  end
+end

data/lib/kml/look_at.rb

@@ -0,0 +1,21 @@
+# <LookAt id="ID">
+#   <longitude></longitude>      <!-- kml:angle180 -->
+#   <latitude></latitude>        <!-- kml:angle90 -->
+#   <altitude>0</altitude>       <!-- double --> 
+#   <range></range>              <!-- double -->
+#   <tilt>0</tilt>               <!-- float -->
+#   <heading>0</heading>         <!-- float -->
+#   <altitudeMode>clampToGround</altitudeMode> 
+#     <!--kml:altitudeModeEnum:clampToGround, relativeToGround, absolute -->
+# </LookAt>
+module KML
+  class LookAt < KML::Object
+    attr_accessor :longitude
+    attr_accessor :latitude
+    attr_accessor :altitude
+    attr_accessor :range
+    attr_accessor :tilt
+    attr_accessor :heading
+    attr_accessor :altitude_mode
+  end
+end

data/lib/kml/model.rb

@@ -0,0 +1,4 @@
+module KML
+  class Model < Geometry
+  end
+end

data/lib/kml/multi_geometry.rb

@@ -0,0 +1,5 @@
+module KML
+  class MultiGeometry < Geometry
+    
+  end
+end

data/lib/kml/object.rb

@@ -0,0 +1,29 @@
+module KML #:nodoc:
+  # Base class for all KML objects
+  class Object
+    # The KML object ID
+    attr_accessor :id
+    
+    # Initialize the object, optionally passing a Hash of attributes to set.
+    def initialize(attributes=nil)
+      if attributes
+        case attributes
+        when Hash
+          attributes.each do |name, value|
+            self.__send__("#{name}=".to_sym, value)
+          end
+        else
+          raise ArgumentError, "Attributes must be specified as a Hash"
+        end
+      end
+    end
+  end
+end
+
+require 'kml/feature'
+require 'kml/geometry'
+require 'kml/color_style'
+require 'kml/style_selector'
+require 'kml/link'
+require 'kml/icon'
+require 'kml/lat_lon_box'

data/lib/kml/overlay.rb

@@ -0,0 +1,20 @@
+module KML
+  # Overlay is the base type for image overlays drawn on the planet surface or on the screen. +icon+ specifies the 
+  # image to use and can be configured to reload images based on a timer or by camera changes. This element also 
+  # includes specifications for stacking order of multiple overlays and for adding color and transparency values to 
+  # the base image.
+  class Overlay < Feature
+    attr_accessor :color
+    attr_accessor :draw_order
+    attr_accessor :icon
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      super
+      xm.color(color) unless color.nil?
+      xm.drawOrder(drawOrder) unless draw_order.nil?
+      icon.render(xm) unless icon.nil?
+    end
+  end
+end
+
+require 'kml/ground_overlay'

data/lib/kml/placemark.rb

@@ -0,0 +1,36 @@
+# Basic XML Structure:
+#
+#   <Placemark id="ID">
+#     <!-- inherited from Feature element -->
+#     <name>...</name>                      <!-- string -->
+#     <visibility>1</visibility>            <!-- boolean -->
+#     <open>1</open>                        <!-- boolean -->
+#     <address>...</address>                <!-- string -->
+#     <AddressDetails xmlns="urn:oasis:names:tc:ciq:xsdschema:xAL:2.0">...
+#         </AddressDetails>                 <!-- string -->
+#     <phoneNumber>...</phoneNumber>        <!-- string -->
+#     <Snippet maxLines="2">...</Snippet>   <!-- string -->
+#     <description>...</description>        <!-- string -->
+#     <LookAt>...</LookAt>
+#     <TimePrimitive>...</TimePrimitive>
+#     <styleUrl>...</styleUrl>              <!-- anyURI -->
+#     <StyleSelector>...</StyleSelector>
+#     <Region>...</Region>
+#     <Metadata>...</Metadata>
+#   
+#     <!-- specific to Placemark element -->
+#     <Geometry>...</Geometry>
+#   </Placemark>
+
+module KML
+  class Placemark < Feature
+    attr_accessor :geometry
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.Placemark {
+        super
+        geometry.render(xm) unless geometry.nil?
+      }
+    end
+  end
+end

data/lib/kml/point.rb

@@ -0,0 +1,47 @@
+# <Point id="ID">
+#   <!-- specific to Point -->
+#   <extrude>0</extrude>                   <!-- boolean -->
+#   <tessellate>0</tessellate>             <!-- boolean -->
+#   <altitudeMode>clampToGround</altitudeMode> 
+#     <!-- kml:altitudeModeEnum: clampToGround, relativeToGround, or absolute -->
+#   <coordinates>...</coordinates>         <!-- lon,lat[,alt] -->
+# </Point>
+module KML
+  class Point < Geometry
+    
+    # A single tuple consisting of floating point values for longitude, latitude, and altitude (in that order). 
+    # Longitude and latitude values are in degrees, where:
+    #
+    # * longitude >= -180 and <= 180
+    # * latitude >= -90 and <= 90
+    # * altitude values (optional) are in meters above sea level
+    def coordinates
+      @coordinates
+    end
+    
+    # Set the coordinates
+    def coordinates=(c)
+      case c
+      when String
+        @coordinates = c.split(',')
+        unless @coordinates.length == 2 || @coordinates.length == 3
+          raise "Coordinates string may only have 2 parts (indicating lat and long) or 3 parts (lat, long and altitude)"
+        end
+      when Array
+        @coordinates = c
+      when Hash
+        @coordinates = [:lng, :lat, :alt].collect {|attr| c[attr]}.compact
+      else
+        raise ArgumentError, "Coordinates must be either a String, Hash or an Array"
+      end
+    end
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.Point {
+        super
+        xm.coordinates(coordinates.join(","))
+      }
+    end
+    
+  end
+end

data/lib/kml/poly_style.rb

@@ -0,0 +1,16 @@
+module KML
+  # Specifies the drawing style for all polygons, including polygon extrusions (which look like the walls of buildings) 
+  # and line extrusions (which look like solid fences).
+  class PolyStyle < ColorStyle
+    attr_accessor :fill
+    attr_accessor :outline
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.PolyStyle {
+        super
+        xm.fill(fill) unless fill.nil?
+        xm.outline(outline) unless outline.nil?
+      }
+    end
+  end
+end

data/lib/kml/polygon.rb

@@ -0,0 +1,44 @@
+# Source file which generates a Polygon element.
+#
+# <Polygon id="ID">
+#   <!-- specific to Polygon -->
+#   <extrude>0</extrude>                       <!-- boolean -->
+#   <tessellate>0</tessellate>                 <!-- boolean -->
+#   <altitudeMode>clampToGround</altitudeMode> 
+#     <!-- kml:altitudeModeEnum: clampToGround, relativeToGround, or absolute -->
+#   <outerBoundaryIs>
+#     <LinearRing>
+#       <coordinates>...</coordinates>         <!-- lon,lat[,alt] -->
+#     </LinearRing>
+#   </outerBoundaryIs>
+#   <innerBoundaryIs>
+#     <LinearRing>
+#       <coordinates>...</coordinates>         <!-- lon,lat[,alt] -->
+#     </LinearRing>
+#   </innerBoundaryIs>
+# </Polygon>
+
+module KML #:nodoc:
+  # A Polygon is defined by an outer boundary and 0 or more inner boundaries. The boundaries, in turn, are defined 
+  # by LinearRings. When a Polygon is extruded, its boundaries are connected to the ground to form additional polygons, 
+  # which gives the appearance of a building. When a Polygon is extruded, each point is extruded individually. 
+  # Extruded Polygons use PolyStyle for their color, color mode, and fill.
+  class Polygon < Geometry
+    attr_accessor :inner_boundary_is
+    attr_accessor :outer_boundary_is
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.Polygon {
+        super
+        xm.outerBoundaryIs {
+          outer_boundary_is.render(xm)
+        }
+        unless inner_boundary_is.nil?
+          xm.innerBoundaryIs {
+            inner_boundary_is.render(xm)
+          }
+        end
+      }
+    end
+  end
+end

data/lib/kml/snippet.rb

@@ -0,0 +1,25 @@
+module KML #:nodoc:
+  # A short description of a feature. In Google Earth, this description is displayed in the Places panel 
+  # under the name of the feature. If a Snippet is not supplied, the first two lines of the description are 
+  # used. In Google Earth, if a Placemark contains both a description and a Snippet, the Snippet appears 
+  # beneath the Placemark in the Places panel, and the description appears in the Placemark's description 
+  # balloon. This object does not support HTML markup.
+  class Snippet
+    # The maximum number of lines to display.
+    attr_accessor :max_lines
+    
+    # The text that is displayed (HTML not supported)
+    attr_accessor :text
+    
+    # Initialize the snippet with the given text and optionally with the given max_lines value.
+    def initialize(text, max_lines=nil)
+      @text = text
+      @max_lines = max_lines
+    end
+    
+    # The maximum number of lines to display. Default is 2
+    def max_lines
+      @max_lines ||= 2
+    end
+  end
+end

data/lib/kml/style.rb

@@ -0,0 +1,23 @@
+module KML
+  # A Style defines an addressable style group that can be referenced by StyleMaps and Features. Styles affect 
+  # how Geometry is presented in the 3D viewer and how Features appear in the Places panel of the List view. 
+  # Shared styles are collected in a Document and must have an id defined for them so that they can be referenced 
+  # by the individual Features that use them.
+  class Style < StyleSelector
+    attr_accessor :icon_style
+    attr_accessor :label_style
+    attr_accessor :line_style
+    attr_accessor :poly_style
+    attr_accessor :balloon_style
+    attr_accessor :list_style
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.Style(:id => id) {
+        %w(Icon Label Line Poly Balloon List).each do |name| 
+          field = "#{name.downcase}_style".to_sym
+          self.__send__(field).render(xm) unless self.__send__(field).nil?
+        end
+      }
+    end
+  end
+end

data/lib/kml/style_map.rb

@@ -0,0 +1,39 @@
+# Source file that defines a StyleMap element
+#
+# <StyleMap id="ID">
+#   <!-- extends StyleSelector -->
+#   <!-- elements specific to StyleMap -->
+#   <Pair id="ID">
+#     <key>normal</key>              <!-- kml:styleStateEnum:  normal or highlight
+#     <styleUrl>...</styleUrl>       <!-- anyURI -->
+#   </Pair>
+# </StyeMap>
+
+module KML #:nodoc:
+  # A StyleMap maps between two different icon styles. Typically a StyleMap element is used to provide 
+  # separate normal and highlighted styles for a placemark, so that the highlighted version appears when 
+  # the user mouses over the icon in Google Earth.
+  class StyleMap < StyleSelector
+    # Key/styleUrl pairs
+    attr_accessor :pairs
+    
+    # Get the pairs Hash. Each key/value pair  maps a mode (normal or highlight) to the predefined style URL. 
+    # Each pair contains a key and a value which references the style. For referenced style elements that 
+    # are local to the KML document, a simple # referencing is used. For styles that are contained in 
+    # external files, use a full URL along with # referencing.
+    def pairs
+      @pairs ||= {}
+    end
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.StyleMap(:id => id) {
+        pairs.each do |key, value|
+          xm.Pair {
+            xm.key(key)
+            xm.styleUrl(value)
+          }
+        end
+      }
+    end
+  end
+end

data/lib/kml/style_selector.rb

@@ -0,0 +1,7 @@
+module KML
+  class StyleSelector < KML::Object
+  end
+end
+
+require 'kml/style'
+require 'kml/style_map'

data/lib/kml/version.rb

@@ -0,0 +1,9 @@
+module KML#:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/lib/kml.rb

@@ -0,0 +1,7 @@
+require 'rubygems'
+require 'builder'
+
+require 'kml_file'
+
+class InvalidKMLError < StandardError
+end

data/lib/kml_file.rb

@@ -0,0 +1,28 @@
+# The KMLFile class is the top level class for constructing KML files. To create a new KML file
+# create a KMLFile instance and add KML objects to its objects. For example:
+#
+#   f = KMLFile.new
+#   f.objects << Placemark.new(
+#     :name => 'Simple placemark', 
+#     :description => 'Attached to the ground. Intelligently places itself at the height of the underlying terrain.',
+#     :geometry => Point.new(:coordinates=>'-122.0822035425683,37.42228990140251,0')
+#   )
+#   puts f.render
+class KMLFile
+  attr_accessor :objects
+
+  # The objects in the KML file
+  def objects
+    @objects ||= []
+  end
+
+  # Render the KML file.
+  def render(xm=Builder::XmlMarkup.new(:indent => 2))
+    xm.instruct!
+    xm.kml(:xmlns => 'http://earth.google.com/kml/2.1'){
+      objects.each { |o| o.render(xm) }
+    }
+  end
+end
+
+require 'kml/object'

data/test/kml/point_test.rb

@@ -0,0 +1,10 @@
+require "#{File.dirname(__FILE__)}/../test_helper"
+
+class KML::PointTest < Test::Unit::TestCase
+  include KML
+
+  def test_allows_coordinates_to_be_specified_with_a_hash
+    point = Point.new(:coordinates => {:lat => 10, :lng => 20, :alt => 30})
+    assert_equal [20, 10, 30], point.coordinates
+  end
+end