ruby_kml 0.1.7

data/lib/kml/geometry.rb

@@ -0,0 +1,102 @@
+module KML
+  class Geometry < KML::Container
+    # 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
+
+    def self.parse(node)
+      self.new.parse(node)
+    end
+
+    def parse(node)
+      super(node) do |cld|
+        case cld.name
+        when 'tessellate'
+          self.tessellate = cld.content
+        else
+          yield cld
+        end
+      end
+      self
+    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'

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.strip.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,67 @@
+# 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.strip.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
+
+    def self.parse(node)
+      self.new.parse(node)
+    end
+
+    def parse(node)
+      super(node) do |cld|
+        case cld.name
+        when 'coordinates'
+          self.coordinates = cld.content
+        else
+          puts "LinearRing"
+          p cld
+          puts
+        end
+      end
+      self
+    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,28 @@
+# <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
+    
+    def render(xm=Builder::XmlMarkup.new(:indent => 2))
+      [:longitude, :latitude, :altitude, :range, :tilt, :heading, :altitude_mode].each do |a|
+        xm.__send__(a, self.__send__(a)) unless self.__send__(a).nil?
+      end
+    end
+    
+  end
+end