Spatial4j came about as a subset of a body of Java spatial code in support of spatial information-retrieval for Apache Lucene and Solr. Spatial4j is the subset that deals solely with defining shapes, computing distances, shape intersection, and parsing and writing shape strings. To my knowledge, it is only used by Lucene 4's spatial module. Spatial4j is an independent part of Lucene spatial for two reasons: Most importantly, it uses (albeit optionally) the 3rd party JTS library which is LGPL licensed. The Apache Software Foundations forbids a dependency, even an optional one, on LGPL licensed software. The second reason is that Spatial4j should be independently useful on its own. I don't know of the geodetic shape intersection algorithms it has existing in any other open-source software. Perhaps I didn't look hard enough but that is to the best of my knowledge.
Andrew Ross contacted David & Ryan extolling the benefits of LocationTech and we are interested. This has the opportunity to get better visibility to Spatial4j which currently exists in the shadow of Lucene spatial.
Spatial4j has a fairly limited scope largely centered around geometric shape implementations:
- Define geometric shapes, both classic Euclidean/Cartesian two-dimensional ones and geodetic (surface-of-sphere) ones. Some sample shapes are: point, rectangle, circle (aka point-distance), polygon, linestring
- Compute the bounding box of a shape
- Compute the intersection case between a pair of shapes, especially where one of them is a point or rectangle. Intersection cases are intersects, contains, within, and disjoint.
- Compute the area of a shape
- Compute the distance between points (plus other misc. distance / angle calculations)
- Compute a geohash string for a point, and vice-versa, and compute the rectangle for a geohash, (plus other misc. geohash calculations)
- Encode and decode a shape to and from a serialized representation. An example is Well Known Text (WKT).
Spatial4j is a general purpose spatial / geospatial ASL licensed open-source Java library. Its core capabilities are 3-fold: to provide common geospatially-aware shapes, to provide distance calculations and other math, and to read and write the shapes to strings.
Shape classes that are geospatially aware(*)
- Shapes: Point, Rectangle, Circle, Polygon (via JTS)
- shape intersection logic, yielding: disjoint, contains, within, intersects
- bounding box
- area calculation
- Spherical: Law of Cosines, Haversine, Vincenty
- Input and Output of shapes to strings using WKT
- Integration with JTS to adapt its shapes to Spatial4j’s interfaces, including adding some geospatial awareness
- No runtime dependencies unless JTS is needed
In addition, the code is well tested and it’s monitored via Travis-CI continuous integration.
(*) Geospatial awareness, AKA "geodetic" means it is aware of the implications of the international dateline and poles. It can’t pretend the earth is flat and infinitely large.
I hope that Spatial4j will get more visibility so that it will be used more and ultimately so that more people might contribute. Also, the additional processes will make the project better managed from an intellecutal property point of view, which could in turn make it easier to consume for corporations that are more discerning in which open-source libraries they use. Finally, joining LocationTech can bring internship opportunities to improve Spatial4j.
The "spatial4j.com" domain is controlled by Ryan McKinley (a Spatial4j project co-creator / committer). Likewise for the spatial4j GitHub "organziation".
All copyright on source files are assigned to the Apache Software Foundation -- even though Spatial4j isn't an ASF project.
Frankly there isn't any schedule. The last release was over a year ago -- Spatial4j v0.3, August 31 2012. It's overdue for a new release and I'm working on features I want in that release.
The layout of the code in source control is built with Maven and it uses Maven's default layout for organization. It's a single module. As of 2012-09 (1 year ago) I measured ~ 2055 "Non-Comment Source Statements". There has been some development in the last year plus the tests are substantial and don't count towards that number. If you look in the git history, it's apparent that the code was originally named Lucene Spatial Playground (LSP) and once included code for Lucene, Solr, and a demo webapp. Those parts now exist elsewhere and this code, Spatial4j, focuses on what's left -- the shapes. There is a mailing list with very light traffic.
There exists a port of Spatial4j to .NET called, unsurprisingly, Spatial4n. This was done by Itamar Syn-Hershko so that the RavenDB database can use it in conjunction with a port of Lucene's spatial module to the .NET platform.
All code is licensed under the Apache Software License, v2.
All source files are copyrighted by the Apache Software Foundation. It's likely copyright is effectively also held by those who wrote/contributed it originally, but nevertheless the source files all indicate copyright to only Apache. See "Code origins" next.
Code origins (who originally wrote what code):
This information may not matter as it's all copyrighted to the ASF. Most of the code was originally written by David Smiley, Ryan McKinley, and Chris Male, in that order. All are current committers and PMC members to the Apache Lucene/Solr joint project. The only exceptions are GeohashUtils and DistanceUtils which were (orignally) written by Patrick O'Leary years ago (a former Apache Lucene committer. They have both been modified substantially since but are recognizable to their origins. A small number of "very minor" contributions have been made by other parties to the existing code.
- JTS Topology Suite. It's LGPL licensed. JTS is optional to Spatial4j users if you don't use certain features -- namely polygons.
Test Dependencies: (do these matter?)
- Randomized Testing. ASL 2 licensed.
- JUnit. Licensed under the Common Public License v. 1.0
- SLF4J. Is licensed under terms identical to the MIT license. SLF4J's license.