Format Specifications

This format stores images as printable text using 94 of the 95 printable ASCII characters. The one character excluded is space. In the commonly-used UTF-8 text encoding, these characters each have a size of 1 byte.

The full ordered set of characters in use, indexed 0-93:

!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~

Layers

Any number of layers can be specified in an image but there must be at least 1. A layer serves a single purpose in an image, most often it is either color or transparency.

A layer conceptually consists of 5 parts:

Purpose within the image:

One layer must be given the purpose of main which indicates it is the most important to the image and is implied that this will be the layer to display as color. Transparency is specified with the purpose of alpha. No other purpose is currently defined, it is open to custom use cases where additional layers are needed. If a layer does not exist within the image but is requested by the decoder, default values will be used instead. For main it is 0 (black). For alpha it is 255 (100% opaque).

The purpose must be unique to each layer, you cannot have two main layers for example.

Data stream type:

The method used to encode the image data. There are currently two data stream types supported: 8-bit RGB (RGB8) and 8-bit generic lossless (A8). See Data Streams for detailed info on how these are encoded.

Data stream version:

0 for all data stream types currently.

Data stream length:

Number of characters in the data stream.

Data stream:

A string of data, only interpretable by the relevant data stream encoder/decoder. Note that in the image format this is stored separately to the above.

Structure

The image format begins with magic number txtimg. This follows with a comma and then these key-value pairs:

• version number v (currently 0)
• image width x in pixels
• image height y in pixels
• list of data stream properties p containing 4 alternating property values. First value indicates the total number of items in the list. The following properties are (in this order): purpose, type, version, length.

Colons separate the key name and value. Key-value pairs are separated by commas. This encoding is known as CSKV or "comma-separated key-values".

Everything listed above is part of the "header". A vertical bar (|) indicates the end of the header.

Finally are the data streams, which are all concatenated without any separating character in the order as given . The data stream length given in the properties allow them to be separated when needed.

Misc. Notes

Reserved characters due to their usage as separators: , : | They must not be used within keys or values.

Use of custom key names to store additional data is allowed however the key name should be prefixed with an underscore to indicate they are custom and to prevent potential future conflicts with official features. These custom keys can be ignored by a standard decoder, it is up to the user of this format to implement any features that use them.

Data streams use pixels that are ordered left-to-right (x axis), bottom-to-top (y axis). The image format has no way of specifying pixel order. It is up to the encoder to ensure pixels are ordered correctly from an input image.

Example

The following is an example TextImage file, with explanation for some of the parts:

txtimg,v:0,x:14,y:17,p:8,main,RGB8,0,142,alpha,A8,0,101|<7?40vV53c><7)877798<7)877798<7)87779;!7H+B.D`@"Co8787779;j<7)8777953f!=J787;b77987779;!8787;!879877794e6p878787798<7N""?q!(FD<7)877798<7)8<7>!!($/T($,%$%($,%$%($,%$%($,%$%($,%$%($,%$%($,%$%($,%$%($,%$%($,%($&%$$$)($&T($,%$%($,%$%($,%$%($,%($/

• txtimg,v:0,x:14,y:17 TextImage file, version 0, dimensions 14x17
• p:8,main,RGB8,0,142,alpha,A8,0,101 Properties containing 8 list items to follow, specifying a main RGB8 data stream that is 142 characters long and an alpha A8 data stream that is 101 characters long.
• | The concatenated data streams follow, in the order given by the properties (RGB8 and then A8)
• <7?40vV53c><7)877798<7)877798<7)87779;!7H+B.D`@"Co8787779;j<7)8777953f!=J787;b77987779;!8787;!879877794e6p878787798<7N""?q!(FD<7)877798<7)8<7> RGB8 data stream
• !!($/T($,%$%($,%$%($,%$%($,%$%($,%$%($,%$%($,%$%($,%$%($,%$%($,%($&%$$$)($&T($,%$%($,%$%($,%$%($,%($/ A8 data stream

More example images