diff --git a/src/main/org/insa/algo/datastructures/BinaryHeap.java b/src/main/org/insa/algo/datastructures/BinaryHeap.java index a987cd9..55c1a5b 100644 --- a/src/main/org/insa/algo/datastructures/BinaryHeap.java +++ b/src/main/org/insa/algo/datastructures/BinaryHeap.java @@ -9,244 +9,205 @@ package org.insa.algo.datastructures; -import java.util.* ; +import java.util.ArrayList; /** - * Implements a binary heap. - * Note that all "matching" is based on the compareTo method. + * Implements a binary heap. Note that all "matching" is based on the compareTo + * method. + * * @author Mark Allen Weiss * @author DLB */ public class BinaryHeap> { - private int currentSize; // Number of elements in heap + private int currentSize; // Number of elements in heap - // Java genericity does not work with arrays. - // We have to use an ArrayList - private ArrayList array; // The heap array + // Java genericity does not work with arrays. + // We have to use an ArrayList + private ArrayList array; // The heap array - /** - * Construct the binary heap. - */ - public BinaryHeap() { - this.currentSize = 0; - this.array = new ArrayList() ; - } + /** + * Construct the binary heap. + */ + public BinaryHeap() { + this.currentSize = 0; + this.array = new ArrayList(); + } - // Constructor used for debug. - public BinaryHeap(BinaryHeap heap) { - this.currentSize = heap.currentSize ; - this.array = new ArrayList(heap.array) ; - } + // Constructor used for debug. + public BinaryHeap(BinaryHeap heap) { + this.currentSize = heap.currentSize; + this.array = new ArrayList(heap.array); + } - // Sets an element in the array - private void arraySet(int index, E value) { - if (index == this.array.size()) { - this.array.add(value) ; - } - else { - this.array.set(index, value) ; - } - } + // Sets an element in the array + private void arraySet(int index, E value) { + if (index == this.array.size()) { + this.array.add(value); + } + else { + this.array.set(index, value); + } + } - /** - * Test if the heap is logically empty. - * @return true if empty, false otherwise. - */ - public boolean isEmpty() { return this.currentSize == 0; } + /** + * Test if the heap is logically empty. + * + * @return true if empty, false otherwise. + */ + public boolean isEmpty() { + return this.currentSize == 0; + } - /** - * Returns size. - * @return current size. - */ - public int size() { return this.currentSize; } + /** + * Returns size. + * + * @return current size. + */ + public int size() { + return this.currentSize; + } + /** + * Returns index of parent. + */ + private int index_parent(int index) { + return (index - 1) / 2; + } - /** - * Returns index of parent. - */ - private int index_parent(int index) { - return (index - 1) / 2 ; - } + /** + * Returns index of left child. + */ + private int index_left(int index) { + return index * 2 + 1; + } - /** - * Returns index of left child. - */ - private int index_left(int index) { - return index * 2 + 1 ; - } + /** + * Insert into the heap. + * + * @param x the item to insert. + */ + public void insert(E x) { + int index = this.currentSize++; + this.arraySet(index, x); + this.percolateUp(index); + } - /** - * Insert into the heap. - * @param x the item to insert. - */ - public void insert(E x) { - int index = this.currentSize++ ; - this.arraySet(index, x) ; - this.percolateUp(index) ; - } + /** + * Internal method to percolate up in the heap. + * + * @param index the index at which the percolate begins. + */ + private void percolateUp(int index) { + E x = this.array.get(index); - /** - * Internal method to percolate up in the heap. - * @param index the index at which the percolate begins. - */ - private void percolateUp(int index) { - E x = this.array.get(index) ; + for (; index > 0 + && x.compareTo(this.array.get(index_parent(index))) < 0; index = index_parent( + index)) { + E moving_val = this.array.get(index_parent(index)); + this.arraySet(index, moving_val); + } - for( ; index > 0 && x.compareTo(this.array.get(index_parent(index)) ) < 0; index = index_parent(index) ) { - E moving_val = this.array.get(index_parent(index)) ; - this.arraySet(index, moving_val) ; - } + this.arraySet(index, x); + } - this.arraySet(index, x) ; - } + /** + * Internal method to percolate down in the heap. + * + * @param index the index at which the percolate begins. + */ + private void percolateDown(int index) { + int ileft = index_left(index); + int iright = ileft + 1; - /** - * Internal method to percolate down in the heap. - * @param index the index at which the percolate begins. - */ - private void percolateDown(int index) { - int ileft = index_left(index) ; - int iright = ileft + 1 ; + if (ileft < this.currentSize) { + E current = this.array.get(index); + E left = this.array.get(ileft); + boolean hasRight = iright < this.currentSize; + E right = (hasRight) ? this.array.get(iright) : null; - if (ileft < this.currentSize) { - E current = this.array.get(index) ; - E left = this.array.get(ileft) ; - boolean hasRight = iright < this.currentSize ; - E right = (hasRight)?this.array.get(iright):null ; + if (!hasRight || left.compareTo(right) < 0) { + // Left is smaller + if (left.compareTo(current) < 0) { + this.arraySet(index, left); + this.arraySet(ileft, current); + this.percolateDown(ileft); + } + } + else { + // Right is smaller + if (right.compareTo(current) < 0) { + this.arraySet(index, right); + this.arraySet(iright, current); + this.percolateDown(iright); + } + } + } + } - if (!hasRight || left.compareTo(right) < 0) { - // Left is smaller - if (left.compareTo(current) < 0) { - this.arraySet(index, left) ; - this.arraySet(ileft, current) ; - this.percolateDown( ileft ) ; - } - } - else { - // Right is smaller - if (right.compareTo(current) < 0) { - this.arraySet(index, right) ; - this.arraySet(iright, current) ; - this.percolateDown( iright ) ; - } - } - } - } + /** + * Find the smallest item in the heap. + * + * @return the smallest item in the heap. + * + * @throws RuntimeException if this heap is empty. + */ + public E findMin() throws RuntimeException { + if (isEmpty()) + throw new RuntimeException("Empty binary heap"); + return this.array.get(0); + } - /** - * Find the smallest item in the heap. - * @return the smallest item. - * @throws Exception if empty. - */ - public E findMin( ) { - if( isEmpty() ) - throw new RuntimeException( "Empty binary heap" ); - return this.array.get(0); - } + /** + * Remove the smallest item from the heap. + * + * @return the smallest item in the heap. + * + * @throws RuntimeException if this heap is empty. + */ + public E deleteMin() throws RuntimeException { + E minItem = findMin(); + E lastItem = this.array.get(--this.currentSize); + this.arraySet(0, lastItem); + this.percolateDown(0); + return minItem; + } - /** - * Remove the smallest item from the heap. - * @return the smallest item. - * @throws Exception if empty. - */ - public E deleteMin( ) { - E minItem = findMin( ); - E lastItem = this.array.get(--this.currentSize) ; - this.arraySet(0, lastItem) ; - this.percolateDown( 0 ); - return minItem; - } + /** + * Prints the heap + */ + public void print() { + System.out.println(); + System.out.println("======== HEAP (size = " + this.currentSize + ") ========"); + System.out.println(); - /** - * Prints the heap - */ - public void print() { - System.out.println() ; - System.out.println("======== HEAP (size = " + this.currentSize + ") ========") ; - System.out.println() ; + for (int i = 0; i < this.currentSize; i++) { + System.out.println(this.array.get(i).toString()); + } - for (int i = 0 ; i < this.currentSize ; i++) { - System.out.println(this.array.get(i).toString()) ; - } + System.out.println(); + System.out.println("-------- End of heap --------"); + System.out.println(); + } - System.out.println() ; - System.out.println("-------- End of heap --------") ; - System.out.println() ; - } + /** + * Prints the elements of the heap according to their respective order. + */ + public void printSorted() { - /** - * Prints the elements of the heap according to their respective order. - */ - public void printSorted() { + BinaryHeap copy = new BinaryHeap(this); - BinaryHeap copy = new BinaryHeap(this) ; + System.out.println(); + System.out.println("======== Sorted HEAP (size = " + this.currentSize + ") ========"); + System.out.println(); - System.out.println() ; - System.out.println("======== Sorted HEAP (size = " + this.currentSize + ") ========") ; - System.out.println() ; + while (!copy.isEmpty()) { + System.out.println(copy.deleteMin()); + } - while (!copy.isEmpty()) { - System.out.println(copy.deleteMin()) ; - } + System.out.println(); + System.out.println("-------- End of heap --------"); + System.out.println(); + } - System.out.println() ; - System.out.println("-------- End of heap --------") ; - System.out.println() ; - } - - - - // Test program : compare with the reference implementation PriorityQueue. - public static void main(String [] args) { - BinaryHeap heap = new BinaryHeap() ; - PriorityQueue queue = new PriorityQueue() ; - - int count = 0 ; - int blocksize = 10000 ; - - System.out.println("Interrupt to stop the test.") ; - - while (true) { - - // Insert up to blocksize elements - int nb_insert = (int)(Math.random() * (blocksize + 1)) ; - - for (int i = 0 ; i < nb_insert ; i++) { - Integer obj = new Integer(i) ; - heap.insert(obj) ; - queue.add(obj) ; - } - - // Remove up to blocksize elements - int nb_remove = (int)(Math.random() * blocksize * 1.1) ; - - if (nb_remove > queue.size()) { - nb_remove = queue.size() ; - } - - for (int i = 0 ; i < nb_remove ; i++) { - - int removed1 = queue.poll().intValue() ; - int removed2 = heap.deleteMin().intValue() ; - - if (removed1 != removed2) { - System.out.println("Ouch : expected " + removed1 + " .. but got " + removed2) ; - System.exit(1) ; - } - } - - if (heap.size() != queue.size()) { - System.out.println("Ouch : heap size = " + heap.size() + " queue size = " + queue.size() ) ; - System.exit(1) ; - } - - count += nb_remove ; - - if (count > 1000000) { - System.out.println("" + count + " items successfully compared. Heap size : " + heap.size()) ; - count = 0 ; - } - } - } } diff --git a/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentObserver.java b/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentObserver.java deleted file mode 100644 index 69f1a01..0000000 --- a/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentObserver.java +++ /dev/null @@ -1,30 +0,0 @@ -package org.insa.algo.strongconnectivity; - -import java.util.ArrayList; - -import org.insa.graph.Node; - -public interface StronglyConnectedComponentObserver { - - /** - * Notify that the algorithm is entering a new component. - * - * @param curNode Starting node for the component. - */ - public void notifyStartComponent(Node curNode); - - /** - * Notify that a new node has been found for the current component. - * - * @param node New node found for the current component. - */ - public void notifyNewNodeInComponent(Node node); - - /** - * Notify that the algorithm has computed a new component. - * - * @param nodes List of nodes in the component. - */ - public void notifyEndComponent(ArrayList nodes); - -} diff --git a/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentsAlgorithm.java b/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentsAlgorithm.java deleted file mode 100644 index 2ddfcd1..0000000 --- a/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentsAlgorithm.java +++ /dev/null @@ -1,25 +0,0 @@ -package org.insa.algo.strongconnectivity; - -import org.insa.algo.AbstractAlgorithm; - -public abstract class StronglyConnectedComponentsAlgorithm - extends AbstractAlgorithm { - - /** - * @param data - */ - public StronglyConnectedComponentsAlgorithm(StronglyConnectedComponentsData data) { - super(data); - } - - @Override - public StronglyConnectedComponentsSolution run() { - return (StronglyConnectedComponentsSolution) super.run(); - } - - @Override - public StronglyConnectedComponentsData getInputData() { - return (StronglyConnectedComponentsData) super.getInputData(); - } - -} diff --git a/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentsData.java b/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentsData.java deleted file mode 100644 index a42ab71..0000000 --- a/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentsData.java +++ /dev/null @@ -1,16 +0,0 @@ -package org.insa.algo.strongconnectivity; - -import org.insa.algo.AbstractInputData; -import org.insa.graph.Graph; - -public class StronglyConnectedComponentsData extends AbstractInputData { - - /** - * - * @param graph - */ - public StronglyConnectedComponentsData(Graph graph) { - super(graph); - } - -} diff --git a/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentsSolution.java b/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentsSolution.java deleted file mode 100644 index cde68f2..0000000 --- a/src/main/org/insa/algo/strongconnectivity/StronglyConnectedComponentsSolution.java +++ /dev/null @@ -1,35 +0,0 @@ -package org.insa.algo.strongconnectivity; - -import java.util.ArrayList; - -import org.insa.algo.AbstractSolution; -import org.insa.graph.Node; - -public class StronglyConnectedComponentsSolution extends AbstractSolution { - - // Components - private ArrayList> components; - - protected StronglyConnectedComponentsSolution(StronglyConnectedComponentsData data) { - super(data); - } - - protected StronglyConnectedComponentsSolution(StronglyConnectedComponentsData data, - Status status, ArrayList> components) { - super(data, status); - this.components = components; - } - - @Override - public StronglyConnectedComponentsData getInputData() { - return (StronglyConnectedComponentsData) super.getInputData(); - } - - /** - * @return Components of the solution, if any. - */ - public ArrayList> getComponents() { - return components; - } - -} diff --git a/src/main/org/insa/algo/strongconnectivity/TarjanAlgorithm.java b/src/main/org/insa/algo/strongconnectivity/TarjanAlgorithm.java deleted file mode 100644 index fc2363b..0000000 --- a/src/main/org/insa/algo/strongconnectivity/TarjanAlgorithm.java +++ /dev/null @@ -1,144 +0,0 @@ -package org.insa.algo.strongconnectivity; - -import java.util.ArrayList; -import java.util.Arrays; -import java.util.Stack; - -import org.insa.algo.AbstractSolution.Status; -import org.insa.graph.Arc; -import org.insa.graph.Graph; -import org.insa.graph.Node; - -public class TarjanAlgorithm extends StronglyConnectedComponentsAlgorithm { - - private final static int UNDEFINED = -1; - - // Stack of nodes and flags. - private Stack stack; - private boolean[] inStack; - - // Current index. - private int index; - - // Information of nodes - private int[] indexes; - private int[] lowlink; - - // Array of strongly connected components - ArrayList> components; - - public TarjanAlgorithm(StronglyConnectedComponentsData data) { - super(data); - } - - /** - * Push the given node to the stack. - * - * @param node - */ - protected void pushNode(Node node) { - stack.push(node); - inStack[node.getId()] = true; - } - - /** - * Pop and return a node from the stack. - * - * @return Node popped from the stack - */ - protected Node popNode() { - Node top = stack.pop(); - inStack[top.getId()] = false; - return top; - } - - /** - * Check if the given node is in the stack. - * - * @param node - * - * @return true if the given node is in the stack, false otherwize. - */ - protected boolean isInStack(Node node) { - return inStack[node.getId()]; - } - - /** - * Find the strong component containing the given node. - * - * @param node - * - * @return The strong component containing the given node. - */ - protected void findAndAddStrongComponent(Node v) { - - // Update node info, index and push the node. - indexes[v.getId()] = index; - lowlink[v.getId()] = index; - index += 1; - pushNode(v); - - for (Arc a: v.getSuccessors()) { - Node w = a.getDestination(); - if (!hasBeenVisited(w)) { - findAndAddStrongComponent(w); - lowlink[v.getId()] = Math.min(lowlink[v.getId()], lowlink[w.getId()]); - } - else if (isInStack(w)) { - lowlink[v.getId()] = Math.min(lowlink[v.getId()], indexes[w.getId()]); - } - } - - // Compute the component (if any) - if (lowlink[v.getId()] == indexes[v.getId()]) { - ArrayList component = new ArrayList(); - Node w; - do { - w = popNode(); - component.add(w); - } while (!w.equals(v)); - components.add(component); - System.out.println("Size of the stack: " + stack.size()); - } - - } - - /** - * Check if the given node has not been visited yet. - * - * @return true if the node has been visited. - */ - protected boolean hasBeenVisited(Node node) { - return this.indexes[node.getId()] != UNDEFINED; - } - - @Override - protected StronglyConnectedComponentsSolution doRun() { - Graph graph = getInputData().getGraph(); - - components = new ArrayList>(); - - // Initialize everything - final int nbNodes = graph.getNodes().size(); - stack = new Stack(); - inStack = new boolean[nbNodes]; - - // Current index. - index = 0; - - // Information of nodes - indexes = new int[nbNodes]; - Arrays.fill(indexes, UNDEFINED); - lowlink = new int[nbNodes]; - - // Find components - for (Node node: graph.getNodes()) { - if (!hasBeenVisited(node)) { - findAndAddStrongComponent(node); - } - } - - return new StronglyConnectedComponentsSolution(getInputData(), Status.OPTIMAL, components); - } - -} diff --git a/src/main/org/insa/graph/Arc.java b/src/main/org/insa/graph/Arc.java index bc4f283..2f5b3d8 100644 --- a/src/main/org/insa/graph/Arc.java +++ b/src/main/org/insa/graph/Arc.java @@ -8,7 +8,7 @@ import java.util.List; * (without having to duplicate attributes). * * Arc should never be created manually but always using the - * {@link Node#linkNodes(Node, Node, int, RoadInformation, java.util.ArrayList)} + * {@link Node#linkNodes(Node, Node, float, RoadInformation, java.util.ArrayList)} * method to ensure proper instantiation of the {@link ArcForward} and * {@link ArcBackward} classes. * diff --git a/src/main/org/insa/graph/GraphStatistics.java b/src/main/org/insa/graph/GraphStatistics.java index a6c24ef..db575b5 100644 --- a/src/main/org/insa/graph/GraphStatistics.java +++ b/src/main/org/insa/graph/GraphStatistics.java @@ -10,6 +10,12 @@ package org.insa.graph; */ public class GraphStatistics { + /** + * Special value used to indicate that the graph has no maximum speed limit + * (some roads are not limited). + */ + public static final int NO_MAXIMUM_SPEED = -1; + /** * Class representing a bounding box for a graph (a rectangle that contains all * nodes in the graph). @@ -59,8 +65,10 @@ public class GraphStatistics { /** * Create a new GraphStatistics instance with the given value. * - * @param maximumSpeed Maximum speed of any road of the graph. A value of 0 may - * be used to indicate that this graph has no maximum limitation. + * @param boundingBox Bounding-box for the graph. + * @param maximumSpeed Maximum speed of any road of the graph. You can use + * {@link #NO_MAXIMUM_SPEED} to indicate that the graph has no maximum + * speed limit. * @param maximumLength Maximum length of any arc of the graph. */ public GraphStatistics(BoundingBox boundingBox, int maximumSpeed, float maximumLength) { @@ -77,8 +85,15 @@ public class GraphStatistics { } /** - * @return Maximum speed of any arc in the graph, or 0 if some road have no - * speed limitations. + * @return true if this graph has a maximum speed limit, false otherwise. + */ + public boolean hasMaximumSpeed() { + return this.maximumLength != NO_MAXIMUM_SPEED; + } + + /** + * @return Maximum speed of any arc in the graph, or {@link #NO_MAXIMUM_SPEED} + * if some roads have no speed limitation. */ public int getMaximumSpeed() { return this.maximumSpeed; diff --git a/src/main/org/insa/graphics/drawing/BasicGraphPalette.java b/src/main/org/insa/graphics/drawing/BasicGraphPalette.java index bce9674..bca569f 100644 --- a/src/main/org/insa/graphics/drawing/BasicGraphPalette.java +++ b/src/main/org/insa/graphics/drawing/BasicGraphPalette.java @@ -8,19 +8,10 @@ import org.insa.graph.RoadInformation.RoadType; public class BasicGraphPalette implements GraphPalette { // Color types for arc. - static final Color motorway = Color.RED; - static final Color bigroad = new Color(255, 105, 0); - static final Color smallroad = new Color(255, 234, 0); - static final Color coastline = Color.BLUE; - - // Default point width - static final int DEFAULT_POINT_WIDTH = 1; - - /** - * - */ - public BasicGraphPalette() { - } + private static final Color MOTORWAY_COLOR = Color.RED; + private static final Color BIG_ROAD_COLOR = new Color(255, 105, 0); + private static final Color SMALL_ROAD_COLOR = new Color(255, 234, 0); + private static final Color COASTLINE_COLOR = Color.BLUE; @Override public int getDefaultPointWidth() { @@ -35,19 +26,16 @@ public class BasicGraphPalette implements GraphPalette { @Override public Color getColorForArc(Arc arc) { RoadType type = arc.getRoadInformation().getType(); - Color color = Color.BLACK; switch (type) { case MOTORWAY: - color = motorway; - break; + return MOTORWAY_COLOR; case TRUNK: case PRIMARY: case SECONDARY: case MOTORWAY_LINK: case TRUNK_LINK: case PRIMARY_LINK: - color = bigroad; - break; + return BIG_ROAD_COLOR; case SECONDARY_LINK: case TERTIARY: case RESIDENTIAL: @@ -58,14 +46,12 @@ public class BasicGraphPalette implements GraphPalette { case PEDESTRIAN: case CYCLEWAY: case TRACK: - color = smallroad; - break; + return SMALL_ROAD_COLOR; case COASTLINE: - color = coastline; - break; + return COASTLINE_COLOR; } - return color; + return Color.BLACK; } @Override diff --git a/src/main/org/insa/graphics/drawing/Drawing.java b/src/main/org/insa/graphics/drawing/Drawing.java index 4a456d8..5cf48c2 100644 --- a/src/main/org/insa/graphics/drawing/Drawing.java +++ b/src/main/org/insa/graphics/drawing/Drawing.java @@ -14,31 +14,34 @@ public interface Drawing { /** * Add a listener to click to this drawing. * - * @param listener + * @param listener DrawingClickListener to add to this Drawing. */ public void addDrawingClickListener(DrawingClickListener listener); /** * Remove the given listener from the drawing. * - * @param listener + * @param listener DrawingClickListener to remove from this Drawing. */ public void removeDrawingClickListener(DrawingClickListener listener); /** - * Clear the drawing. + * Clear the drawing (overlays and underlying graph/map). */ public void clear(); /** - * Remove overlays from the drawing. + * Remove overlays from the drawing (do not remove the underlying graph/map). */ public void clearOverlays(); /** - * Draw the given point with the given color. + * Draw a marker at the given position with the given color. * - * @param point + * @param point Position of the marker to draw. + * @param color Color of the marker to draw. + * + * @return A MarkerOverlay instance representing the newly drawn marker. */ public MarkerOverlay drawMarker(Point point, Color color); @@ -48,65 +51,86 @@ public interface Drawing { * * PointSetOverlay are heavy memory resources, do not use one for each point! * + * @return A new PointSetOverlay for this drawing. */ public PointSetOverlay createPointSetOverlay(); /** - * Create a new PointSetOverlay with the original width and color that can be - * used to add overlay points to this drawing. + * Create a new PointSetOverlay with the given initial width and color that can + * be used to add overlay points to this drawing. * * PointSetOverlay are heavy memory resources, do not use one for each point! * + * @param width Initial width of points in the overlay. + * @param color Initial width of points in the overlay. + * + * @return A new PointSetOverlay for this drawing. */ public PointSetOverlay createPointSetOverlay(int width, Color color); /** * Draw the given graph using the given palette. * - * @param graph - * @param palette + * @param graph Graph to draw. + * @param palette Palette to use to draw the graph. + * + * @see BasicGraphPalette + * @see BlackAndWhiteGraphPalette */ public void drawGraph(Graph graph, GraphPalette palette); /** * Draw the given graph using a default palette specific to the implementation. * - * @param graph + * @param graph Graph to draw. */ public void drawGraph(Graph graph); /** * Draw a path using the given color. * - * @param path - * @param color - * @param markers Show origin and destination markers. - * @return + * @param path Path to draw. + * @param color Color of the path to draw. + * @param markers true to show origin and destination markers. + * + * @return A PathOverlay instance representing the newly drawn path. */ public PathOverlay drawPath(Path path, Color color, boolean markers); /** - * Draw a path using the given color with markers. + * Draw a path with both origin and destination markers using the given color. * - * @param path - * @param color + * @param path Path to draw. + * @param color Color of the path to draw. + * + * @return A PathOverlay instance representing the newly drawn path. + * + * @see Drawing#drawPath(Path, Color, boolean) */ public PathOverlay drawPath(Path path, Color color); /** * Draw a path using a default color specific to the implementation * + * @param path Path to draw. + * @param markers true to show origin and destination markers. * - * @param path - * @param markers Show origin and destination markers. + * @return A PathOverlay instance representing the newly drawn path. + * + * @see Drawing#drawPath(Path, Color, boolean) */ public PathOverlay drawPath(Path path, boolean markers); /** - * Draw a path using a default color specific to the implementation + * Draw a path with both origin and destination markers using a default color + * specific to the implementation * * - * @param path + * @param path Path to draw. + * + * @return A PathOverlay instance representing the newly drawn path. + * + * @see Drawing#drawPath(Path, Color, boolean) */ public PathOverlay drawPath(Path path); diff --git a/src/main/org/insa/graphics/drawing/DrawingClickListener.java b/src/main/org/insa/graphics/drawing/DrawingClickListener.java index 2e2203c..496d841 100644 --- a/src/main/org/insa/graphics/drawing/DrawingClickListener.java +++ b/src/main/org/insa/graphics/drawing/DrawingClickListener.java @@ -7,7 +7,7 @@ public interface DrawingClickListener { /** * Event triggered when a click is made on the map. * - * @param point + * @param point Position (on the map) of the mouse click. */ public void mouseClicked(Point point); diff --git a/src/main/org/insa/graphics/drawing/GraphPalette.java b/src/main/org/insa/graphics/drawing/GraphPalette.java index 4ba62a3..b4292e4 100644 --- a/src/main/org/insa/graphics/drawing/GraphPalette.java +++ b/src/main/org/insa/graphics/drawing/GraphPalette.java @@ -17,14 +17,14 @@ public interface GraphPalette { public Color getDefaultPointColor(); /** - * @param arc + * @param arc Arc for which color should be retrieved. * * @return Color associated with the given arc. */ public Color getColorForArc(Arc arc); /** - * @param arc + * @param arc Arc for which width should be retrieved. * * @return Width associated with the given arc. */ diff --git a/src/main/org/insa/graphics/drawing/components/BasicDrawing.java b/src/main/org/insa/graphics/drawing/components/BasicDrawing.java index 46495c0..ea1f297 100644 --- a/src/main/org/insa/graphics/drawing/components/BasicDrawing.java +++ b/src/main/org/insa/graphics/drawing/components/BasicDrawing.java @@ -449,11 +449,15 @@ public class BasicDrawing extends JPanel implements Drawing { * Return the longitude and latitude corresponding to the given position of the * MouseEvent. * - * @param event + * @param event MouseEvent from which longitude/latitude should be retrieved. * - * @return + * @return Point representing the projection of the MouseEvent position in the + * graph/map. + * + * @throws NoninvertibleTransformException if the actual transformation is + * invalid. */ - public Point getLongitudeLatitude(MouseEvent event) throws NoninvertibleTransformException { + protected Point getLongitudeLatitude(MouseEvent event) throws NoninvertibleTransformException { // Get the point using the inverse transform of the Zoom/Pan object, this gives // us // a point within the drawing box (between [0, 0] and [width, height]). diff --git a/src/main/org/insa/graphics/drawing/components/MapZoomControls.java b/src/main/org/insa/graphics/drawing/components/MapZoomControls.java index dcd4f82..8785eea 100644 --- a/src/main/org/insa/graphics/drawing/components/MapZoomControls.java +++ b/src/main/org/insa/graphics/drawing/components/MapZoomControls.java @@ -111,7 +111,7 @@ public class MapZoomControls { /** * Add a zoom-in listener. * - * @param listener + * @param listener Zoom-in listener to add to this MapZoomControls instance. */ public void addZoomInListener(ActionListener listener) { this.zoomInListeners.add(listener); @@ -120,7 +120,7 @@ public class MapZoomControls { /** * Add a zoom-out listener. * - * @param listener + * @param listener Zoom-out listener to add to this MapZoomControls instance. */ public void addZoomOutListener(ActionListener listener) { this.zoomOutListeners.add(listener); @@ -134,9 +134,9 @@ public class MapZoomControls { } /** - * Set the current zoom level. + * Set the current zoom level without requesting a redraw. * - * @param level + * @param level Zoom level to set. */ public void setZoomLevel(int level) { this.currentLevel = level; @@ -161,10 +161,10 @@ public class MapZoomControls { * Check if a point is contained inside an element of this zoom controls, useful * to avoid spurious click listeners. * - * @param point + * @param point Point to check. * * @return true if the given point correspond to an element of this zoom - * controls. + * controls. */ public boolean contains(Point point) { return zoomInRect.contains(point) || zoomOutRect.contains(point); diff --git a/src/main/org/insa/graphics/drawing/overlays/MarkerAutoScaling.java b/src/main/org/insa/graphics/drawing/overlays/MarkerAutoScaling.java index 70e1435..8c6f0a3 100644 --- a/src/main/org/insa/graphics/drawing/overlays/MarkerAutoScaling.java +++ b/src/main/org/insa/graphics/drawing/overlays/MarkerAutoScaling.java @@ -11,11 +11,27 @@ import org.mapsforge.core.model.Point; import org.mapsforge.map.awt.graphics.AwtBitmap; import org.mapsforge.map.layer.overlay.Marker; +/** + * Class extending the default Mapsforge's {@link Marker} with auto-scaling. + * + * Mapsforge's Markers do not scale with zoom level, this class aims at + * correcting this. Internally, this image stores an {@link Image} instance and + * scale it when a redraw is requested. + * + * @see MarkerUtils#getMarkerForColor(java.awt.Color) + * @see PaintUtils#getStrokeWidth(int, byte) + */ public class MarkerAutoScaling extends Marker { // Original image. private Image image; + /** + * Create a new MarkerAutoScaling at the given position with the given image. + * + * @param latLong Initial position of the marker. + * @param image Image for this marker. + */ public MarkerAutoScaling(LatLong latLong, Image image) { super(latLong, null, 0, 0); this.image = image; diff --git a/src/main/org/insa/graphics/drawing/overlays/MarkerOverlay.java b/src/main/org/insa/graphics/drawing/overlays/MarkerOverlay.java index a761af9..23baf29 100644 --- a/src/main/org/insa/graphics/drawing/overlays/MarkerOverlay.java +++ b/src/main/org/insa/graphics/drawing/overlays/MarkerOverlay.java @@ -5,12 +5,14 @@ import org.insa.graph.Point; public interface MarkerOverlay extends Overlay { /** - * @return The point associated with this marker. + * @return The current position of this marker. */ public Point getPoint(); /** + * Move this marker to the specified location. * + * @param point New position for the marker. */ public void moveTo(Point point); diff --git a/src/main/org/insa/graphics/drawing/overlays/MarkerUtils.java b/src/main/org/insa/graphics/drawing/overlays/MarkerUtils.java index c4d045f..0908c92 100644 --- a/src/main/org/insa/graphics/drawing/overlays/MarkerUtils.java +++ b/src/main/org/insa/graphics/drawing/overlays/MarkerUtils.java @@ -11,15 +11,17 @@ public class MarkerUtils { private static final String MARKER_MASK_FILE = "res/marker_mask.bin"; /** - * Create a Bitmap representing a marker of the given color. + * Create an Image representing a marker of the given color. * - * @param color - * @return + * @param color Color of the marker. + * + * @return A new Image representing a marker with the given color. */ public static Image getMarkerForColor(Color color) { // create image int[][] mask = readMarkerMask(); - BufferedImage image = new BufferedImage(mask[0].length, mask.length, BufferedImage.TYPE_4BYTE_ABGR); + BufferedImage image = new BufferedImage(mask[0].length, mask.length, + BufferedImage.TYPE_4BYTE_ABGR); // Color[] map = getColorMapping(color); int rgb = color.getRGB() & 0x00ffffff; diff --git a/src/main/org/insa/graphics/drawing/overlays/PaintUtils.java b/src/main/org/insa/graphics/drawing/overlays/PaintUtils.java index a4eae00..59413ed 100644 --- a/src/main/org/insa/graphics/drawing/overlays/PaintUtils.java +++ b/src/main/org/insa/graphics/drawing/overlays/PaintUtils.java @@ -4,6 +4,8 @@ import java.awt.Color; import org.mapsforge.core.graphics.GraphicFactory; import org.mapsforge.map.awt.graphics.AwtGraphicFactory; +import org.mapsforge.map.layer.overlay.Marker; +import org.mapsforge.map.layer.overlay.Polyline; public class PaintUtils { @@ -13,8 +15,9 @@ public class PaintUtils { /** * Convert the given AWT color to a mapsforge compatible color. * - * @param color - * @return + * @param color AWT color to convert. + * + * @return Integer value representing a corresponding mapsforge color. */ public static int convertColor(Color color) { return GRAPHIC_FACTORY.createColor(color.getAlpha(), color.getRed(), color.getGreen(), @@ -24,16 +27,23 @@ public class PaintUtils { /** * Convert the given mapsforge color to an AWT Color. * - * @param color - * @return + * @param color Integer value representing a mapsforge color. + * + * @return AWT color corresponding to the given value. */ public static Color convertColor(int color) { return new Color(color, true); } /** - * @param width - * @return + * Compute an updated value for the given width at the given zoom level. This + * function can be used to automatically scale {@link Polyline} or + * {@link Marker} when zooming (which is not done by default in Mapsforge). + * + * @param width Original width to convert. + * @param zoomLevel Zoom level for which the width should be computed. + * + * @return Actual width at the given zoom level. */ public static float getStrokeWidth(int width, byte zoomLevel) { float mul = 1; diff --git a/src/main/org/insa/graphics/drawing/overlays/PointSetOverlay.java b/src/main/org/insa/graphics/drawing/overlays/PointSetOverlay.java index c294972..fbae987 100644 --- a/src/main/org/insa/graphics/drawing/overlays/PointSetOverlay.java +++ b/src/main/org/insa/graphics/drawing/overlays/PointSetOverlay.java @@ -9,48 +9,61 @@ public interface PointSetOverlay extends Overlay { /** * Set the width of this overlay for future addPoint(). * - * @param width + * @param width New default width for this overlay. */ public void setWidth(int width); /** * Set color and width for this overlay for future addPoint(). * - * @param width - * @param color + * @param width New default width for this overlay. + * @param color New default color for this overlay. */ public void setWidthAndColor(int width, Color color); /** * Add a new point using the current width and color. * - * @param point + * @param point Position of the point to add. + * + * @see #setWidth(int) + * @see #setColor(Color) */ public void addPoint(Point point); /** * Set the current width and then add a new point. * - * @param point - * @param width + * @param point Position of the point to add. + * @param width New default width for this overlay. + * + * @see #setWidth(int) + * @see PointSetOverlay#addPoint(Point) */ public void addPoint(Point point, int width); /** * Set the current color and then add a new point. * - * @param point - * @param color + * @param point Position of the point to add. + * @param color New default color for this overlay. + * + * @see #setColor(Color) + * @see PointSetOverlay#addPoint(Point) */ public void addPoint(Point point, Color color); /** - * Add a new point to this set at the given location, with the given color and - * width, and update the current color. + * Add a new point at the given location, with the given color and width, and + * update the current width and color. * - * @param point - * @param width - * @param color + * @param point Position of the point to add. + * @param width New default width for this overlay. + * @param color New default color for this overlay. + * + * @see #setWidth(int) + * @see #setColor(Color) + * @see PointSetOverlay#addPoint(Point) */ public void addPoint(Point point, int width, Color color); diff --git a/src/main/org/insa/graphics/drawing/overlays/PolylineAutoScaling.java b/src/main/org/insa/graphics/drawing/overlays/PolylineAutoScaling.java index e0b2f24..beb344e 100644 --- a/src/main/org/insa/graphics/drawing/overlays/PolylineAutoScaling.java +++ b/src/main/org/insa/graphics/drawing/overlays/PolylineAutoScaling.java @@ -12,6 +12,15 @@ import org.mapsforge.core.model.LatLong; import org.mapsforge.map.awt.graphics.AwtGraphicFactory; import org.mapsforge.map.layer.overlay.Polyline; +/** + * Class extending the default Mapsforge's {@link Polyline} with auto-scaling. + * + * Mapsforge's Polylines do not scale with zoom level, this class aims at + * correcting this. When a redraw is requested, the width of the line is + * recomputed for the current zoom level. + * + * @see PaintUtils#getStrokeWidth(int, byte) + */ public class PolylineAutoScaling extends Polyline { // Graphic factory. @@ -21,8 +30,12 @@ public class PolylineAutoScaling extends Polyline { private final int width; /** - * @param width - * @param color + * Create a new PolylineAutoScaling with the given width and color. + * + * @param width Original width of the line (independent of the zoom level). + * @param color Color of the line. + * + * @see PaintUtils#getStrokeWidth(int, byte) */ public PolylineAutoScaling(int width, Color color) { super(GRAPHIC_FACTORY.createPaint(), GRAPHIC_FACTORY); @@ -48,14 +61,14 @@ public class PolylineAutoScaling extends Polyline { } /** - * @param point + * @param point Point to add to this line. */ public void add(Point point) { getLatLongs().add(new LatLong(point.getLatitude(), point.getLongitude())); } /** - * @param points + * @param points Points to add to this line. */ public void add(List points) { for (Point point: points) {