(Version 1.01)

May 23, 2014

ScanFix is a program written in Java by Duane M. Palyka of Pal Katoonz. ScanFix assists traditional 2D animators who draw on paper and scan their drawings into a computer. When animators scan using a bulk scanner, the scanned drawings lose their alignment. Their digitized frames are offset and twisted relative to each other by the scanning process. ScanFix will realign peg holes on bulk-scanned animation frames so they match the original pre-scanned alignment. It also rotates the drawings in a user-selected direction for viewing and performs a flip-book style pencil test of the scanned and adjusted animation. You can try different "frames-per-second" speeds on your animation or scrub through them to see subtle differences.

Animators Using ScanFix

“The Flower” by Pedro Coronado: http://www.pecorona.com/theflower.html

“Good Morning Cephalgia” by Tom Smolenski: http://www.youtube.com/watch?v=YG_6hoYWADc

“Abandoned Bunny” by Sarah Johnson: http://www.youtube.com/watch?v=kb36EYRy9mQ

Articles Mentioning ScanFix

http://animation-studio-stuff.blogspot.com/2009/05/image-capture-for-animation-scanning.html

Tom Smolenski’s blog: http://www.smomotion.com/2009/10/28/new_software_pt1/

Where to find ScanFix

ScanFix can be found at http://www.pal-katoonz.com.

Problems Running ScanFix

ScanFix uses Java. It currently only runs on Mac OS X. In the future, I hope to have it running under both Windows and Linux.

What’s New

ScanFix with now input and output JPEG files.

ScanFix now works under Mac OS X 10.9 (Mavericks). The main application for Mac OS X is now called "MScanFix". (If you are running under Mavericks, be sure to enable Java by launching "Java Preferences" under "Applications/Utilities" and clicking on "Java SE 6" and "Enable applet plug-in and Web Start applications".)

If you need more memory to run MScanFix, you can now edit a text file called "Memory Allocation". Units are in either gigabytes ("g") or megabytes ("m").

Adjusting the Scanner for ScanFix

For ScanFix to work properly, the peg holes must appear totally black on the scanned frames. To assure this, it will be necessary for the user to determine what part of the scanner shows through the peg holes during the scanning process and to color that area solid black with a magic marker. If your scanner produces images that are larger than the scanned image, that area must be black as well.

Punched Paper

Most commercial scanners take 8.5" x 11" paper. This is too small for traditional 12-field animation paper, which is 10.5" x 12.5" 16-pound bond. If you cannot afford a scanner which will take full-sized animation paper, I recommend cutting the animation paper to 8.5" x 11" and drawing on the reduced size. Some animators use regular 8.5" x 11" 20-lb bond and punch holes in it, but I find this paper weight too heavy for good onion-skinning. It's a matter of preference. If you want to punch holes in 8.5" x 11" paper, search google for 'Animation "3 hole punch"'. Purchase one with standard animation peg hole punches, not the one that punches round holes. If you have a large expensive scanner like the Epson 10000XL (12.2" x 17.2"), then ScanFix can work here as well if you assure that the color behind the scanned image is black so that everything outside of the image area scans as black up to the edges of the scan. When you run ScanFix, you also have to check the "Animation Paper" checkbox on the splash screen. ScanFix expects the paper to be rectangular (one side larger than the other) with the pegholes along the larger side.

Setting up the files to be scanned

1. Using some image manipulation app like Photoshop, scan in all the files that are part of the scene or sequence. Make sure the peg holes are all on the same edge-- although that edge could be facing any one of the four directions. Try to align them as best you can by hand. If you are using the bulk scanner or just scanning by hand, the purpose of ScanFix is to correct the alignment of all the scans for you.

2. ScanFix should work at any resolution. A good resolution is 1500 x 1200 (8.5" x 11" x 150 dpi). ScanFix has worked fine with 300 dpi and even as high as 600 dpi. The only known problem with differing image sizes and resolutions is that ScanFix may crash if the size of the images is too large for the memory that ScanFix has allocated to it. Under these conditions, you usually get the error message: "java.lang.OutOfMemoryError". (See "Memory Size Adjustments" below.) Please email to support@pal-katoonz.com examples of scans where the resolutions didn't work and where the problems are something other than memory size crashes (since they can be corrected).

3. After scanning in the frames, save them in either JPEG or TIF file format. If you save in TIF, save it with no compression. If you save in JPEG, there are no restrictions regarding file format, but JPEG is "lossy". In TIF file format (which is not lossy), you can save them as grayscale, 24-bit RGB Color (no alpha), bitmap or indexed color. In ScanFix, all will be treated as their original format except indexed color, which will be treated as grayscale. However, ScanFix will save them in their original formats. When saving as TIF files, (1) Set "Image Compression" to "None", (2) Set Pixel Order to "Per Channel", and (3) Set "Byte Order" to "Macintosh". Feel free to mix file types in the same folder. That is, you can mix bitmap, grayscale, RGB or indexed color files in the same folder and they will all be processed in the same pass. Also, in the unlikely event that you scan images with different resolutions, ScanFix will alter their resolutions to match the first scan so they all will match in size.

4. Select the scan that you feel is the one with the best alignment. You will use it for the "base" scan.

5. Put all the scans into a folder that will be the input folder for ScanFix.

6. Create an empty folder close by for the fixed output scans. ScanFix will place all the corrected scans into that folder. To protect you from overwriting your original files, ScanFix will force you to choose different folders for input and output.

File Naming and Numbering

ScanFix does not care what names you give to your drawings or how you number them. You don't have to number them at all and ScanFix will still work. However, if you don't number them in alphanumeric order, the optional pencil test mode won't show the drawings in the proper order. Also, you will probably have trouble with them in later parts of the process after ScanFix. Alphanumeric order means that you must pad the numbers with 0's to look like "foo.001.tif", "foo.002.tif", "foo.003.tif", ... , "foo.009.tif", "foo.010.tif". If you don't pad them, the order will be "foo.1.tif", "foo.10.tif", "foo.2.tif", "foo.3.tif", ... , "foo.9.tif". Frame number 10 will be out-of-order.

Launching ScanFix

ScanFix has no installer. Simply drag the "ScanFix1.01" folder to the main hard drive and run it from there. Putting this folder on the desktop is fine or in the Applications folder or in any other folder on the main drive.

In the "ScanFix1.01" folder, you will find three files that can launch as clickable applications: (1) "MScanFix.app" (usually just seen as "MScanFix"), and (2) "ScanFix.jar". "MScanFix.app" is a Mac OS X application bundle with 1024 MB of memory assigned to it. And "ScanFix.jar" is a Java Jar file which uses the default Java memory size of 64 MB. Only run "MScanFix.app". It will call "ScanFix.jar" itself-- allocating more memory to it.

Java must be installed on the computer no matter what version of ScanFix you choose to run. For Mac OS X, Java can be downloaded free from Apple at http://support.apple.com/kb/DL1572. If you wish to increase the memory size used by "MScanFix.app", please see "Memory Size Adjustments" below.

Note

The "ScanFix1.01" folder also contains a few extra files including a copy of this document. It needs these files to run, so please leave the ScanFix runnable applications in this folder. ScanFix will also generate extra files in this folder when it runs. One of the files it generates is "ScanFix.log", which contains a log of everything it does. You may delete this file periodically when it gets too large. ScanFix automatically regenerates a new copy of this file. Please don't delete any other file in the folder.

Running ScanFix

The easiest way to run ScanFix is to launch MScanFix and hit "CONTINUE" on the SplashScreen when it appears. You will then be led through a couple of dialog boxes that gets ScanFix running.

A more detailed explanation:

1. Double-click on the MScanFix icon. The first time you run it, you will be presented with two windows—one containing a license and a smaller one containing “accept” and “reject” buttons. If you don’t see this second window, it may be hiding under one of your other windows. After you accept the license conditions, the ScanFix splash screen appears with a few checkboxes and buttons:

Command Input

2. The first three buttons deal with the new “Command Input” feature-- for your optional use to make production more efficient. For basic operation for beginners, you may want to skip this section and come back to it later.

"Command Input" is a big complicated, but, once you get the knack of it, it can make your ScanFix process more efficient.

In normal operation of ScanFix: whenever you click on a checkbox, select an input or output folder, or perform other similar actions, ScanFix records it and writes the command and its associated values to a text file named “ScanFix-Command-Output.txt”. (Actually it saves the old version of that output file first to “ScanFix-Command-Output0.txt”).  With "Command Input", you can re-use these saved commands to repeat operations with slight variations.

Since these files are just text files, you can edit them outside of ScanFix, rename them, remove commands and add commands as you wish. If you edit these text files, be sure to use a text editor that creates only text and doesn’t insert special characters. On the Mac, “TextEdit” is good if you have it read a text file first. (It won’t write one as “.txt” when you create one anew. )

You can use either the “<FILE” button or the “<VIEWER” button to choose the command input file you want to use. After you select the file and it performs the commands, you have to click the “Continue” button to continue running ScanFix.

The “<VIEWER” button additionally allows you to view the text files first before you select them. You can then select one of the files that you choose to view.

If you want the “<FILE” button and the “<VIEWER” button to continue automatically after selection (so you won’t have to press the “Continue” key), put the command “continue” into the file on the line about the “END” command.

The “<COMPARE TEXT” button allows you to compare two command files, line by line, through two viewers. Differences will show up in red. You can then select a command file to use as you would through a single viewer.

All commands should appear first on a line followed by a space and then whatever value you want to give to the command—if one is needed. Available commands are listed below.

Notice that the “<VIEWER” has special buttons specifically so you can view the last output file and the previous one. You can even select one of them. However, be aware that sometimes some command strings do not make it from the input file to the output file. All the commands in the command input file get executed, but some of their names just don’t make it to the output file. Hopefully this will be fixed in the future.

A good way to use this “Command Input” feature is: (1) Run ScanFix normally once without using command input. (2) Take the file “ScanFix-Command-Output.txt”, which was generated by that run of ScanFix. (3) View it with “<VIEWER” to make sure all the commands are there. (Add any that are missing.) And (4) rename it to be “ScanFix-Input1.txt”. Use that file for future runs of ScanFix—modifying it as necessary.

Rest of the Checkboxes and Buttons

3. Please use the “QUIT” button to exit ScanFix. It does the right stuff to clean up when you leave. In particular, it places an “END” at the end of the Command Output File. This is needed for all your commands to be input properly. On the Mac OS, do not use the “Quit ScanFix (command-q)” under the “ScanFix” menu! Mac OS put it there. If it is made to work right in future versions of ScanFix, I’ll let you know. Meanwhile only use the “QUIT” button on the SplashScreen to exit ScanFix.

4. The checkboxes that are checked are recommended to be checked. You may, of course, turn any of them on or off as you wish. The checkboxes are as follows:

a. “Trans BG” checkbox allows you to export additional files with your drawings on a transparent background. This allows you to treat your black-and-white drawing as an animation cel. The files will be “.png” (ping) files with an extra “t” after your file name.

b. "Twist Adjust": ScanFix does optional rotates to correct for twists on the scans, so you may want to leave this checked. If you don't, the scans will be adjusted for offset but not for twist. In cases, where the pegholes are deformed or torn badly, ScanFix may make better adjustment without trying to un-twist the scans. If the adjustments are not ideal, try a pass with “Twist Adjust” turned off to see just what “Twist Adjust” does.

c. "Rotate 90 degrees Clockwise or Counter-clockwise": After the scan is adjusted ScanFix will rotate the image to the view you prefer. This will show in the Pencil Test and will also take effect in the saved file if "To File" is left checked.

d. "Trim": Lets ScanFix trim the shape of the found pegholes to make it into a more rectangular shape. This will not show on the drawing itself, but will allow ScanFix to calculate the center of the peghole more accurately. This is particularly beneficial if the drawings have torn or deformed pegholes. The degree that the rectangular shape is imposed is governed by the “peghole tweak” called “trim percent”. (See “peghole tweaks” below.) The larger the percent, the more rectangular ScanFix tries to make the peghole. If the adjustment to the scans are not ideal, try a pass with “Trim” turned off. That will show you if “Trim” helps or not.

e. "Animation Paper": Lets ScanFix know that you are using 10.5" x 12.5" (12 field) animation paper instead of 8.5" x 11" bond with holes punched in it.

f. "Fixit": Allows the user to install special code to fix certain problems which may occur with licensing. These codes will be sent from support@pal-katoonz.com in response to complaints.

g. "Debug": Used if problems occur (mostly for my use). It gives a more verbose listing of your progress.

h. "Pencil Test" allows an optional pencil test window to appear. With the slider you can watch your animation with various timing. If you check the "Scrub" checkbox in the Pencil Test window, you can scrub through each frame and watch for subtle differences. Unchecking the "Scrub" checkbox returns to pencil test viewing at the last slider position. The only reasons to uncheck the "Pencil Test" checkbox are (1) to make ScanFix run faster (As ScanFix sets up each frame for the pencil test, it runs slower) and (2) to use available memory more efficiently (The pencil test process uses more memory).

i. "Continue": Clicking this button causes the process to happen. After one pass of scanned images, it will return back to this splash screen for another set of instructions.

5. When ScanFix prompts you, use the file dialog browser to open the input folder you made and to select the "base" file for scanning. Notice that instructions are in the title bar of the dialog box.

6. When it prompts you again, use the file dialog browser to select the output folder so it knows where to place the fixed scan files.

7. Now ScanFix takes every TIFF of JPEG file in your input folder (which ever you have selected), tries to find the peg holes and align it with the base TIFF or JPEG file, and writes it into your output folder. It also prints statements for every thing it does. Usually it finds both pegs on each sheet but occasionally it misses a peg. For your "base" scan, try to choose a file in which ScanFix finds both pegs. For offset alignment, ScanFix only needs to find one peg on each subsequent scan. If you have "Twist Adjust" selected for twist alignment, both pegs will be necessary. It will not "twist adjust" scans where it only finds one peg.

8. ScanFix provides a text window that displays its progress. There is no need to save this window. ScanFix also creates a text file called "ScanFix.log", which records your progress for every time you run ScanFix. It appends your current text window to this file.

9. Whenever things don't go right, first try making changes using “Peghole Tweaks” as described below. If things still don’t work right, then please email support@pal-katoonz.com a set of at least three sample files where problems occurred. These include cases where ScanFix could only find one peg hole or cases where it didn't find any or found other things that it mistook as peg holes. Please also report any interface problems that you encounter or just things that I should change to improve ScanFix. You may also say nice things about ScanFix if you wish. I like hearing that.

Memory Size Adjustments

If you run out of memory when ScanFix runs, you may want to deselect "Pencil Test". If you want to have pencil test selected when you run ScanFix.jar, you must allocate more memory for ScanFix. How much memory should be allocated? Some large amount will be fine-- like 2GB or 4GB. If the amount exceeds the amount of memory on your computer, that's all right. ScanFix will swap to disk when necessary. Use the following procedures to increase memory size:

Edit the "Memory Allocation" text file in TextEdit and change the values. Either use gigabytes ("g") or megabytes ("m"). Relaunch MScanFix to make it work.

Commands Available for Command Input

The following commands are currently implemented in ScanFix. The command must fall at the beginning of the line with the rest of the line for its value(s)—each being separated by spaces or tabs.

1. Commands with no numbers or strings afterwards:

continue (must be the next-to-last string in a command input file. It allows the program to exit the SplashScreen and continue the full run without having to press the “Continue” button.)

END (must be last string in command input file)

2. Commands followed by a string:

inputDir (input directory (folder) name—separated by “/” (not “\” or “:”). Spaces are allowed in the directory name.)

outputDir (output directory (folder) name. Same rules as above. Must be different from “input directory”)

inputFile (name of the “base” file for scanning. Must be a “.tif” or a ".jpg" file.)

outputFile (usually same name as “inputFile”)

3. Commands followed by a “true” or “false”. These match the checkboxes described above. If a command name doesn’t make it to the output file, it’s usually one of these. To my knowledge, the commands above always make it.

animPaper

doTwist

debug

doTrim

doPencilTest

doRotCW90

doRotCCW90

doRotToFile

doSaveTran

There are a few example command input files in the "ScanFix1.01" folder.

Peghole Tweaks

In the "ScanFix1.01" folder, you will find a text file called "Peghole Tweaks". If ScanFix doesn't find two peg holes for every scan, it may miss a few rotates. Even if it does find all the peg holes, the adjustments may not be as good as you would like. If you are experiencing problems, try running a pass with “Twist Adjust” turned off, then one with “Trim” turned off. After you get a feeling for how these help you, try making changes in the “Peghole Tweaks” file. The "Peghole Tweaks" file gives you a means to tweak two variables for determining the shape of the peg holes. If you remove "Peghole Tweaks" from the folder (or rename it), ScanFix will just use the default internal tweak values (currently 75 and 97). Both of these numbers are percentages and range from 0 to 100 each. Changing the numbers in this file will tighten or loosen the way ScanFix finds pegholes.  The first number is the minimum peghole percent of black to look for in the peghole search. None of the pegholes are perfect rectangles. The idea is to find something that roughly looks like a peghole and then “trim” it to find the rectangle within. The second number is the percentage of the perfect rectangle towards which to “trim” the found rectangle. You have to play with these numbers.

A comment on the structure of the “Peghole Tweaks” file itself: ScanFix only looks at the first two values in the "Peghole Tweaks" file. When it finds those two values, it stops looking. You can put anything you want after these numbers in the file-- like tests that didn't work and related comments. If you “comment out” the first two numbers by putting “//” in front of each line containing each of the first two numbers, i.e.: //75, //97 (each on a separate line), ScanFix will skip over this set and try to find another two numbers in the file. This allows you to experiment with different sets of numbers in this file.

Use of External Devices

You may encounter problems if you attach an external device (e.g. a hard drive) onto your computer, run ScanFix from the computer and process image files on the external hard drive. The only success I had was on Mac OS using an external hard drive formatted with the Mac file system accessed through firewire. Using an external hard drive formatted with fat32 failed on the Mac. All failed attempts gave the following error message when attempting to read a Tiff file: "getTiff Error reading file. Unknown byte order: (0, 5)". This needs further investigation.

Other Issues

1. In the pencil test, the red and blue color channels are switched. However, the color channels are correct in the output image file.

History of Bug Fixes

1. 02/08/04: Released version 1.0b3. Fixed bugs related to resolution problems. Now should work at all resolutions. Totally redesigned the rotation code. Rotation looks very solid now.

2. 04/17/04: Released version 1.0b4: Now can input and fix 24-bit RGB color BMP files as well as the 8-bit black and white BMP files that it fixed before. Restrictions: (1) No alpha channel on the RGB images and (2) Cannot combine both RGB and BnW files in the same pass.

3. 06/07/04: Released version 1.0b5: Wrote a TIF image decoder and encoder. Now can input uncompressed TIF images in the following formats: grayscale, RGB color and bitmap. Can also input indexed color images, but they will be treated as grayscale. Still supports BMP images. Can have different formats in the same folder (relieves a restriction from last build.)

4. 07/24/04: Released version 1.0b6: Created a Jar file that makes ScanFix into a clickable application. Had to add a text window to replace the terminal for displaying information. Also began saving all text records in a text file called "ScanFix.log". Fixed some error exit bugs that showed up during these changes.

5. 10/19/04: Released version 1.0b7: Created a clickable "ScanFix.app" for Mac OS X. Added an optional pencil test with FPS adjustment. Added protection from overwriting input files with output files. The output folder must be separate from the input folder. Designed new splash screen. Added license agreement window.

6. 10/27/04: Released version 1.0b8: Created a check box for Animation Paper (10.5" x 12.5"). Updated program to adapt to a large scanner that leaves a large border around the drawing. Border must be black. Finds black border, turns it white, and deals with the drawing within. Created a "Peghole Tweak" file input to allow four tweaking variables to be changed by the user. Adjusted parameters for Animation Paper size.

7. 1/12/05: Released version 1.0b9: Redesigned the Splash Screen and the Splash Screen Dialog Box. Added ability to rotate the frames 90 degrees either clockwise or counter-clockwise and to optionally save the rotated frames to the output file. Added ability to wrap around so you don't have to leave ScanFix after each run. Added scrubbing to the pencil test dialog. Removed BMP file format as an option (TIFF should be sufficient and less to maintain and upgrade). Improved garbage collection for better memory management. Made copyright updates for 2005. Changed references to "Duane M. Palyka" to "Pal Katoonz" instead. Assorted bug fixes and tweaks.

8. 1/25/05: Added a Windows executable version of ScanFix (ScanFix.exe) to the ScanFix folder. No change to ScanFix.jar, so version number is still the same.

9. 2/10/05: Added a Mac OS X executable version of ScanFix (ScanFix.app) to the ScanFix folder. This was a persistent problem since, no matter how hard I tried, I couldn't get MRJAppBuilder for OS X to create a launchable app file. The lack of this app file forced the user to use the terminal to launch ScanFix in order to have enough memory allocated to run ScanFix properly. My workaround solution was to write a Cocoa application which runs AppleScript which then calls a unix shell script to launch ScanFix.app. This roundabout method has one drawback. It requires a unix-style path. In other words, the name of any Mac folder in the path can't have a space in it.

10. 2/7/06: Fixed a bug that crashed ScanFix with: "Fatal Error in ScanFix!!! Exception:java.lang.ArrayIndexOutOfBoundsException". It resulted when various frames in one input folder were different sizes. I believe this bug is the one that caused ScanFix to crash when looping for different sets of frames. ScanFix should be more stable after this bug fix.

11. 7/30/06: Released version 1.0b12. No changes.

12. 2/28/07: Released version 1.0b13. No changes.

13. 8/29/07: Released version 1.0b14. No changes.

14. 2/28/08: Released version 1.0b15. No changes.

15. 8/27/08: Released version 1.0b16. No changes.

16. 1/8/09: Released version 1.0b17. No changes.

17. 8/26/09: Released version 1.0b18. No changes.

18. 1/1/10: Released version 1.0b19. No changes.

19. 5/24/10: Released version 1.0b20. Eliminated center round hole from peghole search. Loose settings on “Peghole Tweaks” would accidently catch this as the “second peghole”. This would be acceptable for translation, which is dependent on the first hole, but would cause bad twist angles affecting the real second peghole. This also establishes less need for Peghole Tweaks, which now works well being looser. Peghole Tweaks should only be used in extreme circumstances—very thin pegholes or extreme scan resolutions or other odd circumstances that I can’t predict.

20. 5/25/10: Released version 1.0b21. Installed a backup system for finding pegs when the main system misses them. Finding pegholes looks solid at this point.

21. 8/9/10: Released version 1.0b22. Eliminated the original system for finding pegholes and started using the backup system instead. Refined the “backup system” by adding “Trim” to find the “perfect rectangle” within the scanned peghole. This allows ScanFix to use torn and deformed pegholes. Dramatically changed “Peghole Tweaks” to contain two adjusting percentages to find the pegholes. “Twist adjust” only worked correctly if pegholes were on right or left. Now works the same on top and bottom as well.

22. 2/26/10: Released version 1.0b23. Minor cosmetic changes. Only released it for three months instead of for six. Working on an installer, which should be ready within that time frame.

23. 5/30/11: Released version 1.0b24. Added Command Input and Output. Added ability to write drawings with transparent background as ping files. Other minor bug fixes.

24. 8/19/11: Released version 1.0b25. No changes.

25. 2/24/12: Released version 1.0b26. Added “Compare Text” button.

26. 8/14/12: Released version 1.0b27. No changes to program, but added "Problems Running ScanFix" above.

27. 8/29/12: Released version 1.0b28. Make changes so it would work with Mac OS X 10.7 (Lion). Redesigned the main application for Mac OS X. It is now called "MScanFix". It no longer has the "Mac Pathname Limitation" of having a "unix-style" path without any spaces. Added the text file "Memory Allocation".

28. 12/31/12: Released version 1.0b29. Fixed problem with inputting color Tiff files. Added ability to input and output JPeg files. For images of different resolutions, now adjusts size to match first selected.

29. 1/27/13: Released version 1.0. Added licensing software.

30. 5/23/14: Released version 1.01. Updated for Mac OS X 10.9 (Mavericks). Fixed a bug that blocked free version updates from running.