fix(core)!: prevent holes during SVG generation

bindings/c/include/cimg2num.h

@@ -42,6 +42,8 @@ typedef struct img2num_ImageToSvgConfig {
 
     /// Minimum area (in pixels) for a region to be included in the SVG.
     int min_cluster_area;
+    /// Minimum thickness (in pixels) for a region to be included in the SVG.
+    int min_thickness;
 
     /// Color space flag.
     /// - 0 = CIE LAB (more perceptually accurate)
@@ -82,7 +84,7 @@ void img2num_bilateral_filter(
 /// @copydoc ::IMG2NUM_H_LABELS_TO_SVG_DOC
 char* 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_area, const int min_thickness
 );
 
 /// @copydoc ::IMG2NUM_H_IMAGE_TO_SVG_DOC

bindings/c/src/cimg2num.cpp

@@ -21,6 +21,7 @@ static img2num::ImageToSvgConfig to_cpp(const img2num_ImageToSvgConfig& c) {
         },
 
         .min_cluster_area = c.min_cluster_area,
+        .min_thickness = c.min_thickness,
         .color_space = c.color_space
     };
     // clang-format on
@@ -38,6 +39,7 @@ static img2num_ImageToSvgConfig to_c(const img2num::ImageToSvgConfig& cpp) {
             .max_iter = cpp.kmeans.max_iter
         },
         .min_cluster_area = cpp.min_cluster_area,
+        .min_thickness = cpp.min_thickness,
         .color_space = cpp.color_space
     };
     // clang-format on
@@ -92,19 +94,20 @@ void img2num_bilateral_filter(
 
 char* 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_area, const int min_thickness
 ) {
     char* result {nullptr};
     img2num::clear_last_error_and_catch(
-        [&](const uint8_t* d, const int32_t* l, const int w, const int h, const int min_a) {
-            std::string svg {img2num::labels_to_svg(d, l, w, h, min_a)};
+        [&](const uint8_t* d, const int32_t* l, const int w, const int h, const int min_a,
+            const int min_t) {
+            std::string svg {img2num::labels_to_svg(d, l, w, h, min_a, min_t)};
             result = static_cast<char*>(std::malloc(svg.size() + 1));
             if (!result) {
                 return; // Allocation failed
             }
             std::memcpy(result, svg.c_str(), svg.size() + 1);
         },
-        data, labels, width, height, min_area
+        data, labels, width, height, min_area, min_thickness
     );
     return result;
 }

bindings/js/src/wasm_wrapper.c

@@ -35,15 +35,16 @@ EMSCRIPTEN_KEEPALIVE void bilateral_filter(
 }
 
 EMSCRIPTEN_KEEPALIVE char* labels_to_svg(
-    uint8_t* data, int32_t* labels, const int width, const int height, const int min_area
+    uint8_t* data, int32_t* labels, const int width, const int height, const int min_area,
+    const int min_thickness
 ) {
-    return img2num_labels_to_svg(data, labels, width, height, min_area);
+    return img2num_labels_to_svg(data, labels, width, height, min_area, min_thickness);
 }
 
 EMSCRIPTEN_KEEPALIVE char* image_to_svg(
     const uint8_t* data, const int width, const int height, double sigma_spatial,
     double sigma_range, const int32_t k, const int32_t max_iter, const int min_area,
-    const uint8_t color_space
+    const int min_thickness, const uint8_t color_space
 ) {
     img2num_ImageToSvgConfig config = img2num_ImageToSvgConfig_default();
 
@@ -52,6 +53,7 @@ EMSCRIPTEN_KEEPALIVE char* image_to_svg(
     config.kmeans.k = k;
     config.kmeans.max_iter = max_iter;
     config.min_cluster_area = min_area;
+    config.min_thickness = min_thickness;
     config.color_space = color_space;
 
     return img2num_image_to_svg(data, width, height, &config);

bindings/py/src/img2num_pybind.cpp

@@ -121,17 +121,20 @@ PYBIND11_MODULE(_img2num, m) {
         "labels_to_svg",
         [](pybind11::array_t<uint8_t, pybind11::array::c_style> data,
            pybind11::array_t<int32_t, pybind11::array::c_style> labels, int width, int height,
-           int min_area) {
+           int min_area, int min_thickness) {
             const uint8_t* data_ptr {static_cast<const uint8_t*>(data.request().ptr)};
             const int32_t* labels_ptr {static_cast<const int32_t*>(labels.request().ptr)};
 
-            std::string svg {img2num::labels_to_svg(data_ptr, labels_ptr, width, height, min_area)};
+            std::string svg {img2num::labels_to_svg(
+                data_ptr, labels_ptr, width, height, min_area, min_thickness
+            )};
             pybind11::str svg_py_str(std::move(svg));
 
             return svg_py_str;
         },
         pybind11::arg("data"), pybind11::arg("labels"), pybind11::arg("width"),
-        pybind11::arg("height"), pybind11::arg("min_area"), "Convert labels to SVG string"
+        pybind11::arg("height"), pybind11::arg("min_area"), pybind11::arg("min_thickness"),
+        "Convert labels to SVG string"
     );
 
     // ---------------------- Config Structs ----------------------
@@ -180,6 +183,8 @@ PYBIND11_MODULE(_img2num, m) {
                 // 4. Process remaining top-level kwargs (like color_space or min_cluster_area)
                 if (kwargs.contains("min_cluster_area"))
                     c->min_cluster_area = kwargs["min_cluster_area"].cast<int>();
+                if (kwargs.contains("min_thickness"))
+                    c->min_thickness = kwargs["min_thickness"].cast<int>();
                 if (kwargs.contains("color_space"))
                     c->color_space = kwargs["color_space"].cast<uint8_t>();
 
@@ -190,6 +195,7 @@ PYBIND11_MODULE(_img2num, m) {
         )
         .def_readwrite("bilateral_filter", &img2num::ImageToSvgConfig::bilateral_filter)
         .def_readwrite("min_cluster_area", &img2num::ImageToSvgConfig::min_cluster_area)
+        .def_readwrite("min_thickness", &img2num::ImageToSvgConfig::min_thickness)
         .def_readwrite("color_space", &img2num::ImageToSvgConfig::color_space)
         .def_readwrite("kmeans", &img2num::ImageToSvgConfig::kmeans)
         .def("__repr__", [](const img2num::ImageToSvgConfig& c) {
@@ -199,6 +205,7 @@ PYBIND11_MODULE(_img2num, m) {
                << "bilateral_filter: "
                << pybind11::repr(pybind11::cast(c.bilateral_filter)).cast<std::string>() << ", "
                << "min_cluster_area: " << c.min_cluster_area << ", "
+               << "min_thickness: " << c.min_thickness << ", "
                << "color_space: " << (int)c.color_space << ", "
                << "kmeans: " << pybind11::repr(pybind11::cast(c.kmeans)).cast<std::string>()
                << "}>";

core/include/img2num.h

@@ -42,6 +42,11 @@ struct ImageToSvgConfig {
     /// Minimum area (in pixels) for a region to be included in the SVG.
     int min_cluster_area = 100;
 
+    /// Minimum thickness (in pixels) for a region to be included in the SVG.
+    /// Regions with an inscribed disk diameter less than this value are merged.
+    /// Set to 0 to disable thickness-based filtering.
+    int min_thickness = 0;
+
     /// Color space flag.
     /// - 0 = CIE LAB (more perceptually accurate)
     /// - 1 = sRGB (faster).
@@ -77,7 +82,7 @@ void bilateral_filter(
 /// @copydoc IMG2NUM_H_LABELS_TO_SVG_DOC
 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_area, const int min_thickness
 );
 
 /// @copydoc IMG2NUM_H_IMAGE_TO_SVG_DOC

core/include/internal/LABAPixel.h

@@ -8,8 +8,7 @@ namespace ImageLib {
 #ifdef _MSC_VER
 #pragma pack(push, 1)
 #endif
-template <typename NumberT>
-struct LABAPixel : public ImageLib::LABPixel<NumberT> {
+template <typename NumberT> struct LABAPixel : public ImageLib::LABPixel<NumberT> {
     // ----- Members -----
     NumberT alpha;
 

core/include/internal/LABPixel.h

@@ -16,8 +16,7 @@ namespace ImageLib {
 #ifdef _MSC_VER
 #pragma pack(push, 1)
 #endif
-template <typename NumberT>
-struct LABPixel : public Pixel<NumberT> {
+template <typename NumberT> struct LABPixel : public Pixel<NumberT> {
     // ----- Members -----
     NumberT l, a, b;
 

core/include/internal/RGBAPixel.h

@@ -8,8 +8,7 @@ namespace ImageLib {
 #ifdef _MSC_VER
 #pragma pack(push, 1)
 #endif
-template <typename NumberT>
-struct RGBAPixel : public ImageLib::RGBPixel<NumberT> {
+template <typename NumberT> struct RGBAPixel : public ImageLib::RGBPixel<NumberT> {
     // ----- Members -----
     NumberT alpha;
 

core/include/internal/RGBPixel.h

@@ -11,8 +11,7 @@ namespace ImageLib {
 #ifdef _MSC_VER
 #pragma pack(push, 1)
 #endif
-template <typename NumberT>
-struct RGBPixel : public Pixel<NumberT> {
+template <typename NumberT> struct RGBPixel : public Pixel<NumberT> {
     // ----- Members -----
     NumberT red, green, blue;
 

core/include/internal/bezier.h

@@ -7,4 +7,13 @@ void fit_curve_reduction(
     const std::vector<std::vector<Point>>& chains, std::vector<std::vector<QuadBezier>>& results,
     float tolerance
 );
+
+// Same, but `fixed[i][k]!=0` marks point k of chain i as a junction that must NOT
+// move: the chain is split at those points so each becomes an exact (pinned)
+// curve endpoint. Chains with no fixed points fit identically to the overload
+// above.
+void fit_curve_reduction(
+    const std::vector<std::vector<Point>>& chains, const std::vector<std::vector<uint8_t>>& fixed,
+    std::vector<std::vector<QuadBezier>>& results, float tolerance
+);
 #endif

core/include/internal/contours.h

@@ -49,6 +49,23 @@ ContoursResult find_contours(const std::vector<uint8_t>& binary, int width, int
 void stitch_smooth(std::vector<Point>& vecA, std::vector<Point>& vecB);
 void coupled_smooth(std::vector<std::vector<Point>>& contours, Rect bounds);
 
+/**
+ * `@brief` Applies coupled smoothing with junction point locking.
+ *
+ * Similar to coupled_smooth but additionally locks points identified as junctions,
+ * preventing them from moving during the smoothing process. This preserves junction
+ * positions where multiple region boundaries meet.
+ *
+ * `@param` contours Vector of contour polylines to smooth
+ * `@param` bounds Bounding rectangle defining boundary constraints
+ * `@param` junctions Junction mask (image buffer with nonzero entries marking junction pixels)
+ * `@param` width Image width for raster indexing into the junctions mask
+ */
+void coupled_smooth_junctions(
+    std::vector<std::vector<Point>>& contours, Rect bounds, std::vector<uint8_t> junctions,
+    int width
+);
+
 void pack_with_boundary_constraints(
     std::vector<std::vector<Point>>& contours, Rect bounds, int iterations = 15
 );

core/include/internal/douglas_peucker.h

@@ -0,0 +1,31 @@
+#ifndef DOUGLAS_PEUCKER_H
+#define DOUGLAS_PEUCKER_H
+
+#include "internal/contours.h"
+
+#include <cstdint>
+#include <vector>
+
+/**
+ * `@brief` Douglas-Peucker contour point reduction with junction locking and retraction bounds.
+ *
+ * Reduces each contour's point count while preserving junctions and preventing gaps.
+ * Fixed junctions marked by `fixed[i][k] != 0` are kept as exact shared endpoints.
+ * Simplification is bounded to never retract a boundary inward past the inter-region
+ * overlap margin, preventing gaps between neighboring regions. Kept points are emitted
+ * as straight-line quadratic Bezier segments for compatibility with existing SVG output.
+ *
+ * `@param` chains Input polyline chains
+ * `@param` fixed Junction mask: fixed[i][k] != 0 marks point k of chain i as a junction to preserve
+ * `@param` results Output straight-line QuadBezier segments for each chain
+ * `@param` eps Overall deviation tolerance in pixels (overridable via IMG2NUM_DP_EPS env var)
+ *
+ * `@note` retract_eps (max inward boundary move) defaults to min(eps, 0.5px) and can be
+ *       overridden via IMG2NUM_DP_RETRACT environment variable.
+ */
+void dp_curve_reduction(
+    const std::vector<std::vector<Point>>& chains, const std::vector<std::vector<uint8_t>>& fixed,
+    std::vector<std::vector<QuadBezier>>& results, float eps
+);
+
+#endif

core/include/internal/gpu.h

@@ -230,8 +230,9 @@ class GPU {
                     std::cout << "Device Acquired" << std::endl;
                 } else {
                     std::cerr << "Device Failed: "
-                    << (msg.data && msg.length > 0 ? std::string(msg.data, msg.length) : "Unknown error")
-                    << std::endl;
+                              << (msg.data && msg.length > 0 ? std::string(msg.data, msg.length)
+                                                             : "Unknown error")
+                              << std::endl;
                 }
                 device_ready = true; // Unblock the loop
             }

core/include/internal/graph.h

@@ -39,6 +39,36 @@ class Graph {
     void hash_node_ids(void);
     void process_overlapping_edges();
 
+    /**
+     * `@brief` Safely retrieves a pixel value from a binary image with bounds checking.
+     *
+     * `@param` img Binary image buffer
+     * `@param` w Image width
+     * `@param` h Image height
+     * `@param` x Pixel x-coordinate
+     * `@param` y Pixel y-coordinate
+     * `@return` Pixel value at (x, y), or 0 if out of bounds
+     */
+    inline uint8_t getPixel(const std::vector<uint8_t>& img, int w, int h, int x, int y) {
+        if (x < 0 || x >= w || y < 0 || y >= h)
+            return 0; // Boundary check
+        return img[y * w + x];
+    }
+
+    /**
+     * `@brief` Analyzes a skeleton image to detect junction points using 8-neighbor
+     * crossing-number.
+     *
+     * Scans the skeleton image and marks pixels as junctions where three or more branches meet,
+     * using the crossing-number method (counts 0→1 transitions in the 8-neighbor ring).
+     *
+     * `@param` skel Binary skeleton image (nonzero = skeleton pixel)
+     * `@param` w Image width
+     * `@param` h Image height
+     * `@return` Junction mask with nonzero entries marking junction pixels
+     */
+    std::vector<uint8_t> analyzeJunctions(const std::vector<uint8_t>& skel, int w, int h);
+
   public:
     inline Graph(std::unique_ptr<std::vector<Node_ptr>>& nodes, int width, int height)
         : m_nodes(std::move(nodes))
@@ -71,7 +101,7 @@ class Graph {
     void discover_edges(
         const std::vector<int32_t>& region_labels, const int32_t width, const int32_t height
     );
-    void merge_small_area_nodes(const int32_t min_area);
+    void merge_small_area_nodes(const int32_t min_area, const int32_t min_thickness = 0);
     void compute_contours();
 };
 

core/include/internal/shared_contours.h

@@ -0,0 +1,27 @@
+#ifndef SHARED_CONTOURS_H
+#define SHARED_CONTOURS_H
+
+#include "internal/contours.h" // QuadBezier
+#include "internal/Point.h"
+
+#include <cstdint>
+#include <unordered_map>
+#include <vector>
+
+/**
+ * `@brief` Build crack-grid shared boundary loops for each region.
+ *
+ * Builds region boundaries on the pixel-corner ("crack") grid rather than on
+ * pixel centres. Shared edges are extracted once, simplified once, and reused
+ * by both adjacent regions so neighbouring loops stay exactly coincident.
+ *
+ * `@param` labels Per-pixel region ids in row-major order (`w * h` entries).
+ * `@param` w Image width in pixels.
+ * `@param` h Image height in pixels.
+ * `@param` eps Curve-fit tolerance applied to each canonical edge.
+ * `@return` Per-region closed boundary loops in corner coordinates.
+ */
+std::unordered_map<int32_t, std::vector<std::vector<QuadBezier>>>
+build_shared_loops(const std::vector<int32_t>& labels, int w, int h, float eps);
+
+#endif

core/src/internal/bezier.cpp

@@ -154,3 +154,39 @@ void fit_curve_reduction(
         results.push_back(result);
     }
 }
+
+// --- Junction-aware wrapper ---
+// Splits each chain at its fixed (junction) points and fits the pieces
+// separately. Because fitRecursive always keeps a segment's first and last point
+// exactly, every junction becomes a pinned on-curve point the fit cannot move.
+void fit_curve_reduction(
+    const std::vector<std::vector<Point>>& chains, const std::vector<std::vector<uint8_t>>& fixed,
+    std::vector<std::vector<QuadBezier>>& results, float tolerance
+) {
+    for (size_t i = 0; i < chains.size(); ++i) {
+        const std::vector<Point>& chain = chains[i];
+        const int n = static_cast<int>(chain.size());
+        std::vector<QuadBezier> result;
+        if (n < 2) {
+            results.push_back(result);
+            continue;
+        }
+
+        // Segment boundaries: chain ends plus every interior junction point.
+        std::vector<int> bounds;
+        bounds.push_back(0);
+        for (int k = 1; k < n - 1; ++k)
+            if (k < static_cast<int>(fixed[i].size()) && fixed[i][k])
+                bounds.push_back(k);
+        bounds.push_back(n - 1);
+
+        // Fit each [bounds[s], bounds[s+1]] piece; consecutive pieces share the
+        // junction point, so the curve stays continuous and pinned there.
+        for (size_t s = 0; s + 1 < bounds.size(); ++s) {
+            const int a = bounds[s], b = bounds[s + 1];
+            std::vector<Point> seg(chain.begin() + a, chain.begin() + b + 1);
+            fitRecursive(seg, tolerance, result);
+        }
+        results.push_back(result);
+    }
+}