schleyfox-ruby_kml 0.1.1

data/CHANGELOG

@@ -0,0 +1,2 @@
+0.1.0 - 
+* Initial release

data/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2006-2007 Anthony Eden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.textile

@@ -0,0 +1,31 @@
+Library for generating KML(Keyhole Markup Language) files in Ruby.
+Sweet if you want to place markers, overlays, and other awesome things over a google map or google earth.
+
+h2. Install
+
+<pre><code>gem install xaviershay-ruby_kml --source http://gems.github.com</code></pre>
+
+h2. Examples
+
+See @test/kml_file_test.rb@ for more examples
+
+h3. Placing markers on a map
+
+"View on Google Maps":http://maps.google.com/maps?q=http://github.com/xaviershay/ruby_kml/tree/master%2Fexamples%2Fmelbourne-stations.kml?raw=true&t=k
+
+<pre><code>require 'kml'
+
+kml = KMLFile.new
+folder = KML::Folder.new(:name => 'Melbourne Stations')
+[
+  ["Flinders St",    -37.818078, 144.966811],
+  ["Southern Cross", -37.818358, 144.952417],
+].each do |name, lat, lng|
+  folder.features << KML::Placemark.new(
+    :name => name, 
+    :geometry => KML::Point.new(:coordinates => {:lat => lat, :lng => lng})
+  )
+end
+kml.objects << folder
+puts kml.render
+</code></pre>

data/Rakefile

@@ -0,0 +1,134 @@
+require 'rake'
+require 'rake/testtask'
+require 'rake/rdoctask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/contrib/rubyforgepublisher'
+
+require File.join(File.dirname(__FILE__), 'lib/kml', 'version')
+
+PKG_BUILD       = ENV['PKG_BUILD'] ? '.' + ENV['PKG_BUILD'] : ''
+PKG_NAME        = 'kmlr'
+PKG_VERSION     = KML::VERSION::STRING + PKG_BUILD
+PKG_FILE_NAME   = "#{PKG_NAME}-#{PKG_VERSION}"
+PKG_DESTINATION = ENV["PKG_DESTINATION"] || "../#{PKG_NAME}"
+
+RELEASE_NAME  = "REL #{PKG_VERSION}"
+
+RUBY_FORGE_PROJECT = "kmlr"
+RUBY_FORGE_USER    = "aeden"
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test the library.'
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = true
+end
+
+desc 'Clean up after tests.'
+task :clean_tests do
+  FileList['test/*.kml'].each do |f|
+    File.unlink(f)
+    puts "Deleting #{f}"
+  end
+end
+
+desc 'Generate documentation for the library.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'KMLr'
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+PKG_FILES = FileList[
+  'CHANGELOG',
+  'README',
+  'TODO',
+  'Rakefile',
+  'bin/**/*',
+  'doc/**/*',
+  'lib/**/*',
+] - [ 'test' ]
+
+spec = Gem::Specification.new do |s|
+  s.name = 'kmlr'
+  s.version = PKG_VERSION
+  s.summary = "Library to product KML files."
+  s.description = <<-EOF
+    KMLr is a Ruby library which can be used to construct Keyhole Markup Language files.
+  EOF
+
+  s.add_dependency('rake',                '>= 0.7.1')
+
+  s.rdoc_options << '--exclude' << '.'
+  s.has_rdoc = false
+
+  s.files = PKG_FILES.to_a.delete_if {|f| f.include?('.svn')}
+  s.require_path = 'lib'
+
+  s.author = "Anthony Eden"
+  s.email = "anthonyeden@gmail.com"
+  s.homepage = "http://kmlr.rubyforge.org/"
+  s.rubyforge_project = "kmlr"
+end
+
+Rake::GemPackageTask.new(spec) do |pkg|
+  pkg.gem_spec = spec
+  pkg.need_tar = true
+  pkg.need_zip = true
+end
+
+desc "Generate code statistics"
+task :lines do
+  lines, codelines, total_lines, total_codelines = 0, 0, 0, 0
+
+  for file_name in FileList["lib/**/*.rb"]
+    next if file_name =~ /vendor/
+    f = File.open(file_name)
+
+    while line = f.gets
+      lines += 1
+      next if line =~ /^\s*$/
+      next if line =~ /^\s*#/
+      codelines += 1
+    end
+    puts "L: #{sprintf("%4d", lines)}, LOC #{sprintf("%4d", codelines)} | #{file_name}"
+    
+    total_lines     += lines
+    total_codelines += codelines
+    
+    lines, codelines = 0, 0
+  end
+
+  puts "Total: Lines #{total_lines}, LOC #{total_codelines}"
+end
+
+desc "Publish the release files to RubyForge."
+task :release => [ :package ] do
+  `rubyforge login`
+
+  for ext in %w( gem tgz zip )
+    release_command = "rubyforge add_release kmlr #{PKG_NAME} 'REL #{PKG_VERSION}' pkg/#{PKG_NAME}-#{PKG_VERSION}.#{ext}"
+    puts release_command
+    system(release_command)
+  end
+end
+
+desc "Publish the API documentation"
+task :pdoc => [:rdoc] do 
+  Rake::SshDirPublisher.new("aeden@rubyforge.org", "/var/www/gforge-projects/kmlr/rdoc", "rdoc").upload
+end
+
+desc "Reinstall the gem from a local package copy"
+task :reinstall => [:package] do
+  windows = RUBY_PLATFORM =~ /mswin/
+  sudo = windows ? '' : 'sudo'
+  gem = windows ? 'gem.bat' : 'gem'
+  `#{sudo} #{gem} uninstall -x -i #{PKG_NAME}`
+  `#{sudo} #{gem} install pkg/#{PKG_NAME}-#{PKG_VERSION}`
+end

data/examples/melbourne-stations.kml

@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<kml xmlns="http://earth.google.com/kml/2.1">
+  <Folder>
+    <name>Melbourne Stations</name>
+    <Placemark>
+      <name>Flinders St</name>
+      <Point>
+        <coordinates>144.966811,-37.818078</coordinates>
+      </Point>
+    </Placemark>
+    <Placemark>
+      <name>Southern Cross</name>
+      <Point>
+        <coordinates>144.952417,-37.818358</coordinates>
+      </Point>
+    </Placemark>
+  </Folder>
+</kml>

data/lib/kml/color_style.rb

@@ -0,0 +1,34 @@
+module KML #:nodoc:
+  # Base class for specifying the color and color mode of extended style types.
+  class ColorStyle < KML::Object
+    # Color and opacity (alpha) values are expressed in hexadecimal notation. The range of values for any one color 
+    # is 0 to 255 (00 to ff). For alpha, 00 is fully transparent and ff is fully opaque. The order of expression is 
+    # aabbggrr, where aa=alpha (00 to ff); bb=blue (00 to ff); gg=green (00 to ff); rr=red (00 to ff). For example, 
+    # if you want to apply a blue color with 50 percent opacity to an overlay, you would specify the following: 
+    # 
+    #   style.color = '7fff0000'
+    # 
+    # where alpha=0x7f, blue=0xff, green=0x00, and red=0x00.
+    attr_accessor :color
+    
+    # Values for +color_mode+ are normal (no effect) and random. A value of random applies a random linear scale to 
+    # the base +color+ as follows. 
+    # 
+    # * To achieve a truly random selection of colors, specify a base +color+ of white (ffffffff).
+    # * If you specify a single color component (for example, a value of ff0000ff for red), random color values for 
+    #   that one component (red) will be selected. In this case, the values would range from 00 (black) to ff (full red).
+    # * If you specify values for two or for all three color components, a random linear scale is applied to each color 
+    #   component, with results ranging from black to the maximum values specified for each component.
+    # * The opacity of a color comes from the alpha component of <color> and is never randomized.
+    attr_accessor :color_mode
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.color(color) unless color.nil?
+      xm.colorMode(color_mode) unless color_mode.nil?
+    end
+  end
+end
+
+require 'kml/line_style'
+require 'kml/poly_style'
+require 'kml/icon_style'

data/lib/kml/container.rb

@@ -0,0 +1,16 @@
+module KML
+  # A Container is an abstract base class that holds one or more Features and allows the creation of nested hierarchies.
+  class Container < Feature
+    
+    # Access the features in the container
+    attr_accessor :features
+    
+    # Get the features in the container
+    def features
+      @features ||= []
+    end
+  end
+end
+
+require 'kml/folder'
+require 'kml/document'

data/lib/kml/document.rb

@@ -0,0 +1,26 @@
+module KML #:nodoc:
+  # A document contains 0 or more features and 0 or more schemas.
+  class Document < Container
+    attr_accessor :schemas
+    
+    # Shared styles
+    attr_accessor :styles
+    
+    def schemas
+      @schemas ||= []
+    end
+    
+    def styles
+      @styles ||= []
+    end
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.Document {
+        super
+        styles.each { |style| style.render(xm) }
+        features.each { |feature| feature.render(xm) }
+        schemas.each { |schema| schema.render(xm) }
+      }
+    end    
+  end
+end

data/lib/kml/feature.rb

@@ -0,0 +1,161 @@
+# This source file implements the Feature class of KML.
+#
+# Basic XML chunk structure:
+#
+#   <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>              <!-- user-defined data -->
+
+module KML #:nodoc:
+  # A feature is an abstract base class.
+  class Feature < KML::Object
+    # Accessor for the feature name
+    attr_accessor :name
+    
+    # Return true if the feature is visible
+    def visibility?
+      @visibility || true
+    end
+    
+    # If the visibility has been set then return '0' for false and '1' for true. If the visibility
+    # has never been explicitly set then return nil (which means that the associated KML tag will
+    # not be rendered)
+    def visibility
+      return nil if @visibility.nil?
+      @visibility ? '1' : '0'
+    end
+    
+    # Set to true to indicate that the feature is visible.
+    def visibility=(v)
+      @visibility = v
+    end
+    
+    # Return true if the feature is expanded when initially displayed.
+    def open?
+      @open || true
+    end
+    
+    # If the open has been set then return '0' for false and '1' for true. If the open has never been 
+    # explicitly set then return nil (which means that the associated KML tag will not be rendered)
+    def open
+      return nil if @open.nil?
+      @open ? '1' : '0'
+    end
+    
+    # Set to true to indicate that the feature is expanded when displayed. Set to false to indicate that the
+    # feature is collapsed.
+    def open=(v)
+      @open = v
+    end
+    
+    # A string value representing an unstructured address written as a standard street, city, state address, and/or as 
+    # a postal code. You can use the +address+ attribute to specify the location of a point instead of using latitude and 
+    # longitude coordinates. (However, if a Point is provided, it takes precedence over the +address+.) To find out 
+    # which locales are supported for this tag in Google Earth, go to the 
+    # <a href="http://maps.google.com/support/bin/answer.py?answer=16634">Google Maps Help</a>.
+    attr_accessor :address
+    
+    # A structured address, formatted as xAL, or eXtensible Address Language, an international standard for address 
+    # formatting. AddressDetails is used by KML for geocoding in Google Maps only. For details, see the Google Maps 
+    # API documentation. Currently, Google Earth does not use this attribute; use +address+ instead.
+    attr_accessor :address_details
+    
+    # A string value representing a telephone number. This element is used by Google Maps Mobile only. The industry 
+    # standard for Java-enabled cellular phones is RFC2806. For more information, see 
+    # <a href="http://www.ietf.org/rfc/rfc2806.txt">http://www.ietf.org/rfc/rfc2806.txt</a>.
+    attr_accessor :phone_number
+    
+    # Accessor for the snippet. See +KML::Snippet+
+    attr_accessor :snippet
+    # Set the snippet. See +KML::Snippet+
+    def snippet=(v)
+      case v
+      when String
+        @snippet = Snippet.new(v)
+      when Snippet
+        @snippet = v
+      else
+        raise ArgumentError, "Snippet must be a String or a Snippet"
+      end
+    end
+    
+    # User-supplied text that appears in the description balloon when the user clicks on either the feature name 
+    # in the Places panel or the Placemark icon in the 3D viewer. This text also appears beneath the feature name 
+    # in the Places panel if no Snippet is specified for the feature.
+    # 
+    # Description supports plain text as well as a subset of HTML formatting elements, including tables. It does 
+    # not support other web-based technology, such as dynamic page markup (PHP, JSP, ASP), scripting languages 
+    # (VBScript, Javascript), nor application languages (Java, Python).
+    # 
+    # If your description contains no HTML markup, Google Earth attempts to format it, replacing newlines with 
+    # &lt;br&gt; and wrapping URLs with anchor tags. A valid URL string for the World Wide Web is automatically 
+    # converted to a hyperlink to that URL (e.g., http://www.google.com). Consequently, you do not need to surround 
+    # a URL with the &lt;a href="http://.."&gt;&lt;/a&gt; tags in order to achieve a simple link.
+    attr_accessor :description
+    
+    # Defines a camera viewpoint associated with any element derived from Feature. See LookAt.
+    attr_accessor :look_at
+    
+    attr_accessor :time_primitive
+    
+    # URI (a URI equals [URL]#ID) of a Style or StyleMap defined in a Document. If the style is in the same file, 
+    # use a # reference. If the style is defined in an external file, use a full URL along with # referencing. Examples:
+    #
+    #   +style_url='#myIconStyleID'
+    #   +style_url='http://someserver.com/somestylefile.xml#restaurant'
+    attr_accessor :style_url
+    
+    # One or more Styles and StyleMaps can be defined to customize the appearance of any element derived from Feature 
+    # or of the Geometry in a Placemark. (See BalloonStyle, ListStyle, StyleSelector, and the styles derived from 
+    # ColorStyle.) A style defined within a Feature is called an "inline style" and applies only to the Feature that 
+    # contains it. A style defined as the child of a Document is called a "shared style." A shared style must have an id 
+    # defined for it. This id is referenced by one or more Features within the <Document>. In cases where a style element 
+    # is defined both in a shared style and in an inline style for a Feature—that is, a Folder, GroundOverlay, 
+    # NetworkLink, Placemark, or ScreenOverlay—the value for the Feature's inline style takes precedence over the value 
+    # for the shared style.
+    attr_accessor :style_selector
+    attr_accessor :region
+    attr_accessor :metadata
+    
+    # Render the object and all of its sub-elements.
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      [:name, :visibility, :address].each do |a|
+        xm.__send__(a, self.__send__(a)) unless self.__send__(a).nil?
+      end
+      
+      xm.description { xm.cdata!(description) } unless description.nil?
+      xm.open(self.open) unless open.nil?
+      
+      xm.phoneNumber(phone_number) unless phone_number.nil?
+      xm.styleUrl(style_url) unless style_url.nil?
+      
+      unless address_details.nil?
+        xm.AddressDetails(:xmlns => "urn:oasis:names:tc:ciq:xsdschema:xAL:2.0") { address_details.render(xm) } 
+      end
+      
+      xm.Snippet(snippet.text, snippet.max_lines) unless snippet.nil?
+      
+      xm.LookAt { look_at.render(xm) } unless look_at.nil?
+      xm.TimePrimitive { time_primitive.render(xm) } unless look_at.nil?
+      xm.StyleSelector { style_selector.render(xm) } unless style_selector.nil?
+    end
+  end
+end
+
+require 'kml/placemark'
+require 'kml/container'
+require 'kml/overlay'
+
+require 'kml/snippet'

data/lib/kml/folder.rb

@@ -0,0 +1,12 @@
+module KML #:nodoc:
+  # A Folder is used to arrange other Features hierarchically (Folders, Placemarks, NetworkLinks, 
+  # or Overlays). A Feature is visible only if it and all its ancestors are visible.
+  class Folder < Container
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.Folder {
+        super
+        features.each { |f| f.render(xm) }
+      }
+    end
+  end
+end

data/lib/kml/geometry.rb

@@ -0,0 +1,86 @@
+module KML
+  class Geometry < KML::Object
+    # Specifies whether to connect the point to the ground. Extrusion requires that the point's +altitude_mode+ be 
+    # either "relativeToGround" or "absolute" and that within the +coordinates+, the altitude component be greater 
+    # than 0 (that is, in the air). Default is false.
+    def extrude?
+      @extrude
+    end
+    
+    # Set to true to extrude.
+    def extrude=(v)
+      @extrude = v
+    end
+    
+    # Return nil if extrude has not been defined, otherwise return '1' for true or '0' for false.
+    def extrude
+      return nil unless @extrude
+      @extrude ? '1' : '0'
+    end
+    
+    # Specifies whether to allow lines and paths to follow the terrain. This specification applies only to LineStrings 
+    # (paths) and LinearRings (polygons) that have an +altitude_mode+ of "clampToGround". Very long lines should enable 
+    # tessellation so that they follow the curvature of the earth (otherwise, they may go underground and be hidden).
+    # Default is false.
+    def tessellate?
+      @tessellate
+    end
+    
+    # Set to true to tessellate.
+    def tessellate=(v)
+      @tessellate = v
+    end
+    
+    # Return nil if tessellate has not been defined, otherwise return '1' for true or '0' for false.
+    def tessellate
+      return nil unless @tessellate
+      @tessellate ? '1' : '0'
+    end
+    
+    # Specifies how altitude components in the <coordinates> element are interpreted. Possible values are:
+    # 
+    # * clampToGround - (default) Indicates to ignore an altitude specification (for example, in the +coordinates+).
+    # * relativeToGround - Sets the altitude of the element relative to the actual ground elevation of a particular 
+    #   location. For example, if the ground elevation of a location is exactly at sea level and the altitude for a 
+    #   point is set to 9 meters, then the elevation for the icon of a point placemark elevation is 9 meters with 
+    #   this mode. However, if the same coordinate is set over a location where the ground elevation is 10 meters 
+    #   above sea level, then the elevation of the coordinate is 19 meters. A typical use of this mode is for placing 
+    #   telephone poles or a ski lift.
+    # * absolute - Sets the altitude of the coordinate relative to sea level, regardless of the actual elevation 
+    #   of the terrain beneath the element. For example, if you set the altitude of a coordinate to 10 meters with 
+    #   an absolute altitude mode, the icon of a point placemark will appear to be at ground level if the terrain 
+    #   beneath is also 10 meters above sea level. If the terrain is 3 meters above sea level, the placemark will 
+    #   appear elevated above the terrain by 7 meters. A typical use of this mode is for aircraft placement.
+    def altitude_mode
+      @altitude_mode || 'clampToGround'
+    end
+    
+    def altitude_mode_set?
+      !(@altitude_mode.nil?)
+    end
+    
+    # Set the altitude mode
+    def altitude_mode=(mode)
+      allowed_modes = %w(clampToGround relativeToGround absolute)
+      if allowed_modes.include?(mode)
+        @altitude_mode = mode
+      else
+        raise ArgumentError, "Must be one of the allowed altitude modes: #{allowed_modes.join(',')}"
+      end
+    end
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.extrude(extrude) unless extrude.nil?
+      xm.tessellate(tessellate) unless tessellate.nil?
+      xm.altitudeMode(altitude_mode) if altitude_mode_set?
+    end
+    
+  end
+end
+
+require 'kml/point'
+require 'kml/line_string'
+require 'kml/linear_ring'
+require 'kml/polygon'
+require 'kml/model'
+require 'kml/multi_geometry'

data/lib/kml/ground_overlay.rb

@@ -0,0 +1,18 @@
+module KML #:nodoc:
+  # This element draws an image overlay draped onto the terrain.
+  class GroundOverlay < Overlay
+    attr_accessor :altitude
+    attr_accessor :altitude_mode
+    attr_accessor :lat_lon_box
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      raise InvalidKMLError, "GroundOverlay.lat_lon_box is required" if lat_lon_box.nil?
+      xm.GroundOverlay {
+        super
+        xm.altitude(altitude) unless altitude.nil?
+        xm.altitudeMode(altitude_mode) unless altitude_mode.nil?
+        lat_lon_box.render(xm)
+      }
+    end
+  end
+end

data/lib/kml/hot_spot.rb

@@ -0,0 +1,31 @@
+module KML #:nodoc:
+  # Specifies the position within the Icon that is "anchored" to the <Point> specified in the Placemark. 
+  # The x and y values can be specified in three different ways: as pixels ("pixels"), as fractions of 
+  # the icon ("fraction"), or as inset pixels ("insetPixels"), which is an offset in pixels from the upper 
+  # right corner of the icon. The x and y positions can be specified in different ways—for example, x can 
+  # be in pixels and y can be a fraction. The origin of the coordinate system is in the lower left corner 
+  # of the icon.
+  # 
+  # * x - Either the number of pixels, a fractional component of the icon, or a pixel inset indicating the 
+  #   x component of a point on the icon.
+  # * y - Either the number of pixels, a fractional component of the icon, or a pixel inset indicating the 
+  #   y component of a point on the icon.
+  # * xunits - Units in which the x value is specified. Default="fraction". A value of "fraction" indicates 
+  #   the x value is a fraction of the icon. A value of "pixels" indicates the x value in pixels. A value of 
+  #   "insetPixels" indicates the indent from the right edge of the icon.
+  # * yunits - Units in which the y value is specified. Default="fraction". A value of "fraction" indicates 
+  #   the y value is a fraction of the icon. A value of "pixels" indicates the y value in pixels. A value of 
+  #   "insetPixels" indicates the indent from the top edge of the icon.
+  class HotSpot
+    attr_reader :x
+    attr_reader :y
+    attr_reader :xunits
+    attr_reader :yunits
+    def initialize(x, y, xunits, yunits)
+      @x = x
+      @y = y
+      @xunits = xunits
+      @yunits = yunits
+    end
+  end
+end

data/lib/kml/icon.rb

@@ -0,0 +1,15 @@
+module KML #:nodoc:
+  # Defines an image associated with an Icon style or overlay. Icon has the same child elements as +Link+. 
+  # The required href defines the location of the image to be used as the overlay or as the icon for the 
+  # placemark. This location can either be on a local file system or a remote web server.
+  class Icon < Link
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      raise InvalidKMLError, "Icon.href must be specified" if href.nil?
+      xm.Icon {
+        self.elements.each do |a|
+          xm.__send__(a, self.__send__(a)) unless self.__send__(a).nil?
+        end
+      }
+    end
+  end
+end

data/lib/kml/icon_style.rb

@@ -0,0 +1,52 @@
+# Source file contains the code for creating the IconStyle element:
+#
+# <IconStyle id="ID">
+#   <!-- inherited from ColorStyle -->
+#   <color>ffffffff</color>            <!-- kml:color -->
+#   <colorMode>normal</colorMode>      <!-- kml:colorModeEnum:normal or random -->
+# 
+#   <!-- specific to IconStyle -->
+#   <scale>1</scale>                   <!-- float -->
+#   <heading>0</heading>               <!-- float -->
+#   <Icon>
+#     <href>...</href>
+#   </Icon> 
+#   <hotSpot x="0.5"  y="0.5" 
+#     xunits="fraction" yunits="fraction"/>    <!-- kml:vec2Type -->                    
+# </IconStyle>
+
+module KML #:nodoc:
+  # Specifies how icons for point Placemarks are drawn, both in the Places panel and in the 3D viewer of 
+  # Google Earth. The Icon object specifies the icon image. The +scale+ specifies the x, y scaling of the 
+  # icon.
+  class IconStyle < ColorStyle
+    # Compass direction, in degrees. Default=0 (North). (
+    # <a href="http://earth.google.com/kml/kml_tags_21.html#heading">See diagram.) Values range from 0 to 
+    # ±180 degrees.
+    attr_accessor :heading
+    
+    # Resizes the icon (default=1).
+    attr_accessor :scale
+    
+    # A custom Icon.
+    attr_accessor :icon
+    
+    # Specifies the position within the Icon that is "anchored" to the Point specified in the Placemark.
+    # See KML::HotSpot
+    attr_accessor :hot_spot
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      xm.IconStyle {
+        super
+        xm.scale(scale) unless scale.nil?
+        xm.heading(heading) unless heading.nil?
+        icon.render(xm) unless icon.nil?
+        unless hot_spot.nil?
+          xm.hotSpot(:x => hot_spot.x, :y => hot_spot.y, :xunits => hot_spot.xunits, :yunits => hot_spot.yunits)
+        end
+      }
+    end
+  end
+end
+
+require 'kml/hot_spot'