Enumerations
enum class	Error { OK = 0 , BAD_ALLOC = 1 , INVALID_ARGUMENT = 2 , RUNTIME = 3 , UNKNOWN = 4 }

Functions
void	gaussian_blur_fft (uint8_t *image, size_t width, size_t height, double sigma)
	Apply a Gaussian blur to an image using FFT.

void	invert_image (uint8_t *ptr, int width, int height)
	Invert the pixel values of an image.

void	threshold_image (uint8_t *ptr, const int width, const int height, const int num_thresholds)
	Apply a thresholding operation to an image.

void	black_threshold_image (uint8_t *ptr, const int width, const int height, const int num_thresholds)
	Apply black-thresholding to an image.

void	kmeans (const uint8_t data, uint8_t out_data, int32_t *out_labels, const int32_t width, const int32_t height, const int32_t k, const int32_t max_iter, const uint8_t color_space)
	Perform k-means clustering on image data.

void	bilateral_filter (uint8_t *image, size_t width, size_t height, double sigma_spatial, double sigma_range, uint8_t color_space)
	Apply bilateral filtering to an image.

std::string	labels_to_svg (const uint8_t data, const int32_t labels, const int width, const int height, const int min_area)
	Convert labeled regions of an image into an SVG string.

Error	get_last_error ()

const std::string	get_last_error_message ()

void	clear_last_error ()

void	set_error (Error code, const std::string message)

template<typename Func , typename... Args>
void	clear_last_error_and_catch (Func &&exception_prone_func, Args &&... args)

Variables
thread_local Error	last_error {Error::OK}

thread_local std::string	last_error_message {}

Detailed Description

Note: All image buffers are assumed to be stored in row-major order, unless otherwise noted.

Enumeration Type Documentation

◆ Error

enum class img2num::Error

strong

Definition at line 8 of file Error.h.

8{ OK = 0, BAD_ALLOC = 1, INVALID_ARGUMENT = 2, RUNTIME = 3, UNKNOWN = 4 };

Function Documentation

◆ bilateral_filter()

void img2num::bilateral_filter	(	uint8_t *	image,
		size_t	width,
		size_t	height,
		double	sigma_spatial,
		double	sigma_range,
		uint8_t	color_space
	)

Apply bilateral filtering to an image.

Parameters

image	Pointer to RGBA pixel buffer.
width	Width of the image in pixels.
height	Height of the image in pixels.
sigma_spatial	Standard deviation for spatial Gaussian (proximity weight).
sigma_range	Standard deviation for range Gaussian (intensity similarity weight).
color_space	Color space flag (0 = CIE LAB, 1 = RGB).

Note: The filter modifies the image buffer in-place.; Dox File: doxygen/img2num.h.dox

Definition at line 222 of file bilateral_filter.cpp.

                                                               {
    GPU::getClassInstance().init_gpu();
 
    if (GPU::getClassInstance().is_initialized()) {
        bilateral_filter_gpu(image, width, height, sigma_spatial, sigma_range, color_space);
    } else {
        bilateral_filter_cpu(image, width, height, sigma_spatial, sigma_range, color_space);
    }
}

◆ black_threshold_image()

void img2num::black_threshold_image	(	uint8_t *	ptr,
		const int	width,
		const int	height,
		const int	num_thresholds
	)

Apply black-thresholding to an image.

Parameters

ptr	Pointer to the image buffer.
width	Width of the image in pixels.
height	Height of the image in pixels.
num_thresholds	Number of thresholds to apply.

Note: Similar to threshold_image but prioritizes darker pixels.; Dox File: doxygen/img2num.h.dox

Definition at line 130 of file image_utils.cpp.

                                                     {
    ImageLib::Image<ImageLib::RGBAPixel<uint8_t>> img;
    img.loadFromBuffer(ptr, width, height, ImageLib::RGBA_CONVERTER<uint8_t>);
 
    const auto imgWidth{img.getWidth()}, imgHeight{img.getHeight()};
    for (ImageLib::RGBAPixel<uint8_t> &p : img) {
        const bool R{p.red < num_thresholds};
        const bool G{p.green < num_thresholds};
        const bool B{p.blue < num_thresholds};
        if (R && B && G) {
            p.setGray(0);
        }
    }
 
    const auto &modified = img.getData();
    std::memcpy(ptr, modified.data(), modified.size() * sizeof(ImageLib::RGBAPixel<uint8_t>));
}

◆ clear_last_error()

void img2num::clear_last_error ( )

Definition at line 7 of file Error.cpp.

                        {
    last_error = Error::OK;
    last_error_message.clear();
}

◆ clear_last_error_and_catch()

template<typename Func , typename... Args>

void img2num::clear_last_error_and_catch	(	Func &&	exception_prone_func,
		Args &&...	args
	)

Definition at line 25 of file Error.h.

                                                                             {
    clear_last_error();  // Clear any previous error state
    try {
        exception_prone_func(std::forward<Args>(args)...);  // Call the passed function
    } catch (const std::bad_alloc& e) {
        set_error(Error::BAD_ALLOC, e.what());
    } catch (const std::invalid_argument& e) {
        set_error(Error::INVALID_ARGUMENT, e.what());
    } catch (const std::runtime_error& e) {
        set_error(Error::RUNTIME, e.what());
    } catch (const std::exception& e) {
        set_error(Error::UNKNOWN, e.what());
    } catch (...) {
        set_error(Error::UNKNOWN, "Unknown exception occurred");
    }
}

◆ gaussian_blur_fft()

void img2num::gaussian_blur_fft	(	uint8_t *	image,
		size_t	width,
		size_t	height,
		double	sigma
	)

Apply a Gaussian blur to an image using FFT.

Parameters

image	Pointer to the image buffer (RGBA).
width	Width of the image in pixels.
height	Height of the image in pixels.
sigma	Standard deviation for Gaussian kernel.

Note: The operation modifies the image buffer in-place.; Dox File: doxygen/img2num.h.dox

Definition at line 43 of file image_utils.cpp.

                                                                                         {
    if (!image || width == 0 || height == 0 || sigma_pixels <= 0) return;
 
    const size_t Npix = width * height;
 
    // Compute padded dimensions (next power of two)
    const size_t W = fft::next_power_of_two(width);
    const size_t H = fft::next_power_of_two(height);
    const size_t Npix_padded = W * H;
 
    // Frequency coordinates helper (DC at corner)
    auto freq_coord = [](int k, int dim) -> double {
        return (k <= dim / 2) ? double(k) / dim : double(k - dim) / dim;
    };
 
    // Precompute Gaussian factor in frequency domain
    const double two_pi2_sigma2 = 2.0 * M_PI * M_PI * sigma_pixels * sigma_pixels;
 
    for (int channel = 0; channel < 3; channel++) {
        // Allocate padded buffer
        std::vector<fft::cd> data(Npix_padded, {0.0, 0.0});
 
        // Copy original image channel into padded buffer
        for (size_t y = 0; y < height; y++)
            for (size_t x = 0; x < width; x++)
                data[y * W + x] = fft::cd(image[(y * width + x) * 4 + channel], 0.0);
 
        // Forward 2D FFT
        fft::iterative_fft_2d(data, W, H, false);
 
        // Apply Gaussian filter in frequency domain
        for (size_t y = 0; y < H; y++) {
            double fy2 = freq_coord(y, H) * freq_coord(y, H);
            for (size_t x = 0; x < W; x++) {
                double fx2 = freq_coord(x, W) * freq_coord(x, W);
                double gain = std::exp(-two_pi2_sigma2 * (fx2 + fy2));
                data[y * W + x] *= gain;
            }
        }
 
        // Inverse 2D FFT
        fft::iterative_fft_2d(data, W, H, true);
 
        // Copy back only the original width/height and clamp
        for (size_t y = 0; y < height; y++)
            for (size_t x = 0; x < width; x++) {
                double v = data[y * W + x].real();
                v = std::clamp(v, 0.0, 255.0);
                image[(y * width + x) * 4 + channel] = static_cast<uint8_t>(std::lrint(v));
            }
    }
 
    // Alpha channel remains unchanged
}

◆ get_last_error()

Error img2num::get_last_error ( )

inline

Definition at line 13 of file Error.h.

                              {
    return last_error;
}

◆ get_last_error_message()

const std::string img2num::get_last_error_message ( )

inline

Definition at line 16 of file Error.h.

                                                {
    return last_error_message;
}

◆ invert_image()

void img2num::invert_image	(	uint8_t *	ptr,
		int	width,
		int	height
	)

Invert the pixel values of an image.

Parameters

ptr	Pointer to the image buffer.
width	Width of the image in pixels.
height	Height of the image in pixels.

Note: Each pixel value is replaced by 255 - original_value.; Dox File: doxygen/img2num.h.dox

Definition at line 99 of file image_utils.cpp.

                                                       {
    ImageLib::Image<ImageLib::RGBAPixel<uint8_t>> img;
    img.loadFromBuffer(ptr, width, height, ImageLib::RGBA_CONVERTER<uint8_t>);
 
    for (ImageLib::RGBAPixel<uint8_t> &p : img) {
        p.red = 255 - p.red;
        p.blue = 255 - p.blue;
        p.green = 255 - p.green;
    }
 
    const auto &modified = img.getData();
    std::memcpy(ptr, modified.data(), modified.size() * sizeof(ImageLib::RGBAPixel<uint8_t>));
}

◆ kmeans()

void img2num::kmeans	(	const uint8_t *	data,
		uint8_t *	out_data,
		int32_t *	out_labels,
		const int32_t	width,
		const int32_t	height,
		const int32_t	k,
		const int32_t	max_iter,
		const uint8_t	color_space
	)

Perform k-means clustering on image data.

Parameters

data	Pointer to input image data buffer.
out_data	Pointer to output buffer where clustered pixel values are stored.
out_labels	Pointer to output buffer for cluster labels per pixel.
width	Width of the image in pixels.
height	Height of the image in pixels.
k	Number of clusters to compute.
max_iter	Maximum number of iterations for the algorithm.
color_space	Color space flag (0 = CIE LAB, 1 = RGB).

Note: The function does not modify the input buffer.; Dox File: doxygen/img2num.h.dox

Definition at line 240 of file kmeans.cpp.

                                       {
    GPU::getClassInstance().init_gpu();
 
    if (GPU::getClassInstance().is_initialized()) {
        std::cout << "kmeans gpu" << std::endl;
        kmeans_gpu(data, out_data, out_labels, width, height, k, max_iter, color_space);
    } else {
        std::cout << "kmeans cpu" << std::endl;
        kmeans_cpu(data, out_data, out_labels, width, height, k, max_iter, color_space);
    }
}

◆ labels_to_svg()

std::string img2num::labels_to_svg	(	const uint8_t *	data,
		const int32_t *	labels,
		const int	width,
		const int	height,
		const int	min_area
	)

Convert labeled regions of an image into an SVG string.

Parameters

data	Pointer to image data buffer.
labels	Pointer to label buffer, indicating region for each pixel.
width	Width of the image in pixels.
height	Height of the image in pixels.
min_area	Minimum area (in pixels) for a region to be included in the SVG.

Returns: std::string A valid SVG string containing the data.

Note: Dox File: doxygen/img2num.h.dox

Definition at line 189 of file labels_to_svg.cpp.

                                                                {
    const int32_t num_pixels{width * height};
    std::vector<int32_t> labels_vector{labels, labels + num_pixels};
    std::vector<int32_t> region_labels;
 
    // 1. enumerate regions and convert to Nodes
    std::vector<Node_ptr> nodes;
    region_labeling(data, labels_vector, region_labels, width, height, nodes);
 
    // 2. initialize Graph from all Nodes
    std::unique_ptr<std::vector<Node_ptr>> node_ptr =
        std::make_unique<std::vector<Node_ptr>>(std::move(nodes));
    Graph G(node_ptr, width, height);
 
    // 3. Discover node adjacencies - add edges to Graph
    G.discover_edges(region_labels, width, height);
 
    // 4. Merge small area nodes until all nodes are minArea or larger
    G.merge_small_area_nodes(min_area);
 
    // 5. recolor image on new regions
    ImageLib::Image<ImageLib::RGBAPixel<uint8_t>> results{width, height};
    for (auto &n : G.get_nodes()) {
        if (n->area() == 0) continue;
 
        auto [r, g, b] = n->color();
        for (auto &[_, p] : n->get_pixels()) {
            results(p.x, p.y) = {r, g, b};
        }
    }
 
    // 6. Contours
    // graph will manage computing contours
    G.compute_contours();
 
    // accumulate all contours for svg export
    ColoredContours all_contours;
    for (auto &n : G.get_nodes()) {
        if (n->area() == 0) continue;
        ColoredContours node_contours = n->get_contours();
        for (auto &c : node_contours.contours) {
            all_contours.contours.push_back(c);
        }
        for (auto &c : node_contours.hierarchy) {
            all_contours.hierarchy.push_back(c);
        }
        for (bool b : node_contours.is_hole) {
            all_contours.is_hole.push_back(b);
        }
        for (auto &c : node_contours.colors) {
            all_contours.colors.push_back(c);
        }
        for (auto &c : node_contours.curves) {
            all_contours.curves.push_back(c);
        }
    }
 
    // 7. Return SVG
    return contoursResultToSVG(all_contours, width, height);
}

◆ set_error()

void img2num::set_error	(	Error	code,
		const std::string	message
	)

Definition at line 12 of file Error.cpp.

                                                    {
    last_error = code;
    last_error_message = message;
}

◆ threshold_image()

void img2num::threshold_image	(	uint8_t *	ptr,
		const int	width,
		const int	height,
		const int	num_thresholds
	)

Apply a thresholding operation to an image.

Parameters

ptr	Pointer to the image buffer.
width	Width of the image in pixels.
height	Height of the image in pixels.
num_thresholds	Number of thresholds to apply.

Note: Thresholds split pixel intensity ranges into discrete levels.; Dox File: doxygen/img2num.h.dox

Definition at line 113 of file image_utils.cpp.

                                                                                                {
    const uint8_t REGION_SIZE(255 / num_thresholds);  // Size of buckets per colour
 
    ImageLib::Image<ImageLib::RGBAPixel<uint8_t>> img;
    img.loadFromBuffer(ptr, width, height, ImageLib::RGBA_CONVERTER<uint8_t>);
 
    const auto imgWidth{img.getWidth()}, imgHeight{img.getHeight()};
    for (ImageLib::RGBAPixel<uint8_t> &p : img) {
        p.red = quantize(p.red, REGION_SIZE);
        p.green = quantize(p.green, REGION_SIZE);
        p.blue = quantize(p.blue, REGION_SIZE);
    }
 
    const auto &modified = img.getData();
    std::memcpy(ptr, modified.data(), modified.size() * sizeof(ImageLib::RGBAPixel<uint8_t>));
}

Variable Documentation

◆ last_error

thread_local Error img2num::last_error {Error::OK}

Definition at line 4 of file Error.cpp.

4{Error::OK};

◆ last_error_message

thread_local std::string img2num::last_error_message {}

Definition at line 5 of file Error.cpp.

5{};

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ Error

Function Documentation

◆ bilateral_filter()

◆ black_threshold_image()

◆ clear_last_error()

◆ clear_last_error_and_catch()

◆ gaussian_blur_fft()

◆ get_last_error()

◆ get_last_error_message()

◆ invert_image()

◆ kmeans()

◆ labels_to_svg()

◆ set_error()

◆ threshold_image()

Variable Documentation

◆ last_error

◆ last_error_message