1 /****************************************************************************/
2 // Eclipse SUMO, Simulation of Urban MObility; see https://eclipse.org/sumo
3 // Copyright (C) 2001-2019 German Aerospace Center (DLR) and others.
4 // This program and the accompanying materials
5 // are made available under the terms of the Eclipse Public License v2.0
6 // which accompanies this distribution, and is available at
7 // http://www.eclipse.org/legal/epl-v20.html
8 // SPDX-License-Identifier: EPL-2.0
9 /****************************************************************************/
10 /// @file    NBDistrict.h
11 /// @author  Daniel Krajzewicz
12 /// @author  Sascha Krieg
13 /// @author  Michael Behrisch
14 /// @date    Sept 2002
15 /// @version $Id$
16 ///
17 // A class representing a single district
18 /****************************************************************************/
19 #ifndef NBDistrict_h
20 #define NBDistrict_h
21 
22 
23 // ===========================================================================
24 // included modules
25 // ===========================================================================
26 #include <config.h>
27 
28 #include <vector>
29 #include <string>
30 #include <utility>
31 #include "NBCont.h"
32 #include <utils/common/Named.h>
33 #include <utils/common/VectorHelper.h>
34 #include <utils/geom/Position.h>
35 #include <utils/geom/PositionVector.h>
36 
37 
38 // ===========================================================================
39 // class declarations
40 // ===========================================================================
41 class NBEdge;
42 class OutputDevice;
43 
44 
45 // ===========================================================================
46 // class definitions
47 // ===========================================================================
48 /**
49  * @class NBDistrict
50  * @brief A class representing a single district
51  *
52  * A "district" is an area within the network which may be referenced by
53  *  O/D-matrices. It stems from importing VISUM-networks. Work with VISUM-
54  *  -networks also made it necessary that a district knows the edges at
55  *  which new vehicles shall approach the simulated network (sources) and
56  *  those to use when leaving the network (sinks). These connections to the
57  *  network are weighted.
58  *
59  * Later work on VISUM required also parsing the shape of a district. This
60  *  information is used by some external tools only, it is even not shown
61  *  within the GUI.
62  *
63  * @todo Recheck whether this can be somehow joined with ODDistrict
64  */
65 class NBDistrict : public Named {
66 public:
67     /** @brief Constructor with id, and position
68      *
69      * @param[in] id The id of the district
70      * @param[in] pos The position of the district
71      */
72     NBDistrict(const std::string& id, const Position& pos);
73 
74 
75     /** @brief Constructor without position
76      *
77      * The position must be computed later
78      *
79      * @param[in] id The id of the district
80      */
81     NBDistrict(const std::string& id);
82 
83 
84     /// @brief Destructor
85     ~NBDistrict();
86 
87 
88     /** @brief Adds a source
89      *
90      * It is checked whether the edge has already been added as a source. false
91      *  is returned in this case. Otherwise, the source is pushed into
92      *  the list of sources and the weight into the list of source weights.
93      *  both lists stay sorted this way. true is returned.
94      *
95      * @param[in] source An edge that shall be used as source
96      * @param[in] weight The weight of the source
97      * @return Whether the source could be added (was not added before)
98      * @todo Consider using only one list for sources/weights
99      */
100     bool addSource(NBEdge* const source, double weight);
101 
102 
103     /** @brief Adds a sink
104      *
105      * It is checked whether the edge has already been added as a sink. false
106      *  is returned in this case. Otherwise, the sink is pushed into
107      *  the list of sink and the weight into the list of sink weights.
108      *  both lists stay sorted this way. true is returned.
109      *
110      * @param[in] sink An edge that shall be used as sink
111      * @param[in] weight The weight of the sink
112      * @return Whether the sink could be added (was not added before)
113      * @todo Consider using only one list for sinks/weights
114      */
115     bool addSink(NBEdge* const sink, double weight);
116 
117 
118     /** @brief Returns the position of this district's center
119      *
120      * @return The position of this district's center
121      * @todo Recheck when this information is set/needed
122      */
getPosition()123     const Position& getPosition() const {
124         return myPosition;
125     }
126 
127 
128     /** @brief Sets the center coordinates
129      *
130      * @param[in] pos The new center to assign
131      * @todo Recheck when this information is set/needed
132      */
133     void setCenter(const Position& pos);
134 
135 
136     /** @brief Replaces incoming edges from the vector (sinks) by the given edge
137      *
138      * When an edge is split/joined/removed/etc., it may get necessary to replace prior
139      *  edges by new ones. This method replaces all occurences of the edges from
140      *  "which" within incoming edges (sinks) by the given edge.
141      *
142      * The new sink edge's weight is the sum of the weights of the replaced edges.
143      *
144      * @param[in] which List of edges to replace
145      * @param[in] by The replacement
146      */
147     void replaceIncoming(const EdgeVector& which, NBEdge* const by);
148 
149 
150     /** @brief Replaces outgoing edges from the vector (source) by the given edge
151      *
152      * When an edge is split/joined/removed/etc., it may get necessary to replace prior
153      *  edges by new ones. This method replaces all occurences of the edges from
154      *  "which" within outgoing edges (sources) by the given edge.
155      *
156      * The new source edge's weight is the sum of the weights of the replaced edges.
157      *
158      * @param[in] which List of edges to replace
159      * @param[in] by The replacement
160      */
161     void replaceOutgoing(const EdgeVector& which, NBEdge* const by);
162 
163 
164     /** @brief Removes the given edge from the lists of sources and sinks
165      *
166      * The according weights are removed, too.
167      *
168      * @param[in] e The edge to remove from sinks/sources
169      */
170     void removeFromSinksAndSources(NBEdge* const e);
171 
172 
173     /** @brief Sets the shape of this district
174      *
175      * @param[in] p The new shape
176      */
177     void addShape(const PositionVector& p);
178 
179 
180     /** @brief Returns the weights of the sources
181      * @return The source weights
182      */
getSourceWeights()183     const std::vector<double>& getSourceWeights() const {
184         return mySourceWeights;
185     }
186 
187 
188     /** @brief Returns the sources
189      * @return The source edges
190      */
getSourceEdges()191     const std::vector<NBEdge*>& getSourceEdges() const {
192         return mySources;
193     }
194 
195 
196     /** @brief Returns the weights of the sinks
197      * @return The sink weights
198      */
getSinkWeights()199     const std::vector<double>& getSinkWeights() const {
200         return mySinkWeights;
201     }
202 
203 
204     /** @brief Returns the sinks
205      * @return The sink edges
206      */
getSinkEdges()207     const std::vector<NBEdge*>& getSinkEdges() const {
208         return mySinks;
209     }
210 
211 
212     /** @brief Returns the shape
213      * @return The district's shape
214      */
getShape()215     const PositionVector& getShape() const {
216         return myShape;
217     }
218 
219 
220 
221     /// @name Applying offset
222     /// @{
223 
224     /** @brief Applies an offset to the district
225      * @param[in] xoff The x-offset to apply
226      * @param[in] yoff The y-offset to apply
227      */
228     void reshiftPosition(double xoff, double yoff);
229 
230     /// @brief mirror coordinates along the x-axis
231     void mirrorX();
232     /// @}
233 
234 
235 
236 
237 
238 private:
239     /// @brief Definition of a vector of connection weights
240     typedef std::vector<double> WeightsCont;
241 
242     /// @brief The sources (connection from district to network)
243     EdgeVector mySources;
244 
245     /// @brief The weights of the sources
246     WeightsCont mySourceWeights;
247 
248     /// @brief The sinks (connection from network to district)
249     EdgeVector mySinks;
250 
251     /// @brief The weights of the sinks
252     WeightsCont mySinkWeights;
253 
254     /// @brief The position of the district
255     Position myPosition;
256 
257     /// @brief The shape of the dsitrict
258     PositionVector myShape;
259 
260 
261 private:
262     /** invalid copy constructor */
263     NBDistrict(const NBDistrict& s);
264 
265     /** invalid assignment operator */
266     NBDistrict& operator=(const NBDistrict& s);
267 
268 
269 };
270 
271 
272 #endif
273 
274 /****************************************************************************/
275 
276