telepaint.lua

[RaiuTheEevee]

What is telepaint.lua?
This program is an art tool for making images with square pixels using the 32 teletext symbols. This program was designed to fit on any type of computer terminal (not including monitors).

The core functions of this program will work on a monitor, but of course right and middle click and scrolling won't work. The program also won't be able to launch if this monitor is too small. Minimum term size is 26x12.

To download, run: pastebin get V0gqrj2v telepaint.lua

This program also requires three APIs to work:
pastebin get Rac6Jxjg /API/LibAppend.lua
pastebin get t2TvSiSU /API/Class.lua
pastebin get KA2dK07y /API/Events.lua
pastebin get sSSyDAFm /API/bpi.lua


Running the program works like the built-in paint program. Run 'telepaint <path>' to load a .bpi file for editing. The program will automatically load a file starting from the directory the shell is currently in. If you put "/" at the start of the path, it will load starting from the root directory. If the file does not exist, a new file and empty canvas will be created.

What is a .bpi file?
'.bpi' is a work in progress file format for images that contain text, as an alternative to ComputerCraft's '.nfp' files. .bpi files are saved in binary encoding.

When saving a bpi image to a file, a table is passed to the save function. The table is formatted as follows:

Code Select Expand

{
  [y] = { -- Y Coordinate
    [x] = { -- X Coordinate
      text = "c", -- Character
      tCol = "0", -- Text Color
      bCol = "f"  -- Background Color
    }
  }
}The X and Y coordinates should be positive numbers greater than zero and less
than or equal to 2^128.

Each pixel in the save file is formatted as follows:

• X Length = 4 bits for the length in bytes of the X Coordinate.
• Y Length = 4 bits for the legnth in bytes of the Y Coordinate.
• X Coordinate = X Length bytes.
• Y Coordinate = Y Length bytes.
• Text Code = 1 byte for the text character code.
• Text Color = 4 bits.
• Background Color = 4 bits.

Each pixel may be between 5 and 35 total bytes depending on the size of the
coordinates. The pixels are not in any specific order. Empty spaces between
pixels may be treated as transparent pixels.

How do I use this program?

The Canvas
The largest window on the left is your canvas. This is your source image used to paint like the built-in 'paint' program. Use left click to paint with the primary selected color, right click to erase, and middle click to pick a new primary color from the canvas.

The window in the top right is the output image that will be saved to the .bpi file. Every 2x3 pixels in the source image is a "pixel" in the output image.

Each "pixel" in the output image can only have two colors, the text and background color for that character. Any extra colors will be converted to the text or background color, based on the dithering mode, explained below.

The background color is based on the bottom right pixel in the 2x3 space, and the text color is based on the first color -  going from left to right, top to bottom - that doesn't match the background color, or it will be the background color if no other color is found.

If there are any transparent pixels in that 2x3 space, they will be automatically converted to the background color. If the pixel for the background color is transparent, it will be converted to the secondary selected color. Here are some examples of that in action.


If all pixels in the 2x3 space are transparent, then the output pixel will also be transparent.

Scrolling
Put your mouse cursor over the source canvas and use scroll wheel to scroll the image up or down. Hold shift while scrolling to scroll left or right. You can also hold shift while clicking and dragging to pan the image. Doing any of these actions with your mouse over the output image will scroll/pan faster. The current scroll position of the output image is printed on the horizontal border under the output image.

Selected Pixel
The bottom right window is the menu. The first line in the menu window starts off blank. If you left click any where in the output window, that pixel will be selected. The selected pixel will be shown by the blinking shell cursor. That pixel and its character code will be printed on the first line in the menu. If you right or middle click on the output, it will deselect the pixel.

The X and Y values shown are the program's scroll position.

Colors
The two pixels all the way on the right are your selected colors. Click any of the other colors with left click to select the primary color, and use right click to select the secondary color.

Dithering Mode
'Dither' is the dithering mode. This controls how pixels with more than two colors are converted to teletext. Click this or press 0 or 1 on your keyboard to toggle this option.

When the mode is 0, extra colors will be converted to the background color.


When the mode is 1, extra colors will be converted to the text color.

This does not affect transparent pixels.

Main Menu
You can use ctrl to access the save and exit menu. Use left or right arrow keys to select either button, then press enter to use them. You can also click on either button to use them. When saving, you will get a message saying if the task was successful, if the file would be too big to save, or if the file is unable to be saved for some other reason.

Additional Screenshots
In the image below, I've drawn the player sprite from Pokémon red. As you can see, it looks corrupted in the output image, and that's because there's more than 2 colors in the corrupted pixels. It can't be effectively converted without damaging the image.


In this image, I've redrawn the sprite in two different ways to adhere to the limitations of teletext. I've also swapped some of the colors to spice up the image.


In this image, I've redrawn the sprite with 2x2 pixels. This makes it so you actually can draw an image with pixel perfect color, but it has the unfortunate side effect of being twice as big. There's also some conflicts with the transparency, as you can see in the output image, which makes this type of image not the most effective way to use this technique. I may make another program in the future that utilizes this technique better.


Changelog
2024/05/14:

• Changed 'doFile' to 'require'.
• Added API for bpi. Files will now be saved and loaded using this API.