Allison Users Manual Excellent Software, Inc. 11735 Dry River Court Reston,VA 22091 Copyright © 1990, by W. Scott Gentry, all rights reserved. By W. Scott Gentry Warranty Disclaimers Excellent Software, Inc., W. Scott Gentry, and Alltech Electronics Co., Inc., make no warranties, either express or implied, with respect to this manual or with respect to the software described herein, its performance, merchantability, or fitness for any particular purpose. In no event will Excellent Software, Inc., W. Scott Gentry, or Alltech Electronics Co., Inc., be liable for direct, indirect, incidental, or consequential damages resulting from any defect in the software. Excellent Software, Inc., W. Scott Gentry, or Alltech Electronics Co., Inc., will not be held liable for any incidental or consequential damages for breach of any express or implied warranty on this software. Some states do not allow the exclusion of limitation of implied warranties or consequential damages, so the above limitations or exclusions may not apply to you. This warranty gives you specific legal rights, and you may have other rights that vary from state to state. Apple Computer Warranty Disclaimers GS/OS is a copyrighted program by Apple Computer, Inc. Licensed to Alltech Electronics Co., Inc., to distribute for use only in combination with Allison. Apple Software shall not be copied onto another diskette (except for archive purposes) or into memory unless as part of the execution of Allison. When Allison has completed execution Apple software shall not be used by any other computer program. APPLE COMPUTER, INC., MAKES NO WARRANTIES, EITHER EXPRESS OR IMPLIED, REGARDING THE ENCLOSED COMPUTER SOFTWARE PACKAGE, ITS MERCHANTABILITY OR ITS FITNESS FOR ANY PARTICULAR PURPOSE. THE EXCLUSION OF IMPLIED WARRANTIES IS NOT PERMITTED BY SOME STATES. THE ABOVE EXCLUSION MAY NOT APPLY TO YOU. THIS WARRANTY PROVIDES YOU WITH SPECIFIC LEGAL RIGHTS. THERE MAY OTHER RIGHTS THAT YOU MAY HAVE WHICH VARY FROM STATE TO STATE. Apple, Apple IIGS, and GS/OS are registered trademarks of Apple Computer, Inc. Visionary GS is a registered trademark of Virtual Realities, Inc. AST Vision Plus is a registered trademark of AST Research, Inc. SuperConvert is a registered trademark of Seven Hills Software The Graphic Exchange is a trademark of Roger Wagner Publishing, Inc. Allison is dedicated in memory of our late daughter, Allison Paige Gentry. Janet and Scott Gentry Using This Manual... In order to get the most out of this manual and to enhance its value to you as a reference guide, several conventions were followed. When you see something like this... The item is very important to the proper operation of the hardware and software. Please, take the time to follow the instructions in these areas exactly as written. +When you see something like this... The text set off in this manner is of particular interest or value. < Note: The text set off in this manner is usually a clarification of a point made earlier. Table of Contents Welcome to Allison! Thank you for upgrading to Allison! The arrival of Allison marks significant advancements in the graphic and image processing capabilities found in your Apple IIGS personal computer. We think you'll find Allison to be powerful, easy to use, and most important -- fun! Allison was developed so you can get the absolute best quality images the Apple IIGS has to offer. Allison wasn't designed to do everything. There are a number of popular programs by other software companies that will perform image conversions for you. We at Excellent Software thought this was an "excellent" opportunity to work together with other companies instead of competing with them. Why reinvent the wheel when a perfectly round one already exists? The final, typset version of this manual will detail using Allison images in graphic conversion applications from the following publishers, please, support those who support you! Seven Hills Software -- SuperConvertª Roger Wagner Publishing, Inc. -- The Graphic Exchangeª Raptor, Inc. -- Second Chance We thank the above companies for their support of Allison. Please take the time to read the information provided in this preliminary document as it will help you get the most out of your investment in this revolutionary new product. BUT... Before you do anything else, please, make a copy of the Allison software disk and put the original away for safe keeping! Use ony the copy! The original should be treated as a Master Disk and be used only for copying should the one copy you make be damaged. A word about a sticky issue... Piracy affects the very life blood of your computer - the application. Companies cannot stay in business for long if nobody buys their software. Please, don't give away copies of Allison. It only hurts you in the long run -- Besides, it's illegal. Setting up Installation instructions for your Enhanced Vision Plus digitizer, can be found in the AST Vision Plus manual that was included with this digitizer. To summarize: 1. Turn your Apple IIGS off. 2. Leave the power chord plugged in. 3. Open the cover. 4. Touch the top of the power supply with your hand. 5. Insert the Enhanced Vision Plus digitizer into any unoccupied slot by gently pushing down on the board until it is firmly seated. 6. Attach the male end of the input cable to the Enhanced Vision Plus digitizer. 7. Install the other end of the cable to the back of the computer. 8. Attach the extension cable to your video source. 9. Replace the cover. 10. Insert your Allison disk into your normal boot drive. 11. Power on the system. Allison will be started automatically. What you see This section explains the basic menu functions of Allison. From left to right the menus in the menu bar are: Apple, File, Edit, Options. The entries under the Apple menu are as follows: About Allison -- information about the program and credits. Preferences -- Allows you to customize the environment Allison runs under. Preference options are: RawFile Loading - Allows you to choose whether or not Allison will dither when loading a Raw image file. Allows you to keep a calculated palette for use in color digitizing. Digitizing Options - Allows you to choose to keep the raw image with the window. < Note: Raw images are large and take up large chunks of memory. If you choose "Keep Raw Image" and have only one megabyte of memory, it is recommended that you save the processed picture and the raw image immediately after digitizing then close the window. Allows you to choose to keep the preview image if one was present. Allows you to select One frame at a time digitizing. Special Preference - Selecting Fewer Warnings allows you to suppress certain alert messages that might become tedious if seen too often. Buttons - Cancel exits the preference dialog without saving your choices Save to disk, saves your choices. Exits dialog. Below Preferences are the System Menu items featuring the Control Panel and any New Desk Accessories (NDA's) you may have installed. Allison fully supports NDA's and their use of the Edit Menu (See Edit Menu discussion). File Menu This menu allows you to: Open raw image files from both Allison and the obsolete AST Vision Plus. Raw image files as saved in "Vid" format under Perfect View are not supported. Raw images are processed automatically after loading. Open also allows you to open Screen files of file type $C1 and Preview images saved under Allison. Please note that Preview images do not create a window. Instead, Preview images may be viewed after opening by using Digitizing Options under the Options menu (see Option menu discussion). Preview images are intended for programmers who wish to create small animations. Save images in either of the following forms: Raw image, Screen images, and Preview images. Save as... see Save. Close. Use close to close open windows on the Allison desktop. Page Setup. Allows you to customize the layout for printed pictures. Print. Allows you to print pictures in color or black and white. Quit. Exits Allison. If the Preference Fewer Warnings is not selected, Allison will prompt you to save pictures not previously saved. Edit Menu Undo - Restores a document to its previous state prior to cutting, copying or pasting. Cut - When selected from a New Desk Accessory, removes the selected area from the document and places that area in the Clipboard file. Copy - When selected from a New Desk Accessory, copy duplicates a selected area and places that area in the Clipboard file. Paste - When selected from a New Desk Accessory, paste copies the contents of the Clipboard file to the current document. Clear - Clears the selected area. Does not copy that area to the Clipboard file. Show Clipboard. Displays a window showing the contents of the Clipboard file. Options menu Digitizing options. Selecting digitizing options open a dialog with controls for digitizing and processing the digitized image. The controls are listed below, from left column to right column. Dithering. Selecting this check box tells Allison to apply its dithering algorithm to images after color selection is complete. Dithering is not available when Previewing digitized images or when processing monochrome images. It is only available to color images during final processing. Aspect Ratio. Aspect Ratio refers to Aspect ratio correction. Aspect ratio correction traditionally means to correct for irregularly shaped pixels in the final display in both the X and Y direction. Under Allison, however, Aspect ratio correction is performed in the X direction only. As such it serves two main purposes. The first purpose is to remove noise that may be inserted during the digitizing pass. Such noise happens in the form of streaks on the extreme left edge of the image. The second purpose is to correct for irregularly shaped objects such as circles which may appear as ovals in some pictures. There are four levels of Aspect ratio correction available to you in the form of a "Pop Up" menu. The four levels are 0 percent, 1 percent, 2 percent, and 4 percent. The first level, Zero percent, applies no correction to the image. The second level, 1 percent, removes three pixels from the left edge of the image. The third level, two percent, removes 6 pixels from the left edge of the image. The fourth level, four percent, removes thirteen pixels from the left edge of the image. All levels of aspect ratio correction except zero percent, stretch the image to fill the entire screen. Additionally, aspect ratio correction is additive meaning that you can mix correction settings to achieve the desired amount of correction. For example, suppose you select one percent correction then press process. Three pixels will be removed from the left side of the image, next the image will be processed according to your settings. If additional correction is needed, simply press process again. Allison will remove an additional three pixels from the left edge of the image yielding a total correction of six pixels. A new window with a freshly processed image is produced for each press of the process button; in this way, you can choose which image best suits your needs. < Note: Aspect ratio correction operates directly on the raw image generated at the time you digitize. Because of this, Allison can generate a very smooth transition from pixel to pixel with blockiness or a Zoomed effect occurring only after very large amounts of correction have been applied. During normal use, this should present no problem. The raw image, however, is altered and cannot be restored to its pre correction state. This is the only instance where the raw image is the target of processing. Since raw images are very in terms of ram used, it was deemed impractical to allow restoration of an image. Fixed Palette. In monochrome mode, this is the only selection possible since the Apple IIGS gray palette can be computed before digitizing. In color mode, this button has two purposes. The first purpose is to allow you to digitize multiple images to one palette that is computed after the first pass of the digitizer. Once a target palette has been calculated, all subsequent passes of the digitizer will use that palette until you stop digitizing and select Calculated Palette and capture an image. The second function is to allow you to digitize to a palette that was calculated from a raw image that was loaded while the Keep Palette preference was selected. < Note: the second function will be ignored if you select calculate palette and you must load a raw image immediately before attempting to use the second method. The purpose of Fixed Palette is to allow you to create smooth color transitions from frame to frame should you desire to use a series of these frame in an animation program such as Paintworks Gold or Paintworks Plus. Calculate Palette. This is the default color digitizing mode. Selecting this option will allow Allison to calculate a new color palette for each frame of video information captured. For most images, this takes between 4 and 10 seconds depending entirely on the count of distinct colors in the raw image and whether or not a computer accelerator card is present. Brightness scroll bar values. The numbers appearing immediately to the left of the scroll bars labeled brightness correspond to the values sent to the digitizer with each capture pass. The values are color coded to correspond with each of the primary colors (i.e. the top value, Red in color corresponds to the red brightness scroll bar setting, etc.). Brightness control scroll bars. There are three brightness controls in Allison. Each bar is color coded for its function. All brightness controls are active during color digitizing; if desired, you can adjust these controls on the fly. In monochrome digitizing, the green and blue brightness controls are disabled and the red brightness control is used to control overall brightness of monochrome images. Contrast control scroll bars. The function and definition of the contrast controls is identical to the brightness group of controls except the contrast controls as implied, control contrast. The green and blue contrast controls are disabled during monochrome digitizing. These controls, like the brightness controls can be used on the fly. Contrast scroll bar values. The function of these items are the same as brightness values except they report contrast settings. < Note: During color preview digitizing it is normal for there to be a delay after using one of the color adjustment scroll bars. For this reason it is often best to click once in either the up or down arrow during color preview mode digitizing. Additionally if you press and hold down the mouse button, digitizing will pause until the mouse button is released. Preview area. The top center of this window is reserved for preview images. If a preview image is available to Allison, it will be displayed here, approximately centered on the color and contrast controls. < Note: During preview mode operations it is normal for the area to either side of the image to change color as the image is displayed. If no preview image is present, an informational message will be displayed in this area. Digitize button. This button activates image capture using the selections present in this dialog. Process. Pressing this button initiates Allisons image processing functions that you have selected. Once processing is complete, a full screen version of the processed image will be displayed. To continue, simply click the mouse button once. At this point a new window for the final processed image will be created. If no errors have occurred, the program will return control to the Digitizing options dialog. If an error occurs, you will be informed (see "What to do if errors happen"). Additionally, for as long as you don't digitize a new image, you can select different processing options such as dithering (in color only) and aspect ratio correction. Pressing Process will reprocess the raw image using the settings you provide. Cancel/Stop. This button has two names, hence it has two separate functions. If you are digitizing in color or mono continuous digitizing mode, to stop digitizing, simply press Stop once. In color, calculated palette continuous digitizing mode, a delay between clicking and stopping is normal. If you happen to click twice in the stop button, you will lose your image since the button will revert to cancel once digitizing and processing have completed. When the button reverts to cancel, in single frame mode, or after pressing stop, pressing cancel will return you to the Allison desktop. Processing information messages. Above Digitize, Process, and Cancel/Stop, during continuous mode color digitizing, progress messages such as "Processing" and "Digitizing" will be displayed. This is done so you can better judge when to press Stop. Color. Pressing this button selects color digitizing mode. Monochrome. Pressing this button selects monochrome digitizing mode. Additionally, pressing this button also automatically selects Fixed Palette mode. Preview. Pressing this button selects preview digitizing mode. Full Screen. Pressing this button selects full screen mode. Full screen digitizing mode is available only in monochrome mode. During this mode the keyboard is used to control the digitizing process. The control keys are as follows. Up Arrow Increases brightness Down Arrow Decreases brightness Left Arrow Decreases contrast Right Arrow Increases contrast Space bar Toggles pause r Lower case Restores default digitizing settings Escape Cancels digitizing without saving the picture Return Saves the current image and returns to the Digitizing Option dialog Mouse button Same as return One Frame. Selecting this option will allow Allison to digitize one frame at a time. If this option is not selected, Allison will be in continuous mode. Note that this button has no effect on monochrome full screen mode. Show Full Screen. Selecting this option or clicking in the content region of windows owned by Allison will show a full screen image. Hints for better pictures As with any large amount of data, the higher the quality of the input, the better the output (GIGO - Garbage in, Garbage out). If you're using a camera, try to use daylight balanced lighting indoors (available at most camera shops), outdoors, pick a nice sunny day, or use daylight balanced lighting at night. At Excellent Software, we use Sylvania BCA photo flood lights. Still, with the best lighting available there is no substitute for a good eye! Don't forget to play with the controls present in Allison. Also, remember that most cameras have a whiteness balance compensator. If you can override automatic whiteness compensation, you might get better pictures. If you're using video tape, Allison can digitize/freeze motion in many cases, however, if something moves quickly, the resulting image will reflect the movement. In color mode, movement can present a problem, however, experimentation is the rule to go by. If you're having problems, try pressing pause. If you've purchased Allison as an upgrade and aren't happy with the quality of color and monochrome images you're getting, the most likely cause is board calibration. Excellent Software is offering recalibration to existing users of VisionaryGS boards at $16.00 (includes shipping) per board. Address information can be found at the end of this document. Recalibration matches your board to Allison and allows you to get the best possible image. What to do if errors happen Allison has in place a very friendly error reporting mechanism. Most error messages contain suggestions that can help you correct a problem. However, with any software, unexpected events can cause unexpected results. Two of the most common problems that can occur are out of memory situations, and loss of video. Out of memory. If you have memory to burn, rest assured, Allison will use it. Allison can support multiple windows on the desktop until almost all memory is exhausted. Since Allison can produce images very quickly, you can also run out of memory quickly. Keeping raw images is one sure fire way to use memory at a startling rate. Raw images are 96,000 bytes in length. At first glance, that might not seem like too much, however, for speed, the images are stored as three separate "planes" in memory. Every effort is made to keep this area as tightly packed as possible, however, memory fragmentation will occur when many windows are open. Keep track of your windows. If you start getting windows stacking up more than two deep, it's time to start saving, then closing your windows. Should you see this message, "Unable to allocate memory. Allison will perform an orderly shutdown", Allison will still allow you to save your work, however, note that it's possible for your data to be corrupt due to memory requirements of the system. Every effort is made to ensure this doesn't happen, however, being aware it can happen is one step in ensuring it doesn't happen at all. Allison will run on systems with as little as one megabyte of memory. However, please realize that as GS/OS matures, its memory requirements increase. In order to more effectively use Allison, and to get the most out your work, we recommend you expand your memory to at least 1.5 megabytes, or deactivate all but the most essential Classic Desk Accessories, New Desk Accessories, Inits, CDEVS, and any driver that is unnecessary. More information on deactivating files can be found in the GS/OS OS Users guide. Loss of Video. The most common cause of this problem is a pause function on a VCR that has timed out. Other causes are 'video breaks' where there is no, or damaged video on the tape. Poor connections can cause problems too. In certain rare circumstances, loss of video or video spikes can cause Allison to crash. Every effort has been made to limited this possibility, however be aware that bad or no video can destroy the contents of memory causing a crash. If you do happen to get a loss of video situation - you will, everyone does, and it's usually because the pause control on a VCR has timed out, Allison will attempt to recover by displaying an alert (color or monochrome preview mode) informing you of the situation, and will wait for you to restore the video input. If you're in Full Screen mode, the computer will beep at regular intervals. Support Should you have any question about the use of this program, please feel free to contact Alltech Electronics at 619/721-7733. Fax 619/721-2823. You can also write to Alltech Electronics, 602 Garrison St. Oceanside, CA 92054. Online support is available on America Online in the Apple II Art & Graphics forum. Contact AFL Scott or Duelplay. Appendix A: File Formats Allison stores images in the following formats. 1. Raw image file. File type $C1, aux type $8001. Each raw image file consists of three 32,000 byte segments for red, green, and blue raw image data. Each byte of the file consists of two pixels. The file is arranged with X=0 and Y=0 as in the first byte of each segment. 2. Screen image files. File type $C1, aux type $0000. Please see Apple File Type Notes for a description of this file type. 3. Preview images are stored as $C0, aux type $0002 format images with no MAIN segment. This is subject to revision at any time. Please see Apple File Type Notes for a description of this file type. The segment name for preview images at this time is Preview. The pixel map occupies 8000 bytes stored in scanline order; the palette for the preview image is stored in 32 bytes following the pixel map. Appendix B: User registration. Please fill out the form below and mail it to: Alltech Electronics Co. 602 Garrison St. Oceanside, CA 92054 USER REGISTRATION FORM Returning this form will allow both Excellent Software and Alltech Electronics Co, Inc. to keep you updated on new products and future revisions of Allison. Additionally, you will get the final, typeset manual when it's complete. Name:_____________________________________ Address:___________________________________ City:_______________________________________ State:______________________________________ Zip:_________________ Phone:_________________ Enhanced Vision Plus serial number:____________________ Where did you purchase this software?___________________ __________________________________________ __________________________________________ Are you pleased with your purchase? _____________ If no, please explain?_____________________________ __________________________________________ __________________________________________ In what ways can we make this product better?_______________ ___________________________________________ ___________________________________________ How much memory is installed in your Apple IIGS? ___________ Do you use a hard disk drive?_________________________ Do you have an accelerator board?______________________ Have you used other video digitizers? ____________________