1 package cz.cuni.amis.pathfinding.map;
2
3 import java.util.Collection;
4
5 /**
6 * This interface provides additional information about the map algorithms are going to work with. In its implementation you may provide custom
7 * view on the map as needed for your search (for instance you need to forbid some nodes / edges or change the general cost of nodes / edges
8 * in order to change how your agent is going to plan the path).
9 * <p><p>
10 * Generally, you will use {@link IPFMap} interface to define the map in general and then use this {@link IPFMapView} interface
11 * to specify a specific needs you need to impose over the map as is "forbidding" some nodes or "imposing additional costs
12 * onto the nodes".
13 *
14 * @author Jimmy
15 */
16 public interface IPFMapView<NODE> {
17
18 /**
19 * This method may return new nodes which are not present in 'mapNeighbors' (as returned by {@link IPFMap#getNeighbors(Object)}).
20 * Such nodes are then exclusively accessible to your particular agent, that is, this methods is adding nodes that can be accessed
21 * by the agent but are not part of your general map description.
22 * <p><p>
23 * "node" MUST NOT BE ADDED TO "mapNeighbors"!
24 * <p><p>
25 * Returned collection must not contain multiple references to a single neighbor (multi-graph is forbidden).
26 * <p><p>
27 * Returned collection must not contain any node from "mapNeighbors".
28 *
29 * @param node
30 * @param mapNeighbors neighbors of the "node" as returned by {@link IPFMap#getNeighbors(Object)}, may return null
31 */
32 public Collection<NODE> getExtraNeighbors(NODE node, Collection<NODE> mapNeighbors);
33
34 /**
35 * Method defining extra-node cost, that is a cost that is added to {@link IPFMap#getNodeCost(Object)}.
36 * <p><p>
37 * This allows you to provide "customization" to the graph nodes, simply, it is a way of telling "this node is cool to have in path" (negative cost)
38 * or "this node is bad to have in path" (positive cost).
39 *
40 * @param node
41 * @param mapCost cost of the node as returned by underlying {@link IPFMap#getNodeCost(Object)}
42 *
43 * @return
44 */
45 public int getNodeExtraCost(NODE node, int mapCost);
46
47 /**
48 * Method defining extra-arc cost, that is a cost that is added to {@link IPFMap#getArcCost(Object, Object)}.
49 * <p><p>
50 * This allows you to
51 * provide "customization" to the graph arc costs. It allows you to say "this is a cool arc to use for travel" (negative extra cost)
52 * or "this edge is hard to cross" (positive extra cost).
53 * <p><p>
54 * NOTE THAT YOU MUST AVOID HAVING NEGATIVELY-VALUED ARCs ({@link IPFMap#getArcCost(Object, Object)} + {@link #getArcExtraCost(Object, Object, int)} < 0)!
55 * <p>
56 * Such arcs might lead to negative-valued circles which will make exploratory
57 * algorithms to endlessly walk in circles.
58 *
59 * @param nodeFrom
60 * @param nodeTo
61 * @param mapCost cost of the arc as returned by underlying {@link IPFMap#getArcCost(Object, Object)}
62 *
63 * @return
64 */
65 public int getArcExtraCost(NODE nodeFrom, NODE nodeTo, int mapCost);
66
67 /**
68 * Nodes filter. Method defining which nodes are allowed to be explored / used by path finding algorithms, i.e., algorithm will never return path leading
69 * to such nodes. May be used to define "forbidden" nodes.
70 *
71 * @param node
72 *
73 * @return
74 */
75 public boolean isNodeOpened(NODE node);
76
77 /**
78 * Arcs filter. Method defining which "arc" (oriented links between nodes) can be used for the purpose of path-planning. It can be used
79 * to "forbid" usage of some arc, that is you can rule out some arc you do not want your agent to be able to travel.
80 *
81 * @param nodeFrom
82 * @param nodeTo
83 *
84 * @return
85 */
86 public boolean isArcOpened(NODE nodeFrom, NODE nodeTo);
87
88 /**
89 * Default view does not impose any specific view on the map... all nodes/arcs are opened, no extra cost/nodes defined.
90 * @author Jimmy
91 */
92 public class DefaultView<NODE> implements IPFMapView<NODE> {
93
94 @Override
95 public Collection<NODE> getExtraNeighbors(NODE node, Collection<NODE> mapNeighbors) {
96 return null;
97 }
98
99 @Override
100 public int getArcExtraCost(NODE nodeFrom, NODE nodeTo, int mapCost) {
101 return 0;
102 }
103
104 @Override
105 public int getNodeExtraCost(NODE node, int mapCost) {
106 return 0;
107 }
108
109 @Override
110 public boolean isArcOpened(NODE nodeFrom, NODE nodeTo) {
111 return true;
112 }
113
114 @Override
115 public boolean isNodeOpened(NODE node) {
116 return true;
117 }
118
119 }
120
121 }