Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ghaiklor/terminal-canvas

Manipulate the cursor in your terminal via high-performant, low-level, canvas-like API
https://github.com/ghaiklor/terminal-canvas

ansi canvas cursor javascript low-level nodejs terminal wrapper

Last synced: 3 days ago
JSON representation

Manipulate the cursor in your terminal via high-performant, low-level, canvas-like API

Host: GitHub
URL: https://github.com/ghaiklor/terminal-canvas
Owner: ghaiklor
License: mit
Created: 2016-03-23T08:01:17.000Z (almost 9 years ago)
Default Branch: master
Last Pushed: 2024-07-05T08:39:49.000Z (6 months ago)
Last Synced: 2024-12-15T22:06:36.704Z (10 days ago)
Topics: ansi, canvas, cursor, javascript, low-level, nodejs, terminal, wrapper
Language: TypeScript
Homepage: https://ghaiklor.github.io/terminal-canvas/
Size: 1.28 MB
Stars: 171
Watchers: 7
Forks: 13
Open Issues: 0
Metadata Files:
- Readme: README.md
- License: LICENSE

Awesome Lists containing this project

README

        # terminal-canvas

![Travis (.com)](https://img.shields.io/travis/com/ghaiklor/terminal-canvas?style=for-the-badge)

![Codecov](https://img.shields.io/codecov/c/gh/ghaiklor/terminal-canvas?style=for-the-badge)

![npm](https://img.shields.io/npm/dt/terminal-canvas?style=for-the-badge)

[![GitHub Follow](https://img.shields.io/github/followers/ghaiklor.svg?label=Follow&style=social)](https://github.com/ghaiklor)

[![Twitter Follow](https://img.shields.io/twitter/follow/ghaiklor.svg?label=Follow&style=social)](https://twitter.com/ghaiklor)

Manipulate the cursor in your terminal via high-performant, low-level, canvas-like API.

Entirely written with TypeScript, terminal-canvas exposes features that you can use for rendering in terminal.

High-performance algorithms and optimizations allow to render only cells which have been changed.

Just look at the demo videos below to see, what you can do with terminal-canvas :smiley:

## Demo

|     Touhou - Bad Apple (ASCII Art)     | Touhou - Bad Apple (Colorful Edition)  | Doom (Colorful Edition) |

| :------------------------------------: | :------------------------------------: | :---------------------: |

| [![1][Touhou ASCII P]][Touhou ASCII V] | [![1][Touhou Color P]][Touhou Color V] | [![1][Doom P]][Doom V]  |

## Getting Started

Install it via npm:

```shell

npm install terminal-canvas

```

Include in your project:

```javascript

const Canvas = require('terminal-canvas');

const canvas = new Canvas();

canvas.moveTo(10, 10).write('Hello, world').flush();

```

## Examples

A lot of examples are available to you [here](./examples)

## API Reference

API Reference is accessible [here](https://ghaiklor.github.io/terminal-canvas/)

## How terminal-canvas works

### Control Sequences

terminal-canvas uses VT100 compatible control sequences to manipulate the cursor in the terminal.

You can find a lot of useful information about that here:

- [Terminal codes (ANSI/VT100) introduction](http://wiki.bash-hackers.org/scripting/terminalcodes)

- [ANSI/VT100 Terminal Control Escape Sequences](http://www.termsys.demon.co.uk/vtansi.htm)

- [Colors and formatting (ANSI/VT100 Control sequences)](http://misc.flogisoft.com/bash/tip_colors_and_formatting)

- [Xterm Control Sequences](http://www.x.org/docs/xterm/ctlseqs.pdf)

- [CONSOLE_CODES (man page)](http://man7.org/linux/man-pages/man4/console_codes.4.html)

The next thing which terminal-canvas does is wrap those control codes, so you are able to call JavaScript methods.

### Virtual Terminal

The first releases of the terminal-canvas (which was kittik-cursor) were based on real-time updating terminal cursor, when you are calling some method on the canvas.

This caused performance issues.

So I decided to create my own wrapper around terminal cells.

Each real cell in the terminal has a wrapper (class Cell in the src folder).

The main problem, which Cell resolves, is to render each cell independently from another cells.

So I can grab any cell at any coordinate and render it independently from others.

It works the following way.

Each Cell has style settings and position in the real terminal.

When you are converting Cell to the control sequences, it concatenates the following sequences:

1. Convert cell position to control sequence

2. Convert foreground and background color to control sequence

3. Convert display settings to control sequences

4. Pre-pend the cell char with sequences above

5. Reset all display settings to default

That way, each cell wrapped in own control sequences that can be flushed at any moment.

### Difference between two frames

The last thing I did, was update only cells that really changed.

The algorithm is simple.

When you are writing to the canvas, all write operations mark virtual cells as modified cells.

After some time, you decide to flush changes. When flush() method is called it does 2 things:

1. Iterate through all cells and find only cells with modified marker;

2. Convert modified cell to control sequence and compare that sequence with the sequence that was used at the previous frame;

3. If they are not equal, store new control sequence and write to stream, otherwise, ignore it

That's how I made it possible to render videos in the terminal at 30 FPS.

BTW, if I remove Throttle stream, I'm getting 120 FPS :smiley:

## License

[MIT](./LICENSE)

[Touhou ASCII P]: https://img.youtube.com/vi/aYK8wFMiRP0/0.jpg

[Touhou ASCII V]: https://www.youtube.com/watch?v=aYK8wFMiRP0

[Touhou Color P]: https://img.youtube.com/vi/wgMm0wOZ8MM/0.jpg

[Touhou Color V]: https://www.youtube.com/watch?v=wgMm0wOZ8MM

[Doom P]: https://img.youtube.com/vi/Y5q_HDkt8nA/0.jpg

[Doom V]: https://www.youtube.com/watch?v=Y5q_HDkt8nA