1 // Created on: 2015-02-03
2 // Copyright (c) 2015 OPEN CASCADE SAS
4 // This file is part of Open CASCADE Technology software library.
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.
12 // Alternatively, this file may be used under the terms of Open CASCADE
13 // commercial license or contractual agreement.
15 #ifndef _AIS_ColorScale_HeaderFile
16 #define _AIS_ColorScale_HeaderFile
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>
28 DEFINE_STANDARD_HANDLE(AIS_ColorScale, AIS_InteractiveObject)
29 //! Class for drawing a custom color scale.
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
40 DEFINE_STANDARD_RTTIEXT(AIS_ColorScale, AIS_InteractiveObject)
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);
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)
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),
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)
70 Standard_Real aHue = theHue;
71 while (aHue < 0.0) { aHue += 360.0; }
72 while (aHue > 360.0) { aHue -= 360.0; }
78 //! Default constructor.
79 Standard_EXPORT AIS_ColorScale();
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;
84 //! Returns minimal value of color scale, 0.0 by default.
85 Standard_Real GetMin() const { return myMin; }
87 //! Sets the minimal value of color scale.
88 void SetMin (const Standard_Real theMin) { SetRange (theMin, GetMax()); }
90 //! Returns maximal value of color scale, 1.0 by default.
91 Standard_Real GetMax() const { return myMax; }
93 //! Sets the maximal value of color scale.
94 void SetMax (const Standard_Real theMax) { SetRange (GetMin(), theMax); }
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
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);
108 //! Returns the hue angle corresponding to minimum value, 230 by default (blue).
109 Standard_Real HueMin() const { return myColorHlsMin[0]; }
111 //! Returns the hue angle corresponding to maximum value, 0 by default (red).
112 Standard_Real HueMax() const { return myColorHlsMax[0]; }
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
118 theMinAngle = myColorHlsMin[0];
119 theMaxAngle = myColorHlsMax[0];
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)
127 myColorHlsMin[0] = theMinAngle;
128 myColorHlsMax[0] = theMaxAngle;
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
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);
139 //! Sets color range corresponding to minimum and maximum values.
140 void SetColorRange (const Quantity_Color& theMinColor,
141 const Quantity_Color& theMaxColor)
143 theMinColor.Values (myColorHlsMin[0], myColorHlsMin[1], myColorHlsMin[2], Quantity_TOC_HLS);
144 theMaxColor.Values (myColorHlsMax[0], myColorHlsMax[1], myColorHlsMax[2], Quantity_TOC_HLS);
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; }
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; }
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; }
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; }
167 //! Returns the number of color scale intervals, 10 by default.
168 Standard_Integer GetNumberOfIntervals() const { return myNbIntervals; }
170 //! Sets the number of color scale intervals.
171 Standard_EXPORT void SetNumberOfIntervals (const Standard_Integer theNum);
173 //! Returns the color scale title string, empty string by default.
174 const TCollection_ExtendedString& GetTitle() const { return myTitle; }
176 //! Sets the color scale title string.
177 void SetTitle (const TCollection_ExtendedString& theTitle) { myTitle = theTitle; }
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; }
184 //! Returns the format of text.
185 const TCollection_AsciiString& Format() const { return myFormat; }
187 //! Sets the color scale auto label format specification.
188 void SetFormat (const TCollection_AsciiString& theFormat) { myFormat = theFormat; }
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;
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;
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);
207 //! Returns the user specified labels.
208 Standard_EXPORT void GetLabels (TColStd_SequenceOfExtendedString& theLabels) const;
210 //! Returns the user specified labels.
211 const TColStd_SequenceOfExtendedString& Labels() const { return myLabels; }
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);
221 //! Returns the user specified colors.
222 Standard_EXPORT void GetColors (Aspect_SequenceOfColor& theColors) const;
224 //! Returns the user specified colors.
225 const Aspect_SequenceOfColor& GetColors() const { return myColors; }
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);
231 //! Returns the position of labels concerning color filled rectangles, Aspect_TOCSP_RIGHT by default.
232 Aspect_TypeOfColorScalePosition GetLabelPosition() const { return myLabelPos; }
234 //! Sets the color scale labels position relative to color bar.
235 void SetLabelPosition (const Aspect_TypeOfColorScalePosition thePos) { myLabelPos = thePos; }
237 //! Returns the position of color scale title, Aspect_TOCSP_LEFT by default.
238 Aspect_TypeOfColorScalePosition GetTitlePosition() const { return myTitlePos; }
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; }
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; }
249 //! Sets true if the labels and colors used in reversed order.
250 void SetReversed (const Standard_Boolean theReverse) { myIsReversed = theReverse; }
252 //! Return TRUE if color transition between neighbor intervals
253 //! should be linearly interpolated, FALSE by default.
254 Standard_Boolean IsSmoothTransition() const { return myIsSmooth; }
256 //! Setup smooth color transition.
257 void SetSmoothTransition (const Standard_Boolean theIsSmooth) { myIsSmooth = theIsSmooth; }
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; }
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; }
269 //! Returns TRUE if the color scale has logarithmic intervals, FALSE by default.
270 Standard_Boolean IsLogarithmic() const { return myIsLogarithmic; }
272 //! Sets true if the color scale has logarithmic intervals.
273 void SetLogarithmic (const Standard_Boolean isLogarithmic) { myIsLogarithmic = isLogarithmic; }
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);
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
286 theBreadth = myBreadth;
287 theHeight = myHeight;
290 //! Sets the size of color bar.
291 void SetSize (const Standard_Integer theBreadth, const Standard_Integer theHeight)
293 myBreadth = theBreadth;
294 myHeight = theHeight;
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; }
301 //! Sets the width of color bar.
302 void SetBreadth (const Standard_Integer theBreadth) { myBreadth = theBreadth; }
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; }
308 //! Sets the height of color bar.
309 void SetHeight (const Standard_Integer theHeight) { myHeight = theHeight; }
311 //! Returns the bottom-left position of color scale, 0x0 by default.
312 void GetPosition (Standard_Real& theX, Standard_Real& theY) const
318 //! Sets the position of color scale.
319 void SetPosition (const Standard_Integer theX, const Standard_Integer theY)
325 //! Returns the left position of color scale, 0 by default.
326 Standard_Integer GetXPosition() const { return myXPos; }
328 //! Sets the left position of color scale.
329 void SetXPosition (const Standard_Integer theX) { myXPos = theX; }
331 //! Returns the bottom position of color scale, 0 by default.
332 Standard_Integer GetYPosition() const { return myYPos; }
334 //! Sets the bottom position of color scale.
335 void SetYPosition (const Standard_Integer theY) { myYPos = theY; }
337 //! Returns the font height of text labels, 20 by default.
338 Standard_Integer GetTextHeight() const { return myTextHeight; }
340 //! Sets the height of text of color scale.
341 void SetTextHeight (const Standard_Integer theHeight) { myTextHeight = theHeight; }
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;
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;
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;
361 //! Return true if specified display mode is supported.
362 virtual Standard_Boolean AcceptDisplayMode (const Standard_Integer theMode) const Standard_OVERRIDE { return theMode == 0; }
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;
369 //! Compute selection - not implemented for color scale.
370 virtual void ComputeSelection (const Handle(SelectMgr_Selection)& /*aSelection*/,
371 const Standard_Integer /*aMode*/) Standard_OVERRIDE {}
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;
380 //! Returns the upper value of given interval, or minimum for theIndex = 0.
381 Standard_Real GetIntervalValue (const Standard_Integer theIndex) const;
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;
391 //! Initialize text aspect for drawing the labels.
392 void updateTextAspect();
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);
405 //! Determine the maximum text label width in pixels.
406 Standard_Integer computeMaxLabelWidth (const TColStd_SequenceOfExtendedString& theLabels) const;
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);
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);
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);
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