# ----------------------------------------------------------------------------- # # Geometry feature interface # # ----------------------------------------------------------------------------- # Copyright 2010 Daniel Azuma # # All rights reserved. # # Redistribution and use in source and binary forms, with or without # modification, are permitted provided that the following conditions are met: # # * Redistributions of source code must retain the above copyright notice, # this list of conditions and the following disclaimer. # * Redistributions in binary form must reproduce the above copyright notice, # this list of conditions and the following disclaimer in the documentation # and/or other materials provided with the distribution. # * Neither the name of the copyright holder, nor the names of any other # contributors to this software, may be used to endorse or promote products # derived from this software without specific prior written permission. # # THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" # AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE # IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE # ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE # LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR # CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF # SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS # INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN # CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE # POSSIBILITY OF SUCH DAMAGE. # ----------------------------------------------------------------------------- ; module RGeo module Features # == SFS 1.1 Description # # Geometry is the root class of the hierarchy. Geometry is an abstract # (non-instantiable) class. # # The instantiable subclasses of Geometry defined in this International # Standard are restricted to 0, 1 and 2-dimensional geometric objects # that exist in 2-dimensional coordinate space (R2). # # All instantiable Geometry classes described in this part of ISO 19125 # are defined so that valid instances of a Geometry class are # topologically closed, i.e. all defined geometries include their # boundary. # # == Notes # # Geometry is defined as a module and is provided primarily for the # sake of documentation. Implementations need not necessarily include # this module itself. Therefore, you should not depend on the # kind_of? method to check type. Instead, use the provided check_type # class method (or === operator) defined in the Type module. # # Some implementations may support higher dimensional objects or # coordinate systems, despite the limits of the SFS. # # == Forms of equivalence # # The Geometry model defines three forms of equivalence. # # Spatial equivalence:: # Spatial equivalence is the weakest form of equivalence, indicating # that the two objects represent the same region of space, but may # be different representations of that region. For example, a # POINT(0 0) and a MULTIPOINT(0 0) are spatially equivalent, as are # LINESTRING(0 0, 10 10) and # GEOMETRYCOLLECTION(POINT(0 0), LINESTRING(0 0, 10 10, 0 0)). # As a general rule, objects must have factories that are eql? in # order to be spatially equivalent. # Objective equivalence:: # Objective equivalence is a stronger form of equivalence, indicating # that the two objects are the same representation, but may be # different objects. All objectively equivalent objects are spatially # equivalent, but not all spatially equivalent objects are # objectively equivalent. For example, none of the examples in the # spatial equivalence section above are objectively equivalent. # However, two separate objects that both represent POINT(1 2) are # objectively equivalent as well as spatially equivalent. # Objective identity:: # Objective identity is the strongest form, indicating that the two # references refer to the same object. Of course, all pairs of # references with the same objective identity are both objectively # equivalent and spatially equivalent. # # Different methods test for different types of equivalence: # # * <tt>equals?</tt> and <tt>==</tt> test for spatial equivalence. # * <tt>eql?</tt> tests for objective equivalence. # * <tt>equal?</tt> tests for objective identity. module Geometry extend Type # Returns a factory for creating features related to this one. # This does not necessarily need to be the same factory that created # this object, but it should create objects that are "compatible" # with this one. (i.e. they should be in the same spatial reference # system by default, and it should be possible to perform relational # operations on them.) def factory raise Errors::MethodUnimplemented end # Cast this geometry to the given type (which must be one of the # type modules in the Features module) and return the resulting # object. Returns nil if the cast fails because the types are not # compatible or the object does not satisfy the assertions for the # new type. # # Generally, this is only useful for casting general classes to # subclasses; e.g. a GeometryCollection to a MultiPoint, or a # LineString to a LinearRing. def cast(type_) raise Errors::MethodUnimplemented end # Returns true if this geometric object is objectively equivalent # to the given object. def eql?(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # The inherent dimension of this geometric object, which must be less # than or equal to the coordinate dimension. This specification is # restricted to geometries in 2-dimensional coordinate space. # # === Notes # # Returns an integer. This value is -1 for an empty geometry, 0 for # point geometries, 1 for curves, and 2 for surfaces. def dimension raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns the instantiable subtype of Geometry of which this # geometric object is an instantiable member. # # === Notes # # Returns one of the type modules in RGeo::Features. e.g. a point # object would return RGeo::Features::Point. Note that this is # different from the SFS specification, which stipulates that the # string name of the type is returned. To obtain the name string, # call the +name+ method of the returned module. def geometry_type raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns the Spatial Reference System ID for this geometric object. # # === Notes # # Returns an integer. # # This will normally be a foreign key to an index of reference systems # stored in either the same or some other datastore. def srid raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # The minimum bounding box for this Geometry, returned as a Geometry. # The polygon is defined by the corner points of the bounding box # [(MINX, MINY), (MAXX, MINY), (MAXX, MAXY), (MINX, MAXY), (MINX, MINY)]. # # === Notes # # Returns an object that supports the Geometry interface. def envelope raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Exports this geometric object to a specific Well-known Text # Representation of Geometry. # # === Notes # # Returns an ASCII string. def as_text raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Exports this geometric object to a specific Well-known Binary # Representation of Geometry. # # === Notes # # Returns a binary string. def as_binary raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object is the empty Geometry. If true, # then this geometric object represents the empty point set for the # coordinate space. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def is_empty? raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object has no anomalous geometric # points, such as self intersection or self tangency. The description # of each instantiable geometric class will include the specific # conditions that cause an instance of that class to be classified as # not simple. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def is_simple? raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns the closure of the combinatorial boundary of this geometric # object. Because the result of this function is a closure, and hence # topologically closed, the resulting boundary can be represented using # representational Geometry primitives. # # === Notes # # Returns an object that supports the Geometry interface. def boundary raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object is "spatially equal" to # another_geometry. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def equals?(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object is "spatially disjoint" from # another_geometry. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def disjoint?(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object "spatially intersects" # another_geometry. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def intersects?(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object "spatially touches" # another_geometry. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def touches?(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object "spatially crosses" # another_geometry. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def crosses?(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object is "spatially within" # another_geometry. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def within?(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object "spatially contains" # another_geometry. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def contains?(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object "spatially overlaps" # another_geometry. # # === Notes # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def overlaps?(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns true if this geometric object is spatially related to # another_geometry by testing for intersections between the interior, # boundary and exterior of the two geometric objects as specified by # the values in the intersection_pattern_matrix. # # === Notes # # The intersection_pattern_matrix is provided as a nine-character # string in row-major order, representing the dimensionalities of # the different intersections in the DE-9IM. Supported characters # include T, F, *, 0, 1, and 2. # # Returns a boolean value. Note that this is different from the SFS # specification, which stipulates an integer return value. def relate(another_geometry_, intersection_pattern_matrix_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns the shortest distance between any two Points in the two # geometric objects as calculated in the spatial reference system of # this geometric object. # # === Notes # # Returns a floating-point scalar value. def distance(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns a geometric object that represents all Points whose distance # from this geometric object is less than or equal to distance. # Calculations are in the spatial reference system of this geometric # object. # # === Notes # # Returns an object that supports the Geometry interface. def buffer(distance_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns a geometric object that represents the convex hull of this # geometric object. # # === Notes # # Returns an object that supports the Geometry interface. def convex_hull() raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns a geometric object that represents the Point set # intersection of this geometric object with another_geometry. # # === Notes # # Returns an object that supports the Geometry interface. def intersection(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns a geometric object that represents the Point set # union of this geometric object with another_geometry. # # === Notes # # Returns an object that supports the Geometry interface. def union(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns a geometric object that represents the Point set # difference of this geometric object with another_geometry. # # === Notes # # Returns an object that supports the Geometry interface. def difference(another_geometry_) raise Errors::MethodUnimplemented end # === SFS 1.1 Description # # Returns a geometric object that represents the Point set symmetric # difference of this geometric object with another_geometry. # # === Notes # # Returns an object that supports the Geometry interface. def sym_difference(another_geometry_) raise Errors::MethodUnimplemented end # Alias of the equals? method. def ==(rhs_) equals?(rhs_) end # Alias of the difference method. def -(rhs_) difference(rhs_) end # Alias of the union method. def +(rhs_) union(rhs_) end # Alias of the intersection method. def *(rhs_) intersection(rhs_) end end end end