Improvements to finding corner points in IdCoordinateSource.

CHANGELOG.md

@@ -6,6 +6,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased/Snapshot]
 
+### Added
+- Enhancing `VoltageLevel` with `equals` method [#1063](https://github.com/ie3-institute/PowerSystemDataModel/issues/1063)
+
+### Fixed
+
+### Changed
+- Improvements to the search for corner points in `IdCoordinateSource` [#1016](https://github.com/ie3-institute/PowerSystemDataModel/issues/1016)
+
+
 ## [5.0.1] - 2024-03-07
 
 ### Fixed
@@ -23,7 +32,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added test for invalid input data in `CsvRawGridSource` [#1021](https://github.com/ie3-institute/PowerSystemDataModel/issues/1021)
 - Added `CsvThermalGridSource` [#1009](https://github.com/ie3-institute/PowerSystemDataModel/issues/1009)
 - Enhance documentation for CSV timeseries [#825](https://github.com/ie3-institute/PowerSystemDataModel/issues/825)
-- Enhancing `VoltageLevel` with `equals` method [#1063](https://github.com/ie3-institute/PowerSystemDataModel/issues/1063)
 
 ### Fixed
 - Fixed Couchbase integration tests that randomly failed [#755](https://github.com/ie3-institute/PowerSystemDataModel/issues/755)

docs/readthedocs/io/csvfiles.md

@@ -81,6 +81,12 @@ You may extend / alter the naming with pre- or suffix by calling `new EntityPers
 
 ```
 
+### Id Coordinate
+Csv id coordinate sources can have two different ways to represent their coordinate:
+1. ICON: Takes a `latitude` and a `longitude` column
+2. COSMO: Takes a `lat_rot`, a `long_rot`, a `lat_geo` and a `long_geo` column
+
+
 ### Time Series
 
 ```{eval-rst}

docs/readthedocs/models/input/additionaldata/idcoordinatesource.md

@@ -7,11 +7,21 @@ coordinates.
 
 ## Information
 
-| Attribute    | Remarks                                                        |
-|:-------------|:---------------------------------------------------------------|
-| `Id`         | An integer value for identifying the coordinate.               |
-| `Coordiante` | Geographical information presented as `Lat/long` of a `Point`. |
+```{eval-rst}
+.. list-table::
+   :widths: 33 33
+   :header-rows: 0
+
+   * - Attribute
+     - Remarks
+
+   * - Id
+     - An integer value for identifying the coordinate. 
+
+   * - Coordinate
+     - Geographical information presented as `Lat/long` of a `Point`.
 
+```
 
 
 ## Known implementations:
@@ -74,19 +84,17 @@ return less than n coordinates.
 
 
 ## Finding and returning the closest corner coordinates:
-In most cases we need four corner coordinates for our given coordinate. Therefor the 
-IdCoordinateSource contains a method that will use the calculated distances to find the closest 
-corner coordinates for the given coordinate.
+In most cases we need four corner coordinates for our given coordinate. Therefor the IdCoordinateSource contains methods
+that tries to return the corner points for a given coordinate. The max. number of corner points is specified by the
+implementation of the second method.
 
 ``` java
-    List<CoordinateDistance> restrictToBoundingBox(
-          Point coordinate,
-          Collection<CoordinateDistance> distances,
-          int numberOfPoints
-    )
+    List<CoordinateDistance> findCornerPoints(Point coordinate, ComparableQuantity<Length> distance)
+    List<CoordinateDistance> findCornerPoints(Point coordinate, Collection<CoordinateDistance> distances)
 ```
 
-For a given set of coordinates, the closest four corner coordinates plus more close points if n > 4
-are returned. If n < 4 the method will return the closest n corner coordinates. If the set of 
-coordinates contains a coordinate that matches the given coordinate, only this one coordinate is
-returned. If n > number of coordinates in the set, all coordinates are returned.
+1. This method can be used to return the corner points by specifying a maximum search distance.
+
+2. If a coordinate matches the given coordinate, only this coordinate is returned. If no coordinate matches the given 
+coordinate, this method tries to return four corner points.
+

src/main/java/edu/ie3/datamodel/io/source/IdCoordinateSource.java

@@ -84,8 +84,7 @@ List<CoordinateDistance> getClosestCoordinates(
 
   /**
    * Calculates and returns the nearest n coordinate distances to the given coordinate from a given
-   * collection of points. If the set is empty or null an empty list is returned. If n is greater
-   * than four, this method will try to return the corner points of the bounding box.
+   * collection of points. If the set is empty or null an empty list is returned.
    *
    * @param coordinate the coordinate to look up the nearest neighbours for
    * @param n how many neighbours to look up
@@ -95,81 +94,77 @@ List<CoordinateDistance> getClosestCoordinates(
   default List<CoordinateDistance> calculateCoordinateDistances(
       Point coordinate, int n, Collection<Point> coordinates) {
     if (coordinates != null && !coordinates.isEmpty()) {
-      List<CoordinateDistance> sortedDistances =
-          GeoUtils.calcOrderedCoordinateDistances(coordinate, coordinates);
-      return restrictToBoundingBox(coordinate, sortedDistances, n);
+      return GeoUtils.calcOrderedCoordinateDistances(coordinate, coordinates).stream()
+          .limit(n)
+          .toList();
     } else {
       return Collections.emptyList();
     }
   }
 
   /**
-   * Method for evaluating the found points. This method tries to return the four corner points of
-   * the bounding box of the given coordinate. If one of the found points matches the given
-   * coordinate, only this point is returned. If the given number of searched points is less than
-   * four, this method will only return the nearest n corner points. If the given number of searched
-   * points is greater than four, this method will return the four corner points plus the nearest n
-   * points to match the number of searched points.
+   * Method for finding the corner points of a given coordinate within a given distance.
+   *
+   * <p>The max. number of returned corner points is set by the implementation (default: 4).
+   *
+   * @param coordinate at the center
+   * @param distance list of fount points with their distances
+   * @return either a list with one exact match or a list of corner points (default implementation:
+   *     max. 4 points)
+   */
+  List<CoordinateDistance> findCornerPoints(Point coordinate, ComparableQuantity<Length> distance);
+
+  /**
+   * Method for finding the corner points of a given coordinate. If a point matches the given
+   * coordinate, only this point is returned.
+   *
+   * <p>The max. number of returned corner points is set by the implementation (default: 4).
    *
    * <p>To work properly, the given collection of {@link CoordinateDistance}'s should already be
    * sorted by distance.
    *
-   * @param coordinate at the center of the bounding box
-   * @param distances list of found points with their distances
-   * @param numberOfPoints that should be returned
-   * @return list of distances
+   * @param coordinate at the center
+   * @param coordinateDistances list of fount points with their distances
+   * @return either a list with one exact match or a list of corner points (default implementation:
+   *     max. 4 points)
    */
-  default List<CoordinateDistance> restrictToBoundingBox(
-      Point coordinate, Collection<CoordinateDistance> distances, int numberOfPoints) {
+  default List<CoordinateDistance> findCornerPoints(
+      Point coordinate, Collection<CoordinateDistance> coordinateDistances) {
     boolean topLeft = false;
     boolean topRight = false;
     boolean bottomLeft = false;
     boolean bottomRight = false;
 
     List<CoordinateDistance> resultingDistances = new ArrayList<>();
-    List<CoordinateDistance> other = new ArrayList<>();
 
     // search for smallest bounding box
-    for (CoordinateDistance distance : distances) {
+    for (CoordinateDistance distance : coordinateDistances) {
       Point point = distance.getCoordinateB();
 
       // check for bounding box
       if (coordinate.equalsExact(point, 1e-6)) {
         // if current point is matching the given coordinate, we need to return only the current
         // point
-        resultingDistances.clear();
-        resultingDistances.add(distance);
-        return resultingDistances;
+        return List.of(distance);
       } else if (!topLeft
-          && (point.getX() < coordinate.getX() && point.getY() > coordinate.getY())) {
+          && (point.getX() <= coordinate.getX() && point.getY() >= coordinate.getY())) {
         resultingDistances.add(distance);
         topLeft = true;
       } else if (!topRight
-          && (point.getX() > coordinate.getX() && point.getY() > coordinate.getY())) {
+          && (point.getX() >= coordinate.getX() && point.getY() >= coordinate.getY())) {
         resultingDistances.add(distance);
         topRight = true;
       } else if (!bottomLeft
-          && (point.getX() < coordinate.getX() && point.getY() < coordinate.getY())) {
+          && (point.getX() <= coordinate.getX() && point.getY() <= coordinate.getY())) {
         resultingDistances.add(distance);
         bottomLeft = true;
       } else if (!bottomRight
-          && (point.getX() > coordinate.getX() && point.getY() < coordinate.getY())) {
+          && (point.getX() >= coordinate.getX() && point.getY() <= coordinate.getY())) {
         resultingDistances.add(distance);
         bottomRight = true;
-      } else {
-        other.add(distance);
       }
     }
 
-    // check if n distances are found
-    int diff = numberOfPoints - resultingDistances.size();
-
-    if (diff > 0) {
-      resultingDistances.addAll(other.stream().limit(diff).toList());
-    } else if (diff < 0) {
-      return resultingDistances.stream().limit(numberOfPoints).toList();
-    }
-
     return resultingDistances;
   }
 }

src/main/java/edu/ie3/datamodel/io/source/csv/CsvIdCoordinateSource.java

@@ -161,20 +161,31 @@ public List<CoordinateDistance> getNearestCoordinates(Point coordinate, int n) {
   @Override
   public List<CoordinateDistance> getClosestCoordinates(
       Point coordinate, int n, ComparableQuantity<Length> distance) {
-    Set<Point> points = coordinateToId.keySet();
-
-    Envelope envelope = GeoUtils.calculateBoundingBox(coordinate, distance);
-    Set<Point> reducedPoints =
-        points.stream()
-            .filter(point -> envelope.contains(point.getCoordinate()))
-            .collect(Collectors.toSet());
+    Collection<Point> reducedPoints = getCoordinatesInBoundingBox(coordinate, distance);
     return calculateCoordinateDistances(coordinate, n, reducedPoints);
   }
 
+  @Override
+  public List<CoordinateDistance> findCornerPoints(
+      Point coordinate, ComparableQuantity<Length> distance) {
+    Collection<Point> points = getCoordinatesInBoundingBox(coordinate, distance);
+    return findCornerPoints(
+        coordinate, GeoUtils.calcOrderedCoordinateDistances(coordinate, points));
+  }
+
   public int getCoordinateCount() {
     return idToCoordinate.keySet().size();
   }
 
+  private Collection<Point> getCoordinatesInBoundingBox(
+      Point coordinate, ComparableQuantity<Length> distance) {
+    Set<Point> points = coordinateToId.keySet();
+    Envelope envelope = GeoUtils.calculateBoundingBox(coordinate, distance);
+    return points.stream()
+        .filter(point -> envelope.contains(point.getCoordinate()))
+        .collect(Collectors.toSet());
+  }
+
   /**
    * Build a stream with mappings from field identifiers to attributes
    *

src/main/java/edu/ie3/datamodel/io/source/sql/SqlIdCoordinateSource.java

@@ -178,25 +178,37 @@ public List<CoordinateDistance> getNearestCoordinates(Point coordinate, int n) {
   @Override
   public List<CoordinateDistance> getClosestCoordinates(
       Point coordinate, int n, ComparableQuantity<Length> distance) {
+    List<Point> points = getCoordinatesInBoundingBox(coordinate, distance);
+    return calculateCoordinateDistances(coordinate, n, points);
+  }
+
+  @Override
+  public List<CoordinateDistance> findCornerPoints(
+      Point coordinate, ComparableQuantity<Length> distance) {
+    List<Point> points = getCoordinatesInBoundingBox(coordinate, distance);
+    return findCornerPoints(
+        coordinate, GeoUtils.calcOrderedCoordinateDistances(coordinate, points));
+  }
+
+  // -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
+
+  private List<Point> getCoordinatesInBoundingBox(
+      Point coordinate, ComparableQuantity<Length> distance) {
     Envelope envelope = GeoUtils.calculateBoundingBox(coordinate, distance);
 
-    List<CoordinateValue> values =
-        executeQueryToList(
+    return executeQueryToList(
             queryForBoundingBox,
             ps -> {
               ps.setDouble(1, envelope.getMinX());
               ps.setDouble(2, envelope.getMinY());
               ps.setDouble(3, envelope.getMaxX());
               ps.setDouble(4, envelope.getMaxY());
-            });
-
-    List<Point> points = values.stream().map(value -> value.coordinate).toList();
-
-    return calculateCoordinateDistances(coordinate, n, points);
+            })
+        .stream()
+        .map(value -> value.coordinate)
+        .toList();
   }
 
-  // -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
-
   private CoordinateValue createCoordinateValue(Map<String, String> fieldToValues) {
     fieldToValues.remove("distance");
 

src/test/groovy/edu/ie3/datamodel/io/source/IdCoordinateSourceMock.groovy

@@ -48,4 +48,9 @@ class IdCoordinateSourceMock implements IdCoordinateSource {
   List<CoordinateDistance> getClosestCoordinates(Point coordinate, int n, ComparableQuantity<Length> distance) {
     return Collections.emptyList()
   }
+
+  @Override
+  List<CoordinateDistance> findCornerPoints(Point coordinate, ComparableQuantity<Length> distance) {
+    return Collections.emptyList()
+  }
 }

src/test/groovy/edu/ie3/datamodel/io/source/IdCoordinateSourceTest.groovy

@@ -14,15 +14,15 @@ class IdCoordinateSourceTest extends Specification {
   private final IdCoordinateSourceMock coordinateSourceMock = new IdCoordinateSourceMock()
 
   private final Point point0 = GeoUtils.buildPoint(52.5, 7.5)
-  private final Point point1 = GeoUtils.buildPoint(53, 8)
+  private final Point point1 = GeoUtils.buildPoint(53, 7.9)
   private final Point point2 = GeoUtils.buildPoint(53, 7)
-  private final Point point3 = GeoUtils.buildPoint(53, 6)
-  private final Point point4 = GeoUtils.buildPoint(52, 8)
+  private final Point point3 = GeoUtils.buildPoint(53, 6.2)
+  private final Point point4 = GeoUtils.buildPoint(52, 7.9)
   private final Point point5 = GeoUtils.buildPoint(52, 7)
-  private final Point point6 = GeoUtils.buildPoint(52, 6)
-  private final Point point7 = GeoUtils.buildPoint(51, 8)
+  private final Point point6 = GeoUtils.buildPoint(52, 6.2)
+  private final Point point7 = GeoUtils.buildPoint(51, 7.9)
   private final Point point8 = GeoUtils.buildPoint(51, 7)
-  private final Point point9 = GeoUtils.buildPoint(51, 6)
+  private final Point point9 = GeoUtils.buildPoint(51, 6.2)
 
   private final List<Point> points = [
     point1,
@@ -36,36 +36,34 @@ class IdCoordinateSourceTest extends Specification {
     point9
   ]
 
-  def "IdCoordinateSource should return correct number of corner points restricted to the bounding box"() {
+  def "IdCoordinateSource should return only the corner points of a collection of coordinate distances"() {
     given:
     List<Point> expectedPoints = [
+      point1,
       point2,
       point4,
-      point5,
-      point6,
-      point8
+      point5
     ]
 
     when:
-    List<CoordinateDistance> distances = coordinateSourceMock.calculateCoordinateDistances(point0, 9, points)
-    List<CoordinateDistance> result = coordinateSourceMock.restrictToBoundingBox(point0, distances, 4)
+    List<CoordinateDistance> distances = GeoUtils.calcOrderedCoordinateDistances(point0, points)
+    List<CoordinateDistance> result = coordinateSourceMock.findCornerPoints(point0, distances)
 
     then:
-    for (CoordinateDistance value: result) {
-      expectedPoints.contains(value.coordinateB)
-    }
+    result.size() == expectedPoints.size()
+    result*.coordinateB.containsAll(expectedPoints)
   }
 
-  def "IdCoordinateSource should return only one point of the bounding box if the starting coordinate exactly matched the found coordinate"() {
+  def "IdCoordinateSource should return only one point if the starting coordinate exactly matched the found coordinate"() {
     given:
     Point matchingPoint = GeoUtils.buildPoint(52.5, 7.5)
 
     when:
     List<Point> withExactMatch = new ArrayList<>(points)
     withExactMatch.addAll(matchingPoint)
 
-    List<CoordinateDistance> distances = coordinateSourceMock.calculateCoordinateDistances(point0, 9, withExactMatch)
-    List<CoordinateDistance> result = coordinateSourceMock.restrictToBoundingBox(point0, distances, 4)
+    List<CoordinateDistance> distances = GeoUtils.calcOrderedCoordinateDistances(point0, withExactMatch)
+    List<CoordinateDistance> result = coordinateSourceMock.findCornerPoints(point0, distances)
 
     then:
     result.size() == 1