
                   !KISSTools V1.03
                   ~~~~~~~~~~~~~~~~

  INDEX

  1 - Background to KISS (and plug for my KISS viewer, !PlayKISS)
  2 - Overview of !KISSTools functionality
  3 - GUI interface
      3.1 - Sprite->CEL conversion
      3.2 - CEL->Sprite conversion
      3.3 - Palette->KCF conversion
      3.4 - KCF->Palette conversion
      3.5 - Repaletting sprites or cels.
      3.6 - Describe file(s)
  4 - Command Line Interface
      4.1 - sprtocol  : Sprite->CEL conversion
      4.2 - celtospr  : CEL->Sprite conversion
      4.3 - paltokcf  : Palette->KCF conversion
      4.4 - kcftopal  : KCF->Palette conversion
      4.5 - repalette : Repaletting sprites or cels.
      4.6 - kissinfo  : Describe file(s)
      4.7 - shrinkpal : Reduce the number of colours in a palette
  5 - Other tools (plug for my KISS editor, !MakeKISS)
  6 - LZH files, and their problems on RISC OS
  7 - License conditions
  8 - Disclaimer
  9 - Bug reports/contacting me

      History


1. KISS Background

KISS is a paper doll program which originated in Japan in 1991.
It was originally developed for a NEC computer, but has been
ported to a number of operating systems & platforms including
Windows, MacIntosh and Amiga.

To help spread KISS, the specification was formalised (and
broadened, to allow for more capable hardware). This is known
as the KISS General Specification (KISS/GS), and is available
on the web on "The Big KISS Page" at:

   http://otakuworld.com/dov/kiss/index.html

KISS/GS is absolutely required reading to create or edit your own
dolls, so this help file assumes you are familiar with the KISS/GS
terminology.

There is a variant of KiSS known as Cherry KiSS (why, I don't know).
Standard KiSS uses 4 or 8 bpp colour images as the basic building
block; Cherry KiSS uses true-colour (24 bpp) images. From version
0.3, KiSSTools provides some not-very-good support for Cherry KiSS
as well.

To view KISS dolls on an Acorn RiscPC, use my !PlayKISS program
(from V3.00, PlayKISS supports Cherry KISS).


2. !KISSTools overview

!KISSTools is a very simple tool to help create and KISS dolls,
that can be run either as a Wimp application or from the command
line (assuming that KISSTools has been seen by the filer).

It provides a number of functions:

    i) Convert sprites to CEL files.

   ii) Convert CEL files to sprites.

  iii) Convert RISC OS palette files to KISS "KCF" palettes.

   iv) Convert KCF files to RISC OS palette files.

    v) Sprite or CEL repaletting (i.e. changing a sprite or
       cel so as to use a different palette)

   vi) Provide simple descriptions of sprites, CELs, palettes
       and KCFs.

  vii) Reduce the number of colours in a palette (by removing
       similar colours)

These are described in the following sections.


3. GUI Interface

This section describes the use of KISSTools via the GUI interface.

A mixed set of sprites, palettes, and data files can be dragged to
the iconbar, and they will be processed in turn (but ordered by
type). If the "Cancel" button on a Save As box is selected, that
file AND ALL THE OUTSTANDING FILES are discarded.

Normally, dragging a KISS-related file to the iconbar will invoke
one of the file conversion functions, depending on the type of file
dragged. However, if the "Describe Only" item on KISSTools' iconbar]
menu is selected, future drags will invoke "describe file" (3.6).
This will continue until the "Describe Only" menu item is unticked.


3.1 Sprite->Cel conversion

Any sprite of 256 colours or less can be converted to KISS/GS2
cels; in addition, sprites of 16 or fewer colours can be converted
to KISS/GS1 sprites.

To convert a sprite, simply drag the file it to the iconbar icon;
you will be presented with a normal "Save As" box (filetype "Data")
with a default filename generated from the sprite name.

The Save As box has the following options:

  Trim   : If ticked, all transparent rows and columns around the 
           edges of the sprite will be removed.

  GS2+   : If ticked, the sprite will be converted to a KISS/GS2
           or later format cel. If "Trim" is not selected, left
           hand transparent columns and top transparent rows will
           be removed, and the "offset" fields in the cel header
           set to compensate.

  Cherry : If ticked, allows 16 or 32 bpp sprites to be converted
           into Cherry KiSS cels. NB. If this is selected, GS2+
           rules for trimming are applied, irresepctive of
           whether the GS2+ option is enabled.

If the sprite file contains more than one sprite, they will be
processed in sequence (ie after each sprite is converted, the
Save As box will open again for the next sprite).

NB As KISS defines colour 0 to mean "transparent", all pixels in
the sprite that are either masked or are colour 0 will be mapped
onto colour zero (this does not apply to Cherry KiSS).


3.2 Cel->Sprite conversion

To convert a CEL file, drag it to the iconbar icon; a Save As
box will appear. There are no options for this conversion.

CEL files will be converted to MODE 27 sprites (16-colour CELs)
MODE 28 sprites (256-colour CELs), or a "deep" sprite for Cherry
KiSS CELs. If the CEL file is a new-format CEL (ie KISS/GS2),
the sprite will have transparent rows and/or columns added
at the top and left to account for any "offset" fields in the CEL
header.

Sprites generated from non-Cherry KiSS cels will have a bizarre
appearance using the default desktop palette (as they have no
palette). To view it as it should be, convert its KCF file to a
RISC OS palette file, and drop the palette into the sprite editing
window in !Paint.

NB CEL files must be file-typed "Data", and should be correctedly
named (ie terminate with "/cel") for !KISSTools to recognise them.

NNB !PlayKISS also provides a Cel export facility to extract all
the cels into a single sprite file. However, they are "New Format"
sprites (ie with a 1 bit-per-pixel mask), and !Paint  will not
allow the palette to be set by dragging and dropping a palette
file. The !PlayKISS cel export facility should therefore be seen
as giving an overview of the available cels, rather than a tool for
building dolls.


3.3 Palette->KCF conversion

To convert one or more palette files into a single KCF file, drag
them to the iconbar. A Save As box will appear, with the following
options:

  GS2+ : If ticked, the resulting KCF file will be in KISS/GS2
         format.

  12 bit ) These define the accuracy of the palette. KISS/GS1
         ) files only allow 12-bit accuracy, so this is disabled
  24 bit ) if the GS2+ option described above is not ticked.

KCF files contain between 1 and 10 palette groups, Multiple groups
can be contructed by dragging multiple palette files to the iconbar
(or the Save As box after it has opened); each palette file will
generate a separate group (the number of palette groups in the KCF
file is shown on the Save As box.

Palettes are not used for Cherry KiSS.


3.4 KCF->Palette conversion

To convert one of the palette groups in a KCF file to a RISC OS
palette, drag the KCF file to the iconbar. A SaveAs box will
appear, with a control which allows a palette group number to be
specified for the conversion.

If the palette group number specified is greater than the number of
groups in the file, the highest numbered group is converted.

NB KCF files must be typed as "Data", and should be correctedly
named (ie terminate with "/kcf") for !KISSTools to recognise them.


3.5 Repaletting sprites or cels.

The repalette function is used to change a cel in such a way that
it will look as near as possible the same but with another palette.
For example, if a cel has been created with a particular palette,
and then (e.g. to avoid exceeding 256 colours) the palettes are
redefined, cels can be automatically adjusted to allow for this.
Note that it is even possible to change the number of colours
in the palette from 16 to 256 or vice-versa (although in the latter
case if source file uses more than 16 colours, the result will be
of lower quality. The function will work whether the source file
is a sprite or a cel file, and whether the original and/or new
palettes are palette files or kcfs, in any combination. The output
file will be of the same type (sprite or palette) as the input file.

Repaletting requires a more complex interface than the simple
file-conversion functions described above; the dialog box used to
control repaletting is invoked by clicking on the KISSTools iconbar
icon. Schematically, the dialog box looks like this:

  +-----------------------------------+
  |   +---------+       +---------+   |
  |   | Source  |       |         |   |
  |   | Bitmap  |       | OldPal  |   |
  |   |         |       |         |   |
  |   |         |       |         |   |
  |   +---------+       +---------+   |
  | +-------------+   +-------------+ |
  | +-------------+   +-------------+ |
  |                                   |
  |   +---------+       +---------+   |
  |   |         |       | Output  |   |
  |   |  NewPal |       | Bitmap  |   |
  |   |         |       |         |   |
  |   |         |       |         |   |
  |   +---------+       +---------+   |
  | +-------------+   +-------------+ |
  | +-------------+   +-------------+ |
  +-----------------------------------+
  |     Cancel              OK        |
  +-----------------------------------+

Files can be dragged to the source bitmap area (sprites or cels),
and the oldpal and newpal areas (palettes or kcfs). The output
bitmap can then be dragged to a filer window, to invoke the
repalette operation.

The 'OK' button and the output bitmap icon and name will be faded
until enough information has been provided to allow the operation
to be performed:

   1) One or more source bitmaps have been dragged to the source
      bitmap area.

   2) A single palette has been dragged to the new palette area.

   3) A single palette has been dragged to the old palette area,
      unless the bitmap is a sprite, in which case this is optional.
      (Note, however, that if the sprite file contains a sprite
       without a palette, the repalette operation will fail).

The dialog box will remain open until the 'Cancel' button is clicked.

NB While the dialog box is open, it will not be possible to perform
file conversions by dragging files to the iconbar icon.


3.6 Describe file

If the "Describe Only" iconbar menu item is selected, dragging a
sprite, palette, CEL or KCF to the KISSTools' icon will invoke this
function.

TO generate the information, drag the text icon from the saveas
dialog box to a filer window. The meaning of the various option
buttons, etc on the dialog box is best deduced from reading the
description of this function in the Command Line Interface section
(section 4.6 kissinfo).


4. Command Line Interface

So long as KISSTools has been seen by the filer, a number of
CLI commands are provided to perform the same functions as the
wimp interface.

The general format of a command is:

   <command> [options] <inputfile>[,<inputfile>...]

with the options available varying from command to command.

Although the options shown have long (and hopefully meaningful)
names, they can always be truncated to one or two characters
(just enough to be uniquely distinguishable from other options).
The options described under each command show the minimum usage
in upper case, although the options are also case-insensitive.
Hence, "-CHerry" means that any of -ch, -che, -cher, -cherr or
-cherry are aceptable, (but -c is not).

All commands allow the following options:

  -Output <filename>  Rather than using the default filename for
                      the output cel, sprite or whatever, use
                      <filename>. The use of this qualifier may
                      limit the command in some way - this is
                      described under each command.

  -Force              Normally the commands will fail when if
                      the output file already exists. This
                      option will force overwriting of any
                      existing file.

  -Verbose            Give progress reports.
                      

The use of RISC OS wildcards ('*' for any sequence of characters,
'%' for exactly one character) for the input file(s) is legal for
file conversion functions only.

KISSTools uses these in an intelligent fashion, so that only
files of the correct type are considered. Hence, in the command
"paltokcf *", the * will match all the RISC OS palette files in
the current directory.

The remainder of this section describes the commands, what they
do, and what additional options are available.

4.1 sprtocel - sprite to cel conversion

All sprites in all input files (which must be sprite files)
are converted to cels. The default output file names are created
from the sprite names (not the spritefile names), with "/cel"
appended where necessary.

Extra options:

  -GS1     Force KISS/GS1 cels (i.e. 16-colour only).
  -CHerry  Allow 32bpp sprites to generate Cherry KISS cels
  -Trim    Remove any transparent columns and lines before
           the conversion. (Use with care. Transparent columns
           and lines are used to offset cels from the position
           of the parent object. KISS/GS2 converts these to
           offsets in the header block anyway).

If the -output option is given, only a single input file is
allowed, and only the first cel will be converted.

Examples:

   sprtocel -output tharg/cel piccy
 
(Generate a cel file called tharg/cel from the first sprite inside
the spritefile piccy)

   sprtocel -gs1 -f -v tharg,eric

(Generate a cel file from each sprite inside tharg and eric. Any
existing files of the same name will be overwritten (-f), and the
user will be informed of progress (-v)).

4.2 celtospr - cel to sprite conversion.

All cels in the input files (which must be data files called
something-or-other/cel) will be converted to sprites. The sprite
files will be named as the cel files, but without the /cel.

Extra options:

  -COlour <palette>   Include the palette in file <palette>. This
                      can be a RISC OS palette or a KISS kcf file.
  -GRoup <groupno>    If a kcf file is provided, use palette group
                      <groupno> (default is zero).

If the /output option is given, all sprites will end up in the same
spritefile.

Example:

   celtospr -out tharg tharg/cel,eric/cel,norman/cel

(Create a sprite file called "tharg" which contains 3 sprites,
generated from tharg/cel, eric/cel and norman/cel).

4.3 paltokcf - RISC OS palette to KISS palette (kcf) conversion

All the input RISC OS palette files (which must be filetyped as
such) are converted to kcf files. The default output filenames
are generated from the RISC OS palette filenames, with "/kcf"
appended.

Extra options:

  -GS1     Generate a KISS/GS1-style kcf file. (i.e. no more than
           16-colour palettes).
  -BPp12   Generate a kcf file with 12-bit colour entries rather
           than 24-bit entries. (I'm not sure why you'd want to
           do this, but the KISS/GS2 spec allows it).

If the -output option is given, all the input palettes are used to
form a kcf file with multiple palette groups (one per input file).
In this case, there may be no more than 10 input files.

Example:

   paltokcf -out kiss/kcf -f pal1,pal2,pal3

(Generate a kcf file with 3 palette groups generated from the 3
input files. Any existing file called kiss/kcf will be overwritten).

4.4 kcftopal - KISS palette (kcf) to RISC OS palette conversion.

Each input kcf file (which must be filetyped as Data and named
something-or-other/kcf) are converted to RISC OS palette files. The
default output filenames are as the input filenames with the /kcf
stripped off.

Extra options:

  -GRoup <n>   Specify which palette group to convert from the
               kcf file. By default, palette group 0 (the first)
               is converted. If <n> is greater than 9, an error
               is reported.

If the -output option is given, only a single input file may be
specified.

Example:

   kcftopal -out fred -group 1 eric/kcf

(Generate a RISC OS palette file called fred, using palette group
1 from eric/kcf).

4.5 repalette - associate a cel or sprite with a new palette

The format of this command is somewhat different to the others:

  repalette [options] <infile>[,<infile>...] <newpal> [<oldpal>]

Each <infile> is either a spritefile or a cel file, while <newpal>
and <oldpal> may be either palette files or kcf files. If each
<infile> is a spritefile where all sprites have palettes, <oldpal>
need not be provided (the old palette is assumed to be that for
the sprite). However, if oldpal is provided, it will override any
internal sprite palettes. If <infile> is a cel or a spritefile
containing an unpaletted sprite, <oldpal> is required.

By default, the output files have the same names as the input files,
but the input files are saved under a new name (a spritefile will have
"/bck" appended; a cel file will be modified so the new name ends
/ce_ rather than /cel). The -output qualifier is legal only if there
is a single input file.

Extra options:

  -BAckup <name>   Provide an alternative name for the backup file.
                   Only legal for a single input file. This option
                   may not be used with -output.
  -NOBAckup        Do not produce a backup file. This option may not
                   be used with -output.
  -GRoup <groupno> If newpal (or oldpal) are kcfs rather than palettes,
                   use palette gorup <groupno> (if -group is not given
                   group zero is assumed).

Example:

   repalette -backup oldtharg tharg pal1

(If tharg is a sprite file, alter the cel to reflect the palette pal1
rather than it's own internal palette. The original version of tharg
will be saved in 'oldtharg'.).

  repalette -noback eric/cel,tharg/cel,normal/cel new/kcf old/kcf

(The three cels eric/cel, tharg/cel and norman/cel are adjusted to
use the palette new/kcf rather than old/kcf; they will not be
backed up).

4.6 kissinfo - provide general information about a cel or palette

Each input file (which may be cels, kcfs, sprites or palettes) is
read and basic or more detailed information is provided. The file
descriptions are by default shown on screen, but may be directed to
a text output file using the "-output" qualifier.

The basic information provided for a file is:

   cel/sprite:   Width, height and colour depth (bpp) for the image.
   kcf/palette:  Number of colours, and a table of colour number
                 vs r,g,b values (both as 0-255 values and as
                 percentage saturations). kcf files also report
                 the number of palette groups, whether the file is
                 a KISS/GS1 file, and the number of bits used to
                 define a colour.

Extra options:
  
  -Tabulate     For sprite/cel files, generate a histogram of colour
                number vs frequency of use (indexed colour cels only).
                For palette/kcf files, generate a table of colour
                values against colour numbers.
  -DUplicates   For palette/kcf files, indicate any duplicated colours
                found (only if -tabulate)
  -GRoup <n>    Specify which palette group is to be tabulated in any
                kcf files. If -group is not given ALL palette groups
                are tabulated. 
  -By_frequency For sprite/cel files, if -tabulate is given output the
                table in frequency order (the table is also truncated
                after the first zero count - all unspecified colours
                are also zero)

Example:

  kissinfo -o info -tab -by_freq -dup tharg/cel,pal/kcf

Write detailed information about files tharg/cel and pal/kcf to text
file "info", including the colour values of the colours in all groups
in pal/kcf, and a frequency-sorted pixel histogram for tharg/cel.

4.7 shrinkpalette - reduce the number of colours in a palette

Each input file (which may be RISC OS palette files or kcfs) is checked
for duplicated (or near-duplicated) colours, and any duplicates removed.
The reduced palette is then written out, with unused colours all set to
black (and all moved to the top of the colour space). If the source
palette can be reduced to 16 colours or less, the output palette will
be converted to 16 colours.

As for the repalette function, by default the output palette file has
the same name as the input palette, with the input file being copied to
a backup file.

Optionally, a bitmap (cel or spritefile) can be provided; if present, the
palette will first be reorganised to put the most-frequently-appearing
colours earliest in the palette. This is most usefully combined with the
-protect qualifier (see below) to ensure that the colours that appear most
frequently are kept distinct.

Extra options:

  -GRoup   <grpno>   Specify which palette group to shrink. This is ignored
                     if the source file is a palette file rather than a kcf.
                     If not present, ALL groups in the source kcf will be
                     shrunk.
  -DElta   <error>   This qualifier can be used to specify how similar two
                     colours need should be to be trated as the same colour.
                     The error term is a real number in the range 0.0 - 100.0;
                     0.0 means the two numbers must be identical; 100.0 will
                     mean that ALL colours are the same as all other colours.
                     The default is 0.0
  -PRotect <numcols> This qualifier makes KISSTools treat the first <numcols>
                     colours differently to the remainder of the colours - 
                     irrespective of the delta value given above, colours
                     in the protected range will only be treated as the same
                     if they are identical (i.e. the delta value is set to
                     zero for the first <numcols> colours in the palette).
                     This is most useful if the optional bitmap file is
                     also provided; it will have the effect of ensuring that
                     the <numcols> most common colours in the bitmap are
                     kept distinct.
  -BAckup <name>     Provide an alternative name for the backup file.
                     Only legal for a single input file. This option
                     may not be used with -output.
  -NOBAckup          Do not produce a backup file. This option may not
                     be used with -output.

Example:
  shrinkpalette -delta 5.0 -protect 8 tharg/kcf tharg/cel

All palette groups in the file tharg/kcf will be shrunk with a minor loss
of resolution (due to the -delta 5.0). The 8 most-frequently-appearing colours
in the cel tharg/cel will be protected from modification. tharg/kcf will be
backed up to tharg/kc_, and overwritten.

5. Other tools

!MakeKISS, a KISS doll development tool, is now available, which
provides a number of sophisticated doll editing facilities.

Although it provides similar file conversion facilities as
!KISSTools, it is not a complete replacement, as the latter is
much more convenient for converting large numbers of files.


6. LZH archives

Unfortunately, SparkFS only provides read access to LZH archives,
not write access. An appropriate archiver, lharc (and its desktop
front end, DTLharc) is available from my web site, at:

   http://www.argonet.co.uk.users/tigger/programs/progs.html

 
7. License Conditions

!KISSTools is NOT Public Domain. However, copies may be passed on
to other people as long as the following conditions are met:

 (1) Copies may be passed between private individuals as long as
     this is done free of charge.

 (2) It may be distributed by public domain libraries, as long as
     no charge is made other than for the media.

 (3) It may be distributed by remote databases such as FTP sites
     or mail servers on InterNet or bulletin boards, as long as no
     charge is made for downloading it (other than the cost of the
     phone call).

 (4) The copyright remains with me at all times.

 (5) It is distributed in its entirety, including these conditions.


8. Disclaimer

!KISSTools is distributed "as is", and used at your own risk. I
accept no responsibility for damage to your computer, your data,
or even the possibly addictive effects of KISS.


9. Further information & bug reports

If you have any problems with !KISSTools, please contact me at the
email address given below, and I'll try to fix them.

Nick Roberts
tigger@argonet.co.uk

=====================================================================

History:

Version       Description

  0.1         First general release. Probably a bit "beta".
  0.2         Fixed default name in sprite->cel conversion saveas.
  0.3         Added simple support for "Cherry" KiSS truecolour cels.
  0.4         Fixed minor bug with 16 colour cels.
  0.5         Fixed bug with transparency for cels with an offset.
  0.6         Internal rewrite to use common code with MakeKISS
  0.7         Now uses version 2 of the shared KISS code.
              Name of cel in a sprite->cel conversion could contain
              a period (if the source sprite did). Now fixed.
  0.8         Stupid error in conversion from 256-colour sprites to
              cels - didn't allow for difference between GCOL and
              colour number. Now fixed. Also, uses V3 of Shared KISS
              code.
  0.90        Provision of command-line interface, allowing batch
              processing of file conversions.
  0.91        New 'Repalette' function.
  0.92        New 'kissinfo' command.
  0.93        New 'shrinkpal' command, and GUI version of kissinfo.
  0.94        Fixed bug in Cherry cel->sprite conversion.
  0.95        kcf to palette conversion "SaveAs" dialog box: The
              group number control is now constrained to the number
              of groups actually available in the kcf.

  1.00        26-bit/32-bit neutral.
  1.01        Hopefully A9-compatible, which it may not have been
              before.
  1.02        Recompiled for Cortex A8 (Beagleboard)
  1.02-1      Changed web site address on ProgInfo to reflect changes
              to riscos.org.uk.
  1.03        Recompiled/linked for Raspberry Pi & to remove stubsg