[Solr Wiki] Update of "SolrAdaptersForLuceneSpatial4" by DavidSmiley

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Solr Wiki" for change notification.

The "SolrAdaptersForLuceneSpatial4" page has been changed by DavidSmiley:
http://wiki.apache.org/solr/SolrAdaptersForLuceneSpatial4?action=diff&rev1=24&rev2=25

Comment:
Some small things.  Added more details on distance calculation.

  
  = Lucene / Solr 4 Spatial =
  
- This document describes how to use the ''new'' spatial field types and related functionality in Lucene / Solr 4.  The [[SpatialSearch|existing spatial support]] introduced in Solr 3 is still present and is still the default used in Solr's example schema via the named "location" field type.
+ This document describes how to use the ''new'' spatial field types and related functionality in Lucene / Solr 4.  The [[SpatialSearch|existing spatial support]] introduced in Solr 3 is still present and is still the default used in Solr's example schema -- LatLonType.
  
  The bulk of the new spatial implementation lives in the new Lucene 4 spatial module.  It replaces the former "Lucene spatial contrib" in v3.  The Solr piece is small as it only needs to provide field types which are essentially adapters to the code in the Lucene spatial module.  The shape implementations and other core spatial code that isn't related to Lucene is held in a new open-source project called [[https://github.com/spatial4j/spatial4j|Spatial4j]].  Presently, polygon support requires an additional dependency -- [[http://sourceforge.net/projects/jts-topo-suite/|JTS]].
  
@@ -19, +19 @@

  These features describe what developer-users of Lucene/Solr 4 will appreciate.  Under the hood, it's a framework designed to be extended for different so-called "spatial strategies".  I'll assume here the RecursivePrefixTreeStrategy as it should address most use-cases and it has the best tests.
  
   * Polygon, LineString and other new shapes.  All shapes are supported as indexed shapes and query shapes.  Shapes other than point, rectangle and circle are supported via JTS -- an otherwise optional dependency.  See JTS caveats below for more information.
-  * Multi-valued indexed fields.  This is critical for storing the results of automatic place extraction from text using natural language processing techniques with a gazetteer (a variant of "geocoding"), since a variable number of locations will be found.
+  * Multi-valued indexed fields.  This is critical for storing the results of automatic place extraction from text using natural language processing techniques with a gazetteer (a variant of "geocoding" / "geotagging"), since a variable number of locations will be found.
   * Index non-point shapes as well as points.  Non-point shapes are essentially pixelated (i.e. gridded) to a configured resolution per shape -- an approximation.  By default that resolution is defined by a percentage of the overall shape size, and it applies to query shapes too.  Note: If extremely high precision of shape edges needs to be retained for accurate indexing, then this solution probably won't scale too well at indexing time (big indexes, slow indexing).  On the other hand, ''query'' shapes generally scale well to the maximum configured precision regardless of shape size.
   * Rectangles with user-specifiable corners.  Oddly, Solr 3 spatial only supports the bounding box of a circle. 
-  * Multi-value distance sort / score boost.  Note: this is a preliminary unoptimized implementation that uses a fair amount of RAM, even when multiValued=false.  An alternative should be provided in the future.
+  * Multi-value distance sort / score boost.  <!> Note: this is a preliminary unoptimized implementation that uses a fair amount of RAM, even when multiValued=false.  An alternative should be provided in the future.
   * Configurable precision which can vary per shape at query time (and sort of at index time).  This enhances the performance.
   * Fast filtering.  The code was benchmarked once showing it outperforms Solr 3's "LatLonType" at its own game (single valued indexed points), and several 3rd parties anecdotally reported the same, especially for multi-million document indices.  It is based on SOLR-2155 which was benchmarked in January 2010; so a new benchmark is a TODO item.  Also, Solr 3 LatLonType sometimes requires all the points to be in memory, whereas the new spatial module here doesn't for filtering.
   * [[http://en.wikipedia.org/wiki/Well-known_text|Well Known Text]] (WKT) support via JTS.  WKT is arguably the most widely supported textual format for shapes.  However, standard WKT doesn't specify a format for circles.
@@ -57, +57 @@

   * worldBounds="minX minY maxX maxY": Set the valid numerical ranges for x & y.  If geo="true" then this is assumed "-180 -90 180 90".  When geo="false" this is the limits of a Java double however those values have been shown to not work (yet), so definitely choose your boundaries for non-geospatial uses.
   * distCalculator="haversine": Set the distance calculation algorithm.  If geo="true" then haversine is the default, otherwise cartesian is.  The possible values are: haversine, lawOfCosines (warning: faulty), vincentySphere, cartesian, and cartesian^2.
  
- A PrefixTree based field sees the world as a grid.  Each grid cell is further decomposed as another set of grid cells at the next level.  The top-most world level is known as "level 1", the next detailed is "level 2" and so on. Here are the attributes specific to PrefixTree based fields:
+ A PrefixTree based field sees the world as a grid.  Each grid cell is further decomposed as another set of grid cells at the next level.  The first and largest cells have "level 1", the next detailed is "level 2" and so on. Here are the attributes specific to PrefixTree based fields:
  
   * prefixTree="geohash": Choose the spatial grid implementation.  "geohash" uses the Geohash algorithm which has 32 children at each level, and its limited to use when geo="true".  The other implementation is "quad" which has 4 children a each level.
   * maxLevels="10": Set the maximum level (aka grid depth) for indexed data.  It's easier to think in terms of a real distance and use maxDistErr instead.
@@ -90, +90 @@

  
  {{{	 <field name="geo">POLYGON((-10 30, -40 40, -10 -20, 40 20, 0 0, -10 30))</field> }}}
  
- In WKT, coordinates are in "x y" (lon lat) order, and the coordinates are each separated by commas.  ''(The double parenthesis is not a typo; see the WKT spec.)''
+ (That requires JTS, remember).  In WKT, coordinates are in "x y" (lon lat) order, and the coordinates are each separated by commas.  ''(The double parenthesis is not a typo; see the WKT spec.)''
  
  == Search ==
  
@@ -139, +139 @@

  
  === Units, Conversion ===
  
+ Degrees to desired units: Math.toRadians(degrees) * earthRadiusInTheUnitsYouWant
+ 
- Degrees to kilometers:  degrees * 111.2
+ Degrees to kilometers:  degrees * 111.1951  
+ 
- Degrees to miles: degrees * 69.09 
+ Degrees to miles: degrees * 69.09341
  
  Just divide instead of multiply to go the other way.
  
@@ -149, +152 @@

  Shapes other than point, circle, or rectangle require [[http://sourceforge.net/projects/jts-topo-suite/|JTS]], an otherwise optional dependency.  If you want to use [[http://en.wikipedia.org/wiki/Well-known_text|Well Known Text]] (WKT) but only need the basic shapes, you still need JTS -- a restriction likely to be addressed in the near future.
  
   * Due to a combination of things, JTS can't simply be referenced by a "<lib>" entry in solrconfig.xml; it needs to be in WEB-INF/lib in Solr's war file, basically.
-  * JTS views the world as a flat plane; the latitude and longitude are mapped to this plane directly.  It uses Euclidean math operations, not Geodesic ones.  This effectively warps shapes slightly, although it can be a bit much if the vertices are particularly far apart longitudinally.
+  * JTS views the world as a flat plane; the latitude and longitude are mapped to this plane directly.  It uses Euclidean math operations, not Geodetic ones.  This effectively warps shapes slightly, although it can be a bit much if the vertices are particularly far apart longitudinally.
   * Dateline crossing '''is''' supported.  Spatial4j adapts shapes that cross the dateline to be compatible with JTS, and so you shouldn't notice a problem (notwithstanding unknown bugs).
   * Pole wrapping '''is not''' supported. Consequently if you want to index or query by an Antarctica polygon for example, you are out of luck for now.  The only shape that can encompass a pole is a Circle.  Technically a longitude-wrapping (-180 to +180) lat-lon box that touches a pole will too.
   * Only Polygon, and MultiPolygon WKT types have been tested.  GeometryCollection will not work but the others like LineString should in theory.  Holes in polygons haven't been tested but there is code in place to support them.
   * WKT shapes must have each vertex less than 180 degrees in longitude difference than the vertex before it, or else it will be confused as going the wrong way around the globe.  The only exception to this is a Polygon representing a rectangle.
   * All WKT coordinates are normalized into the standard geospatial lat-lon boundaries.  So, -184 longitude becomes +176, for example.  Both +180 and -180 are kept distinct -- true for all of Spatial4j, not just JTS.
-  * The standard way to specify a rectangle in WKT is a Polygon -- WKT doesn't have a rectangle shape.  If you want to specify a Rectangle via WKT (instead of the Spatial4j basic non-WKT syntax), you should take care to specify the coordinates in counter-clockwise order, the WKT standard.  If this is done wrong then the rectangle will go the opposite direction longitudinally, even if it means one that spans nearly the entire globe (>180 degrees width).  OpenLayers seems to not honor the WKT standard here, and depending on the corner you drag the rectangle from, might use a clockwise order.  Some systems like PostGIS don't care what the ordering is, but the problem there is that there is then no way to specify a rectangle that has >= 180 width because there would be ambiguity.  Spatial4j follows the WKT spec.
+  * <!> Common error: <!> The standard way to specify a rectangle in WKT is a Polygon -- WKT doesn't have a rectangle shape.  If you want to specify a Rectangle via WKT (instead of the simple non-WKT syntax seen earlier), you should take care to specify the coordinates in counter-clockwise order, the WKT standard.  If this is done wrong then the rectangle will go the opposite direction longitudinally, even if it means one that spans nearly the entire globe (>180 degrees width).  OpenLayers seems to not honor the WKT standard here, and depending on the corner you drag the rectangle from, might use a clockwise order.  Some systems like PostGIS don't care what the ordering is, but the problem there is that there is then no way to specify a rectangle that has >= 180 width because there would be ambiguity.  Spatial4j follows the WKT spec.
  
  = TODO =