PET2BMP
-------
The purpose of this document is to explain a few things about how to use
the pet2bmp utility and offer solutions to common problems you may run
into.

What does pet2bmp do?
---------------------
Pet2bmp is a utility that will extract images from pet files from
PF.Magic's Petz II and Petz 3 programs.  If the pet file contains multiple
images, such as a mother with her puppy/kitten, pet2bmp will extract both
images and add a number to the name of the second image.


1. Instructions
---------------
   1.1 To use pet2bmp, you will first need to find the file pet2bmp.exe.  If
       you unzipped the zip file in C:\, then pet2bmp.exe will be in the
       folder C:\pet2bmp\.  If it isn't you may need to use the Find feature
       of Windows Explorer to find it.

   1.2 Once you've located pet2bmp you may wish to make a shortcut for it
       on your desktop.  To do this simply drag pet2bmp.exe to the desktop
       using the right mouse button.  When you drop it on the desktop be
       sure to choose "Create Shortcut(s) Here".  If you didn't get the
       menu then you probably didn't use the right mouse button.
   
   1.3 To configure pet2bmp simply click on the pet2bmp icon and follow the
       menus.  Be sure to save before quitting the menus.

   1.4 Now that you have pet2bmp configured, you are ready to extract some
       images.  Simply drag and drop pet files onto the pet2bmp icon.
       A window should open to display the progress of the conversion.
       Occasionally problems may arise and pet2bmp will need to ask you a
       question.  In general you can probably answer yes to these questions.
       But the results may not be exactly what you expect.
       
   1.5 Look in the folder where you got the pet files.  The bitmap files
       should now appear in there.


2. The Configuration File
-------------------------
 The configuration file, config.ini, is a text file that specifies the
 background color and the starting offset to look for an image at.

 If pet2bmp is unable to find config.ini or if you run pet2bmp by double
 clicking on the icon, it will ask you if you wish to create a new one.  It
 will then provide you a couple simple menus to allow you to create a
 config.ini file.

 To edit the file simply open it with your favorite text editor, such as
 notepad.  Notepad can usually be found in the start menu under Programs ->
 Accessories -> NotePad.

 The format of the configuration file is fairly simple.  Each line has a
 keyword and a value.  The keyword specifies what value will be set by that

 line.

2.1 Background Color
 To change the background color you will need to change the value of the
 background line (i.e. the part that says "255,0,255").  A background color
 can either be specified in the form "red,green,blue", where red, green and
 blue are whole numbers between 0 and 255.  The other way of specifying a
 color is to use a hexadecimal number like one would in an HTML document.

 In this format the magenta color that is used by default would look like

 "#ff00ff".  The following is a table of common colors.  This is only a

 small sampling of the millions of total possible color combinations.

    Color	Triple		Hex
    -----	------ 		-------
    Black	0,0,0		#000000
    Red		255,0,0		#ff0000
    Orange	255,128,0	#ff8000
    Brown	128,96,64	#806040
    Yellow	255,255,0	#ffff00
    Green	0,255,0		#00ff00
    Cyan	0,255,255	#00ffff
    Blue	0,0,255		#0000ff
    Purple	192,0,255	#c000ff
    Magenta	255,0,255	#ff00ff	(default)
    Pink	255,128,192	#ff80c0
    White	255,255,255	#ffffff
    
 Unfortunately it is not possible to specify colors by name.  You must find
 the red, green and blue values for the color you want to use.

2.2 Offset
 The offset tells pet2bmp where to start looking for an image in the file.
 This should probably always be set to zero or one (i.e. the beginning of the
 pet file).  It's recommended that you use one instead of zero so that pet2bmp
 won't create a new bitmap file if you give it a bitmap file.  This feature is
 a hold over from earlier, less robust versions of pet2bmp.


3. Editing the Background
-------------------------
In the event that you can't figure out how to modify the background color
using the configuration file, don't worry.  You can still edit the images
once you've extracted them.

   3.1 To do this simply open the program Paint, usually found in the Start
       menu under Programs -> Accessories.
       
   3.2 Once Paint is open go to the File -> Open window and open the bitmap
       you just created.

   3.3 Select a color to make the background from the palette at the bottom
       of the window and the "Fill With Color" tool (the spilling paint can).

   3.4 Now fill in all of the offending areas with the new color.  It may be
       useful to zoom in a little using the "Magnifier" tool (the magnifying
       glass).


4. Trouble Shooting
-------------------
This section is meant to help with any common problems you may run into
using pet2bmp.

Problem:
 When I drop my petz onto the pet2bmp icon I get the error message, "Access
 to the specified device, path or file is denied."

 I think this is caused by a limitation on how long a single command line
 can be.

Solution:
 Simply select fewer pet files at a time.  


Problem:
 Whenever I run pet2bmp I get the error "Unknown token ... in config file".

 This means that pet2bmp found something in the configuration file that it
 didn't expect to find or didn't know how to process.

Solution:
 Edit the configuration file and make sure there aren't any extra spaces
 in the middle of any of the names or values.

 If you'd like to set the configuration file back to the defaults simply
 change it to look exactly like this:
     background		255,0,255
     offset		1

 Or you can simply delete the config.ini file and create a new one next
 time you run pet2bmp.


Problem:
 All of the images I extract have a hideous magenta background.

 This is because the Petz program uses that magenta color to specify the
 background of the image.  Any pixel that is that color is converted to the
 appropriate background color whenever the image is needed.

Solution:
 If you want to get rid of that color you can either change it to a
 different color or you can make it transparent.

 To change its color simply edit the config.ini file and specify a new
 background color (see instructions in section 2.1).


 If you wish to make the magenta transparent for use in a GIF image you
 will need to open the image with Paint Shop Pro 5 and go to the 'Set
 Palette Transparency...' window found under the 'Colors' menu.  you will
 then need to select 'Set the transparency value to palette entry' and
 change the number to 253.  Then you can hit ok.  If you then want to see
 the image without the magenta, go back to the color menu again and select,
 'View Palette Transparency...'.  Once you've made the image transparent,
 you will need to save it in a file format such as 'Compuserve Graphics
 Interchange (*.gif)' format.


Problem:
 Pet2bmp claims that it is finding a picture in the file, but the image
 is garbage or I am unable to open the image file.

 It's possible that what pet2bmp looks for to identify an image occurs
 more than once in the file.  If this happens pet2bmp tries to find all
 images in the file.

Solution:
 If pet2bmp doesn't find the correct image in the pet file try editing the 
 config.ini file and specifying an initial offset that is one greater than
 the offset it claims it's finding an image at.  Be sure to set this
 back when you're done as it might make pet2bmp unable to find images in
 other pet files.


Problem:
 When I extract the picture of my pet the colorings are right, but the
 breed is wrong
  
 This sometimes comes up when attempting to hex-paint a Petz II pet by

 swapping breed files around.
     
Solution:
 Simply take your pet out and play with it using the correct breed file.

 This should fix the problem, but I can't easily test this as I don't
 hex-paint animals.


Problem
 When I try to change the background color using Paint, it doesn't do
 anything, even when I have the "Fill With Color" tool selected.

 It's possible Paint doesn't know what area you want the tool applied to.

Solution
 Go to the Edit menu and choose "Select All" and try again.  If that
 doesn't work make sure you've selected a color other then the current
 background color.
                              

Problem:
 I've read all of the documentation and still am unable to get pet2bmp to
 work right for me.

 This may be caused by many things from unclear instructions to a bug in
 the program.

Solution:
 If you truly have read ALL of the instructions and trouble shooting, and you

 are still unable to get pet2bmp to work for you, then please send some e-mail
 to the author, bmfrankl@silver.trica.com.  Be sure to include a detailed

 description of what you tried and what error messages you get (if any).
