lagrange::image Namespace Reference

Basic image data structure. More...

Classes
struct	convert_image_pixel
struct	ImageHistogram
	A struct for storing an image histogram. More...
class	ImageStorage
struct	ImageTraits
class	ImageView
class	ImageViewBase
class	RawInputImage
	RawInputImage holds the basic info and the raw pointer (without ownership) to the image pixels. More...

Enumerations
enum class	SampleType { Density , Regular }
	Type of sampling to use. More...
enum class	ImagePrecision : unsigned int {   uint8 , int8 , uint32 , int32 ,   float32 , float64 , float16 , unknown }
enum class	ImageChannel : unsigned int { one = 1 , three = 3 , four = 4 , unknown }

Functions
void	make_box_kernel (size_t size, image::ImageView< float > &kernel)
	Creates a size by size kernel with all values set to 1 / size. More...
void	make_sobelh_kernel (image::ImageView< float > &kernel)
	Creates a 3 by 3 horizontal Sobel filter kernel. More...
void	make_sobelv_kernel (image::ImageView< float > &kernel)
	Creates a 3 by 3 vertical Sobel filter kernel. More...
void	make_gaussian_kernel (image::ImageView< float > &kernel)
	Creates a 3 by 3 approximation of a Gaussian filter kernel. More...
void	make_weighted_avg_xkernel (image::ImageView< float > &kernel)
	Creates a 3 by 1 horizontal kernel with weights (1, 2, 1) / 4. More...
void	make_weighted_avg_ykernel (image::ImageView< float > &kernel)
	Creates a 1 by 3 vertical kernel with weights (1, 2, 1) / 4. More...
void	make_diff_xkernel (image::ImageView< float > &kernel)
	Creates a 3 by 1 horizontal finite difference kernel with weights (-1, 0, 1). More...
void	make_diff_ykernel (image::ImageView< float > &kernel)
	Creates a 1 by 3 vertical finite difference kernel with weights (-1, 0, 1). More...
void	convolve (const image::ImageView< float > &image, const image::ImageView< float > &kernel, image::ImageView< float > &result)
	Convolves the given image with the specified kernel, using periodic boundary conditions. More...
void	sobel_x (const image::ImageView< float > &image, image::ImageView< float > &result)
	Convolves the given image with a horizontal Sobel filter. More...
void	sobel_y (const image::ImageView< float > &image, image::ImageView< float > &result)
	Convolves the given image with a vertical Sobel filter. More...
void	image_dxx (const image::ImageView< float > &image, image::ImageView< float > &result)
	Convolves the given image twice with a horizontal Sobel filter. More...
void	image_dyy (const image::ImageView< float > &image, image::ImageView< float > &result)
	Convolves the given image twice with a vertical Sobel filter. More...
LA_IMAGE_API void	sample_from_density_map (const image::ImageView< float > &density_map, size_t n_samples, lagrange::Vertices2Df &samples)
	Populates a list of approximately n_samples sample points with integer coordinates ranging from (0, 0) to (width - 1, height - 1), where (width, height) is the size of the input density map. More...
LA_IMAGE_API void	sample_borders (const image::ImageView< float > &density_map, size_t n_samples, lagrange::Vertices2Df &samples, SampleType type=SampleType::Regular)
	Populates a list of n_samples samples with samples along the image borders. More...
LA_IMAGE_API void	density_sample_borders (const image::ImageView< float > &density_map, size_t n_samples, lagrange::Vertices2Df &samples)
	Populates a list of n_samples sample according to the density of the border pixeslin density_map. More...
LA_IMAGE_API void	regular_sample_borders (const image::ImageView< float > &density_map, size_t n_samples, lagrange::Vertices2Df &samples)
	Populates a list of approximately n_samples sample points with integer coordinates, including the four corners as well as uniformly spaced points along all four edges of a rectangle matching the size of the input density map. More...
LA_IMAGE_API float	bilinear_interpolation (const image::ImageView< float > &image, float x, float y)
	Samples a single point from the input image using bilinear interpolation. More...
LA_IMAGE_API float	nearest_neighbor_interpolation (const image::ImageView< float > &image, float x, float y)
	Performs nearest neighbor interpolation on an image. More...
LA_IMAGE_API float	percentile (const image::ImageView< float > &image, const float x, const int num_bins=1000)
	Calculate an approximation of the x-th percentile of an image using a histogram. More...
LA_IMAGE_API std::shared_ptr< ImageStorage >	image_storage_from_raw_input_image (const image::RawInputImage &image)
LA_IMAGE_API image::RawInputImage	raw_input_image_from_image_view (image::ImageViewBase &in, bool copy_buffer=false)
float	image_standard_deviation (const image::ImageView< float > &image)
void	depth_to_disparity (const image::ImageView< float > &image, float vfov, image::ImageView< float > &result)
	Converts a depth image to a disparity image. More...
void	normalize_max_image (const image::ImageView< float > &image, image::ImageView< float > &result)
	Normalizes an image in a way that the maximum value is 1.0. More...
ImageHistogram	create_image_histogram (const image::ImageView< float > &image, int num_bins)
	Function to create an image histogram. More...
float	compute_otsu_threshold (const ImageHistogram &histogram, float upper_limit)
	Computes the Otsu threshold value of a given histogram. More...
template<typename VALUE_SRC , typename VALUE_DST >
VALUE_DST	convert_channel_value (VALUE_SRC val)
	LAGRANGE_IMAGE_TRAITS (Eigen::Matrix< unsigned char LAGRANGE_IMAGE_COMMA 3 LAGRANGE_IMAGE_COMMA 1 >, unsigned char, 3, uint8, three) LAGRANGE_IMAGE_TRAITS(Eigen
template<typename Archive >
void	serialize (lagrange::image::RawInputImage &image, Archive &ar)
	Serialization of RawInputImage.
LA_IMAGE_API RawInputImage	make_default_rgba_image (std::size_t i_width, std::size_t i_height, const void *i_pixels)
	Wrap a void * data into a Linear 4-component image. Pixel memory ownership is not transferred.
LA_IMAGE_API RawInputImage	make_default_luminance_image (std::size_t i_width, std::size_t i_height, const void *i_pixels)
	Wrap a void * data into a Linear 1-component image. Pixel memory ownership is not transferred.
template<typename T >
T	wrap_uv (const T u, const RawInputImage::wrap_mode m)
	wrap uv coordinate

Detailed Description

Basic image data structure.

Enumeration Type Documentation

SampleType

enum class SampleType

strong

Type of sampling to use.

Enumerator
Density	sample according to density map
Regular	sample regularly (ignores density)

Function Documentation

make_box_kernel()

void make_box_kernel	(	size_t	size,
		image::ImageView< float > &	kernel
	)

Creates a size by size kernel with all values set to 1 / size.

Parameters

[in]	size	The size of the kernel.
[out]	kernel	The resulting kernel.

make_sobelh_kernel()

void make_sobelh_kernel

(

image::ImageView< float > &

kernel

)

Creates a 3 by 3 horizontal Sobel filter kernel.

Parameters

[out]

kernel

The resulting kernel.

make_sobelv_kernel()

void make_sobelv_kernel

(

image::ImageView< float > &

kernel

)

Creates a 3 by 3 vertical Sobel filter kernel.

Parameters

[out]

kernel

The resulting kernel.

make_gaussian_kernel()

void make_gaussian_kernel

(

image::ImageView< float > &

kernel

)

Creates a 3 by 3 approximation of a Gaussian filter kernel.

Parameters

[out]

kernel

The resulting kernel.

make_weighted_avg_xkernel()

void make_weighted_avg_xkernel

(

image::ImageView< float > &

kernel

)

Creates a 3 by 1 horizontal kernel with weights (1, 2, 1) / 4.

Parameters

[out]

kernel

The resulting kernel.

make_weighted_avg_ykernel()

void make_weighted_avg_ykernel

(

image::ImageView< float > &

kernel

)

Creates a 1 by 3 vertical kernel with weights (1, 2, 1) / 4.

Parameters

[out]

kernel

The resulting kernel.

make_diff_xkernel()

void make_diff_xkernel

(

image::ImageView< float > &

kernel

)

Creates a 3 by 1 horizontal finite difference kernel with weights (-1, 0, 1).

Parameters

[out]

kernel

The resulting kernel.

make_diff_ykernel()

void make_diff_ykernel

(

image::ImageView< float > &

kernel

)

Creates a 1 by 3 vertical finite difference kernel with weights (-1, 0, 1).

Parameters

[out]

kernel

The resulting kernel.

convolve()

void convolve	(	const image::ImageView< float > &	image,
		const image::ImageView< float > &	kernel,
		image::ImageView< float > &	result
	)

Convolves the given image with the specified kernel, using periodic boundary conditions.

Parameters

[in]	image	The input image. Must be larger than the kernel
[in]	kernel	The kernel.
[out]	result	The result of the convolution. Can be the same as image.

sobel_x()

void sobel_x	(	const image::ImageView< float > &	image,
		image::ImageView< float > &	result
	)

Convolves the given image with a horizontal Sobel filter.

Parameters

[in]	image	The input image.
[out]	result	The result of the convolution. Can be the same as image.

sobel_y()

void sobel_y	(	const image::ImageView< float > &	image,
		image::ImageView< float > &	result
	)

Convolves the given image with a vertical Sobel filter.

Parameters

[in]	image	The input image.
[out]	result	The result of the convolution. Can be the same as image.

image_dxx()

void image_dxx	(	const image::ImageView< float > &	image,
		image::ImageView< float > &	result
	)

Convolves the given image twice with a horizontal Sobel filter.

Parameters

[in]	image	The input image.
[out]	result	The result of the convolution. Can be the same as image.

image_dyy()

void image_dyy	(	const image::ImageView< float > &	image,
		image::ImageView< float > &	result
	)

Convolves the given image twice with a vertical Sobel filter.

Parameters

[in]	image	The input image.
[out]	result	The result of the convolution. Can be the same as image.

sample_from_density_map()

void sample_from_density_map	(	const image::ImageView< float > &	density_map,
		size_t	n_samples,
		lagrange::Vertices2Df &	samples
	)

Populates a list of approximately n_samples sample points with integer coordinates ranging from (0, 0) to (width - 1, height - 1), where (width, height) is the size of the input density map.

Parameters

[in]	density_map	The desired density of samples, with larger values indicating higher likelihood of sampling.
[in]	n_samples	The approximate number of samples to generate. The actual number of samples may may be smaller.
[out]	samples	The resulting samples.

sample_borders()

void sample_borders	(	const image::ImageView< float > &	density_map,
		size_t	n_samples,
		lagrange::Vertices2Df &	samples,
		SampleType	type = SampleType::Regular
	)

Populates a list of n_samples samples with samples along the image borders.

There are two sampling modes: SampleType::Density: sample according to density map. SampleType::Regular: sample regularly (ignores density).

Parameters

[in]	density_map	The input density map.
[in]	n_samples	The approximate number of samples to generate. The actual number of samples may be smaller.
[out]	samples	The resulting samples.
[in]	type	The sampling type. Default is SampleType::Regular.

density_sample_borders()

void density_sample_borders	(	const image::ImageView< float > &	density_map,
		size_t	n_samples,
		lagrange::Vertices2Df &	samples
	)

Populates a list of n_samples sample according to the density of the border pixeslin density_map.

Parameters

[in]	density_map	The input density map.
[in]	n_samples	The approximate number of samples to generate. The actual number of samples may be smaller.
[out]	samples	The resulting samples.

regular_sample_borders()

void regular_sample_borders	(	const image::ImageView< float > &	density_map,
		size_t	n_samples,
		lagrange::Vertices2Df &	samples
	)

Populates a list of approximately n_samples sample points with integer coordinates, including the four corners as well as uniformly spaced points along all four edges of a rectangle matching the size of the input density map.

The values of the density map are ignored.

Parameters

[in]	density_map	The input density map.
[in]	n_samples	The approximate number of samples to generate. The actual number of samples may be smaller.
[out]	samples	The resulting samples.

bilinear_interpolation()

float bilinear_interpolation	(	const image::ImageView< float > &	image,
		float	x,
		float	y
	)

Samples a single point from the input image using bilinear interpolation.

Parameters

image	with float values
x	x coordinate
y	y coordinate

Returns

float value at (x, y) bilinearly interpolated from the image

nearest_neighbor_interpolation()

float nearest_neighbor_interpolation	(	const image::ImageView< float > &	image,
		float	x,
		float	y
	)

Performs nearest neighbor interpolation on an image.

This function retrieves the pixel value from the input image at the provided floating-point coordinates using the nearest neighbor interpolation method. This method finds the closest pixel to the provided coordinates and returns its value.

Parameters

image	An ImageView<float> object representing the input image. This image is the source for the interpolation.
x	The x-coordinate where the interpolation should be performed. This should be a floating-point value within the image dimensions.
y	The y-coordinate where the interpolation should be performed. This should be a floating-point value within the image dimensions.

Returns

The interpolated pixel value at the provided coordinates.

percentile()

float percentile	(	const image::ImageView< float > &	image,
		const float	x,
		const int	num_bins = 1000
	)

Calculate an approximation of the x-th percentile of an image using a histogram.

This function constructs a histogram of the pixel intensities in the image, then approximates the x-th percentile based on this histogram. The percentile is calculated by linearly interpolating the values within the bin that contains the target percentile. This function assumes that the pixel intensities within each bin follow a uniform distribution, and the interpolation represents this distribution reasonably well.

Parameters

image	An ImageView<float> object representing the image. Each pixel intensity in the image should be a floating point value.
x	A float between 0 and 1 representing the target percentile. For example, a value of 0.5 represents the 50th percentile (median).
num_bins	(Optional) The number of bins to use for the histogram. More bins will result in a more accurate approximation but will also require more computational resources. Default is 1000.

Returns

An approximation of the x-th percentile of the pixel intensities in the image. The return value is a floating point number representing a pixel intensity.

depth_to_disparity()

void depth_to_disparity	(	const image::ImageView< float > &	image,
		float	vfov,
		image::ImageView< float > &	result
	)

Converts a depth image to a disparity image.

This function converts a depth image, where each pixel's value represents the depth from the camera, into a disparity image. The disparity is calculated using the formula depth = focal_length / disparity. This conversion is particularly useful in stereo vision and 3D reconstruction tasks.

Parameters

image	An ImageView<float> object representing the depth image. Each pixel's value in the image should represent the depth from the camera to the object in the scene.
vfov	The vertical field of view (VFOV) of the camera in degrees. This parameter is used to calculate the focal length, assuming the sensor's height is the same as the image's height.
result	An ImageView<float> object where the result disparity image will be stored. It must have the same size as the input image, otherwise the function will throw an exception.

Warning

This function assumes that the sizes of the input image and the result image are the same. If they are not, it will call la_runtime_assert. Make sure that the input image and the result image have the same size before calling this function.

Note

If the depth at a pixel is zero or negative, the disparity at that pixel will be set to zero. Depending on your application, you may want to handle this situation differently.

normalize_max_image()

void normalize_max_image	(	const image::ImageView< float > &	image,
		image::ImageView< float > &	result
	)

Normalizes an image in a way that the maximum value is 1.0.

This is done by dividing each pixel by the maximum value.

Parameters

image	input image
result	output image

create_image_histogram()

ImageHistogram create_image_histogram	(	const image::ImageView< float > &	image,
		int	num_bins
	)

Function to create an image histogram.

This function generates a histogram of the input image with a specified number of bins. The minimum and maximum values of the image are used to define the range of the histogram. Each bin's boundaries are then calculated based on this range, and the histogram counts are populated by iterating through the image and incrementing the count of the corresponding bin for each pixel.

Parameters

image	The image to create the histogram from.
num_bins	The number of bins in the histogram.

Returns

An ImageHistogram struct containing the histogram counts, bin boundaries, and the overall minimum and maximum pixel values of the image.

compute_otsu_threshold()

float compute_otsu_threshold	(	const ImageHistogram &	histogram,
		float	upper_limit
	)

Computes the Otsu threshold value of a given histogram.

Otsu's method is a way to automatically perform histogram shape-based image thresholding, or, the reduction of a graylevel image to a binary image. It assumes that the image to be thresholded contains two classes of pixels (e.g. foreground and background), it then calculates the optimum threshold separating those two classes so that their combined spread (intraclass variance) is minimal.

This implementation has been adapted to consider only a specific range of the histogram, up to a given upper limit. This modification is useful for scenarios where we want to exclude certain values (such as near-zero values representing the sky in a disparity image) from the thresholding process. The upper_limit parameter determines the highest value to be considered in the threshold calculation.

The computed threshold is a bin index; to convert this to an actual pixel value, the function multiplies the threshold by the bin width and adds the minimum pixel value of the histogram.

Parameters

histogram	The histogram of the image. It must contain equally-spaced bins, and the bin counts must be non-negative.
upper_limit	The maximum pixel value to consider in the threshold calculation. This should be a value within the range of the histogram.

Returns

The Otsu threshold, computed based on the given histogram and upper limit.

For a detailed explanation of Otsu's method, see: Otsu, N. (1979). A Threshold Selection Method from Gray-Level Histograms. IEEE Transactions on Systems, Man, and Cybernetics, 9(1), 62–66. doi:10.1109/TSMC.1979.4310076