Description

Ansilove is a set of tools to convert ANSi and artscene-related file formats into PNG images, supporting ANSi (.ANS), PCBOARD (.PCB), BiNARY (.BIN), ADF (.ADF), iDF (.IDF), TUNDRA (.TND) and XBiN (.XB) formats.

Caution Ansilove/PHP is now deprecated, version 1.12 will be the last release. Users are encouraged to migrate to Ansilove/C which replaces the command line converter, and to Ansilove.js for doing "on the fly" conversions on web pages.

It includes an all purposes command line converter, along with a library to use on web pages for doing "on the fly" conversions. It creates size optimized 4-bit PNG files and supports SAUCE (Standard Architecture for Universal Comment Extentions), 80x25 and 80x50 PC fonts (including all the 14 MS-DOS charsets and some unofficial ones), Amiga fonts, and iCE colors.

It is written in PHP, and can thus be run on any supported system: the command line converter can be used under Linux, Mac OS X, Windows, and so far and so on.

Important Ansilove doesn’t require any Web server: you can use the bundled command line converter to convert files locally on your computer.

Features

  • ANSi (.ANS) format support

  • PCBOARD (.PCB) format support

  • BiNARY (.BIN) format support

  • ADF (.ADF) format support (Artworx)

  • iDF (.IDF) format support (iCE Draw)

  • TUNDRA (.TND) format support - https://sourceforge.net/projects/tundradraw/

  • XBiN (.XB) format support - http://www.acid.org/info/xbin/xbin.htm

  • Small output file size (4-bit PNG)

  • SAUCE (Standard Architecture for Universal Comment Extentions)

  • 80x25 font support

  • 80x50 font support

  • Amiga font support

  • iCE colors support

Supported charsets

  • IBM PC (Code page 437)

  • Baltic (Code page 775)

  • Cyrillic (Code page 855)

  • French Canadian (Code page 863)

  • Greek (Code pages 737 and 869)

  • Hebrew (Code page 862)

  • Icelandic (Code page 861)

  • Latin-1 (Code page 850)

  • Latin-2 (Code page 852)

  • Nordic (Code page 865)

  • Portuguese (Code page 860)

  • Russian (Code page 866)

  • Turkish (Code page 857)

Supported unofficial charsets

  • Armenian

  • Persian (Iran System encoding standard)

Requirements

Ansilove requires PHP with the GD module installed. If you want to convert huge files, you may have to increase the memory_limit size in your php.ini file.

Installation

Using tarballs

wget https://www.ansilove.org/files/ansilove-php-1.12.tar.gz
tar xvfz ansilove-php-1.12.tar.gz

Using Git

git clone git@github.com:ansilove/ansilove-php.git
Important Under Windows people must install the PHP binaries: the easiest way is to use the .exe installer and enable the GD library.

Configuration options

The configuration options are defined in the ansilove.cfg.php file.

Options list

  • ANSILOVE_FILES_DIRECTORY

Defines the directory where all the files to be rendered must be placed when using the library online to do "on the fly" conversions. Default value: ansis/

  • ANSILOVE_LOG_FILE

Defines the log file used by the error message logger. Default value: ansilove.log

  • PCBOARD_STRIP_CODES

Defines a serie of comma separated values containing PCBoard codes to be stripped from the output.

Default value: "@POFF@,@WAIT@", which means all @POFF@ and @WAIT@ codes will be stripped.

  • DIZ_EXTENSIONS

Defines a serie of comma separated values specifying which files to render in DIZ mode. Default value: ".diz,.ion"

  • SUBSTITUTE_BREAK

Whether or not stop rendering input files when the substitute (SUB) character is encountered. Default value: 1 (ENABLED)

  • WRAP_COLUMN_80

Whether or not enable 80th column wrapping. Default value: 1 (ENABLED)

  • CED_BACKGROUND_COLOR

Defines RGB values of the CED mode background color.

  • CED_FOREGROUND_COLOR

Defines RGB values of the CED mode foreground color.

  • WORKBENCH_COLOR

Defines RGB values of the WorkBench mode colors.

  • THUMBNAILS_SIZE

Defines thumbnails size multiplicator. Default value: 1 (will produce 80 pixels width output)

  • THUMBNAILS_HEIGHT

Defines maximum thumbnails height (in pixels). Default value: 0 (will produce full height output)

  • THUMBNAILS_TAG

Defines the tag added to the output file name. Default value: -thumbnail

  • SPLIT

Whether or not split output in multiple images files. Default value: 0 (DISABLED)

  • SPLIT_HEIGHT

Define the height (in pixels) of each splitted pictures. Default value: 4096

  • SPLIT_SEPARATOR

Defines the separator used in output file names. Default value: .

Supported options for each file format

Format columns font bits icecolors

ANS

X

X

X

PCB

X

X

X

BIN

X

X

X

X

ADF

IDF

TND

X

X

XB

Command line converter

The command line converter can be invoked by typing:

./ansilove
Note Windows users should use the bundled ansilove.bat file.

Usage

ansilove inputfile columns font bits icecolors
Note If no options are specified, default settings are used: 80x25, 8-bit font and iCE colors turned off. If no columns are specified for .BIN, default value is 160.

Columns options

Important Used for .BIN files only. Skip this option when converting other formats.

Font options

  • 80x25

  • 80x50

  • PC or Amiga fonts (8-bit font only)

Amiga fonts options

  • amiga (alias to Topaz)

  • b-strict (Original B-Strict font)

  • b-struct (Original B-Struct font)

  • microknight (Original MicroKnight version)

  • microknight+ (Modified MicroKnight version)

  • microknightplus (alias to MicroKnight + to be used in URLs)

  • mosoul (Original mO’sOul font)

  • pot-noodle (Original P0T-NOoDLE font)

  • topaz (Original Topaz Kickstart 2.x version)

  • topaz+ (Modified Topaz Kickstart 2.x+ version)

  • topazplus (alias to Topaz+ to be used in URLs)

  • topaz500 (Original Topaz Kickstart 1.x version)

  • topaz500+ (Modified Topaz Kickstart 1.x version)

  • topaz500plus (alias to Topaz500+ to be used in URLs)

Note All the amiga fonts come from the excellent Amiga bitmap fonts package by dMG.

PC fonts options

  • 80x25 (Default, code page 437)

  • 80x50 (Code page 437, 80x50 mode)

  • armenian

  • baltic (Code page 775)

  • cyrillic (Code page 855)

  • french-canadian (Code page 863)

  • greek (Code page 737)

  • greek-869 (Code page 869)

  • hebrew (Code page 862)

  • icelandic (Code page 861)

  • latin1 (Code page 850)

  • latin2 (Code page 852)

  • nordic (Code page 865)

  • persian (Iran System encoding standard)

  • portuguese (Code page 860)

  • russian (Code page 866)

  • terminus (Terminus font)

  • turkish (Code page 857)

Bits options

  • 8 (8-bit)

Default rendering mode.

  • 9 (9-bit)

Renders the 9th column of block characters, causing the output to look like it’s displayed in real textmode.

  • ced

Renders files in black on gray, and limit the output to 78 columns (only available in ANSi loader).

Used together with an Amiga font, the output will look like it is displayed on Amiga.

Note It is possible to set custom RGB values by modifying the predefined constants CED_BACKGROUND_COLOR and CED_FOREGROUND_COLOR in the configuration file.

  • thumbnail

Generate thumbnail, using the full length picture by default.

Note You can adjust the maximum height and the output size by changing the THUMBNAILS_HEIGHT and THUMBNAILS_SIZE options in the configuration file. NOTE: It is also possible to change the tag added to the output file name by changing the THUMBNAILS_TAG option in the configuration file.

  • transparent

Renders files with transparent background (only available in ANSi loader).

  • workbench

Renders files using Amiga Workbench colors (only available in ANSi loader).

Note It is possible to set custom RGB values by modifying the predefined constants WORKBENCH_COLOR in the configuration file.

iCE colors options

  • 0 (turned OFF)

  • 1 (turned ON)

Examples

ansilove ansi.ans
ansilove ansi.ans 80x25 9 (80x25 font, 9-bit)
ansilove ansi.ans 80x25 thumbnail (80x25 font, thumbnail rendering)
ansilove ansi.ans 80x50 9 (80x50 font, 9-bit)
ansilove ansi.ans russian 9 (Russian font, 9-bit)
ansilove ansi.ans amiga (Amiga font)
ansilove pcboard.pcb
ansilove pcboard.pcb 80x25 9 (80x25 font, 9-bit)
ansilove pcboard.pcb 80x25 thumbnail (80x25 font, thumbnail rendering)
ansilove binary.bin 160
ansilove binary.bin 160 80x25 9 (80x25 font, 9-bit)
ansilove binary.bin 160 80x25 thumbnail (80x25 font, thumbnail rendering)
ansilove binary.bin 160 80x50 9 (80x50 font, 9-bit)
ansilove adf.adf
ansilove adf.adf thumbnail (thumbnail rendering)
ansilove idf.idf
ansilove idf.idf thumbnail (thumbnail rendering)
ansilove tundra.tnd
ansilove tundra.tnd 80x25 9 (80x25 font, 9-bit)
ansilove tundra.tnd 80x25 thumbnail (80x25 font, thumbnail rendering)
ansilove xbin.xb
ansilove xbin.xb thumbnail (thumbnail rendering)
Important Files with a .DIZ extension are rendered with the exact needed number of columns. White spaces and empty lines at the beginning and end of DIZ files are stripped from the output.
Note You can customize file extensions definitions in the configuration fileby modifying the predefined constant called DIZ_EXTENSIONS

Library usage for doing on the fly conversions on web pages

Using Ansilove library for doing "on the fly" conversions on Web pages, can be done using these loaders:

  • load_ansi.php

  • load_pcboard.php

  • load_bin.php

  • load_adf.php

  • load_idf.php

  • load_tundra.php

  • load_xbin.php

Upload the loaders you plan to use, the library ansilove.php, the config file ansilove.cfg.php, along with the fonts directory somewhere on your web site.

For security issues, all the files to be rendered must be placed in a directory, which is ansis/ by default (the ending slash is required). This value is defined in the configuration file by the ANSILOVE_FILES_DIRECTORY constant.

Caution Do NOT unset the ANSILOVE_FILES_DIRECTORY constant, else it’ll be possible to convert files laying in the same directory than the loaders, which could lead to possible security leaks.
Important Please note that the input is sanitized, so it is impossible to use / and .. in paths.

Including custom image tags in HTML code

<img src="load_ansi.php?input=ansi.ans">
<img src="load_ansi.php?input=ansi.ans&font=80x25&bits=9">
<img src="load_ansi.php?input=ansi.ans&font=80x25&bits=thumbnail">
<img src="load_ansi.php?input=ansi.ans&font=russian">
<img src="load_ansi.php?input=ansi.ans&font=russian&bits=9">
<img src="load_ansi.php?input=ansi.ans&font=amiga">
<img src="load_ansi.php?input=ansi.ans&font=80x50&bits=9">
<img src="load_ansi.php?input=ansi.ans&font=80x25&bits=9&icecolors=1">
<img src="load_pcboard.php?input=pcboard.pcb">
<img src="load_pcboard.php?input=pcboard.pcb&font=80x25&bits=9">
<img src="load_pcboard.php?input=pcboard.pcb&font=80x25&bits=thumbnail">
<img src="load_pcboard.php?input=pcboard.pcb&font=russian">
<img src="load_pcboard.php?input=pcboard.pcb&font=russian&bits=9">
<img src="load_pcboard.php?input=pcboard.pcb&font=amiga">
<img src="load_pcboard.php?input=pcboard.pcb&font=80x50&bits=9">
<img src="load_pcboard.php?input=pcboard.pcb&font=80x25&bits=9&icecolors=1">
<img src="load_binary.php?input=binary.bin&columns=160">
<img src="load_binary.php?input=binary.bin&columns=160&font=80x25&bits=9">
<img src="load_binary.php?input=binary.bin&columns=160&font=80x25&bits=thumbnail">
<img src="load_binary.php?input=binary.bin&columns=160&font=80x50&bits=9">
<img src="load_binary.php?input=binary.bin&columns=160&font=80x25&bits=9&icecolors=1">
<img src="load_adf.php?input=adf.adf">
<img src="load_adf.php?input=adf.adf&bits=thumbnail">
<img src="load_idf.php?input=idf.idf">
<img src="load_idf.php?input=idf.idf&bits=thumbnail">
<img src="load_tundra.php?input=tundra.tnd">
<img src="load_tundra.php?input=tundra.tnd&font=80x25&bits=9">
<img src="load_tundra.php?input=tundra.tnd&font=80x25&bits=thumbnail">
<img src="load_xbin.php?input=xbin.xb">
<img src="load_xbin.php?input=xbin.xb&bits=thumbnail">
Tip Check examples/ansilove.html to see the library in action.
Note If you want your HTML code to validate correctly, you should replace the & characters by &amp; and add an alt element to the img tags.

Library usage

It is also possible to use the library in your PHP applications or scripts:

Loading ansilove.php library in your PHP source

require_once('ansilove.php');

Calling the adequate loaders to convert input files

load_ansi($input,$output,$font,$bits,$icecolors);
load_pcboard($input,$output,$font,$bits,$icecolors);
load_binary($input,$output,$columns,$font,$bits,$icecolors);
load_adf($input,$output);
load_idf($input,$output);
load_tundra($input,$output,$font,$bits);
load_xbin($input,$output);

Retrieve SAUCE Informations

Retrieving SAUCE informations from files can be done using the load_sauce function:

Loading ansilove.php library in your PHP source

require_once('ansilove.php');

Loading sauce informations

$sauce=load_sauce($input_file_name);

The load_sauce function will return an array containing the SAUCE informations:

Array
(
    [ID] => SAUCE
    [Version] => 00
    [Title] => Title
    [Author] => Author
    [Group] => Group
    [Date] => 19970621
    [FileSize] => 1997
    [DataType] => 1
    [FileType] => 1
    [TInfo1] => 80
    [TInfo2] => 29
    [TInfo3] => 0
    [TInfo4] => 0
    [Comments] => 10
    [Flags] => 0
    [Filler] =>
    [Comment_Line_01] => Comment Line
    [...]
    [Comment_Line_255] => Comment Line
)
Note You can find detailed informations about SAUCE (including full specifications) here: http://www.acid.org/info/sauce/sauce.htm

License

Ansilove is released under the BSD 2-Clause license. See LICENSE file for details.

Copyright (c) 2003-2017, Frederic Cambus
All rights reserved.

Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:

  * Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following disclaimer.

  * Redistributions in binary form must reproduce the above copyright
    notice, this list of conditions and the following disclaimer in the
    documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS
BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

Distribution

If you want to add an Ansilove download link on your page, please use the following download link:

https://www.ansilove.org/downloads.html

Ansilove is now also available on GitHub:

https://github.com/ansilove/ansilove-php

Support and Donations

Ansilove is the result of countless hours of coding and testing, in order to provide the most accurate possible ANSi and ASCii conversion tool. If you find this program useful, please consider making a donation, thank you <3

Author

Ansilove is developed by Frederic Cambus.

Site: https://www.cambus.net

Contact

Project Homepage: https://www.ansilove.org

Sister project: https://www.ascii-codes.com

For bug report, feedback, or any other reasons, please write at the following address:

Frederic Cambus <fred AT statdns DOT com>