
**********************************************************************
                               Zoot
**********************************************************************

 ZT image manipulation program

 Version 0.9b (Beta 1 Refresh)

 Written by Francois Poulin, a.k.a. MadScientist
 mailto:poulin1967@lycos.com

**********************************************************************


[
  This version (0.9b) contains a fix for a bug found by ZooAdmin's jbl.
  The bug was that image files created by Zoot contained palette file
  paths that used backslashes instead of the expected slash, causing
  certain types of objects to crash the game. Props to Jeff for tracking
  down the problem!

  -- MadSci
]


INTRODUCTION
============

Thank you for downloading Zoot. This program will allow
you to streamline your ZT design projects in several useful ways.

Features include:

* Conversion of a PNG image to a ZT image (w/ accompanying .PAL file of course)
* Conversion of a set of PNG images to a ZT animation file
* Conversion of a ZT image to a PNG image
* Conversion of a ZT animation to a set of PNG images
* Direct manipulation of ZT animation frames
* Interactive modification of ZT image offsets, which makes the task of
  "fixing rotations" of your ZT objects as easy as click-and-drag!
* Tree-based browsing of your ZT projects, with instant preview of
  selected objects

Other features may then be added in future releases as the need/interest
arises:

* Ability to perform all the above tasks on .ztd files directly
* Ability to edit the palette in-place, allowing for VERY painless
  animal re-colors!


HOW TO INSTALL ZOOT
=====================

Zoot is a Java-based application, which means that you need to have Sun's
Java Runtime Environment (JRE) installed on your machine. You will need
version 1.4.0 or higher.

You can download the latest version of the JRE for free at http://java.sun.com.

Once the JRE is installed on your machine, running Zoot should be as easy
as running the zoot.bat file, making sure the zoot.jar file is in the same
directory.


HOW TO USE ZOOT
=================

As of version yet, Zoot doesn't work with .ztd files directly. You will need to
extract your .ztd file's content to a directory using Winzip first. For the
remainder of this document we will assume you have created a new directory
called C:\MyProject and extracted your .ztd file in it.

When you start Zoot, the first thing the program does is prompt you to open
a project directory (you can also choose "File | Open Project" to open a
project.) Select C:\MyProject. (The next time you start Zoot the last project
you visited will be open for you automatically.)

Once you've selected a project Zoot should now display your project's files
and directories in its tree view on the left.

You will be able to view .cfg, .scn, .ai and other ZT-related text files
directly by selecting them in the tree -- their contents will be displayed
on the right.

You will also be able to preview ZT images and animations on the right by
selecting them in the tree.

In addition, when an image file is selected in the tree, some other operations
will become available from the Image menu. Specifically, you will be able to:

- Edit the image (import/export frames, add/remove frames, reorder frames,
  change animation speed, etc.)
- Interactively change the offsets of the image (a.k.a. "rotation fixing")
- Save the entire image/animation into a series of PNG images.

Note that when viewing an image from anywhere within Zoot, the mouse wheel
will zoom the image in and out (a la PaintShop Pro.)


Converting an image into ZT format:
-----------------------------------

If you wish to add or replace a frame in an existing ZT image, select the
ZT image in the tree then go to "Image | Edit Image" to bring up the image
editor. You can then click on "Add Frame" to import a PNG file into the image.

If you wish to create a brand new ZT image or animation from one or more
PNG files, choose "Image | New Image" from the menu. This will prompt you for
a file name for the new image. Once you have entered a new file name, the
image editor will come up and you can add frames at your leisure.

Click on the "Save Image" button at the bottom to save your work or "Cancel"
to revert your changes.


Converting a set of images into a ZT animation:
-----------------------------------------------

This works exactly the same as converting a single image, as outlined
above. Simply add more frames to a ZT image to make it into an animation.

You can use the "Animation Speed" edit box to speed up / slow down your
animation. The numbers are in milliseconds elapsed between frames.


Converting a ZT image or animation to one or more PNG files:
----------------------------------------------------------------------------

You can do this in two ways: batch-converting the entire ZT animation to
a series of PNG files, or manually exporting frames one by one.

For batch conversion:
Select the ZT image you wish to convert. Then choose "Image | Save Image"
from the menu. You will be prompted for a file name to save your images.
As an example, let's enter myanimal.png. When you hit the Save button,
a series of PNG images will be created (one per frame). They will be named
myanimal000.png, myanimal001.png, etc.

For one by one conversion:
Select the ZT image, then choose "Image | Edit Image" from the menu. In the
image editor, select the frame you wish to save and click on "Export Frame".
You will be prompted for a file name, and then the image will be converted
and saved.


Modifying image location offsets (a.k.a. "Rotation Fixing") :
-------------------------------------------------------------

Select the ZT image file you wish to fix. Then choose "Image | Fix Rotations"
from the menu. This will bring up the Image Offsets editor. You will see
the first frame of your image, overlayed on top of a ZT-like grid.

Remember: the mousewheel will make the image zoom in and out!

The first thing to do is set the grid size to the footprint of your object.
The grid size (X by Y) is directly related to the "cFootprintX" and
"cFootprintY" values in your .ai or .ucs file. Remember that a full grid
square is 2 units wide and high!

Once you have set the width and height of the grid, all you have to do
is drag the image into place on top of the grid into the desired position.
Then click on the "Save To File" button at the bottom and voila!

Simply repeat for all orientation variants of your image (NE, SE, NW, SW).


TROUBLESHOOTING
===============

Problem:
--------
Images don't display when I select them!

Solution:
---------
ZT images can only be displayed/manipulated when they are accessed
from the top-level project directory.

For example, in project C:\MyProj I have a ZT image called
objects\coolfence\idle\NE. If you make Zoot open C:\MyProj\objects\coolfence
as a project directory, you will NOT be able to preview and edit your image
under the idle directory. You can only do this by selecting C:\MyProj as
the project directory.


Problem:
--------
When adding frames to my ZT animation, I get a "Too many colors" error.

Solution:
---------
The ZT file format only supports 256 unique colors across all frames of
an animation. When you add a new frame, any previously unused colors
are added to the animation's palette. However when the total number
of unique colors used reaches 256, an error is given.

Currently, the only solution is to ensure that all frames of your ZT animation
use the same set of 256 colors. This is easily managed in PaintShop Pro using
the "Colors | Load Palette" and "Colors | Save Palette" commands.

My understanding is that APE does some kind of palette normalization
to reduce the number of colors to 256. The resulting frames will not be
exactly as you drew them; they will use an approximation of the desired
colors. As of now, Zoot does not try to normalize the palette across frames.


REPORTING BUGS
==============

If you run into bugs/unexpected behavior/error messages, please let me know
ASAP. You may contact me at the address listed in this file's header.

When you contact me, please include the following information in your email:

- The OS name and version you're running.
- Detailed steps to reproduce the problem.


STANDARD DISCLAIMER
===================

Users of Zoot must accept this disclaimer of warranty: "Zoot is supplied as is.
The author disclaims all warranties, expressed or implied, including, without
limitation, the warranties of merchantability and of fitness for any purpose.
The author assumes no liability for damages, direct or consequential, which
may result from the use of Zoot."


DISTRIBUTION LICENSE
====================

You may distribute Zoot freely as long as the following conditions are met:

- You must not modify it in any way.
- You must distribute all the original files together in the orginal package.
- You must not charge *any* money for redistributing it.


Enjoy!

MadSci
