Sprite Assembler v1.0
    User's Guide
---------------------

Sprite Assembler (SA) automates the process of combining separate frames
of animation (in the form of BMP files) into one final TIM file which
you can incorporate into your Yaroze program (or alternately you can
output into another BMP file).

As the program is entirely command-line driven, this file documents the 
various switches you can use to direct the flow.

=========================================================================
Command Line
------------

Usage:  sprtasm <arguments> <outfile>

Arguments:
  -ci    = Crop all BMPs individually
  -cw    = Crop all BMPs according to worst BMP height & width
  -crb   = Crop rectangle according to any black color table entry
  -cr#,# = Crop rectangle according to color at coordinates #,#
  -t#    = Cropping color tolerance
  -tc    = Convert colors if within tolerance
  -h#    = Resize all BMPs to height of #
  -w#    = Resize all BMPs to width of #
  -a-    = Decrease height or width to maintain aspect ratio
  -a+    = Increase height or width to maintain aspect ratio
  -r#    = Concatenate # BMPs per row
  -f     = Denotes beginning of input file list
  --     = Denotes end of input file list
  -i     = Generate intermediate files
  -?     = Prints this help screen

=========================================================================
Command examples
----------------

Examples of all of these parameters are given on the web page
http://www.scea.sony.com/net/yaroze/pages/scartier.html

A copy of the relevant web page is included in this zip.  It is in the
subdirectory "html".

Also a "tutor" directory was extracted from this zip.  In it you will
find five tutorial examples numbered TUTOR1.BAT through TUTOR5.bat.
Run through them to get a feel for how to actually use the program.

If neither of these directories exist then you probably need to unzip
again using the "-d" option.

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

The Sprite Assember flow
------------------------
o Read input files to compare color tables
    * Right now SA can only work on inputs which have identical color
      tables.
    * SA can only read uncompressed 8- or 4-bit BMP files (I can add
      support for RLEs later).

o Crop each bitmap
    * The object you are rendering will typically only take up a small 
      portion of the rendered frame.  This step eliminates the excess
      background so its left with just the object.
    * The options you can use to influence this step are:
        -crblack : Crop out any excess black.
        -crX,Y   : Find the color at X,Y and crop out any background
                   which matches that color.
        -ci      : Crop each bitmap individually without regard to the 
                   other frames.
        -cw      : Read in all bitmaps first and determine a worst-case
                   cropping rectangle.  The use that same cropping
                   rectangle for all bitmaps.
        -t#      : Allow a tolerance when cropping
        -tc      : Convert all colors within tolerance to the background
                   color (only used if you give "-t#" also)
    * The "-crblack" and "-crX,Y" parameters are mutually exclusive.  If
      you specify more than one, the last one will be kept.
    * The "-ci" and "-cw" parameters are mutually exclusive.  If you 
      specify more than one, the last one will be kept.
    * If "-i" is given then an intermediate file will be saved after
      this step.

o Resize each bitmap
    * After being cropped, SA will reduce the size of each bitmap to a
      specified height and width.  It will maintain the aspect ratio if
      you so desire.
    * The options you can use to influence this step are:
        -h#   : What height to make each frame.
        -w#   : What width to make each frame.
        -a+   : Increase either height or width as appropriate to 
                keep the original aspect ratio.
        -a-   : Decrease either height or width as appropriate to 
                keep the original aspect ratio.
    * If a bitmap is already smaller than the given height or width then
      it will not be changed.
    * If "-i" is given then an intermediate file will be saved after
      this step.

o Concatenate the bitmaps together
    * Creates a final graphic consisting of all the resized bitmaps
      concatenated together.  You can tell it how many frames to put on
      each row of the output.
    * The option you can use to influence this step is:
        -r# : Number of frames on each row of the output

o Save the result in a BMP or TIM file

=========================================================================
Read Input Files to Compare Color Tables
----------------------------------------

On the command line, input files are enclosed by "-f" and "--".  List the 
files individually between these two switches.  A shorthand is available 
to allow you specify a string of files with one name.  When you render a 
series of frames in 3D Studio they follow a naming convention of four 
characters of filename followed by a four digit frame number.  For
example, a ball animation frames might be saved as "BALL0000.BMP", 
"BALL0001.BMP", "BALL0002.BMP", "BALL0003.BMP".  SA can recognize these
filenames so you can just specify the first frame and it will pick up the 
rest.  You can just type the first file name with a "+" on the end.  SA 
will then look for all the frames starting from that one sequentially 
increasing.  You can also optionally add a number after the "+".  This 
will cause it to skip frames.

Consider the following examples:

  sprtasm ... -f mypic.bmp yourpic.bmp ourpic.bmp -- ...

    This will use just the three input files listed.


  sprtasm ... -f ship0000.bmp+ -- ...

    This will search for all frames of the animation beginning with
    "SHIP0000.BMP".  It will increment the frame number until it can't
    find the next frame (SHIP0001.BMP, SHIP0002.BMP, etc).


  sprtasm ... -f lasr0010.bmp+2 -- ...

    This will look for the file "LASR0010.BMP" and every other frame
    after that (LASR0012.BMP, LASR0014.BMP, LASR0016.BMP, etc)


If another 3D package uses a different filename convention for rendered 
frames I would be happy to add it.  I only have access to 3D Studio so 
that's what I used as a reference.

---

Since your output will consist of several frames of animation all in one
graphic it is necessary that they all have the same color table from the
start.  The program is not sophisticated enough (yet) to do color 
conversion. 

This shouldn't be a problem since, when rendering, one of the options in 
3D Studio is to have all output frames share the same color table.  One 
word of warning though, I could only get this to work when I used a 
Custom Palette.  The High, Medium, and Low Palettes didn't work (maybe
I'm just dense).  To use a custom palette you must first render a single 
frame and save it as a GIF.  Then when you render your animation select 
Custom Palette and choose that saved frame as the reference.  It will 
force all frames to use that same color table.

---

SA can only handle 8- or 4-bit bitmap files as inputs.  Also, they must
be in uncompressed form (non-RLE).  When rendering in 3D Studio, select
the output file type to be 256-color BMP and deselect the "Compressed" 
button.  I will add support for RLEs later.

=========================================================================
Crop Each Bitmap
----------------

The first thing SA does to each bitmap is crop out the excess background.
You give it a pair of parameters which direct the program.  You have a
choice for each switch.

---

The first choice is between "-crb" and "-crX,Y".  When cropping, the
program needs to know what color to consider as background.  By giving
"-crb" you're telling SA to crop all black pixels.  Any pixel which
has RGB components of (0, 0, 0) is a candidate for cropping.  An
alternative is "-crX,Y".  You specify a coordinate in place of "X" and
"Y" ("-cr16,16" for example).  The program reads that pixel and uses the
color there as the background.  This second switch is useful when your
bitmap contains a lot of black which you don't want eliminated.

---

Your second cropping choice is to tell SA how the input files are
related.  You can give either "-ci" or "-cw" to make it crop them
individually or worst-case, respectively.  When cropping individually
the program regards each input file on its own.  The worst-case switch 
will cause it to read in each bitmap first, figure out the largest 
cropping rectangle that will fit all the frames, and use that same 
rectangle for every picture.  The first switch is useful if your sprite 
should not change size or move around within the frames.  Conversely the 
second parameter is used when your sprite scales or moves and you need 
to maintain the relative sizes/positions within the animation.

---

You can further modify how SA crops by using the tolerance switches 
"-t#" and "-tc".  By giving a tolerance you are telling the program to 
crop any color which is *close* to the background color.  Each RGB 
component is considered a point in 3-dimensional space (the R, G, and B 
axes instead of X, Y, and Z).  A color is within tolerance if the 
distance between it's RGB coordinate and the background RGB coordinate 
is less than the number you give.  For instance, if you use "-crb" 
then your background RGB coordinate is (0, 0, 0).  Suppose the program 
comes across a color which has RGB (5, 3, 7).  The distance between the 
two colors is 9.11 (using the simple distance formula).  So you would 
need to give a tolerance of at least 10 in order to make the program 
regard this color as background.

The "-tc" switch can be used along with "-t#".  It tells SA to convert
any color within tolerance to the background color.  In the previous
example, giving the options "-t10 -tc" will cause all the pixels with 
the color (5, 3, 7) to change to (0, 0, 0).

=========================================================================
Resize Each Bitmap
------------------

After cropping, SA reduces each input picture to a specified size.
Changing each frame to the same size makes animation easier as you can
use an offset to find the frame you want from your final picture.

The major inputs are "-h#" and "-w#".  They tell the program to reduce
the bitmap size to the given height and width respectively.

There are two additional parameters available:  "-a-" and "-a+".  
These force the program to maintain the aspect ratio of each frame so 
the picture doesn't get distorted.

For "-a-", the program will take your given height and width (from 
"-h#" and "-w#") and decrease one of them to maintain the aspect ratio.  
For example, say a bitmap (after cropping) has a height of 64 and width 
of 48 and you give the parameters "-h32 -w32 -a-".  The program will 
compute the aspect ratio of the original (64:48, or 4:3).  Then it will 
figure out which of the two dimensions it needs to reduce to keep this 
ratio.  First it might fix the WIDTH at 32 and then compute that the new 
height would need to be 43.  This would *increase* the size so we can't 
do that (we used "-a-").  Next it fixes the HEIGHT at 32 and figures 
the new width would be 24.  This *decreases* the width so SA will use 
these values.

Similarly, the "-a+" switch will perform the same operation, only it 
will *increase* the height or width as necessary.  In the example in the 
previous paragraph the program would have selected the first option of
fixing the width at 32 and increasing the height to 43.

Typically you'll want to use these two switches only when you use the 
"-cw" switch.  This will ensure that each frame will be the same size.

=========================================================================
Concatenate the Bitmaps Together
--------------------------------

In the last step SA assembles the cropped/resized input graphics into a
final output graphic.  The last parameter we need to give, "-r#", tells 
how many bitmaps to put on each output row (ex. specifying "-r4" will 
make a final graphic with 4 frames on each row).

=========================================================================
Intermediate Files
------------------

One miscellaneous switch you can use is "-i".  This tells SA to output
all intermediate files as it works.  It will create three sets of
intermediate files depending on what other switches you selected.  The
files will have names beginning with four letters describing which step
to which they refer.  The last four characters will be a four digit
number starting with 0000 and increasing by 1 for each input file.  All
intermediate files will be output in BMP format.

Note if you use this parameter then you do not need to specify an output
file name.  SA will assume you only want the intermediate files.

Here are the file names and the steps to which they correspond:

  CONV0000.BMP:  - Pictures after tolerance conversion
                 - Output if "-t#" and "-tc" given
  CROP0000.BMP:  - Pictures after cropping
                 - Output if any of the cropping switches are used
  RESZ0000.BMP   - Pictures after resizing
                 - Output if resizing is done ("-h#" or "-w#")

Note that since the intermediate files follow the 3D Studio naming 
convention, you can use them as inputs to a subsequent call of Sprite 
Assembler.

For example, this command:
  sprtasm -ci -crb -h32 -w32 -f in0000.bmp+ -- out.bmp
is the same as these two separate commands:
  sprtasm -ci -crb -f in0000.bmp+ -- -i
  sprtasm -h32 -w32 -f crop0000.bmp+ -- out.bmp

=========================================================================
Log file
--------

Sprite Assembler will create a log file "sprtasm.log" which lists all
the steps it took (the same messages that are printed to the screen).  
This is in case you're curious as to what it's doing at each step.

=========================================================================
Examples
--------

Here are some example command lines and what they would do:

  sprtasm -crb -ci -w32 -h32 -r8 -f plnt0000.bmp+ -- planet.tim

    This will read the animation files beginning with PLNT0000.BMP
    (if there are 32 frames then it will stop at PLNT0031.BMP).  It
    will crop each bitmap individually using black as the background
    color.  It will resize each frame to 32 pixels by 32 pixels and
    assemble them all with 8 frames per row.  It will write out the
    final graphic to PLANET.TIM.


  sprtasm -cr639,479 -cw -w64 -h64 -a- -r4 -f dino0000.bmp+3 -- dino.bmp

    The input files start at DINO0000.BMP and take every third frame
    after that (DINO0003.BMP, DINO0006.BMP, etc.)  The input files were 
    probably rendered in 640x480 resolution; we're using the color in 
    the bottom right corner as the background (the "-cr639,479").  It is 
    using a worst-case cropping method.  It will change the height and 
    width to 64 pixels, but it will decrease one or the other to maintain 
    the aspect ratio.  The final graphic will have 4 frames per row and
    will be called DINO.BMP.


  sprtasm -crb -ci -t15 -tc -w16 -h16 -r4 -f in0000.bmp+ lastin.bmp -- out.bmp

    The input files will be IN0000.BMP, IN0001.BMP, IN0002.BMP, etc and
    LASTIN.BMP.  Each bitmap will be cropped individually using black as 
    a background, but a tolerance of 15 (so dark greys will be cropped as 
    well).  Any color within this tolerance will be converted to the 
    background color (which is black).  They will be reduced to 16 by 16 
    and be arranged in rows of 4 frames each.  The output will be a 
    bitmap called OUT.BMP.

=========================================================================
Memory Restrictions
-------------------

I used an old compiler to make this program.  As such it only lets you
use 640k of memory.  This shouldn't present a problem since only one
BMP is read in at a time.  As long as the resulting file isn't too
large you won't run out of memory.

Just in case though, if you see a message such as "Null pointer
returned for..." then you've probably hit the 640k limit.

I'm sorry about this.  I'll try my best to remove this restriction.

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

Bug reports or feature suggestions are always welcome :)

Scott Cartier
dsyaroze@concentric.net

=========================================================================
This document and the Sprite Assembler program are (c) 1997 Scott Cartier

