GeoRuby 1.1.2 → 1.2.0

data/lib/geo_ruby/simple_features/geometry.rb

@@ -88,6 +88,7 @@ module GeoRuby#:nodoc:
 
       #Outputs the geometry in georss format. 
       #Assumes the geometries are in latlon format, with x as lon and y as lat.
+      #Pass the <tt>:dialect</tt> option to swhit format. Possible values are: <tt>:simple</tt> (default), <tt>:w3cgeo</tt> and <tt>:gml</tt>.
       def as_georss(options = {})
         dialect= options[:dialect] || :simple
         case(dialect)

data/lib/geo_ruby.rb

@@ -13,4 +13,4 @@ require 'geo_ruby/simple_features/geometry_factory'
 require 'geo_ruby/simple_features/ewkb_parser'
 require 'geo_ruby/simple_features/ewkt_parser'
 require 'geo_ruby/simple_features/georss_parser'
-
+require 'geo_ruby/shp4r/shp'

data/rakefile.rb

@@ -24,18 +24,18 @@ spec = Gem::Specification::new do |s|
   s.platform = Gem::Platform::RUBY
 
   s.name = 'GeoRuby'
-  s.version = "1.1.2"
+  s.version = "1.2.0"
   s.summary = "Ruby data holder for OGC Simple Features"
   s.description = <<EOF
 GeoRuby is intended as a holder for data returned from PostGIS and MySQL Spatial queries. The data model roughly follows the OGC "Simple Features for SQL" specification (see www.opengis.org/docs/99-049.pdf), although without any kind of advanced functionalities (such as geometric operators or reprojections)
 EOF
   s.author = 'Guilhem Vellut'
-  s.email = 'guilhem.vellut+georuby@gmail.com'
-  s.homepage = "http://thepochisuperstarmegashow.com/projects"
+  s.email = 'guilhem.vellut@gmail.com'
+  s.homepage = "http://thepochisuperstarmegashow.com/projects/"
   
   s.requirements << 'none'
   s.require_path = 'lib'
-  s.files = FileList["lib/**/*.rb", "test/**/*.rb", "README","MIT-LICENSE","rakefile.rb"]
+  s.files = FileList["lib/**/*.rb", "test/**/*.rb", "README","MIT-LICENSE","rakefile.rb","test/data/*.shp","test/data/*.dbf","test/data/*.shx","tools/**/*.yml","tools/**/*.rb","tools/lib/**/*"]
   s.test_files = FileList['test/test*.rb']
 
   s.has_rdoc = true

data/test/test_shp.rb

@@ -0,0 +1,77 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+
+require 'geo_ruby'
+require 'test/unit'
+
+include GeoRuby::SimpleFeatures
+include GeoRuby::Shp4r
+
+class TestShp < Test::Unit::TestCase
+
+  def test_point
+    shpfile = ShpFile.open(File.dirname(__FILE__) + '/data/point.shp')
+    
+    assert_equal(2,shpfile.record_count)
+    assert_equal(1,shpfile.fields.length)
+    assert_equal(ShpType::POINT,shpfile.shp_type)
+    field = shpfile.fields[0]
+    assert_equal("Hoyoyo",field.name)
+    assert_equal("N",field.type)
+    
+    record1 = shpfile[0]
+    assert(record1.geometry.kind_of?(Point))
+    assert_in_delta(-90.08375,record1.geometry.x,0.00001)
+    assert_in_delta(34.39996,record1.geometry.y,0.00001)
+    assert_equal(6,record1.data['Hoyoyo'])
+    
+    record2 = shpfile[1]
+    assert(record1.geometry.kind_of?(Point))
+    assert_in_delta(-87.82580,record2.geometry.x,0.00001)
+    assert_in_delta(33.36417,record2.geometry.y,0.00001)
+    assert_equal(9,record2.data['Hoyoyo'])
+    
+    shpfile.close
+  end
+
+  def test_polyline
+    shpfile = ShpFile.open(File.dirname(__FILE__) + '/data/polyline.shp')
+    
+    assert_equal(1,shpfile.record_count)
+    assert_equal(1,shpfile.fields.length)
+    assert_equal(ShpType::POLYLINE,shpfile.shp_type)
+    field = shpfile.fields[0]
+    assert_equal("Chipoto",field.name)
+    assert_equal("F",field.type)
+
+    record1 = shpfile[0]
+    #a SHP polyline can have multiple parts so they are in fact multilinestrings
+    assert(record1.geometry.kind_of?(MultiLineString))
+    assert_equal(1,record1.geometry.length)
+    assert_equal(6,record1.geometry[0].length)
+    assert_equal(5.678,record1.data['Chipoto'])
+
+    shpfile.close
+  end 
+
+  def test_polygon
+    shpfile = ShpFile.open(File.dirname(__FILE__) + '/data/polygon.shp')
+    
+    assert_equal(1,shpfile.record_count)
+    assert_equal(1,shpfile.fields.length)
+    assert_equal(ShpType::POLYGON,shpfile.shp_type)
+    field = shpfile.fields[0]
+    assert_equal("Hello",field.name)
+    assert_equal("C",field.type)
+    
+    record1 = shpfile[0]
+    #a SHP polygon can have multiple outer loops (although not supported currently) so they are in fact multipolygons
+    assert(record1.geometry.kind_of?(MultiPolygon))
+    assert_equal(1,record1.geometry.length)
+    assert_equal(1,record1.geometry[0].length)
+    assert_equal(7,record1.geometry[0][0].length)
+    assert_equal("Bouyoul!",record1.data['Hello'])
+    
+    shpfile.close
+  end
+
+end

data/tools/db.yml

@@ -0,0 +1,6 @@
+adapter: mysql
+database: database
+username: user
+password: pwd
+host: localhost
+

data/tools/lib/spatial_adapter/MIT-LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2006 Guilhem Vellut <guilhem.vellut+georuby@gmail.com>
+
+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/tools/lib/spatial_adapter/README

@@ -0,0 +1,116 @@
+=Spatial Adapter for Rails
+This is the Spatial Adapter for Rails 0.1.1. It is a plugin for Rails which manages the MySql Spatial and PostGIS geometric columns in a transparent way (that is like the other base data type columns). It also provides a way to manage these columns in migrations. It replaces both the "PostGIS Adapter for Rails" and "MySql Spatial Adapter for Rails" plugins.
+
+===Dependencies
+You need to install a version >= 0.1.1 of the GeoRuby gem (http://rubyforge.org/projects/georuby/) :
+	gem install georuby
+
+
+===Installation
+At the root of your Rails project, type :
+       script\plugin install svn://rubyforge.org/var/svn/georuby/SpatialAdapter/trunk/spatial_adapter
+You need to have SVN installed.
+	
+
+===Operations
+Geometric columns in your ActiveRecord models now appear just like any other column of other basic data types. They can also be dumped in ruby schema mode and loaded in migrations the same way as columns of basic types.
+
+==== Migrations
+
+Here is an example of code for the creation of a table with a geometric column in PostGIS, along with the addition of a spatial index on the column : 
+	ActiveRecord::Schema.define do
+	  create_table "table_points", :force => true do |t|
+    	    t.column "data", :string
+    	    t.column "geom", :point, :null=>false, :srid => 123, :with_z => true
+  	  end
+	
+	  add_index "table_points", "geom", :spatial=>true
+    	end
+
+Here is a related statement valid for MySql version <= 5.0.16 :
+	ActiveRecord::Schema.define do
+	  create_table "table_points", :options=>"ENGINE=MyISAM", :force => true do |t|
+    	    t.column "data", :string
+    	    t.column "geom", :point, :null=>false
+  	  end
+	
+	  add_index "table_points", "geom", :spatial=>true
+    	end
+The differences with the PostGIS version are because of the following reasons :
+- On all version of MySql, the :srid and :with_z would be ignored, since they are not supported.
+- On MySql versions <= 5.0.16, you have to add <tt>:options => "ENGINE=MyISAM"</tt> to the create_table statetement, since only MyISAM tables can have geometric columns.
+
+==== Model
+
+Here is the model you would use, in both MySql and PostGIS:
+	class TablePoint < ActiveRecord::Base
+	end
+That was easy! As you see, there is no need to declare a column as geometric. The plugin will get this information by itself.
+
+==== Access
+
+Here is an example of PostGIS row creation and access, using the model and the table defined above :
+	pt = TablePoint.new(:data => "Hello!",:geom => Point.from_x_y_z(-1.6,2.8,-3.4,123))
+	pt.save
+	pt = TablePoint.find_first
+	puts pt.geom.x #access the geom column like any other
+
+For MySQL, it is slightly different since it does not support Z dimension or SRID :
+	pt = TablePoint.new(:data => "Hello!",:geom => Point.from_x_y(-1.6,2.8))
+	pt.save
+	pt = TablePoint.find_first
+	puts pt.geom.x #access the geom column like any other
+
+==== Fixtures
+
+If you use fixtures for your unit tests, at some point, you will want to input a geometry. You could transform your geometries to a form suitable for YAML yourself everytime but the spatial adapter provides a method to do it for you: +to_fixture_format+. It works for both MySQL and PostGIS (although the string returned is different for each database). You would use it like this, if the geometric column is a point:
+	fixture:
+	 id: 1
+	 data: HELLO
+	 geom: <%= Point.from_x_y(123.5,321.9).to_fixture_format %>
+
+==== Find_by
+
+find_by_[column] has been redefined when column is of a geometric type. Instead of using the Rails default '=' operator, for which I can't see a definition for MySql spatial datatypes and which performs a bounding box equality test in PostGIS, it uses a bounding box intersection: && in PostGIS and MBRIntersects in MySQL, which can both make use of a spatial index if one is present to speed up the queries. You could use this query, for example, if you need to display data from the database: You would want only the geometries which are in the screen rectangle and you could use a bounding box query for that. Since this is a common case, it is the default. You have 2 ways to use the find_by_[geom_column]: Either by passing a geometric object directly, or passing an array with the 2 opposite corners of a bounding box (with 2 or 3 coordinates depending of the dimension of the data).
+	Park.find_by_geom(LineString.from_coordinates([[1.4,5.6],[2.7,8.9],[1.6,5.6]]))
+or
+	Park.find_by_geom([[3,5.6],[19.98,5.9]])
+In PostGIS, since you can only use operations with geometries with the same SRID, you can add a third element representing the SRID of the bounding box to the array. It is by default set to -1:
+	Park.find_by_geom([[3,5.6],[19.98,5.9],123])
+
+==== Geometric data types
+
+Ruby geometric datatypes are currently made available only through the GeoRuby library (http://thepochisuperstarmegashow.com/ProjectsDoc/georuby-doc/index.html): This is where the <tt>Point.from_x_y</tt> in the example above comes from. It is a goal of a future release of the Spatial Adapter to support additional geometric datatype libraries, such as Ruby/GEOS, as long as they can support reading and writing of EWKB.
+
+
+===Warning
+- If you use a version of MySQL before 5.0.16, only tables using the MyISAM engine can support geometric columns. After MySQL 5.0.16, any engine (incuding INNODB) is supported. 
+
+- Since ActiveRecord seems to keep only the string values directly returned from the database, it translates from these to the correct types everytime an attribute is read, which is probably ok for simple types, but might be less than efficient for geometries, since the EWKB string has to be parsed everytime. Also it means you cannot modify the geometry object returned from an attribute directly :
+       place = Place.find_first
+       place.the_geom.y=123456.7
+ 
+- Since the translation to a geometry is performed everytime the_geom is read, the change to y will not be saved! You would have to do something like this :    
+       place = Place.find_first
+       the_geom = place.the_geom
+       the_geom.y=123456.7
+       place.the_geom = the_geom
+
+
+===Changes since last version
+- The PostGIS adapter and the MySql Spatial adapter have been merged into one plugin. The correct files to load is determined using the type of connection defined in the environment.
+- Geometric columns can now be dumped just like other base data types. This means you can use the ruby schema mode, even if you use the plugin.
+- Support of M dimensions in migrations. The <tt>:dimension</tt> key in the column definition has disappeared and has been replaced by <tt>:with_z</tt> and <tt>:with_m</tt>.
+- Addition of unit tests. At the plugin root, Run <tt>rake test:mysql</tt> to run the mysql tests and <tt>rake test:postgis</tt> for the postgis ones. You will need to configure your connection in <tt>test/db/database_mysql.yml</tt> and <tt>test/db/database_postgis.yml</tt>. If you get errors on your platform, please report to mailto:guilhem.vellut+georuby@gmail.com.
+- Addition of a find_by methods with a special behaviour for geometries
+- Addition of a to_fixture_format method to use inside a YAML fixture
+
+===TODO
+- Support of other geometric datatype libraries in addition to GeoRuby
+- Tutorials
+
+===License
+The Spatial Adapter for Rails is released under the MIT license.
+
+===Support
+Any questions, enhancement proposals, bug notifications or corrections can be sent to mailto:guilhem.vellut+georuby@gmail.com.

data/tools/lib/spatial_adapter/init.rb

@@ -0,0 +1,10 @@
+class SpatialAdapterNotCompatibleError < StandardError
+end
+
+if ActiveRecord::Base.connection.is_a?(ActiveRecord::ConnectionAdapters::MysqlAdapter)
+  require 'mysql_spatial_adapter'
+elsif ActiveRecord::Base.connection.is_a?(ActiveRecord::ConnectionAdapters::PostgreSQLAdapter)
+  require 'post_gis_adapter'
+else
+  raise SpatialAdapterNotCompatibleError.new("Only MySQL and PostgreSQL are currently supported by the spatial adapter plugin.")
+end

data/tools/lib/spatial_adapter/lib/common_spatial_adapter.rb

@@ -0,0 +1,175 @@
+
+#Addition of a flag indicating if the index is spatial
+ActiveRecord::ConnectionAdapters::IndexDefinition.class_eval do
+  attr_accessor :spatial
+
+  def initialize(table, name, unique, spatial,columns)
+    super(table,name,unique,columns)
+    @spatial = spatial
+  end
+  
+end
+
+ActiveRecord::SchemaDumper.class_eval do
+  def table(table, stream)
+        
+    columns = @connection.columns(table)
+    begin
+      tbl = StringIO.new
+      
+      if @connection.respond_to?(:pk_and_sequence_for)
+        pk, pk_seq = @connection.pk_and_sequence_for(table)
+      end
+      pk ||= 'id'
+        
+      tbl.print "  create_table #{table.inspect}"
+      if columns.detect { |c| c.name == pk }
+        if pk != 'id'
+          tbl.print %Q(, :primary_key => "#{pk}")
+        end
+      else
+        tbl.print ", :id => false"
+      end
+        
+      if @connection.respond_to?(:options_for)
+        res = @connection.options_for(table)
+        tbl.print ", :options=>'#{res}'" if res
+      end
+      
+      tbl.print ", :force => true"
+      tbl.puts " do |t|"
+      
+      columns.each do |column|
+
+        raise StandardError, "Unknown type '#{column.sql_type}' for column '#{column.name}'" if @types[column.type].nil?
+        next if column.name == pk
+        #need to use less_simplified_type  here or have each specific geometry type be simplified to a specific simplified type in Column and each one treated separately in the Column methods
+        if column.is_a?(SpatialColumn)
+          tbl.print "    t.column #{column.name.inspect}, #{column.geometry_type.inspect}"
+          tbl.print ", :srid => #{column.srid.inspect}" if column.srid != -1
+          tbl.print ", :with_z => #{column.with_z.inspect}" if column.with_z
+          tbl.print ", :with_m => #{column.with_m.inspect}" if column.with_m
+        else
+          tbl.print "    t.column #{column.name.inspect}, #{column.type.inspect}"
+        end
+        tbl.print ", :limit => #{column.limit.inspect}" if column.limit != @types[column.type][:limit] 
+        tbl.print ", :default => #{column.default.inspect}" if !column.default.nil?
+        tbl.print ", :null => false" if !column.null
+        tbl.puts
+      end
+      
+      tbl.puts "  end"
+      tbl.puts
+      
+      indexes(table, tbl)
+      
+      tbl.rewind
+      stream.print tbl.read
+    rescue => e
+      stream.puts "# Could not dump table #{table.inspect} because of following #{e.class}"
+      stream.puts "#   #{e.message} #{e.backtrace}"
+      stream.puts
+    end
+    
+    stream
+  end
+  
+  def indexes(table, stream)
+    indexes = @connection.indexes(table)
+    indexes.each do |index|
+      stream.print "  add_index #{index.table.inspect}, #{index.columns.inspect}, :name => #{index.name.inspect}"
+      stream.print ", :unique => true" if index.unique
+      stream.print ", :spatial=> true " if index.spatial
+      stream.puts
+    end
+    
+    stream.puts unless indexes.empty?
+  end
+end
+
+
+module SpatialAdapter
+  #Translation of geometric data types
+  def geometry_data_types
+    {
+      :point => { :name => "POINT" },
+      :line_string => { :name => "LINESTRING" },
+      :polygon => { :name => "POLYGON" },
+      :geometry_collection => { :name => "GEOMETRYCOLLECTION" },
+      :multi_point => { :name => "MULTIPOINT" },
+      :multi_line_string => { :name => "MULTILINESTRING" },
+      :multi_polygon => { :name => "MULTIPOLYGON" },
+      :geometry => { :name => "GEOMETRY"}
+    }
+  end
+  
+end
+
+
+#using a mixin instead of subclassing Column since each adapter can have a specific subclass of Column
+module SpatialColumn
+  attr_reader  :geometry_type, :srid, :with_z, :with_m
+    
+  def initialize(name, default, sql_type = nil, null = true,srid=-1,with_z=false,with_m=false)
+    super(name,default,sql_type,null)
+    @geometry_type = geometry_simplified_type(@sql_type)
+    @srid = srid
+    @with_z = with_z
+    @with_m = with_m
+  end
+
+  
+  #Redefines type_cast to add support for geometries
+  def type_cast(value)
+    return nil if value.nil?
+    case type
+    when :geometry then self.class.string_to_geometry(value)
+    else super
+    end
+  end
+    
+  #Redefines type_cast_code to add support for geometries. 
+  #
+  #WARNING : Since ActiveRecord keeps only the string values directly returned from the database, it translates from these to the correct types everytime an attribute is read (using the code returned by this method), which is probably ok for simple types, but might be less than efficient for geometries. Also you cannot modify the geometry object returned directly or your change will not be saved. 
+  def type_cast_code(var_name)
+    case type
+    when :geometry then "#{self.class.name}.string_to_geometry(#{var_name})"
+    else super
+    end
+  end
+
+  
+  #Redefines klass to add support for geometries
+  def klass
+    case type
+    when :geometry then GeoRuby::SimpleFeatures::Geometry
+    else super
+    end
+  end
+  
+  private
+  
+  #Redefines the simplified_type method to add behabiour for when a column is of type geometry
+  def simplified_type(field_type)
+    case field_type
+    when /geometry|point|linestring|polygon|multipoint|multilinestring|multipolygon|geometrycollection/i then :geometry
+    else super
+    end
+  end
+
+  #less simlpified geometric type to be use in migrations
+  def geometry_simplified_type(field_type)
+    case field_type
+    when /^point$/i then :point
+    when /^linestring$/i then :line_string
+    when /^polygon$/i then :polygon
+    when /^geometry$/i then :geometry
+    when /multipoint/i then :multi_point
+    when /multilinestring/i then :multi_line_string
+    when /multipolygon/i then :multi_polygon
+    when /geometrycollection/i then :geometry_collection
+    end
+  end
+
+
+end