Python3 library for multimedia functions at the command terminal

Overview

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:

Demonstration of terminedia.print

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

Messy screenshot with current capabilities Graph plot output example Image rendering and big-text

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

Comments
  • Add support for 1/6 block characters

    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.

    enhancement 
    opened by RebeccaRGB 7
  • [Question] How to limit size of image?

    [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 
    
    Screen Shot 2021-08-20 at 8 08 15 PM

    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!

    bug 
    opened by paw-lu 4
  • `terminedia-plot` output garbled for almost every function except the default example

    `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
    

    image

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

    opened by vytas7 3
  • `redirected stdin is pseudofile, has no fileno()`

    `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:

    https://github.com/jsbueno/terminedia/blob/96f44a67dd97acfd49062c7be30057c6767b2de6/terminedia/terminal.py#L92

    opened by paw-lu 3
  • `terminedia-plot` wrong axis position and selection

    `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: image 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: image

    opened by vytas7 2
  • Fix display and flow of larger than 1-unit width characters

    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
    enhancement 
    opened by jsbueno 2
  • Double-width character printing do not trigger Marks at a position if it is skipped as character-continuation

    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.
    opened by jsbueno 1
  • [FORMATTING] Applied black to a few files

    [FORMATTING] Applied black to a few files

    I chose not to apply black to all the lib, bc the changes would be huge. So I took a few files, applied black, checked the changes and made some tests with (and ran some examples).

    opened by chicao 1
  • Gradient transformers

    Gradient transformers

    #pybr2020 #sprints

    This was made in the Sprinting session of the PythonBrasi 2020 confence - Features developed in an hours long pair-programming session with Celestino Gomes - @tinogomes

    Add features to GradientTransforms and Gradients - making them more flexible and easier to use.

    opened by jsbueno 0
  • Text features

    Text features

    First stage of new Text features -

    This branch so far had:

    - Refactor 'text.py' into directory:[V]
        - separate 'font' code into text/fonts.py [V]
        - text_planes/big text into text/planes.py (V)
        - file with text utilities for parsing/rendering text:
            - split string into units containing a single grapheme, by grouping "combining characters" together (V)
            - Refactor code to have a core to be used by  backend.print, screen.print, text.at, shape.print [V]
    - Make assignment of string to shape or text area cell spread the text across as many cells as needed:[V]
        - correctly detect combining characters so that combined characters live on the same cell (V)
    - create markup language for embedding context changing directives inside a single string:[V]
        - make it usable by assignment, `text[x].print` and `at` methods
        - BUG: when rendering spaces from text-planes, attributes (like background) are not updated (V):
                - fixed by sprite transparency handling implementation.[V]
        - Implement a way to "stream" rich text inside these text-plane containers [WIP]:
            - TM.text.style.StyledSequence is the class used for that [v]
            - Streamed text should allow marks for changing style (color, bg, effects, direction, position)[v]
                - accept tokens in embedded square-brackets in the string ex.: "abc[color:red]def[V]
                - Accept absolute/relative movement with "[+x,+y]" tokens embedded in the string (and work as "portals")[V]
                - allow for 'pop last parameter of this type' tokens ([/color], [/effects])[V]
                - allow for default colors with [color:default] (V) (but check default-color bug)
            - Allow a call to MLToken.parse to be passed a transformers-mapping, and us it as a source for
                    transformers objects in the  markup [transformer:...] elements [wip]
    
    - create aliased string names for the text[...] text planes [V]
    - Add tests to terminedia-planes [WIP]:
        - Avoid creating a new "Text" instance on each text-plane access![V]
        - Tests for styling bases classes in progress - testing attribute changing and position
    
    opened by jsbueno 0
  • Braille resolution refactor

    Braille resolution refactor

    Refactor sub-pixel logic, hard coded to 1/4 block chars, and add Braille characters (which allow 2x4 subpixels per block) as an alternative high-resolution plane.

    St

    opened by jsbueno 0
  • Include Unicode transform effects for varios 'Mathematical *

    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
    opened by jsbueno 0
  • Not usable on Windows due to `fcntl`

    Not usable on Windows due to `fcntl`

    opened by paw-lu 2
  • Performance game changing refactor

    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)
    opened by jsbueno 0
  • Processing-like API

    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

    opened by berinhard 0
  • Fix keyboard handling in Windows terminal

    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.
    windows 
    opened by jsbueno 0
  • Fix Colors in Windows

    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.

    windows 
    opened by jsbueno 0
Releases(0.4.2)
  • 0.4.2(Sep 24, 2021)

  • 0.4.1(Jul 25, 2021)

    Hundreds of new features, including text styling using a markup system, mouse events, an incipient widget system, unicode 13 sextant character block (1/6 block) resolution, full-color 1/2 block resolution, and more... (check DONE.txt and git log) terminedia-0.4.1.tar.gz Pending: documentation.

    Source code(tar.gz)
    Source code(zip)
Owner
Joao S. O. Bueno
Joao S. O. Bueno
keep your machine's shell history synchronize

SyncShell Yet another tool for laziness Keep your machine's shell history synchronize Get SyncShell Currently, SyncShell is just available on PyPi and

Masoud Ghorbani 53 Dec 12, 2022
A curated list of awesome things related to Textual

Awesome Textual | A curated list of awesome things related to Textual. Textual is a TUI (Text User Interface) framework for Python inspired by modern

Marcelo Trylesinski 5 May 08, 2022
Easily turn single threaded command line applications into a fast, multi-threaded application with CIDR and glob support.

Easily turn single threaded command line applications into a fast, multi-threaded application with CIDR and glob support.

Michael Skelton 1k Jan 07, 2023
Standalone script written in Python 3 for generating Reverse Shell one liner snippets and handles the communication between target and client using custom Netcat binaries

Standalone script written in Python 3 for generating Reverse Shell one liner snippets and handles the communication between target and client using custom Netcat binaries. It automates the boring stu

Yash Bhardwaj 3 Sep 27, 2022
Albert launcher extension for converting units of length, mass, speed, temperature, time, current, luminosity, printing measurements, molecular substance, and more

unit-converter-albert-ext Extension for converting units of length, mass, speed, temperature, time, current, luminosity, printing measurements, molecu

Jonah Lawrence 2 Jan 13, 2022
Proman is a simple tool for managing projects through cli.

proman proman is a project manager. It helps you manage your projects from a terminal. The features are listed below. Installation Step 1: Download or

Arjun Somvanshi 2 Dec 06, 2021
A powerful Minecraft command library.

Mecha A powerful Minecraft command library. from mecha import Mecha

32 Dec 10, 2022
A minimal todo list for your terminal.

todo A minimal todo list for your terminal. Installation Run the following command. pip install git+https://github.com/piero-vic/todo.git Usage todo

Piero Lescano 7 Aug 08, 2022
Fetch is use to get information about anything on the shell using Wikipedia.

Fetch Search wikipedia article on command line [Why This?] [Support the Project] [Installation] [Configuration] Why this? Fetch helps you to quickly l

Yash Singh 340 Dec 18, 2022
A Terminal Client for MySQL with AutoCompletion and Syntax Highlighting.

mycli A command line client for MySQL that can do auto-completion and syntax highlighting. HomePage: http://mycli.net Documentation: http://mycli.net/

dbcli 10.7k Jan 07, 2023
split-manga-pages: a command line utility written in Python that converts your double-page layout manga to single-page layout.

split-manga-pages split-manga-pages is a command line utility written in Python that converts your double-page layout manga (or any images in double p

Christoffer Aakre 3 May 24, 2022
pyGinit is a command line tools that help you to initialize your current project a local git repo and remote repo

pyGinit pyGinit is a command line tools that help you to initialize your current project a local git repo and remote repo Requirements Requirements be

AlphaBeta 15 Feb 26, 2022
Microsoft Azure CLI - Azure Command-Line Interface

A great cloud needs great tools; we're excited to introduce Azure CLI, our next generation multi-platform command line experience for Azure.

Microsoft Azure 3.4k Dec 30, 2022
slipit is a command line utility for creating archives with path traversal elements.

slipit is a command line utility for creating archives with path traversal elements. It is basically a successor of the famous evilarc utility with an extended feature set and improved base functiona

usd AG 35 Dec 23, 2022
A Command Line Calculator With Python

CalculadoraPY Usando no Termux apt install python3 apt install git pip3 install termcolor git clone https://github.com/kayke981/CalculadoraPY.git

kayake 5 Jan 30, 2022
Multifunctional library for creating progress bars.

👋 Content Installation Using github Using pypi Quickstart Flags Useful links Documentation Pypi Changelog TODO Contributing FAQ Bar structure ⚙️ Inst

DenyS 27 Jan 01, 2023
A lightweight terminal-based password manager coded with Python using SQLCipher for SQLite database encryption.

password-manager A lightweight terminal-based password manager coded with Python using SQLCipher for SQLite database encryption. Screenshot Pre-requis

Leonardo de Araujo 15 Oct 15, 2022
A Command Line Error Parser Built using Python.

"Stalk Overflow with debuggy" Error Parser Everything is done in Python so it's extremely easy to install and use. Supports Python 3. Debuggy is used

Derhnyel 22 Nov 10, 2022
Simple command line tool to train and deploy your machine learning models with AWS SageMaker

metamaker Simple command line tool to train and deploy your machine learning models with AWS SageMaker Features metamaker enables you to: Build a dock

Yasuhiro Yamaguchi 5 Jan 09, 2022
Quickly open any path on your terminal window in your $EDITOR of choice!

Tmux fpp Plugin wrapper around Facebook PathPicker. Quickly open any path on your terminal window in your $EDITOR of choice! Demo Dependencies fpp - F

257 Dec 28, 2022