jsbueno / terminedia

Python3 library for multimedia functions at the command terminal

TERMINEDIA

This is a Python library allowing using a text-terminal as a low-resolution graphics output, along with keyboard realtime reading, and a couple utilities enough to enable using a text terminal to run simple 2D games or simply rich terminal apps.

The "noveau" factor is that it uses Unicode quarter-character block combinations to effectivelly enable 1/4 character "pixels" in the terminal. It also makes use of 24bit "true" color for text, not limiting itself to the 80's 8 color palette for the terminal.

The development version allows loading image files and displaying those as colored block chars on the terminal, several terminal-font text effects, and rendering big-text, 4 or 8 characters tall, by rendering built-in fonts as images using block characters.

It is designed as a library, providing a discoverable and easy to use API for drawing, and upon install a few example scripts will be imediately available as stand-alone scripts with the "terminedia-" prefix.

The idea is to keep this as a lightweight install - with as little dependencies as possible.

Usage

Although targeted for programatic use, after install a few example programs exercising the library capabilities are made available in the active Python environment. Try one of several "terminedia-xxxxx" scripts installed, such as "terminedia-image" and "terminedia-snake"

Some of the features are as easy to use as the print function from Python itself:

Other, like the drawing API which emulates pixels with unicode block characters require a couple more calls:

Documentation

Check the in progress documentation at: https://terminedia.readthedocs.io/en/latest/

(nb. that documentation is currently for the 0.2 version, available from pypi. The project's capabilities evolved far beyond whats is in there, but docs are still missing - the "TODO.txt" file lists implemented features or fixes (marked with a "V") and a loose roadmap. Although for useage and documentation one has to rely on the doc-strings)

Also, the examples folder have concrete snippets and some stress-testing code. The examples were moved into the main package code, and granted stand-alone scripts status when the package is pip-installed.

After install, try calling any of the "terminedia-" scripts made available to check the output.

Although incipient in options, some of these example scripts can work as command line tools. For example terminedia-image <image_file> will downscale and display an image file in the terminal.

Note that the default pip install won't bring PIL, which results in limited image support - use pip install terminedia[images], or simply install PIL directly with pip install pillow, to be able to load arbitrary image files.

Compatibility

Preliminary Windows support - by using the Colorama Python package, with proper fonts configuration on the terminal, it is possible to experiment most of terminedia´s capabilities (the terminedia-snake example works). There is still work to be done, but for a better experience under Windows install the CMDER console emulator and the UNSCII fonts for rendering pseudographics (links in the FRIENDS.md file)

On Linux and other posix systems, Terminedia relies on ANSI scape sequences for all terminal manipulation. It should work in most Linux and Mac OS terminal applications (including non-X11, "native" terminals on Linux)

The output result will vary according to the terminal and font used - a nice experience can be achieved with the "Terminus" font, specially if one is using the Braille characters for drawing.

There is also an HTML backend that can output programatically created ASCII art to an HTML file, formatted with mono-spaced fonts inside a div element. The "terminedia-image" example program makes use of this feature.

License

Terminedia is licensed under GNU's LGPL 3.0 or later, meaning you are free to use it in whatver project you want, comercial or not, private or not - you are only required to contribute back any enhancements you make to this library itself. For details, please read acompanining "LICENSE" file.

terminedia's Issues

`terminedia-plot` output garbled for almost every function except the default example

terminedia-plot without any parameters works just fine, as in the demo screenshot.

However, trying to provide any other function results a semi garbled output with many fragments of escape characters:

$ terminedia-plot --func x

I've used the latest version this repo: pip install git+https://github.com/jsbueno/terminedia.

Double-width character printing do not trigger Marks at a position if it is skipped as character-continuation

When printing text with the text-planes mechanism, one can embed a Mark (an object similiar to an HTML tag to dictate attributes to the text from that point on), fixed on a TextPlane position - for example, doing:

screen.text[1].marks[5,0] = TM.Mark(attribute{"foreground"}: "red') and then rendering some text there with screen.text[1][0,0] = "ABCDEFGH" - will cause the letters EFGH (col 5 and onward) to appear red.
However if the characters being printed are double-width - and column 5 ends up on the continuation of a character that started on the position (4, 0) -, the mark at (5, 0) is never "seem" by the rendering mechanim.

Fixing strategy:

• Anottate in an instance attribute on terminedia.text.style.StyledSequence when a double-character was printed (it will be "seen" on the .render method - right now at line 309.) -
• Consume this attribute when checking for marks for the next character: pass it as an extra parameter to MarkMap.get_full done in the ._process_to method (the MarkMap instance is the .marks attribute in the StyledSequence instance)
• on MarkMap.get_full include the "skipped location" in the mark-search, and return it in the return.

`redirected stdin is pseudofile, has no fileno()`

When trying to test this libary via pytest, an exception is raised: redirected stdin is pseudofile, has no fileno(). This is due to this line:

terminedia/terminedia/terminal.py

Line 92 in 96f44a6

self.fd = sys.stdin.fileno()

Performance game changing refactor

I just outline thse ideas in text - for steps that could take the project to actually feature "animation speed" for most effects.
These were also commited in the "TODO.txt" file:

• BACKENDS:

  • "The One" optmization: (maybe sprint around Christmas 2020)
    • Benchmark complex rendering (with 2 more levels of sprites and 4+ levels of transformers + text effects / frame)
    • add consistent benchmarking as a script in tools
    • then proceed to revamp everything:
      • refactor as many pixel by pixel function calls to a way that can be pre-set to a retangular area and then used as a generator:
        • Rendering backend: should get a "shape", a rect and a file stream, and usr
          a method on the shape to setup pixel yielding for that area, and use a single
          "for" block for rendering.
        • (final backend rendering method should be contained in a single function, with no extra calls)
        • shapes:
          • have a method to setup an area, that will, in turn, setup areas in it's text planes, and sprites
          • use generator semantics with "send" to the sprites (so that transformers with any kind of transparency
            can have their data).
          • optimize storage to use arrays instead of lists. (no need to numpy - just arrays of 4 bytes and
            a fast way to interpret those as a single UTF-32 unicode codepoint string)
        • transformers:
          • benchmark to check if this is worth the effort:
          • (optional) have a decorator that could work on bytecode level to upgrade a normal function-based transformer
            to a generator:
            - insert a pos, pixel, source, ... = yield mydata; char, foreground, background, effects = pixel line
            at the start of the bytecode;
            - replace all "return" values for a "bytecode jump" to the line with the "yield".
            - since the transformer-generator will be garbage colector once its area-blitting is over,
            there is no problem that such a transformer becomes an "infinite size" generator
        • text-planes and text-style:
          • have blitted text-styles in teh text-plane have the combined (text-plane positional + string positional) Marks in place,
            ready to work as a generator for all "full pixels". Updating the shape will trigger the rendering for text planes
            • it is possible that this is hard to do for text-planes of more than one block per character (big-text):
              if that is the case, just leave big-text rendering as eager (as they work today(, and document that.
        • subpixel:
          • benchmark to csheck if "de-normalizing" the super-refactored code in there would make some difference.
          • (current code is super-geekie but requires 3-level calls to set/reset each subpixel)
          • if keeping elegance is a must, evolve a script in tools that will "glue together" the denormalized code inline.
          • (or check pymacro)
  • ^^ these optimizations should bring frame performance to a more reasonable value (10s of FPS expected. Currently 5
    FPS is something just achiaveable for the most simple of renderings, just affecting an area of the screen).
    At this point the bottleneck
    should be the terminal emulator program (then check for Kitty and other terminals that intend to be fast)

Add support for 1/6 block characters

Unicode 13.0 added 1/6 block characters at 1FB00-1FB3B in the Characters for Legacy Computing block. This would be a nice complement to the 1/4, 1/2, and 1/8 (Braille) modes.

`terminedia-plot` wrong axis position and selection

It seems that terminedia-plot plots points at a wrong y coordinate.

For instance, terminedia-plot --func x yields:

From the graph, I'm getting an impression that f(0.01) ≈ 2, which is obviously not even remotely true for f(x) = x.

(One can also see a minor cosmetic issue, a data point seems to be missing on the graph.)

terminedia-plot --func x*x seems to provide a roughly correct data point for (0, 0), but the choice for y range seems to be quite odd:

Add HSV Path to color gradients

Terminedia color gradients are pretty much stand-alone "abstract" usable gradients - they can be enriched to be able to better describe gradients.

A low hanging fruit is to have HSV color-model gradients, instead of just RGB color transitions.

GIMP has those - as well as other features that can be incorporated, such as using different color transition curves per segment, instead of just linear color transitions.

Include Unicode transform effects for varios 'Mathematical *" unicode symbols

Effects currently cnatransfoprm ASCII to "mathematical sans-serif bold *" and "mathematical double-struck"
however there are all these letter-families for mathematical symbols in unicode:

{'MATHEMATICAL BOLD': ['CAPITAL', 'SMALL', 'DIGIT'],
'MATHEMATICAL ITALIC': ['CAPITAL', 'SMALL'],
'MATHEMATICAL BOLD ITALIC': ['CAPITAL', 'SMALL'],
'MATHEMATICAL SCRIPT': ['SMALL'],
'MATHEMATICAL BOLD SCRIPT': ['CAPITAL', 'SMALL'],
'MATHEMATICAL FRAKTUR': ['CAPITAL', 'SMALL'],
'MATHEMATICAL DOUBLE-STRUCK': ['CAPITAL', 'SMALL', 'DIGIT'],
'MATHEMATICAL BOLD FRAKTUR': ['CAPITAL', 'SMALL'],
'MATHEMATICAL SANS-SERIF': ['CAPITAL', 'SMALL', 'DIGIT'],
'MATHEMATICAL SANS-SERIF BOLD': ['CAPITAL', 'SMALL', 'DIGIT'],
'MATHEMATICAL SANS-SERIF ITALIC': ['CAPITAL', 'SMALL'],
'MATHEMATICAL SANS-SERIF BOLD ITALIC': ['CAPITAL', 'SMALL'],
'MATHEMATICAL MONOSPACE': ['CAPITAL', 'SMALL', 'DIGIT']}

more:

• LATIN LETTER SMALL CAPITAL

Not usable on Windows due to `fcntl`

This is mostly an FYI due to #18 and #17 being open.

The fcntl module is apparently unsuported on Windows. Attempting to run raises:

ModuleNotFoundError: No module named 'fcntl'

Didn't know this myself until some Windows tests were failing..

Sphinx documentation generation not working

The refactoring of the project from a single Python file into a full module broke sphinx -
documentation content is partial, despite almost all classes and functions having
a good enough docstring with markup for document generation

Fix display and flow of larger than 1-unit width characters

When rendering rich-text:

• correctly detect if final transformed character takes more than 1 cell width after applying effects, and correctly use 2 cells for character [WIP]
  - retrieve last-character width after calling Shape.__setitem__
  - check that last-character width works with multiple-character grapheme
  - allow Shape.__setitem__ to set character to the left of given position if a special attribute is set in the context (and maybe if direction==Right)
  - Double check and maybe extend role of "Continuation" sentinel character code (used in Shape):
  - Does it make sense for "Continuation" to indicate the "come from" direction, and allow continuation
  for custom double-height characters?
  - implement a dry-run extents call in TextPlane

Processing-like API

A nice to have feature would be an API closer to Processing's one. Maybe we could port pyde scripts to terminedia or something similar.

References

• JS-python mapping from pyp5js;
• p5.js refence in yaml format;
• processing.py list of keywords;

[Question] How to limit size of image?

Trying to use this library to convert images to block characters. So far it's working great.

One point of confusion for me is how to control the size of the output. For context, I'm trying to preserve the ratio of the image, but constrain either its height or width so that it can fit within an arbitrary space.

Here I attempt—and fail—to read in an image and constrain its output to 30 characters in width.

import io

import terminedia
from PIL import Image

screen = terminedia.Screen(backend="ANSI")
resolution = "square"
size = terminedia.V2(x=30, y=30)

image = Image.open("Ent_Steven-Universe_SOCIAL.jpeg")
img = terminedia.shape(
    image,
    size=size,
    promote=True,
    resolution=resolution,
)
output = io.StringIO()
img.render(output=output, backend="ANSI")

print(output.getvalue())
print("-" * 30)  # Ruler to visualize 30 units across 

It renders perfectly, but is wider than 30 characters.

I'm trying to understand:

1. What does the size argument actually do? The resulting image is not 30x30.
2. What's the best way to accomplish my goal—preserving the original aspect ratio of an image while restraining the height and the width to be within a certain number of characters?

---

(Again) thanks for the project!

Fix keyboard handling in Windows terminal

Keybard handling works fine in cmd and cmder, but not on the new Windows terminal - (in an investigation a while back, I traced it to some behavior on the terminal I thought would be reversed soon - it did not happen).

• Check if the terminal app is windows terminal, and handle keyboard properly.

Fix Colors in Windows

Current terminal backend uses the "39 SGR" Ansi sequence for 24bit color on the terminal. However, colorama wll simply strip these sequences off, resulting in no color capabilities in windows - even though windows terminal suppots 24bit color, and "cmder" supports the color sequences (and rounds the colors down to the 16 more used values).

Find a way to detect the terminal app under windows, and only trigger "colorama" if on "cmd" - the other apps work with plainANSI sequences.
Round colors down to the 16 "well known codes" if on cmd or cmder.