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
Python3 command-line tool for the inference of Boolean rules and pathway analysis on omics data

BONITA-Python3 BONITA was originally written in Python 2 and tested with Python 2-compatible packages. This version of the packages ports BONITA to Py

null 1 Dec 22, 2021
Bear-Shell is a shell based in the terminal or command prompt.

Bear-Shell is a shell based in the terminal or command prompt. You can navigate files, run python files, create files via the BearUtils text editor, and a lot more coming up!

MichaelBear 6 Dec 25, 2021
Bear-Shell is a shell based in the terminal or command prompt.

Bear-Shell is a shell based in the terminal or command prompt. You can navigate files, run python files, create files via the BearUtils text editor, and a lot more coming up!

MichaelBear 6 Dec 25, 2021
WA Terminal is a CLI application that allows us to login and send message with WhatsApp with a single command.

WA Terminal is a CLI application that allows us to login and send message with WhatsApp with a single command.

Aziz Fikri 15 Apr 15, 2022
A super simple terminal command shortener 🐟

pcmd A super simple terminal command shortener ?? Source code : https://github.com/j0fiN/pcmd Documentation : https://j0fin.github.io/pcmd About Durin

null 9 Mar 2, 2022
A simple command line chat app to communicate via the terminal.

A simple command line chat app to communicate via the terminal. I'm new to networking so sorry if some of my terminology or code is messed up.

PotNoodle 1 Oct 26, 2021
CLTools provides various tools and command to use in the terminal.

CLTools provides various tools and command to use in the terminal. As of date, CLTools is only able to generate temporary email addresses and receive emails. There are plans to integrate more tools and options in the future.

Ashwin Chugh 2 Feb 14, 2022
Booky - A command line utility for bookmarking files on your terminal!

Booky A command line utility for bookmarking files for quick access With it you can: Bookmark and delete your (aliases of) files at demand Launch them

Pran 1 Sep 11, 2022
A cd command that learns - easily navigate directories from the command line

NAME autojump - a faster way to navigate your filesystem DESCRIPTION autojump is a faster way to navigate your filesystem. It works by maintaining a d

William Ting 14.5k Jan 3, 2023
A command-line based, minimal torrent streaming client made using Python and Webtorrent-cli. Stream your favorite shows straight from the command line.

A command-line based, minimal torrent streaming client made using Python and Webtorrent-cli. Installation pip install -r requirements.txt It use

Jonardon Hazarika 17 Dec 11, 2022
commandpack - A package of modules for working with commands, command packages, files with command packages.

commandpack Help the project financially: Donate: https://smartlegion.github.io/donate/ Yandex Money: https://yoomoney.ru/to/4100115206129186 PayPal:

null 4 Sep 4, 2021
AML Command Transfer. A lightweight tool to transfer any command line to Azure Machine Learning Services

AML Command Transfer (ACT) ACT is a lightweight tool to transfer any command from the local machine to AML or ITP, both of which are Azure Machine Lea

Microsoft 11 Aug 10, 2022
Ros command - Unifying the ROS command line tools

Unifying the ROS command line tools One impairment to ROS 2 adoption is that all

null 37 Dec 15, 2022
A Python-based command prompt concept which includes windows command emulation.

PythonCMD A Python-based command prompt concept which includes windows command emulation. Current features: echo: Input your message and it will be cl

null 1 Feb 5, 2022
Rich is a Python library for rich text and beautiful formatting in the terminal.

The Rich API makes it easy to add color and style to terminal output. Rich can also render pretty tables, progress bars, markdown, syntax highlighted source code, tracebacks, and more — out of the box.

Will McGugan 41.4k Jan 3, 2023
Simple Python Library to display text with color in Python Terminal

pyTextColor v1.0 Introduction pyTextColor is a simple Python Library to display colorful outputs in Terminal, etc. Note: Your Terminal or any software

Siddhesh Chavan 1 Jan 23, 2022
Tablicate - Python library for easy table creation and output to terminal

Tablicate Tablicate - Python library for easy table creation and output to terminal Features Column-wise justification alignment (left, right, center)

null 3 Dec 14, 2022
Shellmon is a tool used to create and control a webshell remotely, created using the Python3

An Simple PHP Webshell Manager Description Shellmon is a tool used to create and control a webshell remotely, created using the Python3 programming la

22XploiterCrew 12 Dec 30, 2022
A Python3 rewrite of my original PwnedConsole project from almost a decade ago

PwnedConsoleX A CLI shell for performing queries against the HaveIBeenPwned? API to gather breach information for user-supplied email addresses. | wri

null 1 Jul 23, 2022