org.apache.lucene.spatial3d.geom.GeoPoint Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of lucene-spatial3d Show documentation
Show all versions of lucene-spatial3d Show documentation
Apache Lucene (module: spatial3d)
/*
* 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;
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
/**
* This class represents a point on the surface of a sphere or ellipsoid.
*
* @lucene.experimental
*/
public class GeoPoint extends Vector implements SerializableObject {
// By making lazily-evaluated variables be "volatile", we guarantee atomicity when they
// are updated. This is necessary if we are using these classes in a multi-thread fashion,
// because we don't try to synchronize for the lazy computation.
/**
* This is the lazily-evaluated magnitude. Some constructors include it, but others don't, and we
* try not to create extra computation by always computing it. Does not need to be synchronized
* for thread safety, because depends wholly on immutable variables of this class.
*/
protected volatile double magnitude = Double.NEGATIVE_INFINITY;
/**
* Lazily-evaluated latitude. Does not need to be synchronized for thread safety, because depends
* wholly on immutable variables of this class.
*/
protected volatile double latitude = Double.NEGATIVE_INFINITY;
/**
* Lazily-evaluated longitude. Does not need to be synchronized for thread safety, because depends
* wholly on immutable variables of this class.
*/
protected volatile double longitude = Double.NEGATIVE_INFINITY;
/**
* Construct a GeoPoint from the trig functions of a lat and lon pair.
*
* @param planetModel is the planetModel to put the point on.
* @param sinLat is the sin of the latitude.
* @param sinLon is the sin of the longitude.
* @param cosLat is the cos of the latitude.
* @param cosLon is the cos of the longitude.
* @param lat is the latitude.
* @param lon is the longitude.
*/
public GeoPoint(
final PlanetModel planetModel,
final double sinLat,
final double sinLon,
final double cosLat,
final double cosLon,
final double lat,
final double lon) {
this(
computeDesiredEllipsoidMagnitude(planetModel, cosLat * cosLon, cosLat * sinLon, sinLat),
cosLat * cosLon,
cosLat * sinLon,
sinLat,
lat,
lon);
}
/**
* Construct a GeoPoint from the trig functions of a lat and lon pair.
*
* @param planetModel is the planetModel to put the point on.
* @param sinLat is the sin of the latitude.
* @param sinLon is the sin of the longitude.
* @param cosLat is the cos of the latitude.
* @param cosLon is the cos of the longitude.
*/
public GeoPoint(
final PlanetModel planetModel,
final double sinLat,
final double sinLon,
final double cosLat,
final double cosLon) {
this(
computeDesiredEllipsoidMagnitude(planetModel, cosLat * cosLon, cosLat * sinLon, sinLat),
cosLat * cosLon,
cosLat * sinLon,
sinLat);
}
/**
* Construct a GeoPoint from a latitude/longitude pair.
*
* @param planetModel is the planetModel to put the point on.
* @param lat is the latitude.
* @param lon is the longitude.
*/
public GeoPoint(final PlanetModel planetModel, final double lat, final double lon) {
this(planetModel, Math.sin(lat), Math.sin(lon), Math.cos(lat), Math.cos(lon), lat, lon);
}
/**
* Construct a GeoPoint from an input stream.
*
* @param planetModel is the planet model
* @param inputStream is the input stream
*/
public GeoPoint(final PlanetModel planetModel, final InputStream inputStream) throws IOException {
this(inputStream);
}
/**
* Construct a GeoPoint from an input stream with no planet model.
*
* @param inputStream is the input stream
*/
public GeoPoint(final InputStream inputStream) throws IOException {
// Note: this relies on left-right parameter execution order!! Much code depends on that though
// and it is apparently in a java spec:
// https://stackoverflow.com/questions/2201688/order-of-execution-of-parameters-guarantees-in-java
this(
SerializableObject.readDouble(inputStream),
SerializableObject.readDouble(inputStream),
SerializableObject.readDouble(inputStream),
SerializableObject.readDouble(inputStream),
SerializableObject.readDouble(inputStream));
}
/**
* Construct a GeoPoint from five unchecked parameters: lat, lon, x, y, z. This is primarily used
* for deserialization, but can also be used to fully initialize a point externally.
*
* @param lat is the latitude in radians
* @param lon is the longitude in radians
* @param x is the unit x value
* @param y is the unit y value
* @param z is the unit z value
*/
public GeoPoint(
final double lat, final double lon, final double x, final double y, final double z) {
super(x, y, z);
this.latitude = lat;
this.longitude = lon;
}
/**
* Construct a GeoPoint from a unit (x,y,z) vector and a magnitude.
*
* @param magnitude is the desired magnitude, provided to put the point on the ellipsoid.
* @param x is the unit x value.
* @param y is the unit y value.
* @param z is the unit z value.
* @param lat is the latitude.
* @param lon is the longitude.
*/
public GeoPoint(
final double magnitude,
final double x,
final double y,
final double z,
double lat,
double lon) {
super(x * magnitude, y * magnitude, z * magnitude);
this.magnitude = magnitude;
if (lat > Math.PI * 0.5 || lat < -Math.PI * 0.5) {
throw new IllegalArgumentException(
"Latitude " + lat + " is out of range: must range from -Math.PI/2 to Math.PI/2");
}
if (lon < -Math.PI || lon > Math.PI) {
throw new IllegalArgumentException(
"Longitude " + lon + " is out of range: must range from -Math.PI to Math.PI");
}
this.latitude = lat;
this.longitude = lon;
}
/**
* Construct a GeoPoint from a unit (x,y,z) vector and a magnitude.
*
* @param magnitude is the desired magnitude, provided to put the point on the ellipsoid.
* @param x is the unit x value.
* @param y is the unit y value.
* @param z is the unit z value.
*/
public GeoPoint(final double magnitude, final double x, final double y, final double z) {
super(x * magnitude, y * magnitude, z * magnitude);
this.magnitude = magnitude;
}
/**
* Construct a GeoPoint from an (x,y,z) value. The (x,y,z) tuple must be on the desired ellipsoid.
*
* @param x is the ellipsoid point x value.
* @param y is the ellipsoid point y value.
* @param z is the ellipsoid point z value.
*/
public GeoPoint(final double x, final double y, final double z) {
super(x, y, z);
}
@Override
public void write(final OutputStream outputStream) throws IOException {
SerializableObject.writeDouble(outputStream, getLatitude());
SerializableObject.writeDouble(outputStream, getLongitude());
SerializableObject.writeDouble(outputStream, x);
SerializableObject.writeDouble(outputStream, y);
SerializableObject.writeDouble(outputStream, z);
}
/**
* Compute an arc distance between two points. Note: this is an angular distance, and not a
* surface distance, and is therefore independent of planet model. For surface distance, see
* {@link PlanetModel#surfaceDistance(GeoPoint, GeoPoint)}
*
* @param v is the second point.
* @return the angle, in radians, between the two points.
*/
public double arcDistance(final Vector v) {
return Tools.safeAcos(dotProduct(v) / (magnitude() * v.magnitude()));
}
/**
* Compute an arc distance between two points.
*
* @param x is the x part of the second point.
* @param y is the y part of the second point.
* @param z is the z part of the second point.
* @return the angle, in radians, between the two points.
*/
public double arcDistance(final double x, final double y, final double z) {
return Tools.safeAcos(dotProduct(x, y, z) / (magnitude() * Vector.magnitude(x, y, z)));
}
/**
* Compute the latitude for the point.
*
* @return the latitude.
*/
public double getLatitude() {
double lat = this.latitude; // volatile-read once
if (lat == Double.NEGATIVE_INFINITY) {
this.latitude = lat = Math.asin(z / magnitude());
}
return lat;
}
/**
* Compute the longitude for the point.
*
* @return the longitude value. Uses 0.0 if there is no computable longitude.
*/
public double getLongitude() {
double lon = this.longitude; // volatile-read once
if (lon == Double.NEGATIVE_INFINITY) {
if (Math.abs(x) < MINIMUM_RESOLUTION && Math.abs(y) < MINIMUM_RESOLUTION) {
this.longitude = lon = 0.0;
} else {
this.longitude = lon = Math.atan2(y, x);
}
}
return lon;
}
/**
* Compute the linear magnitude of the point.
*
* @return the magnitude.
*/
@Override
public double magnitude() {
double mag = this.magnitude; // volatile-read once
if (mag == Double.NEGATIVE_INFINITY) {
this.magnitude = mag = super.magnitude();
}
return mag;
}
/**
* Compute whether point matches another.
*
* @param p is the other point.
* @return true if the same.
*/
public boolean isIdentical(final GeoPoint p) {
return isIdentical(p.x, p.y, p.z);
}
/**
* Compute whether point matches another.
*
* @param x is the x value
* @param y is the y value
* @param z is the z value
* @return true if the same.
*/
public boolean isIdentical(final double x, final double y, final double z) {
return Math.abs(this.x - x) < MINIMUM_RESOLUTION
&& Math.abs(this.y - y) < MINIMUM_RESOLUTION
&& Math.abs(this.z - z) < MINIMUM_RESOLUTION;
}
@Override
public String toString() {
if (this.longitude == Double.NEGATIVE_INFINITY) {
return super.toString();
}
return "[lat=" + getLatitude() + ", lon=" + getLongitude() + "(" + super.toString() + ")]";
}
}