1 /*! @mainpage HippoDraw Library Overview
4 The design of this tool kit is an attempt to decompose into
5 abstractions the process of displaying data in various ways on the
6 screen or printer. Thus, there are a number of class hierarchies
7 with each hierarchy representing an aspect of the decomposition.
10 The base classes are partially pure abstract in that they contain pure
11 virtual member functions. However, they also contain some concrete
12 implementation when it is deemed appropriate. That is where the
13 majority of all derived classes will want to share a common
17 This overview of the library will present the overview each class
18 hierarchy along with an overview of the object data structure. It is
19 easier to understand the purpose of each class hierarchy in context of
20 the object data structure.
22 The class hierarchies are
28 @ref overview_transform
32 @ref overview_projector
34 @ref overview_projectedvalue
36 @ref overview_pointrep
40 @ref overview_binneraxis
42 @ref overview_function
44 @section overview_view View
46 A view object is responsible for all drawing to a display device.
47 Typically, a display device is a computer's display screen or a file
48 sent to a printer. The base class for the view hierarchy is mostly
49 abstract. All drawing is done by the interface defined by this
50 class. A derived class provides a concrete implementation and probably
51 relies on a particular graphics toolkit. An example is QtView which
53 <a href="http://www.trolltech.com/products/qt/index.html" >
57 A view is an Observer of a PlotterBase object, the base class of @ref
58 overview_plotter hierarchy. When it receives the Observer::update message, it
59 initiates drawing by calling back the PlotterBase object with a
62 The base class for view is ViewBase. See the documentation for
63 ViewBase for more details.
65 @section overview_plotter Plotter
67 A plotter is the manager of all drawing and controller of the axis
68 scales. It delegates the actual drawing to members of other
69 hierarchies. The axis are drawn by a derived class of AxisRepBase.
70 The drawing of the data representation is done by a @ref
71 overview_datarep. More than one data representation can be drawn in
74 The axis scales are maintained by derived class of AxisModelBase. A
75 plotter also owns a @ref overview_transform which may transform the
76 data values from one coordinate system to another. For example, if
77 the Y axis is on a logarithmic scale, it is a @ref overview_transform
78 object that does the transformation.
80 A plotter is an Observer of its @ref overview_datarep objects and an
83 The base class for plotters is PlotterBase. See the documentation for
84 PlotterBase for more details.
87 @section overview_transform Transform
89 Before drawing a view, a @ref overview_pointrep object uses a transform
90 object to transform from one coordinate to a another coordinate.
91 A frequently used example of this feature is for Y axis to be on a
92 logarithm scale rather than a linear scale.
94 A transform is usually based on two coordinates, X and Y and the
95 BinaryTransform class represents this abstraction. However,
96 frequently the transform on the X and Y axis are independent of each
97 other. The XYTransform class implements this kind of binary transform.
98 It uses two objects that do the transform on each axis. These objects
99 instances of classes derived from UnaryTransform.
101 Transforms in which the coordinates on the X and Y axis are not
102 independent are also possible. For example, the HammerAito transform implements a form of binary transform that
103 uses latitude and longitude coordinates create
104 <a href="http://www.hypermaths.org/quadibloc/maps/meq0801.htm">
105 Hammer-Aitoff projection</a>.
107 The base class for transforms is TransformBase. However, it is not
108 used directly since the minimum transform requires two coordinates.
109 See the documentation for TransformBase for more details.
112 @section overview_datarep Data Representation
114 A data representation is responsible for both transforming the raw
115 data to values projected on the display device and managing their
116 drawing. The simplest of data representations is the ScatterPlot.
117 It takes a pair of raw data values, creates a @ref
118 overview_projectedvalue by taking one as an X coordinate and the other
119 as Y coordinate. A more complex one is a DyHistogram which takes a
120 single set of raw data, histograms them, and creates a set @ref
121 overview_projectedvalue objects based on the histogram contents. A
122 plot using a DyHistogram data representation is shown below.
124 @image html dyhistogram.png "DyHistogram data representation"
125 @image latex dyhistogram.eps "DyHistogram data representation"
127 A data representation delegates the task of dealing with the raw data
128 to a @ref overview_projector. It also delegates its task of draw the
129 @ref overview_projectedvalue object to a @ref overview_pointrep.
131 The base class for data representation classes is DataRep. Most of
132 the functionality of the data representation is implemented in this
133 base class. Derived classes have constructor to instantiates a @ref
134 overview_projector and @ref overview_projectedvalue appropriate for
135 their representation.
137 A data representation is an Observer of its @ref overview_projector
138 and is an Observable.
140 See the documentation for DataRep for more details.
144 @section overview_projector Projector
146 Projectors are responsible for dealing with the raw data and providing
147 a set of @ref overview_projectedvalue objects. For example, the
148 DyHist1DProjector reads a set of raw data, creates a histogram, and
149 uses its bin contents to create the set of @ref
150 overview_projectedvalue objects.
152 Some projectors delegate part of their tasks to other objects. For
153 example, a BinningProjector uses a @ref overview_binner. The
154 projector provides the binner with the set of values then asks it to
155 create the projected value objects.
157 Projectors provide access to the @ref overview_projectedvalue objects
158 rows in a NTuple object. Multiple clients access this %NTuple object.
159 For example, the @ref overview_pointrep objects use it for drawing.
160 The objective function of the fitter access the same %NTuple object.
161 When @b HippoDraw is used as a Python extension module, the %NTuple
162 objects is available to it as well.
164 Some projectors are Observer objects and all are Observable. For
165 example, the NTupleProjector is an observer of an NTuple object. When
166 it receives the Observer::update message, it marks itself as needing
167 to re-create the projected values and sends an update message to its
170 The base class for projector is ProjectorBase. @sa ProjectorBase
171 documentation for more details.
174 @section overview_projectedvalue Projected Value
176 A projected value represents a coordinate and a value with an optional
177 error on the value. For projected values created by the mechanism of
178 binning, such as for a histogram, the projected value will also
179 contain the bin width.
181 A projected value is represented as a tuple and implemented as a C++
182 standard library @c vector<double>. The indexes into this vector is
183 managed by a enumeration within a namespace. For 2D values,
184 hippodraw::DataPoint2DTuple is used while for 3D values,
185 hippodraw::DataPoint3DTuple is used. The reason for using this
186 technique is to avoid creation of a new classes, which for technical
187 reasons would have a virtual base class, whose sole purpose would be
188 to convey the tuple data to the clients.
190 @section overview_pointrep Point representation
192 Given a projected value, there may be a number of ways to represent it
193 graphically. This is what is called a point representation in this
194 tool kit. An example is a symbol such as a square or circle
195 representing a coordinate position in X and Y as shown below.
197 @image html symbolpointrepsolidsquare.png
198 @image latex symbolpointrepsolidsquare.eps
201 The base class for point representation is RepBase. See the
202 documentation for RepBase for more details.
205 @section overview_binner Binner
207 Binners are responsible for taking a value consisting of one or more
208 raw data points and accumulating them in some fashion into bins.
209 Binners are used by a member of the BinningProjector class hierarchy.
210 An example of a simple binner is the Bins1DHist binner which takes a
211 single data point and accumulates a histogram.
213 Binners do the accumulation into bins, but not the calculation of which
214 bin needs to be accumulated. It delegates that task to a member of
215 the @ref overview_binneraxis class hierarchy.
217 The base class for Binners is the BinsBase class. See the
218 documentation for BinsBase for more details.
221 @section overview_binneraxis Binner Axis
223 Binner Axis classes are responsible tor taking a raw data point of one or
224 more values and calculating the indexes of the bin to be accumulated.
225 The simplest is the BinnerAxisLinear which assumes bins for equal width
226 with a certain range. A more complex one is BinnerAxisLog, which
227 calculates bin edges that are logarithmically increasing in size. These
228 are the only two implemented at the moment, but others could follow.
230 The implemented classes take a single @c double as a coordinate, but
231 this could be generalized in the future. If one wants two doubles,
232 and the two coordinates are independent, then two of these classes
233 could be used, as is the case with classes derived from Bins2DBase. A
234 coordinate representing a time or date might be considered for future
235 implementation, but will certainly requires changes to other class
238 The base class for binner axis is BinnerAxis. See the
239 documentation for BinnerAxis for more details.
243 @section overview_function Function
245 The function classes serves two purposes. One is to display a function
246 as an overlaid on a DataRep. The second is to interact with a fitting
247 program to determine the value of the function's parameters that give
250 The base class for functions is FunctionBase. See the documentation
251 for FunctionBase for more details.
