org.apache.lucene.spatial.bbox

## Class BBoxOverlapRatioValueSource

- java.lang.Object
- - org.apache.lucene.search.DoubleValuesSource
  - - org.apache.lucene.spatial.bbox.BBoxSimilarityValueSource
    - - org.apache.lucene.spatial.bbox.BBoxOverlapRatioValueSource

- All Implemented Interfaces:
    SegmentCacheable

      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.

- - ### Field Summary

    - ### Fields inherited from class org.apache.lucene.search.DoubleValuesSource

      `SCORES`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BBoxOverlapRatioValueSource(ShapeValuesSource rectValueSource, boolean isGeo, org.locationtech.spatial4j.shape.Rectangle queryExtent, double queryTargetProportion, double minSideLength)`
    `BBoxOverlapRatioValueSource(ShapeValuesSource 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

    All Methods Instance Methods Concrete Methods
    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.toString()`.

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

      `explain, getValues, isCacheable, needsScores, rewrite, toString`

    - ### Methods inherited from class org.apache.lucene.search.DoubleValuesSource

      `constant, fromDoubleField, fromField, fromFloatField, fromIntField, fromLongField, fromQuery, fromScorer, getSortField, toLongValuesSource`

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### BBoxOverlapRatioValueSource

          public BBoxOverlapRatioValueSource(ShapeValuesSource 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(ShapeValuesSource 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.toString()`.
      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.

Copyright © 2000-2022 Apache Software Foundation. All Rights Reserved.