Tulip  5.2.0
Large graphs analysis and drawing
LayoutProperty.h
1 /*
2  *
3  * This file is part of Tulip (http://tulip.labri.fr)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux
7  *
8  * Tulip is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU Lesser General Public License
10  * as published by the Free Software Foundation, either version 3
11  * of the License, or (at your option) any later version.
12  *
13  * Tulip is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  * See the GNU General Public License for more details.
17  *
18  */
19 
20 #ifndef TULIP_LAYOUT_H
21 #define TULIP_LAYOUT_H
22 
23 #include <tulip/tuliphash.h>
24 #include <tulip/PropertyTypes.h>
25 #include <tulip/Observable.h>
26 #include <tulip/AbstractProperty.h>
27 #include <tulip/PropertyAlgorithm.h>
28 #include <tulip/minmaxproperty.h>
29 
30 namespace tlp {
31 
32 template <>
34  tlp::edge e, tlp::LineType::RealType newValue);
35 
36 template <>
37 std::pair<tlp::Coord, tlp::Coord>
39 
40 class PropertyContext;
41 class Graph;
42 
43 typedef AbstractProperty<tlp::PointType, tlp::LineType> AbstractLayoutProperty;
44 typedef MinMaxProperty<tlp::PointType, tlp::LineType> LayoutMinMaxProperty;
45 
46 /**
47  * @ingroup Graph
48  * @brief A graph property that maps a tlp::Coord value to graph nodes and std::vector<tlp::Coord>
49  * for edges.
50  */
51 class TLP_SCOPE LayoutProperty : public LayoutMinMaxProperty {
52 public:
53  LayoutProperty(Graph *graph, const std::string &name = "" /*, bool updateOnEdgeReversal=true*/);
54 
55  // override some PropertyInterface methods
56  PropertyInterface *clonePrototype(Graph *, const std::string &) const override;
57  static const std::string propertyTypename;
58  const std::string &getTypename() const override {
59  return propertyTypename;
60  }
61 
62  //=======================================
63  // Methods for extra layout information
64  //=======================================
65 
66  /**
67  * Returns the maximum coordinate of the layout, i.e. the top-right corner of the induced bounding
68  *box
69  *
70  * @param subgraph If not null, returns the maximum coordinate for a subgraph layout
71  **/
72  Coord getMax(const Graph *subgraph = nullptr);
73 
74  /**
75  * Returns the minimum coordinate of the layout, i.e. the bottom-left corner of the induced
76  *bounding box
77  *
78  * @param subgraph If not null, returns the minimum coordinate for a subgraph layout
79  **/
80  Coord getMin(const Graph *subgraph = nullptr);
81 
82  //============================================
83  // Functions for layout modification
84  //============================================
85 
86  /**
87  * Translates the current layout according to a movement vector
88  *
89  * @param move a movement vector
90  * @param subgraph If not null, only translates the layout of that subgraph
91  **/
92  void translate(const Vec3f &move, const Graph *subgraph = nullptr);
93 
94  /**
95  * Translates the layout of a set of nodes and edges provided through iterators
96  * according to a movement vector
97  *
98  * @param move a movement vector
99  * @param itNodes an iterator on graph nodes
100  * @param itEdges an iterator on graph edges
101  *
102  * @warning The iterators are not deleted
103  **/
104  void translate(const Vec3f &move, Iterator<node> *itNodes, Iterator<edge> *itEdges);
105 
106  /**
107  * Scales the current layout according to a vector of scale factors (sx, sy, sz).
108  *
109  * @param scaleFactors a vector of scale factors
110  * @param subgraph If not null, only scales the layout of that subgraph
111  **/
112  void scale(const Vec3f &scaleFactors, const Graph *subgraph = nullptr);
113 
114  /**
115  * Scales the layout of a set of nodes and edges provided through iterators
116  * according to a vector of scale factors (sx, sy, sz).
117  *
118  * @param scaleFactors a vector of scale factors
119  * @param itNodes an iterator on graph nodes
120  * @param itEdges an iterator on graph edges
121  *
122  * @warning The iterators are not deleted
123  **/
124  void scale(const Vec3f &scaleFactors, Iterator<node> *itNodes, Iterator<edge> *itEdges);
125 
126  /**
127  * Rotates the layout around the X-axis according to an angle in degrees.
128  *
129  * @param alpha an angle in degrees
130  * @param subgraph If not null, only rotates the layout of that subgraph
131  **/
132  void rotateX(const double &alpha, const Graph *subgraph = nullptr);
133 
134  /**
135  * Rotates the layout around the Y-axis according to an angle in degrees.
136  *
137  * @param alpha an angle in degrees
138  * @param subgraph If not null, only rotates the layout of that subgraph
139  **/
140  void rotateY(const double &alpha, const Graph *subgraph = nullptr);
141 
142  /**
143  * Rotates the layout around the Z-axis according to an angle in degrees.
144  *
145  * @param alpha an angle in degrees
146  * @param subgraph If not null, only rotates the layout of that subgraph
147  **/
148  void rotateZ(const double &alpha, const Graph *subgraph = nullptr);
149 
150  /**
151  * Rotates the layout around the X-axis of the nodes and edges provided
152  * through iterators according to an angle in degrees.
153  *
154  * @param alpha an angle in degrees
155  * @param itNodes an iterator on graph nodes
156  * @param itEdges an iterator on graph edges
157  *
158  * @warning The iterators are not deleted
159  **/
160  void rotateX(const double &alpha, Iterator<node> *itNodes, Iterator<edge> *itEdges);
161 
162  /**
163  * Rotates the layout around the Y-axis of the nodes and edges provided
164  * through iterators according to an angle in degrees.
165  *
166  * @param alpha an angle in degrees
167  * @param itNodes an iterator on graph nodes
168  * @param itEdges an iterator on graph edges
169  *
170  * @warning The iterators are not deleted
171  **/
172  void rotateY(const double &alpha, Iterator<node> *itNodes, Iterator<edge> *itEdges);
173 
174  /**
175  * Rotates the layout around the Z-axis of the nodes and edges provided through
176  * iterators according to an angle in degrees.
177  *
178  * @param alpha an angle in degrees
179  * @param itNodes an iterator on graph nodes
180  * @param itEdges an iterator on graph edges
181  *
182  * @warning The iterators are not deleted
183  **/
184  void rotateZ(const double &alpha, Iterator<node> *itNodes, Iterator<edge> *itEdges);
185 
186  /**
187  * Centers the layout, meaning translating it in order that
188  * the center of its bounding box is (0,0,0)
189  *
190  * @param subgraph If not null, only centers the layout of that subgraph
191  **/
192  void center(const Graph *subgraph = nullptr);
193 
194  /**
195  * Centers the layout to newCenter, meaning translating it in order that
196  * the center of its bounding box is equal to newCenter
197  *
198  * @param newCenter the coordinate of the new layout center
199  * @param subgraph If not null, only centers the layout of that subgraph
200  **/
201  void center(const Vec3f &newCenter, const Graph *subgraph = nullptr);
202 
203  /**
204  * Normalizes the layout, meaning dividing each nodes and edges coordinate by the maximum magnitude
205  *of the whole coordinates set
206  *
207  * @param subgraph If not null, only normalizes the layout of that subgraph
208  **/
209  void normalize(const Graph *subgraph = nullptr);
210 
211  /**
212  * Scales the layout in order to approach an aspect ratio (width / height) of 1.0 .
213  * @param subgraph If not null, only scales the layout of that subgraph
214  **/
215  void perfectAspectRatio(const Graph *subgraph = nullptr);
216 
217  //=======================================================================
218  // Set of function in order to measure the quality of the LayoutAlgorithm
219  //=======================================================================
220 
221  /**
222  * Returns the length of an edge, the bends are taken into account.
223  * Thus, it measure the length of a polyline.
224  *
225  * @param e the graph edge on which to compute its length
226  *
227  * @warning this function only measure the length of the polyline between bends,
228  * when using curves like B├ęzier etc... the result will not be the length of the curve.
229  **/
230  double edgeLength(const edge e) const;
231 
232  /**
233  * Returns the average edge length of the layout, the bends are taken into account
234  *
235  * @param subgraph If not null, only compute the average edge length for that subgraph
236  **/
237  double averageEdgeLength(const Graph *subgraph = nullptr) const;
238 
239  /**
240  * Returns the average angular resolution of the layout.
241  * It is only defined for 2D drawing, meaning the third coordinate
242  * is omitted
243  *
244  * @param subgraph It not null, only computes the average angular resolution for that subgraph
245  **/
246  double averageAngularResolution(const Graph *subgraph = nullptr) const;
247 
248  /**
249  * Returns the average angular resolution of a node.
250  * It is only defined for 2D drawing, meaning the third coordinate
251  * is omitted
252  *
253  * @param n the graph node on which to compute the angular resolution
254  * @param subgraph If not null, only computes the average angular resolution for the node in that
255  *subgraph
256  **/
257  double averageAngularResolution(const node n, const Graph *subgraph = nullptr) const;
258 
259  /**
260  * Returns a vector of all angular resolution of a node.
261  * It is only defined for 2D drawing, meaning the third coordinate
262  * is omitted
263  *
264  * @param n the graph node on which to compute the angular resolution
265  * @param subgraph If not null, only computes the average angular resolution for the node in that
266  *subgraph
267  **/
268  std::vector<double> angularResolutions(const node n, const Graph *subgraph = nullptr) const;
269 
270  /**
271  * Fixes embedding of the graph according to the layout
272  * ie. sort edges around nodes according to their neighbors/bends position in the layout/
273  * Only works in 2D, the third coordinate is not taken into account.
274  *
275  * @param subgraph It not null, only fixes embedding in that subgraph
276  **/
277  void computeEmbedding(Graph *subgraph = nullptr);
278 
279  /**
280  * Fixes embedding of the node according to the layout
281  * ie. sort edges around the node according to its neighbors/bends position in the layout/
282  * Only work in 2D, the third coordinate is not taken into account.
283  *
284  * @param n the graph node on which to fix embedding
285  * @param subgraph If not null, only fixes the embedding of the node in that subgraph
286  **/
287  void computeEmbedding(const node n, Graph *subgraph = nullptr);
288 
289  /**
290  * Returns the number of crossings in the layout
291  **/
292  // methods removed until we have a working implementation
293  // unsigned int crossingNumber() const;
294 
295  // redefinition of some AbstractProperty methods
296  void setNodeValue(const node, tlp::StoredType<Coord>::ReturnedConstValue v) override;
297  void setEdgeValue(const edge, tlp::StoredType<std::vector<Coord>>::ReturnedConstValue v) override;
298  void setAllNodeValue(tlp::StoredType<Coord>::ReturnedConstValue v) override;
299  void setValueToGraphNodes(tlp::StoredType<Coord>::ReturnedConstValue v,
300  const Graph *graph) override;
301  void setAllEdgeValue(tlp::StoredType<std::vector<Coord>>::ReturnedConstValue v) override;
302  void setValueToGraphEdges(tlp::StoredType<std::vector<Coord>>::ReturnedConstValue v,
303  const Graph *graph) override;
304 
305  _DEPRECATED void setAllNodeValue(tlp::StoredType<Coord>::ReturnedConstValue v,
306  const Graph *graph) override;
307  _DEPRECATED void setAllEdgeValue(tlp::StoredType<std::vector<Coord>>::ReturnedConstValue v,
308  const Graph *graph) override;
309 
310 protected:
311  void clone_handler(AbstractProperty<tlp::PointType, tlp::LineType> &) override;
312 
313 private:
314  void resetBoundingBox();
315  void rotate(const double &alpha, int rot, Iterator<node> *, Iterator<edge> *);
316  // override Observable::treatEvent
317  void treatEvent(const Event &) override;
318 
319 public:
320  // the number of edges with bends
321  unsigned int nbBendedEdges;
322 };
323 
324 /**
325  * @ingroup Graph
326  * @brief A graph property that maps a std::vector<tlp::Coord> value to graph elements.
327  */
328 class TLP_SCOPE CoordVectorProperty
329  : public AbstractVectorProperty<tlp::CoordVectorType, tlp::PointType> {
330 public:
331  CoordVectorProperty(Graph *g, const std::string &n = "")
332  : AbstractVectorProperty<CoordVectorType, tlp::PointType>(g, n) {}
333  // redefinition of some PropertyInterface methods
334  PropertyInterface *clonePrototype(Graph *, const std::string &) const override;
335  static const std::string propertyTypename;
336  const std::string &getTypename() const override {
337  return propertyTypename;
338  }
339 };
340 
342 }
343 #endif
This class extends upon PropertyInterface, and adds type-safe methods to get and set the node and edg...
Abstracts the computation of minimal and maximal values on node and edge values of properties...
A graph property that maps a std::vector<tlp::Coord> value to graph elements.
Interface for Tulip iterators. Allows basic iteration operations only.
Definition: Graph.h:41
PropertyInterface describes the interface of a graph property.
The edge struct represents an edge in a Graph object.
Definition: Edge.h:40
The node struct represents a node in a Graph object.
Definition: Node.h:40
Event is the base class for all events used in the Observation mechanism.
Definition: Observable.h:51
void updateEdgeValue(tlp::edge e, typename edgeType::RealType newValue)
Updates the value on an edge, and updates the minimal/maximal cached values if necessary. Should be called by subclasses in order to keep the cache up to date.
A graph property that maps a tlp::Coord value to graph nodes and std::vector<tlp::Coord> for edges...