1 /*=========================================================================
3 Program: Visualization Toolkit
4 Module: $RCSfile: vtkXYPlotActor.h,v $
6 Date: $Date: 2002/11/11 21:41:29 $
7 Version: $Revision: 1.23 $
9 Copyright (c) 1993-2002 Ken Martin, Will Schroeder, Bill Lorensen
11 See Copyright.txt or http://www.kitware.com/Copyright.htm for details.
13 This software is distributed WITHOUT ANY WARRANTY; without even
14 the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
15 PURPOSE. See the above copyright notice for more information.
17 =========================================================================*/
18 // .NAME vtkXYPlotActor - generate an x-y plot from input dataset(s) or field data
19 // .SECTION Description
20 // vtkXYPlotActor creates an x-y plot of data from one or more input data
21 // sets or field data. The class plots dataset scalar values (y-axis) against
22 // the points (x-axis). The x-axis values are generated by taking the point
23 // ids, computing a cumulative arc length, or a normalized arc length. More
24 // than one input data set can be specified to generate multiple plots.
25 // Alternatively, if field data is supplied as input, the class plots one
26 // component against another. (The user must specify which component to use
27 // as the x-axis and which for the y-axis.)
29 // To use this class to plot dataset(s), you must specify one or more
30 // input datasets containing scalar and point data. You'll probably also
31 // want to invoke a method to control how the point coordinates are converted
32 // into x values (by default point ids are used).
34 // To use this class to plot field data, you must specify one or more input
35 // data objects with its associated field data. You'll also want to specify
36 // which component to use as the x-axis and which to use as the y-axis.
37 // Note that when plotting field data, the x and y values are used directly
38 // (i.e., there are no options to normalize the components).
40 // Once you've set up the plot, you'll want to position it. The
41 // PositionCoordinate defines the lower-left location of the x-y plot
42 // (specified in normalized viewport coordinates) and the Position2Coordinate
43 // define the upper-right corner. (Note: the Position2Coordinate is relative
44 // to PositionCoordinate, so you can move the vtkXYPlotActor around the
45 // viewport by setting just the PositionCoordinate.) The combination of the
46 // two position coordinates specifies a rectangle in which the plot will lie.
48 // Optional features include the ability to specify axes labels, label
49 // format and plot title. You can also
50 // manually specify the x and y plot ranges (by default they are computed
51 // automatically). The Border instance variable is used to create space
52 // between the boundary of the plot window (specified by PositionCoordinate
53 // and Position2Coordinate) and the plot itself.
55 // The font property of the plot title can be modified through the
56 // TitleTextProperty attribute.
57 // The font property of the axes titles and labels can be modified through the
58 // AxisTitleTextProperty and AxisLabelTextProperty attributes. You may also
59 // use the GetXAxisActor2D or GetYAxisActor2D methods
60 // to access each individual axis actor to modify their font properties.
61 // In the same way, the GetLegendBoxActor method can be used to access
62 // the legend box actor to modify its font properties.
64 // There are several advanced features as well. You can assign per curve
65 // properties (such as color and a plot symbol). (Note that each input
66 // dataset and/or data object creates a single curve.) Another option is to
67 // add a plot legend that graphically indicates the correspondance between
68 // the curve, curve symbols, and the data source. You can also exchange the
69 // x and y axes if you prefer you plot orientation that way.
72 // If you are interested in plotting something other than scalar data, you
73 // can use the vtk data shuffling filters (e.g.,
74 // vtkAttributeDataToFieldDataFilter snd vtkFieldDataToAttributeDataFilter)
75 // to convert the data into scalar data and/or points.
78 // vtkActor2D vtkTextMapper vtkScalarBarActor vtkAxisActor2D vtkCubeAxesActor
79 // vtkAttributeDataToFieldDataFilter vtkFieldDataToAttributeDataFilter
82 #ifndef __vtkXYPlotActor_h
83 #define __vtkXYPlotActor_h
85 #define VTK_XYPLOT_INDEX 0
86 #define VTK_XYPLOT_ARC_LENGTH 1
87 #define VTK_XYPLOT_NORMALIZED_ARC_LENGTH 2
88 #define VTK_XYPLOT_VALUE 3
90 #define VTK_XYPLOT_ROW 0
91 #define VTK_XYPLOT_COLUMN 1
93 #include "vtkActor2D.h"
95 class vtkAppendPolyData;
98 class vtkDataObjectCollection;
100 class vtkDataSetCollection;
102 class vtkGlyphSource2D;
104 class vtkLegendBoxActor;
107 class vtkPolyDataMapper2D;
109 class vtkTextProperty;
111 class VTK_HYBRID_EXPORT vtkXYPlotActor : public vtkActor2D
114 vtkTypeRevisionMacro(vtkXYPlotActor,vtkActor2D);
115 void PrintSelf(ostream& os, vtkIndent indent);
118 // Instantiate object with autorange computation; bold, italic, and shadows
119 // on; arial font family; the number of labels set to 5 for the x and y
120 // axes; a label format of "%-#6.3g"; and x coordinates computed from point
122 static vtkXYPlotActor *New();
124 //---Data Set Input----------------------------------------------------------
125 // The following methods are used to plot input datasets. Datasets
126 // will be plotted if set as input; otherwise the input data objects
127 // will be plotted (if defined).
130 // Add a dataset to the list of data to append. The array name specifies
131 // which point array to plot. If the array name is NULL, then the default
132 // scalars are used. The array can have multiple components, but only the
133 // first component is ploted.
134 void AddInput(vtkDataSet *in, const char* arrayName, int component);
135 void AddInput(vtkDataSet *in) {this->AddInput(in, NULL, 0);}
138 // Remove a dataset from the list of data to append.
139 void RemoveInput(vtkDataSet *in, const char* arrayName, int component);
140 void RemoveInput(vtkDataSet *in) {this->RemoveInput(in, NULL, 0);}
143 // This removes all of the data set inputs,
144 // but does not change the data object inputs.
145 void RemoveAllInputs();
148 // Return the list of inputs to this filter.
149 vtkDataSetCollection *GetInputList() {return this->InputList;}
152 // If plotting points by value, which component to use to determine the
153 // value. This sets a value per each input dataset (i.e., the ith dataset).
154 void SetPointComponent(int i, int comp);
155 int GetPointComponent(int i);
156 //---end Data Set Input-----------------------------------------------------
159 // Specify how the independent (x) variable is computed from the points.
160 // The independent variable can be the scalar/point index (i.e., point id),
161 // the accumulated arc length along the points, the normalized arc length,
162 // or by component value. If plotting datasets (e.g., points), the value
163 // that is used is specified by the PointComponent ivar. (Note: these
164 // methods also control how field data is plotted. Field data is usually
165 // plotted by value or index, if plotting length 1-dimensional length
166 // measures are used.)
167 vtkSetClampMacro(XValues,int,VTK_XYPLOT_INDEX,VTK_XYPLOT_VALUE);
168 vtkGetMacro(XValues,int);
169 void SetXValuesToIndex(){this->SetXValues(VTK_XYPLOT_INDEX);};
170 void SetXValuesToArcLength() {this->SetXValues(VTK_XYPLOT_ARC_LENGTH);};
171 void SetXValuesToNormalizedArcLength()
172 {this->SetXValues(VTK_XYPLOT_NORMALIZED_ARC_LENGTH);};
173 void SetXValuesToValue() {this->SetXValues(VTK_XYPLOT_VALUE);};
174 const char *GetXValuesAsString();
176 //---Data Object Input------------------------------------------------------
177 // The following methods are used to plot input data objects. Datasets will
178 // be plotted in preference to data objects if set as input; otherwise the
179 // input data objects will be plotted (if defined).
182 // Add a dataset to the list of data to append.
183 void AddDataObjectInput(vtkDataObject *in);
186 // Remove a dataset from the list of data to append.
187 void RemoveDataObjectInput(vtkDataObject *in);
190 // Return the list of inputs to this filter.
191 vtkDataObjectCollection *GetDataObjectInputList()
192 {return this->DataObjectInputList;}
195 // Indicate whether to plot rows or columns. If plotting rows, then
196 // the dependent variables is taken from a specified row,
198 vtkSetClampMacro(DataObjectPlotMode,int,VTK_XYPLOT_COLUMN,VTK_XYPLOT_ROW);
199 vtkGetMacro(DataObjectPlotMode,int);
200 void SetDataObjectPlotModeToRows()
201 {this->SetDataObjectPlotMode(VTK_XYPLOT_ROW);}
202 void SetDataObjectPlotModeToColumns()
203 {this->SetDataObjectPlotMode(VTK_XYPLOT_COLUMN);}
204 const char *GetDataObjectPlotModeAsString();
207 // Specify which component of the input data object to use as the
208 // independent variable for the ith input data object. (This ivar is
209 // ignored if plotting the index.) Note that the value is interpreted
210 // differently depending on DataObjectPlotMode. If the mode is Rows, then
211 // the value of DataObjectXComponent is the row number; otherwise it's the
213 void SetDataObjectXComponent(int i, int comp);
214 int GetDataObjectXComponent(int i);
217 // Specify which component of the input data object to use as the
218 // dependent variable for the ith input data object. (This ivar is
219 // ignored if plotting the index.) Note that the value is interpreted
220 // differently depending on DataObjectPlotMode. If the mode is Rows, then
221 // the value of DataObjectYComponent is the row number; otherwise it's the
223 void SetDataObjectYComponent(int i, int comp);
224 int GetDataObjectYComponent(int i);
225 //---end Data Object Input--------------------------------------------------
227 //---Per Curve Properties---------------------------------------------------
228 // The following methods are used to set properties on each curve that is
229 // plotted. Each input dataset (or data object) results in one curve. The
230 // methods that follow have an index i that corresponds to the input dataset
232 void SetPlotColor(int i, float r, float g, float b);
233 void SetPlotColor(int i, const float color[3]) {
234 this->SetPlotColor(i, color[0], color[1], color[2]); };
235 float *GetPlotColor(int i);
236 void SetPlotSymbol(int i,vtkPolyData *input);
237 vtkPolyData *GetPlotSymbol(int i);
238 void SetPlotLabel(int i, const char *label);
239 const char *GetPlotLabel(int i);
241 // Allow per-curve specification of line and point rendering. These override
242 // global settings PlotPoints and PlotLines. If not on, the default behavior
243 // is governed by PlotPoints and PlotLines ivars.
244 vtkGetMacro(PlotCurvePoints, int);
245 vtkSetMacro(PlotCurvePoints, int);
246 vtkBooleanMacro(PlotCurvePoints, int);
248 vtkGetMacro(PlotCurveLines, int);
249 vtkSetMacro(PlotCurveLines, int);
250 vtkBooleanMacro(PlotCurveLines, int);
252 void SetPlotLines(int i, int);
253 int GetPlotLines(int i);
255 void SetPlotPoints(int i, int);
256 int GetPlotPoints(int i);
257 //---end Per Curve Properties-----------------------------------------------
260 // Enable/Disable exchange of the x-y axes (i.e., what was x becomes y, and
261 // vice-versa). Exchanging axes affects the labeling as well.
262 vtkSetMacro(ExchangeAxes, int);
263 vtkGetMacro(ExchangeAxes, int);
264 vtkBooleanMacro(ExchangeAxes, int);
267 // Normally the x-axis is plotted from minimum to maximum. Setting this instance
268 // variable causes the x-axis to be plotted from maximum to minimum. Note that
269 // boolean always applies to the x-axis even if ExchangeAxes is set.
270 vtkSetMacro(ReverseXAxis, int);
271 vtkGetMacro(ReverseXAxis, int);
272 vtkBooleanMacro(ReverseXAxis, int);
275 // Normally the y-axis is plotted from minimum to maximum. Setting this instance
276 // variable causes the y-axis to be plotted from maximum to minimum. Note that
277 // boolean always applies to the y-axis even if ExchangeAxes is set.
278 vtkSetMacro(ReverseYAxis, int);
279 vtkGetMacro(ReverseYAxis, int);
280 vtkBooleanMacro(ReverseYAxis, int);
283 // Retrieve handles to the legend box and glyph source. This is useful
284 // if you would like to change the default behavior of the legend box
285 // or glyph source. For example, the default glyph can be changed from
286 // a line to a vertex plus line, etc.)
287 vtkLegendBoxActor *GetLegendBoxActor()
288 {return this->LegendActor;}
289 vtkGlyphSource2D *GetGlyphSource()
290 {return this->GlyphSource;}
293 // Set/Get the title of the x-y plot, and the title along the
295 vtkSetStringMacro(Title);
296 vtkGetStringMacro(Title);
297 vtkSetStringMacro(XTitle);
298 vtkGetStringMacro(XTitle);
299 vtkSetStringMacro(YTitle);
300 vtkGetStringMacro(YTitle);
303 // Retrieve handles to the X and Y axis (so that you can set their text
304 // properties for example)
305 vtkAxisActor2D *GetXAxisActor2D()
306 {return this->XAxis;}
307 vtkAxisActor2D *GetYAxisActor2D()
308 {return this->YAxis;}
311 // Set the plot range (range of independent and dependent variables)
312 // to plot. Data outside of the range will be clipped. If the plot
313 // range of either the x or y variables is set to (v1,v2), where
314 // v1 == v2, then the range will be computed automatically. Note that
315 // the x-range values should be consistent with the way the independent
316 // variable is created (via INDEX, DISTANCE, or ARC_LENGTH).
317 vtkSetVector2Macro(XRange,float);
318 vtkGetVectorMacro(XRange,float,2);
319 vtkSetVector2Macro(YRange,float);
320 vtkGetVectorMacro(YRange,float,2);
321 void SetPlotRange(float xmin, float ymin, float xmax, float ymax)
322 {this->SetXRange(xmin,xmax); this->SetYRange(ymin,ymax);}
325 // Set/Get the number of annotation labels to show along the x and y axes.
326 // This values is a suggestion: the number of labels may vary depending
327 // on the particulars of the data. The convenience method
328 // SetNumberOfLables() sets the number of x and y labels to the same value.
329 vtkSetClampMacro(NumberOfXLabels, int, 0, 50);
330 vtkGetMacro(NumberOfXLabels, int);
331 vtkSetClampMacro(NumberOfYLabels, int, 0, 50);
332 vtkGetMacro(NumberOfYLabels, int);
333 void SetNumberOfLabels(int num)
334 {this->SetNumberOfXLabels(num); this->SetNumberOfYLabels(num);}
337 // Enable/Disable the creation of a legend. If on, the legend labels will
338 // be created automatically unless the per plot legend symbol has been
340 vtkSetMacro(Legend, int);
341 vtkGetMacro(Legend, int);
342 vtkBooleanMacro(Legend, int);
345 // Use these methods to control the position of the legend. The variables
346 // LegendPosition and LegendPosition2 define the lower-left and upper-right
347 // position of the legend. The coordinates are expressed as normalized
348 // values with respect to the rectangle defined by PositionCoordinate and
349 // Position2Coordinate. Note that LegendPosition2 is relative to
351 vtkSetVector2Macro(LegendPosition,float);
352 vtkGetVector2Macro(LegendPosition,float);
353 vtkSetVector2Macro(LegendPosition2,float);
354 vtkGetVector2Macro(LegendPosition2,float);
357 // Set/Get the title text property.
358 virtual void SetTitleTextProperty(vtkTextProperty *p);
359 vtkGetObjectMacro(TitleTextProperty,vtkTextProperty);
362 // Set/Get the title text property of all axes. Note that each axis can
363 // be controlled individually through the GetX/YAxisActor2D() methods.
364 virtual void SetAxisTitleTextProperty(vtkTextProperty *p);
365 vtkGetObjectMacro(AxisTitleTextProperty,vtkTextProperty);
368 // Set/Get the labels text property of all axes. Note that each axis can
369 // be controlled individually through the GetX/YAxisActor2D() methods.
370 virtual void SetAxisLabelTextProperty(vtkTextProperty *p);
371 vtkGetObjectMacro(AxisLabelTextProperty,vtkTextProperty);
373 #ifndef VTK_REMOVE_LEGACY_CODE
375 // Set/Get the font family. Three font types are allowed: Arial (VTK_ARIAL),
376 // Courier (VTK_COURIER), and Times (VTK_TIMES).
377 // Warning: these functions remain for backward compatibility. Use the
378 // vtkTextProperty through the (Set/Get)TitleTextProperty() methods.
379 virtual void SetFontFamily(int val);
380 virtual int GetFontFamily();
381 void SetFontFamilyToArial() { this->SetFontFamily(VTK_ARIAL); };
382 void SetFontFamilyToCourier() { this->SetFontFamily(VTK_COURIER);};
383 void SetFontFamilyToTimes() { this->SetFontFamily(VTK_TIMES); };
386 #ifndef VTK_REMOVE_LEGACY_CODE
388 // Enable/disable text bolding.
389 // Warning: these functions remain for backward compatibility. Use the
390 // vtkTextProperty through the (Set/Get)TitleTextProperty() methods.
391 virtual void SetBold(int val);
392 virtual int GetBold();
393 vtkBooleanMacro(Bold, int);
396 #ifndef VTK_REMOVE_LEGACY_CODE
398 // Enable/disable text italic.
399 // Warning: these functions remain for backward compatibility. Use the
400 // vtkTextProperty through the (Set/Get)TitleTextProperty() methods.
401 virtual void SetItalic(int val);
402 virtual int GetItalic();
403 vtkBooleanMacro(Italic, int);
406 #ifndef VTK_REMOVE_LEGACY_CODE
408 // Enable/disable text shadows.
409 // Warning: these functions remain for backward compatibility. Use the
410 // vtkTextProperty through the (Set/Get)TitleTextProperty() methods.
411 virtual void SetShadow(int val);
412 virtual int GetShadow();
413 vtkBooleanMacro(Shadow, int);
417 // Enable/Disable plotting of Log of x-values.
418 vtkSetMacro(Logx, int);
419 vtkGetMacro(Logx, int);
420 vtkBooleanMacro(Logx, int);
423 // Set/Get the format with which to print the labels on the scalar
425 virtual void SetLabelFormat (const char* _arg);
426 vtkGetStringMacro(LabelFormat);
429 // Set/Get the spacing between the plot window and the plot. The value
430 // is specified in pixels.
431 vtkSetClampMacro(Border, int, 0, 50);
432 vtkGetMacro(Border, int);
435 // Set/Get whether the points are rendered. The point size can be set in
436 // the property object. This is a global flag which affects the plot only
437 // if per curve symbols are not defined.
438 vtkGetMacro(PlotPoints, int);
439 vtkSetMacro(PlotPoints, int);
440 vtkBooleanMacro(PlotPoints, int);
443 // Set/Get whether the lines are rendered. The line width can be set in
444 // the property object.
445 vtkGetMacro(PlotLines, int);
446 vtkSetMacro(PlotLines, int);
447 vtkBooleanMacro(PlotLines, int);
450 // Set/Get the factor that controls how big glyphs are in the plot.
451 // The number is expressed as a fraction of the length of the diagonal
452 // of the plot bounding box.
453 vtkSetClampMacro(GlyphSize, float, 0.0, 0.2);
454 vtkGetMacro(GlyphSize, float);
457 // Given a position within the viewport used by the plot, return the
458 // the plot coordinates (XAxis value, YAxis value)
459 void ViewportToPlotCoordinate(vtkViewport *viewport, float &u, float &v);
462 // An alternate form of ViewportToPlotCoordinate() above. This method
463 // inputs the viewport coordinate pair (defined by the ivar
464 // ViewportCoordinate)and then stores them in the ivar PlotCoordinate.
465 void ViewportToPlotCoordinate(vtkViewport *viewport);
466 vtkSetVector2Macro(PlotCoordinate,float);
467 vtkGetVector2Macro(PlotCoordinate,float);
470 // Given a plot coordinate, return the viewpoint position
471 void PlotToViewportCoordinate(vtkViewport *viewport, float &u, float &v);
474 // An alternate form of PlotToViewportCoordinate() above. This method
475 // inputs the plot coordinate pair (defined in the ivar PlotCoordinate)
476 // and then stores them in the ivar ViewportCoordinate. (This method
478 void PlotToViewportCoordinate(vtkViewport *viewport);
479 vtkSetVector2Macro(ViewportCoordinate,float);
480 vtkGetVector2Macro(ViewportCoordinate,float);
483 // Is the specified viewport position within the plot area (as opposed to the
484 // region used by the plot plus the labels)?
485 int IsInPlot(vtkViewport *viewport, float u, float v);
488 // Take into account the modified time of internal helper classes.
489 unsigned long GetMTime();
493 // WARNING: INTERNAL METHOD - NOT INTENDED FOR GENERAL USE
494 // DO NOT USE THIS METHOD OUTSIDE OF THE RENDERING PROCESS.
495 // Draw the x-y plot.
496 int RenderOpaqueGeometry(vtkViewport*);
497 int RenderOverlay(vtkViewport*);
498 int RenderTranslucentGeometry(vtkViewport *) {return 0;}
501 // Release any graphics resources that are being consumed by this actor.
502 // The parameter window could be used to determine which graphic
503 // resources to release.
504 void ReleaseGraphicsResources(vtkWindow *);
511 vtkDataSetCollection *InputList; //list of data sets to plot
512 char** SelectedInputScalars; // list of data set arrays to plot
513 vtkIntArray* SelectedInputScalarsComponent; // list of componenents
514 vtkDataObjectCollection *DataObjectInputList; //list of data objects to plot
525 float XComputedRange[2]; //range actually used by plot
526 float YComputedRange[2]; //range actually used by plot
536 vtkTextMapper *TitleMapper;
537 vtkActor2D *TitleActor;
538 vtkTextProperty *TitleTextProperty;
540 vtkAxisActor2D *XAxis;
541 vtkAxisActor2D *YAxis;
543 vtkTextProperty *AxisTitleTextProperty;
544 vtkTextProperty *AxisLabelTextProperty;
546 float ViewportCoordinate[2];
547 float PlotCoordinate[2];
549 //Handle data objects and datasets
550 int DataObjectPlotMode;
551 vtkIntArray *XComponent;
552 vtkIntArray *YComponent;
553 vtkIntArray *LinesOn;
554 vtkIntArray *PointsOn;
556 //The data drawn within the axes. Each curve is one polydata.
557 //color is controlled by scalar data. The curves are appended
558 //together, possibly glyphed with point symbols.
560 vtkPolyData **PlotData;
561 vtkGlyph2D **PlotGlyph;
562 vtkAppendPolyData **PlotAppend;
563 vtkPolyDataMapper2D **PlotMapper;
564 vtkActor2D **PlotActor;
565 void InitializeEntries();
567 // Legends and plot symbols. The legend also keeps track of
568 // the symbols and such.
570 float LegendPosition[2];
571 float LegendPosition2[2];
572 vtkLegendBoxActor *LegendActor;
573 vtkGlyphSource2D *GlyphSource;
574 vtkPlanes *ClipPlanes;
577 // Keep track of changes.
579 vtkTimeStamp BuildTime;
581 void ComputeXRange(float range[2], float *lengths);
582 void ComputeYRange(float range[2]);
583 void ComputeDORange(float xrange[2], float yrange[2], float *lengths);
585 virtual void CreatePlotData(int *pos, int *pos2, float xRange[2],
586 float yRange[2], float *norms,
587 int numDS, int numDO);
588 void PlaceAxes(vtkViewport *viewport, int *size, int pos[2], int pos2[2]);
589 void GenerateClipPlanes(int *pos, int *pos2);
590 float ComputeGlyphScale(int i, int *pos, int *pos2);
591 void ClipPlotData(int *pos, int *pos2, vtkPolyData *pd);
592 float *TransformPoint(int pos[2], int pos2[2], float x[3], float xNew[3]);
595 vtkXYPlotActor(const vtkXYPlotActor&); // Not implemented.
596 void operator=(const vtkXYPlotActor&); // Not implemented.