org.apache.lucene.spatial.bbox

Class BBoxOverlapRatioValueSource

java.lang.Object

org.apache.lucene.queries.function.ValueSource

org.apache.lucene.spatial.bbox.BBoxSimilarityValueSource

org.apache.lucene.spatial.bbox.BBoxOverlapRatioValueSource

public class BBoxOverlapRatioValueSource
extends BBoxSimilarityValueSource

The algorithm is implemented as envelope on envelope (rect on rect) overlays rather than complex polygon on complex polygon overlays.

Spatial relevance scoring algorithm:

queryArea

the area of the input query envelope

targetArea

the area of the target envelope (per Lucene document)

intersectionArea

the area of the intersection between the query and target envelopes

queryTargetProportion

A 0-1 factor that divides the score proportion between query and target. 0.5 is evenly.

queryRatio

intersectionArea / queryArea; (see note)

targetRatio

intersectionArea / targetArea; (see note)

queryFactor

queryRatio * queryTargetProportion;

targetFactor

targetRatio * (1 - queryTargetProportion);

score

queryFactor + targetFactor;

Additionally, note that an optional minimum side length minSideLength may be used whenever an area is calculated (queryArea, targetArea, intersectionArea). This allows for points or horizontal/vertical lines to be used as the query shape and in such case the descending order should have smallest boxes up front. Without this, a point or line query shape typically scores everything with the same value since there is 0 area.

Note: The actual computation of queryRatio and targetRatio is more complicated so that it considers points and lines. Lines have the ratio of overlap, and points are either 1.0 or 0.0 depending on whether it intersects or not.

Originally based on Geoportal's SpatialRankingValueSource but modified quite a bit. GeoPortal's algorithm will yield a score of 0 if either a line or point is compared, and it doesn't output a 0-1 normalized score (it multiplies the factors), and it doesn't support minSideLength, and it had dateline bugs.

WARNING: This API is experimental and might change in incompatible ways in the next release.

Constructor Summary

Constructors

Constructor and Description
BBoxOverlapRatioValueSource(ValueSource rectValueSource, boolean isGeo, org.locationtech.spatial4j.shape.Rectangle queryExtent, double queryTargetProportion, double minSideLength)
BBoxOverlapRatioValueSource(ValueSource rectValueSource, org.locationtech.spatial4j.shape.Rectangle queryExtent) Construct with 75% weighting towards target (roughly GeoPortal's default), geo degrees assumed, no minimum side length.

Method Summary

Modifier and Type	Method and Description
boolean	equals(Object o)
int	hashCode()
protected double	score(org.locationtech.spatial4j.shape.Rectangle target, AtomicReference<Explanation> exp) Return a relevancy score.
protected String	similarityDescription() A comma-separated list of configurable items of the subclass to put into BBoxSimilarityValueSource.description().

Methods inherited from class org.apache.lucene.spatial.bbox.BBoxSimilarityValueSource

createWeight, description, getValues

Methods inherited from class org.apache.lucene.queries.function.ValueSource

asDoubleValuesSource, asLongValuesSource, getSortField, newContext, toString

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Constructor Detail

BBoxOverlapRatioValueSource

public BBoxOverlapRatioValueSource(ValueSource rectValueSource,
                                   boolean isGeo,
                                   org.locationtech.spatial4j.shape.Rectangle queryExtent,
                                   double queryTargetProportion,
                                   double minSideLength)

Parameters:

rectValueSource - mandatory; source of rectangles

isGeo - True if ctx.isGeo() and thus dateline issues should be attended to

queryExtent - mandatory; the query rectangle

queryTargetProportion - see class javadocs. Between 0 and 1.

minSideLength - see class javadocs. 0.0 will effectively disable.

BBoxOverlapRatioValueSource

public BBoxOverlapRatioValueSource(ValueSource rectValueSource,
                                   org.locationtech.spatial4j.shape.Rectangle queryExtent)

Construct with 75% weighting towards target (roughly GeoPortal's default), geo degrees assumed, no minimum side length.

Method Detail

equals

public boolean equals(Object o)

Overrides:

equals in class BBoxSimilarityValueSource

hashCode

public int hashCode()

Overrides:

hashCode in class BBoxSimilarityValueSource

similarityDescription

protected String similarityDescription()

Description copied from class: BBoxSimilarityValueSource

A comma-separated list of configurable items of the subclass to put into BBoxSimilarityValueSource.description().

Specified by:

similarityDescription in class BBoxSimilarityValueSource

score

protected double score(org.locationtech.spatial4j.shape.Rectangle target,
                       AtomicReference<Explanation> exp)

Description copied from class: BBoxSimilarityValueSource

Return a relevancy score. If exp is provided then diagnostic information is added.

Specified by:

score in class BBoxSimilarityValueSource

Parameters:

target - The indexed rectangle; not null.

exp - Optional diagnostic holder.

Returns:

a score.