#include <ImFusion/GL/ExplicitIntensityMask.h>

An ExplicitIntensityMask is a combination of an ExplicitMask and an IntensityMask. More...

Inheritance diagram for ExplicitIntensityMask:

Detailed Description

An ExplicitIntensityMask is a combination of an ExplicitMask and an IntensityMask.

It is created with a "reference image" and a "mask image". The reference image defines the pixel grid used for the pixel coordinate provided during mask value query. This location is then transformed to the mask image where the actual mask pixel value lookup takes place. Finally, that value is compared against the configured intensity range yielding whether the queried pixel is inside or outside the mask. In other words: it uses the ImageDescriptorWorld of the reference image and the pixel data of the mask image.

In contrast to Explicit mask, the mask-defining image can be of arbitrary type. Furthermore, this mask also supports non-pixel-direct mapping (i.e. the reference image and the mask image do not need to be of the same size necessarily). In this case, ExplicitIntensityMask will transform between the two pixel coordinate systems. However, be aware that this will decrease the performance of maskValue()!

The default intensity range of this mask will be [1..MAX] for integral type images and [0..1] for floating point type images.

Note: The range of allowed pixel values specified in setIntensityRange() refers to the storage pixel values in the mask image without applying shift/scale.

Public Member Functions
	ExplicitIntensityMask (const SharedImage &referenceImage, std::unique_ptr< SharedImage > maskImage)
	Creates a new ExplicitIntensityMask for the given image.

const SharedImage *	maskImage () const
	Returns the internal image representing the mask.

const vec2f &	intensityRange () const
	Returns the range of allowed pixel values.

void	setIntensityRange (const vec2f &range)
	Sets the range of allowed pixel values.

InterpolationMode	interpolationMode () const
	Returns the interpolation/filtering mode to use during pixel lookup of the reference image.

void	setInterpolationMode (InterpolationMode value)
	Sets the interpolation/filtering mode to use during pixel lookup of the reference image.

void	setBorderClamp (bool isClampToBorder)

bool	borderClamp () const
	If true, set sampler wrapping mode to ClampToBorder (default). If false, set to ClampToEdge.

void	setBorderColor (float color)

float	borderColor () const

const vec2f &	intensityRangeGl () const
	Returns the intensity ranges for GLmask.

Public Member Functions inherited from Mask
uint8_t	maskValue (const vec3i &coord, float value=-1.0f) const
	Convenience overload that calls `maskValue(coord, vec4f(value, value, value, 1.0f))`.

virtual std::unique_ptr< Mask >	resizedMask (const SharedImage &original, const Image &target) const
	Creates a copy of the current mask, resized to the dimensions of the target image.

Public Member Functions inherited from Configurable
virtual void	configureDefaults ()
	Retrieve the properties of this object, replaces values with their defaults and sets it again.

void	registerParameter (ParameterBase *param)
	Register the given Parameter or SubProperty, so that it will be configured during configure()/configuration().

void	unregisterParameter (const ParameterBase *param)
	Remove the given Parameter or SubProperty from the list of registered parameters.

	Configurable (const Configurable &rhs)

	Configurable (Configurable &&rhs) noexcept

Configurable &	operator= (const Configurable &)

Configurable &	operator= (Configurable &&) noexcept

Public Member Functions inherited from GlMask
	GlMask (const std::string &includePath)
	Instantiates a new GL::AbstractInclude using `IMAGE_MASK` as defineName and the given path the to retrieve the GLSL source code from.

Public Member Functions inherited from AbstractInclude
	AbstractInclude (const std::string &defineName, const std::string &includePath)
	Creates a AbstractInclude for the given define and with the corresponding GLSL file at includePath.

const std::string &	defineName () const
	Returns the name of define used by this include.

const std::string &	includePath () const
	Returns the path to the included shader file.

virtual std::function< std::string(const std::string &)>	includeCodeSubstitution () const
	Optionally the abstract include can provide a function to change the shader code.

virtual std::vector< AbstractInclude * >	dependentIncludes () const
	Returns a list of dependent abstract includes that need to be included as well.

virtual Fingerprint	fingerprint () const
	Provides a finger print of the include.

Public Member Functions inherited from MultiIncludable< GlMask >
std::shared_ptr< MultiIncludeType >	createMultiInclude (const std::string &replacementToken)
	Instantiates a new AbstractInclude instance where all occurrences of baseToken provided during construction are replaces with replacementToken according to the specified replacementScheme.

virtual int	setIncludeArguments (Program &prog, IncludeArgumentsTypes... includeArgs, const std::string &token) const=0
	Interface that multi includes should use to configure the shader include (such as setting uniforms, binding textures, etc).

Implementation of base interfaces
uint8_t	maskValue (const vec3i &coord, const vec4f &color) const override
	Returns 0 if the given pixel is outside the mask (i.e.

bool	isCompatible (const SharedImage *image) const override
	Returns `true` if the mask can be used with the given image or `false` otherwise.

bool	requiresPixelValue () const override
	Returns true if the maskValue() rely on the pixel value.

std::unique_ptr< TypedImage< uint8_t > >	createExplicitMask (const SharedImage &image, CreateOption createOption=CreateOption::DeepCopy) const override
	Creates an explicit mask representation of this mask for a given image.

int	setIncludeArguments (GL::Program &p, const std::string &prefix="mask") const override
	Called by users of GlMask in order to correctly setup the mask shader.

std::unique_ptr< GlImage >	createExplicitMaskGl (const GlImage &image, bool normalized=false) override
	Creates an explicit mask representation of this mask when applied to the given image.

GlMask *	glMask () override
	Returns the OpenGL-based implementation of the mask interface if available.

void	configure (const Properties *p) override
	Configure this object instance by de-serializing the given Properties.

void	configuration (Properties *p) const override
	Serialize the current object configuration into the given Properties object.

Additional Inherited Members
Public Types inherited from Mask
enum class	CreateOption { DeepCopy , ShallowCopyIfPossible }
	Enumeration of available behavior for createExplicitMask() More...

Public Types inherited from MultiIncludable< GlMask >
using	MultiIncludeType
	Alias for type of a multi-include instance of the original include.

Static Public Member Functions inherited from GlMask
static std::string	defineName ()
	Returns "IMAGE_MASK".

static std::string	defineSuffix ()
	Returns "MASK".

static std::string	multiIncludeDefine (const std::string &replacementToken)
	Returns `"IMAGE_" + toUpper(replacementToken)`

Public Attributes inherited from Configurable
Signal	signalParametersChanged
	Emitted whenever one of the registered Parameters' or SubPropertys' `signalValueChanged` signal was emitted.

Protected Member Functions inherited from MultiIncludable< GlMask >
	MultiIncludable (GlMask *crtpInstance, const std::string &baseToken, Flags< ShaderTextReplacement > replacementScheme)
	Instantiate and configure the MultiIncludable interface.

Protected Attributes inherited from Configurable
std::vector< Param >	m_params
	List of all registered Parameter and SubProperty instances.

Constructor & Destructor Documentation

◆ ExplicitIntensityMask()

ExplicitIntensityMask	(	const SharedImage &	referenceImage,
		std::unique_ptr< SharedImage >	maskImage )

Creates a new ExplicitIntensityMask for the given image.

Parameters

referenceImage	Image the mask is applied to
maskImage	Source image for the mask, must not be null

Member Function Documentation

◆ intensityRange()

const vec2f & intensityRange ( ) const

Returns the range of allowed pixel values.

Values outside this range will be masked.

Note: The intensity range refers to the storage pixel values in the mask image without applying shift/scale.

◆ setIntensityRange()

void setIntensityRange ( const vec2f & range )

Sets the range of allowed pixel values.

Values outside this range will be masked.

Note: The intensity range refers to the storage pixel values in the mask image without applying shift/scale.

◆ setBorderClamp()

void setBorderClamp ( bool isClampToBorder )

Parameters

isClampToBorder If true, set sampler wrapping mode to ClampToBorder (default). If false, set to ClampToEdge.

◆ setBorderColor()

void setBorderColor ( float color )

Parameters

color normalized for integer images, set borderColor if wrapping mode is ClampToBorder

◆ borderColor()

float borderColor ( ) const

Parameters

color normalized for integer images, set borderColor if wrapping mode is ClampToBorder

◆ maskValue()

uint8_t maskValue	(	const vec3i &	coord,
		const vec4f &	color ) const

overridevirtual

Returns 0 if the given pixel is outside the mask (i.e.

invisible/to be ignored) or a non-zero value if it is inside the mask (i.e. visible/to be considered).

This function takes both the pixel coordinate and pixel value as input. Concrete implementations of the Mask interface are free to use only either input for their decision if it makes sense. Also, it is up to the implementation whether it supports multi-channel images or not. Subclasses only supporting grayscale images should only use the first channel.

Parameters

coord	Pixel coordinate to be tested against the mask, can be outside of the image.
color	Pixel value (not normalized) to be tested against the mask. This parameter is only needed if requiresPixelValue() returns `true`, which can allow for optimizations where pixel lookup is expensive.

Implements Mask.

◆ isCompatible()

bool isCompatible ( const SharedImage * image ) const

overridevirtual

Returns true if the mask can be used with the given image or false otherwise.

Implements Mask.

◆ requiresPixelValue()

bool requiresPixelValue ( ) const

overridevirtual

Returns true if the maskValue() rely on the pixel value.

If this method returns false, the maskValue() method can be safely used with only the coordinate. This is useful to avoid an otherwise unnecessary and expensive pixel lookup.

Implements Mask.

◆ createExplicitMask()

std::unique_ptr< TypedImage< uint8_t > > createExplicitMask	(	const SharedImage &	image,
		CreateOption	createOption = CreateOption::DeepCopy ) const

overridevirtual

Creates an explicit mask representation of this mask for a given image.

Parameters

image	Reference image for which to create the mask, must be compatible.
createOption	Subclasses that already store an explicit representation of the mask can optionally return a non-owning TypedImage (shallow copy). If the returned TypedImage will outlive the source Mask, make sure to use CreateOption::DeepCopy.

Reimplemented from Mask.

◆ setIncludeArguments()

int setIncludeArguments	(	GL::Program &	p,
		const std::string &	prefix = "mask" ) const

overridevirtual

Called by users of GlMask in order to correctly setup the mask shader.

Subclasses should implement this function so that it correctly sets all needed uniforms and input textures to be used by the OpenGL shader instance. Make sure to use the given prefix argument instead of a hardcoded "mask" when defining uniform names to support multi-includes where the prefixes have been replaced with unique alternatives. Example:

p.setArgument(prefix + "UseRange", m_useRange);

Implements GlMask.

◆ createExplicitMaskGl()

std::unique_ptr< GlImage > createExplicitMaskGl	(	const GlImage &	inputImage,
		bool	normalized = false )

overridevirtual

Creates an explicit mask representation of this mask when applied to the given image.

Parameters

inputImage	Image to which the mask should be applied for each pixel in order to generate the explicit mask image. Must be compatible with the mask.
normalized	If the this parameter is `true` the resulting binary mask value will be created as CPU uint8_t values 0 and 255 (corresponding to 0 and 1 on the GPU), instead of 0 and 1 (0 and 1/255 on the GPU).

Reimplemented from GlMask.

◆ glMask()

GlMask * glMask ( )

overridevirtual

Returns the OpenGL-based implementation of the mask interface if available.

This function may return nullptr if this is not implemented (default).

Reimplemented from Mask.

◆ configure()

void configure ( const Properties * p )

overridevirtual

Configure this object instance by de-serializing the given Properties.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configuration() for the inverse functionality

Reimplemented from Configurable.

◆ configuration()

void configuration ( Properties * p ) const

overridevirtual

Serialize the current object configuration into the given Properties object.

The default implementation will do so automatically for all registered Parameter and SubProperty instances.

See also: configure() for the inverse functionality

Reimplemented from Configurable.

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

ImFusion/GL/ExplicitIntensityMask.h

Detailed Description

Public Member Functions

Implementation of base interfaces

Additional Inherited Members

Constructor & Destructor Documentation

◆ ExplicitIntensityMask()

Member Function Documentation

◆ intensityRange()

◆ setIntensityRange()

◆ setBorderClamp()

◆ setBorderColor()

◆ borderColor()

◆ maskValue()

◆ isCompatible()

◆ requiresPixelValue()

◆ createExplicitMask()

◆ setIncludeArguments()

◆ createExplicitMaskGl()

◆ glMask()

◆ configure()

◆ configuration()