
**********************************************************************
                               ZOOT
**********************************************************************

 ZT Image Manipulation Program

 Version 1.1

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

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


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 (with 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!
* Ability to create and edit string resources in DLLs.
* Ability to edit text files (such as .uca, .ai files) directly from Zoot.


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.2 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 easy.
There are a number of ways to run Zoot:
1. Run the zoot.bat file, making sure the zoot.jar file is in the same
   directory. This is the usual way to run Zoot.
2. Run the zootdiamond.bat file. This is the same as the first way to run
   Zoot, but will use a multicolored diamond pattern for the grid.
3. Run the zootcrosspatch.bat file. This is the same as the first way to run
   Zoot, but will use a multicolored crosspatch pattern for the grid.
4. Run the zootcross.bat file. This is the same as the first way to run Zoot,
   but will use a multicolored cross pattern for the grid.
5. Run the zoottest.bat file. This keeps an extra window on the screen
   that will show information on any unexpected errors. However, normally
   there should not be any unexpected errors to show. So this is just in case
   Zoot is causing you unexpected problems and you want to see if there is
   any additional information that might be useful to someone that will
   change Zoot. If you are using an operating system other than MS Windows,
   such as Linux, use this or the next way to run Zoot.
6. It is also possible to run zoot.jar directly, but that will use less memory
   and, therefore, will not work for large images.
7. If Zoot is giving Out of Memory errors for very large animations of very
   large images, you can try to run Zoot in a way that allows it to use more
   memory. You can start a Command Prompt and use the command:
     java -Xmx896M -jar zoot.jar
   You can change the "896M" to whatever amount of memory you want Zoot
   to use.  The first 5 ways to run Zoot will use up to 768M.  So it is
   unlikely you will need to use more memory.  Another approach that can help
   concerning memory with very large animations of very large images
   is to just do 1 view at a time and exit Zoot before working
   on the next view.


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

As of this version, Zoot doesn't work with .ztd files directly. You will need
to extract your .ztd file's content to a directory first, using any unzipping
program. 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.)

Opening a project directory is often confusing. If it is not done the proper
way, Zoot will not be able to find the colors for the images. To make
it easier to understand, it is recommended to use the ".ztd" name, excluding
the ".ztd", as the project directory. For example, if the ".ztd" name
is MyProject.ztd, create a new directory called "MyProject", extract
MyProject.ztd into the MyProject directory, and use the MyProject directory
as the project directory in Zoot. It does not matter where the MyProject
directory is. For example, it can be C:\MyProject or C:\ZT\MyProject
or C:\ZT\zoot\MyProject or D:\WorkArea\MyProject. It will work, as long
as ...MyProject is opened as the project directory in Zoot, and not C:\ZT
or C:\ZT\zoot or D:\WorkArea or \MyProject\objects or \MyProject\animals.

Once you've selected a project, Zoot should then 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. Note that you can NOT edit these text files directly from
Zoot; use a text editor such as WordPad or Vim to do this.

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(s)" 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 to file and close window" 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.

It is possible to load a set of animated frames simultaneously.  On the file
selection screen, click the first file of the set.  Then, while holding down
the "Shift" key, click the last file of the set.  All of the files in between
those two files will also be selected.


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, .ucs, or ".uca" file. Remember that a full
grid square (tile) is 2 units wide and long! In order to make it easier
to adjust the offsets properly, the footprint in Zoot should always use
even numbers. Also, it is usually easier to set the footprint for the SE view
before working on the other views.

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 and close window" button at the bottom
and voila!

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

NOTE: While this operation will modify the actual image file itself, it
will NOT modify the cFootprintX and Y values in the accompanying .ucs file.
You will need to do that in a separate step using a text editor.

It is also possible to adjust the position of each frame in an animation.
To do this, choose "Image | Adjust Frames" from the menu. This needs to be
done when an animation that is not zoomed appears to be hopping around
in Zoot or in ZT.


More information:
-----------------

More information can be found by clicking on the various Help icons (the icons
with a question mark) in Zoot. Each major window has its own Help.


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.


Problem:
--------
If I start ZT while Zoot is running, Zoot disappears without a trace,
not even a crash message. Every time this happens a file called
hs_err_pid*.log gets created in my Zoot project dir.

Solution:
---------
This is a known bug in Sun Java Runtime Environment versions 1.4.0x and
1.4.1x. Upgrading your JRE to 1.4.2 or above will fix this problem.

Also, you can safely delete the hs_err_pid*.log files that were created.


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.
- A screen shot of the buggy window if appropriate.


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 original package.
- You must not charge *any* money for redistributing it.


CREDITS
=======

Special thanks to the intrepid ZT designers who have helped in one way or
another in making this program better. In aphabetical order:

	- Aqua Dragon
	- casey
	- Eagle One
	- Jens
	- Quivaz
	- ZooMaster3

Also thanks to jbl for tracking down a problem in the 0.9 Beta version.

I'm sure I'm forgetting a few, but you know who you are...


Enjoy the program!

MadSci

=======

Jay modified the Zoot program for the following reasons:
- to provide a way (via zoottest.bat) of seeing any unexpected error messages
  that are not shown by Zoot.
- to allow saving larger images and larger animations.
- to allow negative offsets, down to -127, in rotation position adjustments.
- to allow moving the image by clicking buttons or using d/u/l/r keys
  on the rotation position screen, in addition to allowing the dragging.
- to create help buttons for the various windows.
- to fix the out of memory problem that occurs if a project's start directory
  has a file without an extension that is not a ZT image.
- to mirror the grid lines automatically for sw and ne image files.
- to add center pixels to the grid squares.
- to adjust the frame count as frames are added or deleted, and to also show
  the frame number of any selected frame.
- to allow ZT image files to reduce in size.
- to have the main window update its list when a ZT image file is saved.
- to have a refresh also unselect any previously selected image.
- to show as much of a selected frame in the "Editing frames" window
  as possible.
- to finish the work that allows adjusting rotation positions for individual
  frames as well as for a ZT image as a whole.
- to allow the "Editing frames" and "Fixing rotations" windows
  to be maximized.
- to allow seeing multicolored diamond, crosspatch, or cross grid patterns,
  in addition to the default grid outline with center pixels.
- to show animations in a way similar to ZT rather than centering each
  individual frame, which caused some animations to hop around in Zoot
  when they did not in ZT.

--- End of readme.txt. -----
