timfi/dotmatrix

A dot matrix rendered using braille characters.

⣿ dotmatrix

A dot matrix rendered using braille characters.

Description

This library provides class called Matrix which represents a dot matrix that can be rendered to a string of Braille characters. In addition the class also provides some usefull functions for drawing all kinds of things onto said matrix.

A word on fonts...

This heavily relies on the font you want display the resulting characters with. Some "monospace" fonts/systems dot not treat all characters as having the same width! In particular this affects the blank braille character (this: ⠀). The system that causes the most problems seems to be Windows while both mac OS and your average linux distribution don't screw it up. If you are having problems with the images in this readme you can have a look at the images included in the spoilers.

Install

Use can install this library from PyPI:

pip install dotmatrix

Example

Code

from dotmatrix import Matrix

m = Matrix(64, 64)

m.rectangle((0, 0), (63, 63))
m.circle((31, 31), 31)

print(m.render())

Output

⡏⠉⠉⠉⠉⠉⠉⠉⢉⡩⠭⠛⠛⠉⠉⠉⠉⠉⠙⠛⠫⠭⣉⠉⠉⠉⠉⠉⠉⠉⠉⢹
⡇⠀⠀⠀⠀⢀⡠⠊⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠢⣀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⢀⠔⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠑⢄⠀⠀⠀⢸
⡇⠀⡠⠊⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠢⡀⠀⢸
⡇⡰⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠱⡀⢸
⣧⠃⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣⢸
⡟⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⣼
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣿
⣷⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢰⢹
⡏⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡎⢸
⡇⠘⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡜⠀⢸
⡇⠀⠈⢢⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⠊⠀⠀⢸
⡇⠀⠀⠀⠑⢄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⠔⠁⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠈⠢⢄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⣀⠤⠊⠀⠀⠀⠀⠀⠀⢸
⣇⣀⣀⣀⣀⣀⣀⣀⣀⣈⣉⣒⣒⣤⣤⣤⣤⣤⣔⣒⣊⣉⣀⣀⣀⣀⣀⣀⣀⣀⣀⣸

image

This is what it should look like:

Drawing functions

As of now this library contains the following drawing functions:

• scatter – Draws some points.
• iscatter – Draws some points (from an iterator).
• show – Draws an object implementing the Dotted protocol.
• line – Draws a line.
• chain – Draws a chain of segments.
• polygon – Draws a polygon.
• rectangle – Draws an axis aligned rectangle. (from two opposing corners)
• cricle – Draws a circle.
• ellipse – Draws an axis aligned ellipse.
• curve – Draws a Bézier curve.
• plot – Plots a series of XY-coordinates. (matplotlib.pyplot style)
• plotf – Plots a function.

Dotted protocol

---

class Dotted(Protocol):
    """An object that can be drawn on a Matrix."""

    def __dots__(self) -> Iterable[Point]:
        """Generate the pixel positions representing this object.

        :return: pixels to draw
        :rtype: Iterable[Point]
        """

---

⚠️  The origin of the coordinate system, i.e. (0, 0), is at the top left corner!

Does it need to be Braille characters?

No, no it does not. It's just the default; you are free to choose how you want to render things. To facilitate this any given Matrix object internally makes use of an object implementing the Display protocol. For example this library implements, next to the Braille displays, some more display like Block or Unit.

Display protocol

---

class Display(Protocol[V, O]):
    """An object that can be used as a matrix display."""

    width: int
    height: int
    default_brush: V

    def __init__(
        self, width: int, height: int, *, default_brush: Union[V, UseDefault]
    ) -> None:
        """Initialize a matrix object.

        :param width: width of the matrix
        :type width: int
        :param height: height of the matrix
        :type height: int
        """

    def render(self) -> O:
        """Render the current matrix state.

        :return: render result
        :rtype: O
        """

    def __getitem__(self, pos: Point) -> V:
        """Get the value of a pixel.

        :param pos: position of pixel to get
        :type pos: Point
        :raises IndexError: requested pixel is out of the bounds of the matrix
        :return: state of the pixel
        :rtype: bool
        """

    def __setitem__(self, pos: Point, val: V):
        """Set the value of a pixel.

        :param pos: position of the pixel to set
        :type pos: Point
        :param val: the value to set the pixel to
        :type val: bool
        :raises IndexError: requested pixel is out of the bounds of the matrix
        """

---

Block display

---

Code

from dotmatrix import Matrix
from dotmatrix.displays import Block

# Using a different display is as simple as passing it
# into the display-argument of the initializer.
m = Matrix(16, 16, display=Block)

m.rectangle((0, 0), (15, 15))
m.circle((7, 7), 7)

print(m.render())

Output

█▀▀██▀▀▀▀▀██▀▀▀█
█▄▀         ▀▄ █
█▀           ▀▄█
█             ██
█             ██
██           █ █
█ ▀▄▄     ▄▄▀  █
█▄▄▄▄█████▄▄▄▄▄█

---

Unit display

---

Code

from dotmatrix import Matrix
from dotmatrix.displays import Block

# The following isn't required for using the Unit display.
# It's just here to demonstrate that you "pre-instantiate"
# a display and construct a Matrix object from it using
# Matrix.from_display.
d = Unit(16, 16, chars=["  ", "##"])
m = Matrix.from_display(d)

m.curve((0, 0), (15, 0), (0, 15), (15, 15))

print(m.render())

Output

########
        ####
            ##
              ##
              ##
              ##
              ##
              ##
                ##
                ##
                ##
                ##
                ##
                  ##
                    ##
                      ##########

---

More examples

Bézier flower

---

Code

from dotmatrix import Matrix

m = Matrix(64, 64)

m.curve((0, 0), (63, 0), (0, 63), (63, 63))
m.curve((0, 0), (0, 63), (63, 0), (63, 63))
m.curve((63, 0), (0, 0), (63, 63), (0, 63))
m.curve((63, 0), (63, 63), (0, 0), (0, 63))

print(m.render())

Output

⡏⠉⠉⠉⠉⠒⠒⠤⠤⣀⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⣀⠤⠤⠒⠒⠉⠉⠉⠉⢹
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠒⢄⠀⠀⠀⠀⠀⠀⡠⠒⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⢣⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠑⡄⠀⠀⢠⠊⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡜
⠘⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⡆⢰⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⠃
⠀⢣⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢱⡎⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡜⠀
⠀⠈⢢⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡔⠁⠀
⠀⠀⠀⠑⢄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡠⠊⠀⠀⠀
⠀⠀⠀⠀⠀⠉⠢⠤⢄⣀⣀⣀⣀⣀⣀⣸⣇⣀⣀⣀⣀⣀⣀⡠⠤⠔⠉⠀⠀⠀⠀⠀
⠀⠀⠀⠀⠀⣀⠤⠒⠒⠉⠉⠉⠉⠉⠉⢹⡏⠉⠉⠉⠉⠉⠉⠒⠒⠤⣀⠀⠀⠀⠀⠀
⠀⠀⠀⡠⠊⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠑⢄⠀⠀⠀
⠀⢀⠎⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠱⡀⠀
⠀⡜⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡜⢣⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣⠀
⢰⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢠⠃⠘⡄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⡆
⡜⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⡠⠃⠀⠀⠘⢄⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⢀⡠⠊⠀⠀⠀⠀⠀⠀⠑⢄⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⣇⣀⣀⣀⣀⠤⠤⠔⠒⠉⠁⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠉⠒⠢⠤⠤⣀⣀⣀⣀⣸

image

This is what it should look like:

---

Function plotting

---

Code

from dotmatrix import Matrix

m = Matrix(64, 64)

m.rectangle((0, 0), (63, 63))
m.plotf(
    lambda x: 0.005 * x ** 3,
    range(-31, 31),
    origin=(31,31),
)

print(m.render())

Output

⡏⠉⠉⠉⠉⠉⢹⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⠉⢹
⡇⠀⠀⠀⠀⠀⠀⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⢱⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠈⡆⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠸⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠱⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠱⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⠢⢄⣀⣀⣀⣀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠉⠢⡀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⢆⠀⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠈⡆⠀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠸⡀⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣⠀⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠘⡄⠀⠀⠀⠀⠀⠀⢸
⡇⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⠀⢣⠀⠀⠀⠀⠀⠀⢸
⣇⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣀⣸⣀⣀⣀⣀⣀⣀⣸

image

This is what it should look like:

---

Development

In case you want to add some code to this project your need to first make sure you have poetry installed. Afterwards you can run the following commands to get your setup up and running:

poetry install
poetry shell
pre-commit install

Due note that you will have to commit from inside the virtual environment or you need to have the dev-tools installed in your local python installation.

All PRs will be style checked with isort, pydocstyle and black as well as type checked with mypy. In addition to this all PRs should target the dev-branch and contain as many signed commits as possible (better yet only signed commits 😉 ). If you have no clue how or why to sign your commits have a look at the GitHub docs on this topic.

dotmatrix's Issues

Bug: Bad images in README

Description

As you mentioned in reddit post, pictures of matrix can be broken due to browsers "smart" behaviour. This problem is on README too

Code

Not the code, only ask for use picture in README

Output

Will add picture in "Anything else?" section as I am not certain in posting picture here

Anything else?

Example:

Feature Request: Matrix manipulation

Description

It would be nice to be able to rotate/transpose/crop/shift/etc. any give matrix.

Code

from dotmatrix import Matrix

m = Matrix(5, 5)

print("Initial")
m.polygon((0, 0), (0, 4), (4, 4))
print(m.render())

print("Transposed")
m.transpose()
print(m.render())

Output

Initial
⡗⢄⠀
⠉⠉⠁
Transposed
⠙⢍⡇
⠀⠀⠁

Anything else?

No response

Feature Request: Dithered Images

Description

An amazing feature would be the ability to render a given image onto a dotmatrix. And to make things prettier some sort of dithering, be it Floyd-Steinberg or Atkinson or something else entirely, would also be nice.

Code

import dotmatrix as dm

m = dm.Matrix(256, 256)

m.blit(
    "path/to/my/image",
    area=((63, 63), (191, 191)),  # The area to blit the image to.
    dither=dm.dither.Floyd        # The dithering algorithm to use.
)

print(m.render())

or

import dotmatrix as dm
from PIL import Image


m = dm.Matrix(256, 256)
img = Image.open("path/to/my/image")

m.blit(
    img,
    area=((63, 63), (191, 191)),  # The area to blit the image to.
    dither=dm.dither.Floyd        # The dithering algorithm to use.
)

print(m.render())

Output

No response

Anything else?

Example: DotArt by Garrett Albright

The latter example usage would require pillow as dependency. Thus it might be sensible to block this feature behind an "import guard" and add pillow as an extra-install-option, àla dotmatrix[images].

Feature Request: Different "Character sets"

Description

One "nice to have" feature could be the addition of matrices that use other character sets for rendering. One nice set could be ▖▗▘▝▀▄▌▐▚▞▙▛▜▟█, i.e. a 2x2 grid per character.

This could be accomplished by extracting all the character set dependent code into a subclass and leave an ABC that makes use of __getitem__, __setitem__, __init__, and render provided by the subclass.

Code

from dotmatrix import BlockMatrix

m = BlockMatrix(16, 8)

m.rectangle((0, 0), (15, 7))

print(m.render())

Output

▛▀▀▀▀▀▀▜
▌      ▐
▌      ▐
▌      ▐
▌      ▐
▌      ▐
▌      ▐
▙▄▄▄▄▄▄▟

Anything else?

No response