# cee::ug::ScalarSettings

class `ScalarSettings` : public RefCountedObject

  Settings for a specific scalar result.

  See the topic Scalar Results

  The scalar result has various settings that can be configured to make a better visual appearance of your result data, for instance settings such as legend scheme, legend range and filtering.

  Each scalar result has its own settings. Get scalar settings for a specific scalar result by calling UnstructGridModel::scalarSettings() with the requested id.

      int scalarId = scalarResultInfos[0].id();
      cee::ug::ScalarSettings* settings = ugModel->scalarSettings(scalarId);

  Range

  The range specifies the minimum and maximum value for the color scheme to fill. Set a custom range with setRange(double min, double max) and get the current range using rangeMinimum() and rangeMaximum(). To set the color scheme to automatically span a range of scalar values, select a mode using setAutoRangeMode().

  Color mapping and scheme

  The color mapping can be either filled contours with uniform level size or continuous. The ColorMapper object can be accessed through colorMapper(). See ColorMapper for further description on setting color mapping and scheme.

  Legend

  The color legend provides an overlay item in the view that shows the current results legend colors, range and filtering. Legend visibility is toggled with setLegendVisibilityMode() The legend width, colors, line widths, tick marks and text can be heavily customized.

  Filtering

  Elements can be filtered based on scalar values and a filtering minimum and a filtering maximum. Elements with scalar values outside of the specified range, will be set invisible. Set the filtering visible range using setFringesElementFilteringVisibleRange(). And also choose to filter undefined values using setFilterUndefinedElements().

  Example

  This example will set the number of legend levels for the current fringes result and change the color scheme of the legend.

  Gets the scalar setting for the scalar result shown as fringes on the model

      int scalarId = scalarResultInfos[0].id();
      cee::ug::ScalarSettings* settings = ugModel->scalarSettings(scalarId);

  Sets number of legend levels to 5.

      settings->colorMapper().setTypeFilledContoursUniform(5);

  Sets the color scheme to normal inverted.

      settings->colorMapper().setColorScheme(cee::ug::ColorMapper::NORMAL_INVERTED);

  Use filter to only show values elements where the result value is in the interval from 20 to 99. (The scalar result in this data source has a minimum value of 0 and a maximum value of 99.)

  Set filtering range.

      settings->setFringesElementFilteringVisibleRange(20, 99);

  See the complete source code at: UnstructGrid: Set Scalar Settings on a Loaded Model

  See also

  ModelSpec and UnstructGridModel

  Public Types

  enum `MarkerPosition`

    Position of the custom markers to show above/below the color legend.

    Values:

    enumerator `ABOVE`

      Show the marker above the color legend.

    enumerator `BELOW`

      Show the marker below the color legend.

  enum `AutoRangeMode`

    Extent of the automatic range computation.

    Values:

    enumerator `OFF`

      Scalar range is not computed automatically.

    enumerator `ALL_ITEMS`

      Scalar range is computed automatically from scalar result values of all items in the model.

    enumerator `VISIBLE_ITEMS`

      Scalar range is computed automatically from scalar result values of visible items in the model.

  enum `LegendVisibilityMode`

    Control the visibility of the color legend.

    Values:

    enumerator `NEVER`

      Always hide the color legend for this result.

    enumerator `AUTO`

      Show the color legend for this result if used by any visible parts in the view (default)

    enumerator `ALWAYS`

      Always show the color legend for this result, no matter if it is in use or not.

  enum `TickMarksPosition`

    Position of the legend tick marks.

    LEFT/RIGHT are only for vertical legends. TOP/BOTTOM are only for horizontal legends. Default is FOLLOW_LAYOUT. Follow layout will have the tick marks on the “inside” of the legend.

    Values:

    enumerator `LEFT`

      Draw tick marks on the left side of the color legend.

    enumerator `RIGHT`

      Draw tick marks on the right side of the color legend.

    enumerator `TOP`

      Draw tick marks above the color legend.

    enumerator `BOTTOM`

      Draw tick marks below the color legend.

    enumerator `FOLLOW_LAYOUT`

      Automatically position the tick marks left or right based on the color legend’s alignment in the view (default)

  enum `LegendDirection`

    Select the orientation of the legend.

    Default is VERTICAL.

    Values:

    enumerator `HORIZONTAL`

      Draw a horizontal legend.

    enumerator `VERTICAL`

      Draw a vertical legend.

  Public Functions

  double `rangeMinimum`() const

    Returns the minimum value of the currently set range.

  double `rangeMaximum`() const

    Returns the maximum value of the currently set range.

  void `setRange`(double min, double max)

    Sets the range.

    The range given by min and max specifies the min and max value for the color scheme to fill.

    Note! Will not have any effect if auto full range is toggled on.

    See also

    setAutoRangeMode

  AutoRangeMode `autoRangeMode`() const

    Returns how the scalar range is computed automatically.

  void `setAutoRangeMode`(AutoRangeMode mode)

    Sets how the scalar range is computed automatically.

  const ColorMapper &`colorMapper`() const

    Returns the color mapper for these scalar settings.

  ColorMapper &`colorMapper`()

    Returns the color mapper for these scalar settings.

  const ContourLines &`contourLines`() const

    Returns the contour lines settings.

  ContourLines &`contourLines`()

    Returns the contour lines settings.

  bool `logarithmicMapping`() const

    Returns true if the mapper is using a logarithmic scale.

  void `setLogarithmicMapping`(bool logMapper)

    Sets logarithmic or linear mode of the mapper.

  bool `nodeAveragedValues`() const

    Returns true if node averaging is used.

  void `setNodeAveragedValues`(bool useNodeAveraging)

    Enables/disables the use of node averaged values.

  LegendVisibilityMode `legendVisibilityMode`() const

    Returns the visibility mode of the color legend.

  void `setLegendVisibilityMode`(LegendVisibilityMode legendVisibilityMode)

    Specifies the visibility of the color legend.

    The legend can be set to appear if used by any part in the model (AUTO, default), to always be shown (ALWAYS) or to never be shown (NEVER)

  Color3f `legendTextColor`() const

    Returns the legend text color.

  void `setLegendTextColor`(const Color3f &color)

    Sets the legend text color.

  Color3f `legendLineColor`() const

    Returns the legend line color.

  void `setLegendLineColor`(const Color3f &color)

    Sets the legend line color.

  unsigned int `legendLineWidth`() const

    Returns the legend line width.

  void `setLegendLineWidth`(unsigned int lineWidth)

    Sets the legend line width.

  unsigned int `legendBarWidth`() const

    Returns the width of the legend bar (filled boxes) in pixels.

  void `setLegendBarWidth`(unsigned int widthInPixels)

    Sets the width of the legend bar (filled boxes) in pixels.

  Str `customLegendTitle`() const

    Returns the custom legend title.

  void `setCustomLegendTitle`(const Str &title)

    Sets a custom legend title.

  bool `forceTickMarkLinesToCoverLegend`() const

    Returns true if the tick mark lines will be drawn on top of the legend bar for continuous legends.

    See also

    setForceTickMarkLinesToCoverLegend

  void `setForceTickMarkLinesToCoverLegend`(bool alwaysCover)

    Specifies if the tick mark lines should be drawn on top of the legend bar for continuous legends.

    This feature is off by default, causing the tick mark lines to not cover the legend but start on the right side so not to obscure the continuous gradient shown on the legend.

    By enabling this feature, the tick mark lines will be drawn on top of the legend bar and appear much in the same ways as the filled contours legends.

    Note! Only applies when the mapper type is CONTINUOUS

  bool `drawLegendWithMinimumValueOnTop`() const

    Returns true if the color legend is drawn in reverse order (with the minimum value on the top).

    See also

    setDrawLegendWithMinimumValueOnTop

  void `setDrawLegendWithMinimumValueOnTop`(bool minOnTop)

    Specifies if the color legend should be drawn in reverse order (with the minimum value on the top).

  bool `skipOverlappingTickMarkLabels`() const

    Returns true if overlapping tick mark labels will be hidden (default).

    Returns false if all tick mark labels are drawn without overlap checking.

    See also

    setSkipOverlappingTickMarkLabels

  void `setSkipOverlappingTickMarkLabels`(bool skip)

    Specifies if automatic hiding of overlapping tick mark labels should be enabled or not.

    Default is true (skip any overlapping tick mark labels to avoid texts on top of each other).

  LegendVisibilityMode `aboveBelowRangeColorMarkerVisibilityMode`() const

    Returns the mode used to determine if the above/below color markers should be shown or not.

    See also

    setAboveBelowRangeColorMarkerVisibilityMode

  void `setAboveBelowRangeColorMarkerVisibilityMode`(LegendVisibilityMode mode)

    Specifies if above/below color markers should be visible or not.

    Auto will draw above/below if different from top/bottom colors. Default is never.

  TickMarksPosition `tickMarksPosition`() const

    Gets the position of the color legend’s tick marks.

  void `setTickMarksPosition`(TickMarksPosition position)

    Sets the position of the color legend’s tick marks.

    LEFT/RIGHT are only for vertical legends. TOP/BOTTOM are only for horizontal legends. If set to FOLLOW_LAYOUT (default), the tick mark position will be decided from the overlay items layout in the view.

  unsigned int `tickMarkLabelsMinimumDistance`() const

    Returns the minimum distance between tick mark labels.

  void `setTickMarkLabelsMinimumDistance`(unsigned int distance)

    Sets the minimum distance between tick mark labels.

  LegendDirection `legendDirection`() const

    Returns the direction of the color legend.

  void `setLegendDirection`(LegendDirection direction)

    Sets the direction of the color legend.

  bool `drawLegendBackground`() const

    Sets if a background should be drawn for the legend.

  void `setDrawLegendBackground`(bool drawBackground)

    Returns true if a background is drawn for the legend.

  Color3f `legendBackgroundColor`() const

    Returns the color of the legend background.

  void `setLegendBackgroundColor`(const Color3f &color)

    Sets the color of the legend background.

    The legend does not draw the background by default. Set setDrawLegendBackground(true) to draw a background behind the legend. This is useful when you need to improve the contrast between the tick value labels and the background. The background opacity is set using setLegendBackgroundOpacity().

  float `legendBackgroundOpacity`() const

    Returns the opacity of the legend background.

  void `setLegendBackgroundOpacity`(float opacity)

    Sets the legend background opacity.

    The legend does not draw the background by default. Set setDrawLegendBackground(true) to draw a background behind the legend.

  Color3f `legendBackgroundBorderColor`() const

    Returns the color of the legend background border.

  void `setLegendBackgroundBorderColor`(const Color3f &color)

    Sets the color of the legend background border.

  bool `isSingleColorZeroRangeModeEnabled`(Color3f *color = NULL) const

    Returns true if single color for zero range legend mode is used.

    See also

    setSingleColorZeroRangeMode

  void `setSingleColorZeroRangeMode`(const Color3f &color)

    Specifies that results with a zero range legend (min == max) should be shown with the specified color.

    The color legend will show this color and the corresponding value once in the middle of the color legend.

    To disable this mode and get back to the default way of showing zero range legends, use the disableSingleColorZeroRangeMode() method.

  void `disableSingleColorZeroRangeMode`()

    Disables single color for zero range legend mode.

    Revert to using the default way of showing zero range legends (all tick marks same value)

  bool `forceUniformTickMarkSpacing`() const

    Returns true (default) if the color legend should be rendered with evenly sized levels.

    The (possibly) uneven spacing of the level values or custom continuous tick marks are disregarded

  void `setForceUniformTickMarkSpacing`(bool forceUniformSpacing)

    Sets that all tick marks should be evenly distributed in the color legend, despite the uneven size of each level.

    The default value is true, which will render a color legend where all the levels have the same size or all the continuous custom tick marks with even spacing.

  bool `forceUniformTextureLevels`() const

    Returns true if the color legend texture is forced to have evenly spaced texture levels.

    ‘

    See also

    setForceUniformTextureLevels

  void `setForceUniformTextureLevels`(bool forceUniformLevels)

    Sets that all levels should be evenly distributed in the color legend texture if:

    - Color mapper type is set to either FILLED_CONTOURS or FILLED_CONTOURS_UNIFORM and
    - One or more levels have a different size/range than the rest

    The default value is false

    See also

    ColorMapper::type

  char `numericFormat`() const

    Returns the numeric format used to show the legend tick values.

    See also

    setNumericFormat

  void `setNumericFormat`(char format)

    Sets the numeric format to use when showing the legend tick values.

    Available options:

    - ’g/G’ : Use the shortest representation (‘e’ or ‘f’) (default). Example: 392.65
    - ’f/F’ : Decimal floating point. Example: 392.65
    - ’e/E’ : Scientific notation. Example: 3.9265e+2

    Capital letters will give a capital exp letter. E.g.: 2.3e+5 vs 2.3E+5

  int `numericPrecision`() const

    Returns the numeric precision used to show the legend tick values.

    See also

    setNumericPrecision

  void `setNumericPrecision`(int precision)

    Sets the numeric precision to use when showing the legend tick values.

    - For ‘f’ and ‘e’ mode: The number of digits after the decimal point to show
    - For ‘g’ mode: The maximum number of significant digits to show
  double `numericScalingConstant`() const

    Returns the constant term of numeric scaling of the values in the tick marks on the color legend.

    See also

    setNumericScaling

  double `numericScalingFirstDegreeFactor`() const

    Returns the first degree term of numeric scaling of the values in the tick marks on the color legend.

    See also

    setNumericScaling

  void `setNumericScaling`(double constantTerm, double firstDegreeTerm)

    Sets the numeric scaling of the values in the tick marks on the color legend.

    This method allows for applying a first degree function on the values to show as tick marks on the color legend before displaying them. This might be useful to show the result in another unit than what is used in the data model (e.g. convert velocity from miles/hour to m/s).

    The value shown as tick marks on the color legend will be:

        DisplayValue = ConstantTerm + ResultValue*FirstDegreeTerm

    The default is constantTerm = 0 and firstDegreeTerm = 1 (no scaling).

  void `addColorMarker`(MarkerPosition position, const Color3f &color, const Str &description)

    Adds a custom color marker to the color legend.

    This can be used to show the value and name for above, below and undefined colors as defined in the color mapper. Any number of markers can be shown above or below the color legend

  size_t `colorMarkerCount`() const

    Returns the number of custom color markers on the color legend.

  MarkerPosition `colorMarkerPosition`(size_t index) const

    Returns the position (above or below) of the custom color marker with the given index.

  Color3f `colorMarkerColor`(size_t index) const

    Returns the color of the custom color marker with the given index.

  Str `colorMarkerDescription`(size_t index) const

    Returns the description text of the custom color marker with the given index.

  void `clearColorMarkers`()

    Removes all the color markers from the color legend.

    See also

    addColorMarker

  unsigned int `colorMarkerBoxHeight`() const

    Returns the height of a legend custom color marker.

  void `setColorMarkerBoxHeight`(unsigned int height)

    Sets the height of a legend custom color marker.

    The size is the same for all custom markers in a legend. Default size is 25.

  unsigned int `colorMarkerMargin`() const

    Returns the margin between legend custom color markers.

  void `setColorMarkerMargin`(unsigned int margin)

    Sets the margin between legend custom color marker.

  bool `isFringesElementFilteringEnabled`() const

    Returns true if element filtering based on fringes scalar is enabled for this scalar result.

  void `disableFringesElementFiltering`()

    Disables element filtering when this scalar is displayed as fringes.

    See also

    setFringesElementFilteringVisibleRange()

  double `fringesElementFilteringVisibleRangeMinimum`() const

    Returns the minimum scalar value for the filtering.

  double `fringesElementFilteringVisibleRangeMaximum`() const

    Returns the maximum scalar value for the filtering.

  void `setFringesElementFilteringVisibleRange`(double min, double max)

    Sets the visible range for fringe (scalar) element filtering to min and max.

    Elements can be filtered based on the fringes scalar result values. This function defines the visible range. Elements with fringe scalar values outside of this range will be set invisible.

    Warning

    Note that for result mappings other than PER_ELEMENT, elements will be flagged as invisible whenever at least one of the associated scalar values is outside the specified range.

  bool `filterUndefinedElements`() const

    Returns true if elements with undefined scalar result(s) should be filtered (default false).

    See also

    setFilterUndefinedElements

  void `setFilterUndefinedElements`(bool filter)

    Specifies if the elements with undefined (cee::UNDEFINED_DOUBLE) or no results should be filtered or not.

    Default is false, which means that the undefined elements will be shown even if filtering is enabled. To hide the undefined elements when doing filtering, set this setting to true.

    See also

    enableFringesElementFiltering()

    Warning

    Note that for result mappings other than PER_ELEMENT, elements will be identified as undefined whenever at least one of the associated scalar values is undefined.

  bool `showDistributionOnLegend`() const

    Returns true if the distribution curve is shown on the legend.

  void `setShowDistributionOnLegend`(bool show)

    Sets whether to show a distribution curve on the color legend.

  int `distributionBinCount`() const

    Returns the number of bins to use for distribution histogram computation.

  void `setDistributionBinCount`(int count)

    Sets the number of bins to use for distribution histogram computation.

    Parameters: | count – Number of bins. Must be > 0. Default is 100.

  float `distributionCurveWidth`() const

    Returns the line width used to draw the distribution curve.

  void `setDistributionCurveWidth`(float width)

    Sets the line width used to draw the distribution curve.

    Parameters: | width – Line width in pixels. Default is 1.0.

  float `distributionConcentrationThreshold`() const

    Returns the concentration threshold used to decide when to hide the distribution curve shown on the color legend.

    The threshold is a ratio in the interval [0.0, 1.0]. When computing a distribution for the legend two ratios are evaluated:

    - bin concentration ratio: the fraction of the (binned) values that fall in the single most populated histogram bin (max bin count / total binned values).
    - problematic ratio: the fraction of problematic values (undefined or invalid) among all values ((undefined + invalid) / total value count).

    If either of these ratios exceeds the concentration threshold the distribution curve is considered unreliable and will be hidden. Typical meanings:

    - 1.0 : never hide the curve (default)
    - 0.1 : hide if more than 10% of values are concentrated in one bin or more than 10% are undefined/invalid
    - 0.0 : hide in all practical cases unless both ratios are exactly zero

    Invalid inputs (NaN/Inf or values outside the 0.0–1.0 range) are rejected by the underlying implementation and treated as the default (1.0, i.e. “never hide”).

    Returns: | The concentration threshold as a ratio (0.0 to 1.0).

  void `setDistributionConcentrationThreshold`(float threshold)

    Sets the concentration threshold used to decide when to hide the distribution curve on the legend.

    The supplied threshold is a ratio in the range [0.0, 1.0] and controls hiding behavior:

    - Larger values make hiding less likely; 1.0 means “never hide”.
    - Smaller values make hiding more aggressive; for example, 0.1 will hide curves when more than 10% of values are concentrated in a single bin or more than 10% of values are undefined/invalid.

    Invalid values (NaN/Inf or out-of-range) will be rejected by the underlying implementation and reset to the default (1.0).

    Parameters: | threshold – The concentration threshold as a ratio (0.0 to 1.0).

Conversation saved
HOOPSY BETA

### Hello! I'm HOOPSY

Your multilingual generative AI assistant for documentation. Ask me anything about HOOPS Envision for Desktop in your own language, or choose a sample question below to start a conversation:

What is HOOPS Envision for Desktop?
What are the latest release notes for HOOPS Envision for Desktop?
How do I start evaluating HOOPS Envision for Desktop?
How do I write my first sample application?
How can I get assistance?

HOOPSY may store conversations according to OpenAI's policy. Responses may not always be accurate.

HOOPSY is thinking...