GlJointHistogram Class Reference

#include <ImFusion/GL/GlJointHistogram.h>

Provides an interface to calculate the joint histogram of an image either on the CPU or on the GPU. More...

Inheritance diagram for GlJointHistogram:

Detailed Description

Provides an interface to calculate the joint histogram of an image either on the CPU or on the GPU.

The GPU implementation supports two modes:

• If your hardware/driver combination supports OpenGL 4.3 (more precisely the ARB_shader_image_load_store and ARB_compute_shader extensions), GlHistogram will use OpenGL compute shaders.
• If your hardware/driver combination does not support OpenGL 4.3, GlHistogram will fall back to an OpenGL 3.3 implementation based on "Efficient Histogram Generation Using Scattering on GPUs" (Scheuermann, Hensley). Please be aware that this implementation is slower and may be less precise due to float arithmetic.

Usage Example:

GlJointHistogram histogrammer;
histogrammer.setBinCount({128, 128});
if (!histogrammer.update(img1, img2))
    return error();
const TypedImage<float>* histogram = histogrammer.typedData();

Note

- This class can calculate histograms for images with up to 4 channels.

• Due to using float as internal representation the histogram counts may become inaccurate or even saturate for values beyond 2^24.
• Due to the needed shaders and buffers, the instantiation of a GlJointHistogram instance is rather expensive. You should cache it if possible.

See also

GlHistogram

Public Types
enum	Device { Device_CPU = 0 , Device_GPU = 1 }

Public Member Functions
	GlJointHistogram ()
	Creates a new GlJointHistogram instance with default settings.

Configure Joint Histogram Computation
vec2i	binCount () const
	Returns the number of histogram bins.
void	setBinCount (vec2i bins)
	Sets the number of histogram bins.

Run Joint Histogram Computation
bool	update (SharedImage *image1, SharedImage *image2, Device device=Device_GPU)
	Computes the joint histogram of the given images and returns true on success.
bool	update (const GlImage *image1, const GlImage *image2, const mat4 &matrix=mat4::Identity())
	Computes the joint histogram of the given images on the GPU and returns true on success.
bool	update (const MemImage *image1, const MemImage *image2, const mat4 &matrix=mat4::Identity())
	Computes the joint histogram of the given images on the CPU and returns true on success.

Access Results of the Computation
const SharedImage *	data () const
	Returns the joint histogram data stored as a single channel 2D float image while maintaining its ownership.
const TypedImage< float > *	typedData () const
	Returns the histogram data as single channel 2D float image while maintaining its ownership.
std::unique_ptr< SharedImage >	releaseData ()
	Returns the histogram data as a single channel 2D float image and passes ownership of the returned pointer to the caller.
SharedImage *	dataUint () const
	Internal: Returns the histogram data as a 2D unsigned integer image.
double	entropy ()
	Return the image entropy based on the computed histogram.

Member Enumeration Documentation

Device

enum Device

Enumerator
Device_CPU	Compute the histogram on the CPU.
Device_GPU	Compute the histogram on the GPU, automatically detect OpenGL version to use.

Constructor & Destructor Documentation

GlJointHistogram()

GlJointHistogram

(

)

Creates a new GlJointHistogram instance with default settings.

Exceptions

std::runtime_error

if initialization of the OpenGL resources fails.

Member Function Documentation

update() [1/3]

bool update	(	SharedImage *	image1,
		SharedImage *	image2,
		Device	device = Device_GPU )

Computes the joint histogram of the given images and returns true on success.

Parameters

image1	First input image
image2	Second input image
device	Device to use for computation

update() [2/3]

bool update	(	const GlImage *	image1,
		const GlImage *	image2,
		const mat4 &	matrix = mat4::Identity() )

Computes the joint histogram of the given images on the GPU and returns true on success.

Parameters

image1	First input image
image2	Second input image
matrix	Relative pose matrix of image2 wrt. image1

update() [3/3]

bool update	(	const MemImage *	image1,
		const MemImage *	image2,
		const mat4 &	matrix = mat4::Identity() )

Computes the joint histogram of the given images on the CPU and returns true on success.

Parameters

image1	First input image
image2	Second input image
matrix	Relative pose matrix of image2 wrt. image1

dataUint()

SharedImage * dataUint

(

)

const

Internal: Returns the histogram data as a 2D unsigned integer image.

Warning

Contains valid data only when using the modern OpenGL 4.3 implementation.

---

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

• ImFusion/GL/GlJointHistogram.h