Mainpage.dox

   1 /**
   2 @mainpage WarpTree
   3
   4 WarpTree provides a widget, WarpTreeView, that can display any hierarchical data set.
   5
   6 - \ref warped
   7 - \ref features
   8 - \ref examples
   9 - \ref using
  10 - \ref designer
  11
  12 \authors Jos van den Oever
  13
  14 License: LGPL
  15
  16 @section warped Warped space
  17
  18 The amount of data people are handling day to day is steadily increasing. Getting an overview of a large data sets can be a daunting task. For visualizing near-infinite data sets, one would need a near-infinite screen size. Or a convenient way of mapping the infinite screensize to a finite area. Such a methods exist. A popular method is to lay the data out in a hyperbolic plane and visualizing this on a Poincaré disk. Such a disk has a high resolution view of the plane in thecenter and a low resolution on the edges. The Poincaré disk was nice visualized by the Dutch graphic artist <a href="http://en.wikipedia.org/wiki/M._C._Escher">M.C. Escher</a>.
  19
  20 \image html "../images/bi.jpg" "Circle Limit I by MC Escher"
  21 \image latex "../images/bi.eps" "Circle Limit I by MC Escher"
  22
  23 As you can see from the drawing, this information is projected on a circle. This is a bit wasteful on standard computer screens that are usually rectangular. So if one uses a circular projection, the amount of space wasted is at least 20%.
  24
  25 For this reason, we came up with a different projection which we simply call 'warped'. It is the same as the projection above, but points are extended from the center of the projection to the edge of the containing rectangle. If we apply this method to 'Circle Limit I' we get this image:
  26
  27 \image html "../images/bu.jpg" "Square Limit I generated with warp"
  28 \image latex "../images/bu.eps" "Square Limit I generated with warp"
  29
  30
  31 @section qabstract QAbstractItemModel and QAbstractItemView
  32
  33 One of the most powerfull new features in Qt4 is the introduction of a Model/View paradigm. The most important classes of this paradigm are QAbstractItemModel and QAbstractItemView. If you can present your data in QAbstractItemModel, you can use one of the implementations of QAbstractItemView classes to display the data. So the QAbstractItemModel is more or less the standard format for more complex data in Qt and it is a natural choice to implement WarpTree as a QAbstractItemView. Using QAbstractItemView really allows us be more creative with less code.
  34
  35 So what type of view is WarpTreeView? It is a bit like a <a href="http://doc.trolltech.com/4.3/qtreeview.html">QTreeView</a>, but for larger data sets. The best way to understand it is to use it.
  36
  37 \image html "../images/round.png" "Showing the graph on a unit disc."
  38 \image latex "../images/round.eps" "Showing the graph on a unit disc."
  39
  40 \image html "../images/rect.png" "Showing the graph in WarpTreeView."
  41 \image latex "../images/rect.eps" "Showing the graph in WarpTreeView."
  42
  43 @section features Features
  44
  45 - dynamic loading of the network
  46 - showing labels of nodes if there is room for them regardless of position in
  47   the hierarchy
  48 - no overlapping labels
  49 - adaptable to different datatypes and styles by implementing a WarpNodePainter
  50 - zooming with the mousewheel to see different levels of detail
  51 - change the projection with cursor keys and &lt;Home> or by dragging the tree
  52 - show tooltips if the model provides information for them
  53
  54 @section examples Examples
  55
  56 @subsection dirview DirView
  57
  58 DirView is a simple application that uses a QDirModel to browse your files. Looking at the code is very insightfull if you want to start using WarpTreeView. Here you see a screenshot of DirView. On the left you see a normal QTreeView and on the right you see the WarpTreeView. The two views share the same data model and the same selection model. This means that if you select an item in one view, it is also selected in the other view.
  59
  60 The way the background, the nodes and the lines are drawn can be customized by subclassing WarpNodePainter. The default WarpNodePainter does not draw a background. In DirView, an adapted WarpNodePainter is used: if the active file is a picture, ImageNodePainter draws the picture in the background of the view. This allows the user to browse for pictures while keeping an eye on the potentially large directory structure.
  61
  62 \image html "../images/dirview.png" "The DirView example application showing an image preview."
  63 \image latex "../images/dirview.eps" "The DirView example application showing an image preview."
  64
  65 \image html "../images/windirview.png" "The DirView example application running under Windows XP."
  66 \image latex "../images/windirview.eps" "The DirView example application running under Windows XP."
  67
  68 The information in the view is loaded dynamically from the QAbstractItemModel so the user does not have to wait until the entire data model has been scanned. In DirView, you can see how this works, because data shows up as it is loaded into the view. This asynchronous behaviour a very important feature, because a data model might be slow or large.
  69
  70 @subsection treeoflife The Tree of Life
  71
  72 The <a href="tolweb.org">Tree of Life</a> is a website where information is collected about the history of evolution. The tree of life describes which species evolved from which other species. This history can be seen as a big tree which is rooted in the primordial sea, the start of all life. We, humans, are but one of the leaves of this tree. The entire tree currently contains almost 100.000 species. With the WarpTreeView, you can conveniently browse this entire tree.
  73
  74 The program 'tol', that comes with this package, allows you to view the tree. You can start it with 'tol'. This loads a phylogeny with 88000 nodes. This is what you see:
  75
  76 \image html "../images/zoom.png" "Zoomed out view of the tree of life."
  77 \image latex "../images/zoom.eps" "Zoomed out view of the tree of life."
  78
  79 \image html "../images/zoom2.png" "Far zoomed out view of the tree of life."
  80 \image latex "../images/zoom2.eps" "Far zoomed out view of the tree of life."
  81
  82 \image html "../images/zoomtooltip.png" "Zoomed in view of the tree of life with tooltip."
  83 \image latex "../images/zoomtooltip.eps" "Zoomed in view of the tree of life with tooltip."
  84
  85 You can zoom in or out with the mouse-wheel and move around in the tree by dragging it or by using the cursor keys. By clicking on an entry, you move it to the middle of the widget and by hovering over an entry you can activate a tooltip with more information.
  86
  87 The data from the tree of life can be used for non-commercial use as is stated on <a href="http://www.tolweb.org/tree/home.pages/downloadtree.html">the download website</a>.
  88
  89 @section using Using WarpTree
  90
  91 You can use WarpTree by instanciating a WarpTreeView and adding your data to it in the form of a QAbstractItemModel. Examples on how to do it can be found in dirview/main.cpp and treeoflife/tol.cpp.
  92
  93 All you need to use the widget is the dynamic library and the header 'warptreeview.h'.
  94
  95 @subsection designer Integration in Qt Designer
  96
  97 WarpTree comes with a plugin that, when installed, shows up in Qt Designer automatically. It appears in the widget sidebar and can be dragged onto dialogs and applicion windows like any other widget.
  98
  99 @subsection additional
 100
 101 \image html "../images/expand.png" "Schema showing how the warped widget makes better use of the available space by mapping from a cirkel to a square."
 102 \image latex "../images/expand.eps" "Schema showing how the warped widget makes better use of the available space by mapping from a cirkel to a square."
 103
 104 Additional information on hyperbolic planes can be found in the hypertree project. There is a nice paper in there: <a href="http://hypertree.cvs.sourceforge.net/%2Acheckout%2A/hypertree/hypertree/article/principal_hypertree.ps">article on displaying a network on a hyperbolic plane</a>.
 105
 106
 107 */