Karl, do you mind backporting this to branch_6x too? This API is new there and I think we should just have this stuff defined the way we want from the start.
For geo3d changes, its up to you. I personally think those would be good too, especially as we make it more accessible and easier for people to experiment with. On Mon, Apr 4, 2016 at 12:15 PM, <[email protected]> wrote: > Repository: lucene-solr > Updated Branches: > refs/heads/master 0843e95f0 -> ed6f2b0d0 > > > LUCENE-7157: Update API javadoc and Polygon method visibilities > > > Project: http://git-wip-us.apache.org/repos/asf/lucene-solr/repo > Commit: http://git-wip-us.apache.org/repos/asf/lucene-solr/commit/ed6f2b0d > Tree: http://git-wip-us.apache.org/repos/asf/lucene-solr/tree/ed6f2b0d > Diff: http://git-wip-us.apache.org/repos/asf/lucene-solr/diff/ed6f2b0d > > Branch: refs/heads/master > Commit: ed6f2b0d0c2bd8023949fd6113b4900c249643b0 > Parents: 0843e95 > Author: Karl Wright <[email protected]> > Authored: Mon Apr 4 12:13:37 2016 -0400 > Committer: Karl Wright <[email protected]> > Committed: Mon Apr 4 12:13:37 2016 -0400 > > ---------------------------------------------------------------------- > lucene/core/src/java/org/apache/lucene/geo/Polygon.java | 10 ++++++++++ > .../src/java/org/apache/lucene/document/LatLonPoint.java | 5 ++--- > .../apache/lucene/document/LatLonPointInPolygonQuery.java | 3 +-- > .../spatial/geopoint/search/GeoPointInPolygonQuery.java | 10 ++-------- > 4 files changed, 15 insertions(+), 13 deletions(-) > ---------------------------------------------------------------------- > > > http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ed6f2b0d/lucene/core/src/java/org/apache/lucene/geo/Polygon.java > ---------------------------------------------------------------------- > diff --git a/lucene/core/src/java/org/apache/lucene/geo/Polygon.java > b/lucene/core/src/java/org/apache/lucene/geo/Polygon.java > index 3f32920..a5da229 100644 > --- a/lucene/core/src/java/org/apache/lucene/geo/Polygon.java > +++ b/lucene/core/src/java/org/apache/lucene/geo/Polygon.java > @@ -20,6 +20,16 @@ import java.util.Arrays; > > /** > * Represents a closed polygon on the earth's surface. > + * <p> > + * NOTES: > + * <ol> > + * <li>Coordinates must be in clockwise order, except for holes. Holes > must be in counter-clockwise order. > + * <li>The polygon must be closed: the first and last coordinates need to > have the same values. > + * <li>The polygon must not be self-crossing, otherwise may result in > unexpected behavior. > + * <li>All latitude/longitude values must be in decimal degrees. > + * <li>Polygons cannot cross the 180th meridian. Instead, use two > polygons: one on each side. > + * <li>For more advanced GeoSpatial indexing and query operations see the > {@code spatial-extras} module > + * </ol> > * @lucene.experimental > */ > public final class Polygon { > > http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ed6f2b0d/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java > ---------------------------------------------------------------------- > diff --git > a/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java > b/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java > index 26bb04a..0d8a7b2 100644 > --- a/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java > +++ b/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPoint.java > @@ -339,13 +339,12 @@ public class LatLonPoint extends Field { > } > > /** > - * Create a query for matching a polygon. > - * <p> > - * The supplied {@code polygon} must be clockwise or counter-clockwise. > + * Create a query for matching one or more polygons. > * @param field field name. must not be null. > * @param polygons array of polygons. must not be null or empty > * @return query matching points within this polygon > * @throws IllegalArgumentException if {@code field} is null, {@code > polygons} is null or empty > + * @see Polygon > */ > public static Query newPolygonQuery(String field, Polygon... polygons) { > return new LatLonPointInPolygonQuery(field, polygons); > > http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ed6f2b0d/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPointInPolygonQuery.java > ---------------------------------------------------------------------- > diff --git > a/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPointInPolygonQuery.java > > b/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPointInPolygonQuery.java > index 54f5192..f27386c 100644 > --- > a/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPointInPolygonQuery.java > +++ > b/lucene/sandbox/src/java/org/apache/lucene/document/LatLonPointInPolygonQuery.java > @@ -55,8 +55,7 @@ final class LatLonPointInPolygonQuery extends Query { > final String field; > final Polygon[] polygons; > > - /** The lats/lons must be clockwise or counter-clockwise. */ > - public LatLonPointInPolygonQuery(String field, Polygon[] polygons) { > + LatLonPointInPolygonQuery(String field, Polygon[] polygons) { > if (field == null) { > throw new IllegalArgumentException("field must not be null"); > } > > http://git-wip-us.apache.org/repos/asf/lucene-solr/blob/ed6f2b0d/lucene/spatial/src/java/org/apache/lucene/spatial/geopoint/search/GeoPointInPolygonQuery.java > ---------------------------------------------------------------------- > diff --git > a/lucene/spatial/src/java/org/apache/lucene/spatial/geopoint/search/GeoPointInPolygonQuery.java > > b/lucene/spatial/src/java/org/apache/lucene/spatial/geopoint/search/GeoPointInPolygonQuery.java > index 17ce54d..a06bdc0 100644 > --- > a/lucene/spatial/src/java/org/apache/lucene/spatial/geopoint/search/GeoPointInPolygonQuery.java > +++ > b/lucene/spatial/src/java/org/apache/lucene/spatial/geopoint/search/GeoPointInPolygonQuery.java > @@ -36,13 +36,7 @@ import org.apache.lucene.geo.Polygon; > * term is passed to the final point in polygon check. All value comparisons > are subject > * to the same precision tolerance defined in {@value > GeoEncodingUtils#TOLERANCE} > * > - * <p>NOTES: > - * 1. The polygon coordinates need to be in either clockwise or > counter-clockwise order. > - * 2. The polygon must not be self-crossing, otherwise the query may > result in unexpected behavior > - * 3. All latitude/longitude values must be in decimal degrees. > - * 4. Complex computational geometry (e.g., dateline wrapping) is not > supported > - * 5. For more advanced GeoSpatial indexing and query operations see > spatial module > - * > + * @see Polygon > * @lucene.experimental > */ > public final class GeoPointInPolygonQuery extends GeoPointInBBoxQuery { > @@ -79,7 +73,7 @@ public final class GeoPointInPolygonQuery extends > GeoPointInBBoxQuery { > > /** > * Constructs a new GeoPolygonQuery that will match encoded {@link > org.apache.lucene.spatial.geopoint.document.GeoPointField} terms > - * that fall within or on the boundary of the polygon defined by the input > parameters. > + * that fall within or on the boundary of the polygons defined by the > input parameters. > */ > public GeoPointInPolygonQuery(String field, TermEncoding termEncoding, > Polygon... polygons) { > this(field, termEncoding, Rectangle.fromPolygon(polygons), polygons); > --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
