strokemap 0.1.0__tar.gz

strokemap-0.1.0/AUTHORS.md

@@ -0,0 +1,11 @@
+# Authors
+
+## Primary Author
+
+- [Dipin Nair](https://github.com/dipinknair)
+
+## Acknowledgements
+
+Thank you to everyone who contributes bug reports, documentation updates, and feature improvements.
+
+If you would like to be listed here, please contribute to the project and open a pull request with your details.

strokemap-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dipin K Nair
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

strokemap-0.1.0/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: strokemap
+Version: 0.1.0
+Summary: Convert any image into a Paint by Numbers printable PDF
+Author-email: Developer <developer@example.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: opencv-python
+Requires-Dist: scikit-learn
+Requires-Dist: reportlab
+Requires-Dist: scikit-image
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Strokemap - Paint by Numbers Generator
+
+A Python package and CLI tool to convert any image into a high-quality, print-ready "Paint by Numbers" PDF template.
+
+The generated PDF matches premium standards, split into four cleanly laid-out pages:
+1. **Page 1 - Numbered Template**: Light gray outlines with a small, centered index number in each region.
+2. **Page 2 - Clean Outlines**: Clean black outlines without any numbers, perfect for clean canvas painting.
+3. **Page 3 - Colorized Preview**: A color reference picture showing what the finished painting should look like.
+4. **Page 4 - Color Palette Sheet**: A beautifully aligned grid of color swatches showing index numbers, hex codes, paint color blocks, and step-by-step instructions.
+
+---
+
+## Preview
+
+Here is an example of the generator's output using the standard **Lenna** test image:
+
+| Original Image | Numbered Template (Page 1) | Clean Outlines (Page 2) | Colorized Preview (Page 3) |
+| :---: | :---: | :---: | :---: |
+| ![Original Lenna](tests/assets/lenna.png) | ![Numbered Template](tests/assets/lenna_numbered.png) | ![Clean Outlines](tests/assets/lenna_clean.png) | ![Colorized Preview](tests/assets/lenna_colorized.png) |
+
+> [!NOTE]
+> **Image Citation**: Lenna (or Lena) is a standard digital image processing test image, originally from the USC-SIPI Image Database. It is widely used for testing image processing algorithms.
+
+---
+
+## Installation
+
+Create a virtual environment and install the package locally:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### Dependencies
+The package relies on the following standard python packages:
+- `numpy`
+- `pillow`
+- `opencv-python`
+- `scikit-learn`
+- `reportlab`
+- `scikit-image`
+
+---
+
+## Usage
+
+### Command Line Interface
+
+You can convert any image directly from your terminal:
+
+```bash
+strokemap input.jpg output.pdf --colors 20 --difficulty medium
+```
+
+#### CLI Options:
+* `image_path` (required): Path to the input image file.
+* `output_pdf` (required): Path where the final PDF should be saved.
+* `-c`, `--colors` (optional): Target number of colors (default: 20).
+* `-d`, `--difficulty` (optional): Level of region detail (`easy`, `medium`, `hard`) (default: `medium`).
+
+### Python API
+
+You can also use the package programmatically:
+
+```python
+from strokemap import PaintByNumbersGenerator, generate_pdf
+
+# 1. Initialize generator with difficulty settings
+generator = PaintByNumbersGenerator(difficulty="medium")
+
+# 2. Process image to get templates and palette
+numbered_img, clean_img, colorized_img, palette = generator.process("input.jpg", n_colors=20)
+
+# 3. Compile everything into a 4-page A4 PDF
+generate_pdf(
+    output_pdf_path="output.pdf",
+    numbered_img=numbered_img,
+    clean_img=clean_img,
+    colorized_img=colorized_img,
+    palette=palette,
+)
+```
+
+---
+
+## Algorithms Used
+
+1. **Superpixel Segmentation (SLIC)**: Uses the Simple Linear Iterative Clustering (SLIC) algorithm to cluster pixels into contiguous, edge-conforming "superpixels". This ensures that the boundaries of regions natively stick to the actual physical boundaries and details in the image (such as eyes, text, and fine lines).
+2. **Color Quantization**: Performs K-Means clustering on the average colors of the superpixels in the CIELAB color space. Working in CIELAB space allows color distances to match human perception, resulting in a vibrant and accurate palette.
+3. **Detail Reduction & Region Merging**: Small, hard-to-paint micro-regions are intelligently merged into their dominant neighbor using connected components analysis, with thresholds dynamically adjusted by the selected difficulty level.
+4. **Outline Extraction**: Computes a pixel-wise transition grid to produce clean, single-pixel outlines.
+5. **Optimal Label Placement**: Uses a distance transform (`cv2.distanceTransform`) to find the center of the largest inscribed circle within each region, placing number labels at the most readable point.
+
+---
+
+## Authors
+
+- Developer
+
+For additional author and maintainer details, see [AUTHORS.md](AUTHORS.md).
+
+## Contributors
+
+This project is maintained by the community. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the current list of contributors and how to get involved.
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request.
+
+## Security
+
+If you discover a vulnerability, please do not publish it publicly. Refer to [SECURITY.md](SECURITY.md) for our security reporting policy.

strokemap-0.1.0/README.md

@@ -0,0 +1,114 @@
+# Strokemap - Paint by Numbers Generator
+
+A Python package and CLI tool to convert any image into a high-quality, print-ready "Paint by Numbers" PDF template.
+
+The generated PDF matches premium standards, split into four cleanly laid-out pages:
+1. **Page 1 - Numbered Template**: Light gray outlines with a small, centered index number in each region.
+2. **Page 2 - Clean Outlines**: Clean black outlines without any numbers, perfect for clean canvas painting.
+3. **Page 3 - Colorized Preview**: A color reference picture showing what the finished painting should look like.
+4. **Page 4 - Color Palette Sheet**: A beautifully aligned grid of color swatches showing index numbers, hex codes, paint color blocks, and step-by-step instructions.
+
+---
+
+## Preview
+
+Here is an example of the generator's output using the standard **Lenna** test image:
+
+| Original Image | Numbered Template (Page 1) | Clean Outlines (Page 2) | Colorized Preview (Page 3) |
+| :---: | :---: | :---: | :---: |
+| ![Original Lenna](tests/assets/lenna.png) | ![Numbered Template](tests/assets/lenna_numbered.png) | ![Clean Outlines](tests/assets/lenna_clean.png) | ![Colorized Preview](tests/assets/lenna_colorized.png) |
+
+> [!NOTE]
+> **Image Citation**: Lenna (or Lena) is a standard digital image processing test image, originally from the USC-SIPI Image Database. It is widely used for testing image processing algorithms.
+
+---
+
+## Installation
+
+Create a virtual environment and install the package locally:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### Dependencies
+The package relies on the following standard python packages:
+- `numpy`
+- `pillow`
+- `opencv-python`
+- `scikit-learn`
+- `reportlab`
+- `scikit-image`
+
+---
+
+## Usage
+
+### Command Line Interface
+
+You can convert any image directly from your terminal:
+
+```bash
+strokemap input.jpg output.pdf --colors 20 --difficulty medium
+```
+
+#### CLI Options:
+* `image_path` (required): Path to the input image file.
+* `output_pdf` (required): Path where the final PDF should be saved.
+* `-c`, `--colors` (optional): Target number of colors (default: 20).
+* `-d`, `--difficulty` (optional): Level of region detail (`easy`, `medium`, `hard`) (default: `medium`).
+
+### Python API
+
+You can also use the package programmatically:
+
+```python
+from strokemap import PaintByNumbersGenerator, generate_pdf
+
+# 1. Initialize generator with difficulty settings
+generator = PaintByNumbersGenerator(difficulty="medium")
+
+# 2. Process image to get templates and palette
+numbered_img, clean_img, colorized_img, palette = generator.process("input.jpg", n_colors=20)
+
+# 3. Compile everything into a 4-page A4 PDF
+generate_pdf(
+    output_pdf_path="output.pdf",
+    numbered_img=numbered_img,
+    clean_img=clean_img,
+    colorized_img=colorized_img,
+    palette=palette,
+)
+```
+
+---
+
+## Algorithms Used
+
+1. **Superpixel Segmentation (SLIC)**: Uses the Simple Linear Iterative Clustering (SLIC) algorithm to cluster pixels into contiguous, edge-conforming "superpixels". This ensures that the boundaries of regions natively stick to the actual physical boundaries and details in the image (such as eyes, text, and fine lines).
+2. **Color Quantization**: Performs K-Means clustering on the average colors of the superpixels in the CIELAB color space. Working in CIELAB space allows color distances to match human perception, resulting in a vibrant and accurate palette.
+3. **Detail Reduction & Region Merging**: Small, hard-to-paint micro-regions are intelligently merged into their dominant neighbor using connected components analysis, with thresholds dynamically adjusted by the selected difficulty level.
+4. **Outline Extraction**: Computes a pixel-wise transition grid to produce clean, single-pixel outlines.
+5. **Optimal Label Placement**: Uses a distance transform (`cv2.distanceTransform`) to find the center of the largest inscribed circle within each region, placing number labels at the most readable point.
+
+---
+
+## Authors
+
+- Developer
+
+For additional author and maintainer details, see [AUTHORS.md](AUTHORS.md).
+
+## Contributors
+
+This project is maintained by the community. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the current list of contributors and how to get involved.
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request.
+
+## Security
+
+If you discover a vulnerability, please do not publish it publicly. Refer to [SECURITY.md](SECURITY.md) for our security reporting policy.

strokemap-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+[build-system]
+requires = ["setuptools>=61.0.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "strokemap"
+version = "0.1.0"
+description = "Convert any image into a Paint by Numbers printable PDF"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [
+    { name = "Developer", email = "developer@example.com" }
+]
+dependencies = [
+    "numpy",
+    "pillow",
+    "opencv-python",
+    "scikit-learn",
+    "reportlab",
+    "scikit-image",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov",
+    "pre-commit",
+    "ruff",
+]
+
+[project.scripts]
+strokemap = "strokemap.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["strokemap*"]
+
+# ---------------------------------------------------------------------------
+# Ruff – linter + formatter
+# ---------------------------------------------------------------------------
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",   # pycodestyle errors
+    "W",   # pycodestyle warnings
+    "F",   # pyflakes
+    "I",   # isort
+    "B",   # flake8-bugbear
+    "UP",  # pyupgrade
+    "C4",  # flake8-comprehensions
+    "SIM", # flake8-simplify
+]
+ignore = [
+    "E501",  # line too long – handled by formatter
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["strokemap"]
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+
+# ---------------------------------------------------------------------------
+# Pytest
+# ---------------------------------------------------------------------------
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-v"

strokemap-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

strokemap-0.1.0/src/strokemap/__init__.py

@@ -0,0 +1,4 @@
+from .generator import PaintByNumbersGenerator
+from .pdf_generator import generate_pdf
+
+__all__ = ["PaintByNumbersGenerator", "generate_pdf"]

strokemap-0.1.0/src/strokemap/cli.py

@@ -0,0 +1,67 @@
+import argparse
+import os
+import sys
+import traceback
+
+from .generator import PaintByNumbersGenerator
+from .pdf_generator import generate_pdf
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Convert any image to a print-ready Paint by Numbers PDF."
+    )
+    parser.add_argument("image_path", help="Path to the input image file (JPEG, PNG, etc.)")
+    parser.add_argument("output_pdf", help="Path where the output PDF should be saved")
+    parser.add_argument(
+        "-c",
+        "--colors",
+        type=int,
+        default=20,
+        help="Number of colors to use for the painting (default: 20)",
+    )
+    parser.add_argument(
+        "-d",
+        "--difficulty",
+        choices=["easy", "medium", "hard"],
+        default="medium",
+        help="Difficulty level which controls region sizes and details (default: medium)",
+    )
+
+    args = parser.parse_args()
+
+    if not os.path.exists(args.image_path):
+        print(f"Error: Input image file '{args.image_path}' does not exist.", file=sys.stderr)
+        sys.exit(1)
+
+    print(f"Processing image: {args.image_path}")
+    print(f"Difficulty level: {args.difficulty}")
+    print(f"Target colors: {args.colors}")
+
+    # Run the generator pipeline
+    generator = PaintByNumbersGenerator(difficulty=args.difficulty)
+    try:
+        numbered_img, clean_img, colorized_img, palette = generator.process(
+            args.image_path, args.colors
+        )
+
+        print(f"Generated outlines with {len(palette)} final colors.")
+        print(f"Compiling PDF to: {args.output_pdf}")
+
+        generate_pdf(
+            output_pdf_path=args.output_pdf,
+            numbered_img=numbered_img,
+            clean_img=clean_img,
+            colorized_img=colorized_img,
+            palette=palette,
+        )
+        print("Success! Paint by Numbers PDF generated successfully.")
+
+    except Exception as e:
+        print(f"Error generating Paint by Numbers: {e}", file=sys.stderr)
+        traceback.print_exc()
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

strokemap-0.1.0/src/strokemap/generator.py

@@ -0,0 +1,350 @@
+import os
+
+import cv2
+import numpy as np
+from PIL import Image, ImageDraw, ImageFont
+from skimage.segmentation import slic
+from sklearn.cluster import KMeans
+
+
+class PaintByNumbersGenerator:
+    def __init__(
+        self,
+        difficulty="medium",
+        outline_color=(180, 185, 200),
+        number_color=(100, 105, 115),
+        clean_outline_color=(0, 0, 0),
+    ):
+        self.difficulty = difficulty.lower()
+        self.outline_color = outline_color
+        self.number_color = number_color
+        self.clean_outline_color = clean_outline_color
+
+        # Difficulty parameters
+        if self.difficulty == "easy":
+            self.n_segments_base = 800
+            self.slic_compactness = 5.0
+            self.slic_sigma = 3.0
+            self.min_area_fraction = 0.0005
+        elif self.difficulty == "hard":
+            self.n_segments_base = 4000
+            self.slic_compactness = 10.0
+            self.slic_sigma = 1.0
+            self.min_area_fraction = 0.00005
+        else:  # medium
+            self.n_segments_base = 2000
+            self.slic_compactness = 8.0
+            self.slic_sigma = 2.0
+            self.min_area_fraction = 0.0002
+
+    def load_image(self, image_path):
+        """Loads image, handles transparency, and returns RGB numpy array."""
+        # Read with cv2 (BGR)
+        img = cv2.imread(image_path, cv2.IMREAD_UNCHANGED)
+        if img is None:
+            raise FileNotFoundError(f"Could not load image from {image_path}")
+
+        # Convert BGR/BGRA to RGB
+        if len(img.shape) == 3 and img.shape[2] == 4:
+            # BGRA to BGR blending with white background
+            alpha = img[:, :, 3:] / 255.0
+            img = (img[:, :, :3] * alpha + 255.0 * (1.0 - alpha)).astype(np.uint8)
+            img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+        elif len(img.shape) == 3 and img.shape[2] == 3:
+            img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+        else:
+            # Grayscale to RGB
+            img = cv2.cvtColor(img, cv2.COLOR_GRAY2RGB)
+
+        return img
+
+    def preprocess_image(self, img):
+        """Applies median filtering to remove noise before segmentation."""
+        # Using a small median filter, cv2.medianBlur is very fast
+        ksize = 5 if self.difficulty == "easy" else 3
+        return cv2.medianBlur(img, ksize)
+
+    def quantize_colors(self, img, n_colors):
+        """Segments image using SLIC superpixels and clusters their mean colors."""
+        h, w, c = img.shape
+
+        # Calculate number of segments based on image resolution
+        scale_factor = (h * w) / 1000000.0
+        n_segments = int(self.n_segments_base * max(0.5, scale_factor))
+
+        # 1. SLIC Superpixels
+        segments = slic(
+            img,
+            n_segments=n_segments,
+            compactness=self.slic_compactness,
+            sigma=self.slic_sigma,
+            start_label=0,
+        )
+
+        num_segments = np.max(segments) + 1
+
+        # Convert to LAB space for perceptual operations
+        lab_img = cv2.cvtColor(img, cv2.COLOR_RGB2LAB)
+
+        # 2. Compute mean color for each segment
+        segment_means = np.zeros((num_segments, 3), dtype=np.float32)
+
+        # Fast mean computation using bincount
+        for channel in range(3):
+            channel_sums = np.bincount(
+                segments.ravel(), weights=lab_img[:, :, channel].ravel(), minlength=num_segments
+            )
+            pixel_counts = np.bincount(segments.ravel(), minlength=num_segments)
+            pixel_counts[pixel_counts == 0] = 1  # Avoid division by zero
+            segment_means[:, channel] = channel_sums / pixel_counts
+
+        # 3. KMeans clustering on the segment means
+        kmeans = KMeans(n_clusters=n_colors, random_state=42, n_init="auto")
+        segment_labels = kmeans.fit_predict(segment_means)
+        centers_lab = kmeans.cluster_centers_
+
+        # 4. Map superpixel labels back to image
+        labels_2d = segment_labels[segments]
+
+        # Build palette
+        palette = []
+        for i, center in enumerate(centers_lab):
+            center_pixel = center.reshape(1, 1, 3).astype(np.uint8)
+            rgb_pixel = cv2.cvtColor(center_pixel, cv2.COLOR_LAB2RGB)[0, 0]
+            rgb = (int(rgb_pixel[0]), int(rgb_pixel[1]), int(rgb_pixel[2]))
+            hex_code = f"#{rgb[0]:02X}{rgb[1]:02X}{rgb[2]:02X}"
+            palette.append({"old_index": i, "rgb": rgb, "hex": hex_code})
+
+        # Sort palette by perceived brightness (luminance)
+        palette.sort(key=lambda x: 0.299 * x["rgb"][0] + 0.587 * x["rgb"][1] + 0.114 * x["rgb"][2])
+
+        # Create a remapping array for speed
+        remap_arr = np.zeros(n_colors, dtype=np.int32)
+        for new_idx, item in enumerate(palette):
+            remap_arr[item["old_index"]] = new_idx
+
+        labels_2d_sorted = remap_arr[labels_2d]
+
+        # Clean palette data structure
+        sorted_palette = [{"rgb": item["rgb"], "hex": item["hex"]} for item in palette]
+
+        return labels_2d_sorted, sorted_palette
+
+    def merge_small_regions(self, labels_2d, n_colors, min_area):
+        """Iteratively merges components smaller than min_area into their largest neighbors."""
+        h, w = labels_2d.shape
+        result = labels_2d.copy()
+
+        iteration = 0
+        max_iterations = 10
+
+        while iteration < max_iterations:
+            changed = False
+            small_components = []
+
+            # Find connected components for each color index
+            unique_colors = np.unique(result)
+            for c in unique_colors:
+                mask = (result == c).astype(np.uint8)
+                num_labels, labels, stats, centroids = cv2.connectedComponentsWithStats(
+                    mask, connectivity=4
+                )
+
+                for label_idx in range(1, num_labels):
+                    area = stats[label_idx, cv2.CC_STAT_AREA]
+                    if area < min_area:
+                        comp_mask = labels == label_idx
+                        small_components.append({"color": c, "area": area, "mask": comp_mask})
+
+            if not small_components:
+                break
+
+            # Sort by area ascending to merge smallest first
+            small_components.sort(key=lambda x: x["area"])
+
+            for comp in small_components:
+                comp_mask = comp["mask"]
+                current_vals = result[comp_mask]
+                if len(current_vals) == 0:
+                    continue
+
+                val = current_vals[0]
+                if not np.all(current_vals == val):
+                    # Component has already been modified in this iteration, skip
+                    continue
+
+                # Dilate mask to find neighbor pixels
+                kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (3, 3))
+                dilated = cv2.dilate(comp_mask.astype(np.uint8), kernel)
+                border = (dilated == 1) & (~comp_mask)
+
+                neighbor_colors = result[border]
+                if len(neighbor_colors) == 0:
+                    continue
+
+                # Count frequencies of neighboring colors
+                counts = np.bincount(neighbor_colors, minlength=val + 1)
+                counts[val] = 0  # Ignore current color to force merge with a neighbor
+
+                if np.max(counts) == 0:
+                    continue
+
+                best_neighbor = np.argmax(counts)
+                result[comp_mask] = best_neighbor
+                changed = True
+
+            if not changed:
+                break
+
+            iteration += 1
+
+        # Re-index remaining colors to start from 1 to N without gaps
+        unique_remaining = sorted(np.unique(result).tolist())
+        label_map = {old_lbl: new_lbl + 1 for new_lbl, old_lbl in enumerate(unique_remaining)}
+
+        final_labels = np.vectorize(label_map.get)(result)
+
+        return final_labels, unique_remaining
+
+    def get_outlines(self, final_labels):
+        """Generates 1-pixel boundary edge map."""
+        h, w = final_labels.shape
+        edges = np.zeros((h, w), dtype=bool)
+
+        # Compare each pixel with its right and bottom neighbors
+        edges[:-1, :] |= final_labels[:-1, :] != final_labels[1:, :]
+        edges[:, :-1] |= final_labels[:, :-1] != final_labels[:, 1:]
+
+        # Add outer canvas border
+        edges[0, :] = True
+        edges[-1, :] = True
+        edges[:, 0] = True
+        edges[:, -1] = True
+
+        return edges
+
+    def generate_templates(self, final_labels, edges, num_colors):
+        """Creates the numbered template and the clean outlines template images."""
+        h, w = final_labels.shape
+
+        # Determine scaling for drawing (lines, fonts)
+        max_dim = max(h, w)
+        outline_thickness = max(1, int(max_dim / 1500))
+        font_size = max(8, int(max_dim * 0.0055))
+
+        # Build dilated edges for template drawing
+        if outline_thickness > 1:
+            kernel = cv2.getStructuringElement(
+                cv2.MORPH_RECT, (outline_thickness, outline_thickness)
+            )
+            edges_drawn = cv2.dilate(edges.astype(np.uint8), kernel) > 0
+        else:
+            edges_drawn = edges
+
+        # 1. Clean outline image (solid black lines on white)
+        clean_np = np.ones((h, w, 3), dtype=np.uint8) * 255
+        clean_np[edges_drawn] = self.clean_outline_color
+        clean_img = Image.fromarray(clean_np)
+
+        # 2. Numbered outline image (gray lines on white)
+        numbered_np = np.ones((h, w, 3), dtype=np.uint8) * 255
+        numbered_np[edges_drawn] = self.outline_color
+        numbered_img = Image.fromarray(numbered_np)
+
+        draw = ImageDraw.Draw(numbered_img)
+
+        # Load clean sans-serif font
+        font = None
+        font_paths = [
+            "/System/Library/Fonts/Supplemental/Arial.ttf",
+            "/System/Library/Fonts/Helvetica.ttc",
+            "/System/Library/Fonts/SFNS.ttf",
+            "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+            "C:\\Windows\\Fonts\\arial.ttf",
+        ]
+        for path in font_paths:
+            if os.path.exists(path):
+                try:
+                    font = ImageFont.truetype(path, size=font_size)
+                    break
+                except Exception:
+                    pass
+        if font is None:
+            font = ImageFont.load_default()
+
+        min_dist_to_draw = font_size * 0.45
+
+        # Place numbers using distance transform on connected components
+        for v in range(1, num_colors + 1):
+            mask = (final_labels == v).astype(np.uint8)
+            num_labels, labels, stats, centroids = cv2.connectedComponentsWithStats(
+                mask, connectivity=8
+            )
+
+            for i in range(1, num_labels):
+                comp_mask = (labels == i).astype(np.uint8)
+
+                # Compute distance transform of component mask
+                dist_transform = cv2.distanceTransform(comp_mask, cv2.DIST_L2, 5)
+                _, max_val, _, max_loc = cv2.minMaxLoc(dist_transform)
+
+                # Only write number if it fits nicely inside the region
+                if max_val >= min_dist_to_draw:
+                    cx, cy = max_loc
+                    text_str = str(v)
+
+                    # Center the text
+                    bbox = draw.textbbox((0, 0), text_str, font=font)
+                    text_w = bbox[2] - bbox[0]
+                    text_h = bbox[3] - bbox[1]
+
+                    text_x = cx - text_w / 2
+                    text_y = cy - text_h / 2
+
+                    draw.text((text_x, text_y), text_str, fill=self.number_color, font=font)
+
+        return numbered_img, clean_img
+
+    def process(self, image_path, n_colors):
+        """Runs the entire pipeline on the input image and returns output images and palette."""
+        # 1. Load & preprocess
+        img = self.load_image(image_path)
+        smoothed = self.preprocess_image(img)
+
+        # 2. Quantize
+        labels_2d, sorted_palette = self.quantize_colors(smoothed, n_colors)
+
+        # Smooth the initial labels to create curvy, organic boundaries
+        h, w = labels_2d.shape
+        k_size = max(5, int(max(h, w) * 0.005))
+        if k_size % 2 == 0:
+            k_size += 1
+        labels_2d = cv2.medianBlur(labels_2d.astype(np.uint8), k_size).astype(np.int32)
+
+        # 3. Merge small regions
+        min_area = int(h * w * self.min_area_fraction)
+        final_labels, unique_remaining = self.merge_small_regions(labels_2d, n_colors, min_area)
+
+        # 4. Filter palette to remaining colors
+        final_palette = []
+        for i, old_idx in enumerate(unique_remaining):
+            color_info = sorted_palette[old_idx]
+            final_palette.append(
+                {"index": i + 1, "rgb": color_info["rgb"], "hex": color_info["hex"]}
+            )
+
+        num_final_colors = len(final_palette)
+
+        # 5. Extract outlines and draw templates
+        edges = self.get_outlines(final_labels)
+        numbered_img, clean_img = self.generate_templates(final_labels, edges, num_final_colors)
+
+        # 6. Build colorized preview image
+        colorized_np = np.zeros((h, w, 3), dtype=np.uint8)
+        for color_info in final_palette:
+            idx = color_info["index"]
+            rgb = color_info["rgb"]
+            colorized_np[final_labels == idx] = rgb
+        colorized_img = Image.fromarray(colorized_np)
+
+        return numbered_img, clean_img, colorized_img, final_palette

strokemap-0.1.0/src/strokemap/pdf_generator.py

@@ -0,0 +1,231 @@
+import io
+
+from reportlab.lib.colors import HexColor
+from reportlab.lib.enums import TA_CENTER
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.styles import ParagraphStyle, getSampleStyleSheet
+from reportlab.platypus import Image as RLImage
+from reportlab.platypus import PageBreak, Paragraph, SimpleDocTemplate, Spacer, Table, TableStyle
+from reportlab.platypus.flowables import Flowable
+
+
+class ColorSwatch(Flowable):
+    def __init__(self, index, rgb, hex_code, width=80, height=70):
+        super().__init__()
+        self.index = index
+        self.rgb = rgb  # tuple (r, g, b)
+        self.hex_code = hex_code
+        self.width = width
+        self.height = height
+
+    def wrap(self, availWidth, availHeight):
+        return self.width, self.height
+
+    def draw(self):
+        # Draw color box
+        # Normalize color to 0.0 - 1.0 for reportlab
+        r, g, b = (val / 255.0 for val in self.rgb)
+        self.canv.setFillColorRGB(r, g, b)
+        self.canv.setStrokeColorRGB(0.1, 0.1, 0.1)
+        self.canv.setLineWidth(1)
+
+        # Center square horizontally
+        square_size = 36
+        sq_x = (self.width - square_size) / 2
+        sq_y = self.height - square_size - 2
+
+        self.canv.rect(sq_x, sq_y, square_size, square_size, fill=1, stroke=1)
+
+        # Draw color index number
+        self.canv.setFont("Helvetica-Bold", 10)
+        self.canv.setFillColorRGB(0.1, 0.1, 0.1)
+        self.canv.drawCentredString(self.width / 2, sq_y - 12, str(self.index))
+
+        # Draw Hex Code
+        self.canv.setFont("Helvetica", 8)
+        self.canv.setFillColorRGB(0.4, 0.4, 0.4)
+        self.canv.drawCentredString(self.width / 2, sq_y - 24, self.hex_code)
+
+
+def generate_pdf(
+    output_pdf_path,
+    numbered_img,
+    clean_img,
+    colorized_img,
+    palette,
+):
+    # Margins and page size
+    margin = 36  # 0.5 inch
+    doc = SimpleDocTemplate(
+        output_pdf_path,
+        pagesize=A4,
+        leftMargin=margin,
+        rightMargin=margin,
+        topMargin=margin,
+        bottomMargin=margin,
+    )
+
+    page_w, page_h = A4
+    max_w = page_w - 2 * margin
+    max_h = page_h - 2 * margin
+
+    story = []
+
+    # ----------------------------------------------------
+    # Page 1: Numbered Template Image
+    # ----------------------------------------------------
+    num_buf = io.BytesIO()
+    numbered_img.save(num_buf, format="PNG")
+    num_buf.seek(0)
+
+    # Calculate dimensions to maintain aspect ratio
+    img_w, img_h = numbered_img.size
+    aspect_ratio = img_w / img_h
+
+    if max_w / aspect_ratio <= max_h:
+        draw_w = max_w
+        draw_h = max_w / aspect_ratio
+    else:
+        draw_h = max_h
+        draw_w = max_h * aspect_ratio
+
+    # Spacer to vertically center the image on the page
+    v_spacer_1 = (max_h - draw_h) / 2
+    if v_spacer_1 > 0:
+        story.append(Spacer(1, v_spacer_1))
+
+    story.append(RLImage(num_buf, width=draw_w, height=draw_h))
+    story.append(PageBreak())
+
+    # ----------------------------------------------------
+    # Page 2: Clean Outline Image
+    # ----------------------------------------------------
+    clean_buf = io.BytesIO()
+    clean_img.save(clean_buf, format="PNG")
+    clean_buf.seek(0)
+
+    v_spacer_2 = (max_h - draw_h) / 2
+    if v_spacer_2 > 0:
+        story.append(Spacer(1, v_spacer_2))
+
+    story.append(RLImage(clean_buf, width=draw_w, height=draw_h))
+    story.append(PageBreak())
+
+    # ----------------------------------------------------
+    # Page 3: Color Preview Image (How it should look)
+    # ----------------------------------------------------
+    preview_buf = io.BytesIO()
+    colorized_img.save(preview_buf, format="PNG")
+    preview_buf.seek(0)
+
+    v_spacer_3 = (max_h - draw_h) / 2
+    if v_spacer_3 > 0:
+        story.append(Spacer(1, v_spacer_3))
+
+    story.append(RLImage(preview_buf, width=draw_w, height=draw_h))
+    story.append(PageBreak())
+
+    # ----------------------------------------------------
+    # Page 4: Palette Sheet
+    # ----------------------------------------------------
+    styles = getSampleStyleSheet()
+
+    # Custom typography styles
+    title_style = ParagraphStyle(
+        "PaletteTitle",
+        parent=styles["Normal"],
+        fontName="Helvetica-Bold",
+        fontSize=26,
+        leading=32,
+        alignment=TA_CENTER,
+        spaceAfter=6,
+    )
+
+    instruction_title_style = ParagraphStyle(
+        "InstructionTitle",
+        parent=styles["Normal"],
+        fontName="Helvetica-Bold",
+        fontSize=11,
+        leading=15,
+        spaceAfter=6,
+    )
+
+    instruction_body_style = ParagraphStyle(
+        "InstructionBody",
+        parent=styles["Normal"],
+        fontName="Helvetica",
+        fontSize=9.5,
+        leading=14,
+        textColor=HexColor("#333333"),
+        spaceAfter=4,
+    )
+
+    # Title
+    story.append(Paragraph("Strokemap", title_style))
+
+    # Color palette grid
+    num_cols = 6
+    col_w = max_w / num_cols
+
+    swatches = []
+    for color in palette:
+        swatches.append(
+            ColorSwatch(
+                index=color["index"],
+                rgb=color["rgb"],
+                hex_code=color["hex"],
+                width=col_w,
+                height=70,
+            )
+        )
+
+    # Arrange into grid matrix
+    table_data = []
+    current_row = []
+    for _, swatch in enumerate(swatches):
+        current_row.append(swatch)
+        if len(current_row) == num_cols:
+            table_data.append(current_row)
+            current_row = []
+    if current_row:
+        # Pad last row with empty flowables
+        while len(current_row) < num_cols:
+            current_row.append("")
+        table_data.append(current_row)
+
+    palette_table = Table(table_data, colWidths=[col_w] * num_cols)
+    palette_table.setStyle(
+        TableStyle(
+            [
+                ("ALIGN", (0, 0), (-1, -1), "CENTER"),
+                ("VALIGN", (0, 0), (-1, -1), "MIDDLE"),
+                ("LEFTPADDING", (0, 0), (-1, -1), 0),
+                ("RIGHTPADDING", (0, 0), (-1, -1), 0),
+                ("TOPPADDING", (0, 0), (-1, -1), 6),
+                ("BOTTOMPADDING", (0, 0), (-1, -1), 6),
+            ]
+        )
+    )
+
+    story.append(palette_table)
+    story.append(Spacer(1, 24))
+
+    # Instructions at the bottom
+    story.append(Paragraph("Instructions:", instruction_title_style))
+
+    bullets = [
+        "<b>Page 1 - Numbered template:</b> Find numbered areas and match to colors on page 4.",
+        "<b>Page 2 - Clean borders:</b> For those who want a clean painting experience.",
+        "<b>Page 3 - Colored preview:</b> A reference picture showing how the final painting looks.",
+        "1. Choose your preferred template (numbered or clean borders).",
+        "2. Match the numbers to the colors on the palette sheet (page 4).",
+        "3. Paint each area with the corresponding color.",
+        "4. Use the colored preview page as a reference.",
+        "5. Take your time and enjoy the process!",
+    ]
+
+    for bullet in bullets:
+        story.append(Paragraph(bullet, instruction_body_style))
+
+    # Build Document
+    doc.build(story)

strokemap-0.1.0/src/strokemap.egg-info/PKG-INFO

@@ -0,0 +1,137 @@
+Metadata-Version: 2.4
+Name: strokemap
+Version: 0.1.0
+Summary: Convert any image into a Paint by Numbers printable PDF
+Author-email: Developer <developer@example.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: AUTHORS.md
+Requires-Dist: numpy
+Requires-Dist: pillow
+Requires-Dist: opencv-python
+Requires-Dist: scikit-learn
+Requires-Dist: reportlab
+Requires-Dist: scikit-image
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Strokemap - Paint by Numbers Generator
+
+A Python package and CLI tool to convert any image into a high-quality, print-ready "Paint by Numbers" PDF template.
+
+The generated PDF matches premium standards, split into four cleanly laid-out pages:
+1. **Page 1 - Numbered Template**: Light gray outlines with a small, centered index number in each region.
+2. **Page 2 - Clean Outlines**: Clean black outlines without any numbers, perfect for clean canvas painting.
+3. **Page 3 - Colorized Preview**: A color reference picture showing what the finished painting should look like.
+4. **Page 4 - Color Palette Sheet**: A beautifully aligned grid of color swatches showing index numbers, hex codes, paint color blocks, and step-by-step instructions.
+
+---
+
+## Preview
+
+Here is an example of the generator's output using the standard **Lenna** test image:
+
+| Original Image | Numbered Template (Page 1) | Clean Outlines (Page 2) | Colorized Preview (Page 3) |
+| :---: | :---: | :---: | :---: |
+| ![Original Lenna](tests/assets/lenna.png) | ![Numbered Template](tests/assets/lenna_numbered.png) | ![Clean Outlines](tests/assets/lenna_clean.png) | ![Colorized Preview](tests/assets/lenna_colorized.png) |
+
+> [!NOTE]
+> **Image Citation**: Lenna (or Lena) is a standard digital image processing test image, originally from the USC-SIPI Image Database. It is widely used for testing image processing algorithms.
+
+---
+
+## Installation
+
+Create a virtual environment and install the package locally:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+### Dependencies
+The package relies on the following standard python packages:
+- `numpy`
+- `pillow`
+- `opencv-python`
+- `scikit-learn`
+- `reportlab`
+- `scikit-image`
+
+---
+
+## Usage
+
+### Command Line Interface
+
+You can convert any image directly from your terminal:
+
+```bash
+strokemap input.jpg output.pdf --colors 20 --difficulty medium
+```
+
+#### CLI Options:
+* `image_path` (required): Path to the input image file.
+* `output_pdf` (required): Path where the final PDF should be saved.
+* `-c`, `--colors` (optional): Target number of colors (default: 20).
+* `-d`, `--difficulty` (optional): Level of region detail (`easy`, `medium`, `hard`) (default: `medium`).
+
+### Python API
+
+You can also use the package programmatically:
+
+```python
+from strokemap import PaintByNumbersGenerator, generate_pdf
+
+# 1. Initialize generator with difficulty settings
+generator = PaintByNumbersGenerator(difficulty="medium")
+
+# 2. Process image to get templates and palette
+numbered_img, clean_img, colorized_img, palette = generator.process("input.jpg", n_colors=20)
+
+# 3. Compile everything into a 4-page A4 PDF
+generate_pdf(
+    output_pdf_path="output.pdf",
+    numbered_img=numbered_img,
+    clean_img=clean_img,
+    colorized_img=colorized_img,
+    palette=palette,
+)
+```
+
+---
+
+## Algorithms Used
+
+1. **Superpixel Segmentation (SLIC)**: Uses the Simple Linear Iterative Clustering (SLIC) algorithm to cluster pixels into contiguous, edge-conforming "superpixels". This ensures that the boundaries of regions natively stick to the actual physical boundaries and details in the image (such as eyes, text, and fine lines).
+2. **Color Quantization**: Performs K-Means clustering on the average colors of the superpixels in the CIELAB color space. Working in CIELAB space allows color distances to match human perception, resulting in a vibrant and accurate palette.
+3. **Detail Reduction & Region Merging**: Small, hard-to-paint micro-regions are intelligently merged into their dominant neighbor using connected components analysis, with thresholds dynamically adjusted by the selected difficulty level.
+4. **Outline Extraction**: Computes a pixel-wise transition grid to produce clean, single-pixel outlines.
+5. **Optimal Label Placement**: Uses a distance transform (`cv2.distanceTransform`) to find the center of the largest inscribed circle within each region, placing number labels at the most readable point.
+
+---
+
+## Authors
+
+- Developer
+
+For additional author and maintainer details, see [AUTHORS.md](AUTHORS.md).
+
+## Contributors
+
+This project is maintained by the community. See [CONTRIBUTORS.md](CONTRIBUTORS.md) for the current list of contributors and how to get involved.
+
+## Contributing
+
+Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request.
+
+## Security
+
+If you discover a vulnerability, please do not publish it publicly. Refer to [SECURITY.md](SECURITY.md) for our security reporting policy.

strokemap-0.1.0/src/strokemap.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+AUTHORS.md
+LICENSE
+README.md
+pyproject.toml
+src/strokemap/__init__.py
+src/strokemap/cli.py
+src/strokemap/generator.py
+src/strokemap/pdf_generator.py
+src/strokemap.egg-info/PKG-INFO
+src/strokemap.egg-info/SOURCES.txt
+src/strokemap.egg-info/dependency_links.txt
+src/strokemap.egg-info/entry_points.txt
+src/strokemap.egg-info/requires.txt
+src/strokemap.egg-info/top_level.txt
+tests/test_generator.py

strokemap-0.1.0/src/strokemap.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

strokemap-0.1.0/src/strokemap.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+strokemap = strokemap.cli:main

strokemap-0.1.0/src/strokemap.egg-info/requires.txt

@@ -0,0 +1,12 @@
+numpy
+pillow
+opencv-python
+scikit-learn
+reportlab
+scikit-image
+
+[dev]
+pytest>=7.0
+pytest-cov
+pre-commit
+ruff

strokemap-0.1.0/src/strokemap.egg-info/top_level.txt

@@ -0,0 +1 @@
+strokemap

strokemap-0.1.0/tests/test_generator.py

@@ -0,0 +1,107 @@
+"""
+Unit and integration tests for strokemap.generator.
+
+The Lenna (Lena) standard test image (512×512) is used as the canonical sample input.
+Source: USC SIPI Image Database – http://sipi.usc.edu/database/
+Image:  assets/lenna.png
+"""
+
+from pathlib import Path
+
+import numpy as np
+import pytest
+
+from strokemap.generator import PaintByNumbersGenerator
+
+# Path to the canonical test asset – lives in tests/assets/
+ASSETS_DIR = Path(__file__).parent / "assets"
+LENNA_PATH = ASSETS_DIR / "lenna.png"
+
+
+# ---------------------------------------------------------------------------
+# Fixtures
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="module")
+def lenna_rgb():
+    """Load Lenna once per test module."""
+    gen = PaintByNumbersGenerator()
+    return gen.load_image(str(LENNA_PATH))
+
+
+@pytest.fixture(scope="module")
+def generator_medium():
+    return PaintByNumbersGenerator(difficulty="medium")
+
+
+# ---------------------------------------------------------------------------
+# Initialisation tests
+# ---------------------------------------------------------------------------
+
+
+class TestPaintByNumbersGeneratorInit:
+    """Tests for correct initialization of PaintByNumbersGenerator."""
+
+    def test_default_difficulty_is_medium(self):
+        gen = PaintByNumbersGenerator()
+        assert gen.difficulty == "medium"
+
+    @pytest.mark.parametrize("difficulty", ["easy", "medium", "hard"])
+    def test_valid_difficulties_accepted(self, difficulty):
+        gen = PaintByNumbersGenerator(difficulty=difficulty)
+        assert gen.difficulty == difficulty
+
+    def test_slic_params_set_for_medium(self):
+        gen = PaintByNumbersGenerator(difficulty="medium")
+        assert gen.n_segments_base > 0
+        assert gen.slic_compactness > 0
+        assert gen.slic_sigma > 0
+
+    def test_slic_params_set_for_easy(self):
+        gen = PaintByNumbersGenerator(difficulty="easy")
+        gen_medium = PaintByNumbersGenerator(difficulty="medium")
+        # Easy should produce fewer superpixels (simpler output)
+        assert gen.n_segments_base < gen_medium.n_segments_base
+
+    def test_slic_params_set_for_hard(self):
+        gen = PaintByNumbersGenerator(difficulty="hard")
+        gen_medium = PaintByNumbersGenerator(difficulty="medium")
+        # Hard should produce more superpixels (more detailed output)
+        assert gen.n_segments_base > gen_medium.n_segments_base
+
+
+# ---------------------------------------------------------------------------
+# load_image tests
+# ---------------------------------------------------------------------------
+
+
+class TestLoadImage:
+    def test_lenna_loads_correctly(self, lenna_rgb):
+        assert lenna_rgb.shape == (512, 512, 3)
+        assert lenna_rgb.dtype == np.uint8
+
+    def test_raises_on_missing_file(self):
+        gen = PaintByNumbersGenerator()
+        with pytest.raises(FileNotFoundError):
+            gen.load_image("does_not_exist.jpg")
+
+
+# ---------------------------------------------------------------------------
+# preprocess_image tests
+# ---------------------------------------------------------------------------
+
+
+class TestPreprocessImage:
+    def test_returns_same_shape(self, lenna_rgb, generator_medium):
+        result = generator_medium.preprocess_image(lenna_rgb)
+        assert result.shape == lenna_rgb.shape
+
+    def test_returns_uint8(self, lenna_rgb, generator_medium):
+        result = generator_medium.preprocess_image(lenna_rgb)
+        assert result.dtype == np.uint8
+
+    def test_output_differs_from_input(self, lenna_rgb, generator_medium):
+        """Median blur should change at least some pixel values."""
+        result = generator_medium.preprocess_image(lenna_rgb)
+        assert not np.array_equal(result, lenna_rgb)