img2num Namespace Reference

Classes
struct	ImageToSvgConfig
	Configuration options for image_to_svg. More...

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, const int min_thickness)
	Convert labeled regions of an image into an SVG string.
std::string	image_to_svg (const uint8_t *data, const int width, const int height, const ImageToSvgConfig &config)
	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.

{ 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 230 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);
    }
}

Referenced by image_to_svg().

Here is the caller graph for this function:

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 139 of file image_utils.cpp.

  {
    if (num_thresholds <= 0) {
        return;
    }
    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 48 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;
}

image_to_svg()

std::string img2num::image_to_svg	(	const uint8_t *	data,
		const int	width,
		const int	height,
		const ImageToSvgConfig &	config
	)

Convert labeled regions of an image into an SVG string.

Parameters

data	Pointer to image data buffer.
width	Width of the image in pixels.
height	Height of the image in pixels.
config	img2num_ImageToSvgConfig Configuration Struct. ‍See img2num::ImageToSvgConfig.

Returns

std::string An SVG string containing data roughly approximate to the input image.

Note

Dox File: doxygen/img2num.h.dox

Definition at line 7 of file image_to_svg.cpp.

  {
    // self deallocate
    std::vector<uint8_t> img_data(static_cast<size_t>(width) * static_cast<size_t>(height) * 4);
    std::vector<uint8_t> out_data(static_cast<size_t>(width) * static_cast<size_t>(height) * 4);
    std::vector<int32_t> out_labels(static_cast<size_t>(width) * static_cast<size_t>(height));
 
    std::memcpy(
        img_data.data(), data, static_cast<size_t>(width) * static_cast<size_t>(height) * 4
    );
    bilateral_filter(
        img_data.data(), width, height, config.bilateral_filter.sigma_spatial,
        config.bilateral_filter.sigma_range, config.color_space
    );
    kmeans(
        img_data.data(), out_data.data(), out_labels.data(), width, height, config.kmeans.k,
        config.kmeans.max_iter, config.color_space
    );
    std::string svg {labels_to_svg(
        data, out_labels.data(), width, height, config.min_cluster_area, config.min_thickness
    )};
 
    return svg;
}

References bilateral_filter(), img2num::ImageToSvgConfig::color_space, img2num::ImageToSvgConfig::KMeansConfig::k, kmeans(), labels_to_svg(), img2num::ImageToSvgConfig::KMeansConfig::max_iter, img2num::ImageToSvgConfig::min_cluster_area, img2num::ImageToSvgConfig::min_thickness, img2num::ImageToSvgConfig::BilateralFilterConfig::sigma_range, and img2num::ImageToSvgConfig::BilateralFilterConfig::sigma_spatial.

Here is the call graph for this function:

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 105 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 241 of file kmeans.cpp.

  {
    GPU::getClassInstance().init_gpu();
 
    if (GPU::getClassInstance().is_initialized()) {
        kmeans_gpu(data, out_data, out_labels, width, height, k, max_iter, color_space);
    } else {
        kmeans_cpu(data, out_data, out_labels, width, height, k, max_iter, color_space);
    }
}

Referenced by image_to_svg().

Here is the caller graph for this function:

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,
		const int	min_thickness = 0
	)

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 203 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, min_thickness);
 
    // 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);
}

Referenced by image_to_svg().

Here is the caller graph for this function:

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 119 of file image_utils.cpp.

                                                                                                {
    if (num_thresholds <= 0) {
        return;
    }
    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.

{Error::OK};

last_error_message

thread_local std::string img2num::last_error_message {}

Definition at line 5 of file Error.cpp.

{};