KWWidgets
debian/tmp/usr/include/KWWidgets/vtkKWParameterValueFunctionInterface.h
Go to the documentation of this file.
1 /*=========================================================================
2 
3  Module: $RCSfile: vtkKWParameterValueFunctionInterface.h,v $
4 
5  Copyright (c) Kitware, Inc.
6  All rights reserved.
7  See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
8 
9  This software is distributed WITHOUT ANY WARRANTY; without even
10  the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
11  PURPOSE. See the above copyright notice for more information.
12 
13 =========================================================================*/
14 // .NAME vtkKWParameterValueFunctionInterface - a parameter/value function editor/interface
15 // .SECTION Description
16 // A widget that allows the user to edit a parameter/value function
17 // interactively. This abstract class is the first abstract stage of
18 // vtkKWParameterValueFunctionEditor, which in turns provides most of the
19 // user-interface functionality.
20 // This class was created to take into account the amount of code and
21 // the complexity of vtkKWParameterValueFunctionEditor, most of which should
22 // not be a concern for developpers.
23 // As a superclass it emphasizes and tries to document which pure virtual
24 // methods *needs* to be implemented in order to create an editor tailored
25 // for a specific kind of parameter/value function. It only describes
26 // the low-level methods that are required to manipulate a function in
27 // a user-interface independent way. For example, given the id (rank) of a
28 // point in the function, how to retrieve its corresponding parameter and/or
29 // value(s) ; how to retrieve the dimensionality of a point ; how to
30 // interpolate the value of a point over the parameter range, etc.
31 // Its subclass vtkKWParameterValueFunctionEditor uses those methods
32 // to create and manage a graphical editor, without concrete knowledge of
33 // what specific class the function relates to.
34 // The subclasses of vtkKWParameterValueFunctionEditor provide a concrete
35 // implementation of vtkKWParameterValueFunctionEditor by tying up a
36 // specific class of function to the methods below. For example, the class
37 // vtkKWPiecewiseFunctionEditor manipulates instances of vtkPiecewiseFunction
38 // internally as functions: the methods below are implemented as proxy to the
39 // vtkPiecewiseFunction methods.
40 // Same goes vtkKWColorTransferFunctionEditor, which manipulates instances of
41 // vtkColorTransferFunction internally.
42 // .SECTION Thanks
43 // This work is part of the National Alliance for Medical Image
44 // Computing (NAMIC), funded by the National Institutes of Health
45 // through the NIH Roadmap for Medical Research, Grant U54 EB005149.
46 // Information on the National Centers for Biomedical Computing
47 // can be obtained from http://nihroadmap.nih.gov/bioinformatics.
48 // .SECTION See Also
49 // vtkKWParameterValueFunctionEditor vtkKWPiecewiseFunctionEditor vtkKWColorTransferFunctionEditor
50 
51 #ifndef __vtkKWParameterValueFunctionInterface_h
52 #define __vtkKWParameterValueFunctionInterface_h
53 
54 #include "vtkKWWidgetWithLabel.h"
55 
57 {
58 public:
60  void PrintSelf(ostream& os, vtkIndent indent);
61 
62  // Description:
63  // Return 1 if there is a function associated to the editor.
64  // It is used, among *other* things, to disable the UI automatically if
65  // there is nothing to edit at the moment.
66  virtual int HasFunction() = 0;
67 
68  // Description:
69  // Return the number of points/elements in the function
70  virtual int GetFunctionSize() = 0;
71 
72  // Description:
73  // This probably should not be hard-coded, but will make our life easier.
74  // It specificies the maximum dimensionality of a point (not the *number*
75  // of points). For example, for a RGB color transfer function editor, each
76  // point has a dimensionality of 3 (see GetFunctionPointDimensionality).
77  //BTX
78  enum
79  {
80  MaxFunctionPointDimensionality = 20
81  };
82  //ETX
83 
84  // *******************************************************************
85  // The following methods are fast low-level manipulators: do *not* check if
86  // points can added/removed or are locked, it is up to the higer-level
87  // methods to do it (see vtkKWParameterValueFunctionEditor for example,
88  // AddFunctionPointAtParameter() will use the low-level
89  // FunctionPointCanBeRemoved() and RemoveFunctionPoint() below).
90  // Points are usually accessed by 'id', which is pretty much its rank
91  // in the function (i.e., the 0-th point is the first point and has id = 0,
92  // the next point has id = 1, etc., up to GetFunctionSize() - 1)
93  // *******************************************************************
94 
95  // Description:
96  // Return the modification time of the function (a monotonically increasing
97  // value changing each time the function is modified)
98  virtual unsigned long GetFunctionMTime() = 0;
99 
100  // Description:
101  // Get the 'parameter' at point 'id'
102  // Ex: a scalar range, or a instant in a timeline.
103  // Return 1 on success, 0 otherwise
104  virtual int GetFunctionPointParameter(int id, double *parameter) = 0;
105 
106  // Description:
107  // Get the dimensionality of the points in the function
108  // (Ex: 3 for a RGB point, 1 for a boolean value or an opacity value)
109  virtual int GetFunctionPointDimensionality() = 0;
110 
111 protected:
112  // Description:
113  // Interpolate and get the 'n-tuple' value at a given 'parameter' (where
114  // 'n' is the dimensionality of the point). In other words, compute the
115  // value of a point as if it was located at a given parameter over the
116  // parameter range of the function). Note that 'values' has to be allocated
117  // with enough room. The interpolation method is function dependent
118  // (linear in the vtkKWPiecewiseFunctionEditor class for example).
119  // Return 1 on success, 0 otherwise
120 
121  virtual int InterpolateFunctionPointValues(double parameter,double *values)=0;
122  // Description:
123  // Description:
124  // Get the 'n-tuple' value at point 'id' (where 'n' is the dimensionality of
125  // the point). Note that 'values' has to be allocated with enough room.
126  // Return 1 on success, 0 otherwise
127  virtual int GetFunctionPointValues(int id, double *values) = 0;
128 
129  // Description:
130  // Set the 'n-tuple' value at point 'id' (where 'n' is the dimensionality of
131  // the point). Note that the point has to exist.
132  // Return 1 on success, 0 otherwise
133  virtual int SetFunctionPointValues(int id, const double *values) = 0;
134 
135  // Add a 'n-tuple' value at a given 'parameter' over the parameter range
136  // (where 'n' is the dimensionality of the point), and return the
137  // corresponding point 'id' (the rank of the newly added point in the
138  // function).
139  // Return 1 on success, 0 otherwise
140  virtual int AddFunctionPoint(double parameter,const double *values,int *id)=0;
141  // Description:
142  // Set the 'parameter' *and* 'n-tuple' value at point 'id' (where 'n' is the
143  // dimensionality of the point). Note that the point has to exist.
144  // It basically *moves* the point to a new location over the parameter range
145  // and change its value simultaneously. Note that doing so should really
146  // *not* change the rank/id of the point in the function, otherwise things
147  // might go wrong (untested). Basically it means that points can
148  // not be moved "over" other points, i.e. when you drag a point in the
149  // editor, you can not move it "before" or "past" its neighbors, which makes
150  // sense anyway (I guess), but make sure the constraint is enforced :)
151  // Return 1 on success, 0 otherwise
152  virtual int SetFunctionPoint(int id, double parameter, const double *values)=0;
153 
154  // Description:
155  // Remove a function point 'id'.
156  // Note: do not use FunctionPointCanBeRemoved() inside that function, it
157  // has been done for you already in higher-level methods.
158  // Return 1 on success, 0 otherwise
159  virtual int RemoveFunctionPoint(int id) = 0;
160 
161  // *******************************************************************
162  // The following low-level methods can be reimplemented, but a default
163  // implementation is provided either by this class or by
164  // vtkKWParameterValueFunctionEditor and is working just fine.
165  // If you have to reimplement them (for efficiency reasons for example),
166  // make sure to call the corresponding superclass method too
167  // (or have a good reason not to :).
168  // Those methods are used by high-level methods, and should
169  // not be called from the other low-level methods described above
170  // (see vtkKWParameterValueFunctionEditor for example, the high-level
171  // AddFunctionPointAtParameter() method will use the low-level
172  // below FunctionPointCanBeRemoved() and above RemoveFunctionPoint()).
173  // *******************************************************************
174 
175 public:
176  // Description:
177  // Get the 'id' of the point at parameter 'parameter', if *any*.
178  // The current implementation is probably not too efficient as it
179  // loops over all points, call GetFunctionPointParameter and return
180  // the corresponding id if the parameter that was retrieved matches.
181  // Return 1 on success, 0 otherwise
182  virtual int GetFunctionPointId(double parameter, int *id);
183 
184  // Description:
185  // Return 1 if a point can be added to the function, 0 otherwise.
186  // Ex: there might be many reasons why a function could be "locked", it
187  // depends on your implementation, but here is the hook.
188  virtual int FunctionPointCanBeAdded() = 0;
189 
190  // Description:
191  // Return 1 if the point 'id' can be removed from the function, 0 otherwise.
192  virtual int FunctionPointCanBeRemoved(int id) = 0;
193 
194  // Description:
195  // Return 1 if the 'parameter' of the point 'id' is locked (can/should
196  // not be changed/edited), 0 otherwise.
197  virtual int FunctionPointParameterIsLocked(int id) = 0;
198 
199  // Description:
200  // Return 1 if the 'n-tuple' value of the point 'id' is locked (can/should
201  // not be changed/edited), 0 otherwise.
202  // Note that by default point with dimensionality > 1 will be placed in the
203  // center of the editor, as the is no way to edit a n-dimensional point
204  // in a 2D editor. Still, some editors (see vtkKWColorTransferFunctionEditor
205  // will provide 3 text entries to allow the point value(s) to be edited).
206  virtual int FunctionPointValueIsLocked(int id) = 0;
207 
208  // Description:
209  // Return 1 if the point 'id' can be moved over the parameter range to a
210  // new 'parameter', 0 otherwise.
211  // vtkKWParameterValueFunctionEditor provides a default implementation
212  // preventing the point to be moved outside the parameter range, or
213  // if the parameter is locked, or if it is passing over or before its
214  // neighbors.
215  virtual int FunctionPointCanBeMovedToParameter(int id, double parameter) = 0;
216 
217 protected:
220 
221  // Description:
222  // Create the widget.
223  virtual void CreateWidget();
224 
225  // Description:
226  // Return 1 if the function line joining point 'id1' and point 'id2'
227  // needs to be sampled at regular interval (instead of a straight line).
228  // If the interpolation function InterpolateFunctionPointValues is not
229  // linear, it is likely that this function should return 1 so that the
230  // line that is drawn between the two points is not a straight line but a
231  // set of segments computed by sampling between each end-points. Yet,
232  // it does not have to be *always* resampled, given the property of the
233  // interpolant, some cases may end up requiring just a straight line,
234  // which can be drawn much more efficiently.
235  virtual int FunctionLineIsSampledBetweenPoints(int id1, int id2);
236 
237 private:
239  void operator=(const vtkKWParameterValueFunctionInterface&); // Not implemented
240 };
241 
242 #endif