Ansilove - Documentation

NEWS - DOWNLOAD - DOCUMENTATION - EXAMPLES - LINKS

DESCRIPTION

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

It includes an all purposes command line converter, along with a library to use on web pages for doing "on the fly" conversions.

Features are:

- ANSi (.ANS) format support
- BiNARY (.BIN) format support
- ADF (.ADF) format support
- iDF (.IDF) format support
- TUNDRA (.TND) format support (http://tundradraw.sourceforge.net)
- 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) support
- 80x25 font support
- 80x50 font support
- Amiga font support
- iCE colors support

REQUIREMENTS

Ansilove/PHP requires PHP with the GD module (version greater than 1.6) installed. If you want to convert huge files, you may have to increase the memory_limit size in your php.ini file.

COMMAND LINE CONVERTER USAGE

The command line converter is the file ansilove.
You can invoke it either by typing: php ansilove or simply by ansilove. In the second case, check the file header to ensure the path of your PHP interpreter is correct. Ansilove use /usr/bin/php as default path. FreeBSD users must change it to /usr/local/bin/php

USAGE:	ansilove inputfile columns (.BIN only) font bits icecolors
EXAMPLES:	ansilove ansi.ans ansilove binary.bin 160 ansilove adf.adf

Font can be: 80x25, 80x50, or amiga fonts (8-bit font only)

Amiga fonts can be:

amiga (alias to Topaz+)
b-strict (B-Strict)
b-struct (B-Struct)
microknight (MicroKnight)
mosoul (mO'sOul)
pot-noodle (P0T-NOoDLE)
topaz (Topaz)
topaz+ (Topaz+)
topazplus (alias to Topaz+ to be used in URLs)

Bits can be: 8 (8-bit) or 9 (9-bit) or ced (See below)
iCE colors: 0 (turned off) or 1 (turned on)

Setting the bits to 'ced', will cause the input file to be rendered in black on gray (only available in ANSi loader).

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.

Files with a .DIZ extension are rendered with the exact needed number of columns.

All the amiga fonts come from the excellent t!s-af07.zip package by dMG, which is available here: http://www.trueschool.org

Supported options for each file format:

	Columns	Font	Bits	iCE colors
ANS		X	X	X
BIN	X	X	X	X
ADF
IDF
TND		X	X
XB

LIBRARY USAGE FOR ON THE FLY CONVERSIONS ON WEB PAGES

Use of the ansilove.php library for doing "on the fly" conversions on web pages, is done via these loaders:
load_ansi.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. This value is defined in the config file by the constant 'ANSILOVE_FILES_DIRECTORY'. The ending '/' is required.

Don't unset this defined constant, else it'll be possible to convert files laying in the same directory than the loaders, which could lead to possible security leaks.

Please note that the input is sanitized, so it is impossible to use / and .. in the input.

Then you just include custom IMG tags in your HTML code, like this:

<IMG SRC="load_ansi.php?input=ansi.ans">
<IMG SRC="load_ansi.php?input=ansi.ans&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&icecolors=1">

<IMG SRC="load_adf.php?input=adf.adf">

<IMG SRC="load_idf.php?input=idf.idf">

<IMG SRC="load_tundra.php?input=tundra.tnd">
<IMG SRC="load_tundra.php?input=tundra.tnd&font=80x25&bits=9">

<IMG SRC="load_xbin.php?input=xbin.xb">

Check examples/ansilove.html to see the library in action.

ANSILOVE ONLINE

Since version 1.02, Ansilove/PHP features an online converter allowing people to upload their stuff to be converted with their WEB browser. If you want to offer this feature on your site, install the library (See: LIBRARY USAGE), and also copy the 'online' directory in the same directory than the library.

The 'online' directory contains an 'upload' directory which will receive the uploaded files. It needs to be accessible by the HTTP server, so you have to set the permissions accordingly, or to set it world writable (chmod 777 upload). The 'upload' directory contains a .htaccess to restrict its access (Deny to all by default).

It is advised to put the 'upload' directory outside of the web space, if possible.

This path of the 'upload' directory is defined in the config file by the constant 'ANSILOVE_UPLOAD_DIRECTORY'. The ending '/' is required.

You can now change the 'online' directory name to whatever name you want, without touching any configuration file.

LIBRARY USAGE

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

Load ansilove.php library in your PHP source:
require_once('ansilove.php');

Then call the loaders to convert your stuff:

load_ansi($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

If you need to retrieve sauce informations from files:

Load ansilove.php library in your PHP source:
require_once('ansilove.php');

Then load sauce infos:
$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
)

LICENSE

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

DISTRIBUTION

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

http://sourceforge.net/project/showfiles.php?group_id=151229

CONTACT

For contact informations, please read the README file included in the releases.