adot-image-creator

adot-image-creator

Convert images to packed monochrome C arrays for dot-matrix displays, with an optional interactive bitmap editor.

Features

• Load common bitmap formats (PNG, JPG, BMP, ...) as grayscale
• Optional SVG support via cairosvg (extra dependency)
• Automatically scale and center image into target width/height
• Convert image to monochrome bytes optimized for dot-matrix displays (8-pixel pages)
• Optional interactive editor (Tkinter GUI) to fine-tune individual pixels
• Generate C-style hexadecimal dump including width/height header

Installation

From PyPI

Once published, you will be able to install the package via:

pip install adot-image-creator

To enable SVG input support, install with the svg extra:

pip install "adot-image-creator[svg]"

Command-line usage

The package exposes a console script named adot-image-creator.

adot-image-creator -i INPUT -H HEIGHT -w WIDTH [options]

Arguments:

• -i, --input – input image file (PNG, JPG, SVG, BMP, ...), required
• -H, --height – target height in pixels (1–255), required
• -w, --width – target width in pixels (1–255), required
• -t, --threshold – threshold level between white and black (0–10, default: 5)
• -s, --scale – pixel scale for interactive editor (logical pixel = s × s screen pixels, default: 4)

Example:

adot-image-creator \
  -i logo.png \
  -H 32 \
  -w 64 \
  -t 5 \
  -s 4

The tool will:

1. Load and resize the image to fit into the specified width/height.
2. Convert it to monochrome using the given threshold.
3. Optionally open a Tkinter-based editor where you can flip individual pixels.
4. Show a preview of the resulting bitmap.
5. Print a C-style hex dump to standard output, including height and width bytes.

You can redirect the output directly into a C source file, for example:

adot-image-creator -i logo.png -H 32 -w 64 > logo_bitmap.c

Library usage

The same functionality is available from Python code via the adot_image_creator package.

from adot_image_creator import (
    load_image,
    to_monochrome_bytes,
    bytes_to_bool_matrix,
    bool_matrix_to_bytes,
    interactive_edit_bitmap,
    preview_from_bytes,
    format_hexdump,
)

# Load and prepare an image
img = load_image("logo.png", width=64, height=32)

# Convert to monochrome bytes (0–10 threshold)
raw_bytes = to_monochrome_bytes(img, threshold_level=5)

# Optionally let the user tweak pixels in a small GUI editor
bitmap = bytes_to_bool_matrix(width=64, height=32, data=raw_bytes)
edited_bitmap = interactive_edit_bitmap(width=64, height=32, bitmap=bitmap, scale=4)
final_bytes = bool_matrix_to_bytes(width=64, height=32, bitmap=edited_bitmap)

# Preview result in a simple image viewer
preview_from_bytes(width=64, height=32, data=final_bytes)

# Generate C hex dump
hexdump = format_hexdump(height=32, width=64, data=final_bytes)
print(hexdump)

Dependencies

• Pillow – required for image loading and processing
• cairosvg – optional, required only when working with SVG/SVGZ input ([svg] extra)
• tkinter – optional, used only for the interactive bitmap editor (may not be available in some environments)

License

This project is distributed under a proprietary license.