diff --git a/src/main/java/io/github/js0ny/ilp_coursework/service/GpsCalculationService.java b/src/main/java/io/github/js0ny/ilp_coursework/service/GpsCalculationService.java index 6da3d0b..0cf07f8 100644 --- a/src/main/java/io/github/js0ny/ilp_coursework/service/GpsCalculationService.java +++ b/src/main/java/io/github/js0ny/ilp_coursework/service/GpsCalculationService.java @@ -1,38 +1,73 @@ package io.github.js0ny.ilp_coursework.service; -import io.github.js0ny.ilp_coursework.data.LngLatDto; -import io.github.js0ny.ilp_coursework.data.RegionDto; +import io.github.js0ny.ilp_coursework.data.*; import java.util.List; import org.springframework.stereotype.Service; +/** + * Class that handles calculations about Coordinates + * + * @see LngLatDto + * @see RegionDto + */ @Service public class GpsCalculationService { + /** + * Given step size + * + * @see #nextPosition(LngLatDto, double) + */ private static final double STEP = 0.00015; - private static final double CLOSE_THRESHOLD = STEP; + /** + * Given threshold to judge if two points are close to each other + * + * @see #isCloseTo(LngLatDto, LngLatDto) + */ + private static final double CLOSE_THRESHOLD = 0.00015; + /** + * Calculate the Euclidean distance between position1 and position2, which are coordinates + * defined as {@link LngLatDto} + * + * @param position1 The coordinate of the first position + * @param position2 The coordinate of the second position + * @return The Euclidean distance between position1 and position2 + * @see io.github.js0ny.ilp_coursework.controller.ApiController#getDistance(DistanceRequestDto) + */ public double calculateDistance(LngLatDto position1, LngLatDto position2) { double lngDistance = position2.lng() - position1.lng(); double latDistance = position2.lat() - position1.lat(); return Math.sqrt(lngDistance * lngDistance + latDistance * latDistance); } + /** + * Check if position1 and position2 are close to each other, the threshold is < 0.00015 + *

+ * Note that = 0.00015 will be counted as not close to and will return false + * + * @param position1 The coordinate of the first position + * @param position2 The coordinate of the second position + * @return True if position1 and position2 are close to each other + * @see #CLOSE_THRESHOLD + * @see io.github.js0ny.ilp_coursework.controller.ApiController#getIsCloseTo(DistanceRequestDto) + */ public boolean isCloseTo(LngLatDto position1, LngLatDto position2) { double distance = calculateDistance(position1, position2); return distance < CLOSE_THRESHOLD; } /** - * Called from ApiController.getNextPosition. - *

* Returns the next position moved from start in the direction with angle, with step size * 0.00015 * * @param start The coordinate of the original start point. * @param angle The direction to be moved in angle. * @return The next position moved from start + * @see #STEP + * @see io.github.js0ny.ilp_coursework.controller.ApiController#getNextPosition(MovementRequestDto) */ public LngLatDto nextPosition(LngLatDto start, double angle) { double rad = Math.toRadians(angle); @@ -42,15 +77,15 @@ public class GpsCalculationService { } /** - * Called from ApiController.getIsInRegion. - *

* Used to check if the given position * is inside the region, on edge and vertex is considered as inside. * * @param position The coordinate of the position. - * @param region A RegionDto that contains name and a list of LngLatDto + * @param region A {@link RegionDto} that contains name and a list of LngLatDto * @return true if position is inside the region. * @throws IllegalArgumentException If region is not closed + * @see io.github.js0ny.ilp_coursework.controller.ApiController#getIsInRegion(RegionCheckRequestDto) + * @see RegionDto#isClosed() */ public boolean checkIsInRegion(LngLatDto position, RegionDto region) throws IllegalArgumentException { if (!region.isClosed()) { // call method from RegionDto to check if not closed @@ -69,6 +104,8 @@ public class GpsCalculationService { * sits inside. * @return If the point sits inside the polygon then * return True + * @see #isPointOnEdge(LngLatDto, LngLatDto, LngLatDto) + * @see #checkIsInRegion(LngLatDto, RegionDto) */ private boolean rayCasting(LngLatDto point, List polygon) { int intersections = 0; @@ -81,7 +118,7 @@ public class GpsCalculationService { return true; } - // Ensure that a is norther than b, in order to easy classification + // Ensure that `a` is norther than `b`, in order to easy classification if (a.lat() > b.lat()) { LngLatDto temp = a; a = b; @@ -100,10 +137,6 @@ public class GpsCalculationService { double xIntersection = a.lng() + ((point.lat() - a.lat()) * (b.lng() - a.lng())) / (b.lat() - a.lat()); -// // The point is on the edge -// if (xIntersection == point.lng()) { -// return true; -// } if (xIntersection > point.lng()) { ++intersections; @@ -123,6 +156,7 @@ public class GpsCalculationService { * @param a point that forms the edge * @param b point that forms the edge * @return boolean, if p is on ab then true + * @see #rayCasting(LngLatDto, List) */ private boolean isPointOnEdge(LngLatDto p, LngLatDto a, LngLatDto b) { // Cross product: (p - a) × (b - a) diff --git a/src/test/java/io/github/js0ny/ilp_coursework/service/GpsCalculationServiceTest.java b/src/test/java/io/github/js0ny/ilp_coursework/service/GpsCalculationServiceTest.java index e0728b0..0e46370 100644 --- a/src/test/java/io/github/js0ny/ilp_coursework/service/GpsCalculationServiceTest.java +++ b/src/test/java/io/github/js0ny/ilp_coursework/service/GpsCalculationServiceTest.java @@ -16,7 +16,7 @@ import static org.assertj.core.api.AssertionsForClassTypes.within; public class GpsCalculationServiceTest { private static final double STEP = 0.00015; - private static final double CLOSE_THRESHOLD = STEP; + // private static final double CLOSE_THRESHOLD = STEP; private static final double PRECISION = 1e-9; private GpsCalculationService service;