postgis_adapter 0.1.8

data/History.txt

@@ -0,0 +1,6 @@
+=== 1.0.0 / 2008-12-10
+
+* 1 major enhancement
+
+  * Birthday!
+

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+Spatial Adapter Copyright (c) 2006 Guilhem Vellut <guilhem.vellut+georuby@gmail.com>
+PostGis Adapter Functions (c) 2008 Marcos Piccinini <nofxx>
+
+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/Manifest.txt

@@ -0,0 +1,36 @@
+History.txt
+MIT-LICENSE
+Manifest.txt
+README.rdoc
+Rakefile
+init.rb
+install.rb
+lib/postgis_adapter.rb
+lib/postgis_adapter/acts_as_geom.rb
+lib/postgis_adapter/common_spatial_adapter.rb
+lib/postgis_functions.rb
+lib/postgis_functions/bbox.rb
+lib/postgis_functions/class.rb
+lib/postgis_functions/common.rb
+lib/postgis_functions/linestring.rb
+lib/postgis_functions/point.rb
+lib/postgis_functions/polygon.rb
+postgis_adapter.gemspec
+rails/init.rb
+script/console
+script/destroy
+script/generate
+spec/acts_as_geom_spec.rb
+spec/common_spatial_adapter_spec.rb
+spec/db/database_postgis.yml
+spec/db/models_postgis.rb
+spec/db/schema_postgis.rb
+spec/postgis_adapter_spec.rb
+spec/postgis_functions/bbox_spec.rb
+spec/postgis_functions/linestring_spec.rb
+spec/postgis_functions/point_spec.rb
+spec/postgis_functions/polygon_spec.rb
+spec/postgis_functions_spec.rb
+spec/spec.opts
+spec/spec_helper.rb
+uninstall.rb

data/README.rdoc

@@ -0,0 +1,311 @@
+= PostgisAdapter
+
+A plugin for ActiveRecord which manages the 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.
+
+This fork adds handy methods to make geometrical calculations on postgis.
+
+Postgis Manual - http://postgis.refractions.net/documentation/manual-svn
+
+*PostGIS and Rails 2+ only*.
+
+
+=== Install
+
+If you are using Spatial Adapter, *remove it first*.
+
+
+==== Dependencies
+
+- georuby
+- postgres 8.3+
+- postgis  1.3+
+
+
+==== As gem:
+
+    sudo gem sources --add http://gems.github.com
+    sudo gem install nofxx-postgis_adapter
+  
+    config.gem "nofxx-postgis_adapter", :lib => "postgis_adapter", :source => "http://gems.github.com"
+    
+  
+==== As plugin:
+
+    script/plugin install git://github.com/nofxx/postgis_adapter.git
+
+
+=== How to Use
+
+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.
+
+
+=== Model
+
+    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.
+
+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(1,2))
+  	pt.save
+  	pt = TablePoint.first
+  	puts pt.geom.x
+  	=> 1
+
+
+== PostGIS Functions
+
+Here are this fork additions. To use it:
+
+
+    class Street < ActiveRecord::Base
+      acts_as_geom :line
+    end
+
+    ...
+
+    @place  =   Poi.new(    :data  =>   **Point**      )
+    @park   =   Park.new(   :area  =>  **Polygon**     )
+    @street =   Street.new( :line  => **LineString**   )
+
+
+=== Play!
+
+    @place.inside?(@park)
+    => true
+
+    @place.in_bounds?(@park, 0.5) # margin
+    => false
+
+    @place.outside?(@park)
+
+    @street.crosses?(@park)
+
+    @area.contains?(@place)
+    
+
+Polygons:
+
+    @park.area
+    => 1345
+
+    @park.contains?(@point)
+    => true
+
+    @park.overlaps?(@other_park)
+    => false
+    
+
+Line Strings:
+
+    @street_east.intersects?(@street_west)
+    => false
+
+    @street_central.length
+    => 4508.53636
+
+    @street_central.length(:miles)
+    => 2.81798593
+
+    @street.length_spheroid
+    => 4.40853636
+
+
+=== And for classes:
+
+    City.close_to(@point)
+    => [Array of cities in order by distance...
+
+    Street.close_to(@point)
+    => [Array streets in order by distance...
+
+    Country.contain(@point)
+    => The Conutry that contains the point
+
+    Areas.contains(@point)
+    => [Array of areas contains the point...
+
+
+=== BBox Support
+
+    @area.strictly_left_of? @point
+
+    @area.overlaps_or_above? @street
+
+    ...
+
+    completely_contained_by?
+    completely_contains?
+    overlaps_or_above?
+    overlaps_or_below?
+    overlaps_or_left_of?
+    overlaps_or_right_of?
+    strictly_above?
+    strictly_below?
+    strictly_left_of?
+    strictly_right_of?
+    interacts_with?
+    binary_equal?
+    same_as?
+
+
+Or use a (almost) postgis like notation:
+
+    @area.bbox "<<", @point
+
+    @area.bbox "|>>", @point
+
+    @area.bbox "@",  @park
+
+
+
+=== Warning
+
+*To be fixed:*
+
+This only supports one geom column per model. Still looking for the best way to
+implement a multi geom.
+
+http://nofxx.lighthouseapp.com/projects/20712/tickets/3-multiple-geoms-in-model
+
+
+=== Wiki
+
+Check out the wiki pages (http://github.com/nofxx/postgis_adapter/wikis).
+For all functions.
+
+
+=== 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])
+
+
+
+== Database Tools
+
+=== 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 :places do |t|
+        t.string :name
+      	t.point  :geom, :srid => 123, :with_z => true, :null => false
+    	 
+        t.timestamps
+      end
+  	  add_index :table_points, :geom, :spatial=>true
+    end
+
+
+=== 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_yaml+.
+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_yaml %>
+
+
+=== Annotate
+
+If you are using annotate_models, check out this fork which adds geometrical annotations for PostgisAdapter and SpatialAdapter:
+
+http://github.com/nofxx/annotate_models
+
+
+== Geometric data types
+
+Ruby geometric datatypes are currently made available only through
+the GeoRuby library (http://georuby.rubyforge.org): This is where the
+*Point.from_x_y* 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
+
+- 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.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.first
+       the_geom = place.the_geom
+       the_geom.y=123456.7
+       place.the_geom = the_geom
+
+
+== License
+
+Spatial Adapter for Rails is released under the MIT license.
+Postgis Adapter is released under the MIT license.
+
+
+== Support
+
+Tested using rails 2.2.2 / postgresql 8.3.5 / postgis 1.3.3 / linux / osx
+
+Any questions, enhancement proposals, bug notifications or corrections:
+
+
+=== PostgisAdapter
+
+Project Tracker http://nofxx.lighthouseapp.com/projects/20712-postgis_adapter
+
+
+=== SpatialAdapter
+
+
+guilhem.vellut+georuby@gmail.com.

data/Rakefile

@@ -0,0 +1,100 @@
+#$:.unshift(File.join(File.dirname(__FILE__) ,'../../gems/georuby/lib/'))
+$:.unshift(File.join(File.dirname(__FILE__), 'lib'))
+require 'rake'
+require 'spec/rake/spectask'
+require 'rake/rdoctask'
+require 'active_record'
+require 'active_record/connection_adapters/postgresql_adapter' 
+%w[rubygems rake rake/clean fileutils newgem rubigen].each { |f| require f }
+require File.dirname(__FILE__) + '/lib/postgis_adapter'
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)PostgisAdapter::VERSION
+$hoe = Hoe.new('postgis_adapter', PostgisAdapter::VERSION) do |p|
+  p.developer('Marcos Piccinini', 'x@nofxx.com')
+  p.summary = "Postgis Adapter for Activer Record"
+  p.description = "Postgis Adapter for Activer Record"
+  p.url = "http://github.com/nofxx/postgis_adapter"
+  p.changes              = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+#  p.post_install_message = 'PostInstall.txt' # TODO remove if post-install message not required
+  p.rubyforge_name       = "postgis_adapter" # TODO this is default value
+  p.extra_deps         = [
+     ['activerecord','>= 2.0.2'],
+  ]
+  p.extra_dev_deps = [
+    ['newgem', ">= #{::Newgem::VERSION}"]
+  ]
+  
+  p.clean_globs |= %w[**/.DS_Store tmp *.log]
+  path = (p.rubyforge_name == p.name) ? p.rubyforge_name : "\#{p.rubyforge_name}/\#{p.name}"
+  p.remote_rdoc_dir = File.join(path.gsub(/^#{p.rubyforge_name}\/?/,''), 'rdoc')
+  p.rsync_args = '-av --delete --ignore-errors'
+end
+
+require 'newgem/tasks' # load /tasks/*.rake
+Dir['tasks/**/*.rake'].each { |t| load t }
+
+# TODO - want other tests/tasks run by default? Add them to the list
+# task :default => [:spec, :features]
+
+desc 'Default: run specs.'
+task :default => :spec
+
+desc "Run all specs"
+Spec::Rake::SpecTask.new do |t|
+  t.spec_files = FileList['spec/*_spec.rb']
+  t.spec_opts = ['--options', 'spec/spec.opts']
+  unless ENV['NO_RCOV']
+    t.rcov = true
+    t.rcov_dir = 'coverage'
+    t.rcov_opts = ['--html', '--exclude', "\.autotest,schema.rb,init.rb,\.gitignore,spec\/spec_helper.rb,spec\/db/*,#{ENV['GEM_HOME']}"]
+  end
+end
+
+desc "Look for TODO and FIXME tags in the code"
+task :todo do
+  egrep /(FIXME|TODO|TBD)/
+end
+
+namespace :db do
+  task :migrate do
+    load('spec/db/schema_postgis.rb')
+  end
+end
+
+desc "Generate the documentation"
+Rake::RDocTask::new do |rdoc|
+  rdoc.rdoc_dir = 'doc/'
+  rdoc.title    = "PostGIS Adapter for Rails Documentation"
+  rdoc.options << '--line-numbers' << '--inline-source'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+# From Rspec Rakefile
+#
+def egrep(pattern)
+  Dir['**/*.rb'].each do |fn|
+    count = 0
+    open(fn) do |f|
+      while line = f.gets
+        count += 1
+        if line =~ pattern
+          puts "#{fn}:#{count}:#{line}"
+        end
+      end
+    end
+  end
+end
+
+desc "verify_committed, verify_rcov, post_news, release"
+task :complete_release => [:verify_committed, :post_news, :release]
+
+desc "Verifies that there is no uncommitted code"
+task :verify_committed do
+  IO.popen('git status') do |io|
+    io.each_line do |line|
+      raise "\n!!! Do a git commit first !!!\n\n" if line =~ /^#\s*modified:/
+    end
+  end
+end