/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.lucene.spatial3d.geom;

An object for accumulating latitude/longitude bounds information.
@lucene.experimental
/** * An object for accumulating latitude/longitude bounds information. * * @lucene.experimental */
public class LatLonBounds implements Bounds {
Set to true if no longitude bounds can be stated
/** Set to true if no longitude bounds can be stated */
private boolean noLongitudeBound = false;
Set to true if no top latitude bound can be stated
/** Set to true if no top latitude bound can be stated */
private boolean noTopLatitudeBound = false;
Set to true if no bottom latitude bound can be stated
/** Set to true if no bottom latitude bound can be stated */
private boolean noBottomLatitudeBound = false;
If non-null, the minimum latitude bound
/** If non-null, the minimum latitude bound */
private Double minLatitude = null;
If non-null, the maximum latitude bound
/** If non-null, the maximum latitude bound */
private Double maxLatitude = null; // For longitude bounds, this class needs to worry about keeping track of the distinction // between left-side bounds and right-side bounds. Points are always submitted in pairs // which have a maximum longitude separation of Math.PI. It's therefore always possible // to determine which point represents a left bound, and which point represents a right // bound. // // The next problem is how to compare two of the same kind of bound, e.g. two left bounds. // We need to keep track of the leftmost longitude of the shape, but since this is a circle, // this is arbitrary. What we could try to do instead would be to find a pair of (left,right) bounds such // that: // (1) all other bounds are within, and // (2) the left minus right distance is minimized // Unfortunately, there are still shapes that cannot be summarized in this way correctly. // For example. consider a spiral that entirely circles the globe; we might arbitrarily choose // lat/lon bounds that do not in fact circle the globe. // // One way to handle the longitude issue correctly is therefore to stipulate that we // walk the bounds of the shape in some kind of connected order. Each point or circle is therefore // added in a sequence. We also need an interior point to make sure we have the right // choice of longitude bounds. But even with this, we still can't always choose whether the actual shape // goes right or left. // // We can make the specification truly general by submitting the following in order: // addSide(PlaneSide side, Membership... constraints) // ... // This is unambiguous, but I still can't see yet how this would help compute the bounds. The plane // solution would in general seem to boil down to the same logic that relies on points along the path // to define the shape boundaries. I guess the one thing that you do know for a bounded edge is that // the endpoints are actually connected. But it is not clear whether relationship helps in any way. // // In any case, if we specify shapes by a sequence of planes, we should stipulate that multiple sequences // are allowed, provided they progressively tile an area of the sphere that is connected and sequential. // For example, paths do alternating rectangles and circles, in sequence. Each sequence member is // described by a sequence of planes. I think it would also be reasonable to insist that the first segment // of a shape overlap or adjoin the previous shape. // // Here's a way to think about it that might help: Traversing every edge should grow the longitude bounds // in the direction of the traversal. So if the traversal is always known to be less than PI in total longitude // angle, then it is possible to use the endpoints to determine the unambiguous extension of the envelope. // For example, say you are currently at longitude -0.5. The next point is at longitude PI-0.1. You could say // that the difference in longitude going one way around would be beter than the distance the other way // around, and therefore the longitude envelope should be extended accordingly. But in practice, when an // edge goes near a pole and may be inclined as well, the longer longitude change might be the right path, even // if the arc length is short. So this too doesn't work. // // Given we have a hard time making an exact match, here's the current proposal. The proposal is a // heuristic, based on the idea that most areas are small compared to the circumference of the globe. // We keep track of the last point we saw, and take each point as it arrives, and compute its longitude. // Then, we have a choice as to which way to expand the envelope: we can expand by going to the left or // to the right. We choose the direction with the least longitude difference. (If we aren't sure, // and can recognize that, we can set "unconstrained in longitude".)
If non-null, the left longitude bound
/** If non-null, the left longitude bound */
private Double leftLongitude = null;
If non-null, the right longitude bound
/** If non-null, the right longitude bound */
private Double rightLongitude = null;
Construct an empty bounds object
/** Construct an empty bounds object */
public LatLonBounds() { } // Accessor methods
Get maximum latitude, if any.
Returns:maximum latitude or null.
/** Get maximum latitude, if any. *@return maximum latitude or null. */
public Double getMaxLatitude() { return maxLatitude; }
Get minimum latitude, if any.
Returns:minimum latitude or null.
/** Get minimum latitude, if any. *@return minimum latitude or null. */
public Double getMinLatitude() { return minLatitude; }
Get left longitude, if any.
Returns:left longitude, or null.
/** Get left longitude, if any. *@return left longitude, or null. */
public Double getLeftLongitude() { return leftLongitude; }
Get right longitude, if any.
Returns:right longitude, or null.
/** Get right longitude, if any. *@return right longitude, or null. */
public Double getRightLongitude() { return rightLongitude; } // Degenerate case check
Check if there's no longitude bound.
Returns:true if no longitude bound.
/** Check if there's no longitude bound. *@return true if no longitude bound. */
public boolean checkNoLongitudeBound() { return noLongitudeBound; }
Check if there's no top latitude bound.
Returns:true if no top latitude bound.
/** Check if there's no top latitude bound. *@return true if no top latitude bound. */
public boolean checkNoTopLatitudeBound() { return noTopLatitudeBound; }
Check if there's no bottom latitude bound.
Returns:true if no bottom latitude bound.
/** Check if there's no bottom latitude bound. *@return true if no bottom latitude bound. */
public boolean checkNoBottomLatitudeBound() { return noBottomLatitudeBound; } // Modification methods @Override public Bounds addPlane(final PlanetModel planetModel, final Plane plane, final Membership... bounds) { plane.recordBounds(planetModel, this, bounds); return this; } @Override public Bounds addHorizontalPlane(final PlanetModel planetModel, final double latitude, final Plane horizontalPlane, final Membership... bounds) { if (!noTopLatitudeBound || !noBottomLatitudeBound) { addLatitudeBound(latitude); } return this; } @Override public Bounds addVerticalPlane(final PlanetModel planetModel, final double longitude, final Plane verticalPlane, final Membership... bounds) { if (!noLongitudeBound) { addLongitudeBound(longitude); } return this; } @Override public Bounds isWide() { return noLongitudeBound(); } @Override public Bounds addXValue(final GeoPoint point) { if (!noLongitudeBound) { // Get a longitude value addLongitudeBound(point.getLongitude()); } return this; } @Override public Bounds addYValue(final GeoPoint point) { if (!noLongitudeBound) { // Get a longitude value addLongitudeBound(point.getLongitude()); } return this; } @Override public Bounds addZValue(final GeoPoint point) { if (!noTopLatitudeBound || !noBottomLatitudeBound) { // Compute a latitude value double latitude = point.getLatitude(); addLatitudeBound(latitude); } return this; } @Override public Bounds addIntersection(final PlanetModel planetModel, final Plane plane1, final Plane plane2, final Membership... bounds) { plane1.recordBounds(planetModel, this, plane2, bounds); return this; } @Override public Bounds addPoint(GeoPoint point) { if (!noLongitudeBound) { // Get a longitude value addLongitudeBound(point.getLongitude()); } if (!noTopLatitudeBound || !noBottomLatitudeBound) { // Compute a latitude value addLatitudeBound(point.getLatitude()); } return this; } @Override public Bounds noLongitudeBound() { noLongitudeBound = true; leftLongitude = null; rightLongitude = null; return this; } @Override public Bounds noTopLatitudeBound() { noTopLatitudeBound = true; maxLatitude = null; return this; } @Override public Bounds noBottomLatitudeBound() { noBottomLatitudeBound = true; minLatitude = null; return this; } @Override public Bounds noBound(final PlanetModel planetModel) { return noLongitudeBound().noTopLatitudeBound().noBottomLatitudeBound(); } // Protected methods
Update latitude bound.
Params:
  • latitude – is the latitude.
/** Update latitude bound. *@param latitude is the latitude. */
private void addLatitudeBound(double latitude) { if (!noTopLatitudeBound && (maxLatitude == null || latitude > maxLatitude)) maxLatitude = latitude; if (!noBottomLatitudeBound && (minLatitude == null || latitude < minLatitude)) minLatitude = latitude; }
Update longitude bound.
Params:
  • longitude – is the new longitude value.
/** Update longitude bound. *@param longitude is the new longitude value. */
private void addLongitudeBound(double longitude) { // If this point is within the current bounds, we're done; otherwise // expand one side or the other. if (leftLongitude == null && rightLongitude == null) { leftLongitude = longitude; rightLongitude = longitude; } else { // Compute whether we're to the right of the left value. But the left value may be greater than // the right value. double currentLeftLongitude = leftLongitude; double currentRightLongitude = rightLongitude; if (currentRightLongitude < currentLeftLongitude) currentRightLongitude += 2.0 * Math.PI; // We have a range to look at that's going in the right way. // Now, do the same trick with the computed longitude. if (longitude < currentLeftLongitude) longitude += 2.0 * Math.PI; if (longitude < currentLeftLongitude || longitude > currentRightLongitude) { // Outside of current bounds. Consider carefully how we'll expand. double leftExtensionAmt; double rightExtensionAmt; if (longitude < currentLeftLongitude) { leftExtensionAmt = currentLeftLongitude - longitude; } else { leftExtensionAmt = currentLeftLongitude + 2.0 * Math.PI - longitude; } if (longitude > currentRightLongitude) { rightExtensionAmt = longitude - currentRightLongitude; } else { rightExtensionAmt = longitude + 2.0 * Math.PI - currentRightLongitude; } if (leftExtensionAmt < rightExtensionAmt) { currentLeftLongitude = leftLongitude - leftExtensionAmt; while (currentLeftLongitude <= -Math.PI) { currentLeftLongitude += 2.0 * Math.PI; } leftLongitude = currentLeftLongitude; } else { currentRightLongitude = rightLongitude + rightExtensionAmt; while (currentRightLongitude > Math.PI) { currentRightLongitude -= 2.0 * Math.PI; } rightLongitude = currentRightLongitude; } } } double testRightLongitude = rightLongitude; if (testRightLongitude < leftLongitude) testRightLongitude += Math.PI * 2.0; if (testRightLongitude - leftLongitude >= Math.PI) { noLongitudeBound = true; leftLongitude = null; rightLongitude = null; } } }