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-acr 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! Such arcs might lead to negative-valued circles which will make exploratory
55 * algorithms to endlessly walk in circles. That is abs(returned value) must be greater or equal to abs(mapCost).
56 *
57 * @param nodeFrom
58 * @param nodeTo
59 * @param mapCost cost of the arc as returned by underlying {@link IPFMap#getArcCost(Object, Object)}
60 *
61 * @return
62 */
63 public int getArcExtraCost(NODE nodeFrom, NODE nodeTo, int mapCost);
64
65 /**
66 * Nodes filter. Method defining which nodes are allowed to be explored / used by path finding algorithms, i.e., algorithm will never return path leading
67 * to such nodes. May be used to define "forbidden" nodes.
68 *
69 * @param node
70 *
71 * @return
72 */
73 public boolean isNodeOpened(NODE node);
74
75 /**
76 * Arcs filter. Method defining which "arc" (oriented links between nodes) can be used for the purpose of path-planning. It can be used
77 * 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.
78 *
79 * @param nodeFrom
80 * @param nodeTo
81 *
82 * @return
83 */
84 public boolean isArcOpened(NODE nodeFrom, NODE nodeTo);
85
86 /**
87 * Default view does not impose any specific view on the map... all nodes/arcs are opened, no extra cost/nodes defined.
88 * @author Jimmy
89 */
90 public class DefaultView<NODE> implements IPFMapView<NODE> {
91
92 @Override
93 public Collection<NODE> getExtraNeighbors(NODE node, Collection<NODE> mapNeighbors) {
94 return null;
95 }
96
97 @Override
98 public int getArcExtraCost(NODE nodeFrom, NODE nodeTo, int mapCost) {
99 return 0;
100 }
101
102 @Override
103 public int getNodeExtraCost(NODE node, int mapCost) {
104 return 0;
105 }
106
107 @Override
108 public boolean isArcOpened(NODE nodeFrom, NODE nodeTo) {
109 return true;
110 }
111
112 @Override
113 public boolean isNodeOpened(NODE node) {
114 return true;
115 }
116
117 }
118
119 }