Base class defining an interface for color scales. More...

#include <color_scale.h>

Inheritance diagram for cgv::media::color_scale:

Public Member Functions
virtual	~color_scale ()
	Destruct this color scale.

virtual bool	is_discrete () const =0
	Return whether the color scale represents a discrete mapping.

virtual bool	is_opaque () const
	Return whether the color scale maps to opacity.

virtual void	set_domain (cgv::vec2 domain)
	Set the input domain of scalars that will be mapped.

cgv::vec2	get_domain () const
	Get the input domain of scalars that will be mapped.

virtual void	set_clamped (bool clamped)
	Set whether the input values are clamped to the domain before mapping.

bool	is_clamped () const
	Get whether the input values are clamped to the domain before mapping.

virtual void	set_reversed (bool reverse)
	Set whether the output color ramp is reversed.

bool	is_reversed () const
	Get whether the output color ramp is reversed.

virtual void	set_unknown_color (cgv::rgba color)
	Set the color returned for scalars outside the domain if clamping is disabled.

cgv::rgba	get_unknown_color () const
	Get the color returned for scalars outside the domain if clamping is disabled.

virtual float	normalize_value (float value) const
	Map a value through the scale and return a normalized value in the range [0,1].

virtual cgv::rgba	map_value (float value) const
	Map a value through the scale and return a RGBA color.

virtual cgv::rgb	get_mapped_color (float value) const
	Map a value through the scale and return a RGB color.

virtual float	get_mapped_opacity (float value) const
	Map a value through the scale and return an opacity.

virtual cgv::rgba	get_indexed_color (size_t index) const
	Map a discrete index through the lookup table and return a RGBA color.

virtual size_t	get_indexed_color_count () const
	return the number of available indexed colors.

virtual std::vector< cgv::rgba >	quantize (size_t count) const =0
	Return count uniformly spaced samples from the color ramp or all indexed colors.

virtual std::vector< float >	get_ticks (size_t request_count) const =0
	Evaluate the color scheme at n uniformly-spaced positions within the range [0,1].

cgv::data::time_point	get_modified_time () const
	Get the time point of the last modification of this object.

Protected Member Functions
void	modified ()
	Update the object's modified time.

bool	is_unknown (float value) const
	Test whether the value is outside the domain according to the mapping options.

float	map_range_safe (float value, float in_left, float in_right, float out_left, float out_right) const
	Remap a scalar value from an input range to and output range while safely handling empty ranges.

Detailed Description

Base class defining an interface for color scales.

A color_scale is a function that maps scalar values from an input domain to a RGB output range. The color_scale can optionally also map to opacity. The mapping from input to output values can be linear or follow some other transform, like log or power scales. color_scales can have a continuous or discrete input domain and can be sampled with continuous scalar values or, in case of discrete scales, additionally with indexed lookup.

Definition at line 22 of file color_scale.h.

Constructor & Destructor Documentation

◆ ~color_scale()

virtual cgv::media::color_scale::~color_scale ( )

inlinevirtual

Destruct this color scale.

Definition at line 25 of file color_scale.h.

Member Function Documentation

◆ get_domain()

cgv::vec2 cgv::media::color_scale::get_domain ( ) const

inline

Get the input domain of scalars that will be mapped.

Returns: The domain.

Definition at line 52 of file color_scale.h.

Referenced by cgv::render::device_color_scale::get_arguments(), cgv::media::continuous_color_scale::get_ticks(), cgv::media::transfer_function::get_ticks(), is_unknown(), cgv::media::continuous_color_scale::normalize_value(), cgv::media::discrete_color_scale::normalize_value(), cgv::media::transfer_function::normalize_value(), cgv::media::transfer_function::rescale(), and cgv::media::transfer_function::set_domain().

◆ get_indexed_color()

virtual cgv::rgba cgv::media::color_scale::get_indexed_color ( size_t index ) const

inlinevirtual

Map a discrete index through the lookup table and return a RGBA color.

This is typically only defined for discrete color scales.

Parameters

index The index into the lookup table.

Returns: The mapped color.

Reimplemented in cgv::media::discrete_color_scale.

Definition at line 134 of file color_scale.h.

◆ get_indexed_color_count()

virtual size_t cgv::media::color_scale::get_indexed_color_count ( ) const

inlinevirtual

return the number of available indexed colors.

This is typically only defined for discrete color scales.

Returns: The count.

Reimplemented in cgv::media::discrete_color_scale.

Definition at line 142 of file color_scale.h.

◆ get_mapped_color()

virtual cgv::rgb cgv::media::color_scale::get_mapped_color ( float value ) const

inlinevirtual

Map a value through the scale and return a RGB color.

Parameters

value The value to map.

Returns: The mapped color.

Reimplemented in cgv::media::continuous_color_scale, cgv::media::discrete_color_scale, and cgv::media::transfer_function.

Definition at line 117 of file color_scale.h.

◆ get_mapped_opacity()

virtual float cgv::media::color_scale::get_mapped_opacity ( float value ) const

inlinevirtual

Map a value through the scale and return an opacity.

Parameters

value The value to map.

Returns: The mapped color.

Reimplemented in cgv::media::transfer_function.

Definition at line 125 of file color_scale.h.

◆ get_modified_time()

cgv::data::time_point cgv::media::color_scale::get_modified_time ( ) const

inline

Get the time point of the last modification of this object.

Returns: The time point.

Definition at line 171 of file color_scale.h.

◆ get_ticks()

virtual std::vector< float > cgv::media::color_scale::get_ticks ( size_t request_count ) const

pure virtual

Evaluate the color scheme at n uniformly-spaced positions within the range [0,1].

Parameters

n	The number of samples to interpolate.

Returns: The sequence of interpolated colors.

Get a sequence of locations within the input domain representing tickmark locations for, e.g. a scale legend. The number of returned ticks is approximately equal to request_count. Implementations should aim to generate nicely-spaced and located ticks according to the set domain and mapping.

Parameters

request_count The number of requested tickmarks.

Returns: A sequence of tick locations.

Implemented in cgv::media::continuous_color_scale, cgv::media::discrete_color_scale, and cgv::media::transfer_function.

◆ get_unknown_color()

cgv::rgba cgv::media::color_scale::get_unknown_color ( ) const

inline

Get the color returned for scalars outside the domain if clamping is disabled.

Returns: The color.

Definition at line 93 of file color_scale.h.

Referenced by cgv::render::device_color_scale::get_arguments(), cgv::media::continuous_color_scale::get_mapped_color(), cgv::media::discrete_color_scale::get_mapped_color(), and cgv::media::transfer_function::get_mapped_color().

◆ is_clamped()

bool cgv::media::color_scale::is_clamped ( ) const

inline

Get whether the input values are clamped to the domain before mapping.

Returns: True if clamped, false otherwise.

Definition at line 64 of file color_scale.h.

Referenced by cgv::render::device_color_scale::get_arguments(), is_unknown(), cgv::media::continuous_color_scale::normalize_value(), and cgv::media::discrete_color_scale::normalize_value().

◆ is_discrete()

virtual bool cgv::media::color_scale::is_discrete ( ) const

pure virtual

Return whether the color scale represents a discrete mapping.

If true, implementations should allow indexed color lookup. If false, indexed color lookup is potentially undefined.

Returns: True if the mapping uses discrete input values, false otherwise.

Implemented in cgv::media::continuous_color_scale, cgv::media::discrete_color_scale, and cgv::media::transfer_function.

◆ is_opaque()

virtual bool cgv::media::color_scale::is_opaque ( ) const

inlinevirtual

Return whether the color scale maps to opacity.

If true, implementations should provide mapped opacity alongside mapped color values. If false, the returned opacity should always be 1.

Returns: True if opacity is supported, false otherwise.

Reimplemented in cgv::media::continuous_color_scale, cgv::media::discrete_color_scale, and cgv::media::transfer_function.

Definition at line 39 of file color_scale.h.

◆ is_reversed()

bool cgv::media::color_scale::is_reversed ( ) const

inline

Get whether the output color ramp is reversed.

Returns: True if reversed, false otherwise.

Definition at line 76 of file color_scale.h.

Referenced by cgv::media::continuous_color_scale::normalize_value(), cgv::media::continuous_color_scale::quantize(), cgv::media::discrete_color_scale::quantize(), cgv::media::transfer_function::quantize_color(), and cgv::media::transfer_function::quantize_opacity().

◆ is_unknown()

bool cgv::media::color_scale::is_unknown ( float value ) const

protected

Test whether the value is outside the domain according to the mapping options.

Parameters

value The value to test.

Returns: True if the value is unknown, false otherwise.

Definition at line 28 of file color_scale.cxx.

References get_domain(), and is_clamped().

Referenced by cgv::media::continuous_color_scale::get_mapped_color(), cgv::media::discrete_color_scale::get_mapped_color(), and cgv::media::transfer_function::get_mapped_color().

◆ map_range_safe()

float cgv::media::color_scale::map_range_safe	(	float	value,
		float	in_left,
		float	in_right,
		float	out_left,
		float	out_right
	)		const

protected

Remap a scalar value from an input range to and output range while safely handling empty ranges.

The value is not clamped to the input domain.

Parameters

value	The value to map.
in_left	The input range lower bound.
in_right	The input range upper bound.
out_left	The output range lower bound.
out_right	The output range upper bound.

Returns: The mapped value.

Definition at line 33 of file color_scale.cxx.

Referenced by cgv::media::continuous_color_scale::normalize_value(), cgv::media::discrete_color_scale::normalize_value(), cgv::media::transfer_function::normalize_value(), and cgv::media::transfer_function::rescale().

◆ map_value()

virtual cgv::rgba cgv::media::color_scale::map_value ( float value ) const

inlinevirtual

Map a value through the scale and return a RGBA color.

Parameters

value The value to map.

Returns: The mapped color.

Reimplemented in cgv::media::transfer_function.

Definition at line 109 of file color_scale.h.

◆ modified()

void cgv::media::color_scale::modified ( )

inlineprotected

Update the object's modified time.

Definition at line 177 of file color_scale.h.

Referenced by cgv::media::transfer_function::remove_color_point(), cgv::media::transfer_function::remove_opacity_point(), set_clamped(), cgv::media::transfer_function::set_color_interpolation(), cgv::media::continuous_color_scale::set_diverging(), set_domain(), cgv::media::transfer_function::set_domain(), cgv::media::transfer_function::set_interpolation(), cgv::media::continuous_color_scale::set_log_base(), cgv::media::continuous_color_scale::set_midpoint(), cgv::media::transfer_function::set_opacity_interpolation(), cgv::media::continuous_color_scale::set_pow_exponent(), set_reversed(), cgv::media::continuous_color_scale::set_scheme(), cgv::media::discrete_color_scale::set_scheme(), and cgv::media::continuous_color_scale::set_transform().

◆ normalize_value()

virtual float cgv::media::color_scale::normalize_value ( float value ) const

inlinevirtual

Map a value through the scale and return a normalized value in the range [0,1].

Parameters

value The value to map.

Returns: The normalized value.

Reimplemented in cgv::media::continuous_color_scale, cgv::media::discrete_color_scale, and cgv::media::transfer_function.

Definition at line 101 of file color_scale.h.

◆ quantize()

virtual std::vector< cgv::rgba > cgv::media::color_scale::quantize ( size_t count ) const

pure virtual

Return count uniformly spaced samples from the color ramp or all indexed colors.

Will return a reversed color ramp if get_reversed() returns true. The number of returned samples may be different from count if color values cannot be interpolated as is typically the case for discrete color scales.

Parameters

count The number of samples to return.

Returns: The sequence of sampled colors.

Implemented in cgv::media::continuous_color_scale, cgv::media::discrete_color_scale, and cgv::media::transfer_function.

◆ set_clamped()

void cgv::media::color_scale::set_clamped ( bool clamped )

virtual

Set whether the input values are clamped to the domain before mapping.

Parameters

clamped Set to true to enable clamping.

Definition at line 14 of file color_scale.cxx.

References modified().

◆ set_domain()

void cgv::media::color_scale::set_domain ( cgv::vec2 domain )

virtual

Set the input domain of scalars that will be mapped.

Defaults to [0,1].

Parameters

domain The new domain.

Reimplemented in cgv::media::continuous_color_scale, and cgv::media::transfer_function.

Definition at line 9 of file color_scale.cxx.

References modified().

Referenced by cgv::media::transfer_function::rescale(), and cgv::media::continuous_color_scale::set_domain().

◆ set_reversed()

void cgv::media::color_scale::set_reversed ( bool reverse )

virtual

Set whether the output color ramp is reversed.

Parameters

reverse Set to true to reverse.

Definition at line 21 of file color_scale.cxx.

References modified().

◆ set_unknown_color()

virtual void cgv::media::color_scale::set_unknown_color ( cgv::rgba color )

inlinevirtual

Set the color returned for scalars outside the domain if clamping is disabled.

Parameters

color The color.

Definition at line 83 of file color_scale.h.

The documentation for this class was generated from the following files:

cgv/media/color_scale.h
cgv/media/color_scale.cxx

Public Member Functions

Protected Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ~color_scale()

Member Function Documentation

◆ get_domain()

◆ get_indexed_color()

◆ get_indexed_color_count()

◆ get_mapped_color()

◆ get_mapped_opacity()

◆ get_modified_time()

◆ get_ticks()

◆ get_unknown_color()

◆ is_clamped()

◆ is_discrete()

◆ is_opaque()

◆ is_reversed()

◆ is_unknown()

◆ map_range_safe()

◆ map_value()

◆ modified()

◆ normalize_value()

◆ quantize()

◆ set_clamped()

◆ set_domain()

◆ set_reversed()

◆ set_unknown_color()