00001 /*========================================================================= 00002 00003 Module: $RCSfile: vtkKWParameterValueFunctionInterface.h,v $ 00004 00005 Copyright (c) Kitware, Inc. 00006 All rights reserved. 00007 See Copyright.txt or http://www.kitware.com/Copyright.htm for details. 00008 00009 This software is distributed WITHOUT ANY WARRANTY; without even 00010 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR 00011 PURPOSE. See the above copyright notice for more information. 00012 00013 =========================================================================*/ 00014 // .NAME vtkKWParameterValueFunctionInterface - a parameter/value function editor/interface 00015 // .SECTION Description 00016 // A widget that allows the user to edit a parameter/value function 00017 // interactively. This abstract class is the first abstract stage of 00018 // vtkKWParameterValueFunctionEditor, which in turns provides most of the 00019 // user-interface functionality. 00020 // This class was created to take into account the amount of code and 00021 // the complexity of vtkKWParameterValueFunctionEditor, most of which should 00022 // not be a concern for developpers. 00023 // As a superclass it emphasizes and tries to document which pure virtual 00024 // methods *needs* to be implemented in order to create an editor tailored 00025 // for a specific kind of parameter/value function. It only describes 00026 // the low-level methods that are required to manipulate a function in 00027 // a user-interface independent way. For example, given the id (rank) of a 00028 // point in the function, how to retrieve its corresponding parameter and/or 00029 // value(s) ; how to retrieve the dimensionality of a point ; how to 00030 // interpolate the value of a point over the parameter range, etc. 00031 // Its subclass vtkKWParameterValueFunctionEditor uses those methods 00032 // to create and manage a graphical editor, without concrete knowledge of 00033 // what specific class the function relates to. 00034 // The subclasses of vtkKWParameterValueFunctionEditor provide a concrete 00035 // implementation of vtkKWParameterValueFunctionEditor by tying up a 00036 // specific class of function to the methods below. For example, the class 00037 // vtkKWPiecewiseFunctionEditor manipulates instances of vtkPiecewiseFunction 00038 // internally as functions: the methods below are implemented as proxy to the 00039 // vtkPiecewiseFunction methods. 00040 // Same goes vtkKWColorTransferFunctionEditor, which manipulates instances of 00041 // vtkColorTransferFunction internally. 00042 // .SECTION Thanks 00043 // This work is part of the National Alliance for Medical Image 00044 // Computing (NAMIC), funded by the National Institutes of Health 00045 // through the NIH Roadmap for Medical Research, Grant U54 EB005149. 00046 // Information on the National Centers for Biomedical Computing 00047 // can be obtained from http://nihroadmap.nih.gov/bioinformatics. 00048 // .SECTION See Also 00049 // vtkKWParameterValueFunctionEditor vtkKWPiecewiseFunctionEditor vtkKWColorTransferFunctionEditor 00050 00051 #ifndef __vtkKWParameterValueFunctionInterface_h 00052 #define __vtkKWParameterValueFunctionInterface_h 00053 00054 #include "vtkKWWidgetWithLabel.h" 00055 00056 class KWWidgets_EXPORT vtkKWParameterValueFunctionInterface : public vtkKWWidgetWithLabel 00057 { 00058 public: 00059 vtkTypeRevisionMacro(vtkKWParameterValueFunctionInterface,vtkKWWidgetWithLabel); 00060 void PrintSelf(ostream& os, vtkIndent indent); 00061 00062 // Description: 00063 // Return 1 if there is a function associated to the editor. 00064 // It is used, among *other* things, to disable the UI automatically if 00065 // there is nothing to edit at the moment. 00066 virtual int HasFunction() = 0; 00067 00068 // Description: 00069 // Return the number of points/elements in the function 00070 virtual int GetFunctionSize() = 0; 00071 00072 // Description: 00073 // This probably should not be hard-coded, but will make our life easier. 00074 // It specificies the maximum dimensionality of a point (not the *number* 00075 // of points). For example, for a RGB color transfer function editor, each 00076 // point has a dimensionality of 3 (see GetFunctionPointDimensionality). 00077 //BTX 00078 enum 00079 { 00080 MaxFunctionPointDimensionality = 20 00081 }; 00082 //ETX 00083 00084 // ******************************************************************* 00085 // The following methods are fast low-level manipulators: do *not* check if 00086 // points can added/removed or are locked, it is up to the higer-level 00087 // methods to do it (see vtkKWParameterValueFunctionEditor for example, 00088 // AddFunctionPointAtParameter() will use the low-level 00089 // FunctionPointCanBeRemoved() and RemoveFunctionPoint() below). 00090 // Points are usually accessed by 'id', which is pretty much its rank 00091 // in the function (i.e., the 0-th point is the first point and has id = 0, 00092 // the next point has id = 1, etc., up to GetFunctionSize() - 1) 00093 // ******************************************************************* 00094 00095 // Description: 00096 // Return the modification time of the function (a monotonically increasing 00097 // value changing each time the function is modified) 00098 virtual unsigned long GetFunctionMTime() = 0; 00099 00100 // Description: 00101 // Get the 'parameter' at point 'id' 00102 // Ex: a scalar range, or a instant in a timeline. 00103 // Return 1 on success, 0 otherwise 00104 virtual int GetFunctionPointParameter(int id, double *parameter) = 0; 00105 00106 // Description: 00107 // Get the dimensionality of the points in the function 00108 // (Ex: 3 for a RGB point, 1 for a boolean value or an opacity value) 00109 virtual int GetFunctionPointDimensionality() = 0; 00110 00111 protected: 00112 // Description: 00113 // Interpolate and get the 'n-tuple' value at a given 'parameter' (where 00114 // 'n' is the dimensionality of the point). In other words, compute the 00115 // value of a point as if it was located at a given parameter over the 00116 // parameter range of the function). Note that 'values' has to be allocated 00117 // with enough room. The interpolation method is function dependent 00118 // (linear in the vtkKWPiecewiseFunctionEditor class for example). 00119 // Return 1 on success, 0 otherwise 00120 00121 virtual int InterpolateFunctionPointValues(double parameter,double *values)=0; 00122 // Description: 00123 // Description: 00124 // Get the 'n-tuple' value at point 'id' (where 'n' is the dimensionality of 00125 // the point). Note that 'values' has to be allocated with enough room. 00126 // Return 1 on success, 0 otherwise 00127 virtual int GetFunctionPointValues(int id, double *values) = 0; 00128 00129 // Description: 00130 // Set the 'n-tuple' value at point 'id' (where 'n' is the dimensionality of 00131 // the point). Note that the point has to exist. 00132 // Return 1 on success, 0 otherwise 00133 virtual int SetFunctionPointValues(int id, const double *values) = 0; 00134 00135 // Add a 'n-tuple' value at a given 'parameter' over the parameter range 00136 // (where 'n' is the dimensionality of the point), and return the 00137 // corresponding point 'id' (the rank of the newly added point in the 00138 // function). 00139 // Return 1 on success, 0 otherwise 00140 virtual int AddFunctionPoint(double parameter,const double *values,int *id)=0; 00141 // Description: 00142 // Set the 'parameter' *and* 'n-tuple' value at point 'id' (where 'n' is the 00143 // dimensionality of the point). Note that the point has to exist. 00144 // It basically *moves* the point to a new location over the parameter range 00145 // and change its value simultaneously. Note that doing so should really 00146 // *not* change the rank/id of the point in the function, otherwise things 00147 // might go wrong (untested). Basically it means that points can 00148 // not be moved "over" other points, i.e. when you drag a point in the 00149 // editor, you can not move it "before" or "past" its neighbors, which makes 00150 // sense anyway (I guess), but make sure the constraint is enforced :) 00151 // Return 1 on success, 0 otherwise 00152 virtual int SetFunctionPoint(int id, double parameter, const double *values)=0; 00153 00154 // Description: 00155 // Remove a function point 'id'. 00156 // Note: do not use FunctionPointCanBeRemoved() inside that function, it 00157 // has been done for you already in higher-level methods. 00158 // Return 1 on success, 0 otherwise 00159 virtual int RemoveFunctionPoint(int id) = 0; 00160 00161 // ******************************************************************* 00162 // The following low-level methods can be reimplemented, but a default 00163 // implementation is provided either by this class or by 00164 // vtkKWParameterValueFunctionEditor and is working just fine. 00165 // If you have to reimplement them (for efficiency reasons for example), 00166 // make sure to call the corresponding superclass method too 00167 // (or have a good reason not to :). 00168 // Those methods are used by high-level methods, and should 00169 // not be called from the other low-level methods described above 00170 // (see vtkKWParameterValueFunctionEditor for example, the high-level 00171 // AddFunctionPointAtParameter() method will use the low-level 00172 // below FunctionPointCanBeRemoved() and above RemoveFunctionPoint()). 00173 // ******************************************************************* 00174 00175 public: 00176 // Description: 00177 // Get the 'id' of the point at parameter 'parameter', if *any*. 00178 // The current implementation is probably not too efficient as it 00179 // loops over all points, call GetFunctionPointParameter and return 00180 // the corresponding id if the parameter that was retrieved matches. 00181 // Return 1 on success, 0 otherwise 00182 virtual int GetFunctionPointId(double parameter, int *id); 00183 00184 // Description: 00185 // Return 1 if a point can be added to the function, 0 otherwise. 00186 // Ex: there might be many reasons why a function could be "locked", it 00187 // depends on your implementation, but here is the hook. 00188 virtual int FunctionPointCanBeAdded() = 0; 00189 00190 // Description: 00191 // Return 1 if the point 'id' can be removed from the function, 0 otherwise. 00192 virtual int FunctionPointCanBeRemoved(int id) = 0; 00193 00194 // Description: 00195 // Return 1 if the 'parameter' of the point 'id' is locked (can/should 00196 // not be changed/edited), 0 otherwise. 00197 virtual int FunctionPointParameterIsLocked(int id) = 0; 00198 00199 // Description: 00200 // Return 1 if the 'n-tuple' value of the point 'id' is locked (can/should 00201 // not be changed/edited), 0 otherwise. 00202 // Note that by default point with dimensionality > 1 will be placed in the 00203 // center of the editor, as the is no way to edit a n-dimensional point 00204 // in a 2D editor. Still, some editors (see vtkKWColorTransferFunctionEditor 00205 // will provide 3 text entries to allow the point value(s) to be edited). 00206 virtual int FunctionPointValueIsLocked(int id) = 0; 00207 00208 // Description: 00209 // Return 1 if the point 'id' can be moved over the parameter range to a 00210 // new 'parameter', 0 otherwise. 00211 // vtkKWParameterValueFunctionEditor provides a default implementation 00212 // preventing the point to be moved outside the parameter range, or 00213 // if the parameter is locked, or if it is passing over or before its 00214 // neighbors. 00215 virtual int FunctionPointCanBeMovedToParameter(int id, double parameter) = 0; 00216 00217 protected: 00218 vtkKWParameterValueFunctionInterface() {}; 00219 ~vtkKWParameterValueFunctionInterface() {}; 00220 00221 // Description: 00222 // Create the widget. 00223 virtual void CreateWidget(); 00224 00225 // Description: 00226 // Return 1 if the function line joining point 'id1' and point 'id2' 00227 // needs to be sampled at regular interval (instead of a straight line). 00228 // If the interpolation function InterpolateFunctionPointValues is not 00229 // linear, it is likely that this function should return 1 so that the 00230 // line that is drawn between the two points is not a straight line but a 00231 // set of segments computed by sampling between each end-points. Yet, 00232 // it does not have to be *always* resampled, given the property of the 00233 // interpolant, some cases may end up requiring just a straight line, 00234 // which can be drawn much more efficiently. 00235 virtual int FunctionLineIsSampledBetweenPoints(int id1, int id2); 00236 00237 private: 00238 vtkKWParameterValueFunctionInterface(const vtkKWParameterValueFunctionInterface&); // Not implemented 00239 void operator=(const vtkKWParameterValueFunctionInterface&); // Not implemented 00240 }; 00241 00242 #endif