KWWidgets
vtkKWParameterValueFunctionInterface.h
Go to the documentation of this file.
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