img2num Namespace Reference

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

Functions
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)
void	gaussian_blur_fft (uint8_t *image, size_t width, size_t height, double sigma)
	Apply a Gaussian blur to an image using FFT. More...
void	invert_image (uint8_t *ptr, int width, int height)
	Invert the pixel values of an image. More...
void	threshold_image (uint8_t *ptr, const int width, const int height, const int num_thresholds)
	Apply a thresholding operation to an image. More...
void	black_threshold_image (uint8_t *ptr, const int width, const int height, const int num_thresholds)
	Apply black-thresholding to an image. More...
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. More...
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. More...
char *	labels_to_svg (uint8_t *data, int32_t *labels, const int width, const int height, const int min_area, const bool draw_contour_borders)
	Convert labeled regions of an image into an SVG string. More...

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.

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 155 of file bilateral_filter.cpp.

                                                               {
    // bad data -> return
    if (sigma_spatial <= 0.0 || sigma_range <= 0.0 || width <= 0 || height <= 0) return;
    if (color_space != COLOR_SPACE_OPTION_CIELAB && color_space != COLOR_SPACE_OPTION_RGB) return;
 
    const int raw_radius{static_cast<int>(std::ceil(SIGMA_RADIUS_FACTOR * sigma_spatial))};
    const int radius{std::min(raw_radius, MAX_KERNEL_RADIUS)};
    const int kernel_diameter{2 * radius + 1};
 
    std::vector<uint8_t> result(width * height * 4);
 
    std::vector<double> spatial_weights(kernel_diameter * kernel_diameter);
 
    // Precompute Spatial Weights (Gaussian Kernel)
    for (int ky{-radius}; ky <= radius; ++ky) {
        for (int kx{-radius}; kx <= radius; ++kx) {
            const double dist{static_cast<double>(std::sqrt(kx * kx + ky * ky))};
            spatial_weights[(ky + radius) * kernel_diameter + (kx + radius)] =
                gaussian(dist, sigma_spatial);
        }
    }
 
    // ========= RGB-only section start =========
    // Precompute Range Weights
    std::vector<double> range_lut;
    if (color_space == COLOR_SPACE_OPTION_RGB) {
        range_lut.resize(MAX_RGB_DIST_SQ + 1);
        for (int i{0}; i <= MAX_RGB_DIST_SQ; ++i) {
            range_lut[i] = gaussian(static_cast<double>(std::sqrt(i)), sigma_range);
        }
    }
    // ========= RGB-only section end =========
 
    // ========= CIELAB section start =========
    // Compute full image RGB - CIELAB conversion
    std::vector<double> cie_image;
    if (color_space == COLOR_SPACE_OPTION_CIELAB) {
        cie_image.resize(width * height * 4);
 
        for (int y{0}; y < height; y++) {
            for (int x{0}; x < width; x++) {
                int center_idx{(y * static_cast<int>(width) + x) * 4};
                uint8_t r0{image[center_idx]};
                uint8_t g0{image[center_idx + 1]};
                uint8_t b0{image[center_idx + 2]};
                uint8_t a0{image[center_idx + 3]};
                double L0, A0, B0;
                rgb_to_lab<uint8_t, double>(r0, g0, b0, L0, A0, B0);
 
                cie_image[center_idx] = L0;
                cie_image[center_idx + 1] = A0;
                cie_image[center_idx + 2] = B0;
                cie_image[center_idx + 3] = 0.0;  // unused but keep for indexing purposes
            }
        }
    }
    // ========= CIELAB section end =========
 
    _process(image, cie_image, result, spatial_weights, range_lut, radius, sigma_range, 0,
             static_cast<int>(height), height, width, color_space);
 
    std::memcpy(image, result.data(), result.size());
}

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

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
}

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

                                       {
    ImageLib::Image<ImageLib::RGBAPixel<float>> pixels;
    pixels.loadFromBuffer(data, width, height, ImageLib::RGBA_CONVERTER<float>);
    const int32_t num_pixels{pixels.getSize()};
 
    // width = k, height = 1
    // k centroids, initialized to rgba(0,0,0,255)
    // Init of each pixel is from default in Image constructor
    ImageLib::Image<ImageLib::RGBAPixel<float>> centroids{k, 1};
    ImageLib::Image<ImageLib::LABAPixel<float>> centroids_lab{k, 1};
    std::vector<int32_t> labels(num_pixels, 0);
 
    ImageLib::Image<ImageLib::LABAPixel<float>> lab(pixels.getWidth(), pixels.getHeight());
    if (color_space == COLOR_SPACE_OPTION_CIELAB) {
        for (int i{0}; i < pixels.getSize(); ++i) {
            rgb_to_lab<float, float>(pixels[i], lab[i]);
        }
    }
 
    // Step 2: Initialize centroids randomly
 
    switch (color_space) {
        case COLOR_SPACE_OPTION_RGB: {
            kMeansPlusPlusInit<ImageLib::RGBAPixel<float>>(pixels, centroids, k);
            break;
        }
        case COLOR_SPACE_OPTION_CIELAB: {
            kMeansPlusPlusInit<ImageLib::LABAPixel<float>>(lab, centroids_lab, k);
            break;
        }
    }
 
    // Step 3: Run k-means iterations
 
    // Assignment step
    for (int32_t iter{0}; iter < max_iter; ++iter) {
        bool changed{false};
 
        // Iterate over pixels
        for (int32_t i{0}; i < num_pixels; ++i) {
            float min_color_dist{std::numeric_limits<float>::max()};
            int32_t best_cluster{0};
 
            // Iterate over centroids to find centroid with most similar color to
            // pixels[i]
            float dist;
            for (int32_t j{0}; j < k; ++j) {
                switch (color_space) {
                    case COLOR_SPACE_OPTION_RGB: {
                        dist = ImageLib::RGBAPixel<float>::colorDistance(pixels[i], centroids[j]);
                        break;
                    }
                    case COLOR_SPACE_OPTION_CIELAB: {
                        dist = ImageLib::LABAPixel<float>::colorDistance(lab[i], centroids_lab[j]);
                        break;
                    }
                }
                if (dist < min_color_dist) {
                    min_color_dist = dist;
                    best_cluster = j;
                }
            }
 
            if (labels[i] != best_cluster) {
                changed = true;
                labels[i] = best_cluster;
            }
        }
 
        // Stop if no changes
        if (!changed) {
            break;
        }
 
        // Update step
        ImageLib::Image<ImageLib::RGBAPixel<float>> new_centroids(k, 1, 0);
        ImageLib::Image<ImageLib::LABAPixel<float>> new_centroids_lab(k, 1, 0);
        std::vector<int32_t> counts(k, 0);
 
        for (int32_t i = 0; i < num_pixels; ++i) {
            int32_t cluster = labels[i];
            switch (color_space) {
                case COLOR_SPACE_OPTION_RGB: {
                    new_centroids[cluster].red += pixels[i].red;
                    new_centroids[cluster].green += pixels[i].green;
                    new_centroids[cluster].blue += pixels[i].blue;
                    break;
                }
                case COLOR_SPACE_OPTION_CIELAB: {
                    new_centroids_lab[cluster].l += lab[i].l;
                    new_centroids_lab[cluster].a += lab[i].a;
                    new_centroids_lab[cluster].b += lab[i].b;
                    break;
                }
            }
            counts[cluster]++;
        }
 
        for (int32_t j = 0; j < k; ++j) {
            /*
               A centroid may become a dead centroid if it never gets pixels assigned
               to it. May be good idea to reinitialize these dead centroids.
               */
            if (counts[j] > 0) {
                switch (color_space) {
                    case COLOR_SPACE_OPTION_RGB: {
                        centroids[j].red = new_centroids[j].red / counts[j];
                        centroids[j].green = new_centroids[j].green / counts[j];
                        centroids[j].blue = new_centroids[j].blue / counts[j];
                        break;
                    }
                    case COLOR_SPACE_OPTION_CIELAB: {
                        centroids_lab[j].l = new_centroids_lab[j].l / counts[j];
                        centroids_lab[j].a = new_centroids_lab[j].a / counts[j];
                        centroids_lab[j].b = new_centroids_lab[j].b / counts[j];
                        break;
                    }
                }
            }
        }
    }
 
    if (color_space == COLOR_SPACE_OPTION_CIELAB) {
        for (int32_t i{0}; i < k; ++i) {
            lab_to_rgb<float, float>(centroids_lab[i], centroids[i]);
        }
    }
 
    // Write the final centroid values to each pixel in the cluster
    for (int32_t i = 0; i < num_pixels; ++i) {
        const int32_t cluster = labels[i];
        out_data[i * 4 + 0] =
            static_cast<uint8_t>(std::clamp(centroids[cluster].red, 0.0f, 255.0f));
        out_data[i * 4 + 1] =
            static_cast<uint8_t>(std::clamp(centroids[cluster].green, 0.0f, 255.0f));
        out_data[i * 4 + 2] =
            static_cast<uint8_t>(std::clamp(centroids[cluster].blue, 0.0f, 255.0f));
        out_data[i * 4 + 3] = 255;
    }
 
    // Write labels to out_labels
    std::memcpy(out_labels, labels.data(), labels.size() * sizeof(int32_t));
}

labels_to_svg()

char * img2num::labels_to_svg	(	uint8_t *	data,
		int32_t *	labels,
		const int	width,
		const int	height,
		const int	min_area,
		const bool	draw_contour_borders
	)

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.
draw_contour_borders	If true, contours of labeled regions will be drawn.

Returns

Pointer to a dynamically allocated C-string containing the SVG data.

Note

Caller is responsible for freeing the returned string.

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. Copy recolored image back
    const auto &modified = results.getData();
    std::memcpy(data, modified.data(), modified.size() * sizeof(ImageLib::RGBAPixel<uint8_t>));
 
    // 8. Return SVG if requested
    if (!draw_contour_borders) {
        std::string svg{contoursResultToSVG(all_contours, width, height)};
 
        // Dynamic C-style allocation (since returned over C ABI)
        char *res_svg{static_cast<char *>(std::malloc(svg.size() + 1))};
        if (!res_svg) {
            return nullptr;  // Allocation failed
        }
        std::memcpy(res_svg, svg.c_str(), svg.size() + 1);
 
        return res_svg;
    }
 
    return nullptr;  // no SVG
}

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