ansilove

ANSI and ASCII art to PNG converter in C
Log | Files | Refs | README | LICENSE

README.md (9517B)


      1 ```
      2          _______         ___________          ___
      3        __\___   \_  ____/     /\   /______ ___\_/__            /\
      4       /    \|     \/  _ \    /--\_____    \\   /  /\          /  \
      5     _/      |     /    \     \      |/     /      \ \ _ _____/    \_______
      6     \       |_____\____/     /      /      \____  /\/                    /
      7      \______|      \  \_____/\______       /\   \/  \   /\NSILOVE / C   /____ _
      8       \     |_______\__\___ \ \    \      /  \___\__/____
      9        \____|        /____/\_\/\__ /     / __/___ \     /\    ____
     10                      \    \ \     /     /_/ __   \/    /__\__/  _/ _____ ___
     11                  /\   \____\/    /     //   \    /    /    /    _>/    //__/\
     12                 /  \           _/      \   //   /    /    /     \/    / \__\/
     13 _ _________    /    \_______ _ \___    /_______/    /   _/ \____      \  /
     14            \  /                 \ \___/\       \_______/\\  \  \______/\/
     15             \/                   \_\  \ \_______\      \ \\/ \__\     \ \
     16                                     \__\/        \______\/ h7/dS!\_____\/
     17 ```
     18 
     19 # AnsiLove/C
     20 
     21 [![Build Status][1]][2]
     22 
     23 AnsiLove is an ANSI and ASCII art to PNG converter, allowing to convert
     24 ANSI and artscene-related file formats into PNG images, supporting ANSI
     25 (.ANS), PCBoard (.PCB), Binary (.BIN), Artworx (.ADF), iCE Draw (.IDF),
     26 Tundra (.TND) and XBin (.XB) formats.
     27 
     28 It creates size optimized 4-bit PNG files and supports SAUCE (Standard
     29 Architecture for Universal Comment Extentions), 80x25 and 80x50 PC fonts
     30 (including all the 14 MS-DOS charsets), Amiga fonts, and iCE colors.
     31 
     32 This is a complete rewrite of [AnsiLove/PHP][3] in the C programming
     33 language.
     34 
     35 # Specs
     36 
     37 AnsiLove/C is strictly using the `C99 standard` to achieve high
     38 portability to all major operating systems. Supported compilers are
     39 `GCC` and `Clang`, others may work but aren't tested. We use Linux
     40 and OpenBSD for AnsiLove/C development.
     41 
     42 # Why C?
     43 
     44 There were many reasons, most notably PHP interpreter independence
     45 and performance. A solid C foundation is just perfect for creating
     46 libraries and it can easily be embedded into applications. We already
     47 mentioned portability. What else? We wanted evolution. AnsiLove/C
     48 should not be understood as a port. It takes many different approaches
     49 (like processing binary font dumps or generating @2x Retina images),
     50 it is overall improved and introduces new features. While results
     51 tend to be the same, the codebase does not have much in common with
     52 it's ancestor.
     53 
     54 # Dependencies
     55 
     56 AnsiLove/C uses the `CMake` build system and requires the
     57 [libansilove][4] library and header files.
     58 
     59 # Installing dependencies
     60 
     61 - OpenBSD: `pkg_add -r cmake`
     62 - NetBSD: `pkgin install cmake`
     63 - FreeBSD: `pkg install cmake`
     64 - Mac OS X: `brew install cmake`
     65 - Alpine Linux: `apk add cmake gcc make musl-dev`
     66 - Debian / Ubuntu / Mint: `apt-get install build-essential cmake`
     67 - Fedora: `yum install cmake gcc make`
     68 - Solus: `eopkg install -c system.devel`
     69 
     70 Binary packages for `libansilove` are available on OpenBSD, NetBSD,
     71 FreeBSD, Debian, Ubuntu, and Solus.
     72 
     73 On other systems, `libansilove` has to be installed manually.
     74 
     75 # Compiling
     76 
     77 	mkdir build
     78 	cd build
     79 	cmake ..
     80 	make
     81 
     82 # Packages
     83 
     84 Packages are available for the following operating systems:
     85 
     86 - [OpenBSD][5]
     87 - [NetBSD][6]
     88 - [FreeBSD][7]
     89 - [Debian][8]
     90 - [Ubuntu][9]
     91 - [openSUSE][10]
     92 - [Solus][11]
     93 
     94 # Features
     95 
     96 The following formats are supported:
     97 
     98 - .ANS - ANSi (ANSI escape sequences: ANSI X3.64 standard)
     99 - .PCB - PCBoard Bulletin Board System (BBS) own file format
    100 - .BIN - Binary format (raw memory copy of text mode video memory)
    101 - .ADF - Artworx format, supporting custom character sets and palettes
    102 - .IDF - iCE Draw format, supporting custom character sets and palettes
    103 - .TND - [TundraDraw][12] format, supporting 24-bit color mode
    104 - .XB - The eXtended Binary [XBin][13] format, supporting custom character sets
    105   and palettes
    106 
    107 Files with custom suffix default to the ANSi renderer (e.g. ICE or CIA).
    108 
    109 AnsiLove/C is capabable of processing:
    110 
    111 - [SAUCE][14] records
    112 - DOS and Amiga fonts (embedded binary dump)
    113 - iCE colors
    114 
    115 Even more:
    116 
    117 - Small output file size (4-bit PNG).
    118 - Optionally generates proper Retina @2x (and up to @8x) PNG.
    119 - You can use custom options for adjusting output results.
    120 - Built-in support for rendering Amiga ASCII.
    121 
    122 # Documentation
    123 
    124 ## Synopsis
    125 
    126 ```
    127      ansilove [-dhiqrsv] [-b bits] [-c columns] [-f font] [-m mode] [-o file]
    128               [-R factor] [-t type] file
    129 ```
    130 
    131 ## Options
    132 
    133 ```
    134      -b bits     Set to 9 to render 9th column of block characters (default:
    135                  8).
    136 
    137      -c columns  Adjust number of columns for ANSI, BIN, and TND files.
    138 
    139      -d          Enable DOS aspect ratio.
    140 
    141      -f font     Select font for supported formats.
    142 
    143      -h          Show help.
    144 
    145      -i          Enable iCE colors.
    146 
    147      -m mode     Set rendering mode for ANS files. Valid options are:
    148 
    149                  ced     Black on gray, with 78 columns.
    150 
    151                  transparent
    152                          Render with transparent background.
    153 
    154                  workbench
    155                          Use Amiga Workbench palette.
    156 
    157      -o file     Specify output filename/path.
    158 
    159      -q          Suppress output messages (quiet).
    160 
    161      -r          Create Retina @2x output file.
    162 
    163      -R factor   Create Retina output file with custom scale factor.
    164 
    165      -t type     Specify input file type.
    166 
    167      -s          Show SAUCE record without generating output.
    168 
    169      -v          Show version information.
    170 ```
    171 
    172 There are certain cases where you need to set options for proper
    173 rendering. However, this is occasionally. Results turn out well
    174 with the built-in defaults.
    175 
    176 ## Fonts
    177 
    178 We dumped many fonts as binary data right into AnsiLove/C, so the
    179 most popular typefaces for rendering ANSi / ASCII art are available
    180 at your fingertips.
    181 
    182 PC fonts can be (all case-sensitive):
    183 
    184 - `80x25` Default (Code page 437)
    185 - `80x50` 80x50 mode (Code page 437)
    186 - `cp737` Greek (Code page 737)
    187 - `cp775` Baltic (Code page 775)
    188 - `cp850` Latin-1 (Code page 850)
    189 - `cp852` Latin-2 (Code page 852)
    190 - `cp855` Cyrillic (Code page 855)
    191 - `cp857` Turkish (Code page 857)
    192 - `cp860` Portuguese (Code page 860)
    193 - `cp861` Icelandic (Code page 861)
    194 - `cp862` Hebrew (Code page 862)
    195 - `cp863` French Canadian (Code page 863)
    196 - `cp865` Nordic (Code page 865)
    197 - `cp866` Russian (Code page 866)
    198 - `cp869` Greek (Code page 869)
    199 - `terminus` Terminus (Modern font, code page 437)
    200 
    201 AMIGA fonts can be (all case-sensitive):
    202 
    203 - `amiga` (alias to Topaz)
    204 - `microknight` (Original MicroKnight version)
    205 - `microknight+` (Modified MicroKnight version)
    206 - `mosoul` (Original mO'sOul font)
    207 - `pot-noodle` (Original P0T-NOoDLE font)
    208 - `topaz` (Original Topaz Kickstart 2.x version)
    209 - `topaz+` (Modified Topaz Kickstart 2.x+ version)
    210 - `topaz500` (Original Topaz Kickstart 1.x version)
    211 - `topaz500+` (Modified Topaz Kickstart 1.x version)
    212 
    213 ## Bits
    214 
    215 `bits` can be:
    216 
    217 - `8` (8-bit)
    218 - `9` (9-bit)
    219 
    220 Setting the bits to `9` will render the 9th column of block characters,
    221 so the output will look like it is displayed in real textmode.
    222 
    223 ## Rendering Mode
    224 
    225 `mode` can be (all case-sensitive):
    226 
    227 - `ced`
    228 - `transparent`
    229 - `workbench`
    230 
    231 Setting the mode to `ced` will cause the input file to be rendered
    232 in black on gray, and limit the output to 78 columns (only available
    233 for `ANS` files). Used together with an Amiga font, the output will
    234 look like it is displayed on Amiga.
    235 
    236 Setting the mode to `workbench` will cause the input file to be
    237 rendered using Amiga Workbench colors (only available for `ANS`
    238 files).
    239 
    240 Settings the mode to `transparent` will produce output files with
    241 transparent background (only available for `ANS` files).
    242 
    243 ## iCE Colors
    244 
    245 iCE colors are disabled by default, and can be enabled by specifying
    246 the `-i` option.
    247 
    248 When an ANSi source was created using iCE colors, it was done with
    249 a special mode where the blinking was disabled, and you had 16
    250 background colors available. Basically, you had the same choice for
    251 background colors as for foreground colors, that's iCE colors.
    252 
    253 ## Columns
    254 
    255 `columns` is only relevant for .ANS, .BIN, .PCB,  and .TND files, and
    256 is optional. In most cases conversion will work fine if you don't set
    257 this flag, the default value is `160` for .BIN files and `80`
    258 otherwise.
    259 
    260 ## SAUCE records
    261 
    262 It's fine to use AnsiLove/C as SAUCE reader without generating any
    263 output, just set option `-s` for this purpose.
    264 
    265 # License
    266 
    267 AnsiLove/C is released under the BSD 2-Clause License. See the
    268 `LICENSE` file for details.
    269 
    270 # Authors
    271 
    272 AnsiLove/C is developed by Stefan Vogt ([@ByteProject][15]), Brian Cassidy
    273 ([@bricas][16]) and Frederic Cambus ([@fcambus][17]).
    274 
    275 # Resources
    276 
    277 Project homepage: https://www.ansilove.org
    278 
    279 GitHub: https://github.com/ansilove/ansilove
    280 
    281 [1]: https://api.travis-ci.org/ansilove/ansilove.png?branch=master
    282 [2]: https://travis-ci.org/ansilove/ansilove
    283 [3]: https://www.ansilove.org
    284 [4]: https://github.com/ansilove/libansilove
    285 [5]: https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/graphics/ansilove
    286 [6]: https://pkgsrc.se/graphics/ansilove
    287 [7]: https://www.freshports.org/graphics/ansilove/
    288 [8]: https://packages.debian.org/search?keywords=ansilove
    289 [9]: https://packages.ubuntu.com/search?keywords=ansilove
    290 [10]: https://software.opensuse.org/package/ansilove
    291 [11]: https://dev.getsol.us/source/ansilove/
    292 [12]: https://sourceforge.net/projects/tundradraw/
    293 [13]: https://github.com/radman1/xbin
    294 [14]: https://github.com/radman1/sauce
    295 [15]: https://github.com/ByteProject
    296 [16]: https://github.com/bricas
    297 [17]: https://github.com/fcambus