rgeo 0.2.4 → 0.2.5

data/History.rdoc

@@ -1,3 +1,8 @@
+=== 0.2.5 / 2011-03-21
+
+* Line segment intersection tests in the simple cartesian implementations were failing for a few cases involving collinear segments. Fixed. (Reported by Dimitry Solovyov.)
+* Argument hash RDocs should be more readable.
+
 === 0.2.4 / 2010-12-31
 
 * Several bugs were preventing the low-level Proj4 transform functions from working at all. Fixed. (Reported by mRg.)

data/Spatial_Programming_With_RGeo.rdoc

@@ -1,7 +1,7 @@
 = An Introduction to Spatial Programming With RGeo
 
 * by Daniel Azuma
-* version 0.2 (7 Dec 2010)
+* version 0.3 (17 Feb 2011)
 
 == Introduction
 
@@ -18,7 +18,7 @@ The contents of this document are as follows.
 * Section 5 covers the most common open source spatial databases.
 * Section 6 briefly covers interoperability with location services and other externally-sourced geospatial data.
 
-Geographic information systems (GIS) is a broad and highly sophisticated field, and this introduction will only scratch the surface of the current state of the art. The goal is not to be comprehensive, but to summarize the important elements, and reference outside resources for readers that want more detailed information.
+Geographic information systems (GIS) is a broad and highly sophisticated field, and this introduction will only scratch the surface of the current state of the art. The goal is not to be comprehensive, but to summarize the important elements, and reference outside resources for readers seeking more detailed information.
 
 === About The Author
 
@@ -28,9 +28,9 @@ Geographic information systems (GIS) is a broad and highly sophisticated field,
 
 === 1.1. Why Spatial Programming?
 
-By 2010, location had established itself as one of the hottest emerging technological trends. In January, a Juniper Research report predicted that mobile location services alone could drive revenues of nearly $13 billion by 2014 (see {TechCrunch article}[http://techcrunch.com/2010/02/23/location-based-services-revenue/]), while location dominated new feature offerings from startups and giants such as Facebook and Twitter alike. Although the underlying disciplines of cartography and geographic information systems (GIS) have been around for several decades, they have broken into mainstream consumer technology only very recently. This has largely been due to a few key developments, notably, the success of mapping applications beginning with Google Maps, and the ubiquity of mobile GPS devices especially in mobile phones.
+By 2010, location had established itself as one of the hottest emerging technological trends. In January, a Juniper Research report predicted that mobile location services alone could drive revenues of nearly $13 billion by 2014 (see {TechCrunch article}[http://techcrunch.com/2010/02/23/location-based-services-revenue/]), while location dominated new feature offerings from a myriad of startups as well as from giants such as Facebook and Twitter. Although the underlying disciplines of computer-assisted cartography and geographic information systems (GIS) have been around for several decades, they have broken into mainstream consumer technology only very recently. This has largely been due to a few key developments, notably, the success of online mapping applications beginning with Google Maps, and the ubiquity of mobile GPS devices especially in mobile phones.
 
-Despite this growing interest, location-aware applications remain difficult to develop because the concepts and techniques involved are only beginning to make their way into the mainstream developer consciousness and tools. Working with location data requires techniques beyond the document-oriented or relational data typically used in a web application. The primary purpose of this document is to cover the basics that a Ruby developer needs to know when developing with location data, and to introduce the tools that are available.
+Despite this growing interest, location-aware applications remain difficult to develop because the concepts and techniques involved are only beginning to make their way into the mainstream developer consciousness and tools. The primary purpose of this document is to cover the basics that a Ruby or Ruby On Rails developer needs to know when developing with location data, and to introduce the tools and resources that are available.
 
 === 1.2. The Emerging Spatial Ecosystem
 
@@ -40,7 +40,7 @@ Visualization tools have advanced considerably in recent years. Mapping services
 
 Most major relational databases now support spatial extensions. The {MySQL}[http://mysql.com/] database provides basic spatial column support out of the box. Third-party add-on libraries exist for {Sqlite3}[http://www.sqlite.org/] and {PostgreSQL}[http://www.postgresql.org/] in the form of {SpatiaLite}[http://www.gaia-gis.it/spatialite/] and {PostGIS}[http://www.postgis.org/], respectively. Commercial databases such as Oracle and Microsoft SQL Server also provide facilities for storing and querying spatial data. Spatial features are also appearing in non-relational data stores. {MongoDB}[http://www.mongodb.org/] recently introduced geospatial indexing, {Solr}[http://lucene.apache.org/solr/] is expected to support spatial queries in the next release of its Lucene-based search engine, and {Sphinx}[http://sphinxsearch.com/] also provides limited spatial search capabilities.
 
-A variety of data services have also appeared. Geocoding, the process approximating a latitude/longitude coordinate from a street address, is now offered by most major mapping service vendors such as {Google}[http://code.google.com/apis/maps/documentation/geocoding/], {Microsoft}[http://www.microsoft.com/maps/developers/], and {Yahoo}[http://developer.yahoo.com/geo/placefinder/]. Place databases with geocoded business and major location listings are now also available from a variety of vendors. {SimpleGeo}[http://www.simplegeo.com/] is a relatively new service for cloud-based storage and querying of custom location data.
+A variety of data services have also appeared. Geocoding, the process approximating a latitude/longitude coordinate from a street address, is now offered by most major mapping service vendors such as {Google}[http://code.google.com/apis/maps/documentation/geocoding/], {Microsoft}[http://www.microsoft.com/maps/developers/], and {Yahoo}[http://developer.yahoo.com/geo/placefinder/]. Place databases with geocoded business and major location listings are now also available from a variety of vendors. Several services, notably {SimpleGeo}[http://www.simplegeo.com/], have recently appeared for cloud-based storage and querying of custom location data.
 
 Integrating these existing services in a web application is often a challenge, but a few integration libraries and frameworks do exist. {GeoDjango}[http://geodjango.org/] is an add-on for the Python-based Django web framework for building location-based applications. {RGeo}[http://github.com/dazuma/rgeo] is a suite of libraries for Ruby that can perform the same function for Ruby on Rails.
 
@@ -50,7 +50,7 @@ Perhaps most important of all, however, are the organizations that have appeared
 
 Ruby developers have had access to a fair number of spatial tools, primarily integration libraries for external services. {Geokit}[http://geokit.rubyforge.org/] provides a common interface for querying geocoding services, and a basic ActiveRecord extension for simple spatial queries. {YM4R}[http://ym4r.rubyforge.org/] provides a simple interface for integrating the Google and Yahoo map visualization tools in a Ruby application. Finally, {GeoRuby}[http://georuby.rubyforge.org/] provides classes for basic spatial data types such as points, lines, and polygons, and the add-on library {spatial_adapter}[http://github.com/fragility/spatial_adapter] hacks a few of the popular ActiveRecord database adapters to support spatial columns in the database.
 
-In this document, we will use {RGeo}[http://github.com/dazuma/rgeo], a new spatial data library for Ruby that provides a complete and robust implementation of the standard OGC spatial data types and operations. It covers some of the same functionality as GeoRuby and spatial_adapter. However, where GeoRuby implements only a minimal subset of the OGC feature interfaces, \RGeo supports the entire specification, as well as providing many features and extensions not available with the older libraries.
+In this document, we will cover {RGeo}[http://github.com/dazuma/rgeo], a new spatial data library for Ruby that provides a complete and robust implementation of the standard OGC spatial data types and operations. It covers some of the same functionality as GeoRuby and spatial_adapter. However, where GeoRuby implements only a minimal subset of the OGC feature interfaces, \RGeo supports the entire specification, as well as providing many features and extensions not available with the older libraries.
 
 \RGeo comprises several libraries, distributed as gems: a core library, and a suite of optional add-on modules. The core library, distributed as the {rgeo}[http://github.com/dazuma/rgeo] gem, includes the spatial data implementation itself. Currently available add-on modules include {rgeo-geojson}[http://github.com/dazuma/rgeo-geojson], which reads and writes the {GeoJSON}[http://www.geojson.org/] format, and {rgeo-shapefile}[http://github.com/dazuma/rgeo-shapefile], which reads ESRI shapefiles. A number of ActiveRecord adapters also utilize \RGeo to communicate with spatial databases; these include {mysqlspatial}[http://github.com/dazuma/activerecord-mysqlspatial-adapter], {mysql2spatial}[http://github.com/dazuma/activerecord-mysql2spatial-adapter], {spatialite}[http://github.com/dazuma/activerecord-spatialite-adapter], and {postgis}[http://github.com/dazuma/activerecord-postgis-adapter].
 
@@ -60,7 +60,7 @@ This section will cover the standard types of spatial data used in geospatial ap
 
 === 2.1. The Simple Features Specification
 
-The Open Geospatial Consortium (OGC) defines and publishes a specification entitled "{Geographic information -- Simple feature access}[http://www.opengeospatial.org/standards/sfa]", which defines, among other things, a set of spatial data types and operations that can be done on them. This standard, which we will refer to as the Simple Features Specification (SFS), defines the core interfaces used by most spatial applications and databases. Although more recent versions of the spec are now available, most current implementations, including \RGeo, follow version 1.1 of the SFS, and this is the specification we will cover here.
+The Open Geospatial Consortium (OGC) defines and publishes a specification entitled "{Geographic information -- Simple feature access}[http://www.opengeospatial.org/standards/sfa]", which defines, among other things, a set of spatial data types and operations that can be done on them. This standard, which we will refer to as the Simple Features Specification (SFS), defines the core types and interfaces used by most spatial applications and databases. Although more recent versions of the spec are now available, most current implementations, including \RGeo, follow version 1.1 of the SFS, and this is the specification we will cover here.
 
 A "feature" in the SFS is a geometric object in 2 or 3 dimensional space. These objects can be points, lines, curves, surfaces, and polygons-- in general, most 0, 1, or 2 dimensional objects are supported. Each of these objects is identified by coordinates (X, Y, and sometimes Z), and has an object-oriented interface associated with it, defining a set of operations that can be done. In \RGeo, these interfaces exist as modules in the RGeo::Feature namespace.
 
@@ -80,7 +80,7 @@ An SFS "Point" is a single 0-dimensional point in space. Points are typically us
 
 An SFS "LineString" is a set of one or more connected line segments representing a single continuous, piecewise linear path. It could, for example, represent the path of a single street, the full driving directions from one point to another, or the path of a waterway. It is defined by connecting a series of points in order with line segments, and you can retrieve those points from the LineString object.
 
-LineString itself has two subclases, Line and LinearRing. Line is restricted to a single line segment (i.e. two points). LinearRing is a "closed" LineString, where the two endpoints are the same point.
+LineString itself has two subclases, Line and LinearRing. Line is restricted to a single line segment (i.e. two points). LinearRing is a "closed" LineString, in which the two endpoints are coincident.
 
 (LineString is actually a subclass of the more general abstract class "Curve", which need not be piecewise linear. However, Curve is not by itself instantiable, and the current SFS version does not actually specify another type of instantiable Curve that is not a LineString.)
 
@@ -114,9 +114,9 @@ For complete details on the geometry class hierarchy, download the actual {Simpl
 
 === 2.10. \RGeo Geometry Factories
 
-The data types we have covered here are actually merely interface specifications. \RGeo actually provides several different implementations of these data type interfaces, intended for different use cases. For example, the RGeo::Geos implementation is \RGeo's main implementation which provides every data type and every operation defined by the SFS. However, that implementation requires a third-party C library, GEOS, to be installed. In cases where that library is not available, \RGeo provides an alternative, the Simple Cartesian implementation, which is a pure Ruby implementation that provides every data type but does not implement some of the more advanced geometric operations. \RGeo also provides further implementations that are designed specifically to work with geographic (longitude/latitude) coordinates, and different projections and ways of performing calculations on the earth's surface. These different implementations are described in more detail in the section on Coordinate Systems and Projections.
+The data types we have covered here are actually merely interface specifications. \RGeo provides several different concrete implementations of these data type interfaces, intended for different use cases. For example, the RGeo::Geos implementation is \RGeo's main implementation which provides every data type and every operation defined by the SFS. However, that implementation requires a third-party C library, GEOS, to be installed. In cases where that library is not available, \RGeo provides an alternative, the Simple Cartesian implementation, which is a pure Ruby implementation that provides every data type but does not implement some of the more advanced geometric operations. \RGeo also provides further implementations that are designed specifically to work with geographic (longitude/latitude) coordinates, and different projections and ways of performing calculations on the earth's surface. These different implementations are described in more detail in the section on Coordinate Systems and Projections.
 
-A particular implementation of these spatial data types is represented in \RGeo by a factory. A factory is an object that represents the coordinate system and other settings for that implementation, and provides methods for creating the actual geometric objects, as defined in the RGeo::Feature::Factory interface. For example:
+Each concrete implementation is represented in \RGeo by a factory. A factory is an object that represents the coordinate system and other settings for that implementation. It also provides methods for creating actual geometric objects for that implementation, as defined in the RGeo::Feature::Factory interface. For example:
 
  factory = get_my_factory()
  point1 = factory.point(1, 2)
@@ -168,7 +168,7 @@ A second common property of geometry objects is "simplicity", which basically me
 
 All geometry objects also contain a "spatial reference ID", returned by the <tt>Geometry#srid</tt> method. This is an external ID reference indicating the "spatial reference system", or coordinate system in use by the geometry. See the section on Coordinate Systems and Projections for further discussion.
 
-=== 3.2. Equality and Comparisons
+=== 3.2. Relational Operations
 
 The SFS specifies a suite of comparison operations that test geometric objects for such relational predicates as equality, overlap, containment, and so forth. In \RGeo, these operations are implemented by methods that return booleans. e.g.
 
@@ -204,7 +204,7 @@ Similarly, \RGeo's equality checking comes in several forms: geometric equality,
  p1.equals?(p2)  # => false
  p1.equals?(p1)  # => true
 
-=== 3.3. Combinations
+=== 3.3. Binary Spatial Operations
 
 The SFS also provides several operations that take two geometries and yield a third. For example, you can calculate the intersection, union, or difference between two geometries. In addition to the methods specified by the SFS interfaces, \RGeo provides operators for some of these calculations.
 
@@ -216,7 +216,7 @@ The SFS also provides several operations that take two geometries and yield a th
  diff = p1.difference(p2)  # or p1 - p2
  diff.is_empty?            # returns true
 
-=== 3.4. Boundaries, Envelopes, etc.
+=== 3.4. Unary Spatial Operations
 
 Methods are provided to compute the boundary of an object, the envelope (i.e. the bounding box), and the convex hull. In addition, there is a "buffer" method that attempts to return a polygon approximating the area within a given distance from the object. Note that, because the SFS does not yet define any geometric types with curved edges, most buffers will be polygonal approximations.
 
@@ -255,11 +255,11 @@ Note that there are several key shortcomings in the WKT and WKB formats as stric
 
 So far, we have discussed geometric data and operations mostly without reference to coordinate system. However, coordinate system is a critical component for interpreting what a piece of data means. If you have a point (1, 2), are the 1 and 2 measured in meters? Miles? Degrees? And where are they measured from? What is the origin (0, 0), and what directions do X and Y represent?
 
-Generally, the spatial technologies we're discussing are used to represent location, objects on the eart's surface. In this section, we'll cover the coordinate systems that you'll use for geolocation, as well as the issues you'll face.
+Generally, the spatial technologies we're discussing are used to represent location, objects on the earth's surface. In this section, we'll cover the coordinate systems that you'll use for geolocation, as well as the issues you'll face.
 
 === 4.1. The World is Not Flat
 
-First off, most of us agree that the earth is not flat, but shaped as something resembling a slightly flattened ball. This immediately results in a whole host of complications when dealing with geometric objects on the earth's surface. Distance can't quite be computed accurately using the familiar formulas you learned in high school geometry. Lines that start off parallel will eventually cross. And if you try to display things on a flat computer monitor, you will end up with various kinds of distortion.
+First off, most of us agree that the earth is not flat, but has a shape resembling a slightly flattened ball. This immediately results in a whole host of complications when dealing with geometric objects on the earth's surface. Distance can't quite be computed accurately using the familiar formulas you learned in high school geometry. Lines that start off parallel will eventually cross. And if you try to display things on a flat computer monitor, you will end up with various kinds of distortion.
 
 Let's take a simple example. Suppose we have a simple LineString with two points: starting in Vancouver, Canada, and ending in Frankfurt, Germany, both located at around 50 degrees north latitude. The LineString would consist of a straight line between those two points. But what is meant by "straight"? Does the shape follow the 50 degrees north latitude line, passing through Newfoundland? Or does it follow the actual shortest path on the globe, which passes much further north, close to Reykjavik, Iceland? (For a detailed explanation, see Morten Nielsen's post {"Straight Lines on a Sphere"}[http://www.sharpgis.net/post/2008/01/12/Straight-lines-on-a-sphere.aspx], which also includes some helpful diagrams.) If you were to call the SFS "distance" function to measure the distance between this LineString and a Point located at Reykjavik, what would you get?
 
@@ -289,7 +289,7 @@ Does this matter in your application? The answer is, it depends: on what kind of
 
 === 4.3. Geodetic and Projection Parameters
 
-This subsection covers some more advanced topics that most developers may not need to deal with directly, but I believe it is important to have at least a conceptual understanding of them.
+This subsection covers some more advanced topics that most developers may not need to deal with directly, but I believe it is important to have at least a high-level understanding of them.
 
 Simply put, there's more to a coordinate system than just the type: geocentric, geographic, or projected. For a geocentric coordinate system, we know it's centered at the center of the earth, but where _is_ the center of the earth? Which direction do the axes point? And do we measure the units in meters, miles, or light-years? For a geographic coordinate system, again, we need a center and orientation (i.e. where is the "zero longitude" line?), but we also need to define specifically _which_ "latitude". The latitude commonly used is the "geodetic latitude", which is the angle between the equator and what is normal (i.e. vertical) to the surface of the earth. This means it is dependent on one's model of the earth's surface, whether you use a sphere or a flattened ellipsoid, and how much flattening you choose. The same location on the earth's surface may have different latitudes depending on which system you use! As for projected systems, not only do we need to specify which projection to use (and there are hundreds defined), but we also need to know which geographic (latitude-longitude) system to start from. That is, a map projection is merely a function mapping latitude/longitude to flat coordinates, so we need to specify _which_ latitude/longitude.
 
@@ -311,7 +311,7 @@ What about Google and Bing maps? They use a combination of two coordinate system
 
 === 4.4. Using Proj4
 
-Under most circumstances, when you're working with geographic data in \RGeo, you can probably use either the spherical factory (if you just want to deal with points on the sphere) or the simple mercator factory (if you want to deal with objects as they would appear on Google or Bing maps). However, if you need to work with arbitrary projections, there exists a software library that understands coordinate systems and handles the math involved. {Proj}[http://trac.osgeo.org/proj/] is a C library that defines a syntax for specifying coordinate systems based on the above parameters, and an implementation for transforming coordinates from one coordinate system to another. Its syntax has become a <i>de facto</i> standard.
+Under most circumstances, when you're working with geographic data in \RGeo, you can probably use either the spherical factory (if you just want to deal with points on the sphere) or the simple mercator factory (if you want to deal with objects as they would appear on Google or Bing maps). However, if you need to work with arbitrary projections, you can use {Proj}[http://trac.osgeo.org/proj/], a C library that understands coordinate systems and handles the math involved. Proj defines a syntax for specifying coordinate systems based on the above parameters, and provides an implementation for transforming coordinates from one coordinate system to another. Its syntax has become a <i>de facto</i> standard.
 
 \RGeo provides a Ruby wrapper around the Proj interface, and integrates proj into its representation of geometric objects. You can use the Proj syntax to specify the coordinate system for input data, and tell \RGeo to translate it to a different coordinate system for analysis or output. \RGeo's geographic factories can also be configured with a particular projection using the Proj syntax, and automatically convert between latitude-longitude and that projection's coordinate system. For example:
 
@@ -329,29 +329,31 @@ Under most circumstances, when you're working with geographic data in \RGeo, you
 
 === 4.5. Spatial Reference Systems and the EPSG Dataset
 
-The OGC also defines a syntax for specifying coordinate systems, the {Coordinate Transformation Services Specification}[http://www.opengeospatial.org/standards/ct]. This specification defines both an object model and a well-known text representation for coordinate systems and transformations. \RGeo does not yet implement this specification, but it is on the to-do list.
+The OGC also defines a syntax for specifying coordinate systems, the {Coordinate Transformation Services Specification}[http://www.opengeospatial.org/standards/ct]. This specification defines both an object model and a well-known text representation for coordinate systems and transformations. \RGeo also provides basic support for this specification; you can attach an OGC coordinate system specification to a factory to indicate the coordinate system. However, if you want \RGeo to automatically convert spatial data between coordinate systems, you must use Proj4 syntax.
 
 Finally, there also exists a <i>de facto</i> standard database of coordinate systems and related parameters, published by EPSG (now the OGP Geomatics Committee). This is a set of coordinate systems, each tagged with a well-known ID number, including geographic and projected systems. You can browse this database, including both OGC and Proj4 representations, at http://www.spatialreference.org/. This database is also included as a table in many popular spatial databases including PostGIS and SpatiaLite. Typically, the EPSG number is used as the SRID identifying the coordinate system for geometric objects stored in the database.
 
 The most common EPSG number in use is 4326, which identifies the WGS84 geographic (longitude-latitude) coordinate system on the WGS84 ellipsoid. In fact, current versions of PostGIS restrict geography objects to this SRID. Be aware, again, that this is a non-projected ellipsoidal coordinate system. If you load EPSG 4326 data directly into, say, a Cartesian implementation in \RGeo, then the basic data fields will work fine, but size and distance functions, as well as spatial analysis operations such as intersections, may yield surprising or incorrect results because the data's coordinate system does not match how \RGeo is treating it.
 
+The EPSG database is so ubiquitous that it is commonly distributed along with spatial database systems such as PostGIS and SpatiaLite, as described in the next section. \RGeo takes advantage of this by providing automatic lookup of the coordinate system from the EPSG number. If you use one of these spatial databases, you do not need to know the exact definition of the coordinate system; just provide the EPSG number in the SRID field, and the \RGeo factory will know how to construct the correct Proj4 syntax for performing coordinate conversions. You can even create custom spatial reference system databases if you do not want to use the provided standard databases.
+
 == 5. Spatial Databases
 
 Now that we have a basic understanding of geospatial data, we'll turn to the question of storing and querying for this data.
 
-As we have seen, there exist a variety of ways to serialize geometric objects, notably the OGC "well-known text" and "well-known binary" formats. The simplest way to store such objects in a database, then, is to simply serialize the object into a blob. However, this would not allow us to include conditions relating to the object itself in a query. Typical location-based applications may need to run queries such as "give me all the locations within one mile of this lat-long." This kind of capability is the domain of spatial databases.
+As we have seen, there exist a variety of ways to serialize geometric objects, notably the OGC "well-known text" and "well-known binary" formats. The simplest way to store such objects in a database, then, is to simply serialize the object into a blob. However, this would not allow us to perform queries with conditions relating to the object itself. Typical location-based applications may need to run queries such as "give me all the locations within one mile of a particular position." This kind of capability is the domain of spatial databases.
 
-=== 5.1. Spatial Queries and Indexes
+=== 5.1. Spatial Queries and Spatial Indexes
 
 The OGC defines a {specification}[http://www.opengeospatial.org/standards/sfs], related to the SFS, describing SQL extensions for a spatial database. This specification includes a table for spatial reference systems (that is, coordinate systems) which can contain OGC and Proj4 representations, and a table of metadata for geometry columns which stores such information as type, dimension, and srid constraints. It also defines a suite of SQL functions that you can call in a query. For example, in a compliant database, to find all rows in "mytable" where the geometry-valued column "geom" contains data within 5 units of the coordinates (10, 20), you might be able to run a query similar to:
 
  SELECT * FROM mytable WHERE ST_Distance(geom, ST_WKTToSQL("POINT(10 20)")) > 5;
 
-Like all database queries, however, when there are a large number of rows, such queries can be slow if it has to do a full table scan. This is especially true if it has to evaluate geometric functions like the above, which can be numerically complex and slow to execute. To speed up queries, it is necessary to index your geometric columns.
+Like all database queries, however, when there are a large number of rows, such a query can be slow if it has to do a full table scan. This is especially true if it has to evaluate geometric functions like the above, which can be numerically complex and slow to execute. To speed up queries, it is necessary to index your spatial columns.
 
-Spatial indexes are somewhat more complex than typical database indexes. A typical B-tree index relies on a global ordering of data: the fact that you can sort values in a binary tree and hence perform logarithmic-time searches. However, there isn't an obvious global ordering for spatial data. Should POINT(0 1) come before or after POINT(1 0)? And how do each of those compare with LINESTRING(0 1, 1 0)? More concretely, spatial data exists in two dimensions rather than one, and can span finite ranges.
+Spatial indexes are somewhat more complex than typical database indexes. A typical B-tree index relies on a global ordering of data: the fact that you can sort scalar values in a binary tree and hence perform logarithmic-time searches. However, there isn't an obvious global ordering for spatial data. Should POINT(0 1) come before or after POINT(1 0)? And how do each of those compare with LINESTRING(0 1, 1 0)? More concretely, spatial data exists in two dimensions rather than one, and can span finite ranges.
 
-Spatial databases handle the problem of indexing spatial data in different ways, but most techniques are variants on an indexing algorithm known as an R-tree. I won't go into the details of how an R-tree works. For the interested, I recommend the text {"Spatial Databases With Application To GIS"}[http://www.amazon.com/dp/1558605886], which covers a wide variety of issues related to basic spatial database implementation. For our purposes, just note that for large datasets, it is necessary to index the geometry columns, and that the index creation process may be different from that of normal scalar columns. The next sections provide some information specific to some of the common spatial databases.
+Spatial databases handle the problem of indexing spatial data in various ways, but most techniques are variants on an indexing algorithm known as an R-tree. I won't go into the details of how an R-tree works here. For the interested, I recommend the text {"Spatial Databases With Application To GIS"}[http://www.amazon.com/dp/1558605886], which covers a wide variety of issues related to basic spatial database implementation. For our purposes, just note that for large datasets, it is necessary to index the geometry columns, and that the index creation process may be different from that of normal scalar columns. The next sections provide some information specific to some of the common spatial databases.
 
 === 5.2. MySQL Spatial
 
@@ -370,7 +372,7 @@ In general, if you're using MySQL for the rest of your application, and you just
 
 {SpatiaLite}[http://www.gaia-gis.it/spatialite/] is an add-on library for the popular database {Sqlite}[http://www.sqlite.org/]. It is close to a fully compliant implementation of the OGC SQL specification, but as a result it is more difficult to manage than MySQL.
 
-To install SpatiaLite, you must compile it as a shared library, then load that library as an extension using the appropriate sqlite API. This gives you access to the full suite of spatial SQL functions defined by the OGC, along with a set of utility functions for managing spatial columns and indexes as well as the geometry columns and spatial reference systems tables. These utility functions automatically create and manage the appropriate entries in the geometry columns table, and the triggers that enforce type and SRID constraints and maintain the spatial indexes.
+To install SpatiaLite, you must compile it as a shared library, then load that library as an extension using the appropriate sqlite API. This gives you access to the full suite of spatial SQL functions defined by the OGC, along with a set of utility functions for managing spatial columns and indexes as well as the geometry columns and spatial reference systems tables. These utility functions automatically create and manage the appropriate entries in the geometry columns table and the triggers that enforce type and SRID constraints and maintain the spatial indexes.
 
  CREATE TABLE mytable(id INTEGER PRIMARY KEY);
  SELECT AddGeometryColumn('mytable', 'latlon', 4326, 'POINT', 'XY');
@@ -382,7 +384,7 @@ Spatial indexes themselves are implemented using SpatiaLite's Rtree extension, a
    (SELECT pkid FROM idx_mytable_latlon WHERE
       xmin > -123 AND xmax < -122 AND ymin > 47 AND ymax < 48);
 
-SpatiaLite's internal format is a binary format loosely based on the WKB, but extended to include the SRID, as well as some internal bounding rectangle data to speed up calculations. Like MySQL, SpatiaLite provides functions to convert this data to and from WKB and WKT. I'm not completely clear on this, but it does not seem that SpatiaLite supports Z and M coordinates.
+SpatiaLite's internal format is a binary format loosely based on the WKB, but extended to include the SRID, as well as some internal bounding rectangle data to speed up calculations. Like MySQL, SpatiaLite provides functions to convert this data to and from WKB and WKT. I'm not completely clear on this, but it does not seem that SpatiaLite supports Z and M coordinates at this time.
 
 === 5.4. PostGIS
 
@@ -394,16 +396,18 @@ Like SpatiaLite, PostGIS is compiled and installed as a plug-in library to the d
  SELECT AddGeometryColumn('mytable', 'latlon', 4326, 'POINTM', 3);
  CREATE INDEX idx_mytable_latlon ON mytable USING GIST (latlon);
 
+PostGIS actually provides two types of spatial columns: geometry and geography. The former assumes a flat coordinate system and performs Euclidean/Cartesian geometric calculations using any EPSG coordinate system you choose. The latter is specifically designed for geographic (longitude-latitude) coordinate systems. It performs calculations on the sphereoid and only works with EPSG 4326; however, some of the more advanced functions are not implemented because the calculations involved would be prohibitively complex. When you create a spatial column in PostGIS, you will need to decide whether to use the geometry or geography type.
+
 PostGIS uses as its internal format a variant of WKB known as EWKB. This variant provides support for Z and M coordinates as well as embedded SRID values. PostGIS also defines an corresponding EWKT format adding Z and M support and SRIDs to WKT, and provides conversion functions. The EWKB and EWKT variants are commonly used and so are supported by \RGeo's WKB and WKT parsers.
 
 === 5.5. \RGeo ActiveRecord Integration
 
-\RGeo provides extra support for web applications built on Ruby On Rails or similar frameworks that use the ActiveRecord library, in the form of a suite of ActiveRecord connection adapters for the various spatial databases we have covered. These connection adapters subclass the stock database connection adapters, and add support for the \RGeo geometric data types. You can create spatial columns and indexes using extensions to the ActiveRecord schema definition functions, and the appropriate fields on your ActiveRecord objects will appear as \RGeo spatial data objects. Using one of these connection adapters is probably the easiest way to integrate your Rails application with a spatial database.
+\RGeo provides extra support for web applications built on Ruby On Rails or similar frameworks that use the ActiveRecord library, in the form of a suite of ActiveRecord connection adapters for the various spatial databases we have covered. These connection adapters subclass the stock database connection adapters, and add support for the \RGeo geometric data types. You can create spatial columns and indexes using extensions to the ActiveRecord schema definition functions, and the appropriate fields on your ActiveRecord objects will appear as \RGeo spatial data objects. Some of these adapters also modify ActiveRecord's rake tasks to help automate the process of creating and maintaining spatial databases. Using one of these connection adapters is probably the easiest way to integrate your Rails application with a spatial database.
 
 \RGeo's spatial ActiveRecord adapters are provided in separate gems, named according to the recommended convention. These are the names of these connection adapters:
 
 * *mysqlspatial*: Subclasses the mysql adapter and adds support for MySQL's spatial types. Available as the <b>activerecord-mysqlspatial-adapter</b> gem.
-* *mysql2spatial*: Subclasses the mysql2 adapter and adds support for MySQL's spatial types. Available as the <b>activerecord-mysql2spatial-adapter</b> gem.
+* <b>mysql2spatial</b>: Subclasses the mysql2 adapter and adds support for MySQL's spatial types. Available as the <b>activerecord-mysql2spatial-adapter</b> gem.
 * *spatialite*: Subclasses the sqlite3 adapter and adds support for the SpatiaLite extension. Available as the <b>activerecord-spatialite-adapter</b> gem.
 * *postgis*: Subclasses the postgresql adapter and adds support for the PostGIS extension. Available as the <b>activerecord-postgis-adapter</b> gem.
 
@@ -415,11 +419,11 @@ When writing a location-aware application, you will often need to interact with
 
 {ESRI}[http://www.esri.com/] is one of the oldest and most well-known GIS corporations, developing a suite of applications including the venerable {ArcGIS}[http://www.esri.com/software/arcgis/index.html]. ESRI also created the Shapefile, a geospatial data file format that has become a <i>de facto</i> standard despite its legacy and somewhat awkward characteristics. Today, many of the widely-available geospatial data sets are distributed as shapefiles.
 
-The shapefile format is specified in an ESRI {whitepaper}[http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf]. It typically comprises three files: a geometric data file "*.shp" containing the actual geometric data, a corresponding index file "*.shx" providing offsets into the .shp file to support random access, and a corresponding file "*.dbf" in dBASE format that stores arbitrary attributes for the shape records. Many GIS systems can read and/or write shapefiles. SpatiaLite can treat a shapefile as an external "virtual table". An optional \RGeo module, RGeo::Shapefile (distributed as the gem <b>rgeo-shapefile</b>) can read shapefiles and represent their contents as \RGeo's geometric data types.
+The shapefile format is specified in an ESRI {whitepaper}[http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf]. It typically comprises three files: the main file "*.shp" containing the actual geometric data, a corresponding index file "*.shx" providing offsets into the .shp file to support random access, and a corresponding file "*.dbf" in dBASE format that stores arbitrary attributes for the shape records. Many GIS systems can read and/or write shapefiles. SpatiaLite can treat a shapefile as an external "virtual table". An optional \RGeo module, RGeo::Shapefile (distributed as the gem <b>rgeo-shapefile</b>) can read shapefiles and expose their contents as \RGeo's geometric data types.
 
 === 6.2. GeoJSON and Location-Based Services
 
-Location is becoming a common feature of web services as well. An emerging standard in the encoding of geographic data in a web service is {GeoJSON}[http://www.geojson.org/], an geospatial data format based on JSON. GeoJSON can encode any of the OGR geometry types, along with attributes, bounding boxes, and coordinate system specifications. {SimpleGeo}[http://www.simplegeo.com/] is one of several high-profile location based APIs now using GeoJSON. \RGeo also provides an optional module RGeo::GeoJSON (distrubted as the gem <b>rgeo-geojson</b>) that can read and write this format.
+Location is becoming a common feature of web services as well. An emerging standard in the encoding of geographic data in a web service is {GeoJSON}[http://www.geojson.org/], an geospatial data format based on JSON. GeoJSON can encode any of the OGR geometry types, along with attributes, bounding boxes, and coordinate system specifications. {SimpleGeo}[http://www.simplegeo.com/] is one of several high-profile location based APIs now using GeoJSON. \RGeo also provides an optional module RGeo::GeoJSON (distributed as the gem <b>rgeo-geojson</b>) that can read and write this format.
 
 Other common formats that may be used by web services include {GeoRSS}[http://www.georss.org/], an extension to RSS and Atom for geotagging RSS feed entries, and {KML}[http://www.opengeospatial.org/standards/kml], an XML-based markup language for geographic information originally developed by Google and recently adopted as an OGC standard. The GeoRuby library provides rudimentary support for these formats. \RGeo does not yet, but appropriate optional modules are on the to-do list.
 
@@ -431,5 +435,6 @@ At the time of this writing, a number of open source geospatial tools and librar
 
 == History
 
-* Version 0.1 / 5 Dec 2010: Initial draft.
-* Version 0.2 / 7 Dec 2010: More code examples and other minor updates.
+* Version 0.1 / 5 Dec 2010: Initial draft
+* Version 0.2 / 7 Dec 2010: More code examples and other minor updates
+* Version 0.3 / 17 Feb 2011: Further minor clarifications and fixes, and coverage of features in newer \RGeo releases

data/Version

@@ -1 +1 @@
-0.2.4
+0.2.5

data/lib/rgeo/cartesian/bounding_box.rb

@@ -64,10 +64,10 @@ module RGeo
       # 
       # Options include:
       # 
-      # <tt>:ignore_z</tt>::
+      # [<tt>:ignore_z</tt>]
       #   If true, ignore z coordinates even if the factory supports them.
       #   Default is false.
-      # <tt>:ignore_m</tt>::
+      # [<tt>:ignore_m</tt>]
       #   If true, ignore m coordinates even if the factory supports them.
       #   Default is false.
       

data/lib/rgeo/cartesian/calculations.rb

@@ -78,6 +78,10 @@ module RGeo
       end
       
       
+      # Returns a negative value if the point is to the left,
+      # a positive value if the point is to the right, or
+      # 0 if the point is collinear to the segment.
+      
       def side(p_)
         px_ = p_.x
         py_ = p_.y
@@ -89,9 +93,7 @@ module RGeo
         if @lensq == 0
           nil
         else
-          px_ = @sx - p_.x
-          py_ = @sy - p_.y
-          - (@dx * px_ + @dy * py_) / @lensq
+          (@dx * (p_.x - @sx) + @dy * (p_.y - @sy)) / @lensq
         end
       end
       
@@ -108,16 +110,41 @@ module RGeo
       
       def intersects_segment?(seg_)
         s2_ = seg_.s
+        # Handle degenerate cases
+        if seg_.degenerate?
+          if @lensq == 0
+            return @s == s2_
+          else
+            return contains_point?(s2_)
+          end
+        elsif @lensq == 0
+          return seg_.contains_point?(@s)
+        end
+        # Both segments have nonzero length.
         sx2_ = s2_.x
         sy2_ = s2_.y
         dx2_ = seg_.dx
         dy2_ = seg_.dy
         denom_ = @dx*dy2_ - @dy*dx2_
-        return side(s2_) == 0 if denom_ == 0
-        t_ = (dy2_ * (sx2_ - @sx) + dx2_ * (@sy - sy2_)) / denom_
-        return false if t_ < 0.0 || t_ > 1.0
-        t2_ = (@dy * (sx2_ - @sx) + @dx * (@sy - sy2_)) / denom_
-        t2_ >= 0.0 && t2_ <= 1.0
+        if denom_ == 0
+          # Segments are parallel. Make sure they are collinear.
+          return false unless side(s2_) == 0
+          # 1-D check.
+          ts_ = (@dx * (sx2_ - @sx) + @dy * (sy2_ - @sy)) / @lensq
+          te_ = (@dx * (sx2_ + dx2_ - @sx) + @dy * (sy2_ + dy2_ - @sy)) / @lensq
+          if ts_ < te_
+            te_ >= 0.0 && ts_ <= 1.0
+          else
+            ts_ >= 0.0 && te_ <= 1.0
+          end
+        else
+          # Segments are not parallel. Check the intersection of their
+          # containing lines.
+          t_ = (dy2_ * (sx2_ - @sx) + dx2_ * (@sy - sy2_)) / denom_
+          return false if t_ < 0.0 || t_ > 1.0
+          t2_ = (@dy * (sx2_ - @sx) + @dx * (@sy - sy2_)) / denom_
+          t2_ >= 0.0 && t2_ <= 1.0
+        end
       end
       
       

data/lib/rgeo/cartesian/interface.rb

@@ -90,25 +90,25 @@ module RGeo
       # 
       # Options include:
       # 
-      # <tt>:srid</tt>::
+      # [<tt>:srid</tt>]
       #   Set the SRID returned by geometries created by this factory.
       #   Default is 0.
-      # <tt>:proj4</tt>::
+      # [<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. Optional.
-      # <tt>:coord_sys</tt>::
+      # [<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.
       #   Optional.
-      # <tt>:srs_database</tt>::
+      # [<tt>:srs_database</tt>]
       #   Optional. If provided, the value should be an implementation of
       #   CoordSys::SRSDatabase::Interface. If both this and an SRID are
       #   provided, they are used to look up the proj4 and coord_sys
       #   objects from a spatial reference system database.
-      # <tt>:has_z_coordinate</tt>::
+      # [<tt>:has_z_coordinate</tt>]
       #   Support a Z coordinate. Default is false.
-      # <tt>:has_m_coordinate</tt>::
+      # [<tt>:has_m_coordinate</tt>]
       #   Support an M coordinate. Default is false.
       
       def simple_factory(opts_={})

data/lib/rgeo/coord_sys/cs/entities.rb

@@ -202,7 +202,7 @@ module RGeo
         
         # Computes the WKT representation. Options include:
         # 
-        # <tt>:standard_brackets</tt>::
+        # [<tt>:standard_brackets</tt>]
         #   If set to true, outputs parentheses rather than square
         #   brackets. Default is false.
         

data/lib/rgeo/coord_sys/proj4.rb

@@ -172,7 +172,7 @@ module RGeo
         # 
         # Recognized options include:
         # 
-        # <tt>:radians</tt>::
+        # [<tt>:radians</tt>]
         #   If set to true, then this proj4 will represent geographic
         #   (latitude/longitude) coordinates in radians rather than
         #   degrees. If this is a geographic coordinate system, then its

data/lib/rgeo/coord_sys/srs_database/active_record_table.rb

@@ -55,57 +55,57 @@ module RGeo
         # 
         # Options include:
         # 
-        # <tt>:ar_class</tt>::
+        # [<tt>:ar_class</tt>]
         #   An ActiveRecord class to use. You may provide this if you
         #   already have an ActiveRecord class that accesses the table.
         #   If not provided, an ActiveRecord class will be generated
         #   for you, using the <tt>:ar_base_class</tt>,
         #   <tt>:database_config</tt>, and <tt>:table_name</tt> options.
-        # <tt>:ar_base_class</tt>::
+        # [<tt>:ar_base_class</tt>]
         #   Specify an ActiveRecord base class to use when generating an
         #   ActiveRecord class. Default is ::ActiveRecord::Base. You may
         #   want to use this if you have a base class already that
         #   specifies an existing database connection and/or other
         #   class-scope options.
-        # <tt>:database_config</tt>::
+        # [<tt>:database_config</tt>]
         #   If provided, <tt>establish_connection</tt> will be called on
         #   the generated ActiveRecord class, with the given value.
-        # <tt>:table_name</tt>::
+        # [<tt>:table_name</tt>]
         #   The table name for the new ActiveRecord class. Defaults to
         #   the value <tt>spatial_ref_sys</tt>, which is the OGC-specified
         #   name for this table.
-        # <tt>:srid_column</tt>::
+        # [<tt>:srid_column</tt>]
         #   The name of the SRID column. Defaults to "srid", which is the
         #   OGC-specified name for this column.
-        # <tt>:auth_name_column</tt>::
+        # [<tt>:auth_name_column</tt>]
         #   The name of the authority name column. On an OGC-compliant
         #   database, this column should be named "auth_name". However,
         #   the default is set to nil; you should set this option
         #   explicitly if you want to read the authority name.
-        # <tt>:auth_srid_column</tt>::
+        # [<tt>:auth_srid_column</tt>]
         #   The name of the authority srid column. On an OGC-compliant
         #   database, this column should be named "auth_srid". However,
         #   the default is set to nil; you should set this option
         #   explicitly if you want to read the authority's srid.
-        # <tt>:name_column</tt>::
+        # [<tt>:name_column</tt>]
         #   The name of the coordinate system name column. This column is
         #   not part of the OGC spec, but it is included in some spatial
         #   database implementations. Default is nil.
-        # <tt>:description_column</tt>::
+        # [<tt>:description_column</tt>]
         #   The name of the coordinate system description column. This
         #   column is not part of the OGC spec, but may be included in
         #   some spatial database implementations. Default is nil.
-        # <tt>:srtext_column</tt>::
+        # [<tt>:srtext_column</tt>]
         #   The name of the spatial reference WKT column. On an
         #   OGC-compliant database, this column should be named "srtext".
         #   However, not all databases include this column, so the default
         #   is set to nil; you should set this option explicitly if you
         #   want to read the OGC coordinate system specification.
-        # <tt>:proj4text_column</tt>::
+        # [<tt>:proj4text_column</tt>]
         #   The name of the Proj4 format projection spec column. This
         #   column is not part of the OGC spec, but may be included in
         #   some spatial database implementations. Default is nil.
-        # <tt>:cache</tt>::
+        # [<tt>:cache</tt>]
         #   If set to true, entries are cached when first retrieved, so
         #   subsequent requests do not have to make a database round trip.
         #   Default is false.

data/lib/rgeo/coord_sys/srs_database/interface.rb

@@ -92,18 +92,18 @@ module RGeo
         # 
         # Some attribute inputs have special behaviors:
         # 
-        # <tt>:coord_sys</tt>::
+        # [<tt>:coord_sys</tt>]
         #   You can pass a CS coordinate system object, or a string in
         #   WKT format.
-        # <tt>:proj4</tt>::
+        # [<tt>:proj4</tt>]
         #   You can pass a Proj4 object, or a proj4-format string.
-        # <tt>:name</tt>::
+        # [<tt>:name</tt>]
         #   If the name is not provided directly, it is taken from the
         #   coord_sys.
-        # <tt>:authority</tt>::
+        # [<tt>:authority</tt>]
         #   If the authority name is not provided directly, it is taken
         #   from the coord_sys.
-        # <tt>:authority_code</tt>::
+        # [<tt>:authority_code</tt>]
         #   If the authority code is not provided directly, it is taken
         #   from the coord_sys.
         

data/lib/rgeo/coord_sys/srs_database/proj4_data.rb

@@ -55,7 +55,7 @@ module RGeo
         # 
         # These options are recognized:
         # 
-        # <tt>:dir</tt>::
+        # [<tt>:dir</tt>]
         #   The path for the share/proj directory that contains the
         #   requested data file. By default, the Proj4Data class will
         #   try a number of directories for you, including
@@ -65,7 +65,7 @@ module RGeo
         #   option. You may also pass nil as the value, in which case all
         #   the normal lookup paths will be disabled, and you will have to
         #   provide the full path as the file name.
-        # <tt>:cache</tt>::
+        # [<tt>:cache</tt>]
         #   If set to true, this class caches previously looked up entries
         #   so subsequent lookups do not have to reread the file. If set
         #   to <tt>:read_all</tt>, then ALL values in the file are read in
@@ -73,7 +73,7 @@ module RGeo
         #   <tt>:preload</tt>, then ALL values in the file are read in
         #   immediately when the database is created. Default is false,
         #   indicating that the file will be reread on every lookup.
-        # <tt>:authority</tt>::
+        # [<tt>:authority</tt>]
         #   If set, its value is taken as the authority name for all
         #   entries. The authority code will be set to the identifier. If
         #   not set, then the authority fields of entries will be blank.

data/lib/rgeo/coord_sys/srs_database/sr_org.rb

@@ -56,7 +56,7 @@ module RGeo
         # 
         # Options:
         # 
-        # <tt>:cache</tt>::
+        # [<tt>:cache</tt>]
         #   If set to true, lookup results are cached so if the same URL
         #   is requested again, the result is served from cache rather
         #   than issuing another HTTP request. Default is false.

data/lib/rgeo/coord_sys/srs_database/url_reader.rb

@@ -54,7 +54,7 @@ module RGeo
         # 
         # Options:
         # 
-        # <tt>:cache</tt>::
+        # [<tt>:cache</tt>]
         #   If set to true, lookup results are cached so if the same URL
         #   is requested again, the result is served from cache rather
         #   than issuing another HTTP request. Default is false.

data/lib/rgeo/feature/factory.rb

@@ -91,17 +91,17 @@ module RGeo
       # 
       # Currently defined well-known properties are:
       # 
-      # <tt>:has_z_coordinate</tt>::
+      # [<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>::
+      # [<tt>:has_m_coordinate</tt>]
       #   Set to true if geometries created by this factory include a M
       #   coordinate, and the Point#z method is available.
-      # <tt>:is_cartesian</tt>::
+      # [<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>::
+      # [<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
@@ -301,13 +301,13 @@ module RGeo
       # (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>::
+      # [<tt>:keep_subtype</tt>]
       #   indicates whether to keep the subtype if casting to a supertype
       #   of the current type
-      # <tt>:force_new</tt>::
+      # [<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>::
+      # [<tt>:project</tt>]
       #   indicates whether to project the coordinates from the source to
       #   the destination proj4 coordinate system, if available
       # 

data/lib/rgeo/feature/factory_generator.rb

@@ -80,31 +80,31 @@ module RGeo
       # recommendation only. There is no hard requirement for any
       # particular factory generator to support them.
       # 
-      # <tt>:strict</tt>::
+      # [<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>::
+      # [<tt>:srid</tt>]
       #   The SRID for the factory and objects it creates.
       #   Default is usually 0.
-      # <tt>:proj4</tt>::
+      # [<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>::
+      # [<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>::
+      # [<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>::
+      # [<tt>:has_z_coordinate</tt>]
       #   Support Z coordinates. Default is usually false.
-      # <tt>:has_m_coordinate</tt>::
+      # [<tt>:has_m_coordinate</tt>]
       #   Support M coordinates. Default is usually false.
       
       def call(config_={})

data/lib/rgeo/feature/geometry.rb

@@ -68,27 +68,26 @@ module RGeo
     # 
     # 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
+    # * <b>Spatial equivalence</b> is the weakest form of equivalence,
+    #   indicating that the objects represent the same region of space,
+    #   but may be different representations of that region. For example,
     #   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
     #   Factory#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
+    # 
+    # * <b>Objective equivalence</b> is a stronger form of equivalence, 
+    #   indicating that the 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
+    # 
+    # * <b>Objective identity</b> is the strongest form, indicating that
+    #   the references refer to the same object. Of course, all pairs of
     #   references with the same objective identity are both objectively
     #   equivalent and spatially equivalent.
     # 

data/lib/rgeo/feature/line_string.rb

@@ -95,7 +95,7 @@ module RGeo
       
       
     end
-  
+    
     
   end
   

data/lib/rgeo/feature/types.rb

@@ -110,20 +110,20 @@ module RGeo
       # Parameters may be provided as a hash, or as separate arguments.
       # Hash keys are as follows:
       # 
-      # <tt>:factory</tt>::
+      # [<tt>:factory</tt>]
       #   Set the factory to the given factory. If this argument is not
       #   given, the original object's factory is kept.
-      # <tt>:type</tt>::
+      # [<tt>:type</tt>]
       #   Cast to the given type, which must be a module in the
       #   RGeo::Feature namespace. If this argument is not given, the
       #   result keeps the same type as the original.
-      # <tt>:project</tt>::
+      # [<tt>:project</tt>]
       #   If this is set to true, and both the original and new factories
       #   support proj4 projections, then the cast will also cause the
       #   coordinates to be transformed between those two projections.
       #   If set to false, the coordinates are not modified. Default is
       #   false.
-      # <tt>:keep_subtype</tt>::
+      # [<tt>:keep_subtype</tt>]
       #   Value must be a boolean indicating whether to keep the subtype
       #   of the original. If set to false, casting to a particular type
       #   always casts strictly to that type, even if the old type is a
@@ -133,7 +133,7 @@ module RGeo
       #   LinearRing is already a more specific subtype. If you set this
       #   value to true, the casted object will remain a LinearRing.
       #   Default is false.
-      # <tt>:force_new</tt>::
+      # [<tt>:force_new</tt>]
       #   Always return a newly-created object, even if neither the type
       #   nor factory is modified. Normally, if this is set to false, and
       #   a cast is not set to modify either the factory or type, the

data/lib/rgeo/geographic/interface.rb

@@ -82,11 +82,11 @@ module RGeo
       # You may use the following options when creating a spherical
       # factory:
       # 
-      # <tt>:has_z_coordinate</tt>::
+      # [<tt>:has_z_coordinate</tt>]
       #   Support a Z coordinate. Default is false.
-      # <tt>:has_m_coordinate</tt>::
+      # [<tt>:has_m_coordinate</tt>]
       #   Support an M coordinate. Default is false.
-      # <tt>:proj4</tt>::
+      # [<tt>:proj4</tt>]
       #   Provide the coordinate system in Proj4 format. You may pass
       #   either an RGeo::CoordSys::Proj4 object, or a string or hash
       #   containing the Proj4 parameters. This coordinate system must be
@@ -94,18 +94,18 @@ module RGeo
       #   "popular visualization CRS" (EPSG 4055), represented by
       #   "<tt>+proj=longlat +a=6378137 +b=6378137 +towgs84=0,0,0,0,0,0,0 +no_defs</tt>".
       #   Has no effect if Proj4 is not available.
-      # <tt>:coord_sys</tt>::
+      # [<tt>:coord_sys</tt>]
       #   Provide a coordinate system in OGC format, either as an object
       #   (one of the CoordSys::CS classes) or as a string in WKT format.
       #   This coordinate system must be a GeographicCoordinateSystem.
       #   The default is the "popular visualization CRS" (EPSG 4055).
-      # <tt>:srid</tt>::
+      # [<tt>:srid</tt>]
       #   The SRID that should be returned by features from this factory.
       #   Default is 4055, indicating EPSG 4055, the "popular
       #   visualization crs". You may alternatively wish to set the srid
       #   to 4326, indicating the WGS84 crs, but note that that value
       #   implies an ellipsoidal datum, not a spherical datum.
-      # <tt>:srs_database</tt>::
+      # [<tt>:srs_database</tt>]
       #   Optional. If provided, the value should be an implementation of
       #   CoordSys::SRSDatabase::Interface. If both this and an SRID are
       #   provided, they are used to look up the proj4 and coord_sys
@@ -168,9 +168,9 @@ module RGeo
       # You may use the following options when creating a simple_mercator
       # factory:
       # 
-      # <tt>:has_z_coordinate</tt>::
+      # [<tt>:has_z_coordinate</tt>]
       #   Support a Z coordinate. Default is false.
-      # <tt>:has_m_coordinate</tt>::
+      # [<tt>:has_m_coordinate</tt>]
       #   Support an M coordinate. Default is false.
       # 
       # You may also provide options understood by the underlying
@@ -220,24 +220,24 @@ module RGeo
       # Following are detailed descriptions of the various options you can
       # pass to this method.
       # 
-      # <tt>:projection_factory</tt>::
+      # [<tt>:projection_factory</tt>]
       #   Specify an existing Cartesian factory to use for the projection.
       #   This factory must have a non-nil Proj4. If this is provided, any
       #   <tt>:projection_proj4</tt>, <tt>:projection_coord_sys</tt>, and
       #   <tt>:projection_srid</tt> are ignored.
-      # <tt>:projection_proj4</tt>::
+      # [<tt>:projection_proj4</tt>]
       #   Specify a Proj4 projection to use to construct the projection
       #   factory. This may be specified as a CoordSys::Proj4 object, or
       #   as a Proj4 string or hash representation.
-      # <tt>:projection_coord_sys</tt>::
+      # [<tt>:projection_coord_sys</tt>]
       #   Specify a OGC coordinate system for the projection. This may be
       #   specified as an RGeo::CoordSys::CS::GeographicCoordinateSystem
       #   object, or as a String in OGC WKT format. Optional.
-      # <tt>:projection_srid</tt>::
+      # [<tt>:projection_srid</tt>]
       #   The SRID value to use for the projection factory. Defaults to
       #   the given projection coordinate system's authority code, or to
       #   0 if no projection coordinate system is known.
-      # <tt>:proj4</tt>::
+      # [<tt>:proj4</tt>]
       #   A proj4 projection for the geographic (lat-lon) factory. You may
       #   pass either an RGeo::CoordSys::Proj4 object, or a string or hash
       #   containing the Proj4 parameters. This coordinate system must be
@@ -246,7 +246,7 @@ module RGeo
       #   Generally, you should leave it at the default unless you want
       #   the geographic coordinate system to be based on a different
       #   horizontal datum than the projection.
-      # <tt>:coord_sys</tt>::
+      # [<tt>:coord_sys</tt>]
       #   An OGC coordinate system for the geographic (lat-lon) factory,
       #   which may be an RGeo::CoordSys::CS::GeographicCoordinateSystem
       #   object or a string in OGC WKT format. It defaults to the
@@ -254,21 +254,21 @@ module RGeo
       #   Generally, you should leave it at the default unless you want
       #   the geographic coordinate system to be based on a different
       #   horizontal datum than the projection.
-      # <tt>:srid</tt>::
+      # [<tt>:srid</tt>]
       #   The SRID value to use for the main geographic factory. Defaults
       #   to the given geographic coordinate system's authority code, or
       #   to 0 if no geographic coordinate system is known.
-      # <tt>:srs_database</tt>::
+      # [<tt>:srs_database</tt>]
       #   Optional. If provided, the value should be an implementation of
       #   CoordSys::SRSDatabase::Interface. If both this and an SRID are
       #   provided, they are used to look up the proj4 and coord_sys
       #   objects from a spatial reference system database.
-      # <tt>:has_z_coordinate</tt>::
+      # [<tt>:has_z_coordinate</tt>]
       #   Support a Z coordinate. Default is false.
       #   Note: this is ignored if a <tt>:projection_factory</tt> is
       #   provided; in that case, the geographic factory's z-coordinate
       #   availability will match the projection factory's setting.
-      # <tt>:has_m_coordinate</tt>::
+      # [<tt>:has_m_coordinate</tt>]
       #   Support an M coordinate. Default is false.
       #   Note: this is ignored if a <tt>:projection_factory</tt> is
       #   provided; in that case, the geographic factory's m-coordinate

data/lib/rgeo/geographic/simple_mercator_projector.rb

@@ -46,7 +46,13 @@ module RGeo
       
       def initialize(geography_factory_, opts_={})
         @geography_factory = geography_factory_
-        @projection_factory = Cartesian.preferred_factory(:srid => 3785, :proj4 => SimpleMercatorProjector._proj4_3785, :coord_sys => SimpleMercatorProjector._coordsys_3785, :buffer_resolution => opts_[:buffer_resolution], :lenient_multi_polygon_assertions => opts_[:lenient_multi_polygon_assertions], :has_z_coordinate => opts_[:has_z_coordinate], :has_m_coordinate => opts_[:has_m_coordinate])
+        @projection_factory = Cartesian.preferred_factory(:srid => 3785,
+          :proj4 => SimpleMercatorProjector._proj4_3785,
+          :coord_sys => SimpleMercatorProjector._coordsys_3785,
+          :buffer_resolution => opts_[:buffer_resolution],
+          :lenient_multi_polygon_assertions => opts_[:lenient_multi_polygon_assertions],
+          :has_z_coordinate => opts_[:has_z_coordinate],
+          :has_m_coordinate => opts_[:has_m_coordinate])
       end
       
       
@@ -100,7 +106,7 @@ module RGeo
           @geography_factory.line_string(geometry_.points.map{ |p_| unproject(p_) })
         when Feature::Polygon
           @geography_factory.polygon(unproject(geometry_.exterior_ring),
-                                    geometry_.interior_rings.map{ |p_| unproject(p_) })
+            geometry_.interior_rings.map{ |p_| unproject(p_) })
         when Feature::MultiPoint
           @geography_factory.multi_point(geometry_.map{ |p_| unproject(p_) })
         when Feature::MultiLineString
@@ -121,7 +127,9 @@ module RGeo
       
       
       def limits_window
-        @limits_window ||= ProjectedWindow.new(@geography_factory, -20037508.342789, -20037508.342789, 20037508.342789, 20037508.342789, :is_limits => true)
+        @limits_window ||= ProjectedWindow.new(@geography_factory,
+          -20037508.342789, -20037508.342789, 20037508.342789, 20037508.342789,
+          :is_limits => true)
       end
       
       

data/lib/rgeo/geos/interface.rb

@@ -71,13 +71,13 @@ module RGeo
       # 
       # Options include:
       # 
-      # <tt>:lenient_multi_polygon_assertions</tt>::
+      # [<tt>:lenient_multi_polygon_assertions</tt>]
       #   If set to true, assertion checking on MultiPolygon is disabled.
       #   This may speed up creation of MultiPolygon objects, at the
       #   expense of not doing the proper checking for OGC MultiPolygon
       #   compliance. See RGeo::Feature::MultiPolygon for details on
       #   the MultiPolygon assertions. Default is false.
-      # <tt>:buffer_resolution</tt>::
+      # [<tt>:buffer_resolution</tt>]
       #   The resolution of buffers around geometries created by this
       #   factory. This controls the number of line segments used to
       #   approximate curves. The default is 1, which causes, for
@@ -85,25 +85,25 @@ module RGeo
       #   4-sided polygon. A resolution of 2 would cause that buffer
       #   to be approximated by an 8-sided polygon. The exact behavior
       #   for different kinds of buffers is defined by GEOS.
-      # <tt>:srid</tt>::
+      # [<tt>:srid</tt>]
       #   Set the SRID returned by geometries created by this factory.
       #   Default is 0.
-      # <tt>:proj4</tt>::
+      # [<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. Optional.
-      # <tt>:coord_sys</tt>::
+      # [<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.
       #   Optional.
-      # <tt>:srs_database</tt>::
+      # [<tt>:srs_database</tt>]
       #   Optional. If provided, the value should be an implementation of
       #   CoordSys::SRSDatabase::Interface. If both this and an SRID are
       #   provided, they are used to look up the proj4 and coord_sys
       #   objects from a spatial reference system database.
-      # <tt>:has_z_coordinate</tt>::
+      # [<tt>:has_z_coordinate</tt>]
       #   Support <tt>z_coordinate</tt>. Default is false.
-      # <tt>:has_m_coordinate</tt>::
+      # [<tt>:has_m_coordinate</tt>]
       #   Support <tt>m_coordinate</tt>. Default is false.
       
       def factory(opts_={})

data/lib/rgeo/wkrep/wkb_generator.rb

@@ -53,7 +53,7 @@ module RGeo
     # The following options are recognized. These can be passed to the
     # constructor, or set on the object afterwards.
     # 
-    # <tt>:type_format</tt>::
+    # [<tt>:type_format</tt>]
     #   The format for type codes. Possible values are <tt>:wkb11</tt>,
     #   indicating SFS 1.1 WKB (i.e. no Z or M values); <tt>:ewkb</tt>,
     #   indicating the PostGIS EWKB extensions (i.e. Z and M presence
@@ -61,13 +61,13 @@ module RGeo
     #   embedded SRID); or <tt>:wkb12</tt> (indicating SFS 1.2 WKB
     #   (i.e. Z and M presence flagged by adding 1000 and/or 2000 to
     #   the type code.) Default is <tt>:wkb11</tt>.
-    # <tt>:emit_ewkb_srid</tt>::
+    # [<tt>:emit_ewkb_srid</tt>]
     #   If true, embed the SRID in the toplevel geometry. Available only
     #   if <tt>:type_format</tt> is <tt>:ewkb</tt>. Default is false.
-    # <tt>:hex_format</tt>::
+    # [<tt>:hex_format</tt>]
     #   If true, output a hex string instead of a byte string.
     #   Default is false.
-    # <tt>:little_endian</tt>::
+    # [<tt>:little_endian</tt>]
     #   If true, output little endian (NDR) byte order. If false, output
     #   big endian (XDR), or network byte order. Default is false.
     

data/lib/rgeo/wkrep/wkb_parser.rb

@@ -58,19 +58,19 @@ module RGeo
     # The following additional options are recognized. These can be passed
     # to the constructor, or set on the object afterwards.
     # 
-    # <tt>:support_ewkb</tt>::
+    # [<tt>:support_ewkb</tt>]
     #   Activate support for PostGIS EWKB type codes, which use high
     #   order bits in the type code to signal the presence of Z, M, and
     #   SRID values in the data. Default is false.
-    # <tt>:support_wkb12</tt>::
+    # [<tt>:support_wkb12</tt>]
     #   Activate support for SFS 1.2 extensions to the type codes, which
     #   use values greater than 1000 to signal the presence of Z and M
     #   values in the data. SFS 1.2 types such as triangle, tin, and
     #   polyhedralsurface are NOT yet supported. Default is false.
-    # <tt>:ignore_extra_bytes</tt>::
+    # [<tt>:ignore_extra_bytes</tt>]
     #   If true, extra bytes at the end of the data are ignored. If
     #   false (the default), extra bytes will trigger a parse error.
-    # <tt>:default_srid</tt>::
+    # [<tt>:default_srid</tt>]
     #   A SRID to pass to the factory generator if no SRID is present in
     #   the input. Defaults to nil (i.e. don't specify a SRID).
     

data/lib/rgeo/wkrep/wkt_generator.rb

@@ -52,7 +52,7 @@ module RGeo
     # The following options are recognized. These can be passed to the
     # constructor, or set on the object afterwards.
     # 
-    # <tt>:tag_format</tt>::
+    # [<tt>:tag_format</tt>]
     #   The format for tags. Possible values are <tt>:wkt11</tt>,
     #   indicating SFS 1.1 WKT (i.e. no Z or M markers in the tags) but
     #   with Z and/or M values added in if they are present;
@@ -63,13 +63,13 @@ module RGeo
     #   Z is present); or <tt>:wkt12</tt>, indicating SFS 1.2 WKT
     #   tags that indicate the presence of Z and M in a separate token.
     #   Default is <tt>:wkt11</tt>.
-    # <tt>:emit_ewkt_srid</tt>::
+    # [<tt>:emit_ewkt_srid</tt>]
     #   If true, embed the SRID of the toplevel geometry. Available only
     #   if <tt>:type_format</tt> is <tt>:ewkt</tt>. Default is false.
-    # <tt>:square_brackets</tt>::
+    # [<tt>:square_brackets</tt>]
     #   If true, uses square brackets rather than parentheses.
     #   Default is false.
-    # <tt>:convert_case</tt>::
+    # [<tt>:convert_case</tt>]
     #   Possible values are <tt>:upper</tt>, which changes all letters
     #   in the output to ALL CAPS; <tt>:lower</tt>, which changes all
     #   letters to lower case; or nil, indicating no case changes from

data/lib/rgeo/wkrep/wkt_parser.rb

@@ -61,23 +61,23 @@ module RGeo
     # The following additional options are recognized. These can be passed
     # to the constructor, or set on the object afterwards.
     # 
-    # <tt>:support_ewkt</tt>::
+    # [<tt>:support_ewkt</tt>]
     #   Activate support for PostGIS EWKT type tags, which appends an "M"
     #   to tags to indicate the presence of M but not Z, and also
     #   recognizes the SRID prefix. Default is false.
-    # <tt>:support_wkt12</tt>::
+    # [<tt>:support_wkt12</tt>]
     #   Activate support for SFS 1.2 extensions to the type codes, which
     #   use a "M", "Z", or "ZM" token to signal the presence of Z and M
     #   values in the data. SFS 1.2 types such as triangle, tin, and
     #   polyhedralsurface are NOT yet supported. Default is false.
-    # <tt>:strict_wkt11</tt>::
+    # [<tt>:strict_wkt11</tt>]
     #   If true, parsing will proceed in SFS 1.1 strict mode, which
     #   disallows any values other than X or Y. This has no effect if
     #   support_ewkt or support_wkt12 are active. Default is false.
-    # <tt>:ignore_extra_tokens</tt>::
+    # [<tt>:ignore_extra_tokens</tt>]
     #   If true, extra tokens at the end of the data are ignored. If
     #   false (the default), extra tokens will trigger a parse error.
-    # <tt>:default_srid</tt>::
+    # [<tt>:default_srid</tt>]
     #   A SRID to pass to the factory generator if no SRID is present in
     #   the input. Defaults to nil (i.e. don't specify a SRID).
     

data/test/simple_cartesian/tc_calculations.rb

@@ -54,10 +54,13 @@ module RGeo
           @point5 = @factory.point(-1, 2)
           @point6 = @factory.point(-1, 1)
           @point7 = @factory.point(5, 4)
+          @point8 = @factory.point(1, 3)
           @horiz_seg = ::RGeo::Cartesian::Segment.new(@point1, @point3)
           @vert_seg = ::RGeo::Cartesian::Segment.new(@point4, @point1)
           @short_rising_seg = ::RGeo::Cartesian::Segment.new(@point1, @point2)
           @long_rising_seg = ::RGeo::Cartesian::Segment.new(@point5, @point2)
+          @collinear_rising_seg = ::RGeo::Cartesian::Segment.new(@point5, @point8)
+          @touching_collinear_rising_seg = ::RGeo::Cartesian::Segment.new(@point1, @point8)
           @parallel_rising_seg = ::RGeo::Cartesian::Segment.new(@point6, @point7)
           @steep_rising_seg = ::RGeo::Cartesian::Segment.new(@point6, @point4)
           @degenerate_seg = ::RGeo::Cartesian::Segment.new(@point5, @point5)
@@ -114,6 +117,10 @@ module RGeo
         def test_segment_intersects_parallel
           assert(@long_rising_seg.intersects_segment?(@long_rising_seg))
           assert(!@long_rising_seg.intersects_segment?(@parallel_rising_seg))
+          assert(!@short_rising_seg.intersects_segment?(@collinear_rising_seg))
+          assert(@touching_collinear_rising_seg.intersects_segment?(@short_rising_seg))
+          assert(@touching_collinear_rising_seg.intersects_segment?(@long_rising_seg))
+          assert(@long_rising_seg.intersects_segment?(@touching_collinear_rising_seg))
         end
         
         

metadata

@@ -1,12 +1,8 @@
 --- !ruby/object:Gem::Specification 
 name: rgeo
 version: !ruby/object:Gem::Version 
-  prerelease: false
-  segments: 
-  - 0
-  - 2
-  - 4
-  version: 0.2.4
+  prerelease: 
+  version: 0.2.5
 platform: ruby
 authors: 
 - Daniel Azuma
@@ -14,7 +10,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-12-31 00:00:00 -08:00
+date: 2011-03-21 00:00:00 -07:00
 default_executable: 
 dependencies: []
 
@@ -193,23 +189,17 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      segments: 
-      - 1
-      - 8
-      - 7
       version: 1.8.7
 required_rubygems_version: !ruby/object:Gem::Requirement 
   none: false
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      segments: 
-      - 0
       version: "0"
 requirements: []
 
 rubyforge_project: virtuoso
-rubygems_version: 1.3.7
+rubygems_version: 1.6.2
 signing_key: 
 specification_version: 3
 summary: RGeo is a spatial data library for Ruby.