/***************************************************************************\
 *                                                                         * 
 *          Electronic Documentation for NeonJax3D Path Crawler            * 
 *                                                                         * 
 *                               Version 1.0                               * 
 *                                                                         * 
 *                             July 9th, 2002                              * 
 *                                                                         * 
 *                 Copyright (c) 2002 by Richard Goedeken                  * 
 *                                                                         * 
 *                                                                         * 
 *                  A product of Fascination Software Co.                  * 
 *                                                                         * 
\***************************************************************************/
-----------------------------------------------------------------------------

Legal Stuff:
This software (NeonJax3D SDK Version 1.0) is copyrighted software.  I give
you (the LICENSEE) permission to freely copy and distribute this software in
any manner to anyone (the RECIPIENTS) as long as the following two conditions
are met:

A) The LICENSEE may not charge the RECIPIENTS more than us$1 over and above
   the media and duplication costs for copies of this software.
B) Any copies made by the LICENSEE must retain all of the original files and
   the original file structure from the ZIP file distributed by Fascination
   Software. (NeonJax3D-SDK.zip)

Fascination Software, and Richard Goedeken, are not in any way liable for any
damages incurred by the use of this software.  The user assumes full
responsibility for the use of this software.

-----------------------------------------------------------------------------
 *************************************************************************** 
 **                             PathFind.txt                              ** 
 *************************************************************************** 

This document was written with the assumption that the reader understands
the basic operating principles of the NeonJax3D screen saver, the 1000 Points
of Light object and the Marquee effect.  If the reader is not familiar with
this information then it is recommended that he or she read the main
Readme.txt file and J3DComp.txt file before reading this.

This file contains information regarding the usage of the NeonJax3D Path
Crawler.  The Path Crawler is used to generate NeonJax3D Path object source
code to be used in Scene source files.  This tiny 32-bit DOS DPMI program
reads two color 8-bit BMP line drawing images and traces all of the path
segments in the image.  The PathFind program outputs the segment data in a
J3D Scene File compatible format which may be cut and pasted into a Path
definition.  The usage specification for PathFind.exe is below:

       ************************************************************
       * Usage:                                                   *
       *   PathFind.exe <image.bmp> <CenterX> <CenterY> [-c]      *
       * -------------------------------------------------------  *
       *   <image.bmp> == input image in 8-bit BMP format         *
       *   <CenterX>   == X coordinate of desired center of image *
       *   <CenterY>   == Y coordinate of desired center of image *
       *   [-c]        == Output compressed (code-form) data      *
       ************************************************************

The following files should be present in the 'PathFind\' folder:

  nuclear.gif             - Sample 16-color image from the web
  Nuclear1.bmp            - 8-bit BMP of sample image
  Nuclear2.bmp            - 24-bit enlarged image
  Nuclear3.bmp            - 8-bit outline image
  Nuclear4.bmp            - 8-bit corrected outline
  Nuclear.txt             - Output Path data
  Nuclear-Path-Create.bat - Batch file for creating Path output file
  PathFind.exe            - NeonJax3D Path Crawler executable
  PathFind.txt            - Manual for NeonJax3D Path Crawler (this file)

-----------------------------------------------------------------------------
 ++-----------------------------------------------------------------------++
 ||                             Simple Usage                              ||
 ++-----------------------------------------------------------------------++

To test the PathFind.exe program, execute the 'Nuclear-Path-Create.bat' batch
file.  This script runs the PathFind program on the 'Nuclear4.bmp' image and
directs the output to the 'Nuclear.txt' file.  The Path source code may then
be cut and pasted from the 'Nuclear.txt' file to the user's J3D Scene source
file.

-----------------------------------------------------------------------------
 ++-----------------------------------------------------------------------++
 ||                      Won't You Be My Neighbor?                        ||
 ++-----------------------------------------------------------------------++

The PathFind program works by first determining the background and foreground
colors, then searching through the image data until the first foreground
pixel is found.  The PathFind program then crawls along the path found,
recording the steps taken, until the path ends.  Then the program saves the
segment information and begins searching through the image data to find the
next segment.  Up to 16 segments are found and converted in this way.

The paths in the line-drawing BMP images must be special.  They must be
'connected in the 4-neighborhood'.  This means that the PathFind path crawler
must be able to crawl along the path of the image by taking single steps of
either left, right, up, or down.  The path may not have any diagonal steps.
It should also not have any extra pixels.  From each point on the path, there
should only be two ways to go: back or forward.  If there are extra pixels,
the Path Crawler may produce some very small Segments (just a few steps) or
there may be more segments than necessary.

The table below illustrates these requirements:

+-------------------------------------+-------------------------------------+
|             Not Good                |                 Good                |
+-------------------------------------+-------------------------------------+ 
|                                     |                                     |
|        XXXXXXX                      |          XXXXXXXX                   |
|               XXX                   |                 XXXX                |
|                  XXX                |                    XXX              |
|                     XXXXX           |                      XXXXXX         |
|                                     |                                     |
|                                     |                                     |
|                                     |                                     |
|        XXXXXXXX                     |         XXXXXXX                     |
|        XXX    XXXXX                 |        XX     XXXXX                 |
|     XXXX         XXXXX              |     XXXX          XXXX              |
|                     XXXXXXX         |                      XXXXXX         |
|                X                    |                                     |
|               XXX                   |               XXX                   |
|              XXXXX                  |              XX XX                  |
|          XXXXX   XXXXX  X           |          XXXXX   XXXXX              |
|      XXXXX           XXXXXX         |      XXXXX           XXXXXX         |
|                                     |                                     |

-----------------------------------------------------------------------------
 ++-----------------------------------------------------------------------++
 ||                        Making Your Own Paths                          ||
 ++-----------------------------------------------------------------------++

The Nuclear1.bmp - Nuclear4.bmp images provide an example of the steps
necessary to prepare an image for PathFind using an image editing program
such as Paint Shop Pro or Adobe Photoshop.  The following list enumerates all
of the steps of this process:

1. Start by loading the image (nuclear.gif or Nuclear1.bmp) and converting it
   to 24-bit RGB color.
2. Use the tools (paint bucket and magic wand, lasso, brightness / contrast,
   etc) to convert the image to black and white.  Convert to greyscale mode.
3. Resize the image to desired dimensions - one step per pixel.  Use high
   quality (bi-cubic) resize if possible.  The image should look similar to
   Nuclear2.bmp at this point.
4. Using Brightness / Contrast adjustments, set the contrast to 100% and
   adjust the brightness to select the best looking two-color image.
5. Select the background colored areas in the image using the magic wand.
6. Expand or grow the selection by one pixel.
7. Invert the selection.
8. Use the eraser / paintbrush / paint bucket to blank out the insides of the
   foreground areas with the background color.  Only the outlines should
   remain. Deselect everything.  The image should look like Nuclear3.bmp.
9. Now the image must be looked over and tweaked by hand.  Zoom the image up
   and manually trace the path, removing stray pixels and adding pixels as
   necessary to ensure that the path is connected in the 4-neighborhood as
   demonstrated in the table above.  After this step the image should look
   like Nuclear4.bmp.

This procedure may be used to convert any image into a line drawing suitable
for conversion by PathFind and use in NeonJax3D.  As a final step, it is
necessary to choose a point in the image to use as the object's center point.
Write down the coordinates of this point and use them when calling
PathFind.exe to generate the Path source text.

-----------------------------------------------------------------------------
 ++-----------------------------------------------------------------------++
 ||                               Contact                                 ||
 ++-----------------------------------------------------------------------++

To contact Fascination Software, point your web browser at:

                        www.fascinationsoftware.com

And follow the links...

-----------------------------------------------------------------------------
EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF EOF
-----------------------------------------------------------------------------