diff --git a/lib/postgis_functions.rb b/lib/postgis_functions.rb index e78855c..eb07720 100644 --- a/lib/postgis_functions.rb +++ b/lib/postgis_functions.rb @@ -16,12 +16,10 @@ # Earth Spheroid - http://en.wikipedia.org/wiki/Figure_of_the_Earth # # +# module PostgisFunctions - - # Default Earth Spheroid - # # EARTH_SPHEROID = "'SPHEROID[\"GRS-80\",6378137,298.257222101]'" - # + EARTH_SPHEROID = "'SPHEROID[\"IERS_2003\",6378136.6,298.25642]'" def postgis_calculate(operation, subject, options = nil) @@ -33,8 +31,11 @@ def postgis_calculate(operation, subject, options = nil) # # COMMON GEOMETRICAL FUNCTIONS # + # The methods here can be used by all geoms. + # - # Returns true if the given geometries represent the same geometry. + # + # True if the given geometries represent the same geometry. # Directionality is ignored. # # Returns TRUE if the given Geometries are "spatially equal". @@ -45,14 +46,16 @@ def postgis_calculate(operation, subject, options = nil) # (it must be noted ST_OrderingEquals is a little more stringent than # simply verifying order of points are the same). # - # This function will return false if either geometry is invalid even if they are binary equal. + # This function will return false if either geometry is invalid even + # if they are binary equal. # - # Returns boolean ST_Equals(geometry A, geometry B); + # Returns Boolean ST_Equals(geometry A, geometry B); # def spatially_equal?(other) postgis_calculate(:equals, [self, other]) end + # # Returns the minimum bounding box for the supplied geometry, as a geometry. # The polygon is defined by the corner points of the bounding box # ((MINX, MINY), (MINX, MAXY), (MAXX, MAXY), (MAXX, MINY), (MINX, MINY)). @@ -70,12 +73,13 @@ def spatially_equal?(other) # But it also means that the bounding box is NOT the same as the minimum # bounding rectangle that bounds the geome. # - # Returns boolean ST_Envelope(geometry g1); + # Returns GeometryCollection ST_Envelope(geometry g1); # def envelope postgis_calculate(:envelope, self) end + # # Computes the geometric center of a geometry, or equivalently, # the center of mass of the geometry as a POINT. For [MULTI]POINTs, this is # computed as the arithmetric mean of the input coordinates. @@ -92,171 +96,217 @@ def envelope # # http://postgis.refractions.net/documentation/manual-svn/ST_Centroid.html # - # Returns geometry ST_Centroid(geometry g1); + # Returns Geometry ST_Centroid(geometry g1); # def centroid postgis_calculate(:centroid, self) end - - # Returns the closure of the combinatorial boundary of this Geometry. The - # combinatorial boundary is defined as described in section 3.12.3.2 of the + + # + # Returns the closure of the combinatorial boundary of this Geometry. + # The combinatorial boundary is defined as described in section 3.12.3.2 of the # OGC SPEC. Because the result of this function is a closure, and hence topologically # closed, the resulting boundary can be represented using representational # geometry primitives as discussed in the OGC SPEC, section 3.12.2. # - # Performed by the GEOS module - # Do not call with a GEOMETRYCOLLECTION as an argument + # Do not call with a GEOMETRYCOLLECTION as an argument. # - # Returns geometry ST_Boundary(geometry geomA); + # Performed by the GEOS module. + # + # Returns Geometry ST_Boundary(geometry geomA); # def boundary postgis_calculate(:boundary, self) end - # Returns the 2-dimensional minimum cartesian distance between two - # geometries in projected units. # - # Returns float ST_Distance(geometry g1, geometry g2); + # 2D minimum cartesian distance between two geometries in projected units. + # + # Returns Float ST_Distance(geometry g1, geometry g2); # def distance_to(other) postgis_calculate(:distance, [self, other]) end - - # Returns TRUE if geometry A is completely inside geometry B. + + # + # True if geometry A is completely inside geometry B. + # # For this function to make sense, the source geometries must both be of the same # coordinate projection, having the same SRID. It is a given that # if ST_Within(A,B) is true and ST_Within(B,A) is true, then the # two geometries are considered spatially equal. # - # Performed by the GEOS module - # Do not call with a GEOMETRYCOLLECTION as an argument - # Do not use this function with invalid geometries. You will get unexpected results. - # # This function call will automatically include a bounding box comparison that will # make use of any indexes that are available on the geometries. To avoid index use, # use the function _ST_Within. # - # Returns boolean ST_Within(geometry A, geometry B); + # Do not call with a GEOMETRYCOLLECTION as an argument + # Do not use this function with invalid geometries. You will get unexpected results. + # + # Performed by the GEOS module. + # + # Returns Boolean ST_Within(geometry A, geometry B); # def within? other postgis_calculate(:within, [self, other]) end - # Returns TRUE if geometry B is completely inside geometry A. For this function - # to make sense, the source geometries must both be of the same coordinate - # projection, having the same SRID. ST_Contains is the inverse of ST_Within. - # So ST_Contains(A,B) implies ST_Within(B,A) except in the case of invalid + # + # True if geometry B is completely inside geometry A. + # + # For this function to make sense, the source geometries must both be of the same + # coordinate projection, having the same SRID. 'contains?' is the inverse of 'within?'. + # + # So a.contains?(b) is like b.within?(a) except in the case of invalid # geometries where the result is always false regardless or not defined. # - # Performed by the GEOS module # Do not call with a GEOMETRYCOLLECTION as an argument # Do not use this function with invalid geometries. You will get unexpected results. # - # Returns boolean ST_Contains(geometry geomA, geometry geomB); + # Performed by the GEOS module + # + # Returns Boolean ST_Contains(geometry geomA, geometry geomB); # def contains? other postgis_calculate(:contains, [self, other]) end - - # True if no point in Geometry A is outside Geometry B + # - # Performed by the GEOS module - # Do not call with a GEOMETRYCOLLECTION as an argument - # Do not use this function with invalid geometries. You will get unexpected results. + # True if no point in Geometry A is outside Geometry B # # This function call will automatically include a bounding box comparison that # will make use of any indexes that are available on the geometries. To avoid # index use, use the function _ST_CoveredBy. # - # Returns boolean ST_CoveredBy(geometry geomA, geometry geomB); + # Do not call with a GEOMETRYCOLLECTION as an argument. + # Do not use this function with invalid geometries. You will get unexpected results. + # + # Performed by the GEOS module. + # + # Aliased as 'inside?' + # + # Returns Boolean ST_CoveredBy(geometry geomA, geometry geomB); # def covered_by? other postgis_calculate(:coveredby, [self, other]) end alias_method "inside?", "covered_by?" - - # Eye-candy. Returns boolean. + + # + # Eye-candy. See 'covered_by?'. + # + # Returns !(Boolean ST_CoveredBy(geometry geomA, geometry geomB);) + # def outside? other !covered_by? other end - # Returns how many dimensions the geom has (2, 3 or 4) + # + # True if the Geometries do not "spatially intersect" - if they + # do not share any space together. + # + # Overlaps, Touches, Within all imply geometries are not spatially disjoint. + # If any of the aforementioned returns true, then the geometries are not + # spatially disjoint. Disjoint implies false for spatial intersection. + # + # Do not call with a GEOMETRYCOLLECTION as an argument. + # + # Returns boolean ST_Disjoint( geometry A , geometry B ); + # + def disjoint? other + postgis_calculate(:disjoint, [self, other]) + end + + # + # How many dimensions the geom is made of (2, 3 or 4) + # + # Returns Integer ST_Dimension(geom g1) + # def dimension postgis_calculate(:dimension, self).to_i end + # # Returns a "simplified" version of the given geometry using the Douglas-Peuker # algorithm. Will actually do something only with (multi)lines and (multi)polygons # but you can safely call it with any kind of geometry. Since simplification # occurs on a object-by-object basis you can also feed a GeometryCollection to this # function. # - # Note that returned geometry might loose its simplicity (see ST_IsSimple) - # Note topology may not be preserved and may result in invalid geometries. - # Use (see ST_SimplifyPreserveTopology) to preserve topology. + # Note that returned geometry might loose its simplicity (see 'is_simple?'). + # Topology may not be preserved and may result in invalid geometries. + # Use 'simplify_preserve_topology' to preserve topology. # # Performed by the GEOS Module. # - # Returns geometry ST_Simplify(geometry geomA, float tolerance); + # Returns Geometry ST_Simplify(geometry geomA, float tolerance); # def simplify(tolerance=0.1) postgis_calculate(:simplify, self, tolerance) end + #TODO: #def simplify! + # # Returns a "simplified" version of the given geometry using the Douglas-Peuker # algorithm. Will avoid creating derived geometries (polygons in particular) that # are invalid. Will actually do something only with (multi)lines and (multi)polygons # but you can safely call it with any kind of geometry. Since simplification occurs # on a object-by-object basis you can also feed a GeometryCollection to this function. # - # Performed by the GEOS module. - # Requires GEOS 3.0.0+ + # Performed by the GEOS module. Requires GEOS 3.0.0+ # - # Returns geometry ST_SimplifyPreserveTopology(geometry geomA, float tolerance); + # Returns Geometry ST_SimplifyPreserveTopology(geometry geomA, float tolerance); # def simplify_preserve_topology(tolerance=0.1) postgis_calculate(:simplifypreservetopology, self, tolerance) end - # True if Geometries "spatially intersect" - (share any portion of space) + # + # True if Geometries "spatially intersect", share any portion of space. # False if they don't (they are Disjoint). - # Overlaps, Touches, Within all imply spatial intersection. + # + # 'overlaps?', 'touches?', 'within?' all imply spatial intersection. # If any of the aforementioned returns true, then the geometries also - # spatially intersect. Disjoint implies false for spatial intersection. + # spatially intersect. 'disjoint?' implies false for spatial intersection. # - # Returns boolean + # Returns Boolean ST_Intersects(geometry geomA, geometry geomB); # def intersects? other postgis_calculate(:intersects, [self, other]) end - # True if Geometries Envelopes "spatially intersect" - (share any portion of space) # - # Returns boolean + # True if a Geometry`s Envelope "spatially intersect", share any portion of space. + # + # It`s 'intersects?', for envelopes. + # + # Returns Boolean SE_EnvelopesIntersect(geometry geomA, geometry geomB); # def envelopes_intersect? other postgis_calculate(:se_envelopesintersect, [self, other]) end - # Returns a geometry that represents the point set intersection of the Geometries. + # + # Geometry that represents the point set intersection of the Geometries. # In other words - that portion of geometry A and geometry B that is shared between # the two geometries. If the geometries do not share any space (are disjoint), # then an empty geometry collection is returned. # - # ST_Intersection in conjunction with ST_Intersects is very useful for clipping + # 'intersection' in conjunction with intersects? is very useful for clipping # geometries such as in bounding box, buffer, region queries where you only want # to return that portion of a geometry that sits in a country or region of interest. # - # Do not call with a GEOMETRYCOLLECTION as an argument - # Performed by the GEOS module + # Do not call with a GEOMETRYCOLLECTION as an argument. + # Performed by the GEOS module. # - # Returns geometry ST_Intersection( geometry geomA , geometry geomB ); + # Returns Geometry ST_Intersection(geometry geomA, geometry geomB); # def intersection other postgis_calculate(:intersection, [self, other]) end - # Returns TRUE if the Geometries share space, are of the same dimension, but are + # + # True if the Geometries share space, are of the same dimension, but are # not completely contained by each other. They intersect, but one does not # completely contain another. # @@ -265,9 +315,9 @@ def intersection other # will make use of any indexes that are available on the geometries. To avoid # index use, use the function _ST_Overlaps. # - # Performed by the GEOS module + # Performed by the GEOS module. # - # Returns boolean ST_Overlaps(geometry A, geometry B); + # Returns Boolean ST_Overlaps(geometry A, geometry B); # def overlaps? other postgis_calculate(:overlaps, [self, other]) @@ -275,35 +325,38 @@ def overlaps? other ActiveRecord::StatementInvalid end - # Returns TRUE if the geometries have at least one point in common, + # True if the geometries have at least one point in common, # but their interiors do not intersect. # # If the only points in common between g1 and g2 lie in the union of the - # boundaries of g1 and g2. The ST_Touches relation applies to all Area/Area, + # boundaries of g1 and g2. The 'touches?' relation applies to all Area/Area, # Line/Line, Line/Area, Point/Area and Point/Line pairs of relationships, # but not to the Point/Point pair. # - # Returns boolean ST_Touches(geometry g1, geometry g2); + # Returns Boolean ST_Touches(geometry g1, geometry g2); # def touches? other postgis_calculate(:touches, [self, other]) end + # # The convex hull of a geometry represents the minimum closed geometry that # encloses all geometries within the set. + # # It is usually used with MULTI and Geometry Collections. Although it is not # an aggregate - you can use it in conjunction with ST_Collect to get the convex # hull of a set of points. ST_ConvexHull(ST_Collect(somepointfield)). # It is often used to determine an affected area based on a set of point observations. # - # Performed by the GEOS module + # Performed by the GEOS module. # # Returns Geometry ST_ConvexHull(geometry geomA); # def convex_hull postgis_calculate(:convexhull, self) end - + + # # Returns true if this Geometry has no anomalous geometric points, such as # self intersection or self tangency. # @@ -327,11 +380,18 @@ def is_simple? # # BBox # - # These operators utilize indexes. They compare - # bounding boxes of 2 geometries # + + # + # These operators utilize indexes. They compare geometries by bounding boxes. # - # A.bbox(">>", B) + # You can use the literal forms or call directly using the 'bbox' method. eg.: + # + # @point.bbox(">>", @area) + # @point.bbox("|&>", @area) + # + # + # Cheatsheet: # # A &< B (A overlaps or is to the left of B) # A &> B (A overlaps or is to the right of B) @@ -351,54 +411,93 @@ def bbox(operator, other) postgis_calculate(:bbox, [self, other], operator) end + # + # bbox literal method. + # def completely_contained_by? other bbox("@", other) end + # + # bbox literal method. + # def completely_contains? other bbox("~", other) end + # + # bbox literal method. + # def overlaps_or_above? other bbox("|&>", other) end + # + # bbox literal method. + # def overlaps_or_below? other bbox("&<|", other) end + # + # bbox literal method. + # def overlaps_or_left_of? other bbox("&<", other) end + # + # bbox literal method. + # def overlaps_or_right_of? other bbox("&>", other) end + # + # bbox literal method. + # def strictly_above? other bbox("|>>", other) end + # + # bbox literal method. + # def strictly_below? other bbox("<<|", other) end + # + # bbox literal method. + # def strictly_left_of? other bbox("<<", other) end + # + # bbox literal method. + # def strictly_right_of? other bbox(">>", other) end + # + # bbox literal method. + # def interacts_with? other bbox("&&", other) end + # + # bbox literal method. + # def binary_equal? other bbox("~=", other) end + # + # bbox literal method. + # def same_as? other bbox("=", other) end @@ -412,7 +511,8 @@ def same_as? other # module PointFunctions - # Returns true if the geometries are within the specified distance of one another. + # + # True if the geometries are within the specified distance of one another. # The distance is specified in units defined by the spatial reference system # of the geometries. For this function to make sense, the source geometries # must both be of the same coorindate projection, having the same SRID. @@ -424,6 +524,7 @@ def d_within?(other, margin=0.1) end alias_method "in_bounds?", "d_within?" + # # Returns a float between 0 and 1 representing the location of the closest point # on LineString to the given Point, as a fraction of total 2d line length. # @@ -438,18 +539,20 @@ def where_on_line line postgis_calculate(:line_locate_point, [line, self]) end - # Returns linear distance in meters between two lon/lat points. + # + # Linear distance in meters between two lon/lat points. # Uses a spherical earth and radius of 6370986 meters. # Faster than 'distance_spheroid', but less accurate. # # Only implemented for points. # - # Returns float ST_Distance_Sphere(geometry pointlonlatA, geometry pointlonlatB); + # Returns Float ST_Distance_Sphere(geometry pointlonlatA, geometry pointlonlatB); # def distance_sphere_to(other) dis = postgis_calculate(:distance_sphere, [self, other]) end + # # Calculates the distance on an ellipsoid. This is useful if the # coordinates of the geometry are in longitude/latitude and a length is # desired without reprojection. The ellipsoid is a separate database type and @@ -466,7 +569,7 @@ def distance_sphere_to(other) # # SPHEROID["IERS_2003",6378136.6,298.25642] # - # Returns Float + # Returns ST_Distance_Spheroid(geometry geomA, geometry geomB, spheroid); # def distance_spheroid_to(other, spheroid = EARTH_SPHEROID) postgis_calculate(:distance_spheroid, [self, other], spheroid) @@ -474,13 +577,14 @@ def distance_spheroid_to(other, spheroid = EARTH_SPHEROID) ActiveRecord::StatementInvalid end - # Returns the azimuth of the segment defined by the given Point geometries, + # + # The azimuth of the segment defined by the given Point geometries, # or NULL if the two points are coincident. Return value is in radians. # # The Azimuth is mathematical concept defined as the angle, in this case # measured in radian, between a reference plane and a point. # - # Returns float ST_Azimuth(geometry pointA, geometry pointB); + # Returns Float ST_Azimuth(geometry pointA, geometry pointB); # def azimuth other #TODO: return if not point/point @@ -489,9 +593,10 @@ def azimuth other ActiveRecord::StatementInvalid end + # # True if the geometry is a point and is inside the circle. # - # Returns boolean ST_point_inside_circle(geometry, float, float, float) + # Returns Boolean ST_point_inside_circle(geometry, float, float, float) # def inside_circle?(x,y,r) postgis_calculate(:point_inside_circle, self, [x,y,r]) @@ -562,16 +667,21 @@ def num_points postgis_calculate(:npoints, self).to_i end + # # Returns geometry start point. + # def start_point postgis_calculate(:startpoint, self) end - #Returns geometry last point. + # + # Returns geometry last point. + # def end_point postgis_calculate(:endpoint, self) end + # # Takes two geometry objects and returns TRUE if their intersection # "spatially cross", that is, the geometries have some, but not all interior # points in common. The intersection of the interiors of the geometries must @@ -581,12 +691,13 @@ def end_point # geometries. Otherwise, it returns FALSE. # # - # Returns boolean ST_Crosses(geometry g1, geometry g2); + # Returns Boolean ST_Crosses(geometry g1, geometry g2); # def crosses? other postgis_calculate(:crosses, [self, other]) end + # # Returns a float between 0 and 1 representing the location of the closest point # on LineString to the given Point, as a fraction of total 2d line length. # @@ -601,6 +712,7 @@ def locate_point point postgis_calculate(:line_locate_point, [self, point]) end + # # Returns a point interpolated along a line. First argument must be a LINESTRING. # Second argument is a float8 between 0 and 1 representing fraction of total # linestring length the point has to be located. @@ -608,10 +720,12 @@ def locate_point point # See ST_Line_Locate_Point for computing the line location nearest to a Point. # # Returns geometry ST_Line_Interpolate_Point(geometry a_linestring, float a_fraction); + # def interpolate_point(fraction) postgis_calculate(:line_interpolate_point, self, fraction) end + # # Return a linestring being a substring of the input one starting and ending # at the given fractions of total 2d length. Second and third arguments are # float8 values between 0 and 1. This only works with LINESTRINGs. To use @@ -642,37 +756,41 @@ def line_substring(s,e) # module PolygonFunctions + # # The area of the geometry if it is a polygon or multi-polygon. # Return the area measurement of an ST_Surface or ST_MultiSurface value. # Area is in the units of the spatial reference system. # - # Returns float ST_Area(geometry g1); + # Returns Float ST_Area(geometry g1); # def area postgis_calculate(:area, self) end + # # Returns the 2D perimeter of the geometry if it is a ST_Surface, ST_MultiSurface # (Polygon, Multipolygon). 0 is returned for non-areal geometries. For linestrings # use 'length'. Measurements are in the units of the spatial reference system of # the geometry. # - # Returns float ST_Perimeter(geometry g1); + # Returns Float ST_Perimeter(geometry g1); # def perimeter postgis_calculate(:perimeter, self) end + # # Returns the 3-dimensional perimeter of the geometry, if it is a polygon or multi-polygon. # If the geometry is 2-dimensional, then the 2-dimensional perimeter is returned. # - # Returns float ST_Perimeter3D(geometry geomA); + # Returns Float ST_Perimeter3D(geometry geomA); # def perimeter3d postgis_calculate(:perimeter3d, self) end - # True if the LINESTRING's start and end points are coincident. + # + # True if the LineString's start and end points are coincident. # # This method implements the OpenGIS Simple Features Implementation # Specification for SQL. @@ -686,36 +804,24 @@ def closed? end alias_method "is_closed?", "closed?" - # Returns 1 (TRUE) if no point in Geometry B is outside Geometry A # - # Perrformed by the GEOS module - # Do not call with a GEOMETRYCOLLECTION as an argument - # Do not use this function with invalid geometries. You will get unexpected results. + # True if no point in Geometry B is outside Geometry A # # This function call will automatically include a bounding box comparison # that will make use of any indexes that are available on the geometries. # To avoid index use, use the function _ST_Covers. # - # Returns boolean ST_Covers(geometry geomA, geometry geomB); + # Do not call with a GEOMETRYCOLLECTION as an argument + # Do not use this function with invalid geometries. You will get unexpected results. + # + # Performed by the GEOS module. + # + # Returns Boolean ST_Covers(geometry geomA, geometry geomB); # def covers? other postgis_calculate(:covers, [self, other]) end - # Returns TRUE if the Geometries do not "spatially intersect" - if they - # do not share any space together. - # - # Overlaps, Touches, Within all imply geometries are not spatially disjoint. - # If any of the aforementioned returns true, then the geometries are not - # spatially disjoint. Disjoint implies false for spatial intersection. - # - # Do not call with a GEOMETRYCOLLECTION as an argument - # - # Returns boolean ST_Disjoint( geometry A , geometry B ); - # - def disjoint? other - postgis_calculate(:disjoint, [self, other]) - end end ### diff --git a/spec/postgis_functions_spec.rb b/spec/postgis_functions_spec.rb index 52f01e6..7e60762 100644 --- a/spec/postgis_functions_spec.rb +++ b/spec/postgis_functions_spec.rb @@ -2,7 +2,9 @@ describe "PostgisFunctions" do before(:all) do - #load_schema + + + #load_schema class City < ActiveRecord::Base acts_as_geom :geom @@ -107,11 +109,11 @@ class CommonGeo < ActiveRecord::Base @p3.should_not be_in_bounds(@s1, 1) end - it "calculate another point azimuth??" do + it do @p1.azimuth(@p2).should be_close(0.785398163397448,0.000001) end - it "calculate linestring azimuth??" do + it do @p1.azimuth(@s2).should raise_error end @@ -126,6 +128,10 @@ class CommonGeo < ActiveRecord::Base it do @p1.should_not be_inside_circle(50,50,2) end + + it do + @p1.disjoint?(@s2).should be_true + end end @@ -291,6 +297,10 @@ class CommonGeo < ActiveRecord::Base it do @s1.simple?.should be_true end + + it do + @s1.disjoint?(@s2).should be_true + end end @@ -360,11 +370,6 @@ class CommonGeo < ActiveRecord::Base @c3.overlaps?(@c2).should raise_error # WHY?? end - it "city disjoint point?" do - pending - @c1.disjoint?(@s2).should be_false - end - it "should get a polygon for envelope" do @c2.envelope.should be_instance_of(Polygon) end @@ -406,7 +411,15 @@ class CommonGeo < ActiveRecord::Base it do @c2.should be_simple end - + + it do + @c2.disjoint?(@p2).should be_true + end + + # weird... + # it do + # @c1.disjoint?(@s2).should be_true + # end end