The central objects of the Space package are pairs, < u, s > of a URI, u, and its associated shape, s. The URIs are linked to the shapes with the uri_shape/2 predicate. We will support all OpenGIS Simple Features, points, linestrings, polygons (with >= 0 holes), multi-points, multi-polygons, and geometry collections; and some utility shapes like box and circle regions.1The current version of the Space package, 0.1.2 , only supports points, linestrings, and polygons (with holes) and box regions. Development on the other (multi-)shape types is underway.
Both the URIs and the shapes are represented as Prolog terms. This
makes them first-class Prolog citizens, which allows the construction
and transformation of shapes using regular Prolog clauses, or Definite
Clause Grammars (DCGs). We support input from locations encoded in RDF
with the W3C WGS84
vocabulary and with the GeoRSS
Simple properties and the GeoRSS
where property leading to
an XML literal consisting of a GML element. The uri_shape/2
predicate searches for URI-Shape pairs in SWI-Prolog's RDF triple store.
It matches URIs to Shapes by using WGS84 and GeoRSS properties. For
example, a URI u is associated with the shape s=
if the triple store contains the triples: < u,
lat > and < u,
long >; or when it contains one of the following triples:
or < u,
<gml:pos> lat long
The XML literal containing the GML description of the geometric shape is
parsed with a DCG that can also be used to generate GML from Prolog
?- shape(point(52.3325,4.8673)), shape(box(point(52.3324,4.8621),point(52.3348,4.8684))), shape( polygon([[point(52.3632,4.981)|_], % the outer shell of the polygon [point(52.3631,4.9815)|_] |_ % any number of holes 0..* ])). true. %% uri_shape(?URI, ?Shape) is nondet. ?- uri_shape('http://www.example.org/myoffice', Shape). % read from RDF Shape = point(52.3325,4.8673).
The spatial index can be modified in two ways: By inserting or retracting single URI-shape pairs respectively using the space_assert/3, or the space_retract/3 predicate; or by loading many pairs at once using the space_bulkload/3 predicate or its parameterless counterpart space_index_all/0 which simply loads all the shapes it can find with the uri_shape/2 predicate into the default index. The former method is best for small manipulations of indices, while the latter method is best for the loading of large numbers of URI-shape pairs into an index. The Space package can deal with multiple indices to make it possible to divide sets of features. Indices are identified with a name handle, which can be any Prolog atom.2Every predicate in the Space package that must be given an index handle also has an abbreviated version without the index handle argument which automatically uses the default index. The actual indexing of the shapes is performed using lazy evaluation. Assertions and retractions are put on a queue that belongs to an index. The queue is committed to the index whenever a query is performed, or when a different kind of modification is called for (i.e. when the queue contains assertions and a retraction is requested or vice versa).
?- space_assert(ex:myoffice, point(52.3325,4.8673), demo_index). % only adds it to the 'demo_index' queue true. ?- space_contains(box(point(52.3324,4.8621), point(52.3348,4.8684)), Cont, demo_index). % uses 'demo_index', so triggers a call to space_index('demo_index'). Cont = 'http://www.example.org/myoffice' . % first instantiation, etc.
?- space_bulkload(space, uri_shape, demo_index). true.
% If the KML Geometry elements have an ID attribute, % you can load them from a file, e.g. 'office.kml', like this: ?- space_bulkload(kml_file_uri_shape('office.kml'), 'demo_index'). % Added 12 URI-Shape pairs to demo_index true. % You can insert the same objects one by one like this: ?- forall( kml_file_uri_shape('office.kml', Uri, Shape), space_assert(Uri, Shape, 'demo_index') ). true.
We chose three basic spatial query types as our basic building blocks: containment, intersection, and nearest neighbor. These three query types are implemented as pure Prolog predicates, respectively space_contains/3, space_intersects/3, and space_nearest/3. These predicates work completely analogously, taking an index handle and a query shape to retrieve the URI of a shape matching the query, which is bound to the second argument. Any successive calls to the predicate try to re-instantiate the second argument with a different matching URI. The results of containment and intersection queries are instantiated in no particular order, while the nearest neighbor results are instantiated in order of increasing distance to the query shape. The space_nearest_bounded/4 predicate is a containment query based on space_nearest/3, which returns objects within a certain range of the query shape in order of increasing distance.
?- space_nearest(point(52.3325,4.8673), N, 'demo_index'). N = 'http://sws.geonames.org/2759113/' ; % retry, ask for more N = 'http://sws.geonames.org/2752058/' ; % retry N = 'http://sws.geonames.org/2754074/' . % cut, satisfied
Besides supporting input from RDF we support input and output for other standards, likeGML, KML and WKT. All shapes can be converted from and to these standards with the gml_shape/2, kml_shape/2, and wkt_shape/2 predicates.
% Convert a WKT shape into GML and KML} ?- wkt_shape('POINT ( 52.3325 4.8673 )', Shape), % instantiate from WKT gml_shape(GML, Shape), kml_shape(KML, Shape). Shape = point(52.3325, 4.8673), GML = '<gml:Point><gml:pos>52.3325 4.8673</gml:pos></gml:Point>', KML = '<Point><coordinates>4.8673,52.3325</coordinates></Point>' .
The non-deterministic implementation of the queries makes them behave like a lazy stream of solutions. This allows tight integration with other types of reasoning, like RDF(S) and OWL reasoning or other Prolog rules. An example of combined RDF and spatial reasoning is shown below.
% Finds nearest railway stations in the province Utrecht (in GeoNames) ?- uri_shape(ex:myoffice, Office), rdf(Utrecht, geo:name, literal('Provincie Utrecht')), space_nearest(Office, Near), % 'S' stands for a spot, like a building, 'RSTN' for railway station rdf(Near, geo:featureCode, geo:'S.RSTN'), % 'Near' connected to 'Utrecht' by transitive 'parentFeature' rdf_reachable(Near, geo:parentFeature, Utrecht), rdf(Near, geo:name, literal(Name)), % fetch name of 'Near' uri_shape(Near, Station), % fetch shape of station % compute actual distance in km} space_distance_greatcircle(Office, Station, Distance, km). Utrecht = 'http://sws.geonames.org/2745909/', % first instantiation Near = 'http://sws.geonames.org/6639765/', Name = 'Station Abcoude' , Station = point(52.2761, 4.97904), Distance = 9.85408 ; % etc. Utrecht = 'http://sws.geonames.org/2745909/', % second instantiation Near = 'http://sws.geonames.org/6639764/', Name = 'Station Breukelen' , Station = point(52.17, 4.9906), Distance = 19.9199 . % etc.
Integration of multiple spatial queries can be done in the same way. Since the queries return URIs an intermediate URI-Shape predicate is necessary to get a shape that can be used as a query. An example is shown below.
% Find features inside nearby polygons. ?- uri_shape(ex:myoffice, Office), space_nearest(Office, NearURI), uri_shape(NearURI, NearShape), % look up the shape of the URI 'Near' NearShape = polygon(_), % assert that it must be a polygon} space_contains(NearShape, Contained).
space_bulkload/3 predicate also communicates back across the FLI from C++ to Prolog, allowing the indexing functions to ask for candidates to index from the Prolog database, for example, by calling the uri_shape/2 predicate.
The three search operations provided by the Space package all yield their results incrementally, i.e. one at a time. Prolog predicates actually do not have return values, but instantiate parameters. Multiple return values are returned by subsequently instantiating the same variable, so the first call to a predicate can make different variable instantiations than the second call. This standard support of non-deterministic behavior makes it easy to write incremental algorithms in Prolog.
Internally, the search operations are handled by C++ functions that work on an R*-tree index from the Spatial Index Library . The C++ functions are accessed with the SWI-Prolog foreign language interface. To implement non-deterministic behavior the query functions have to store their state between successive calls and Prolog has to be aware which state is relevant to every call.
Every search query creates an instance of a SpatialIndex::IQueryStrategy class (the IncrementalNearestNeighborStrategy class for INN queries, the IncrementalRangeQuery for containment and intersection queries). This class contains the search algorithm, accesses the R*-tree index, and stores the current state of the algorithm. For containment and intersection queries the results can be returned in any particular order so implementing non-deterministic behavior simply involves storing a pointer to a node in the R*-tree and returning every subsequent matching object. For nearest neighbor queries keeping state is slightly more complicated, because it is necessary to keep a priority queue of candidate results at all times to guarantee that the results are returned in order of increasing proximity.
The Spatial Index library does not include an incremental nearest neighbor, so we implemented an adaptation of the algorithm described in  as an IQueryStrategy. The original algorithm emits results, for example, with a callback function, without breaking from the search loop that finds all matches. Our adaptation breaks the search loop at every matching object and stores a handle to the state (including the priority queue) so that it can restart the search loop where it left off. This makes it possible to tie the query strategy into the non-deterministic foreign language interface of SWI-Prolog with very little time overhead. A pointer to the IQueryStrategy instance is stored on the Prolog stack, so that every successive call to the procedure knows with which query to continue.
An alternative implementation would be to take the exact IncNearest algorithm described in  and to emit the results into a queue. The Prolog stack would then contain a pointer to the queue. Every successive call would dequeue a result from the queue. This strategy is less time efficient, because of two reasons. It does not halt after each match, so it is less efficient when looking for few results. It requires two separate processes to run. One to find results, the other to poll the queue. This means there is some process management and communication overhead.
rtree_storage(S)where S is disk or memory only have effect after clearing or bulkloading. Others, take effect immediately on a running index. More documentation will be provided in the near future.
graph(Graph)option to specify which RDF named graph should be converted to KML.
><extrude>0</extrude>...</Point> will, besides parsing the Point, also instantiate Content with [
extrude(0)] and Attributes with [
Options is an option list that can contain the option
specifying the Name of the document.
Options is an option list that can contain the option
content(+List) that can be used
to add additional attributes or xml element content to a shape. This can
be used to specify things like the ID or name.
Layout elements, like Placemark and Folder, have their own separate extra attributes to supply additional attributes and content. These can contain the special terms geom_attributes and geom_content that pass their content to the shape contained by the Placemark. For example, rendering a Placemark with the ID "placemark12" of an extruded Point shape with its URI as name of the Placemark and as ID of the shape and an additional styleUrl works as follows:
kml_save_shape(Stream, placemark(point(53.0,3.9), [ id(placemark12), geom_attributes([ id(URI) ]) ], [ name(URI),styleUrl(URI), geom_content([ extrude(1) ]) ]), ).