ftmap

Creates a GIF map of a Full Thrust game

Contents

Usage: ftmap -a -b -d -f output.gif -g -i imagedir -l -r resource_file -t -v -w

ftmap reads a fomatted file from the standard input and produces an interlaced GIF map of the data, according to the parameters contained within the file. ftmap does text clash management so that the labels on the map are positions for the best readability. ftmap also does sophisticated color compression so that multi-color maps can be produced within the limited 256 color palette of a GIF image.

Example

ftmap -b -i image -f example.gif < example.ft

Produces a bitonal map (white background, black foreground) in the file example.gif using the data in the file example.ft

Program flags

-a apply image resampling, this doesn't work very well on a white background, it works best for images on a black background. It also takes a lot longer to create the map.

-b bitonal mode, uses a white background and inverts the game object bitmaps to be black. Any background image or color resource file is ignored. This mode is used for producing maps that can be printed or emailed as the bitonal maps are small

-d debug mode currently draws boxes for the text clash resolution system and various ugly messages

-f followed by name of the resuting gif map file -g add a reference grid to the map axes, this is set at 10 game units

-i followed by name of directory to search for the game object images, this allows several sets of images to be used and managed

-l draw a legend of the game objects, this can take up a lot of room and is not subject to rigorous clash detection with existing text

-r followed by name of the resource file containing color definitions for the main elements of an ftmap, *ignored* if -b specified

-t if object tracks are enabled then plot them as Real Thrust vectors, not as Full Thrust cinematic movement plots

-v verbose mode it tells you whats its doing on

-w if background image is enabled, wallpaper/tile the background image instead of stretching it to fit

Format of the Data File

Ok, now for the format of ftmap's data file, Generally blank lines are not tolerated and comments etc. are not supported.

The first section defines the map parameters

Header Section

<1> Title
<2> Background gif filename or '-' to use a plain background
<3> object tracks flag - 1 on, 0 off
<4> min x co-ord (in game units)
<5> min y co-ord (in game units)
<6> max x co-ord (in game units)
<7> max y co-ord (in game units)
<8> number of pixels per game unit

Example

Numbers are reference to the fields described and should not be included in actual file 
<1> FT Example Map
<2> -
<3> 1
<4> -15.0
<5> 0.0
<6> 85.0
<7> 70.0
<8> 10.0

Notes

This section has a fixed length format and thus requires no delimiter for the next section following. There next follows a section defining the available game object classes and the images to use.

If using Field <3> object tracks on, their plotting varies according to the -t program flag being supplied or not.

If using the -t option the Real Thrust object tracks is displayed as a vector along the current heading (which must be specified in degrees not clock facing) with a magnitude of the current velocity, it shows where the ship will be next turn, if no thrust is applied.

This is the reverse of the cinematic movement object tracks, which show how the ship moved for the current turn.

Game Object Image Section

<1> The game object CLASS NAME
<2> The file name of the gif used for the class (pointing in direction 12)
<3> Scale factor for displaying the gif 
<4> Legend flag ( 1==list class in legend, 0==don't list class in legend)

Example

Numbers are reference to the fields described and should not be included in actual file 
<1> Hyperion
<2> ea_bc.gif
<3> 1.0
<4> 1
*

Notes

This is repeated for each class, with a line containing a single * indicating the end of the section. There follows a section describing each ship or other game object (fighter, missile, asteroid).

Game Object Section

<1> Name (can contain white space)
<2> CLASS NAME exact match to <1> in [Game Object Image Section])
<3> x co-ord
<4> y co-ord
<5> heading (1-12)or(1-360)
<6> facing (1-12)
<7> velocity
<8> change of heading delta (S=+ve, P=-ve e.g. p3 = -3, S2 = 2)

Example

Numbers are reference to the fields described and should not be included in actual file 
<1> NERGAL
<2> Hyperion
<3> 14.2
<4> 28.3
<5> 8
<6> 8
<7> 9
<8> 0
*

Notes

This is repeated for each class, with a line containing a single * indicating the end of the section.

Field <5> is in clock facing (1-12) for cinematic movement and degrees (1-360) for real thrust movement.

Field <8> applies to cinematic movement only and is ignored if using the Real Thrust -t flag, although a dummy value must be present in the file.

Data File Example

FT Map Example
-
1
-15.0
0.0
85.0
70.0
10.0
Omega
ea_cv.gif
1.0
1S
Hyperion
ea_bc.gif
1.0
1
*
JASON
Omega
15.7
37.3
12
12
5
1
NERGAL
Hyperion
14.2
28.3
8
8
9
0
*

Fomat of Game Object Images

The game object images are stored in individual gif files. One image per file. The default orientation of the file should be with the game object facing the 12 o'clock position

Example

The convention is for the image background to be black and the image foreground to be white or color, *breaking the convention will produce the wrong results*.

Color images are supported where the image background is black and the foreground various colors. For producing bitonal maps (white background black foreground) the conventional images are inverted by the program automatically.

The images can be any size but typically not too big (33x33). The images are scaled according to the scaling factor in the data file The images can be of any game object a ship, fighters, missiles, asteroids etc.

Resource File

The -r file for ftmap allows the use of a separate resource file which controls the appearance of the ftmap. The resource file is made up of sections denoted by '[' ']' i.e. [Color] and within a section a resource name is allocated a value. The section and resource names are case insensitive but must be spelt correctly. A resource name has a following '=' and then its values separated by white space.

ftmap only supports a Color section at this time. The resource file can contain comments beginning with ';' on a separate line or the end of a line. The example shows the current color resources and what they apply to. The -r option colors are currently ignored if you use the -b flag.

Example

;******************************************************************************
; ftmap color resource file
;
; The section identifier [Color] must be present & spelled correctly
;
; Resource names are case insensitive & must be spelled correctly
; The '=' must follow the resource names.
;
; Color values are given as red blue and green values between 0 - 255
; separated by white space
;
; History:
; 25-Feb-1997 Tim Jones
; Created
;******************************************************************************
;
[Color]
;------------------------------------------------------------------------------
;                    r    g    b
;                       0 - 255        comments
;------------------------------------------------------------------------------
backgroundColor =    0    30   0     ; background MUST always be specified first
foregroundColor =    0    255  0     ; replaces white in the image bitmaps
titleTextColor =     0    255  0     ; map title
axesColor =          0    200  0     ; x & y axes
axesgridColor =      0    100  0     ; axes grid
axesTextColor =      0    220  100   ; axes text
labelTextColor =     0    200  96    ; label text
leaderColor =        0    150  96    ; leader line from label
courseColor =        0    255  100   ; game object course tracks
locusColor =         200  255  100   ; accurate centre of game object
legendColor =        0    200  0     ; legend box
legendTextColor =    0    200  100   ; legend text
;******************************************************************************

Important

backgroundColor is a special resource as it MUST be the first color in the file so that the GIF image has the correct transparency. The foregroundColor is also a special resource as this changes the foreground color (white) of conventional images to the specified color. The results with non conventional images will be undefined.

Formatting Data File From Game Report

The ftmap data file format is optimised for computer reading but is difficult for humans to read. Typically a game will produce reports which can be parsed and formatted into the correct data file format by tools such as awk or perl. as a last resort you can type in the data yourself.

Header File

Typically the game header section in the data file doesn't change and is stored in a separate file that the text processing filter includes into the final data file. These lines have the HEADER: so that the text filter can recognise them.

Example

HEADER: FT Map Example
HEADER: -
HEADER: 1
HEADER: -15.0
HEADER: 0.0
HEADER: 85.0
HEADER: 70.0
HEADER: 10.0
HEADER: Omega
HEADER: ea_cv.gif
HEADER: 1.0
HEADER: 1
HEADER: Hyperion
HEADER: ea_bc.gif
HEADER: 1.0
HEADER: 1
HEADER: *
There is an example awk program supplied example.awk that parses a game report example.rpt into the ftmap data file format example.ft.

Map Making Procedure

Typical procedure for producing a map is thus.
  1. Edit the header file to change the title etc.
  2. Edit the report file to conform to the text filter program, this may require fiddling with information so that is all looks the same. As most people seem to do this manually there are often formatting mistakes. Its a trade off between a simple text parser and a complicated one that can cope with various idiosyncrasies in the report format. This is the bit *you* have to figure out
  3. Run the text processor to produce the data file this merges the turn header with the data in the report to produce the data file ftmap requires.

    4. Example:

    awk -f example.awk example_header example.rpt > test.ft

  4. Produce the map using ftmap and the data file. if it core dumps its probably a problem with the data file, so check that first.

    5. ftmap -r ftmap.ini -i image -f example.gif < example.ft

  5. View the image and check for funnies, repeat from 2) to eliminate errors.

    6. Example

Known Problems

Authors

ftmap is the intellectual property of Alun Thomas, it was conceived by him. I Tim Jones have extended the original work by adding various options, creating the distribution and documentation.

Distribution

This program is freeware and can be distributed as long as you don't claim its yours or try to make money out of it or modify the source in any way. The source code is included (Unix only) so you can build the program but please don't modify it without permission.

New Features Version 1.8.1

New Features Version 1.8.2

Certain resources in the ftmap init file no longer have default values if they are undefined these are:

They can be commented out in the init file by using the comment character ';' semi-colon or omitted all together.

If a text label has a null value then the label should not be plotted. A null value is a line with nothing on it but a carriage return.

Unix

The distribution is in file 

ftmap1-8-2_tar.gz - base pack

README.txt        - documentation
README1-8-2.txt   - additional release notes for 1.8.2
ftmap.c           - source code
ftmap.ini         - resource file
gd1.2.tar         - gd image library
Makefile          - makefile example
example.awk       - awk program example
example.hdr       - turn header example
example.rpt       - example turn report 
example.ft        - ftmap example data file uses example.tar images 
ex_img.tar        - example images

Procedure

I'd create a structure like 
    $HOME/ftmap
    $HOME/ftmap/image

  1. download ftmap1-8-2_tar.gz.

  2. gunzip and unpack ftmap1-8-2_tar.gz in $HOME/ftmap

  3. unpack gd1.2.tar in $HOME/ftmap. it will create $HOME/ftmap/gd1.2 ,go there. Modify $HOME/ftmap/gd1.2/Makefile there for you platform and make libgd.a there using 'make'.

  4. go to $HOME/ftmap and modify the ftmap Makefile for you platform compiler and to point the libgd.a library from step 2) and where to install the program; if different; then

    make ftmap

  5. move ex_img.tar to $HOME/ftmap/image and unpack ex_img.tar there, these are the example images

  6. from a console window 
        cd $HOME/ftmap
    ftmap -i image -f example.gif < example.ft

  7. this should produce example.gif which you can view with your favourite paint program (xv) or browser.

Upgrading

  1. download the latest source code

  2. rename the latest version of the source code ftmap.c to ftmap.c

  3. remake the executable

    make ftmap

  4. modify batch files and data files to make use of the latest features

Win32

ftmap_1_8_2.zip - base pack

README.txt        - documentation
ftmap.exe         - the ftmap program
ftmap.ini         - resource file
example.awk       - awk program example
example.hdr       - turn header example
example.rpt       - example turn report 
example.ft        - ftmap example data file uses example.tar images 
ex_img.zip        - example images

Procedure

The Win32 distribution doesn't need building just un-pack the files and your ready to go, I'd create a structure like 
    C:\ftmap
    C:\ftmap\image
  1. unpack ftmap_1_8_2.zip in C:\ftmap

  2. move ex_img.zip to C:\ftmap\image and unpack ex_img.zip there, these are the example images

  3. From a console window (DOS box) 
        cd C:\ftmap
    ftmap -i image -f example.gif

  4. this should produce example.gif which you can view with your favourite paint program or browser.

Upgrading

  1. download the latest version of ftmap.exe

  2. rename it to ftmap.exe

  3. modify batch files and data files to make use of the latest features
Modified 8-Dec-1997 Tim Jones
Updated for corrections 29 October 1998 1