A dot matrix rendered using braille characters.

Last update: Dec 12, 2022

Related tags

Overview

⣿ 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.

Comments

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:
bug
opened by Masynchin 2
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
enhancement
opened by timfi 1
Feature: Display Abstraction
Closes #2

What's the idea?

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.

Code

from dotmatrix import BlockMatrix m = BlockMatrix(16, 8) m.rectangle((0, 0), (15, 7)) print(m.render())

Output

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

from issue

How did I accomplish this?

To implement this I added the Display protocol/abstraction which describes all methods required for setting/getting pixel values and rendering said values to some useful output. The Braille logic has been moved to such a display (at dotmatrix.displays.Braille and remains the default display type. In addition to this I've also implemented a unicode block character display at dotmatrix.displays.Block.

Code

from dotmatrix import Matrix from dotmatrix.displays import Block m = Matrix(16, 16, display=Block) m.rectangle((0, 0), (15, 15)) m.circle((7, 7), 7) print(m.render())

Output

█▀▀██▀▀▀▀▀██▀▀▀█ █▄▀ ▀▄ █ █▀ ▀▄█ █ ██ █ ██ ██ █ █ █ ▀▄▄ ▄▄▀ █ █▄▄▄▄█████▄▄▄▄▄█
opened by timfi 0
Feature: Display Abstraction and new Display-type
Closes #2

What's the idea?

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.

Code

from dotmatrix import BlockMatrix m = BlockMatrix(16, 8) m.rectangle((0, 0), (15, 7)) print(m.render())

Output

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

from issue

How did I accomplish this?

To implement this I added the Display protocol/abstraction which describes all methods required for setting/getting pixel values and rendering said values to some useful output. The Braille logic has been moved to such a display (at dotmatrix.displays.Braille and remains the default display type. In addition to this I've also implemented a unicode block character display at dotmatrix.displays.Block.

Code

from dotmatrix import Matrix from dotmatrix.displays import Block m = Matrix(16, 16, display=Block) m.rectangle((0, 0), (15, 15)) m.circle((7, 7), 7) print(m.render())

Output

█▀▀██▀▀▀▀▀██▀▀▀█ █▄▀ ▀▄ █ █▀ ▀▄█ █ ██ █ ██ ██ █ █ █ ▀▄▄ ▄▄▀ █ █▄▄▄▄█████▄▄▄▄▄█
enhancement
opened by timfi 0

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

enhancement

opened by timfi 0

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].
enhancement
opened by timfi 0

Releases(v0.2.0)

v0.2.0(Aug 22, 2021)
Adds Display protocol to describe the low level drawing interface.

Adds 3 implementations of the Display protocol

display.Braille: as the name implies, this is existing "display mode"

display.Block: renders using unicode block charaters

display.Unit: renders using two given charaters for each state (0 vs. 1)

Source code(tar.gz)
Source code(zip)
v0.1.1(Aug 16, 2021)

Added some badges to the readme!
Source code(tar.gz)
Source code(zip)
v0.1.0(Aug 16, 2021)

Initial Alpha Release! 🥳

Presenting a python library for drawing things using Braille characters.

Note that this release has been janked from PyPI due to ambiguous license declarations!
Source code(tar.gz)
Source code(zip)

Owner

Tim Fischer

GitHub Repository https://pypi.org/project/dotmatrix/

A ULauncher/Albert extension that supports currency, units and date time conversion, as well as a calculator that supports complex numbers and functions.

Ulauncher/Albert Calculate Anything Ulauncher/Albert Calculate Anything is an extension for Ulauncher and Albert to calculate things like currency, ti