Apache Lucene open-source search software
Improve user-facing docs for geo package (#14534)
Ankit Jainbb8b1397b014
diff --git a/lucene/CHANGES.txt b/lucene/CHANGES.txtindex 9dca1db2c27..e06262af574 100644--- a/lucene/CHANGES.txt+++ b/lucene/CHANGES.txt@@ -81,10 +81,12 @@ New FeaturesImprovements----------------------* GITHUB#14458 : Add an IndexDeletion policy that retains the last N commits. (Owais Kazi)+* GITHUB#14458: Add an IndexDeletion policy that retains the last N commits. (Owais Kazi)* GITHUB#14476: Removing unnecessary splitX in ComponentTree (Ankit Jain)+* GITHUB#14534: Improve user-facing docs for geo package (Ankit Jain)+* GITHUB#14602: Refactor the expressions compiler to use official ClassData BSM with indexed lookup(Uwe Schindler)diff --git a/lucene/core/src/java/org/apache/lucene/geo/Circle.java b/lucene/core/src/java/org/apache/lucene/geo/Circle.javaindex 9d5357a7111..c079b8000dd 100644--- a/lucene/core/src/java/org/apache/lucene/geo/Circle.java+++ b/lucene/core/src/java/org/apache/lucene/geo/Circle.java@@ -17,27 +17,43 @@package org.apache.lucene.geo;/**- * Represents a circle on the earth's surface.+ * Represents a circle on the Earth's surface defined by a center point and radius.*- * <p>NOTES:+ * <p>The circle is defined using:*- * <ol>- * <li>Latitude/longitude values must be in decimal degrees.- * <li>Radius must be in meters.- * <li>For more advanced GeoSpatial indexing and query operations see the {@code spatial-extras}- * module- * </ol>+ * <ul>+ * <li>Center point (latitude/longitude in degrees)+ * <li>Radius in meters+ * </ul>+ *+ * <p>Important Notes:+ *+ * <ul>+ * <li>The circle is approximated on the spherical Earth model+ * <li>For very large circles or circles near poles, consider using polygons instead+ * <li>Dateline crossing is handled automatically+ * </ul>+ *+ * <p>Example usage:+ *+ * <pre>{@code+ * // Create a circle with 1km radius around the Eiffel Tower+ * Circle circle = new Circle(48.8584, 2.2945, 1000);+ *+ * // Create a query using this circle+ * Query query = LatLonShape.newDistanceQuery("location", circle);+ * }</pre>** @lucene.experimental*/public final class Circle extends LatLonGeometry {- /** Center latitude */+ /** Center latitude of the circle in degrees (-90 to 90) */private final double lat;- /** Center longitude */+ /** Center longitude of the circle in degrees (-180 to 180) */private final double lon;- /** radius in meters */+ /** radius of the circle in meters */private final double radiusMeters;/** Creates a new circle from the supplied latitude/longitude center and a radius in meters.. */diff --git a/lucene/core/src/java/org/apache/lucene/geo/GeoUtils.java b/lucene/core/src/java/org/apache/lucene/geo/GeoUtils.javaindex 7f7278d066c..16c2ecd80f4 100644--- a/lucene/core/src/java/org/apache/lucene/geo/GeoUtils.java+++ b/lucene/core/src/java/org/apache/lucene/geo/GeoUtils.java@@ -23,7 +23,28 @@ import org.apache.lucene.index.PointValues.Relation;import org.apache.lucene.util.SloppyMath;/**- * Basic reusable geo-spatial utility methods+ * Utility methods for geo-spatial calculations and coordinate validation.+ *+ * <p>This class provides:+ *+ * <ul>+ * <li>Coordinate validation methods+ * <li>Earth model constants+ * <li>Common geometric calculations+ * <li>Coordinate normalization utilities+ * </ul>+ *+ * <p>Important Constants:+ *+ * <ul>+ * <li>Earth's mean radius: 6,371,008.7714 meters+ * <li>Latitude range: -90° to +90°+ * <li>Longitude range: -180° to +180°+ * </ul>+ *+ * <p>Note: This class uses a spherical Earth model for simplicity and performance. For applications+ * requiring higher precision, consider using a geodetic library that implements the WGS84 ellipsoid+ * model.** @lucene.experimental*/diff --git a/lucene/core/src/java/org/apache/lucene/geo/Rectangle.java b/lucene/core/src/java/org/apache/lucene/geo/Rectangle.javaindex 6435d745243..63fa0a17422 100644--- a/lucene/core/src/java/org/apache/lucene/geo/Rectangle.java+++ b/lucene/core/src/java/org/apache/lucene/geo/Rectangle.java@@ -32,18 +32,51 @@ import static org.apache.lucene.util.SloppyMath.asin;import static org.apache.lucene.util.SloppyMath.cos;import static org.apache.lucene.util.SloppyMath.sin;-/** Represents a lat/lon rectangle. */+/**+ * Represents a rectangular bounding box on Earth's surface.+ *+ * <p>A rectangle is defined by its minimum and maximum latitude/longitude coordinates. It can cross+ * the dateline, in which case minLon > maxLon.+ *+ * <p>Key Features:+ *+ * <ul>+ * <li>Handles dateline crossing automatically+ * <li>Supports point-in-box testing+ * <li>Can be used to create spatial queries+ * <li>Useful for creating bounding boxes around other shapes+ * </ul>+ *+ * <p>Example usage:+ *+ * <pre>{@code+ * // Create a rectangle covering central London+ * Rectangle bbox = new Rectangle(51.4, 51.6, -0.2, 0.0);+ *+ * // Create a rectangle crossing the dateline+ * Rectangle datelineBox = new Rectangle(20, 30, 170, -170);+ *+ * // Create a bounding box around a point with given radius+ * Rectangle circle = Rectangle.fromPointDistance(lat, lon, radiusMeters);+ * }</pre>+ *+ * <p>Note: When working with areas near poles, consider that rectangles become highly distorted and+ * may not provide accurate representation of the actual area.+ */public class Rectangle extends LatLonGeometry {- /** maximum longitude value (in degrees) */+ /** Minimum latitude in degrees (-90 to 90) */public final double minLat;- /** minimum longitude value (in degrees) */- public final double minLon;-- /** maximum latitude value (in degrees) */+ /** Maximum latitude in degrees (-90 to 90) */public final double maxLat;- /** minimum latitude value (in degrees) */+ /**+ * Minimum longitude in degrees (-180 to 180). May be greater than maxLon when crossing the+ * dateline.+ */+ public final double minLon;++ /** Maximum longitude in degrees (-180 to 180) */public final double maxLon;/**diff --git a/lucene/core/src/java/org/apache/lucene/geo/package-info.java b/lucene/core/src/java/org/apache/lucene/geo/package-info.javaindex b0e6d3224e2..bb34fa8daea 100644--- a/lucene/core/src/java/org/apache/lucene/geo/package-info.java+++ b/lucene/core/src/java/org/apache/lucene/geo/package-info.java@@ -15,5 +15,54 @@* limitations under the License.*/-/** Geospatial Utility Implementations for Lucene Core */+/**+ * Core geo-spatial types and utilities for handling geographical data and spatial operations in+ * Lucene.+ *+ * <h2>Overview</h2>+ *+ * This package provides classes for representing, indexing, and querying geographical data in+ * Lucene. It uses the WGS84 coordinate system with latitude/longitude pairs to represent points on+ * Earth.+ *+ * <h2>Core Concepts</h2>+ *+ * <ul>+ * <li>Coordinate System: WGS84 (World Geodetic System 1984)+ * <ul>+ * <li>Latitude: -90° to +90° (negative for South, positive for North)+ * <li>Longitude: -180° to +180° (negative for West, positive for East)+ * </ul>+ * <li>Distance calculations use haversine formula on a spherical Earth model+ * <li>Areas near poles and the dateline receive special handling+ * </ul>+ *+ * <h2>Key Components</h2>+ *+ * <ul>+ * <li>{@link org.apache.lucene.geo.Point}: Represents a point on Earth's surface+ * <li>{@link org.apache.lucene.geo.Rectangle}: Defines a bounding box for spatial queries+ * <li>{@link org.apache.lucene.geo.Circle}: Represents a circular area with a center point and+ * radius+ * <li>{@link org.apache.lucene.geo.Polygon}: Represents an arbitrary polygon shape+ * <li>{@link org.apache.lucene.geo.Line}: Represents a path or line string+ * </ul>+ *+ * <h2>Common Operations</h2>+ *+ * <ul>+ * <li>Distance calculations between points+ * <li>Point-in-polygon testing+ * <li>Rectangle containment and intersection+ * <li>Creation of bounding boxes+ * <li>Polygon validation and preprocessing+ * </ul>+ *+ * <h2>Usage Examples</h2>+ *+ * <pre>{@code+ * Rectangle bbox = Rectangle.fromPointDistance(51.5, -0.12, 5000); // 5km around London+ * Circle circle = new Circle(48.8566, 2.3522, 1000); // 1km around Paris+ * }</pre>+ */package org.apache.lucene.geo;