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.

../_images/scalar.png

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.