Tulip  4.2.0
Better Visualization Through Research
 All Classes Namespaces Files Functions Variables Enumerations Enumerator Properties Groups Pages
LayoutProperty.h
1 /*
2  *
3  * This file is part of Tulip (www.tulip-software.org)
4  *
5  * Authors: David Auber and the Tulip development Team
6  * from LaBRI, University of Bordeaux 1 and Inria Bordeaux - Sud Ouest
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 
35 template <>
37 
38 class PropertyContext;
39 class Graph;
40 
41 typedef AbstractProperty<tlp::PointType, tlp::LineType> AbstractLayoutProperty;
42 typedef MinMaxProperty<tlp::PointType, tlp::LineType> LayoutMinMaxProperty;
43 
44 /**
45  * @ingroup Graph
46  * @brief A graph property that maps a tlp::Coord value to graph nodes and std::vector<tlp::Coord> for edges.
47  */
48 class TLP_SCOPE LayoutProperty : public LayoutMinMaxProperty {
49 public:
50  LayoutProperty(Graph *graph, std::string name="", bool updateOnEdgeReversal=true);
51 
52  // override some PropertyInterface methods
53  PropertyInterface* clonePrototype(Graph *, const std::string& );
54  static const std::string propertyTypename;
55  std::string getTypename() const {
56  return propertyTypename;
57  }
58 
59  //=======================================
60  //Methods for extra layout information
61  //=======================================
62 
63  /**
64  * Returns the maximum coordinate of the layout, i.e. the top-right corner of the induced bounding box
65  *
66  * @param subgraph If not null, returns the maximum coordinate for a sub-graph layout
67  **/
68  Coord getMax(Graph *subgraph=NULL);
69 
70  /**
71  * Returns the minimum coordinate of the layout, i.e. the bottom-left corner of the induced bounding box
72  *
73  * @param subgraph If not null, returns the minimum coordinate for a sub-graph layout
74  **/
75  Coord getMin(Graph *subgraph=NULL);
76 
77  //============================================
78  //Functions for layout modification
79  //============================================
80 
81  /**
82  * Translates the current layout according to a movement vector
83  *
84  * @param move a movement vector
85  * @param subgraph If not null, only translates the layout of that sub-graph
86  **/
87  void translate(const Vec3f &move, Graph *subgraph=NULL);
88 
89  /**
90  * Translates the layout of a set of nodes and edges provided through iterators
91  * according to a movement vector
92  *
93  * @param move a movement vector
94  * @param itNodes an iterator on graph nodes
95  * @param itEdges an iterator on graph edges
96  *
97  * @warning The iterators are not deleted
98  **/
99  void translate(const Vec3f &move, Iterator<node> *itNodes, Iterator<edge> *itEdges);
100 
101  /**
102  * Scales the current layout according to a vector of scale factors (sx, sy, sz).
103  *
104  * @param scaleFactors a vector of scale factors
105  * @param subgraph If not null, only scales the layout of that sub-graph
106  **/
107  void scale(const Vec3f &scaleFactors, Graph *subgraph=NULL);
108 
109  /**
110  * Scales the layout of a set of nodes and edges provided through iterators
111  * according to a vector of scale factors (sx, sy, sz).
112  *
113  * @param scaleFactors a vector of scale factors
114  * @param itNodes an iterator on graph nodes
115  * @param itEdges an iterator on graph edges
116  *
117  * @warning The iterators are not deleted
118  **/
119  void scale(const Vec3f &scaleFactors, Iterator<node> *itNodes, Iterator<edge> *itEdges);
120 
121  /**
122  * Rotates the layout around the X-axis according to an angle in degrees.
123  *
124  * @param alpha an angle in degrees
125  * @param subgraph If not null, only rotates the layout of that sub-graph
126  **/
127  void rotateX(const double &alpha, Graph *subgraph=NULL);
128 
129  /**
130  * Rotates the layout around the Y-axis according to an angle in degrees.
131  *
132  * @param alpha an angle in degrees
133  * @param subgraph If not null, only rotates the layout of that sub-graph
134  **/
135  void rotateY(const double &alpha, Graph *subgraph=NULL);
136 
137  /**
138  * Rotates the layout around the Z-axis according to an angle in degrees.
139  *
140  * @param alpha an angle in degrees
141  * @param subgraph If not null, only rotates the layout of that sub-graph
142  **/
143  void rotateZ(const double &alpha, Graph *subgraph=NULL);
144 
145  /**
146  * Rotates the layout around the X-axis of the nodes and edges provided
147  * through iterators according to an angle in degrees.
148  *
149  * @param alpha an angle in degrees
150  * @param itNodes an iterator on graph nodes
151  * @param itEdges an iterator on graph edges
152  *
153  * @warning The iterators are not deleted
154  **/
155  void rotateX(const double &alpha, Iterator<node> *itNodes, Iterator<edge> *itEdges);
156 
157  /**
158  * Rotates the layout around the Y-axis of the nodes and edges provided
159  * through iterators according to an angle in degrees.
160  *
161  * @param alpha an angle in degrees
162  * @param itNodes an iterator on graph nodes
163  * @param itEdges an iterator on graph edges
164  *
165  * @warning The iterators are not deleted
166  **/
167  void rotateY(const double &alpha, Iterator<node> *itNodes, Iterator<edge> *itEdges);
168 
169  /**
170  * Rotates the layout around the Z-axis of the nodes and edges provided through
171  * iterators according to an angle in degrees.
172  *
173  * @param alpha an angle in degrees
174  * @param itNodes an iterator on graph nodes
175  * @param itEdges an iterator on graph edges
176  *
177  * @warning The iterators are not deleted
178  **/
179  void rotateZ(const double &alpha, Iterator<node> *itNodes, Iterator<edge> *itEdges);
180 
181  /**
182  * Centers the layout, meaning translating it in order that
183  * the center of its bounding box is (0,0,0)
184  *
185  * @param subgraph If not null, only centers the layout of that sub-graph
186  **/
187  void center(Graph *subgraph=NULL);
188 
189  /**
190  * Centers the layout to newCenter, meaning translating it in order that
191  * the center of its bounding box is equal to newCenter
192  *
193  * @param newCenter the coordinate of the new layout center
194  * @param subgraph If not null, only centers the layout of that sub-graph
195  **/
196  void center(const Vec3f &newCenter, Graph *subgraph=NULL);
197 
198  /**
199  * Normalizes the layout, meaning dividing each nodes and edges coordinate by the maximum magnitude of the whole coordinates set
200  *
201  * @param subgraph If not null, only normalizes the layout of that sub-graph
202  **/
203  void normalize(Graph *subgraph=NULL);
204 
205  /**
206  * Scales the layout in order to approach an aspect ratio (width / height) of 1.0 .
207  **/
208  void perfectAspectRatio();
209 
210  //=======================================================================
211  // Set of function in order to measure the quality of the LayoutAlgorithm
212  //=======================================================================
213 
214  /**
215  * Returns the length of an edge, the bends are taken into account.
216  * Thus, it measure the length of a polyline.
217  *
218  * @param e the graph edge on which to compute its length
219  *
220  * @warning this function only measure the length of the polyline between bends,
221  * when using curves like Bézier etc... the result will not be the length of the curve.
222  **/
223  double edgeLength(const edge e) const;
224 
225  /**
226  * Returns the average edge length of the layout, the bends are taken into account
227  *
228  * @param subgraph If not null, only compute the average edge length for that sub-graph
229  **/
230  double averageEdgeLength(const Graph *subgraph=NULL) const;
231 
232  /**
233  * Returns the average angular resolution of the layout.
234  * It is only defined for 2D drawing, meaning the third coordinate
235  * is omitted
236  *
237  * @param subgraph It not null, only computes the average angular resolution for that sub-graph
238  **/
239  double averageAngularResolution(const Graph *subgraph=NULL) const;
240 
241  /**
242  * Returns the average angular resolution of a node.
243  * It is only defined for 2D drawing, meaning the third coordinate
244  * is omitted
245  *
246  * @param n the graph node on which to compute the angular resolution
247  * @param subgraph If not null, only computes the average angular resolution for the node in that sub-graph
248  **/
249  double averageAngularResolution(const node n, const Graph *subgraph=NULL) const;
250 
251  /**
252  * Returns a vector of all angular resolution of a node.
253  * It is only defined for 2D drawing, meaning the third coordinate
254  * is omitted
255  *
256  * @param n the graph node on which to compute the angular resolution
257  * @param subgraph If not null, only computes the average angular resolution for the node in that sub-graph
258  **/
259  std::vector<double> angularResolutions(const node n, const Graph *subgraph=NULL) const;
260 
261  /**
262  * Fixes embedding of the graph according to the layout
263  * ie. sort edges around nodes according to their neighbors/bends position in the layout/
264  * Only works in 2D, the third coordinate is not taken into account.
265  *
266  * @param subgraph It not null, only fixes embedding in that sub-graph
267  **/
268  void computeEmbedding(Graph *subgraph=NULL);
269 
270  /**
271  * Fixes embedding of the node according to the layout
272  * ie. sort edges around the node according to its neighbors/bends position in the layout/
273  * Only work in 2D, the third coordinate is not taken into account.
274  *
275  * @param n the graph node on which to fix embedding
276  * @param subgraph If not null, only fixes the embedding of the node in that sub-graph
277  **/
278  void computeEmbedding(const node n, Graph *subgraph=NULL);
279 
280  /**
281  * Returns the number of crossings in the layout
282  **/
283  unsigned int crossingNumber() const;
284 
285  // redefinition of some AbstractProperty methods
286  virtual void setNodeValue(const node, const Coord &v);
287  virtual void setEdgeValue(const edge, const std::vector<Coord> &v);
288  virtual void setAllNodeValue(const Coord &v);
289  virtual void setAllEdgeValue(const std::vector<Coord> &v);
290 
291 protected:
292 
293  virtual void clone_handler(AbstractProperty<tlp::PointType, tlp::LineType> &);
294 
295 private:
296  void resetBoundingBox();
297  void rotate(const double& alpha, int rot, Iterator<node> *, Iterator<edge> *);
298  // override Observable::treatEvent
299  void treatEvent(const Event&);
300 };
301 
302 /**
303  * @ingroup Graph
304  * @brief A graph property that maps a std::vector<tlp::Coord> value to graph elements.
305  */
306 class TLP_SCOPE CoordVectorProperty:public AbstractVectorProperty<tlp::CoordVectorType, tlp::PointType> {
307 public :
308  CoordVectorProperty(Graph *g, std::string n=""):AbstractVectorProperty<CoordVectorType, tlp::PointType>(g, n) {}
309  // redefinition of some PropertyInterface methods
310  PropertyInterface* clonePrototype(Graph *, const std::string& );
311  static const std::string propertyTypename;
312  std::string getTypename() const {
313  return propertyTypename;
314  }
315 
316 };
317 
318 typedef CoordVectorProperty LayoutVectorProperty;
319 
320 
321 
322 }
323 #endif