rgeo-dschee 0.5.4

data/lib/rgeo/feature/curve.rb

@@ -0,0 +1,111 @@
+# -----------------------------------------------------------------------------
+#
+# Curve feature interface
+#
+# -----------------------------------------------------------------------------
+
+module RGeo
+  module Feature
+    # == SFS 1.1 Description
+    #
+    # A Curve is a 1-dimensional geometric object usually stored as a
+    # sequence of Points, with the subtype of Curve specifying the form of
+    # the interpolation between Points. This part of ISO 19125 defines only
+    # one subclass of Curve, LineString, which uses linear interpolation
+    # between Points.
+    #
+    # A Curve is a 1-dimensional geometric object that is the homeomorphic
+    # image of a real, closed interval D=[a,b] under a mapping f:[a,b]->R2.
+    #
+    # A Curve is simple if it does not pass through the same Point twice.
+    #
+    # A Curve is closed if its start Point is equal to its end Point.
+    #
+    # The boundary of a closed Curve is empty.
+    #
+    # A Curve that is simple and closed is a Ring.
+    #
+    # The boundary of a non-closed Curve consists of its two end Points.
+    #
+    # A Curve is defined as topologically closed.
+    #
+    # == Notes
+    #
+    # Curve 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 points.
+
+    module Curve
+      include Geometry
+      extend Type
+
+      # === SFS 1.1 Description
+      #
+      # The length of this Curve in its associated spatial reference.
+      #
+      # === Notes
+      #
+      # Returns a floating-point scalar value.
+
+      def length
+        raise Error::UnsupportedOperation, "Method Curve#length not defined."
+      end
+
+      # === SFS 1.1 Description
+      #
+      # The start Point of this Curve.
+      #
+      # === Notes
+      #
+      # Returns an object that supports the Point interface.
+
+      def start_point
+        raise Error::UnsupportedOperation, "Method Curve#start_point not defined."
+      end
+
+      # === SFS 1.1 Description
+      #
+      # The end Point of this Curve.
+      #
+      # === Notes
+      #
+      # Returns an object that supports the Point interface.
+
+      def end_point
+        raise Error::UnsupportedOperation, "Method Curve#end_point not defined."
+      end
+
+      # === SFS 1.1 Description
+      #
+      # Returns true if this Curve is closed [StartPoint() = EndPoint()].
+      #
+      # === Notes
+      #
+      # Returns a boolean value. Note that this is different from the SFS
+      # specification, which stipulates an integer return value.
+
+      def is_closed?
+        raise Error::UnsupportedOperation, "Method Curve#is_closed? not defined."
+      end
+
+      # === SFS 1.1 Description
+      #
+      # Returns true if this Curve is closed [StartPoint() = EndPoint()]
+      # and this Curve is simple (does not pass through the same Point
+      # more than once).
+      #
+      # === Notes
+      #
+      # Returns a boolean value. Note that this is different from the SFS
+      # specification, which stipulates an integer return value.
+
+      def is_ring?
+        raise Error::UnsupportedOperation, "Method Curve#is_ring? not defined."
+      end
+    end
+  end
+end

data/lib/rgeo/feature/factory.rb

@@ -0,0 +1,278 @@
+# -----------------------------------------------------------------------------
+#
+# Feature factory interface
+#
+# -----------------------------------------------------------------------------
+
+module RGeo
+  module Feature
+    # This is a standard interface for factories of features.
+    # Generally, each Feature implementation will implement these
+    # methods as a standard way to create features.
+    #
+    # If the implementation is unable to create the given feature,
+    # it should generally return nil. Implementations may also choose to
+    # raise an exception on failure.
+    #
+    # Some implementations may extend this interface to provide facilities
+    # for creating additional objects according to the capabilities
+    # provided by that implementation. Examples might include
+    # higher-dimensional coordinates or additional subclasses not
+    # explicitly required by the Simple Features Specification.
+    #
+    # Factory 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 result
+    # of <tt>is_a?(Factory)</tt> to check type. However, to support
+    # testing for factory-ness, the <tt>Factory::Instance</tt> submodule
+    # is provided. All factory implementation classes MUST include
+    # <tt>Factory::Instance</tt>, and you may use it in <tt>is_a?</tt>,
+    # <tt>===</tt>, and case-when constructs.
+
+    module Factory
+      # All factory implementations MUST include this submodule.
+      # This serves as a marker that may be used to test an object for
+      # factory-ness.
+
+      module Instance
+      end
+
+      # Returns meta-information about this factory, by key. This
+      # information may involve support for optional functionality,
+      # properties of the coordinate system, or other characteristics.
+      #
+      # Each property has a symbolic name. Names that have no periods are
+      # considered well-known names and are reserved for use by RGeo. If
+      # you want to define your own properties, use a name that is
+      # namespaced with periods, such as <tt>:'mycompany.myprop'</tt>.
+      #
+      # Property values are dependent on the individual property.
+      # Generally, properties that involve testing for functionality
+      # should return true if the functionality is support, or false or
+      # nil if not. A property value could also invlove different values
+      # indicating different levels of support. In any case, the factory
+      # should return nil for property names it does not recognize. This
+      # value is considered the "default" or "no value" value.
+      #
+      # Currently defined well-known properties are:
+      #
+      # [<tt>:has_z_coordinate</tt>]
+      #   Set to true if geometries created by this factory include a Z
+      #   coordinate, and the Point#z method is available.
+      # [<tt>:has_m_coordinate</tt>]
+      #   Set to true if geometries created by this factory include a M
+      #   coordinate, and the Point#m method is available.
+      # [<tt>:is_cartesian</tt>]
+      #   Set to true if this Factory guarantees that it operates in
+      #   Cartesian geometry. If false or nil, no such guarantee is made,
+      #   though it is possible the geometries may still be Cartesian.
+      # [<tt>:is_geographic</tt>]
+      #   Set to true if this Factory's coordinate system is meant to be
+      #   interpreted as x=longitude and y=latitude. If false or nil, no
+      #   information is present about whether the coordinate system is
+      #   meant to be so interpreted.
+
+      def property(_name_)
+        nil
+      end
+
+      # Parse the given string in well-known-text format and return the
+      # resulting feature. Returns nil if the string couldn't be parsed.
+
+      def parse_wkt(_str_)
+        nil
+      end
+
+      # Parse the given string in well-known-binary format and return the
+      # resulting feature. Returns nil if the string couldn't be parsed.
+
+      def parse_wkb(_str_)
+        nil
+      end
+
+      # Create a feature of type Point.
+      # The x and y parameters should be Float values.
+      #
+      # The extra parameters should be the Z and/or M coordinates, if
+      # supported. If both Z and M coordinates are supported, Z should
+      # be passed first.
+
+      def point(_x_, _y_, *_extra_)
+        nil
+      end
+
+      # Create a feature of type LineString.
+      # The given points argument should be an Enumerable of Point
+      # objects, or objects that can be cast to Point.
+      #
+      # Although implementations are free to attempt to handle input
+      # objects that are not of this factory, strictly speaking, the
+      # result of building geometries from objects of the wrong factory
+      # is undefined.
+
+      def line_string(_points_)
+        nil
+      end
+
+      # Create a feature of type Line.
+      # The given point arguments should be Point objects, or objects
+      # that can be cast to Point.
+      #
+      # Although implementations are free to attempt to handle input
+      # objects that are not of this factory, strictly speaking, the
+      # result of building geometries from objects of the wrong factory
+      # is undefined.
+
+      def line(_start_, _end_)
+        nil
+      end
+
+      # Create a feature of type LinearRing.
+      # The given points argument should be an Enumerable of Point
+      # objects, or objects that can be cast to Point.
+      # If the first and last points are not equal, the ring is
+      # automatically closed by appending the first point to the end of the
+      # string.
+      #
+      # Although implementations are free to attempt to handle input
+      # objects that are not of this factory, strictly speaking, the
+      # result of building geometries from objects of the wrong factory
+      # is undefined.
+
+      def linear_ring(_points_)
+        nil
+      end
+
+      # Create a feature of type Polygon.
+      # The outer_ring should be a LinearRing, or an object that can be
+      # cast to LinearRing.
+      # The inner_rings should be a possibly empty Enumerable of
+      # LinearRing (or objects that can be casted to LinearRing).
+      # You may also pass nil to indicate no inner rings.
+      #
+      # Although implementations are free to attempt to handle input
+      # objects that are not of this factory, strictly speaking, the
+      # result of building geometries from objects of the wrong factory
+      # is undefined.
+
+      def polygon(_outer_ring_, _inner_rings_ = nil)
+        nil
+      end
+
+      # Create a feature of type GeometryCollection.
+      # The elems should be an Enumerable of Geometry objects.
+      #
+      # Although implementations are free to attempt to handle input
+      # objects that are not of this factory, strictly speaking, the
+      # result of building geometries from objects of the wrong factory
+      # is undefined.
+
+      def collection(_elems_)
+        nil
+      end
+
+      # Create a feature of type MultiPoint.
+      # The elems should be an Enumerable of Point objects, or objects
+      # that can be cast to Point.
+      # Returns nil if any of the contained geometries is not a Point,
+      # which would break the MultiPoint contract.
+      #
+      # Although implementations are free to attempt to handle input
+      # objects that are not of this factory, strictly speaking, the
+      # result of building geometries from objects of the wrong factory
+      # is undefined.
+
+      def multi_point(_elems_)
+        nil
+      end
+
+      # Create a feature of type MultiLineString.
+      # The elems should be an Enumerable of objects that are or can be
+      # cast to LineString or any of its subclasses.
+      # Returns nil if any of the contained geometries is not a
+      # LineString, which would break the MultiLineString contract.
+      #
+      # Although implementations are free to attempt to handle input
+      # objects that are not of this factory, strictly speaking, the
+      # result of building geometries from objects of the wrong factory
+      # is undefined.
+
+      def multi_line_string(_elems_)
+        nil
+      end
+
+      # Create a feature of type MultiPolygon.
+      # The elems should be an Enumerable of objects that are or can be
+      # cast to Polygon or any of its subclasses.
+      # Returns nil if any of the contained geometries is not a Polygon,
+      # which would break the MultiPolygon contract.
+      # Also returns nil if any of the other assertions for MultiPolygon
+      # are not met, e.g. if any of the polygons overlap.
+      #
+      # Although implementations are free to attempt to handle input
+      # objects that are not of this factory, strictly speaking, the
+      # result of building geometries from objects of the wrong factory
+      # is undefined.
+
+      def multi_polygon(_elems_)
+        nil
+      end
+
+      # Returns a RGeo::CoordSys::Proj4 representing the projection for
+      # the coordinate system of features created by this factory, or nil
+      # if there is no such proj4 projection.
+
+      def proj4
+        nil
+      end
+
+      # Returns the coordinate system specification for the features
+      # created by this factory, or nil if there is no such coordinate
+      # system.
+      #
+      # NOTE: This is a required method of the factory interface, but the
+      # coordinate system classes themselves are not yet available, so
+      # implementations should just return nil for now.
+
+      def coord_sys
+        nil
+      end
+
+      # This is an optional method that may be implemented to customize
+      # casting for this factory. Basically, RGeo defines standard ways
+      # to cast certain types of objects from one factory to another and
+      # one SFS type to another. However, a factory may choose to
+      # override how things are casted TO its implementation using this
+      # method. It can do this to optimize certain casting cases, or
+      # implement special cases particular to this factory.
+      #
+      # This method will be called (if defined) on the destination
+      # factory, and will be passed the original object (which may or may
+      # not already be created by this factory), the SFS feature type
+      # (which again may or may not already be the type of the original
+      # object), and a hash of additional flags. These flags are:
+      #
+      # [<tt>:keep_subtype</tt>]
+      #   indicates whether to keep the subtype if casting to a supertype
+      #   of the current type
+      # [<tt>:force_new</tt>]
+      #   indicates whether to force the creation of a new object even if
+      #   the original is already of the desired factory and type
+      # [<tt>:project</tt>]
+      #   indicates whether to project the coordinates from the source to
+      #   the destination proj4 coordinate system, if available
+      #
+      # It should return either a casted result object, false, or nil.
+      # A nil return value indicates that casting should be forced to
+      # fail (and RGeo::Feature.cast will return nil).
+      # A false return value indicates that this method declines to
+      # override the casting algorithm, and RGeo should use its default
+      # algorithm to cast the object. Therefore, by default, you should
+      # return false.
+
+      def override_cast(_original_, _type_, _flags_)
+        false
+      end
+    end
+  end
+end

data/lib/rgeo/feature/factory_generator.rb

@@ -0,0 +1,96 @@
+# -----------------------------------------------------------------------------
+#
+# Feature factory interface
+#
+# -----------------------------------------------------------------------------
+
+module RGeo
+  module Feature
+    # A FactoryGenerator is a callable object (usually a Proc) that
+    # takes a configuration as a hash and returns a factory. These are
+    # often used, e.g., by parsers to determine what factory the parsed
+    # geometry should have.
+    #
+    # See the call method for a list of common configuration parameters.
+    # Different generators will support different parameters. There is
+    # no mechanism defined to reflect on the parameters understood by a
+    # factory generator.
+    #
+    # Many of the implementations provide a factory method for creating
+    # factories. For example, RGeo::Cartesian.preferred_factory can be
+    # called to create a factory using the preferred Cartesian
+    # implementation. Thus, to get a corresponding factory generator,
+    # you can use the <tt>method</tt> method. e.g.
+    #
+    #  factory_generator = ::RGeo::Cartesian.method(:preferred_factory)
+    #
+    # FactoryGenerator 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 determine if an object is a
+    # factory generator.
+
+    module FactoryGenerator
+      # Generate a factory given a configuration as a hash.
+      #
+      # If the generator does not recognize or does not support a given
+      # configuration value, the behavior is usually determined by the
+      # <tt>:strict</tt> configuration element. If <tt>strict</tt> is
+      # set to true, the generator should fail fast by returning nil or
+      # raising an exception. If it is set to false, the generator should
+      # attempt to do the best it can, even if it means returning a
+      # factory that does not match the requested configuration.
+      #
+      # Common parameters are as follows. These are intended as a
+      # recommendation only. There is no hard requirement for any
+      # particular factory generator to support them.
+      #
+      # [<tt>:strict</tt>]
+      #   If true, return nil or raise an exception if any configuration
+      #   was not recognized or not supportable. Otherwise, if false,
+      #   the generator should attempt to do its best to return some
+      #   viable factory, even if it does not strictly match the
+      #   requested configuration. Default is usually false.
+      # [<tt>:srid</tt>]
+      #   The SRID for the factory and objects it creates.
+      #   Default is usually 0.
+      # [<tt>:proj4</tt>]
+      #   The coordinate system in Proj4 format, either as a
+      #   CoordSys::Proj4 object or as a string or hash representing the
+      #   proj4 format. This is usually an optional parameter; the default
+      #   is usually nil.
+      # [<tt>:coord_sys</tt>]
+      #   The coordinate system in OGC form, either as a subclass of
+      #   CoordSys::CS::CoordinateSystem, or as a string in WKT format.
+      #   This is usually an optional parameter; the default is usually
+      #   nil.
+      # [<tt>:srs_database</tt>]
+      #   If provided, look up the Proj4 and OGC coordinate systems from
+      #   the given database and SRID.
+      # [<tt>:has_z_coordinate</tt>]
+      #   Support Z coordinates. Default is usually false.
+      # [<tt>:has_m_coordinate</tt>]
+      #   Support M coordinates. Default is usually false.
+
+      def call(_config_ = {})
+        nil
+      end
+
+      # Return a new FactoryGenerator that always returns the given
+      # factory.
+
+      def self.single(factory_)
+        ::Proc.new { |_c_| factory_ }
+      end
+
+      # Return a new FactoryGenerator that calls the given delegate, but
+      # modifies the configuration passed to it. You can provide defaults
+      # for configuration values not explicitly specified, and you can
+      # force certain values to override the given configuration.
+
+      def self.decorate(delegate_, default_config_ = {}, force_config_ = {})
+        ::Proc.new { |c_| delegate_.call(default_config_.merge(c_).merge(force_config_)) }
+      end
+    end
+  end
+end