From adeeb78f3d92060749853f4acc77840b7206618c Mon Sep 17 00:00:00 2001 From: bten Date: Wed, 15 Apr 2020 18:49:15 +0200 Subject: [PATCH] Add javadoc and redo some TopologyException-handlings --- .../hunt/strategy/geom/GeometryStyle.java | 4 +- .../hider/impl/RandomHalfPlaneHintHider.java | 1 - .../strategy/hint/impl/HalfPlaneHint.java | 20 +++++-- .../ExcludedAreasUtils.java | 22 +++---- ...egy.java => MinimumRectangleSearcher.java} | 60 ++++++++++++++++--- .../RectangleScanEnhanced.java | 57 ++++++++++++------ .../TransformForAxisParallelism.java | 5 +- .../strategyFromPaper/GeometricUtils.java | 7 +-- .../LastHintBadSubroutine.java | 11 ++-- .../strategyFromPaper/RoutinesFromPaper.java | 21 +++---- .../strategyFromPaper/StatusMessages.java | 35 +++++++---- .../strategyFromPaper/StrategyFromPaper.java | 45 +++----------- 12 files changed, 166 insertions(+), 122 deletions(-) rename src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/{MinimumRectangleStrategy.java => MinimumRectangleSearcher.java} (91%) diff --git a/src/main/java/com/treasure/hunt/strategy/geom/GeometryStyle.java b/src/main/java/com/treasure/hunt/strategy/geom/GeometryStyle.java index 71193f60..3b2afba0 100644 --- a/src/main/java/com/treasure/hunt/strategy/geom/GeometryStyle.java +++ b/src/main/java/com/treasure/hunt/strategy/geom/GeometryStyle.java @@ -28,8 +28,8 @@ public class GeometryStyle { public static final GeometryStyle PREVIOUS_RECTANGLE = new GeometryStyle(true, new Color(0xBB67aa57, true)); public static final GeometryStyle CURRENT_POLYGON = new GeometryStyle(true, new Color(0x40E0D0), new Color(0x0840E0D0, true)); public static final GeometryStyle HALF_PLANE_CURRENT_RED = new GeometryStyle(true, new Color(0x99ff0000, true), new Color(0x11ff0000, true)); - public static final GeometryStyle HALF_PLANE_PREVIOUS_BROWN = new GeometryStyle(true, new Color(0x99fc532d, true), new Color(0x05fc532d, true)); - public static final GeometryStyle HALF_PLANE_BEFORE_PREVIOUS_LIGHT_BROWN = new GeometryStyle(true, new Color(0x99ff9933, true), new Color(0x05ff9933, true)); + public static final GeometryStyle HALF_PLANE_PREVIOUS_BROWN = new GeometryStyle(true, new Color(0x99fc532d, true), new Color(0x09fc532d, true)); + public static final GeometryStyle HALF_PLANE_BEFORE_PREVIOUS_LIGHT_BROWN = new GeometryStyle(true, new Color(0x99ff9933, true), new Color(0x09ff9933, true)); public static final GeometryStyle L1_DOUBLE_APOS = new GeometryStyle(true, Color.BLUE); public static final GeometryStyle HALF_PLANE = new GeometryStyle(true, new Color(0x777777), new Color(0x22777777, true)); public static final GeometryStyle WAY_POINT_LINE = new GeometryStyle(true, new Color(0xFFFFFF)); diff --git a/src/main/java/com/treasure/hunt/strategy/hider/impl/RandomHalfPlaneHintHider.java b/src/main/java/com/treasure/hunt/strategy/hider/impl/RandomHalfPlaneHintHider.java index 301337ca..5e0fedd7 100644 --- a/src/main/java/com/treasure/hunt/strategy/hider/impl/RandomHalfPlaneHintHider.java +++ b/src/main/java/com/treasure/hunt/strategy/hider/impl/RandomHalfPlaneHintHider.java @@ -20,7 +20,6 @@ * @author Rank */ @Preference(name = PreferenceService.MAX_TREASURE_DISTANCE, value = 100) -@Preference(name = PreferenceService.TREASURE_DISTANCE, value = 100) @Preference(name = PreferenceService.MIN_TREASURE_DISTANCE, value = 100) public class RandomHalfPlaneHintHider implements Hider { HalfPlaneHint lastHint = null; diff --git a/src/main/java/com/treasure/hunt/strategy/hint/impl/HalfPlaneHint.java b/src/main/java/com/treasure/hunt/strategy/hint/impl/HalfPlaneHint.java index 91edd335..ab87fb57 100644 --- a/src/main/java/com/treasure/hunt/strategy/hint/impl/HalfPlaneHint.java +++ b/src/main/java/com/treasure/hunt/strategy/hint/impl/HalfPlaneHint.java @@ -19,7 +19,7 @@ * A special ase of {@link AngleHint} with 180 degrees or {@link Math#PI} radians, * defining a {@link HalfPlane} in which the treasure lies * - * @author bsen + * @author Rank */ public class HalfPlaneHint extends AngleHint { @@ -47,10 +47,6 @@ public HalfPlaneHint(Coordinate center, Coordinate right) { /** * This constructor can be used when unsure whether pointOne or pointTwo is the right/left point of the * hint but the direction of the hint is known. - * - * @param pointOne - * @param pointTwo - * @param direction */ public HalfPlaneHint(Coordinate pointOne, Coordinate pointTwo, Direction direction) { super(new Coordinate(), new Coordinate(), new Coordinate()); @@ -204,6 +200,10 @@ public List> getGeometryItems() { } } + /** + * Returns either the center or the right point + * The point with the lower y value gets returned. + */ public Coordinate getLowerHintPoint() { if (getCenter().getY() < getRight().getY()) { return getCenter(); @@ -212,6 +212,10 @@ public Coordinate getLowerHintPoint() { } } + /** + * Returns either the center or the right point + * The point with the higher y value gets returned. + */ public Coordinate getUpperHintPoint() { if (getCenter().getY() < getRight().getY()) { return getRight(); @@ -220,11 +224,17 @@ public Coordinate getUpperHintPoint() { } } + /** + * @return true if the treasure is above this hints line, false otherwise + */ public boolean pointsUpwards() { return (getDirection() == Direction.left && getLowerHintPoint().getX() < getUpperHintPoint().getX()) || (getDirection() == Direction.right && getLowerHintPoint().getX() > getUpperHintPoint().getX()); } + /** + * @return true if the treasure is below this hints line, false otherwise + */ public boolean pointsDownwards() { return (getDirection() == Direction.left && getLowerHintPoint().getX() > getUpperHintPoint().getX()) || (getDirection() == Direction.right && getLowerHintPoint().getX() < getUpperHintPoint().getX()); diff --git a/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/ExcludedAreasUtils.java b/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/ExcludedAreasUtils.java index e8c3484b..cfee433b 100644 --- a/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/ExcludedAreasUtils.java +++ b/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/ExcludedAreasUtils.java @@ -4,6 +4,7 @@ import com.treasure.hunt.strategy.searcher.SearchPath; import com.treasure.hunt.utils.JTSUtils; import org.locationtech.jts.geom.*; +import org.locationtech.jts.operation.buffer.BufferParameters; import java.util.ArrayList; import java.util.List; @@ -91,8 +92,7 @@ static Polygon intersectHints(List hintListOne, List halfPlaneHints) {//todo do better - for (HalfPlaneHint halfPlaneHint : halfPlaneHints) { - convexPolygon = reduceConvexPolygon(convexPolygon, halfPlaneHint); - if (convexPolygon == null) { - return JTSUtils.GEOMETRY_FACTORY.createPolygon(); - } - } - return convexPolygon; - } - - static Geometry visitedPolygon(Point lastLocation, SearchPath move) { + static Geometry visitedPolygon(Point lastLocation, SearchPath move, int endCapStyle) { if (lastLocation == null || move == null) { throw new IllegalArgumentException("lastLocation or move is null"); } @@ -173,6 +163,10 @@ static Geometry visitedPolygon(Point lastLocation, SearchPath move) { return JTSUtils.GEOMETRY_FACTORY.createPoint(movesCoordinates[0]).buffer(1); } LineString path = JTSUtils.GEOMETRY_FACTORY.createLineString(movesCoordinates); - return path.buffer(1); + return path.buffer(1, 8, endCapStyle); + } + + static Geometry visitedPolygon(Point lastLocation, SearchPath move) { + return visitedPolygon(lastLocation, move, BufferParameters.CAP_ROUND); } } diff --git a/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/MinimumRectangleStrategy.java b/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/MinimumRectangleSearcher.java similarity index 91% rename from src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/MinimumRectangleStrategy.java rename to src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/MinimumRectangleSearcher.java index 2733c95b..dfbc3e78 100644 --- a/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/MinimumRectangleStrategy.java +++ b/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/MinimumRectangleSearcher.java @@ -13,7 +13,9 @@ import com.treasure.hunt.strategy.searcher.impl.strategyFromPaper.StrategyFromPaper; import com.treasure.hunt.utils.JTSUtils; import lombok.Getter; +import lombok.extern.slf4j.Slf4j; import org.locationtech.jts.geom.*; +import org.locationtech.jts.operation.buffer.BufferParameters; import org.locationtech.jts.util.AssertionFailedException; import java.util.ArrayList; @@ -62,14 +64,12 @@ * * @author Rank */ -public class MinimumRectangleStrategy extends StrategyFromPaper implements Searcher { +@Slf4j +public class MinimumRectangleSearcher extends StrategyFromPaper implements Searcher { Point realSearcherStartPosition; RectangleScanEnhanced rectangleScanEnhanced = new RectangleScanEnhanced(this); private boolean firstMoveWithHint = true; private TransformForAxisParallelism transformer; - /** - * received after the last update of the phase's rectangle - */ @Getter private List obtainedHints; // stored in internal coordinates /** @@ -235,6 +235,10 @@ public SearchPath move(HalfPlaneHint hint) { return returnHandlingMinimumRectangleStrategy(goodHintSubroutine()); } + /** + * Reduces hintPolygon and currentMultiPolygon, by excluding the area hint can exclude. + * @param hint a received hint (in internal representation) + */ void reducePolygons(HalfPlaneHint hint) { if (hintPolygon == null) { currentMultiPolygon = null; @@ -243,11 +247,19 @@ void reducePolygons(HalfPlaneHint hint) { if (hintPolygon == null || currentMultiPolygonIsEmpty()) { currentMultiPolygon = null; } else { - currentMultiPolygon = hintPolygon.difference(visitedPolygon); + try { + currentMultiPolygon = hintPolygon.difference(visitedPolygon); + } catch (TopologyException e) { + log.info("Due to precision error, the strategy is exiting."); + throw e; + } } } } + /** + * @return the search-path to go in case the hint was good + */ SearchPath goodHintSubroutine() { SearchPath move = new SearchPath(); currentHintQuality = HintQuality.good; @@ -257,6 +269,13 @@ SearchPath goodHintSubroutine() { return move; } + /** + * Increments the phase (possibly multiple times) until the currentMultiPolygon of this phase is not empty. + * Then it moves to the middle of the new current rectangle (which gets determined by the currentMultiPolygon). + * + * @param move the search-path the moves should be added to + * @return the search-path with the appropriate moves added + */ SearchPath setNewPhaseAndMove(SearchPath move) { phaseGotIncrementedThisMove = true; if (!currentMultiPolygonIsEmpty()) { @@ -282,6 +301,10 @@ SearchPath setNewPhaseAndMove(SearchPath move) { return move; } + /** + * @param hintInInternal the current hint in internal representation + * @return true if the hint is good, false otherwise + */ boolean hintIsGood(HalfPlaneHint hintInInternal) { LineSegment hintLine = hintInInternal.getHalfPlaneLine(); LineSegment AB = new LineSegment(searchAreaCornerA.getCoordinate(), searchAreaCornerB.getCoordinate()); @@ -309,14 +332,23 @@ boolean hintIsGood(HalfPlaneHint hintInInternal) { return true; } - - void updateVisitedPolygon(SearchPath move) {// lastLocation has to be set right - visitedPolygon = (Polygon) visitedPolygon.union(visitedPolygon(lastLocation, move)); + /** + * Adds the areas seen by move to the visitedPolygon + */ + void updateVisitedPolygon(SearchPath move) { + Polygon newVisitedPolygon = (Polygon) visitedPolygon.union(visitedPolygon(lastLocation, move)); if (hintPolygon != null && !currentMultiPolygonIsEmpty()) { - currentMultiPolygon = hintPolygon.difference(visitedPolygon); + try { + currentMultiPolygon = hintPolygon.difference(newVisitedPolygon); + } catch (TopologyException e) { + newVisitedPolygon = (Polygon) visitedPolygon.union(visitedPolygon(lastLocation, move, BufferParameters.CAP_FLAT)); + log.info("due to precision problem, the seen area of the player gets calculated different"); + } } else { currentMultiPolygon = null; } + + visitedPolygon = newVisitedPolygon; } /** @@ -424,6 +456,9 @@ protected SearchPath specificRectangleScan(Coordinate rectangleCorner1, Coordina move); } + /** + * @return the current rectangle in internal representation + */ private Coordinate[] searchRectangle() { return new Coordinate[]{searchAreaCornerA.getCoordinate(), searchAreaCornerB.getCoordinate(), searchAreaCornerC.getCoordinate(), searchAreaCornerD.getCoordinate()}; @@ -444,10 +479,17 @@ private SearchPath scanCurrentRectangle(SearchPath move, HalfPlaneHint hint) { searchAreaCornerC.getCoordinate(), searchAreaCornerD.getCoordinate(), move); } + /** + * @return true if the currentMultiPolygon is empty, false otherwise + */ private boolean currentMultiPolygonIsEmpty() { return currentMultiPolygon == null || JTSUtils.doubleEqual(currentMultiPolygon.getArea(), 0); } + /** + * Does set searchAreaCornerA, searchAreaCornerB, etc. so that the searchRectangle covers all areas in currentMultiPolygon + * and is parallel to the phase rectangle + */ private void setABCDinStrategy() { if (currentMultiPolygonIsEmpty()) { searchAreaCornerA = null; diff --git a/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/RectangleScanEnhanced.java b/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/RectangleScanEnhanced.java index d36fc67a..d1fcb2da 100644 --- a/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/RectangleScanEnhanced.java +++ b/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/RectangleScanEnhanced.java @@ -8,27 +8,30 @@ import static com.treasure.hunt.strategy.searcher.impl.strategyFromPaper.RoutinesFromPaper.meanderThroughLines; /** + * Implements some alternatives to the RectangleScan-Routine used by the paper "Deterministic Treasure Hunt in the + * Plane with Angular Hints" from Bouchard et al. + * * @author Rank */ public class RectangleScanEnhanced { - MinimumRectangleStrategy strategy; + MinimumRectangleSearcher strategy; - public RectangleScanEnhanced(MinimumRectangleStrategy strategy) { + public RectangleScanEnhanced(MinimumRectangleSearcher strategy) { this.strategy = strategy; } /** * Meanders through the rectangle to scan it like the RectangleScan Routine from the paper but uses fewer distance * - * @param a - * @param b - * @param c - * @param d - * @param searchPath - * @return + * @param a a corner of the rectangle which is to be scanned, neighboring d and b + * @param b a corner of the rectangle which is to be scanned, neighboring a and c + * @param c a corner of the rectangle which is to be scanned, neighboring b and d + * @param d a corner of the rectangle which is to be scanned, neighboring c and a + * @param move the search-path the scan should be added to + * @return the resulting search-path */ public static SearchPath rectangleScanEnhanced(Coordinate a, Coordinate b, Coordinate c, Coordinate d, - SearchPath searchPath) { + SearchPath move) { if (a.distance(b) > a.distance(d)) { Coordinate temp = a; a = d; @@ -40,19 +43,27 @@ public static SearchPath rectangleScanEnhanced(Coordinate a, Coordinate b, Coord if (numberOfPointsInOneLine == 1) { Vector2D aToBHalf = new Vector2D(a, b); aToBHalf = aToBHalf.divide(2); - searchPath.addPoint(JTSUtils.createPoint(a.x + aToBHalf.getX() + move.addPoint(JTSUtils.createPoint(a.x + aToBHalf.getX() , a.y + aToBHalf.getY())); - searchPath.addPoint(JTSUtils.createPoint(d.x + aToBHalf.getX(), + move.addPoint(JTSUtils.createPoint(d.x + aToBHalf.getX(), d.y + aToBHalf.getY() )); - return searchPath; + return move; } Point[] a_k = lineOfPointsWithDistanceAtMostTwo(numberOfPointsInOneLine, a, b); Point[] b_k = lineOfPointsWithDistanceAtMostTwo(numberOfPointsInOneLine, d, c); - return meanderThroughLines(a_k, b_k, numberOfPointsInOneLine - 1, searchPath); + return meanderThroughLines(a_k, b_k, numberOfPointsInOneLine - 1, move); } + /** + * Returns a list of points on the line-segment from p1 to p2 + * The first point is in distance 1 to p1 and the last point is in distance 1 to p2. + * The other points go consecutive from the first to the last point and have equal distances to their neighboring + * points. There are numberOfPointsOnLine points in this returned list. + * + * @param numberOfPointsOnLine the number of points in the returned list + */ static private Point[] lineOfPointsWithDistanceAtMostTwo(int numberOfPointsOnLine, Coordinate p1, Coordinate p2) { if (numberOfPointsOnLine <= 1) { throw new IllegalArgumentException("numberOfPointsOnLine must be bigger than 1 but equals " + numberOfPointsOnLine); @@ -76,13 +87,25 @@ static private Point[] lineOfPointsWithDistanceAtMostTwo(int numberOfPointsOnLin return res; } - SearchPath rectangleScanMinimal(Coordinate rectangleCorner1, Coordinate rectangleCorner2, - Coordinate rectangleCorner3, Coordinate rectangleCorner4, SearchPath move) { + /** + * Replaces RectangleScan and does so by only scanning the minimum to the rectangle abcd parallel rectangle + * which covers all areas not seen and not excludable by hints, inside the current phase rectangle and the input rectangle. + * It then uses EnhancedRectangleScan to scan this rectangle. + * + * @param a a corner of the rectangle which is to be scanned, neighboring d and b + * @param b a corner of the rectangle which is to be scanned, neighboring a and c + * @param c a corner of the rectangle which is to be scanned, neighboring b and d + * @param d a corner of the rectangle which is to be scanned, neighboring c and a + * @param move the search-path the scan should be added to + * @return the resulting search-path + */ + SearchPath rectangleScanMinimal(Coordinate a, Coordinate b, + Coordinate c, Coordinate d, SearchPath move) { TransformForAxisParallelism transformerForRectangleAxisParallelism = - new TransformForAxisParallelism(new LineSegment(rectangleCorner1, rectangleCorner2)); + new TransformForAxisParallelism(new LineSegment(a, b)); strategy.updateVisitedPolygon(move); Polygon rectanglePolygon = JTSUtils.GEOMETRY_FACTORY.createPolygon(new Coordinate[]{ - rectangleCorner1, rectangleCorner2, rectangleCorner3, rectangleCorner4, rectangleCorner1}); + a, b, c, d, a}); Geometry newAreaToScan = strategy.getCurrentMultiPolygon().intersection(rectanglePolygon); diff --git a/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/TransformForAxisParallelism.java b/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/TransformForAxisParallelism.java index 378eba35..11e98e19 100644 --- a/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/TransformForAxisParallelism.java +++ b/src/main/java/com/treasure/hunt/strategy/searcher/impl/minimumRectangleStrategy/TransformForAxisParallelism.java @@ -9,6 +9,9 @@ import org.locationtech.jts.geom.util.AffineTransformation; /** + * For more information what internal and external refers to please look in the documentation of MinimumRectangleSearcher + * @see MinimumRectangleSearcher + * * @author Rank */ public class TransformForAxisParallelism { @@ -35,8 +38,6 @@ public TransformForAxisParallelism(HalfPlaneHint hint, Point internalCenterInExt /** * Creates a transformer where the line line in internal coordinate is parallel to the x-axis and * the point line.p0 is (0,0) in internal coordinates. - * - * @param line */ public TransformForAxisParallelism(LineSegment line) { this.internalCenterInExternalRepresentation = JTSUtils.GEOMETRY_FACTORY.createPoint(line.p0); diff --git a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/GeometricUtils.java b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/GeometricUtils.java index 67228831..07eeb707 100644 --- a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/GeometricUtils.java +++ b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/GeometricUtils.java @@ -41,12 +41,9 @@ public static SearchPath moveToCenterOfRectangle(Point P1, Point P2, Point P3, P } /** - * Coordinate of rect are rounded in the precision model grid and reordered so tha rect[0] is the upper left point, - * rect[1] is the upper right point, rect[2] is the bottom right point and rect[3] is the bottom left point. + * Coordinate of rect are reordered so tha rect[0] is the upper left point, rect[1] is the upper right point, + * rect[2] is the bottom right point and rect[3] is the bottom left point. * If the rectangle is not parallel to the x and y axis, an error is thrown. - * - * @param rect - * @return */ static Coordinate[] arrangeRectangle(Coordinate[] rect) { assertRectangle(rect); diff --git a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/LastHintBadSubroutine.java b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/LastHintBadSubroutine.java index 211f67b8..c9df0934 100644 --- a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/LastHintBadSubroutine.java +++ b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/LastHintBadSubroutine.java @@ -15,6 +15,9 @@ import static com.treasure.hunt.utils.JTSUtils.lineWayIntersection; /** + * Implements the "else"-part of the first if-condition in Algorithm 3 (Function ReduceRectangle(R)) + * in the paper "Deterministic Treasure Hunt in the Plane with Angular Hints" from Bouchard et al. + * * @author Rank */ public class LastHintBadSubroutine { @@ -134,10 +137,10 @@ private void initializeVariables(HalfPlaneHint currentHint, HalfPlaneHint lastBa * The function equals the "else"-part of the first if-condition in Algorithm 3 (Function ReduceRectangle(R)) * in the paper. * - * @param currentHint - * @param lastBadHint - * @param move - * @param changeABCD + * @param currentHint the hint gotten last by the calling strategy + * @param lastBadHint the hint gotten before the currentHint by the calling strategy + * @param move the move the steps get added to + * @param changeABCD true if ABCD should be changed, false if the strategy does so by itself * @return The move to scan various areas so that A,B,C and D can be updated to a smaller rectangle (or the treasure * is found) */ diff --git a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/RoutinesFromPaper.java b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/RoutinesFromPaper.java index d934551d..5ea22086 100644 --- a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/RoutinesFromPaper.java +++ b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/RoutinesFromPaper.java @@ -15,8 +15,8 @@ import static com.treasure.hunt.utils.JTSUtils.lineWayIntersection; /** - * For an explanation what each method does, it is recommended to look in the paper (Deterministic Treasure Hunt in the - * Plane with Angular Hints from Bouchard et al.). + * For an explanation what each method does, it is recommended to look in the paper ("Deterministic Treasure Hunt in the + * Plane with Angular Hints" from Bouchard et al.). * There the same symbols are used. * The functionality of rectangleScan is explained there on page 3. * Phi, rho, sigma and the basic-transformation are explained on pages 7ff. @@ -50,27 +50,20 @@ static private Point[] lineOfPointsWithDistanceOne(int k, Coordinate p1, Coordin * It adds the Points to searchPath so that the player sees all points in the rectangle ABCD. * Unlike the paper it does not add the point where the procedure started to the search-path. * - * @param A - * @param B - * @param C - * @param D + * @param A a corner of the rectangle which is to be scanned, neighboring d and b + * @param B a corner of the rectangle which is to be scanned, neighboring a and c + * @param C a corner of the rectangle which is to be scanned, neighboring b and d + * @param D a corner of the rectangle which is to be scanned, neighboring c and a * @param searchPath the searchPath the rectangle scan path gets added to * @param lastPosition when the searchPath is empty, it is assumed that this was the point where the procedure * rectangleScan got started and the searcher returns there afterwards - * @return + * @return the search-path with the added scan */ public static SearchPath rectangleScan(Point A, Point B, Point C, Point D, SearchPath searchPath, Point lastPosition) { return rectangleScan(A.getCoordinate(), B.getCoordinate(), C.getCoordinate(), D.getCoordinate(), searchPath, lastPosition); } /** - * @param A - * @param B - * @param C - * @param D - * @param searchPath - * @param lastPosition - * @return * @see RoutinesFromPaper#rectangleScan(Point, Point, Point, Point, SearchPath, Point) */ public static SearchPath rectangleScan(Coordinate A, Coordinate B, Coordinate C, Coordinate D, SearchPath searchPath, Point lastPosition) { diff --git a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/StatusMessages.java b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/StatusMessages.java index cb72b2b3..0e3edd11 100644 --- a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/StatusMessages.java +++ b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/StatusMessages.java @@ -9,6 +9,8 @@ import com.treasure.hunt.utils.JTSUtils; /** + * Gets used by StrategyFromPaper to output some useful status messages + * * @author Rank */ public class StatusMessages { @@ -43,9 +45,18 @@ public class StatusMessages { "For more information please look in the paper." ); + /** + * Can be used by lastHintBadSubroutine to add the description of the case used in it. + * It also adds a visualisation of L1'' when needed. + * + * @param move the search-path this status message should be added to + * @param basicTransformation the basicTransformation of the current configuration + * @param caseIndex the caseIndex as used in LastHintBadSubroutine.lastHintBadSubroutine + * @param lastHintBadSubroutine the calling class + */ static void addCaseDescriptionToStatus(SearchPath move, int basicTransformation, int caseIndex, LastHintBadSubroutine lastHintBadSubroutine) { - String[] transformedRectangle = getLettersOfTransformedRectangle(basicTransformation); + String[] transformedRectangle = getCharactersOfTransformedRectangle(basicTransformation); String statusMessage = "Let ABCD be the previous rectangle's corners, with\n" + "A being the corner on the top left,\n" + "B being the corner on the top right,\n" + @@ -159,17 +170,17 @@ private static void addL1DoubleApos(SearchPath move, LastHintBadSubroutine lastH GeometryType.L1_DOUBLE_APOS)); } - private static String[] getLettersOfTransformedRectangle(int basicTransformation) { - /** - * The rectangle got transformed by phi (with basicTransformation as index) - * The old rectangle gets called ABCD in the following, with A being the corner-point on the top left, - * B being the point on the top right, etc. - * In the following transformedRectangle[0] is the top left corner from the transformed rectangle - * (this could be A,B,C or D dependant on the basicTransformation's value) - * transformedRectangle[0] is the top left corner, - * transformedRectangle[1] is the top right corner, - * transformedRectangle[2] is the bottom right corner and - * transformedRectangle[3] is the bottom left corner. + private static String[] getCharactersOfTransformedRectangle(int basicTransformation) { + /* + The rectangle got transformed by phi (with basicTransformation as index) + The old rectangle gets called ABCD in the following, with A being the corner-point on the top left, + B being the point on the top right, etc. + In the following transformedRectangle[0] is the top left corner from the transformed rectangle + (this could be A,B,C or D dependant on the basicTransformation's value) + transformedRectangle[0] is the top left corner, + transformedRectangle[1] is the top right corner, + transformedRectangle[2] is the bottom right corner and + transformedRectangle[3] is the bottom left corner. */ String transformedRectangleString; String[] transformedRectangle; diff --git a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/StrategyFromPaper.java b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/StrategyFromPaper.java index 3a723f71..2c28365f 100644 --- a/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/StrategyFromPaper.java +++ b/src/main/java/com/treasure/hunt/strategy/searcher/impl/strategyFromPaper/StrategyFromPaper.java @@ -84,6 +84,9 @@ public void init(Point startPosition) { lastPosition = start; } + /** + * {@inheritDoc} + */ @Override public SearchPath move() { SearchPath move = new SearchPath(); @@ -95,6 +98,9 @@ public SearchPath move() { return (returnHandling(incrementPhase(move))); } + /** + * {@inheritDoc} + */ @Override public SearchPath move(HalfPlaneHint hint) { previousHint = currentHint; @@ -138,7 +144,8 @@ public SearchPath move(HalfPlaneHint hint) { if (rectangleNotLargeEnough()) { previousHintQuality = HintQuality.none; move.getStatusMessageItemsToBeAdded().add(new StatusMessageItem(StatusMessageType.PREVIOUS_HINT_QUALITY, - "none, because the previous rectangle was small enough to be scanned directly.")); + "none, because the previous rectangle was small enough to be scanned directly.\n " + + "The phase got incremented.")); return returnHandling(incrementPhase(move)); } @@ -192,9 +199,6 @@ protected boolean rectangleNotLargeEnough() { * This method is used to visualize the current phases rectangle and the current search rectangle. * Adds their values to move * - * @param move - * @param currentRectanglePoints - * @param phaseRectanglePoints * @return the input with the visualisations of the current phase and the search rectangle added */ protected SearchPath addState(SearchPath move, Coordinate[] currentRectanglePoints, Coordinate[] phaseRectanglePoints) { @@ -259,14 +263,6 @@ protected SearchPath returnHandling(SearchPath move) { * If the hint-line goes through AD and BC, the biggest axis parallel-rectangle which * lies in ABCD and where the treasure could be located due to the information gained by the hint, is returned. * Otherwise the return value is null. - * - * @param A - * @param B - * @param C - * @param D - * @param hint - * @param hintLine - * @return */ protected Point[] splitRectangleHorizontally(Point A, Point B, Point C, Point D, HalfPlaneHint hint, LineSegment hintLine) { @@ -326,13 +322,6 @@ protected Point[] splitRectangleHorizontally(Point A, Point B, Point C, Point D, /** * A specific rectangle scanner for this strategy, in case of StrategyFromPaper, the standard rectangleScanSpecificForStrategy from * RoutinesFromPaper is used (this method is required for the MinimumRectangleStrategy which inherits from this class.) - * - * @param rectangleCorner1 - * @param rectangleCorner2 - * @param rectangleCorner3 - * @param rectangleCorner4 - * @param move - * @return */ protected SearchPath specificRectangleScan(Coordinate rectangleCorner1, Coordinate rectangleCorner2, Coordinate rectangleCorner3, Coordinate rectangleCorner4, SearchPath move) { @@ -342,13 +331,6 @@ protected SearchPath specificRectangleScan(Coordinate rectangleCorner1, Coordina /** * A specific rectangle scanner for this strategy, in case of StrategyFromPaper, the standard rectangleScanSpecificForStrategy from * RoutinesFromPaper is used (this method is required for the MinimumRectangleStrategy which inherits from this class.) - * - * @param rectangleCorner1 - * @param rectangleCorner2 - * @param rectangleCorner3 - * @param rectangleCorner4 - * @param move - * @return */ protected SearchPath specificRectangleScan(Point rectangleCorner1, Point rectangleCorner2, Point rectangleCorner3, Point rectangleCorner4, SearchPath move) { @@ -362,14 +344,6 @@ protected SearchPath specificRectangleScan(Point rectangleCorner1, Point rectang * If the hint-line goes through AB and CD, the biggest axis-parallel rectangle which * lies in ABCD and where the treasure could be located due to the information gained by the hint, is returned. * Otherwise the return value is null. - * - * @param A - * @param B - * @param C - * @param D - * @param hint - * @param hintLine - * @return */ protected Point[] splitRectangleVertically(Point A, Point B, Point C, Point D, HalfPlaneHint hint, LineSegment hintLine) { @@ -421,7 +395,6 @@ protected Point[] splitRectangleVertically(Point A, Point B, Point C, Point D, H * Increments the phase-field and updates ABCD accordingly. * Then adds the step to the center of the new rectangle ABCD to move. * - * @param move * @return the parameter move with the center of the new ABCD added */ private SearchPath incrementPhase(SearchPath move) { @@ -440,8 +413,6 @@ private SearchPath incrementPhase(SearchPath move) { /** * Returnes the rectangle of the current phase, by using the current phase index (equates to j in the paper or * the phase-field in this implementation) - * - * @return */ protected Coordinate[] currentPhaseRectangle() { return phaseRectangle(phase);