stevenzwu commented on code in PR #12667: URL: https://github.com/apache/iceberg/pull/12667#discussion_r2453865714
########## api/src/main/java/org/apache/iceberg/geospatial/GeospatialBound.java: ########## @@ -0,0 +1,313 @@ +/* + * 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.iceberg.geospatial; + +import java.nio.ByteBuffer; +import java.nio.ByteOrder; +import java.util.Objects; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; + +/** + * Represents a geospatial bound (minimum or maximum) for Iceberg tables. + * + * <p>According to the <a href="https://iceberg.apache.org/spec/#bound-serialization";>Bound + * serialization section of Iceberg Table spec</a>, geospatial bounds are serialized differently + * from the regular WKB representation. Geometry and geography bounds are single point encoded as a + * concatenation of 8-byte little-endian IEEE 754 coordinate values in the order X, Y, Z (optional), + * M (optional). + * + * <p>The encoding varies based on which coordinates are present: + * + * <ul> + * <li>x:y (2 doubles) when both z and m are unset + * <li>x:y:z (3 doubles) when only m is unset + * <li>x:y:NaN:m (4 doubles) when only z is unset + * <li>x:y:z:m (4 doubles) when all coordinates are set + * </ul> + * + * <p>This class represents a lower or upper geospatial bound and handles serialization and + * deserialization of these bounds to/from byte arrays, conforming to the Iceberg specification. + */ +public class GeospatialBound { + /** + * Parses a geospatial bound from a byte buffer according to Iceberg spec. + * + * <p>Based on the buffer size, this method determines which coordinates are present: - 16 bytes + * (2 doubles): x and y only - 24 bytes (3 doubles): x, y, and z - 32 bytes (4 doubles): x, y, z + * (might be NaN), and m + * + * <p>The ordinates are encoded as 8-byte little-endian IEEE 754 values. + * + * @param buffer the ByteBuffer containing the serialized geospatial bound + * @return a GeospatialBound object representing the parsed bound + * @throws IllegalArgumentException if the buffer has an invalid size + */ + public static GeospatialBound fromByteBuffer(ByteBuffer buffer) { + Preconditions.checkArgument( + buffer.order() == ByteOrder.LITTLE_ENDIAN, "Unsupported byte order: big endian"); + int size = buffer.remaining(); + Preconditions.checkArgument( + size == 2 * Double.BYTES || size == 3 * Double.BYTES || size == 4 * Double.BYTES, + "Invalid geo spatial bound buffer size: %s. Valid sizes are 16, 24, or 32 bytes.", + size); + + if (size == 2 * Double.BYTES) { + // x:y format (2 doubles) + double coordX = buffer.getDouble(); + double coordY = buffer.getDouble(); + return createXY(coordX, coordY); + } else if (size == 3 * Double.BYTES) { + // x:y:z format (3 doubles) + double coordX = buffer.getDouble(); + double coordY = buffer.getDouble(); + double coordZ = buffer.getDouble(); + return createXYZ(coordX, coordY, coordZ); + } else { + // x:y:z:m format (4 doubles) - z might be NaN + double coordX = buffer.getDouble(); + double coordY = buffer.getDouble(); + double coordZ = buffer.getDouble(); + double coordM = buffer.getDouble(); + return new GeospatialBound(coordX, coordY, coordZ, coordM); + } + } + + /** + * Serializes this geospatial bound to a byte buffer according to Iceberg spec. + * + * <p>Following the Iceberg spec, the bound is serialized based on which coordinates are set: - + * x:y (2 doubles) when both z and m are unset - x:y:z (3 doubles) when only m is unset - + * x:y:NaN:m (4 doubles) when only z is unset - x:y:z:m (4 doubles) when all coordinates are set + * + * @return A ByteBuffer containing the serialized geospatial bound + */ + public ByteBuffer toByteBuffer() { + // Calculate size based on which coordinates are present + int size; + if (!hasZ() && !hasM()) { + // Just x and y + size = 2 * Double.BYTES; + } else if (hasZ() && !hasM()) { + // x, y, and z (no m) + size = 3 * Double.BYTES; + } else { + // x, y, z (or NaN), and m + size = 4 * Double.BYTES; + } + + ByteBuffer buffer = ByteBuffer.allocate(size).order(ByteOrder.LITTLE_ENDIAN); + buffer.putDouble(x); + buffer.putDouble(y); + + if (hasZ() || hasM()) { + // If we have z or m or both, we need to include z (could be NaN) + buffer.putDouble(z); + } + + if (hasM()) { + // If we have m, include it + buffer.putDouble(m); + } + + buffer.flip(); + return buffer; + } + + /** + * Parses a geospatial bound from a byte array according to Iceberg spec. + * + * @param bytes the byte array containing the serialized geospatial bound + * @return a GeospatialBound object representing the parsed bound + * @throws IllegalArgumentException if the byte array has an invalid length + */ + public static GeospatialBound fromByteArray(byte[] bytes) { + return fromByteBuffer(ByteBuffer.wrap(bytes).order(ByteOrder.LITTLE_ENDIAN)); + } + + /** + * Creates a GeospatialBound with X and Y coordinates only. + * + * @param x the X coordinate (longitude/easting) + * @param y the Y coordinate (latitude/northing) + * @return a GeospatialBound with XY coordinates + */ + @SuppressWarnings("ParameterName") + public static GeospatialBound createXY(double x, double y) { + return new GeospatialBound(x, y, Double.NaN, Double.NaN); + } + + /** + * Creates a GeospatialBound with X, Y, and Z coordinates, with no M value. + * + * @param x the X coordinate (longitude/easting) + * @param y the Y coordinate (latitude/northing) + * @param z the Z coordinate (elevation) + * @return a GeospatialBound with XYZ coordinates + */ + @SuppressWarnings("ParameterName") + public static GeospatialBound createXYZ(double x, double y, double z) { + return new GeospatialBound(x, y, z, Double.NaN); + } + + /** + * Creates a GeospatialBound with X, Y, Z, and M coordinates. + * + * @param x the X coordinate (longitude/easting) + * @param y the Y coordinate (latitude/northing) + * @param z the Z coordinate (elevation) + * @param m the M value (measure) + * @return a GeospatialBound with XYZM coordinates + */ + @SuppressWarnings("ParameterName") + public static GeospatialBound createXYZM(double x, double y, double z, double m) { + return new GeospatialBound(x, y, z, m); + } + + /** + * Creates a GeospatialBound with X, Y, and M values, with no Z coordinate. + * + * @param x the X coordinate (longitude/easting) + * @param y the Y coordinate (latitude/northing) + * @param m the M value (measure) + * @return a GeospatialBound with XYM coordinates + */ + @SuppressWarnings("ParameterName") + public static GeospatialBound createXYM(double x, double y, double m) { + return new GeospatialBound(x, y, Double.NaN, m); + } + + @SuppressWarnings("MemberName") + private final double x; + + @SuppressWarnings("MemberName") + private final double y; + + @SuppressWarnings("MemberName") + private final double z; + + @SuppressWarnings("MemberName") + private final double m; + + /** Private constructor - use factory methods instead. */ + @SuppressWarnings("ParameterName") + private GeospatialBound(double x, double y, double z, double m) { + this.x = x; + this.y = y; + this.z = z; + this.m = m; + } + + /** + * Get the X coordinate (longitude/easting). + * + * @return X coordinate value + */ + @SuppressWarnings("MethodName") + public double x() { + return x; + } + + /** + * Get the Y coordinate (latitude/northing). + * + * @return Y coordinate value + */ + @SuppressWarnings("MethodName") + public double y() { + return y; + } + + /** + * Get the Z coordinate (typically elevation). + * + * @return Z coordinate value or NaN if not set + */ + @SuppressWarnings("MethodName") + public double z() { + return z; + } + + /** + * Get the M value (measure). + * + * @return M value or NaN if not set + */ + @SuppressWarnings("MethodName") + public double m() { + return m; + } + + /** + * Check if this bound has a defined Z coordinate. + * + * @return true if Z is not NaN + */ + public boolean hasZ() { + return !Double.isNaN(z); + } + + /** + * Check if this bound has a defined M value. + * + * @return true if M is not NaN + */ + public boolean hasM() { + return !Double.isNaN(m); + } + + @Override + public String toString() { + return "GeospatialBound(" + simpleString() + ")"; Review Comment: nit: we are not using `MoreObjects.toStringHelper` here. is it important to expose the `simpleString` separately? ########## api/src/test/java/org/apache/iceberg/geospatial/TestGeospatialBound.java: ########## @@ -0,0 +1,228 @@ +/* + * 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.iceberg.geospatial; + +import static org.assertj.core.api.Assertions.assertThat; + +import java.nio.ByteBuffer; +import org.apache.iceberg.util.ByteBuffers; +import org.junit.jupiter.api.Test; + +public class TestGeospatialBound { + + @Test + public void testCreateXY() { + GeospatialBound bound = GeospatialBound.createXY(1.0, 2.0); + assertThat(bound.x()).isEqualTo(1.0); + assertThat(bound.y()).isEqualTo(2.0); + assertThat(bound.hasZ()).isFalse(); + assertThat(bound.hasM()).isFalse(); + assertThat(Double.isNaN(bound.z())).isTrue(); + assertThat(Double.isNaN(bound.m())).isTrue(); + } + + @Test + public void testCreateXYZ() { + GeospatialBound bound = GeospatialBound.createXYZ(1.0, 2.0, 3.0); + assertThat(bound.x()).isEqualTo(1.0); + assertThat(bound.y()).isEqualTo(2.0); + assertThat(bound.z()).isEqualTo(3.0); + assertThat(bound.hasZ()).isTrue(); + assertThat(bound.hasM()).isFalse(); + assertThat(Double.isNaN(bound.m())).isTrue(); + } + + @Test + public void testCreateXYM() { + GeospatialBound bound = GeospatialBound.createXYM(1.0, 2.0, 4.0); + assertThat(bound.x()).isEqualTo(1.0); + assertThat(bound.y()).isEqualTo(2.0); + assertThat(bound.m()).isEqualTo(4.0); + assertThat(bound.hasZ()).isFalse(); + assertThat(bound.hasM()).isTrue(); + assertThat(Double.isNaN(bound.z())).isTrue(); + } + + @Test + public void testCreateXYZM() { + GeospatialBound bound = GeospatialBound.createXYZM(1.0, 2.0, 3.0, 4.0); + assertThat(bound.x()).isEqualTo(1.0); + assertThat(bound.y()).isEqualTo(2.0); + assertThat(bound.z()).isEqualTo(3.0); + assertThat(bound.m()).isEqualTo(4.0); + assertThat(bound.hasZ()).isTrue(); + assertThat(bound.hasM()).isTrue(); + } + + @Test + public void testEqualsAndHashCode() { + GeospatialBound xy1 = GeospatialBound.createXY(1.0, 2.0); + GeospatialBound xy2 = GeospatialBound.createXY(1.0, 2.0); + GeospatialBound xy3 = GeospatialBound.createXY(2.0, 1.0); + assertThat(xy1).isEqualTo(xy2); + assertThat(xy1.hashCode()).isEqualTo(xy2.hashCode()); + assertThat(xy1).isNotEqualTo(xy3); + + GeospatialBound xyz1 = GeospatialBound.createXYZ(1.0, 2.0, 3.0); + GeospatialBound xyz2 = GeospatialBound.createXYZ(1.0, 2.0, 3.0); + GeospatialBound xyz3 = GeospatialBound.createXYZ(1.0, 2.0, 4.0); + assertThat(xyz1).isEqualTo(xyz2); + assertThat(xyz1.hashCode()).isEqualTo(xyz2.hashCode()); + assertThat(xyz1).isNotEqualTo(xyz3); + assertThat(xyz1).isNotEqualTo(xy1); + + GeospatialBound xym1 = GeospatialBound.createXYM(1.0, 2.0, 4.0); + GeospatialBound xym2 = GeospatialBound.createXYM(1.0, 2.0, 4.0); + GeospatialBound xym3 = GeospatialBound.createXYM(1.0, 2.0, 5.0); + assertThat(xym1).isEqualTo(xym2); + assertThat(xym1.hashCode()).isEqualTo(xym2.hashCode()); + assertThat(xym1).isNotEqualTo(xym3); + assertThat(xym1).isNotEqualTo(xy1); + + GeospatialBound xyzm1 = GeospatialBound.createXYZM(1.0, 2.0, 3.0, 4.0); + GeospatialBound xyzm2 = GeospatialBound.createXYZM(1.0, 2.0, 3.0, 4.0); + GeospatialBound xyzm3 = GeospatialBound.createXYZM(1.0, 2.0, 3.0, 5.0); + assertThat(xyzm1).isEqualTo(xyzm2); + assertThat(xyzm1.hashCode()).isEqualTo(xyzm2.hashCode()); + assertThat(xyzm1).isNotEqualTo(xyzm3); + assertThat(xyzm1).isNotEqualTo(xyz1); + } + + @Test + public void testToString() { + GeospatialBound xy = GeospatialBound.createXY(1.0, 2.0); + assertThat(xy.toString()).isEqualTo("GeospatialBound(x=1.0, y=2.0)"); + + GeospatialBound xyz = GeospatialBound.createXYZ(1.0, 2.0, 3.0); + assertThat(xyz.toString()).isEqualTo("GeospatialBound(x=1.0, y=2.0, z=3.0)"); + + GeospatialBound xym = GeospatialBound.createXYM(1.0, 2.0, 4.0); + assertThat(xym.toString()).isEqualTo("GeospatialBound(x=1.0, y=2.0, m=4.0)"); + + GeospatialBound xyzm = GeospatialBound.createXYZM(1.0, 2.0, 3.0, 4.0); + assertThat(xyzm.toString()).isEqualTo("GeospatialBound(x=1.0, y=2.0, z=3.0, m=4.0)"); + } + + @Test + public void testSimpleString() { + GeospatialBound xy = GeospatialBound.createXY(1.0, 2.0); + assertThat(xy.simpleString()).isEqualTo("x=1.0, y=2.0"); + + GeospatialBound xyz = GeospatialBound.createXYZ(1.0, 2.0, 3.0); + assertThat(xyz.simpleString()).isEqualTo("x=1.0, y=2.0, z=3.0"); + + GeospatialBound xym = GeospatialBound.createXYM(1.0, 2.0, 4.0); + assertThat(xym.simpleString()).isEqualTo("x=1.0, y=2.0, m=4.0"); + + GeospatialBound xyzm = GeospatialBound.createXYZM(1.0, 2.0, 3.0, 4.0); + assertThat(xyzm.simpleString()).isEqualTo("x=1.0, y=2.0, z=3.0, m=4.0"); + } + + @Test + public void testSerde() { + // Test XY format (16 bytes: x:y) + // These bytes represent x=10.0, y=13.0 + byte[] xyBytes = + new byte[] { + 0, 0, 0, 0, 0, 0, 36, 64, // 10.0 in little-endian IEEE 754 + 0, 0, 0, 0, 0, 0, 42, 64 // 13.0 in little-endian IEEE 754 + }; + GeospatialBound xy = GeospatialBound.fromByteArray(xyBytes); + assertThat(xy.x()).isEqualTo(10.0); + assertThat(xy.y()).isEqualTo(13.0); + assertThat(xy.hasZ()).isFalse(); + assertThat(xy.hasM()).isFalse(); + assertThat(ByteBuffers.toByteArray(xy.toByteBuffer())).isEqualTo(xyBytes); + + // Test XYZ format (24 bytes: x:y:z) + // These bytes represent x=10.0, y=13.0, z=15.0 + byte[] xyzBytes = + new byte[] { + 0, 0, 0, 0, 0, 0, 36, 64, // 10.0 in little-endian IEEE 754 + 0, 0, 0, 0, 0, 0, 42, 64, // 13.0 in little-endian IEEE 754 + 0, 0, 0, 0, 0, 0, 46, 64 // 15.0 in little-endian IEEE 754 + }; + GeospatialBound xyz = GeospatialBound.fromByteArray(xyzBytes); + assertThat(xyz.x()).isEqualTo(10.0); + assertThat(xyz.y()).isEqualTo(13.0); + assertThat(xyz.z()).isEqualTo(15.0); + assertThat(xyz.hasZ()).isTrue(); + assertThat(xyz.hasM()).isFalse(); + assertThat(ByteBuffers.toByteArray(xyz.toByteBuffer())).isEqualTo(xyzBytes); + // Test XYM format (32 bytes: x:y:NaN:m) Review Comment: nit: add an empty line before this ########## api/src/test/java/org/apache/iceberg/geospatial/TestGeospatialPredicateEvaluators.java: ########## @@ -0,0 +1,489 @@ +/* + * 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.iceberg.geospatial; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +import org.apache.iceberg.types.EdgeAlgorithm; +import org.apache.iceberg.types.Type; +import org.apache.iceberg.types.Types; +import org.junit.jupiter.api.Test; + +public class TestGeospatialPredicateEvaluators { + + @Test + public void testGeometryType() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + assertThat(evaluator).isInstanceOf(GeospatialPredicateEvaluators.GeometryEvaluator.class); + } + + @Test + public void testSphericalGeographyType() { + Type geographyType = Types.GeographyType.of("srid:4326", EdgeAlgorithm.SPHERICAL); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geographyType); + + assertThat(evaluator).isInstanceOf(GeospatialPredicateEvaluators.GeographyEvaluator.class); + } + + @Test + public void testUnsupportedType() { + Type stringType = Types.StringType.get(); + + assertThatThrownBy(() -> GeospatialPredicateEvaluators.create(stringType)) + .isInstanceOf(UnsupportedOperationException.class) + .hasMessageContaining("Unsupported type for BoundingBox"); + } + + @Test + public void testOverlappingGeometryBoxesIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(5.0, 5.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(3.0, 3.0); + GeospatialBound max2 = GeospatialBound.createXY(8.0, 8.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testNonOverlappingGeometryBoxesDontIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(3.0, 3.0); + GeospatialBound max2 = GeospatialBound.createXY(5.0, 5.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + } + + @Test + public void testGeometryBoxesTouchingAtCornerIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(2.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXY(4.0, 4.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testGeometryBoxesTouchingAtEdgeIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(2.0, 0.0); + GeospatialBound max2 = GeospatialBound.createXY(4.0, 2.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testGeometryBoxContainedWithinAnotherIntersects() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(10.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(2.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXY(5.0, 5.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testGeometryBoxesWithZCoordinate() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + // Two boxes with Z coordinates that overlap in X and Y but not in Z + GeospatialBound min1 = GeospatialBound.createXYZ(0.0, 0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXYZ(2.0, 2.0, 1.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXYZ(1.0, 1.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXYZ(3.0, 3.0, 3.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + GeospatialBound min3 = GeospatialBound.createXYZ(1.0, 1.0, 1.0); + GeospatialBound max3 = GeospatialBound.createXYZ(3.0, 3.0, 3.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + assertThat(evaluator.intersects(box1, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box1)).isTrue(); + assertThat(evaluator.intersects(box2, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box2)).isTrue(); + } + + @Test + public void testGeometryBoxesWithMCoordinate() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + // Two boxes with M coordinates that overlap in X and Y but not in M + GeospatialBound min1 = GeospatialBound.createXYM(0.0, 0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXYM(2.0, 2.0, 1.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXYM(1.0, 1.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXYM(3.0, 3.0, 3.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + GeospatialBound min3 = GeospatialBound.createXYM(1.0, 1.0, 1.0); + GeospatialBound max3 = GeospatialBound.createXYM(3.0, 3.0, 3.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + assertThat(evaluator.intersects(box1, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box1)).isTrue(); + assertThat(evaluator.intersects(box2, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box2)).isTrue(); + } + + @Test + public void testGeometryBoxesWithEmptyXRange() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(170.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(-170.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + GeospatialBound min2 = GeospatialBound.createXY(-175.0, 5.0); + GeospatialBound max2 = GeospatialBound.createXY(-160.0, 15.0); + BoundingBox box2 = new BoundingBox(min2, max2); + GeospatialBound min3 = GeospatialBound.createXY(160.0, 0.0); + GeospatialBound max3 = GeospatialBound.createXY(-160.0, 10.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + assertThat(evaluator.intersects(box1, box3)).isFalse(); + assertThat(evaluator.intersects(box3, box1)).isFalse(); + } + + @Test + public void testBasicGeographyCases() { + Type geographyType = Types.GeographyType.of("srid:4326", EdgeAlgorithm.SPHERICAL); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geographyType); + + // Two overlapping boxes + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(10.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(5.0, 5.0); + GeospatialBound max2 = GeospatialBound.createXY(15.0, 15.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + + // Non-overlapping boxes + GeospatialBound min3 = GeospatialBound.createXY(20.0, 20.0); + GeospatialBound max3 = GeospatialBound.createXY(30.0, 30.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box3)).isFalse(); + assertThat(evaluator.intersects(box3, box1)).isFalse(); + + // Boxes at extreme valid latitudes + GeospatialBound min4 = GeospatialBound.createXY(-10.0, -90.0); + GeospatialBound max4 = GeospatialBound.createXY(10.0, -80.0); + BoundingBox box4 = new BoundingBox(min4, max4); + + GeospatialBound min5 = GeospatialBound.createXY(-5.0, 80.0); + GeospatialBound max5 = GeospatialBound.createXY(15.0, 90.0); + BoundingBox box5 = new BoundingBox(min5, max5); + + assertThat(evaluator.intersects(box4, box5)).isFalse(); + assertThat(evaluator.intersects(box5, box4)).isFalse(); + } + + @Test + public void testGeographyWrapAround() { + Type geographyType = Types.GeographyType.of("srid:4326", EdgeAlgorithm.SPHERICAL); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geographyType); + + // Box that wraps around the antimeridian + GeospatialBound min1 = GeospatialBound.createXY(170.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(-170.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + // Box that overlaps with the part after the wrap around + GeospatialBound min2 = GeospatialBound.createXY(-175.0, 5.0); + GeospatialBound max2 = GeospatialBound.createXY(-160.0, 15.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testInvalidGeographyLatitude() { + Type geographyType = Types.GeographyType.of("srid:4326", EdgeAlgorithm.SPHERICAL); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geographyType); + + // Box with latitude below -90 + GeospatialBound min1 = GeospatialBound.createXY(0.0, -91.0); + GeospatialBound max1 = GeospatialBound.createXY(10.0, 0.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + // Box with latitude above 90 + GeospatialBound min2 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max2 = GeospatialBound.createXY(10.0, 91.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + GeospatialBound validMin = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound validMax = GeospatialBound.createXY(10.0, 10.0); + BoundingBox validBox = new BoundingBox(validMin, validMax); + + assertThatThrownBy(() -> evaluator.intersects(box1, validBox)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Latitude out of range"); + + assertThatThrownBy(() -> evaluator.intersects(validBox, box1)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Latitude out of range"); + + assertThatThrownBy(() -> evaluator.intersects(box2, validBox)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Latitude out of range"); + + assertThatThrownBy(() -> evaluator.intersects(validBox, box2)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Latitude out of range"); + } + + @Test + public void testInvalidGeographyLongitude() { + Type geographyType = Types.GeographyType.of("srid:4326", EdgeAlgorithm.SPHERICAL); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geographyType); + + // Box with longitude below -180 + GeospatialBound min1 = GeospatialBound.createXY(-181.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(0.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + // Box with longitude above 180 + GeospatialBound min2 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max2 = GeospatialBound.createXY(181.0, 10.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + GeospatialBound validMin = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound validMax = GeospatialBound.createXY(10.0, 10.0); + BoundingBox validBox = new BoundingBox(validMin, validMax); + + assertThatThrownBy(() -> evaluator.intersects(box1, validBox)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Longitude out of range"); + + assertThatThrownBy(() -> evaluator.intersects(validBox, box1)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Longitude out of range"); + + assertThatThrownBy(() -> evaluator.intersects(box2, validBox)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Longitude out of range"); + + assertThatThrownBy(() -> evaluator.intersects(validBox, box2)) + .isInstanceOf(IllegalArgumentException.class) + .hasMessageContaining("Longitude out of range"); + } + + @Test + public void testExtremeGeographyLongitudeBoundaries() { + // Tests valid boxes at the extreme boundaries of longitude + Type geographyType = Types.GeographyType.of("srid:4326", EdgeAlgorithm.SPHERICAL); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geographyType); + + // Box at -180 longitude + GeospatialBound min1 = GeospatialBound.createXY(-180.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(-170.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + // Box at 180 longitude + GeospatialBound min2 = GeospatialBound.createXY(170.0, 0.0); + GeospatialBound max2 = GeospatialBound.createXY(180.0, 10.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + // These boxes should not intersect + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + + // Box that wraps around the antimeridian, touching -180 and 180 + GeospatialBound min3 = GeospatialBound.createXY(180.0, 0.0); + GeospatialBound max3 = GeospatialBound.createXY(-180.0, 10.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + // This should intersect with both boxes at the extreme edges + assertThat(evaluator.intersects(box1, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box1)).isTrue(); + assertThat(evaluator.intersects(box2, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box2)).isTrue(); + } + + @Test + public void testBoxesWithXYZMCoordinates() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + // Two boxes with all XYZM coordinates that overlap in X, Y, Z but not in M + GeospatialBound min1 = GeospatialBound.createXYZM(0.0, 0.0, 0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXYZM(2.0, 2.0, 2.0, 1.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXYZM(1.0, 1.0, 1.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXYZM(3.0, 3.0, 3.0, 3.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + // They should NOT intersect because M dimensions don't overlap + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + } + + @Test + public void testBoxesWithXYZMCoordinatesIntersecting() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + // Two boxes with all XYZM coordinates that overlap in all dimensions + GeospatialBound min1 = GeospatialBound.createXYZM(0.0, 0.0, 0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXYZM(2.0, 2.0, 2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXYZM(1.0, 1.0, 1.0, 1.0); + GeospatialBound max2 = GeospatialBound.createXYZM(3.0, 3.0, 3.0, 3.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + // They should intersect because all dimensions overlap + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testMixedDimensionsXYvsXYZ() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + // One box with XY coordinates, another with XYZ coordinates + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXYZ(1.0, 1.0, 100.0); + GeospatialBound max2 = GeospatialBound.createXYZ(3.0, 3.0, 200.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + // They should intersect because Z dimension is ignored when not present in both Review Comment: so if Z is ignored in box1, the evaluator considers the Z as the full range? ########## api/src/test/java/org/apache/iceberg/geospatial/TestGeospatialPredicateEvaluators.java: ########## @@ -0,0 +1,489 @@ +/* + * 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.iceberg.geospatial; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +import org.apache.iceberg.types.EdgeAlgorithm; +import org.apache.iceberg.types.Type; +import org.apache.iceberg.types.Types; +import org.junit.jupiter.api.Test; + +public class TestGeospatialPredicateEvaluators { + + @Test + public void testGeometryType() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + assertThat(evaluator).isInstanceOf(GeospatialPredicateEvaluators.GeometryEvaluator.class); + } + + @Test + public void testSphericalGeographyType() { + Type geographyType = Types.GeographyType.of("srid:4326", EdgeAlgorithm.SPHERICAL); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geographyType); + + assertThat(evaluator).isInstanceOf(GeospatialPredicateEvaluators.GeographyEvaluator.class); + } + + @Test + public void testUnsupportedType() { + Type stringType = Types.StringType.get(); + + assertThatThrownBy(() -> GeospatialPredicateEvaluators.create(stringType)) + .isInstanceOf(UnsupportedOperationException.class) + .hasMessageContaining("Unsupported type for BoundingBox"); + } + + @Test + public void testOverlappingGeometryBoxesIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(5.0, 5.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(3.0, 3.0); + GeospatialBound max2 = GeospatialBound.createXY(8.0, 8.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testNonOverlappingGeometryBoxesDontIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(3.0, 3.0); + GeospatialBound max2 = GeospatialBound.createXY(5.0, 5.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + } + + @Test + public void testGeometryBoxesTouchingAtCornerIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(2.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXY(4.0, 4.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testGeometryBoxesTouchingAtEdgeIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(2.0, 0.0); + GeospatialBound max2 = GeospatialBound.createXY(4.0, 2.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testGeometryBoxContainedWithinAnotherIntersects() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(10.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(2.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXY(5.0, 5.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testGeometryBoxesWithZCoordinate() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + // Two boxes with Z coordinates that overlap in X and Y but not in Z + GeospatialBound min1 = GeospatialBound.createXYZ(0.0, 0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXYZ(2.0, 2.0, 1.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXYZ(1.0, 1.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXYZ(3.0, 3.0, 3.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + GeospatialBound min3 = GeospatialBound.createXYZ(1.0, 1.0, 1.0); + GeospatialBound max3 = GeospatialBound.createXYZ(3.0, 3.0, 3.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + assertThat(evaluator.intersects(box1, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box1)).isTrue(); + assertThat(evaluator.intersects(box2, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box2)).isTrue(); + } + + @Test + public void testGeometryBoxesWithMCoordinate() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + // Two boxes with M coordinates that overlap in X and Y but not in M + GeospatialBound min1 = GeospatialBound.createXYM(0.0, 0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXYM(2.0, 2.0, 1.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXYM(1.0, 1.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXYM(3.0, 3.0, 3.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + GeospatialBound min3 = GeospatialBound.createXYM(1.0, 1.0, 1.0); + GeospatialBound max3 = GeospatialBound.createXYM(3.0, 3.0, 3.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + assertThat(evaluator.intersects(box1, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box1)).isTrue(); + assertThat(evaluator.intersects(box2, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box2)).isTrue(); + } + + @Test + public void testGeometryBoxesWithEmptyXRange() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(170.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(-170.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + GeospatialBound min2 = GeospatialBound.createXY(-175.0, 5.0); + GeospatialBound max2 = GeospatialBound.createXY(-160.0, 15.0); + BoundingBox box2 = new BoundingBox(min2, max2); + GeospatialBound min3 = GeospatialBound.createXY(160.0, 0.0); + GeospatialBound max3 = GeospatialBound.createXY(-160.0, 10.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + assertThat(evaluator.intersects(box1, box3)).isFalse(); + assertThat(evaluator.intersects(box3, box1)).isFalse(); + } + + @Test + public void testBasicGeographyCases() { + Type geographyType = Types.GeographyType.of("srid:4326", EdgeAlgorithm.SPHERICAL); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geographyType); + + // Two overlapping boxes + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(10.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(5.0, 5.0); + GeospatialBound max2 = GeospatialBound.createXY(15.0, 15.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + + // Non-overlapping boxes + GeospatialBound min3 = GeospatialBound.createXY(20.0, 20.0); + GeospatialBound max3 = GeospatialBound.createXY(30.0, 30.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box3)).isFalse(); + assertThat(evaluator.intersects(box3, box1)).isFalse(); + + // Boxes at extreme valid latitudes + GeospatialBound min4 = GeospatialBound.createXY(-10.0, -90.0); + GeospatialBound max4 = GeospatialBound.createXY(10.0, -80.0); + BoundingBox box4 = new BoundingBox(min4, max4); + + GeospatialBound min5 = GeospatialBound.createXY(-5.0, 80.0); + GeospatialBound max5 = GeospatialBound.createXY(15.0, 90.0); + BoundingBox box5 = new BoundingBox(min5, max5); + + assertThat(evaluator.intersects(box4, box5)).isFalse(); + assertThat(evaluator.intersects(box5, box4)).isFalse(); + } + + @Test + public void testGeographyWrapAround() { Review Comment: could we have non overlap scenario with wrap around? ########## api/src/main/java/org/apache/iceberg/geospatial/GeospatialBound.java: ########## @@ -0,0 +1,313 @@ +/* + * 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.iceberg.geospatial; + +import java.nio.ByteBuffer; +import java.nio.ByteOrder; +import java.util.Objects; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; + +/** + * Represents a geospatial bound (minimum or maximum) for Iceberg tables. + * + * <p>According to the <a href="https://iceberg.apache.org/spec/#bound-serialization";>Bound + * serialization section of Iceberg Table spec</a>, geospatial bounds are serialized differently + * from the regular WKB representation. Geometry and geography bounds are single point encoded as a + * concatenation of 8-byte little-endian IEEE 754 coordinate values in the order X, Y, Z (optional), + * M (optional). + * + * <p>The encoding varies based on which coordinates are present: + * + * <ul> + * <li>x:y (2 doubles) when both z and m are unset + * <li>x:y:z (3 doubles) when only m is unset + * <li>x:y:NaN:m (4 doubles) when only z is unset + * <li>x:y:z:m (4 doubles) when all coordinates are set + * </ul> + * + * <p>This class represents a lower or upper geospatial bound and handles serialization and + * deserialization of these bounds to/from byte arrays, conforming to the Iceberg specification. + */ +public class GeospatialBound { + /** + * Parses a geospatial bound from a byte buffer according to Iceberg spec. + * + * <p>Based on the buffer size, this method determines which coordinates are present: - 16 bytes + * (2 doubles): x and y only - 24 bytes (3 doubles): x, y, and z - 32 bytes (4 doubles): x, y, z + * (might be NaN), and m + * + * <p>The ordinates are encoded as 8-byte little-endian IEEE 754 values. + * + * @param buffer the ByteBuffer containing the serialized geospatial bound + * @return a GeospatialBound object representing the parsed bound + * @throws IllegalArgumentException if the buffer has an invalid size + */ + public static GeospatialBound fromByteBuffer(ByteBuffer buffer) { + Preconditions.checkArgument( + buffer.order() == ByteOrder.LITTLE_ENDIAN, "Unsupported byte order: big endian"); Review Comment: nit: Iceberg error msg style would say `Invalid byte order: big endian` please update it in other places too. ########## api/src/test/java/org/apache/iceberg/geospatial/TestGeospatialPredicateEvaluators.java: ########## @@ -0,0 +1,489 @@ +/* + * 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.iceberg.geospatial; + +import static org.assertj.core.api.Assertions.assertThat; +import static org.assertj.core.api.Assertions.assertThatThrownBy; + +import org.apache.iceberg.types.EdgeAlgorithm; +import org.apache.iceberg.types.Type; +import org.apache.iceberg.types.Types; +import org.junit.jupiter.api.Test; + +public class TestGeospatialPredicateEvaluators { + + @Test + public void testGeometryType() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + assertThat(evaluator).isInstanceOf(GeospatialPredicateEvaluators.GeometryEvaluator.class); + } + + @Test + public void testSphericalGeographyType() { + Type geographyType = Types.GeographyType.of("srid:4326", EdgeAlgorithm.SPHERICAL); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geographyType); + + assertThat(evaluator).isInstanceOf(GeospatialPredicateEvaluators.GeographyEvaluator.class); + } + + @Test + public void testUnsupportedType() { + Type stringType = Types.StringType.get(); + + assertThatThrownBy(() -> GeospatialPredicateEvaluators.create(stringType)) + .isInstanceOf(UnsupportedOperationException.class) + .hasMessageContaining("Unsupported type for BoundingBox"); + } + + @Test + public void testOverlappingGeometryBoxesIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(5.0, 5.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(3.0, 3.0); + GeospatialBound max2 = GeospatialBound.createXY(8.0, 8.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testNonOverlappingGeometryBoxesDontIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(3.0, 3.0); + GeospatialBound max2 = GeospatialBound.createXY(5.0, 5.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + } + + @Test + public void testGeometryBoxesTouchingAtCornerIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(2.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXY(4.0, 4.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testGeometryBoxesTouchingAtEdgeIntersect() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(2.0, 2.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(2.0, 0.0); + GeospatialBound max2 = GeospatialBound.createXY(4.0, 2.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testGeometryBoxContainedWithinAnotherIntersects() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + GeospatialBound min1 = GeospatialBound.createXY(0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXY(10.0, 10.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXY(2.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXY(5.0, 5.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + assertThat(evaluator.intersects(box1, box2)).isTrue(); + assertThat(evaluator.intersects(box2, box1)).isTrue(); + } + + @Test + public void testGeometryBoxesWithZCoordinate() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + // Two boxes with Z coordinates that overlap in X and Y but not in Z + GeospatialBound min1 = GeospatialBound.createXYZ(0.0, 0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXYZ(2.0, 2.0, 1.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXYZ(1.0, 1.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXYZ(3.0, 3.0, 3.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + GeospatialBound min3 = GeospatialBound.createXYZ(1.0, 1.0, 1.0); + GeospatialBound max3 = GeospatialBound.createXYZ(3.0, 3.0, 3.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + assertThat(evaluator.intersects(box1, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box1)).isTrue(); + assertThat(evaluator.intersects(box2, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box2)).isTrue(); + } + + @Test + public void testGeometryBoxesWithMCoordinate() { + Type geometryType = Types.GeometryType.crs84(); + GeospatialPredicateEvaluators.GeospatialPredicateEvaluator evaluator = + GeospatialPredicateEvaluators.create(geometryType); + + // Two boxes with M coordinates that overlap in X and Y but not in M + GeospatialBound min1 = GeospatialBound.createXYM(0.0, 0.0, 0.0); + GeospatialBound max1 = GeospatialBound.createXYM(2.0, 2.0, 1.0); + BoundingBox box1 = new BoundingBox(min1, max1); + + GeospatialBound min2 = GeospatialBound.createXYM(1.0, 1.0, 2.0); + GeospatialBound max2 = GeospatialBound.createXYM(3.0, 3.0, 3.0); + BoundingBox box2 = new BoundingBox(min2, max2); + + GeospatialBound min3 = GeospatialBound.createXYM(1.0, 1.0, 1.0); + GeospatialBound max3 = GeospatialBound.createXYM(3.0, 3.0, 3.0); + BoundingBox box3 = new BoundingBox(min3, max3); + + assertThat(evaluator.intersects(box1, box2)).isFalse(); + assertThat(evaluator.intersects(box2, box1)).isFalse(); + assertThat(evaluator.intersects(box1, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box1)).isTrue(); + assertThat(evaluator.intersects(box2, box3)).isTrue(); + assertThat(evaluator.intersects(box3, box2)).isTrue(); + } + + @Test + public void testGeometryBoxesWithEmptyXRange() { Review Comment: what does `EmptyXRange` mean? Is this trying to test X wraparound for geometry, which was not allowed with latest? It makes me think that `GeometryEvaluator` should throw an exception when the bounding box has X wraparound, similar to the `GeographyEvaluator#validateBoundingBox` method ########## api/src/main/java/org/apache/iceberg/geospatial/GeospatialBound.java: ########## @@ -0,0 +1,313 @@ +/* + * 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.iceberg.geospatial; + +import java.nio.ByteBuffer; +import java.nio.ByteOrder; +import java.util.Objects; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; + +/** + * Represents a geospatial bound (minimum or maximum) for Iceberg tables. + * + * <p>According to the <a href="https://iceberg.apache.org/spec/#bound-serialization";>Bound + * serialization section of Iceberg Table spec</a>, geospatial bounds are serialized differently + * from the regular WKB representation. Geometry and geography bounds are single point encoded as a + * concatenation of 8-byte little-endian IEEE 754 coordinate values in the order X, Y, Z (optional), + * M (optional). + * + * <p>The encoding varies based on which coordinates are present: + * + * <ul> + * <li>x:y (2 doubles) when both z and m are unset + * <li>x:y:z (3 doubles) when only m is unset + * <li>x:y:NaN:m (4 doubles) when only z is unset + * <li>x:y:z:m (4 doubles) when all coordinates are set + * </ul> + * + * <p>This class represents a lower or upper geospatial bound and handles serialization and + * deserialization of these bounds to/from byte arrays, conforming to the Iceberg specification. + */ +public class GeospatialBound { + /** + * Parses a geospatial bound from a byte buffer according to Iceberg spec. + * + * <p>Based on the buffer size, this method determines which coordinates are present: - 16 bytes Review Comment: nit: for readability, change this paragraph to bullet lists ########## api/src/main/java/org/apache/iceberg/geospatial/GeospatialBound.java: ########## @@ -0,0 +1,313 @@ +/* + * 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.iceberg.geospatial; + +import java.nio.ByteBuffer; +import java.nio.ByteOrder; +import java.util.Objects; +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; + +/** + * Represents a geospatial bound (minimum or maximum) for Iceberg tables. + * + * <p>According to the <a href="https://iceberg.apache.org/spec/#bound-serialization";>Bound + * serialization section of Iceberg Table spec</a>, geospatial bounds are serialized differently + * from the regular WKB representation. Geometry and geography bounds are single point encoded as a + * concatenation of 8-byte little-endian IEEE 754 coordinate values in the order X, Y, Z (optional), + * M (optional). + * + * <p>The encoding varies based on which coordinates are present: + * + * <ul> + * <li>x:y (2 doubles) when both z and m are unset + * <li>x:y:z (3 doubles) when only m is unset + * <li>x:y:NaN:m (4 doubles) when only z is unset + * <li>x:y:z:m (4 doubles) when all coordinates are set + * </ul> + * + * <p>This class represents a lower or upper geospatial bound and handles serialization and + * deserialization of these bounds to/from byte arrays, conforming to the Iceberg specification. + */ +public class GeospatialBound { + /** + * Parses a geospatial bound from a byte buffer according to Iceberg spec. + * + * <p>Based on the buffer size, this method determines which coordinates are present: - 16 bytes + * (2 doubles): x and y only - 24 bytes (3 doubles): x, y, and z - 32 bytes (4 doubles): x, y, z + * (might be NaN), and m + * + * <p>The ordinates are encoded as 8-byte little-endian IEEE 754 values. + * + * @param buffer the ByteBuffer containing the serialized geospatial bound + * @return a GeospatialBound object representing the parsed bound + * @throws IllegalArgumentException if the buffer has an invalid size + */ + public static GeospatialBound fromByteBuffer(ByteBuffer buffer) { + Preconditions.checkArgument( + buffer.order() == ByteOrder.LITTLE_ENDIAN, "Unsupported byte order: big endian"); + int size = buffer.remaining(); + Preconditions.checkArgument( + size == 2 * Double.BYTES || size == 3 * Double.BYTES || size == 4 * Double.BYTES, + "Invalid geo spatial bound buffer size: %s. Valid sizes are 16, 24, or 32 bytes.", + size); + + if (size == 2 * Double.BYTES) { + // x:y format (2 doubles) + double coordX = buffer.getDouble(); + double coordY = buffer.getDouble(); + return createXY(coordX, coordY); + } else if (size == 3 * Double.BYTES) { + // x:y:z format (3 doubles) + double coordX = buffer.getDouble(); + double coordY = buffer.getDouble(); + double coordZ = buffer.getDouble(); + return createXYZ(coordX, coordY, coordZ); + } else { + // x:y:z:m format (4 doubles) - z might be NaN + double coordX = buffer.getDouble(); + double coordY = buffer.getDouble(); + double coordZ = buffer.getDouble(); + double coordM = buffer.getDouble(); + return new GeospatialBound(coordX, coordY, coordZ, coordM); + } + } + + /** + * Serializes this geospatial bound to a byte buffer according to Iceberg spec. + * + * <p>Following the Iceberg spec, the bound is serialized based on which coordinates are set: - + * x:y (2 doubles) when both z and m are unset - x:y:z (3 doubles) when only m is unset - Review Comment: nit: similarly use bullet list for readability ########## api/src/main/java/org/apache/iceberg/geospatial/GeospatialPredicateEvaluators.java: ########## @@ -0,0 +1,214 @@ +/* + * 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.iceberg.geospatial; + +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.types.Type; +import org.apache.iceberg.types.Types; + +public class GeospatialPredicateEvaluators { + private GeospatialPredicateEvaluators() {} + + public interface GeospatialPredicateEvaluator { + /** + * Determines whether the two bounding boxes intersect. + * + * @param bbox1 the first bounding box + * @param bbox2 the second bounding box + * @return true if this box intersects the other box + */ + boolean intersects(BoundingBox bbox1, BoundingBox bbox2); + } + + /** + * Create an evaluator for evaluating bounding box relationship for the given geospatial type. + * + * @param type the geospatial type, should be one of Type.TypeID.GEOMETRY or Type.TypeID.GEOGRAPHY + * @return the evaluator + */ + public static GeospatialPredicateEvaluator create(Type type) { + switch (type.typeId()) { + case GEOMETRY: + return create((Types.GeometryType) type); + case GEOGRAPHY: + return create((Types.GeographyType) type); + default: + throw new UnsupportedOperationException("Unsupported type for BoundingBox: " + type); + } + } + + /** + * Create an evaluator for evaluating bounding box relationship for planar geometries + * + * @return the evaluator + */ + public static GeometryEvaluator create(Types.GeometryType type) { + return new GeometryEvaluator(); + } + + /** + * Create an evaluator for evaluating bounding box relationship for geographies + * + * @return the evaluator + */ + public static GeographyEvaluator create(Types.GeographyType type) { + return new GeographyEvaluator(); + } + + public static class GeometryEvaluator implements GeospatialPredicateEvaluator { + + /** + * Check if two bounding boxes intersect + * + * @param bbox1 the first bounding box + * @param bbox2 the second bounding box + * @return true if the bounding boxes intersect + */ + @Override + public boolean intersects(BoundingBox bbox1, BoundingBox bbox2) { + if (!intersectsYZM(bbox1, bbox2)) { + return false; + } + + // Check X dimension (longitude/easting) - no wrap-around + return rangeIntersects(bbox1.min().x(), bbox1.max().x(), bbox2.min().x(), bbox2.max().x()); + } + + static boolean intersectsYZM(BoundingBox bbox1, BoundingBox bbox2) { + // Check Z dimension (elevation) if both boxes have Z coordinates - no wrap-around + if (bbox1.min().hasZ() && bbox1.max().hasZ() && bbox2.min().hasZ() && bbox2.max().hasZ()) { + if (!rangeIntersects(bbox1.min().z(), bbox1.max().z(), bbox2.min().z(), bbox2.max().z())) { + return false; + } + } + + // Check M dimension (measure) if both boxes have M coordinates - no wrap-around + if (bbox1.min().hasM() && bbox1.max().hasM() && bbox2.min().hasM() && bbox2.max().hasM()) { + if (!rangeIntersects(bbox1.min().m(), bbox1.max().m(), bbox2.min().m(), bbox2.max().m())) { + return false; + } + } + + // Check Y dimension (latitude/northing) - no wrap-around + if (!rangeIntersects(bbox1.min().y(), bbox1.max().y(), bbox2.min().y(), bbox2.max().y())) { + return false; + } + + return true; + } + + /** + * Check if two intervals intersect using regular interval logic. Two intervals [min1, max1] and + * [min2, max2] intersect if min1 <= max2 AND max1 >= min2. + * + * @param min1 minimum of first interval + * @param max1 maximum of first interval + * @param min2 minimum of second interval + * @param max2 maximum of second interval + * @return true if the intervals intersect + */ + static boolean rangeIntersects(double min1, double max1, double min2, double max2) { + return min1 <= max2 && max1 >= min2; + } + } + + public static class GeographyEvaluator implements GeospatialPredicateEvaluator { + /** + * Check if two bounding boxes intersect, taking wrap-around into account. + * + * <p>Wraparound (or antimeridian crossing) occurs when a geography crosses the 180°/-180° + * longitude line on a map. In these cases, the minimum X value is greater than the maximum X + * value (xmin > xmax). This represents a bounding box that wraps around the globe. + * + * <p>For example, a bounding box with xmin=170° and xmax=-170° represents an area that spans + * from 170° east to 190° east (or equivalently, -170° west). This is important for geometries + * that cross the antimeridian, like a path from Japan to Alaska. + * + * <p>When xmin > xmax, a point matches if its X coordinate is either X ≥ xmin OR X ≤ xmax, + * rather than the usual X ≥ xmin AND X ≤ xmax. In geographic terms, if the westernmost + * longitude is greater than the easternmost longitude, this indicates an antimeridian crossing. + * + * @param bbox1 the first bounding box + * @param bbox2 the second bounding box + * @return true if the bounding boxes intersect + */ + @Override + public boolean intersects(BoundingBox bbox1, BoundingBox bbox2) { + validateBoundingBox(bbox1); + validateBoundingBox(bbox2); + + if (!GeometryEvaluator.intersectsYZM(bbox1, bbox2)) { + return false; + } + + // Check X dimension (longitude/easting) - with wrap-around + return rangeIntersectsWithWrapAround( + bbox1.min().x(), bbox1.max().x(), bbox2.min().x(), bbox2.max().x()); + } + + /** + * For geography types, coordinates are restricted to the canonical ranges of [-180°, 180°] for + * longitude (X) and [-90°, 90°] for latitude (Y). + * + * @param bbox the bounding box to validate + * @throws IllegalArgumentException if the bounding box is invalid + */ + private void validateBoundingBox(BoundingBox bbox) { + Preconditions.checkArgument( + bbox.min().y() >= -90.0d && bbox.max().y() <= 90.0d, "Latitude out of range: %s", bbox); Review Comment: nit: error msg style `Invalid latitude: %s. Out of range : [-90°, 90°]` ########## api/src/main/java/org/apache/iceberg/geospatial/GeospatialPredicateEvaluators.java: ########## @@ -0,0 +1,128 @@ +/* + * 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.iceberg.geospatial; + +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.types.Type; + +public class GeospatialPredicateEvaluators { + private GeospatialPredicateEvaluators() {} + + public interface GeospatialPredicateEvaluator { + /** + * Test whether this bounding box intersects with another. + * + * @param bbox1 the first bounding box + * @param bbox2 the second bounding box + * @return true if this box intersects the other box + */ + boolean intersects(BoundingBox bbox1, BoundingBox bbox2); + } + + public static GeospatialPredicateEvaluator create(Type type) { Review Comment: can we remove this generic create method since we are the other two more specific create methods? ########## api/src/main/java/org/apache/iceberg/geospatial/BoundingBox.java: ########## @@ -0,0 +1,154 @@ +/* + * 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.iceberg.geospatial; + +import java.nio.ByteBuffer; +import java.nio.ByteOrder; +import java.util.Objects; + +/** + * Represents a geospatial bounding box composed of minimum and maximum bounds. + * + * <p>A bounding box (also called a Minimum Bounding Rectangle or MBR) is defined by two points: the + * minimum and maximum coordinates that define the box's corners. This provides a simple + * approximation of a more complex geometry for efficient filtering and data skipping. + */ +public class BoundingBox { + /** + * Create a {@link BoundingBox} object from buffers containing min and max bounds + * + * @param min the serialized minimum bound + * @param max the serialized maximum bound + * @return a BoundingBox instance + */ + public static BoundingBox fromByteBuffers(ByteBuffer min, ByteBuffer max) { Review Comment: looks like this method is also used at line 66 below. ########## api/src/main/java/org/apache/iceberg/geospatial/GeospatialPredicateEvaluators.java: ########## @@ -0,0 +1,214 @@ +/* + * 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.iceberg.geospatial; + +import org.apache.iceberg.relocated.com.google.common.base.Preconditions; +import org.apache.iceberg.types.Type; +import org.apache.iceberg.types.Types; + +public class GeospatialPredicateEvaluators { + private GeospatialPredicateEvaluators() {} + + public interface GeospatialPredicateEvaluator { + /** + * Determines whether the two bounding boxes intersect. + * + * @param bbox1 the first bounding box + * @param bbox2 the second bounding box + * @return true if this box intersects the other box + */ + boolean intersects(BoundingBox bbox1, BoundingBox bbox2); + } + + /** + * Create an evaluator for evaluating bounding box relationship for the given geospatial type. + * + * @param type the geospatial type, should be one of Type.TypeID.GEOMETRY or Type.TypeID.GEOGRAPHY + * @return the evaluator + */ + public static GeospatialPredicateEvaluator create(Type type) { + switch (type.typeId()) { + case GEOMETRY: + return create((Types.GeometryType) type); + case GEOGRAPHY: + return create((Types.GeographyType) type); + default: + throw new UnsupportedOperationException("Unsupported type for BoundingBox: " + type); + } + } + + /** + * Create an evaluator for evaluating bounding box relationship for planar geometries + * + * @return the evaluator + */ + public static GeometryEvaluator create(Types.GeometryType type) { + return new GeometryEvaluator(); + } + + /** + * Create an evaluator for evaluating bounding box relationship for geographies + * + * @return the evaluator + */ + public static GeographyEvaluator create(Types.GeographyType type) { + return new GeographyEvaluator(); + } + + public static class GeometryEvaluator implements GeospatialPredicateEvaluator { + + /** + * Check if two bounding boxes intersect + * + * @param bbox1 the first bounding box + * @param bbox2 the second bounding box + * @return true if the bounding boxes intersect + */ + @Override + public boolean intersects(BoundingBox bbox1, BoundingBox bbox2) { + if (!intersectsYZM(bbox1, bbox2)) { + return false; + } + + // Check X dimension (longitude/easting) - no wrap-around + return rangeIntersects(bbox1.min().x(), bbox1.max().x(), bbox2.min().x(), bbox2.max().x()); + } + + static boolean intersectsYZM(BoundingBox bbox1, BoundingBox bbox2) { Review Comment: nit: this util method can be pulled outside of this nested class. it doesn't affect the code sharing with `GeographyEvaluator`. just will be a little more symmetric. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
