GlReduction Class Reference

#include <ImFusion/GL/GlReduction.h>

High-performance implementation of a reduction of 2D and 3D images using OpenGL. More...

Inheritance diagram for GlReduction:

Detailed Description

High-performance implementation of a reduction of 2D and 3D images using OpenGL.

This class provides a set of reduction operators that can be applied to either a GlImage or alternatively an ImageMath::GlExpr. Furthermore, you can apply the reduction to only a subregion of the image or alternatively optionally provide a GlMask to dynamically exclude individual pixels/regions from the reduction.

Usage example:

GlImage* img = ...;
GlReduction reduction(GlReduction::MIN);
std::vector<double> mins = reduction.reduce(*img);
// `mins` will contain the minimum pixel value in `img` for each channel

Note

Due to the needed shaders and buffers, the instantiation of a GlReduction instance is rather expensive. You should cache it if possible. Alternatively, you can use the GlMinReduction, GlMaxReduction, GlSumReduction, GlProductReduction, or GlAverageReduction specializations that implement the GL::InstanceManager interface for caching.

Public Types
enum	ReductionOperator {   MIN , MAX , SUM , PRODUCT ,   AVERAGE , AVERAGE_ABSOLUTE }
	Operation to be performed by reduction. More...

Public Member Functions
	GlReduction (ReductionOperator reductionOperator)
	Creates a new GlReduction instance using the given reduction oparator in reduce().
	GlReduction (GlReduction &&other) noexcept
GlReduction &	operator= (GlReduction &&) noexcept
std::vector< double >	reduce (const GlImage &img, const GlMask *mask=nullptr, std::vector< vec3i > *outArgMinMax=nullptr)
	Reduces the given input image and returns the reduction result for each channel.
std::vector< double >	reduce (const ImageMath::GlExpr &expr, const ImageDescriptor &desc, std::vector< vec3i > *outArgMinMax=nullptr)
	Reduces the given input image and returns the reduction result for each channel.
std::vector< double >	reduceSubregion (const GlImage &img, const vec3i &subregion, const GlMask *mask=nullptr, std::vector< vec3i > *outArgMinMax=nullptr)
	Reduces the given subregion of the input image and returns the reduction result for each channel.

Member Enumeration Documentation

ReductionOperator

enum ReductionOperator

Operation to be performed by reduction.

Enumerator
MIN	Find the minimum element.
MAX	Find the maximum element.
SUM	Compute the sum of all elements.
PRODUCT	Compute the product of all elements.
AVERAGE	Compute the average of all elements.
AVERAGE_ABSOLUTE	Compute the average of the absolute values of all elements.

Constructor & Destructor Documentation

GlReduction()

GlReduction ( ReductionOperator reductionOperator )

explicit

Creates a new GlReduction instance using the given reduction oparator in reduce().

Exceptions

std::runtime_error

if initialization of the OpenGL resources fails.

Member Function Documentation

reduce() [1/2]

std::vector< double > reduce	(	const GlImage &	img,
		const GlMask *	mask = nullptr,
		std::vector< vec3i > *	outArgMinMax = nullptr )

Reduces the given input image and returns the reduction result for each channel.

Result values are normalized intensities as they reside on GPU memory. If you want the original intensity domain convert the result using GlUtils::normalizedToStorage().

Parameters

img	The input image for the reduction.
mask	Optional image mask. Only image values under locations with nonzero mask values will be considered for the reduction.
outArgMinMax	Optional output parameter for returning the argmin/argmax result. If this is a minimum/maximum reduction you will find the channel-wise pixel coordinates of a min/max value. It is undefined which coordinate is returned in case the argmin/argmax is not unique.

Exceptions

std::runtime_error

if initialization of the OpenGL resources fails.

reduce() [2/2]

std::vector< double > reduce	(	const ImageMath::GlExpr &	expr,
		const ImageDescriptor &	desc,
		std::vector< vec3i > *	outArgMinMax = nullptr )

Reduces the given input image and returns the reduction result for each channel.

Returns the original values as provided by expr.

namespace IM = ImageMath;
SharedImage img(...);
auto res = GlReduction(GlReduction::MIN).reduce(IM::GlExpr((IM::makeArray(img) + 3).abs()), img.descriptor());

Note

Reduction of GlExprs can only be used with the minimum, maximum, sum, or product reduction operator. Using this overload with average or average-of-absolutes mode will yield undefined behavior!

Parameters

expr	A ImageMath::GlExpr representing any arithmetic expression on images.
outArgMinMax	Optional output parameter for returning the argmin/argmax result. If this is a minimum/maximum reduction you will find the channel-wise pixel coordinates of a min/max value. It is undefined which coordinate is returned in case the argmin/argmax is not unique.

Exceptions

std::runtime_error

if initialization of the OpenGL resources fails.

reduceSubregion()

std::vector< double > reduceSubregion	(	const GlImage &	img,
		const vec3i &	subregion,
		const GlMask *	mask = nullptr,
		std::vector< vec3i > *	outArgMinMax = nullptr )

Reduces the given subregion of the input image and returns the reduction result for each channel.

Result values are normalized intensities as they reside on GPU memory. If you want the original intensity domain convert the result using GlUtils::normalizedToStorage().

Parameters

img	The input image for the reduction.
subregion	Size of the subregion for which to perform the reduction. It is not possible to define an offset: subregion and image will always share the same origin.
mask	Optional image mask. Only image values under locations with nonzero mask values will be considered for the reduction.
outArgMinMax	Optional output parameter for returning the argmin/argmax result. If this is a minimum/maximum reduction you will find the channel-wise pixel coordinates of a min/max value. It is undefined which coordinate is returned in case the argmin/argmax is not unique.

Exceptions

std::runtime_error

if initialization of the OpenGL resources fails.

---

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

• ImFusion/GL/GlReduction.h