Image Converter
Copyright  1997-1999 Art Dahm
(palm@dahm.com)


Introduction
------------

Image Converter (pimg.exe) is a Windows 95/98/NT application for converting
GIF, JPG, PCX, DIB, RLE, and TGA graphic files into Palm .PRC images
compatible with Image Viewer.


Installing Image Converter
--------------------------
Unzip the file pimg.exe and NViewLib.dll into their own separate folder.
To start the Image Converter, double click the pimg.exe file from the
Windows Desktop or Explorer.

Creating an Image
-----------------

The steps involved in creating an Image Viewer image are:

- Select the image source.  The source of an image can be a graphic file,
the Windows clipboard or an area of the screen.

- If the image source is a graphic file, click the 'Open' button to select
the graphic file to convert.

- If the image source is the Widows Clipboard, click the 'Open' button to
load the contents of the clipboard into the image converter.

- If the image source is the screen, click the 'Open' button to hide the
image converter window.  Click the left mouse button in the upper left
corner of the area of the screen to be converted.  Drag the mouse to the
lower right corner and click the left mouse button again.  The image
converter window will be restored and the selected area will be loaded into
the image converter.

- The Image Title is the name of the image as it will appear on the
handheld device.

- The Image File is the name of the Palm database file (.PDB) containing
the image which will be hotsynced to the Palm device.

There are several conversion options available by clicking on the
'Options' tab:

  - Click on the 'Black & White' radio button to create two color black and
    white images.  The size limit of black and white images can be up to twice
    as much as grayscale images.

  - Click on the '4 Level Grayscale' radio button to create four color
    grayscale images.

  - Click on the '16 Level Grayscale' radio button to create 16 color
    grayscale images.  Check the 'Use only 8 levels' to use only the middle
    8 grayscale levels of the 16 level palette.  This is useful because the
    Palm display can cause the four darkest colors to appear as black and
    the four lightest colors to appear as white.

  - Check the 'Compress Image' checkbox if you want the image compressed.
    Compressed images take up less space on your handheld, but take longer to
    view and may not be viewable under low memory situations.

  - Dithering is a process of making a limited number of colors seem like
    more by creating a pattern of two similar colors to simulate a third
    color.  The dithering options are 'None', 'Ordered' and 'Error
    Diffusion'.  Ordered dithering is not available for 16 level grayscale
    images.

- Check the 'Auto Install' checkbox if you want the image to be
  automatically installed on your handheld the next time you HotSync.
  Otherwise, to install the image, use the Palm Install Tool.

- Click the 'Convert' button to convert the image.  The new Palm
database file will be stored in the same folder as the original file.

- If the image is too large, a dialog box will pop up with a suggested amount
to decrease the size of the image by.

Command Line Syntax
-------------------
Usage:

  pimg [file] [image title] [image notes] [-compress] [-c] [-nocompress] [-nc]
    [-grayscale4] [-gs4] [-g4] [-grayscale16] [-gs16] [-g16] [-bw]
    [-autoinstall] [-a] [-noautoinstall] [-na] [-ordered] [-o]
    [-errordiffusion] [-ed] [-nodither] [-nd] [-quiet] [-q] [-crop] [-shrink]
    [-noresize] [-ask]

Where:

  [file] is the name of the graphic file to convert.
  [image title] is the name of the image as it will appear in the image list
    on the handheld device.
  [image notes] is a string enclosed in quotes which will appear in the
    image notes.
  [-compress] [-c] compresses the image
  [-nocompress] [-nc] doesn't compress the image
  [-grayscale4] [-gs4] [-g4] creates a 4 level grayscale image
  [-grayscale16] [-gs16] [-g16] creates a 16 level grayscale image
  [-bw] creates a black & white image
  [-ordered] [-o] dithers the image using an 'ordered' algorithm
  [-errordiffusion] [-ed] dithers the image using an 'error-diffusion'
    algorithm
  [-nodither] [-nd] doesn't dither the image
  [-autoinstall] [-a] will auto install the image
  [-noautoinstall [-na] won't auto install the image
  [-quiet] [-q] suppresses all windows and dialogs (except 'ask', see below)
  [-crop] crop the image if it is too large
  [-shrink] shrink the image if it is too large
  [-noresize] abort the conversion if the image is too large
  [-ask] presents a dialog box if the image is too large

All command line parameters are optional.  However:

  If a command line switch is not specified, the state from the most
  recent image conversion will be used.

  If a file is specified, the image converter will exit after it converts
  the image.

  A file must be specified in order to specify and image title and image
  notes.

  A file and image title must be specified in order to specify image notes.

Tips
----

Use your favorite paint program to convert an image to grayscale to get a
better idea of how it will look on your handheld device.

Palm Computing(R) Platform handheld devices use four levels of gray (white, 
light gray, dark gray and black) which are evenly distributed among the 
range of grays used in a paint program.  If an image loses certain details 
when converted, try changing the brightness of some of the colors so they 
map to a different grayscale level.

If an image is too large for Image Converter to convert or resize, use your
paint program's Crop or Resize feature to decrease the size of the image.

Ordered dithering is best for images that contain large areas of a single
color, such as maps or diagrams, whereas error diffusion dithering is better
suited for photographs.

Updates
-------
v3.0	- Added support for 16 level grayscale images.
	- Converter remembers file path between sessions.
v2.9.3	- Added error diffusion dithering option
	- Added ability to crop or shrink files that are too big to convert.
	- Created 'Options' tab.
	- Improved command line support
v2.9.2	- Not released
v2.9.1	- Fixed a small color mapping issue
v2.9	- Added command line options
v2.8b
	- Fixed bug which caused B&W images to be offset to the left by one pixel.
v2.8
	- Improved process used to convert color pictures to grayscale.
v2.7
	- Added image compression.
v2.5
	- Added support for GIF, JPG, PCX, DIB, RLE, and TGA graphic file types.
v2.4
	- Added a light next to the Convert button which turns red if an image is too large to be converted
v2.3
	- Added ability to convert an image in the Windows clipboard
	- Added ability to capture and convert an area of the screen
v2.2
	- Fixed multiple user auto-install bug
v2.1
	- Added grayscale 'dither' option
	- Added black & white 'dither' option
v2.0
	- Redesigned UI: Tabbed dialog replaces multiple windows.
	- Added auto-install option: No more need to run the Palm Install Tool.
	  Just convert and hotsync.
	- Added preview tab: See how Palm device images will look before
	  installing them.
	- Removed 'dither' option
V1.3
	- Added support for black & white images
V1.2
	- Added support for attaching notes to images
V1.1
	- Added 'dither' option to simulate three more grayscale levels.
	- Increased maximum image size by about 10%
