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:
- Page 1 - Numbered Template: Light gray outlines with a small, centered index number in each region.
- Page 2 - Clean Outlines: Clean black outlines without any numbers, perfect for clean canvas painting.
- Page 3 - Colorized Preview: A color reference picture showing what the finished painting should look like.
- 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.
Here is an example of the generator's output using the standard Lenna test image:
| Original Image | Numbered Template | Clean Outlines | Colorized Preview |
|---|---|---|---|
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.
Ensure you have Python 3.10 or newer installed. You can install strokemap using one of the methods below:
You can install strokemap directly from PyPI:
pip install strokemapOr install it from the local source directory:
pip install .To set up a virtual environment and install dependencies for development:
# 1. Clone the repository (if not already done)
git clone https://github.com/dipinknair/strokemap.git
cd strokemap
# 2. Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
# 3. Install the package in editable mode with development dependencies
pip install -e ".[dev]"
# 4. Install pre-commit hooks for linting
pre-commit installTip
If you are using Windows, activate the virtual environment with:
.venv\Scripts\activate
The installation automatically handles the following core dependencies:
numpy: Numerical array operationspillow: Image loading and savingopencv-python: Outline detection and distance transformscikit-learn: K-Means clustering for color quantizationscikit-image: SLIC superpixel segmentationreportlab: Premium multi-page PDF generation
You can convert any image directly from your terminal:
strokemap input.jpg output.pdf --colors 20 --difficulty mediumimage_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).
You can also use the package programmatically:
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,
)- 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).
- 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.
- 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.
- Outline Extraction: Computes a pixel-wise transition grid to produce clean, single-pixel outlines.
- 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.
For additional author and maintainer details, see AUTHORS.md.
This project is maintained by the community. See CONTRIBUTORS.md for the current list of contributors and how to get involved.
Contributions are welcome! Please read CONTRIBUTING.md before opening an issue or pull request.
If you discover a vulnerability, please do not publish it publicly. Refer to SECURITY.md for our security reporting policy.