ptrm

ASCII art and animation tool for the terminal

requirements

• cargo for building
• a modern terminal emulator (tested on alacritty, kitty, ghostty)

install

cargo install --git https://gitlab.com/unlessgames/ptrm

usage

new

create a new file at a given width, height and output path

ptrm new 40 20 -o myanim

If a file already exists at the given location, ptrm will try to open it instead (ignoring the size inputs).

If you don't provide an output path, a file with the current date as name will be created.

edit

open an existing file for editing with edit

ptrm edit existing.paf

keys and mouse

ptrm uses a single MOD key that corresponds to both CTRL and ALT keys. All three mouse buttons are utilized (LMB, MMB, RMB).

In most cases, the LMB is used to draw, MMB to select and RMB to erase.

There are a few different modes to use, you can switch between them by pressing the mode's character with a MOD key. Characters for modes are located around the WASD keys for easy access while using the mouse.
You can also click a mode's button on the top and bottom bar to switch to it.
The selected mode's border on the UI will become bright.

• d - draw single characters with the selected color onto the canvas
• s - stamp the selected stamp onto the canvas (create stamps by selecting with MMB in draw mode)
• w - write characters to the current selection by typing on your keyboard
• e - flood fill with LMB or replace every matching character with MOD+LMB
• v - view and transform the selection, this mode lets you select disconnected islands as well
• a - edit the animation

characters

When in draw mode, press any ascii character on your keyboard to use it as character brush.
Once you've used a character, it will be added to the quick char column on the left-side.
You can use the scroll wheel or click items in this column to quickly change to previously used characters.

Pressing SPACE will toggle the character entry that allows you to color existing characters on the canvas without changing them. When using a color-only brush, the draw button will show a filled rectangle instead of a character.

colors

ptrm supports 16 different colors, you can switch between them using the F keys from F1 to F8.

• F1 - white
• F2 - red
• F3 - yellow
• F4 - green
• F5 - cyan
• F6 - blue
• F7 - magenta
• F8 - black

Use F9 to toggle accessing the brighter layer of 8 colors with the same keys.

When selecting a color in stamp mode your current stamp will be made monochromatic and recolored to the selected color. Press the same color again to get back to the original colors of the stamp.

layers

There are two layers you can use to draw on:

• F the foreground (top row in the animation timeline)
• B the background (bottom row on timeline).

You can switch between editing these layers with the UP/DOWN arrows, there are 6 possible views you can step through

• edit F with dimmed previous frame (onion skinning) O
• edit F without seeing B *
• edit F while seeing B as dimmed characters = -
• edit B while seeing F as dimmed characters - =
• edit B without seeing F *
• edit B with dimmed previous frame (onion skinning) O

animation

You can create an animation with multiple frames.

• Use MOD+SPACE from any mode to toggle playing the animation.
• step through frames withTAB/SHIFT+TAB, LEFT/RIGHT or MOD+SCROLL.

When in animation mode

• swap frames with MOD+LEFT/RIGHT or by dragging the frame with LMB
• set the FPS with MOD+UP/DOWN or SCROLL
• remove a frame with BACKSPACE or RMB click
• insert a new frame with ENTER
• duplicate the current frame with MOD+ENTER

view

When you have a completed animation file you might want to view it without editing.

Play an animation on loop

ptrm play myanim.paf

Dump specific framee from a file (might be useful in pipes)

ptrm print myanim.paf -i 0

remapping

while ptrm limits you to the visible ASCII characters and 16 colors, you can remap each of these to any character and any RGB color (as long as your terminal supports true color).

To remap characters, pass in a quoted string with ASCII-UNICODE pairs, separated by space, you will be able to pick these with the keys you have remapped and the remaps will be saved to the file.

ptrm --chars "pπ lλ s♠" new 32 32

To remap colors, pass in a quoted string with INDEX+HEX pairs, separated by space, indices are hexadecimal from 0-F. Below we are remapping the default gray to pink and the default red to hard yellow.

ptrm --tints "0#FF00FF 1#FFFF00" new 32 32

You can use these to remap with all commands (make sure that the remapping arguments come before the subcommand), edit and new will save the remap to the file, while print and play will just use the remap temporarily.

See more options by running ptrm help <SUBCOMMAND>

config

In my limited testing kitty and ghostty works without issues when using Ctrl as MOD.

alacritty) sends the wrong escape code for Ctrl+Enter for historical reasons? Alt+Enter can be used instead or your can remap this key combo to the expected sequence with

# ~/.config/alacritty.toml

[keyboard]
bindings = [
  { key = "Enter", mods = "Control", chars = "\u001B[13;5u" },
]
  

support

If you enjoy this tool consider donating.