2023-04-10 23:51:39 +03:00
2023-04-15 04:30:34 +03:00
Textual Paint
2023-04-10 23:51:39 +03:00
=============
2023-04-15 04:30:34 +03:00
MS Paint in your terminal.
2023-04-10 23:51:39 +03:00
2023-04-15 04:30:34 +03:00
This is a TUI (Text User Interface) image editor, inspired by MS Paint, built with [Textual ](https://textual.textualize.io/ ).
2023-04-10 23:51:39 +03:00
2023-04-15 04:30:34 +03:00
<!-- GitHub doesn't support line - height style in markdown, so I can't use inline HTML for the screenshot without seams between rows of text. But I can include the HTML inside <foreignObject> in an SVG file and include that as an <img> element. -->
<!-- GitHub doesn't support figure/figcaption in markdown, so I have to use a table. -->
Add textual screenshot to readme
This took a lot of trial and error to get this working.
- First I had to figure out how to copy the terminal output as HTML.
I had to configure keybindings for Select All and Copy As HTML in
the Ubuntu terminal.
- GitHub doesn't support line-height in markdown, so I came up with
using an SVG with <foreignObject> to contain the screenshot HTML.
- GitHub doesn't support inline SVG, so I had to use <img>, that's fine.
An external file is cleaner anyways.
- I spent a long time trying to fix the seams between rows of text.
`line-height: <font-size>` is not `line-height: 1`!
I think I tried `line-height: 1` first, but it wasn't working for some
reason so I tried a bajillion things, having mentally discounted it,
before circling back to it and trying it again and it actually worked.
- I spent a long time futzing about with SVG viewports and units.
- The text was staggered due to some of the Unicode characters, so I
developed a script to fix that up. I managed to achieve a nice
development cycle for this, but only near the end of developing it.
Most of the time while working on it I was copying and pasting
the updated code into the console after hitting up up enter to
re-run grapheme-splitter's JS.
The next commit will apply this script.
- All in all, getting this screenshot working took basically all day!
Compare that to my first day of progress on this project, having
never used the Textual framework before, and also having not used
Python for a while. In summary, coding is a land of contrasts.
- VS Code's markdown rendering isn't working with the ch/lh units.
2023-04-14 09:21:27 +03:00
< table >
< tr > < td align = "center" >
< img src = "screenshot.svg" alt = "MS Paint like interface" / >
< / td > < / tr >
2023-04-15 04:30:34 +03:00
< tr > < td align = "center" > This screenshot of Textual Paint is the terminal's screen buffer copied as HTML, wrapped in SVG, placed in HTML inside Markdown.< br > This might not render correctly in your browser.< / tr > < / td >
Add textual screenshot to readme
This took a lot of trial and error to get this working.
- First I had to figure out how to copy the terminal output as HTML.
I had to configure keybindings for Select All and Copy As HTML in
the Ubuntu terminal.
- GitHub doesn't support line-height in markdown, so I came up with
using an SVG with <foreignObject> to contain the screenshot HTML.
- GitHub doesn't support inline SVG, so I had to use <img>, that's fine.
An external file is cleaner anyways.
- I spent a long time trying to fix the seams between rows of text.
`line-height: <font-size>` is not `line-height: 1`!
I think I tried `line-height: 1` first, but it wasn't working for some
reason so I tried a bajillion things, having mentally discounted it,
before circling back to it and trying it again and it actually worked.
- I spent a long time futzing about with SVG viewports and units.
- The text was staggered due to some of the Unicode characters, so I
developed a script to fix that up. I managed to achieve a nice
development cycle for this, but only near the end of developing it.
Most of the time while working on it I was copying and pasting
the updated code into the console after hitting up up enter to
re-run grapheme-splitter's JS.
The next commit will apply this script.
- All in all, getting this screenshot working took basically all day!
Compare that to my first day of progress on this project, having
never used the Textual framework before, and also having not used
Python for a while. In summary, coding is a land of contrasts.
- VS Code's markdown rendering isn't working with the ch/lh units.
2023-04-14 09:21:27 +03:00
< / table >
2023-04-13 17:06:39 +03:00
## Features
2023-04-18 10:43:45 +03:00
- [x] Open and save images
- [x] Fancy file dialogs
2023-05-01 19:31:21 +03:00
- [x] Drag and drop files to open
2023-04-18 10:43:45 +03:00
- [x] Warnings when overwriting an existing file, or closing with unsaved changes
2023-05-06 04:50:42 +03:00
- [x] Auto-saves a `.ans~` backup file alongside the file you're editing, for crash recovery
2023-04-30 00:29:06 +03:00
- File formats, chosen by typing a file extension in the Save As dialog:
- [x] ANSI (.ans) — Note that while it can load the files that it saves, you may have limited success loading other ANSI files that you find on the web, or create with other tools. ANSI files can vary a lot and even encode animations!
- [x] Plain Text (.txt) — discards color information
- [x] SVG (.svg) — save only
- [x] HTML (.html) — save only
- [ ] PNG (.png) — not yet
- [ ] Bitmap (.bmp) — not yet
2023-04-13 17:06:39 +03:00
- Tools
2023-04-23 05:49:58 +03:00
- [x] Free-Form Select
2023-04-21 23:34:35 +03:00
- [x] Select
2023-04-25 20:17:44 +03:00
- [x] Eraser/Color Eraser
2023-04-13 17:06:39 +03:00
- [x] Fill With Color
2023-04-14 01:54:51 +03:00
- [x] Pick Color
2023-04-20 02:18:29 +03:00
- [x] Magnifier
2023-04-13 17:06:39 +03:00
- [x] Pencil
- [x] Brush
2023-04-14 01:48:24 +03:00
- [x] Airbrush
2023-04-22 04:19:05 +03:00
- [x] Text
2023-04-13 17:06:39 +03:00
- [x] Line
2023-04-22 05:51:00 +03:00
- [x] Curve
2023-04-13 17:06:39 +03:00
- [x] Rectangle
2023-04-22 08:04:19 +03:00
- [x] Polygon
2023-04-13 17:06:39 +03:00
- [x] Ellipse
- [x] Rounded Rectangle
- [x] Color palette
- [x] Undo/Redo
- [x] Efficient screen updates and undo/redo history, by tracking regions affected by each action
- You could totally use this program over SSH! Haha, this "what if" project could actually be useful. Of course, it should be mentioned that you can also run graphical programs over SSH, but this might be more responsive, or just fit your vibe better.
2023-04-14 03:28:58 +03:00
- [x] Brush previews
2023-04-13 17:06:39 +03:00
- [x] Menu bar
2023-04-24 23:46:32 +03:00
- [x] Status bar
- [x] Keyboard shortcuts
2023-04-18 11:09:47 +03:00
- [x] Localization into 26 languages: Arabic, Czech, Danish, German, Greek, English, Spanish, Finnish, French, Hebrew, Hungarian, Italian, Japanese, Korean, Dutch, Norwegian, Polish, Portuguese, Brazilian Portuguese, Russian, Slovak, Slovenian, Swedish, Turkish, Chinese, Simplified Chinese
2023-04-10 23:51:39 +03:00
2023-04-17 02:25:02 +03:00
## Usage
<!-- ### Installation
```bash
pip install textual-paint
```
### Running
```bash
textual-paint
``` -->
### Command Line Options
```
$ python3 paint.py --help
2023-05-01 17:47:36 +03:00
usage: paint.py [options] [filename]
2023-04-17 02:25:02 +03:00
Paint in the terminal.
positional arguments:
2023-05-06 02:56:36 +03:00
filename Path to a file to open. File will be created if it
doesn't exist.
2023-04-17 02:25:02 +03:00
options:
2023-04-18 08:05:40 +03:00
-h, --help show this help message and exit
2023-04-30 00:50:03 +03:00
--version show program's version number and exit
2023-04-18 08:05:40 +03:00
--theme {light,dark} Theme to use, either "light" or "dark"
2023-04-18 10:43:45 +03:00
--language {ar,cs,da,de,el,en,es,fi,fr,he,hu,it,ja,ko,nl,no,pl,pt,pt-br,ru,sk,sl,sv,tr,zh,zh-simplified}
Language to use
2023-04-18 08:05:40 +03:00
--ascii-only-icons Use only ASCII characters for tool icons
--inspect-layout Inspect the layout with middle click, for development
2023-05-03 01:19:58 +03:00
--clear-screen Clear the screen before starting; useful for
development, to avoid seeing fixed errors
--restart-on-changes Restart the app when the source code is changed, for
development
2023-05-02 22:19:40 +03:00
--recode-samples Open and save each file in samples/, for testing
2023-04-17 02:25:02 +03:00
```
### Keyboard Shortcuts
- < kbd > Ctrl</ kbd > +< kbd > D</ kbd > : Toggle Dark Mode
- < kbd > Ctrl</ kbd > +< kbd > Q</ kbd > : Quit
- < kbd > Ctrl</ kbd > +< kbd > Shift</ kbd > +< kbd > S</ kbd > : Save As **IF SHIFT IS DETECTED** — might trigger Save instead, and overwrite the open file! ⚠️
- < kbd > Ctrl</ kbd > +< kbd > Shift</ kbd > +< kbd > Z</ kbd > : Redo **IF SHIFT IS DETECTED** — might trigger Undo instead.
The rest match MS Paint's keyboard shortcuts:
- < kbd > Ctrl</ kbd > +< kbd > S</ kbd > : Save
- < kbd > Ctrl</ kbd > +< kbd > O</ kbd > : Open
- < kbd > Ctrl</ kbd > +< kbd > N</ kbd > : New
- < kbd > Ctrl</ kbd > +< kbd > T</ kbd > : Toggle Tools Box
- < kbd > Ctrl</ kbd > +< kbd > W</ kbd > : Toggle Colors Box
- < kbd > Ctrl</ kbd > +< kbd > Z</ kbd > : Undo
- < kbd > Ctrl</ kbd > +< kbd > Y</ kbd > : Redo
- < kbd > F4</ kbd > : Redo
2023-04-23 08:09:19 +03:00
- < kbd > Ctrl</ kbd > +< kbd > A</ kbd > : Select All
2023-04-21 08:32:44 +03:00
- < kbd > Ctrl</ kbd > +< kbd > PageUp</ kbd > : Large Size
- < kbd > Ctrl</ kbd > +< kbd > PageDown</ kbd > : Normal Size
2023-04-17 02:25:02 +03:00
2023-04-25 19:49:00 +03:00
### Tips
2023-04-25 06:43:38 +03:00
You can draw with a character by clicking the selected color display area in the palette and then typing the character,
2023-04-29 23:52:03 +03:00
or by double clicking the same area to pick a character from a list.
2023-04-25 06:43:38 +03:00
You can set the text color by holding Ctrl while clicking a color in the palette, or while double clicking a color to open the Edit Colors dialog.
You can display a saved ANSI file in the terminal with `cat` :
```bash
2023-04-29 23:53:38 +03:00
cat samples/ship.ans
2023-04-25 06:43:38 +03:00
```
2023-04-24 23:46:32 +03:00
## Known Issues
2023-04-30 00:11:47 +03:00
- Undo/Redo doesn't work with text. Ctrl+Z will delete the textbox. (Also note that the Text tool works differently from MS Paint; it will overwrite characters and the cursor can move freely, which makes it better for ASCII art and worse for prose.)
- The selection box border appears inside instead of outside (and lacks dashes). For the text box, I hid the border because it was too visually confusing, but it should also have an outer border.
- Pick Color can't be cancelled (with Esc or by pressing both mouse buttons), since it samples the color continuously.
- Pressing both mouse buttons stops the current tool, but doesn't undo the current action.
2023-04-24 23:46:32 +03:00
- Due to limitations of the terminal, shortcuts using Shift or Alt might not work.
- Menus are not keyboard navigable.
2023-05-04 23:01:10 +03:00
- The Zoom submenu flickers as it opens, and may not always open in the right place.
- The canvas flickers when zooming in with the Magnifier tool.
2023-04-24 23:46:32 +03:00
- Some languages don't display correctly.
2023-04-25 21:10:59 +03:00
- Large files can make the program very slow, as can magnifying the canvas.
- Saved ANSI files are unnecessarily large, because they include escape sequences for every cell, even if the colors match the previous cell.
2023-04-29 19:33:32 +03:00
- Free-Form Select stamping/finalizing is incorrect when the selection is off-screen to the left or top.
2023-04-30 00:18:41 +03:00
- Moving the selection with the arrow keys does not cut out the selection from the canvas, it only moves the selection box.
- Status bar description can be left blank when selecting a menu item <!--I'm guessing Leave can come after close-->
- Menu items like Copy/Cut/Paste are not grayed out when inapplicable. Only unimplemented items are grayed out.
2023-05-02 05:35:12 +03:00
- Set As Wallpaper may not work on your system. For me, on Ubuntu, the wallpaper setting is updated but the picture is not, unless I manually pick it. There is however untested support for many platforms, and you may have better luck than me.
2023-05-06 03:03:15 +03:00
- If you paste and then stamp the selection with Ctrl+Click, the stamp(s) can't be undone. An undo state is only created when finalizing the selection, for pasted selections.
2023-04-25 21:10:59 +03:00
The program has only been tested on Linux. Issues on other platforms are as-yet _unknown_ :)
2023-04-24 23:46:32 +03:00
2023-04-10 23:51:39 +03:00
## Development
2023-04-19 09:34:17 +03:00
Install Textual and other dependencies:
2023-04-10 23:51:39 +03:00
```bash
2023-04-26 19:52:19 +03:00
pip install "textual[dev]" stransi psutil watchdog pyperclip pyright
2023-04-10 23:51:39 +03:00
```
2023-04-19 19:00:34 +03:00
Run via Textual's CLI for live-reloading CSS support, and enable other development features:
2023-04-10 23:51:39 +03:00
```bash
2023-04-29 20:38:09 +03:00
textual run --dev "src/textual_paint/paint.py --clear-screen --inspect-layout --restart-on-changes"
2023-04-10 23:51:39 +03:00
```
2023-04-17 02:23:00 +03:00
Or run more basically:
2023-04-10 23:51:39 +03:00
```bash
2023-04-29 20:38:09 +03:00
python src/textual_paint/paint.py
2023-04-10 23:51:39 +03:00
```
2023-04-17 02:23:00 +03:00
`--clear-screen` is useful for development, because it's sometimes jarring to see error messages that have actually been fixed, when exiting the program.
2023-04-29 20:38:09 +03:00
`--inspect-layout` lets you middle click to visualize the layout breakdown by labeling each widget in the hierarchy, and coloring their regions. The labels affect the layout, so you can also hold Ctrl to only colorize, and you can remember how the colors correspond to the labels, to build a mental model of the layout.
2023-04-19 19:00:34 +03:00
`--restart-on-changes` automatically restarts the program when any Python files change. This works by the program restarting itself directly. (Programs like `modd` or `nodemon` that run your program in a subprocess don't work well with Textual's escape sequences.)
2023-04-17 02:23:00 +03:00
There are also launch tasks configured for VS Code, so you can run the program from the Run and Debug panel.
2023-04-19 21:12:44 +03:00
Note that it runs slower in VS Code's debugger.
To see logs, run [`textual console` ](https://textual.textualize.io/guide/devtools/#console ) and then run the program via `textual run --dev` .
This also makes it run slower.
2023-04-17 02:23:00 +03:00
2023-05-04 03:17:23 +03:00
Often it's useful to exclude events with `textual console -x EVENT` .
To test file encoding, run `textual run --dev "src/textual_paint/paint.py --recode-samples"` .
If there are differences in the ANSI files, you can set up a special diff like this:
```bash
git config --local "diff.cat-show-all.textconv" "cat --show-all"
```
but you should check that `cat --show-all samples/2x2.ans` works on your system first.
Also, note that it might not work with your Git GUI of choice; you may need to use the command line.
2023-05-01 21:47:30 +03:00
### Linting
```bash
pyright # type checking
cspell-cli lint . # spell checking
```
2023-04-19 19:00:34 +03:00
### Update Dependencies
```bash
python -m pipreqs.pipreqs --ignore .history --force
```
2023-04-10 23:51:39 +03:00
## License
[MIT ](LICENSE.txt )
## Unicode Symbols and Emojis for Paint Tools
2023-04-15 04:30:34 +03:00
The first thing I did in this project was to collect possible characters to represent all the tool icons in MS Paint, to gauge how good of a recreation it would be possible to achieve, starting from looks.
2023-04-13 16:15:22 +03:00
Unfortunately, I haven't run into any significant roadblocks, so I'm apparently recreating MS Paint. [Again. ](https://jspaint.app )
These are the symbols I've found so far:
2023-04-14 04:31:36 +03:00
- Free-Form Select: ✂️📐🆓🕸✨⚝🫥🇫/🇸◌⁛⁘ ⢼⠮
2023-04-18 22:06:12 +03:00
- Select: ⬚▧🔲 ⣏⣹
2023-04-17 08:57:27 +03:00
- Eraser/Color Eraser: 🧼🧽🧹🚫👋🗑️▰▱
2023-04-13 07:30:47 +03:00
- Fill With Color: 🌊💦💧🌈🎉🎊🪣🫗
2023-04-13 07:27:27 +03:00
- Pick Color: 🎨💉💅💧📌📍⤤𝀃🝯🍶
2023-04-10 23:51:39 +03:00
- Magnifier: 🔍🔎👀🔬🔭🧐🕵️♂️🕵️♀️
2023-04-13 07:27:27 +03:00
- Pencil: ✏️✎✍️🖎🖊️🖋️✒️🖆📝🖍️
2023-04-10 23:51:39 +03:00
- Brush: 🖌️🖌👨🎨🧑🎨💅
- Airbrush: 💨ᖜ╔🧴🥤🫠
2023-04-13 07:27:27 +03:00
- Text: 🆎📝📄📃🔤📜AA
2023-04-13 16:15:22 +03:00
- Line: 📏📉📈⟍𝈏╲⧹\⧵ ∖
- Curve: ↪️🪝🌙〰️◡◠~∼≈∽∿〜〰﹋﹏≈≋~⁓
- Rectangle: ▭▬▮▯🟥🟧🟨🟩🟦🟪🟫⬛⬜◼️◻️◾◽▪️▫️
- Polygon: ▙𝗟𝙇﹄』⬣⬟🔶🔷🔸🔹🔺🔻△▲
- Ellipse: ⬭⭕🔴🟠🟡🟢🔵🟣🟤⚫⚪🫧
2023-04-10 23:51:39 +03:00
- Rounded Rectangle: ▢⬜⬛
2023-04-13 16:15:22 +03:00
The default symbols used may not be the best on your particular system, so I may add some kind of configuration for this in the future.
### Cursor
A crosshair cursor could use one of `+✜✛✚╋╬` , but whilst that imitates the look, it might be better to show the pixel under the cursor, i.e. character cell, surrounded by dashes, like this:
```
╻
╺█╸
╹
```
2023-04-10 23:51:39 +03:00
## See Also
2023-04-11 01:31:41 +03:00
- [JavE ](http://jave.de/ ), an advanced Java-based ASCII art editor
2023-04-25 08:57:13 +03:00
- [Playscii ](http://vectorpoem.com/playscii/ ), a beautiful ASCII/ANSI art editor. This is also written in Python and MIT licensed, so I might take some code from it, for converting images to ANSI, for example. Maybe even try to support (or piggy back off of) its file format.
2023-04-11 01:44:24 +03:00
- [cmdpxl ](https://github.com/knosmos/cmdpxl ), a pixel art editor for the terminal using the keyboard
- [pypixelart ](https://github.com/douglascdev/pypixelart ), a pixel art editor using vim-like keybindings, inspired by cmdpxl but not terminal-based