xaviershay-ruby_kml 0.1

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_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

data/test/kml_file_test.rb

@@ -0,0 +1,220 @@
+require "#{File.dirname(__FILE__)}/test_helper"
+
+class KMLFileTest < Test::Unit::TestCase
+  include KML
+  
+  def test_placemark
+    kml = KMLFile.new
+    kml.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')
+    )
+    write_and_show(kml, File.dirname(__FILE__) + '/simple_placemark.kml')
+  end
+  
+  def test_cdata_description
+    description = <<-DESC
+<h1>CDATA Tags are useful!</h1>
+<p><font color="red">Text is <i>more readable</i> and 
+<b>easier to write</b> when you can avoid using entity 
+references.</font></p>
+DESC
+    
+    kml = KMLFile.new
+    document = Document.new(
+      :name => 'Document with CDATA example', 
+      :snippet => Snippet.new("Document level snippet")
+    )
+    document.features << Placemark.new(
+      :name => 'CDATA example', 
+      :description => description,
+      :snippet => Snippet.new("Example of a snippet"),
+      :geometry => Point.new(:coordinates=>'-122.0822035425683,37.4228,0')
+    )
+    kml.objects << document
+    write_and_show(kml, File.dirname(__FILE__) + '/cdata_and_snippet.kml')
+  end
+  
+  def test_ground_overlays
+    kml = KMLFile.new
+    folder = Folder.new(
+      :name => 'Ground Overlays',
+      :description => 'Examples of ground overlays'
+    )
+    folder.features << GroundOverlay.new(
+      :name => 'Large-scale overlay on terrain',
+      :description => 'Overlay shows Mount Etna erupting on July 13th, 2001.',
+      :icon => Icon.new(:href => 'http://code.google.com/apis/kml/documentation/etna.jpg'),
+      :lat_lon_box => LatLonBox.new(
+        :north => 37.91904192681665,
+        :south => 37.46543388598137,
+        :east => 15.35832653742206,
+        :west => 14.60128369746704,
+        :rotation => -0.1556640799496235
+      )
+    )
+    kml.objects << folder
+    write_and_show(kml, File.dirname(__FILE__) + '/ground_overlays.kml')
+  end
+  
+  def test_paths
+    kml = KMLFile.new
+    kml.objects << Document.new(
+      :name => 'Paths',
+      :description => 'Examples of paths. Note that the tessellate tag is by default
+            set to 0. If you want to create tessellated lines, they must be authored
+            (or edited) directly in KML.',
+      :styles => [
+        Style.new(
+          :id => 'yellowLineGreenPoly',
+          :line_style => LineStyle.new(:color => '7f00ffff', :width => 4),
+          :poly_style => PolyStyle.new(:color => '7f00ff00')
+        )
+      ],
+      :features => [
+        Placemark.new(
+          :name => 'Absolute Extruded',
+          :description => 'Transparent green wall with yellow outlines',
+          :style_url => '#yellowLineGreenPoly',
+          :geometry => LineString.new(
+            :extrude => true,
+            :tessellate => true,
+            :altitude_mode => 'absolute',
+            :coordinates => '-112.2550785337791,36.07954952145647,2357
+                      -112.2549277039738,36.08117083492122,2357
+                      -112.2552505069063,36.08260761307279,2357
+                      -112.2564540158376,36.08395660588506,2357
+                      -112.2580238976449,36.08511401044813,2357
+                      -112.2595218489022,36.08584355239394,2357
+                      -112.2608216347552,36.08612634548589,2357
+                      -112.262073428656,36.08626019085147,2357
+                      -112.2633204928495,36.08621519860091,2357
+                      -112.2644963846444,36.08627897945274,2357
+                      -112.2656969554589,36.08649599090644,2357'
+          )
+        )
+      ]
+    )
+    #puts kml.render
+    write_and_show(kml, File.dirname(__FILE__) + '/paths.kml')
+  end
+  
+  def test_polygon
+    kml = KMLFile.new
+    kml.objects << Placemark.new(
+      :name => 'The Pentagon',
+      :geometry => Polygon.new(
+        :extrude => true,
+        :altitude_mode => 'relativeToGround',
+        :outer_boundary_is => LinearRing.new(
+          :coordinates => '-77.05788457660967,38.87253259892824,100 
+                      -77.05465973756702,38.87291016281703,100 
+                      -77.05315536854791,38.87053267794386,100 
+                      -77.05552622493516,38.868757801256,100 
+                      -77.05844056290393,38.86996206506943,100 
+                      -77.05788457660967,38.87253259892824,100'
+        ),
+        :inner_boundary_is => LinearRing.new(
+          :coordinates => '-77.05668055019126,38.87154239798456,100 
+                      -77.05542625960818,38.87167890344077,100 
+                      -77.05485125901024,38.87076535397792,100 
+                      -77.05577677433152,38.87008686581446,100 
+                      -77.05691162017543,38.87054446963351,100 
+                      -77.05668055019126,38.87154239798456,100'
+        )
+      )
+    )
+    
+    #puts kml.render
+    write_and_show(kml, File.dirname(__FILE__) + '/polygon.kml')
+  end
+  
+  def test_geometry_styles
+    kml = KMLFile.new
+    kml.objects << Style.new(
+      :id => "transBluePoly",
+      :line_style => LineStyle.new(
+        :width => 1.5
+      ),
+      :poly_style => PolyStyle.new(
+        :color => '7dff0000'
+      )
+    )
+    kml.objects << Placemark.new(
+      :name => 'Building 41',
+      :style_url => '#transBluePoly',
+      :geometry => Polygon.new(
+        :extrude => true,
+        :altitude_mode => 'relativeToGround',
+        :outer_boundary_is => LinearRing.new(
+          :coordinates => '-122.0857412771483,37.42227033155257,17
+                        -122.0858169768481,37.42231408832346,17
+                        -122.085852582875,37.42230337469744,17
+                        -122.0858799945639,37.42225686138789,17
+                        -122.0858860101409,37.4222311076138,17
+                        -122.0858069157288,37.42220250173855,17
+                        -122.0858379542653,37.42214027058678,17
+                        -122.0856732640519,37.42208690214408,17
+                        -122.0856022926407,37.42214885429042,17
+                        -122.0855902778436,37.422128290487,17
+                        -122.0855841672237,37.42208171967246,17
+                        -122.0854852065741,37.42210455874995,17
+                        -122.0855067264352,37.42214267949824,17
+                        -122.0854430712915,37.42212783846172,17
+                        -122.0850990714904,37.42251282407603,17
+                        -122.0856769818632,37.42281815323651,17
+                        -122.0860162273783,37.42244918858722,17
+                        -122.0857260327004,37.42229239604253,17
+                        -122.0857412771483,37.42227033155257,17'
+        )
+      )
+    )
+    
+    write_and_show(kml, File.dirname(__FILE__) + '/polygon_style.kml')
+  end
+  
+  def test_style_map
+    kml = KMLFile.new
+    kml.objects << Document.new(
+      :name => 'Highlighted Icon',
+      :description => 'Place your mouse over the icon to see it display the new icon',
+      :styles => [
+        Style.new(
+          :id => "highlightPlacemark",
+          :icon_style => IconStyle.new(
+            :icon => Icon.new(
+              :href => "http://maps.google.com/mapfiles/kml/paddle/red-stars.png"
+            )
+          )
+        ),
+        Style.new(
+          :id => "normalPlacemark",
+          :icon_style => IconStyle.new(
+            :icon => Icon.new(
+              :href => "http://maps.google.com/mapfiles/kml/paddle/wht-blank.png"
+            )
+          )
+        ),
+        StyleMap.new(
+          :id => 'exampleStyleMap',
+          :pairs => {
+            'normal' => '#normalPlacemark',
+            'highlight' => '#highlightPlacemark'
+          }
+        )
+      ],
+      :features => [
+        Placemark.new(
+          :name => 'Roll over this icon',
+          :style_url => '#exampleStyleMap',
+          :geometry => Point.new(
+            :coordinates => '-122.0856545755255,37.42243077405461,0'
+          )
+        )
+      ]
+    )
+    #puts kml.render
+    write_and_show(kml, File.dirname(__FILE__) + '/style_map.kml')
+  end
+end