Package org.apache.lucene.document

## Class XYShape

- java.lang.Object
- - org.apache.lucene.document.XYShape

-     public class XYShape
      extends Object

  A cartesian shape utility class for indexing and searching geometries whose vertices are unitless x, y values.

  This class defines seven static factory methods for common indexing and search operations:

  - `createIndexableFields(String, XYPolygon)` for indexing a cartesian polygon.
  - `createDocValueField(String, XYPolygon)` for indexing a cartesian polygon doc value field.
  - `createIndexableFields(String, XYPolygon, boolean)` for indexing a cartesian polygon with the possibility of checking for self-intersections.
  - `createIndexableFields(String, XYPolygon, boolean)` for indexing a cartesian polygon doc value field with the possibility of checking for self-intersections.
  - `createIndexableFields(String, XYLine)` for indexing a cartesian linestring.
  - `createDocValueField(String, XYLine)` for indexing a cartesian linestring doc value.
  - `createIndexableFields(String, float, float)` for indexing a x, y cartesian point.
  - `createDocValueField(String, float, float)` for indexing a x, y cartesian point doc value.
  - `createDocValueField(String, BytesRef)` for indexing a cartesian doc value from existing encoding.
  - `newBoxQuery()` for matching cartesian shapes that have some `ShapeField.QueryRelation` with a bounding box.
  - `newLineQuery()` for matching cartesian shapes that have some `ShapeField.QueryRelation` with a linestring.
  - `newPolygonQuery()` for matching cartesian shapes that have some `ShapeField.QueryRelation` with a polygon.
  - `newGeometryQuery()` for matching cartesian shapes that have some `ShapeField.QueryRelation` with one or more `XYGeometry`.
  - `createXYShapeDocValues(BytesRef)` for creating the `XYShapeDocValues`
  WARNING: Like `LatLonPoint`, vertex values are indexed with some loss of precision from the original `double` values.
  See Also:
    `PointValues`, `XYDocValuesField`

- - ### Method Summary

    All Methods Static Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `static XYShapeDocValuesField` | `createDocValueField​(String fieldName, float x, float y)` | create a `XYShapeDocValuesField` for cartesian points without creating indexable fields.
    `static XYShapeDocValuesField` | `createDocValueField​(String fieldName, List<ShapeField.DecodedTriangle> tessellation)` | create a `XYShapeDocValuesField` from a precomputed tessellation
    `static XYShapeDocValuesField` | `createDocValueField​(String fieldName, XYLine line)` | create doc value field for x, y line geometry without creating indexable fields.
    `static XYShapeDocValuesField` | `createDocValueField​(String fieldName, XYPolygon polygon)` | create doc value field for X,Y polygon geometry without creating indexable fields
    `static XYShapeDocValuesField` | `createDocValueField​(String fieldName, XYPolygon polygon, boolean checkSelfIntersections)` | create doc value field for lat lon polygon geometry without creating indexable fields.
    `static XYShapeDocValuesField` | `createDocValueField​(String fieldName, BytesRef binaryValue)` | create a `XYShapeDocValuesField` from an existing encoded representation
    `static Field[]` | `createIndexableFields​(String fieldName, float x, float y)` | create indexable fields for cartesian point geometry
    `static Field[]` | `createIndexableFields​(String fieldName, XYLine line)` | create indexable fields for cartesian line geometry
    `static Field[]` | `createIndexableFields​(String fieldName, XYPolygon polygon)` | create indexable fields for cartesian polygon geometry
    `static Field[]` | `createIndexableFields​(String fieldName, XYPolygon polygon, boolean checkSelfIntersections)` | create indexable fields for cartesian polygon geometry.
    `static XYShapeDocValues` | `createXYShapeDocValues​(BytesRef bytesRef)` | Factory method for creating the `XYShapeDocValues`
    `static Query` | `newBoxQuery​(String field, ShapeField.QueryRelation queryRelation, float minX, float maxX, float minY, float maxY)` | create a query to find all cartesian shapes that intersect a defined bounding box *
    `static Query` | `newDistanceQuery​(String field, ShapeField.QueryRelation queryRelation, XYCircle... circle)` | create a query to find all cartesian shapes that intersect a provided circle (or arrays of circles) *
    `static Query` | `newGeometryQuery​(String field, ShapeField.QueryRelation queryRelation, XYGeometry... xyGeometries)` | create a query to find all indexed geo shapes that intersect a provided geometry collection note: Components do not support dateline crossing
    `static Query` | `newLineQuery​(String field, ShapeField.QueryRelation queryRelation, XYLine... lines)` | create a query to find all cartesian shapes that intersect a provided linestring (or array of linestrings) *
    `static Query` | `newPointQuery​(String field, ShapeField.QueryRelation queryRelation, float[]... points)` | create a query to find all indexed shapes that comply the `ShapeField.QueryRelation` with the provided point
    `static Query` | `newPolygonQuery​(String field, ShapeField.QueryRelation queryRelation, XYPolygon... polygons)` | create a query to find all cartesian shapes that intersect a provided polygon (or array of polygons) *
    `static Query` | `newSlowDocValuesBoxQuery​(String field, ShapeField.QueryRelation queryRelation, float minX, float maxX, float minY, float maxY)` | create a docvalue query to find all cartesian shapes that intersect a defined bounding box *

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

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

- - ### Method Detail

    - #### createIndexableFields

          public static Field[] createIndexableFields​(String fieldName,
                                                      XYPolygon polygon)

      create indexable fields for cartesian polygon geometry

    - #### createDocValueField

          public static XYShapeDocValuesField createDocValueField​(String fieldName,
                                                                  XYPolygon polygon)

      create doc value field for X,Y polygon geometry without creating indexable fields

    - #### createIndexableFields

          public static Field[] createIndexableFields​(String fieldName,
                                                      XYPolygon polygon,
                                                      boolean checkSelfIntersections)

      create indexable fields for cartesian polygon geometry. If `checkSelfIntersections` is set to true, the validity of the provided polygon is checked with a small performance penalty.

    - #### createDocValueField

          public static XYShapeDocValuesField createDocValueField​(String fieldName,
                                                                  XYPolygon polygon,
                                                                  boolean checkSelfIntersections)

      create doc value field for lat lon polygon geometry without creating indexable fields.

    - #### createIndexableFields

          public static Field[] createIndexableFields​(String fieldName,
                                                      XYLine line)

      create indexable fields for cartesian line geometry

    - #### createDocValueField

          public static XYShapeDocValuesField createDocValueField​(String fieldName,
                                                                  XYLine line)

      create doc value field for x, y line geometry without creating indexable fields.

    - #### createIndexableFields

          public static Field[] createIndexableFields​(String fieldName,
                                                      float x,
                                                      float y)

      create indexable fields for cartesian point geometry

    - #### createDocValueField

          public static XYShapeDocValuesField createDocValueField​(String fieldName,
                                                                  float x,
                                                                  float y)

      create a `XYShapeDocValuesField` for cartesian points without creating indexable fields.

    - #### createDocValueField

          public static XYShapeDocValuesField createDocValueField​(String fieldName,
                                                                  BytesRef binaryValue)

      create a `XYShapeDocValuesField` from an existing encoded representation

    - #### createDocValueField

          public static XYShapeDocValuesField createDocValueField​(String fieldName,
                                                                  List<ShapeField.DecodedTriangle> tessellation)

      create a `XYShapeDocValuesField` from a precomputed tessellation

    - #### newBoxQuery

          public static Query newBoxQuery​(String field,
                                          ShapeField.QueryRelation queryRelation,
                                          float minX,
                                          float maxX,
                                          float minY,
                                          float maxY)

      create a query to find all cartesian shapes that intersect a defined bounding box *

    - #### newSlowDocValuesBoxQuery

          public static Query newSlowDocValuesBoxQuery​(String field,
                                                       ShapeField.QueryRelation queryRelation,
                                                       float minX,
                                                       float maxX,
                                                       float minY,
                                                       float maxY)

      create a docvalue query to find all cartesian shapes that intersect a defined bounding box *

    - #### newLineQuery

          public static Query newLineQuery​(String field,
                                           ShapeField.QueryRelation queryRelation,
                                           XYLine... lines)

      create a query to find all cartesian shapes that intersect a provided linestring (or array of linestrings) *

    - #### newPolygonQuery

          public static Query newPolygonQuery​(String field,
                                              ShapeField.QueryRelation queryRelation,
                                              XYPolygon... polygons)

      create a query to find all cartesian shapes that intersect a provided polygon (or array of polygons) *

    - #### newPointQuery

          public static Query newPointQuery​(String field,
                                            ShapeField.QueryRelation queryRelation,
                                            float[]... points)

      create a query to find all indexed shapes that comply the `ShapeField.QueryRelation` with the provided point

    - #### newDistanceQuery

          public static Query newDistanceQuery​(String field,
                                               ShapeField.QueryRelation queryRelation,
                                               XYCircle... circle)

      create a query to find all cartesian shapes that intersect a provided circle (or arrays of circles) *

    - #### newGeometryQuery

          public static Query newGeometryQuery​(String field,
                                               ShapeField.QueryRelation queryRelation,
                                               XYGeometry... xyGeometries)

      create a query to find all indexed geo shapes that intersect a provided geometry collection note: Components do not support dateline crossing

    - #### createXYShapeDocValues

          public static XYShapeDocValues createXYShapeDocValues​(BytesRef bytesRef)

      Factory method for creating the `XYShapeDocValues`
      Parameters:
        `bytesRef` - `BytesRef`
      Returns:
        `XYShapeDocValues`