edu.ucsb.adl.middleware
Class SpatialRanker

java.lang.Object
  |
  +--edu.ucsb.adl.middleware.SpatialRanker

All Implemented Interfaces:

Ranker, XmlHandler

public final class SpatialRanker

extends java.lang.Object

implements Ranker, XmlHandler

Ranks query results by spatial similarity to the query region. Results having spatial footprints that are more similar to the query region are ranked higher.

The query must contain a spatial constraint against bucket adl:geographic-locations; if not, an exception is raised. Limitation: if the query region is a polygon, the polygon's bounding box is used for ranking purposes.

A result's spatial footprint is obtained from the result's mapping to the adl:geographic-locations bucket in its ADL bucket view. If the result has more than one such mapping, the mapping that results in the highest rank is used; if the result has no such mappings, it is assigned a minimal rank. Limitation: as with the query region, if the spatial footprint is a polygon or polyline, the polygon's or polyline's bounding box is used for ranking purposes.

This class supports two algorithms for computing spatial similarity. In both algorithms, "spatial similarity" means similarity in terms of size, shape, and location.

In the "hausdorff-distance" algorithm, a result's rank is determined by the Hausdorff distance between its spatial footprint and the query region; the smaller the distance, the higher the rank. The so-called "directed Hausdorff distance" from a region A to a region B is the distance between the point p in A that is farthest from any point in B and the point q in B that is closest to p. The Hausdorff distance between A and B is then the maximum of the directed distance from A to B and the directed distance from B to A. Intuitively, the Hausdorff distance is a measure of the mismatch between A and B: if the Hausdorff distance is d, then every point of A is within distance d of some point of B and vice versa.

In the "intersection-union-ratio" algorithm, a result's rank is determined by the ratio of 1) the area of the intersection of its spatial footprint and the query region to 2) the area of the union of its spatial footprint and the query region; the greater the ratio, the higher the rank. If the query region has zero area, all results are assigned a minimal rank.

This class computes spatial similarity using a truncated cylinder manifold as the underlying topology. That is, the distance is computed in an equirectangular projection, but there is no discontinuity at the +/-180 meridian (or any other meridian).

For more information, see Spatial Similarity Functions.

Version:

$Header: /export/home/gjanee/middleware/edu/ucsb/adl/middleware/RCS/SpatialRanker.java,v 1.1 2004/09/05 21:43:21 gjanee Exp $

$Log: SpatialRanker.java,v $ Revision 1.1 2004/09/05 21:43:21 gjanee Initial revision

Author:

Greg Janée
Alexandria Digital Library

Method Summary

void	characters(char[] string, int start, int length) For use by ValidatingXmlParser only.
static edu.ucsb.adl.middleware.SpatialRanker	createRanker(java.lang.String algorithm) Creates a SpatialRanker.
void	endElement(int elementCode) For use by ValidatingXmlParser only.
static void	main(java.lang.String[] args) Test driver.
double	rank(edu.ucsb.adl.middleware.Result result, edu.ucsb.adl.middleware.Query query) Ranks a query result.
void	startElement(int elementCode, java.lang.String[] attributes) For use by ValidatingXmlParser only.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

createRanker

public static edu.ucsb.adl.middleware.SpatialRanker createRanker(java.lang.String algorithm)
                                                          throws InternalErrorException

Creates a SpatialRanker. The ranker may be invoked multiple times, but is not multithread-safe.

Parameters:

algorithm - The algorithm to use. Must be either "hausdorff-distance" or "intersection-union-ratio".

Returns:

A SpatialRanker.

Throws:

InternalErrorException - If algorithm is invalid.

rank

public double rank(edu.ucsb.adl.middleware.Result result,
                   edu.ucsb.adl.middleware.Query query)
            throws InternalErrorException

Ranks a query result. This method is not multithread-safe.

Specified by:

rank in interface Ranker

Parameters:

result - The result.

query - The query that produced the result, which must contain a spatial constraint against bucket adl:geographic-locations.

Returns:

The result's rank.

Throws:

InternalErrorException - If any error occurs.

startElement

public void startElement(int elementCode,
                         java.lang.String[] attributes)

For use by ValidatingXmlParser only.

Specified by:

startElement in interface XmlHandler

Parameters:

elementCode - The element's code.

attributes - Element attribute values, indexed by attribute code. All of the element's declared attributes are represented in the array; attributes for which a value is specified in the document or for which there is a DTD-specified default have non-null values. The handler should reference the array for the duration of the call only, as it is reused by the parser. Also, the array may be longer than necessary.

endElement

public void endElement(int elementCode)
                throws XmlException

For use by ValidatingXmlParser only.

Specified by:

endElement in interface XmlHandler

Parameters:

elementCode - The element's code.

Throws:

XmlException - If any error occurs.

characters

public void characters(char[] string,
                       int start,
                       int length)

For use by ValidatingXmlParser only.

Specified by:

characters in interface XmlHandler

Parameters:

string - The textual content.

start - The index in string at which the textual content starts.

length - The length of the content.

main

public static void main(java.lang.String[] args)
                 throws java.io.IOException,
                        InternalErrorException

Test driver.

java.io.IOException

InternalErrorException