0029894: Visualization - AIS_ColorScale ColorRange returns only min color
[occt.git] / src / AIS / AIS_ColorScale.hxx
1 // Created on: 2015-02-03
2 // Copyright (c) 2015 OPEN CASCADE SAS
3 //
4 // This file is part of Open CASCADE Technology software library.
5 //
6 // This library is free software; you can redistribute it and/or modify it under
7 // the terms of the GNU Lesser General Public License version 2.1 as published
8 // by the Free Software Foundation, with special exception defined in the file
9 // OCCT_LGPL_EXCEPTION.txt. Consult the file LICENSE_LGPL_21.txt included in OCCT
10 // distribution for complete text of the license and disclaimer of any warranty.
11 //
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
14
15 #ifndef _AIS_ColorScale_HeaderFile
16 #define _AIS_ColorScale_HeaderFile
17
18 #include <AIS_InteractiveObject.hxx>
19 #include <Aspect_TypeOfColorScaleData.hxx>
20 #include <Aspect_TypeOfColorScalePosition.hxx>
21 #include <Aspect_SequenceOfColor.hxx>
22 #include <Standard.hxx>
23 #include <Standard_DefineHandle.hxx>
24 #include <TCollection_ExtendedString.hxx>
25 #include <TColStd_SequenceOfExtendedString.hxx>
26
27 class AIS_ColorScale;
28 DEFINE_STANDARD_HANDLE(AIS_ColorScale, AIS_InteractiveObject)
29 //! Class for drawing a custom color scale.
30 //!
31 //! The color scale consists of rectangular color bar (composed of fixed
32 //! number of color intervals), optional labels, and title.
33 //! The labels can be positioned either at the boundaries of the intervals,
34 //! or at the middle of each interval.
35 //! Colors and labels can be either defined automatically or set by the user.
36 //! Automatic labels are calculated from numerical limits of the scale,
37 //! its type (logarithmic or plain), and formatted by specified format string.
38 class AIS_ColorScale : public AIS_InteractiveObject
39 {
40   DEFINE_STANDARD_RTTIEXT(AIS_ColorScale, AIS_InteractiveObject)
41 public:
42
43   //! Calculate color according passed value; returns true if value is in range or false, if isn't
44   Standard_EXPORT static Standard_Boolean FindColor (const Standard_Real theValue,
45                                                      const Standard_Real theMin,
46                                                      const Standard_Real theMax,
47                                                      const Standard_Integer theColorsCount,
48                                                      const Graphic3d_Vec3d& theColorHlsMin,
49                                                      const Graphic3d_Vec3d& theColorHlsMax,
50                                                      Quantity_Color& theColor);
51
52   //! Calculate color according passed value; returns true if value is in range or false, if isn't
53   static Standard_Boolean FindColor (const Standard_Real theValue,
54                                      const Standard_Real theMin,
55                                      const Standard_Real theMax,
56                                      const Standard_Integer theColorsCount,
57                                      Quantity_Color& theColor)
58   {
59     return FindColor (theValue, theMin, theMax, theColorsCount,
60                       Graphic3d_Vec3d (230.0, 1.0, 1.0),
61                       Graphic3d_Vec3d (0.0,   1.0, 1.0),
62                       theColor);
63   }
64
65   //! Shift hue into valid range.
66   //! Lightness and Saturation should be specified in valid range [0.0, 1.0],
67   //! however Hue might be given out of Quantity_Color range to specify desired range for interpolation.
68   static Standard_Real hueToValidRange (const Standard_Real theHue)
69   {
70     Standard_Real aHue = theHue;
71     while (aHue <   0.0) { aHue += 360.0; }
72     while (aHue > 360.0) { aHue -= 360.0; }
73     return aHue;
74   }
75
76 public:
77
78   //! Default constructor.
79   Standard_EXPORT AIS_ColorScale();
80
81   //! Calculate color according passed value; returns true if value is in range or false, if isn't
82   Standard_EXPORT Standard_Boolean FindColor (const Standard_Real theValue, Quantity_Color& theColor) const;
83
84   //! Returns minimal value of color scale, 0.0 by default.
85   Standard_Real GetMin() const { return myMin; }
86
87   //! Sets the minimal value of color scale.
88   void SetMin (const Standard_Real theMin) { SetRange (theMin, GetMax()); }
89
90   //! Returns maximal value of color scale, 1.0 by default.
91   Standard_Real GetMax() const { return myMax; }
92
93   //! Sets the maximal value of color scale.
94   void SetMax (const Standard_Real theMax) { SetRange (GetMin(), theMax); }
95
96   //! Returns minimal and maximal values of color scale, 0.0 to 1.0 by default.
97   void GetRange (Standard_Real& theMin, Standard_Real& theMax) const
98   {
99     theMin = myMin;
100     theMax = myMax;
101   }
102
103   //! Sets the minimal and maximal value of color scale.
104   //! Note that values order will be ignored - the minimum and maximum values will be swapped if needed.
105   //! ::SetReversed() should be called to swap displaying order.
106   Standard_EXPORT void SetRange (const Standard_Real theMin, const Standard_Real theMax);
107
108   //! Returns the hue angle corresponding to minimum value, 230 by default (blue).
109   Standard_Real HueMin() const { return myColorHlsMin[0]; }
110
111   //! Returns the hue angle corresponding to maximum value, 0 by default (red).
112   Standard_Real HueMax() const { return myColorHlsMax[0]; }
113
114   //! Returns the hue angle range corresponding to minimum and maximum values, 230 to 0 by default (blue to red).
115   void HueRange (Standard_Real& theMinAngle,
116                  Standard_Real& theMaxAngle) const
117   {
118     theMinAngle = myColorHlsMin[0];
119     theMaxAngle = myColorHlsMax[0];
120   }
121
122   //! Sets hue angle range corresponding to minimum and maximum values.
123   //! The valid angle range is [0, 360], see Quantity_Color and Quantity_TOC_HLS for more details.
124   void SetHueRange (const Standard_Real theMinAngle,
125                     const Standard_Real theMaxAngle)
126   {
127     myColorHlsMin[0] = theMinAngle;
128     myColorHlsMax[0] = theMaxAngle;
129   }
130
131   //! Returns color range corresponding to minimum and maximum values, blue to red by default.
132   void ColorRange (Quantity_Color& theMinColor,
133                    Quantity_Color& theMaxColor) const
134   {
135     theMinColor.SetValues (hueToValidRange (myColorHlsMin[0]), myColorHlsMin[1], myColorHlsMin[2], Quantity_TOC_HLS);
136     theMaxColor.SetValues (hueToValidRange (myColorHlsMax[0]), myColorHlsMax[1], myColorHlsMax[2], Quantity_TOC_HLS);
137   }
138
139   //! Sets color range corresponding to minimum and maximum values.
140   void SetColorRange (const Quantity_Color& theMinColor,
141                       const Quantity_Color& theMaxColor)
142   {
143     theMinColor.Values (myColorHlsMin[0], myColorHlsMin[1], myColorHlsMin[2], Quantity_TOC_HLS);
144     theMaxColor.Values (myColorHlsMax[0], myColorHlsMax[1], myColorHlsMax[2], Quantity_TOC_HLS);
145   }
146
147   //! Returns the type of labels, Aspect_TOCSD_AUTO by default.
148   //! Aspect_TOCSD_AUTO - labels as boundary values for intervals
149   //! Aspect_TOCSD_USER - user specified label is used
150   Aspect_TypeOfColorScaleData GetLabelType() const { return myLabelType; }
151
152   //! Sets the type of labels.
153   //! Aspect_TOCSD_AUTO - labels as boundary values for intervals
154   //! Aspect_TOCSD_USER - user specified label is used
155   void SetLabelType (const Aspect_TypeOfColorScaleData theType) { myLabelType = theType; }
156
157   //! Returns the type of colors, Aspect_TOCSD_AUTO by default.
158   //! Aspect_TOCSD_AUTO - value between Red and Blue
159   //! Aspect_TOCSD_USER - user specified color from color map
160   Aspect_TypeOfColorScaleData GetColorType() const { return myColorType; }
161
162   //! Sets the type of colors.
163   //! Aspect_TOCSD_AUTO - value between Red and Blue
164   //! Aspect_TOCSD_USER - user specified color from color map
165   void SetColorType (const Aspect_TypeOfColorScaleData theType) { myColorType = theType; }
166
167   //! Returns the number of color scale intervals, 10 by default.
168   Standard_Integer GetNumberOfIntervals() const { return myNbIntervals; }
169
170   //! Sets the number of color scale intervals.
171   Standard_EXPORT void SetNumberOfIntervals (const Standard_Integer theNum);
172
173   //! Returns the color scale title string, empty string by default.
174   const TCollection_ExtendedString& GetTitle() const { return myTitle; }
175
176   //! Sets the color scale title string.
177   void SetTitle (const TCollection_ExtendedString& theTitle) { myTitle = theTitle; }
178
179   //! Returns the format for numbers, "%.4g" by default.
180   //! The same like format for function printf().
181   //! Used if GetLabelType() is TOCSD_AUTO;
182   const TCollection_AsciiString& GetFormat() const { return myFormat; }
183
184   //! Returns the format of text.
185   const TCollection_AsciiString& Format() const { return myFormat; }
186
187   //! Sets the color scale auto label format specification.
188   void SetFormat (const TCollection_AsciiString& theFormat) { myFormat = theFormat; }
189
190   //! Returns the user specified label with index theIndex.
191   //! Index is in range from 1 to GetNumberOfIntervals() or to
192   //! GetNumberOfIntervals() + 1 if IsLabelAtBorder() is true.
193   //! Returns empty string if label not defined.
194   Standard_EXPORT TCollection_ExtendedString GetLabel (const Standard_Integer theIndex) const;
195
196   //! Returns the user specified color from color map with index (starts at 1).
197   //! Returns default color if index is out of range in color map.
198   Standard_EXPORT Quantity_Color GetIntervalColor (const Standard_Integer theIndex) const;
199
200   //! Sets the color of the specified interval. 
201   //! Note that list is automatically resized to include specified index.
202   //! @param theColor color value to set
203   //! @param theIndex index in range [1, GetNumberOfIntervals()];
204   //!                 appended to the end of list if -1 is specified
205   Standard_EXPORT void SetIntervalColor (const Quantity_Color& theColor, const Standard_Integer theIndex);
206
207   //! Returns the user specified labels.
208   Standard_EXPORT void GetLabels (TColStd_SequenceOfExtendedString& theLabels) const;
209
210   //! Returns the user specified labels.
211   const TColStd_SequenceOfExtendedString& Labels() const { return myLabels; }
212
213   //! Sets the color scale labels.
214   //! The length of the sequence should be equal to GetNumberOfIntervals() or to GetNumberOfIntervals() + 1 if IsLabelAtBorder() is true.
215   //! If length of the sequence does not much the number of intervals,
216   //! then these labels will be considered as "free" and will be located
217   //! at the virtual intervals corresponding to the number of labels
218   //! (with flag IsLabelAtBorder() having the same effect as in normal case).
219   Standard_EXPORT void SetLabels (const TColStd_SequenceOfExtendedString& theSeq);
220
221   //! Returns the user specified colors.
222   Standard_EXPORT void GetColors (Aspect_SequenceOfColor& theColors) const;
223
224   //! Returns the user specified colors.
225   const Aspect_SequenceOfColor& GetColors() const { return myColors; }
226
227   //! Sets the color scale colors.
228   //! The length of the sequence should be equal to GetNumberOfIntervals().
229   Standard_EXPORT void SetColors (const Aspect_SequenceOfColor& theSeq);
230
231   //! Returns the position of labels concerning color filled rectangles, Aspect_TOCSP_RIGHT by default.
232   Aspect_TypeOfColorScalePosition GetLabelPosition() const { return myLabelPos; }
233
234   //! Sets the color scale labels position relative to color bar.
235   void SetLabelPosition (const Aspect_TypeOfColorScalePosition thePos) { myLabelPos = thePos; }
236
237   //! Returns the position of color scale title, Aspect_TOCSP_LEFT by default.
238   Aspect_TypeOfColorScalePosition GetTitlePosition() const { return myTitlePos; }
239
240   //! Sets the color scale title position.
241   Standard_DEPRECATED("AIS_ColorScale::SetTitlePosition() has no effect!")
242   void SetTitlePosition (const Aspect_TypeOfColorScalePosition thePos) { myTitlePos = thePos; }
243
244   //! Returns TRUE if the labels and colors used in reversed order, FALSE by default.
245   //!  - Normal,   bottom-up order with Minimal value on the Bottom and Maximum value on Top.
246   //!  - Reversed, top-down  order with Maximum value on the Bottom and Minimum value on Top.
247   Standard_Boolean IsReversed() const { return myIsReversed; }
248
249   //! Sets true if the labels and colors used in reversed order.
250   void SetReversed (const Standard_Boolean theReverse) { myIsReversed = theReverse; }
251
252   //! Return TRUE if color transition between neighbor intervals
253   //! should be linearly interpolated, FALSE by default.
254   Standard_Boolean IsSmoothTransition() const { return myIsSmooth; }
255
256   //! Setup smooth color transition.
257   void SetSmoothTransition (const Standard_Boolean theIsSmooth) { myIsSmooth = theIsSmooth; }
258
259   //! Returns TRUE if the labels are placed at border of color intervals, TRUE by default.
260   //! The automatically generated label will show value exactly on the current position:
261   //!  - value connecting two neighbor intervals (TRUE)
262   //!  - value in the middle of interval (FALSE)
263   Standard_Boolean IsLabelAtBorder() const { return myIsLabelAtBorder; }
264
265   //! Sets true if the labels are placed at border of color intervals (TRUE by default).
266   //! If set to False, labels will be drawn at color intervals rather than at borders.
267   void SetLabelAtBorder (const Standard_Boolean theOn) { myIsLabelAtBorder = theOn; }
268
269   //! Returns TRUE if the color scale has logarithmic intervals, FALSE by default.
270   Standard_Boolean IsLogarithmic() const { return myIsLogarithmic; }
271
272   //! Sets true if the color scale has logarithmic intervals.
273   void SetLogarithmic (const Standard_Boolean isLogarithmic) { myIsLogarithmic = isLogarithmic; }
274
275   //! Sets the color scale label at index.
276   //! Note that list is automatically resized to include specified index.
277   //! @param theLabel new label text
278   //! @param theIndex index in range [1, GetNumberOfIntervals()] or [1, GetNumberOfIntervals() + 1] if IsLabelAtBorder() is true;
279   //!                 label is appended to the end of list if negative index is specified
280   Standard_EXPORT void SetLabel (const TCollection_ExtendedString& theLabel, const Standard_Integer theIndex);
281
282   //! Returns the size of color bar, 0 and 0 by default
283   //! (e.g. should be set by user explicitly before displaying).
284   void GetSize (Standard_Integer& theBreadth, Standard_Integer& theHeight) const
285   {
286     theBreadth = myBreadth;
287     theHeight  = myHeight;
288   }
289
290   //! Sets the size of color bar.
291   void SetSize (const Standard_Integer theBreadth, const Standard_Integer theHeight)
292   {
293     myBreadth = theBreadth;
294     myHeight  = theHeight;
295   }
296
297   //! Returns the breadth of color bar, 0 by default
298   //! (e.g. should be set by user explicitly before displaying).
299   Standard_Integer GetBreadth() const { return myBreadth; }
300
301   //! Sets the width of color bar.
302   void SetBreadth (const Standard_Integer theBreadth) { myBreadth = theBreadth; }
303
304   //! Returns the height of color bar, 0 by default
305   //! (e.g. should be set by user explicitly before displaying).
306   Standard_Integer GetHeight() const { return myHeight; }
307
308   //! Sets the height of color bar.
309   void SetHeight (const Standard_Integer theHeight) { myHeight  = theHeight; }
310
311   //! Returns the bottom-left position of color scale, 0x0 by default.
312   void GetPosition (Standard_Real& theX, Standard_Real& theY) const
313   {
314     theX = myXPos;
315     theY = myYPos;
316   }
317
318   //! Sets the position of color scale.
319   void SetPosition (const Standard_Integer theX, const Standard_Integer theY)
320   {
321     myXPos = theX;
322     myYPos = theY;
323   }
324
325   //! Returns the left position of color scale, 0 by default.
326   Standard_Integer GetXPosition() const { return myXPos; }
327
328   //! Sets the left position of color scale.
329   void SetXPosition (const Standard_Integer theX) { myXPos = theX; }
330
331   //! Returns the bottom position of color scale, 0 by default.
332   Standard_Integer GetYPosition() const { return myYPos; }
333
334   //! Sets the bottom position of color scale.
335   void SetYPosition (const Standard_Integer theY) { myYPos = theY; }
336
337   //! Returns the font height of text labels, 20 by default.
338   Standard_Integer GetTextHeight() const { return myTextHeight; }
339
340   //! Sets the height of text of color scale.
341   void SetTextHeight (const Standard_Integer theHeight) { myTextHeight = theHeight; }
342
343 public:
344
345   //! Returns the width of text.
346   //! @param theText [in] the text of which to calculate width.
347   Standard_EXPORT Standard_Integer TextWidth (const TCollection_ExtendedString& theText) const;
348
349   //! Returns the height of text.
350   //! @param theText [in] the text of which to calculate height.
351   Standard_EXPORT Standard_Integer TextHeight (const TCollection_ExtendedString& theText) const;
352
353   Standard_EXPORT void TextSize (const TCollection_ExtendedString& theText,
354                                  const Standard_Integer theHeight,
355                                  Standard_Integer& theWidth,
356                                  Standard_Integer& theAscent,
357                                  Standard_Integer& theDescent) const;
358
359 public:
360
361   //! Return true if specified display mode is supported.
362   virtual Standard_Boolean AcceptDisplayMode (const Standard_Integer theMode) const Standard_OVERRIDE { return theMode == 0; }
363
364   //! Compute presentation.
365   Standard_EXPORT virtual void Compute (const Handle(PrsMgr_PresentationManager3d)& thePresentationManager,
366                                         const Handle(Prs3d_Presentation)& thePresentation,
367                                         const Standard_Integer theMode) Standard_OVERRIDE;
368
369   //! Compute selection - not implemented for color scale.
370   virtual void ComputeSelection (const Handle(SelectMgr_Selection)& /*aSelection*/,
371                                  const Standard_Integer /*aMode*/) Standard_OVERRIDE {}
372
373 private:
374
375   //! Returns the size of color scale.
376   //! @param theWidth [out] the width of color scale.
377   //! @param theHeight [out] the height of color scale.
378   void SizeHint (Standard_Integer& theWidth, Standard_Integer& theHeight) const;
379
380   //! Returns the upper value of given interval, or minimum for theIndex = 0.
381   Standard_Real GetIntervalValue (const Standard_Integer theIndex) const;
382
383   //! Returns the color for the given value in the given interval.
384   //! @param theValue [in] the current value of interval
385   //! @param theMin   [in] the min value of interval
386   //! @param theMax   [in] the max value of interval
387   Quantity_Color colorFromValue (const Standard_Real theValue,
388                                  const Standard_Real theMin,
389                                  const Standard_Real theMax) const;
390
391   //! Initialize text aspect for drawing the labels.
392   void updateTextAspect();
393
394   //! Simple alias for Prs3d_Text::Draw().
395   //! @param theGroup [in] presentation group
396   //! @param theText  [in] text to draw
397   //! @param theX     [in] X coordinate of text position
398   //! @param theY     [in] Y coordinate of text position
399   //! @param theVertAlignment [in] text vertical alignment
400   void drawText (const Handle(Graphic3d_Group)& theGroup,
401                  const TCollection_ExtendedString& theText,
402                  const Standard_Integer theX, const Standard_Integer theY,
403                  const Graphic3d_VerticalTextAlignment theVertAlignment);
404
405   //! Determine the maximum text label width in pixels.
406   Standard_Integer computeMaxLabelWidth (const TColStd_SequenceOfExtendedString& theLabels) const;
407
408   //! Draw labels.
409   void drawLabels (const Handle(Prs3d_Presentation)& thePrs,
410                    const TColStd_SequenceOfExtendedString& theLabels,
411                    const Standard_Integer theBarBottom,
412                    const Standard_Integer theBarHeight,
413                    const Standard_Integer theMaxLabelWidth,
414                    const Standard_Integer theColorBreadth);
415
416   //! Draw a color bar.
417   void drawColorBar (const Handle(Prs3d_Presentation)& thePrs,
418                      const Standard_Integer theBarBottom,
419                      const Standard_Integer theBarHeight,
420                      const Standard_Integer theMaxLabelWidth,
421                      const Standard_Integer theColorBreadth);
422
423   //! Draw a frame.
424   //! @param theX [in] the X coordinate of frame position.
425   //! @param theY [in] the Y coordinate of frame position.
426   //! @param theWidth [in] the width of frame.
427   //! @param theHeight [in] the height of frame.
428   //! @param theColor [in] the color of frame.
429   void drawFrame (const Handle(Prs3d_Presentation)& thePrs,
430                   const Standard_Integer theX, const Standard_Integer theY,
431                   const Standard_Integer theWidth, const Standard_Integer theHeight,
432                   const Quantity_Color& theColor);
433
434 private:
435
436   Standard_Real                    myMin;             //!< values range - minimal value
437   Standard_Real                    myMax;             //!< values range - maximal value
438   Graphic3d_Vec3d                  myColorHlsMin;     //!< HLS color corresponding to minimum value
439   Graphic3d_Vec3d                  myColorHlsMax;     //!< HLS color corresponding to maximum value
440   TCollection_ExtendedString       myTitle;           //!< optional title string     
441   TCollection_AsciiString          myFormat;          //!< sprintf() format for generating label from value
442   Standard_Integer                 myNbIntervals;     //!< number of intervals
443   Aspect_TypeOfColorScaleData      myColorType;       //!< color type
444   Aspect_TypeOfColorScaleData      myLabelType;       //!< label type
445   Standard_Boolean                 myIsLabelAtBorder; //!< at border
446   Standard_Boolean                 myIsReversed;      //!< flag indicating reversed order
447   Standard_Boolean                 myIsLogarithmic;   //!< flag indicating logarithmic scale
448   Standard_Boolean                 myIsSmooth;        //!< flag indicating smooth transition between the colors
449   Aspect_SequenceOfColor           myColors;          //!< sequence of custom colors
450   TColStd_SequenceOfExtendedString myLabels;          //!< sequence of custom text labels
451   Aspect_TypeOfColorScalePosition  myLabelPos;        //!< label position relative to the color scale
452   Aspect_TypeOfColorScalePosition  myTitlePos;        //!< title position
453   Standard_Integer                 myXPos;            //!< left   position
454   Standard_Integer                 myYPos;            //!< bottom position
455   Standard_Integer                 myBreadth;         //!< color scale breadth
456   Standard_Integer                 myHeight;          //!< height of the color scale
457   Standard_Integer                 mySpacing;         //!< extra spacing between element
458   Standard_Integer                 myTextHeight;      //!< label font height
459
460 };
461
462 #endif