Docs: Add JavaDoc

CityDoctorParent/Extensions/CityDoctorGUI/src/main/java/de/hft/stuttgart/citydoctor2/gui/HighlightController.java

@@ -70,67 +70,108 @@ public class HighlightController {
 	}
 
 	/**
-	 * Adds a highlight
-	 * @param p
-	 * @param currentTriGeom
+	 * Clears existing highlights and adds a highlight geometry to a {@link TriangulatedGeometry}.
+	 * @param p a polygon to highlight
+	 * @param triGeom the TriangulatedGeometry
 	 */
-	public void highlight(Polygon p, TriangulatedGeometry currentTriGeom) {
+	public void highlight(Polygon p, TriangulatedGeometry triGeom) {
 		clearHighlights();
-		addPolygonHighlight(p, currentTriGeom, Color.RED, Color.BLUE, Color.ORANGE);
+		addPolygonHighlight(p, triGeom, Color.RED, Color.BLUE, Color.ORANGE);
 	}
-	
-	public void highlight(LinearRing ring, TriangulatedGeometry currentTriGeom) {
+
+	/**
+	 * Clears existing highlights and adds a highlight geometry to a {@link TriangulatedGeometry}.
+	 * @param ring a linear-ring to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlight(LinearRing ring, TriangulatedGeometry triGeom) {
 		clearHighlights();
 		if (ring.getType() == LinearRingType.EXTERIOR) {
-			addRingHighlight(ring, currentTriGeom, Color.RED, Color.ORANGE);
+			addRingHighlight(ring, triGeom, Color.RED, Color.ORANGE);
 		} else {
-			addRingHighlight(ring, currentTriGeom, Color.BLUE, Color.ORANGE);
+			addRingHighlight(ring, triGeom, Color.BLUE, Color.ORANGE);
 		}
 	}
 
-	public void highlight(Edge e, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Clears existing highlights and adds a highlight geometry to a {@link TriangulatedGeometry}.
+	 * @param e an edge to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlight(Edge e, TriangulatedGeometry triGeom) {
 		clearHighlights();
-		addEdgeHighlight(e, currentTriGeom);
+		addEdgeHighlight(e, triGeom, Color.RED, Color.ORANGE);
 	}
 
-	public void highlight(Vertex v, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Clears existing highlights and adds a highlight geometry to a {@link TriangulatedGeometry}.
+	 * @param v a vertex to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlight(Vertex v, TriangulatedGeometry triGeom) {
 		clearHighlights();
-		addVertexHighlight(v, currentTriGeom, Color.RED);
+		addVertexHighlight(v, triGeom, Color.RED);
 	}
 
-	public void highlight(Triangle3d t, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Clears existing highlights and adds a highlight geometry to a {@link TriangulatedGeometry}.
+	 * @param t a triangle to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlight(Triangle3d t, TriangulatedGeometry triGeom) {
 		clearHighlights();
-		addSegmentHighlight(t.getP1(), t.getP2(), currentTriGeom.getMovedBy(), Color.ORANGE);
-		addSegmentHighlight(t.getP2(), t.getP3(), currentTriGeom.getMovedBy(), Color.ORANGE);
-		addSegmentHighlight(t.getP3(), t.getP1(), currentTriGeom.getMovedBy(), Color.ORANGE);
+		addSegmentHighlight(t.getP1(), t.getP2(), triGeom.getMovedBy(), Color.ORANGE);
+		addSegmentHighlight(t.getP2(), t.getP3(), triGeom.getMovedBy(), Color.ORANGE);
+		addSegmentHighlight(t.getP3(), t.getP1(), triGeom.getMovedBy(), Color.ORANGE);
 	}
 
-	public void highlightRings(List<LinearRing> rings, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Clears existing highlights and adds a highlighted collection of linear-rings to a {@link TriangulatedGeometry}.
+	 * @param rings a collection of linear-rings to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlightRings(Collection<LinearRing> rings, TriangulatedGeometry triGeom) {
 		clearHighlights();
 		for (LinearRing lr : rings) {
 			if (lr.getType() == LinearRingType.EXTERIOR) {
-				addRingHighlight(lr, currentTriGeom, Color.RED, Color.ORANGE);
+				addRingHighlight(lr, triGeom, Color.RED, Color.ORANGE);
 			} else {
-				addRingHighlight(lr, currentTriGeom, Color.BLUE, Color.ORANGE);
+				addRingHighlight(lr, triGeom, Color.BLUE, Color.ORANGE);
 			}
 		}
 	}
 
-	public void highlightEdges(List<Edge> errorEdges, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Clears existing highlights and adds a highlighted collection of edges to a {@link TriangulatedGeometry}.
+	 * @param edges a collection of edges to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlightEdges(Collection<Edge> edges, TriangulatedGeometry triGeom) {
 		clearHighlights();
-		for (Edge e : errorEdges) {
-			addEdgeHighlight(e, currentTriGeom);
+		for (Edge e : edges) {
+			addEdgeHighlight(e, triGeom, Color.RED, Color.ORANGE);
 		}
 	}
 
-	public void highlightPolygons(Collection<Polygon> polygons, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Clears existing highlights and adds a highlighted collection of polygons to a {@link TriangulatedGeometry}.
+	 * @param polygons a collection of edges to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlightPolygons(Collection<Polygon> polygons, TriangulatedGeometry triGeom) {
 		clearHighlights();
 		for (Polygon p : polygons) {
-			addPolygonHighlight(p, currentTriGeom);
+			addPolygonHighlight(p, triGeom);
 		}
 	}
 
-	public void highlightPolygonClusters(List<List<Polygon>> components, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Clears existing highlights and highlights a list of polygon clusters in a {@link TriangulatedGeometry}. Cycles
+	 * between three vertex color-schemes to distinguish the clusters.
+	 * @param components a list of polygon-lists representing clusters
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlightPolygonClusters(List<List<Polygon>> components, TriangulatedGeometry triGeom) {
 		clearHighlights();
 		for (int i = 0; i < components.size(); i++) {
 			Color extColor;
@@ -151,16 +192,23 @@ public class HighlightController {
 			// select some color pairs for exterior and inner rings
 			List<Polygon> component = components.get(i);
 			for (Polygon p : component) {
-				addPolygonHighlight(p, currentTriGeom, extColor, intColor, Color.ORANGE);
+				addPolygonHighlight(p, triGeom, extColor, intColor, Color.ORANGE);
 			}
 		}
 	}
 
-	private void addRingHighlight(LinearRing ring, TriangulatedGeometry currentTriGeom, Color pointColor, Color edgeColor) {
-		if (currentTriGeom == null || ring == null) {
+	/**
+	 * Adds a linear-ring highlight to a {@link TriangulatedGeometry}.
+	 * @param ring the ring to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 * @param pointColor color for the vertex highlights
+	 * @param edgeColor color for the edge highlights
+	 */
+	private void addRingHighlight(LinearRing ring, TriangulatedGeometry triGeom, Color pointColor, Color edgeColor) {
+		if (triGeom == null || ring == null) {
 			return;
 		}
-		Vector3d movedBy = currentTriGeom.getMovedBy();
+		Vector3d movedBy = triGeom.getMovedBy();
 		for (Vertex v : ring.getVertices()) {
 			addPointHighlight(movedBy, v, pointColor);
 		}
@@ -171,36 +219,61 @@ public class HighlightController {
 		}
 	}
 
-	private void addPolygonHighlight(Polygon p, TriangulatedGeometry currentTriGeom, Color extColor, Color intColor, Color edgeColor) {
-		if (currentTriGeom == null || p == null) {
+	/**
+	 * Adds a polygon highlight to a {@link TriangulatedGeometry}.
+	 * @param p the polygon to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 * @param extColor color for the vertex highlights of the exterior ring
+	 * @param intColor color for the vertex highlights of the interior rings
+	 * @param edgeColor color for the edge highlights
+	 */
+	private void addPolygonHighlight(Polygon p, TriangulatedGeometry triGeom, Color extColor, Color intColor, Color edgeColor) {
+		if (triGeom == null || p == null) {
 			return;
 		}
-		addRingHighlight(p.getExteriorRing(), currentTriGeom, extColor, edgeColor);
+		addRingHighlight(p.getExteriorRing(), triGeom, extColor, edgeColor);
 		for (LinearRing intRing : p.getInnerRings()) {
-			addRingHighlight(intRing, currentTriGeom, intColor, edgeColor);
+			addRingHighlight(intRing, triGeom, intColor, edgeColor);
 		}
 	}
 
-
-	private void addEdgeHighlight(Edge e, TriangulatedGeometry currentTriGeom) {
-		if (currentTriGeom == null || e == null) {
+	/**
+	 * Adds an edge highlight to a {@link TriangulatedGeometry}.
+	 * @param e the polygon to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 * @param pointColor color for the vertex highlights
+	 * @param edgeColor color for the edge highlight
+	 */
+	private void addEdgeHighlight(Edge e, TriangulatedGeometry triGeom, Color pointColor, Color edgeColor) {
+		if (triGeom == null || e == null) {
 			return;
 		}
-		Vector3d movedBy = currentTriGeom.getMovedBy();
-		addSegmentHighlight(e.getFrom(), e.getTo(), movedBy, Color.ORANGE);
-		addPointHighlight(movedBy, e.getFrom(), Color.RED);
-		addPointHighlight(movedBy, e.getTo(), Color.RED);
+		Vector3d movedBy = triGeom.getMovedBy();
+		addSegmentHighlight(e.getFrom(), e.getTo(), movedBy, edgeColor);
+		addPointHighlight(movedBy, e.getFrom(), pointColor);
+		addPointHighlight(movedBy, e.getTo(), pointColor);
 	}
 
-
-	public void addVertexHighlight(Vertex v, TriangulatedGeometry currentTriGeom, Color c) {
-		if (currentTriGeom == null || v == null) {
+	/**
+	 * Adds a vertex highlight to a {@link TriangulatedGeometry}.
+	 * @param v the polygon to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 * @param color color for the highlight
+	 */
+	public void addVertexHighlight(Vertex v, TriangulatedGeometry triGeom, Color color) {
+		if (triGeom == null || v == null) {
 			return;
 		}
-		Vector3d movedBy = currentTriGeom.getMovedBy();
-		addPointHighlight(movedBy, v, c);
+		Vector3d movedBy = triGeom.getMovedBy();
+		addPointHighlight(movedBy, v, color);
 	}
-	
+
+	/**
+	 * Creates a colored point in the JavaFX scenegraph at the relative position of a Vertex within a {@link TriangulatedGeometry}.
+	 * @param movedBy offset vector of the origin of the TriangulatedGeometry
+	 * @param v the vertex to highlight
+	 * @param color color for the highlight
+	 */
 	private void addPointHighlight(Vector3d movedBy, Vertex v, Color color) {
 		Sphere sp = new Sphere(0.5);
 		sp.setMaterial(new PhongMaterial(color));
@@ -216,6 +289,13 @@ public class HighlightController {
 		points.getChildren().add(sp);
 	}
 
+	/**
+	 * Creates a colored segment in the JavaFX scenegraph at the relative position of an edge within a {@link TriangulatedGeometry}.
+	 * @param v1 start point of the edge
+	 * @param v2 end point of the edge
+	 * @param movedBy offset vector of the origin of the TriangulatedGeometry
+	 * @param color color for the highlight
+	 */
 	private void addSegmentHighlight(Vector3d v1, Vector3d v2, Vector3d movedBy, Color color) {
 		Point3D origin = new Point3D(v1.getX() - movedBy.getX(), v1.getY() - movedBy.getY(),
 				v1.getZ() - movedBy.getZ());
@@ -239,46 +319,91 @@ public class HighlightController {
 		edges.getChildren().add(cy);
 	}
 
-	public void addCandidateSkeletonHighlight(CityObject candidate, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Adds a gray wireframe highlight of a CityObject to a {@link TriangulatedGeometry} to allow for unobtrusive
+	 * display of candidate features in TopologicalErrors.
+	 * @param candidate the candidate feature
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void addCandidateSkeletonHighlight(CityObject candidate, TriangulatedGeometry triGeom) {
 		candidate.accept(new CheckableUtilsVisitor() {
 			@Override
 			public void check(Geometry geom) {
 				geom.getPolygons().forEach(p -> {
-					addPolygonHighlight(p, currentTriGeom, Color.GRAY, Color.GRAY, Color.DARKGRAY);
+					addPolygonHighlight(p, triGeom, Color.GRAY, Color.GRAY, Color.DARKGRAY);
 				});
 			}
 		});
 	}
 
-	public void addPolygonHighlight(Polygon p, TriangulatedGeometry currentTriGeom) {
-		addPolygonHighlight(p, currentTriGeom, Color.RED, Color.BLUE, Color.ORANGE);
+	/**
+	 * Adds a polygon highlight to a {@link TriangulatedGeometry}.
+	 * @param p the polygon to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void addPolygonHighlight(Polygon p, TriangulatedGeometry triGeom) {
+		addPolygonHighlight(p, triGeom, Color.RED, Color.BLUE, Color.ORANGE);
 	}
 
-	public void addCandidateHighlight(Polygon p, TriangulatedGeometry currentTriGeom) {
-		addPolygonHighlight(p, currentTriGeom, Color.DARKRED, Color.NAVY, Color.ROSYBROWN);
+	/**
+	 * Adds a polygon highlight to a {@link TriangulatedGeometry}, using darker colors to differentiate candidate polygons.
+	 * @param p the polygon to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void addCandidateHighlight(Polygon p, TriangulatedGeometry triGeom) {
+		addPolygonHighlight(p, triGeom, Color.DARKRED, Color.NAVY, Color.ROSYBROWN);
 	}
 
-	public void addCandidateHighlight(Collection<Polygon> polys, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Adds highlights for a collection of polygons to a {@link TriangulatedGeometry}, using darker colors to
+	 * differentiate candidate polygons.
+	 * @param polys the polygons to highlight
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void addCandidateHighlight(Collection<Polygon> polys, TriangulatedGeometry triGeom) {
 		for (Polygon p : polys) {
-			addCandidateHighlight(p, currentTriGeom);
+			addCandidateHighlight(p, triGeom);
 		}
 	}
 
-	public void highlightGeometryCollisions(CollisionRecord collRecord, TriangulatedGeometry currentTriGeom) {
+	/**
+	 * Clears existing highlights and highlights polygons within a {@link TriangulatedGeometry}, which were found to be
+	 * colliding by the feature collision check. Darker colors will be used for differentiating the candidate polygons.
+	 *
+	 * @param collRecord the collision record of the check
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlightGeometryCollisions(CollisionRecord collRecord, TriangulatedGeometry triGeom) {
 		Map<Polygon, List<Polygon>> collisionMap = collRecord.collisionMap();
 		Set<Polygon> collidingPolys = collisionMap.values().stream().flatMap(List::stream).collect(Collectors.toSet());
-		highlightTopoPolygonGroups(collisionMap.keySet(), collidingPolys, currentTriGeom);
+		highlightTopoPolygonGroups(collisionMap.keySet(), collidingPolys, triGeom);
 	}
 
-	public void highlightTopoPolygonPair(Polygon subject, Polygon candidate,TriangulatedGeometry currentTriGeom) {
-		highlight(subject, currentTriGeom);
-		addCandidateHighlight(candidate, currentTriGeom);
+	/**
+	 * Clears existing highlights and highlight a polygon pair within a {@link TriangulatedGeometry}, which were found to
+	 * be conflicting a topological requirement. Darker colors will be used for differentiating the candidate polygon.
+	 *
+	 * @param subject the subject polygon
+	 * @param candidate the candidate polygon
+	 * @param triGeom the TriangulatedGeometry
+	 */
+	public void highlightTopoPolygonPair(Polygon subject, Polygon candidate,TriangulatedGeometry triGeom) {
+		highlight(subject, triGeom);
+		addCandidateHighlight(candidate, triGeom);
 	}
 
+	/**
+	 * Clears existing highlights and highlights polygons {@link TriangulatedGeometry} which were found to
+	 * be conflicting a topological requirement. Darker colors will be used for differentiating the candidate polygons.
+	 *
+	 * @param subjectPolys the subject polygons
+	 * @param candidatePolys the candidate polygons
+	 * @param triGeom the TriangulatedGeometry
+	 */
 	public void highlightTopoPolygonGroups(Collection<Polygon> subjectPolys, Collection<Polygon> candidatePolys,
-										   TriangulatedGeometry currentTriGeom) {
-		highlightPolygons(subjectPolys, currentTriGeom);
-		addCandidateHighlight(candidatePolys, currentTriGeom);
+										   TriangulatedGeometry triGeom) {
+		highlightPolygons(subjectPolys, triGeom);
+		addCandidateHighlight(candidatePolys, triGeom);
 	}