Scan Books using Free Software and a Digital Camera

HOW TO BUILT, INSTALL AND USE HOMER, A POWERFUL, SIMPLE AND FREE HARDWARE AND SOFTWARE PACKAGE FOR SCANNING BOOKS
By Cosimo Lupo and Juliano Spyer September, 2011

Homer is a package of hardware and software that provides an inexpensive and efficient solution to create a powerful book scanner using a regular digital camera. This manual explains how to build the prototype, download and install the software, and proceed to transform loose images into readable PDF files. Homer produces a digital book that maintains the formatting of the printed version while adding a second layer of data to allows the text to be searched, marked and copied. To give it a glance, you can watch this video (115) for a demonstration or watch this one (921) for a more detailed introduction to the project. For the newest information, including the links to download the up-to-date software, please visit: http://bookscanner.pbworks.com The hardware prototype is based on a previous model developed by Daniel Reetz and Matti Kariluoma. Dan is also the founder of an online community of technology enthusiasts sharing their knowledge and passion for do-it-yourself book scanning, which is where we drew most of our original inspiration to create Homer.

1. ABOUT THIS PROJECT Office scanners are made to copy office papers, not books. It is hard to fit correctly a book page and you also risk damaging the book.

MENU 1. About this project .p.2 2. How to build the prototype p.3 3. How to install the software p.4 a. Windows b. Mac OS X c. Linux d. Uninstalling Homer 4. How to copy a book .p.6 5. How to process the images .p.7 a. Step 1: Renaming and rotating

b. Step 2: Post-processing c. Step 3: OCR and conversion to PDF 6. How you can help developing Homer p. 11 7. Documentation p. 12 a. Homer bash script b. Homer installer for Mac c. Homer installer for Windows 8. About us/Contact us .p.18

There are commercial solutions today that simplify the process of digitalising books while lowering the chances of damage. Most of these make use of digital cameras, combined with some kind of software that converts the photos into readable documents. However, these solutions dont work for all cameras and their prices put them beyond the reach of the average consumer. Homer is a prototype that aims to bridge this gap. It works with simple digital cameras and uses a combination of free and open source software to transform loose digital images into a readable, searchable PDF. Plus, the software package includes an installer that automatically sets up all the programs, allowing also users with basic computer skills to benefit from the solution. Our aim in putting together this prototype is to enable libraries, schools and individuals with limited budgets to have access to a simple and yet efficient book scanning solution.

Homer is arguably an invented historical character credited with the authorship of the Iliad and the Odyssey, epic poems that are the beginning of the Western canon of literature. If Homer indeed existed, it is possible that he belonged to a professional class of ancient sing-poets called aoidoi in classical Greece. The aoidoi used a generations-old technique that emerged from oral literary tradition to memorize and spread culture.

1.1 Why Homer?

For the younger generations, Homer may also be the patriarch of the Simpsons family, an invention of modern-time aoidoi Matt Groening. This reference may suggest that Homer is a friendly book scanner, even to someone generally seen as incompetent and lazy as Mr. Simpson!

2 HOW TO BUILD THE PROTOTYPE

Since our prototype is very similar to the original cardboard-box book scanner designed by Daniel Reetz and Matti Kariluoma, we suggest you to read their guide for more detailed information on how to build the scanner (the guide is also available in PDF).

There is not much your need to know about how to build the prototype. Simply cut a cardboard box in half (preferably cube shaped), use duct tape to attach a small camera tripod to one of the edges, and extract a piece of glass from a picture frame you will need that to flatten the paper while scanning. Finally, position a desk lamp at the opposite side of the camera in order to light up the paper surface without producing glare on the glass. We used our own compact digital camera (10 Mpx), obtaining surprisingly good results.

Basically, the main difference between the two lies in the tripod: they used a taller one attached to the table, while we use a smaller tripod fixed to the box itself. The latter solution makes the scanner more portable, but also means that the tripods position is not adjustable: sometimes you may need to fix the inclination of the scanner by putting something (e.g., other books) under one end of the box, in order to keep the book pages parallel to the cameras lens.

3 HOW TO INSTALL THE SOFTWARE In order to use our book scanner, you need some software that is able to reorder the pages, fix their orientation, enhance their readability, recognize the text within them, and finally bind them into a single portable document. To do the job, there are of course several commercial applications e.g., Adobe Acrobat , though these are usually quite expensive. On the other hand, there are as well many free programs that accomplish the same tasks, producing results that well bear comparison with those of the commercial solutions. The only downside is that they are often more difficult to install and use than their commercial counterpart, for they may require developer tools which dont come pre-installed on every systems, or may consit in so-called command-line utilities (i.e., lacking a graphical user interface or GUI). To transform the photos into a digital book, Homer makes use of an array of free, open-source software to tackle specific tasks, all of which are already available online. It just adds two simple things: first, it provides an automatic installer that makes the process of setting up almost effortless; second, it brings together the various pieces of software into a single workflow that automatically rearranges the images, applies the optical character recognition (OCR) engine, and finally merges the files into a single, searchable PDF. Here you will find Homers donwload links for Windows and Mac OS X *. You can read the complete list of the programs included the packages at the Documentation page (see the section for Windows (section 7.3) and Mac (section 7.2)). Before using the installer, we strongly recommend to check that none of the included programs are already installed on your machine, to avoid accidentally overwriting them (the script isnt clever enough yet). If you have already installed any of those programs, you should probably be expert enough to manage without an automatic installer. When you are ready, select the package that is compatible with your operating system and download it on your computer, then follow the relative instructions.

3.1 Windows Windows XP /Windows Vista /Windows 7: Homer-v1.0beta1-Win.zip15 (size 165.5 MB - MD5 checksum: 92f14674e3952c8cf66fa5d0761b2cf4)

Extract the content of the ZIP archive somewhere on your hard drive, then launch the installer called Homer-install.exe, click Install and simply wait until the setup is finished. The process may take a while to complete, after which you will hear a
*

13300 x 300 DPI is simply a rule of thumb that work on most circumstances. If you want to obtain the exact figure you need to measure the physical dimensions of the area of which the picture was taken using a ruler, converting centimeters to inches14; then divide it by the numbers of pixels to get the DPI (dots or pixels per inch). Mac users can use the built-in Preview.app and drag with the selection tool a box around one scanned page, which will show the exact number of pixels it contains. Lets say the page is 20 cm long in the real world, while it is 3000 pixels long in the digital one according to the resolution, the distance of the page from the lens and the zoom level of my digital camera. The fixed DPI level in this circumstance will be 3000 pixels /( 20 cm = 7,87 inches ) = 381.

3.2 Mac OS X Mac OS X 10.6 Snow Leopard : Homer-v1.0beta1-Snow.dmg16 (size 149.6 MB - MD5 checksum: 603196f357c1d356d090a0a574194707) Mac OS X 10.7 Lion : Homer-v1.0beta1-Lion.dmg17 (size 148.8 MB - MD5 checksum: ed9711a17cb8d1ccefa806dfd3e8307a)

sound alert and you will notice two new shortcuts appearing on your Desktop, called respectively Homer and Scan Tailor. Note that on Windows Vista and Windows 7 the setup requires administrative privileges, so you will need to enter your users password upon launching the installer.

Mount the disk image (double-click on the .dmg file), and then launch the shell script named install.command. Enter your users password if the installer requires you to do so, and wait one or two minutes until the setup is completed that is, when the icons of Homer and Scan Tailor appear in the Dock. Please note that the Homer installer is only compabile with Intel Macs. PowerPC Macs are not supported yet. 3.3 Linux There is no Homer installer for the Linux platform (yet). However, since all the programs used by the Homer script were originally developed for Linux, it should not be difficult for Linux users to install them on their machine. Besides, the Homer script is written using the Bash scripting language, so it should be fully compatible with Linux or other *NIX based operating systems. We still did not have the chance to test Homer on Linux, but if you are a Linux user, please consult the support (chapter 6) page for details about the software required to execute the Homer bash script, and let us know if it works. 3.4 Uninstalling Homer If you wish to remove Homer and all the supporting software, simply launch the uninstaller which is located in C:\Program Files\Homer\Homer-uninstall.exe on Windows, or / Applications/Homer/uninstall.command on Mac OS X. Your computer should return to its original state.

4 HOW TO COPY A BOOK Place the book in the center of the cardboard box, so that the pages to be scanned are parallel to the cameras lens. Depending on the shape of your box, you may need to put some stuff under one end of the scanner to correct its inclination. Pay attention to the position of the light in order to avoid any glare on the glass. If your digital camera supports it, try to adjust the white balance to attain the best possible colours. Many cameras include a range of presets that cover common lighting conditions. For example, our cheap desk lamp turns out to be incandescent (hopefully not!).

The normal procedure is to start taking pictures from the pages on the right-hand side, then turn the book and scan the remaining left-hand pages. Thus, if you plan to scan the whole book, you can start from the cover, proceed until the end of the book, and then you rotate the book 180 degrees and scan the rest. Alternatively say you want to scan only a section of the book, or the book you want to scan is written in Japanese , you can choose to start scanning from the left-hand pages. There is an option on the Homer script that lets you choose whether the first half of the pictures must be treated as right-hand or left-hand pages. This is important to know because the two sets of pictures require different actions: right-hand pages must be rotated 90 degrees clockwise, while left-hand pages 90 degrees counterclockwise. The best way to make sure that the script wont fail in renaming and rotating the photos is to follow these two simple rules, however stupid they might sound at first:

Thus, for each scanned page there must always be another one following it. They must always go in pairs, be they right + left or left + right. So, if you scanned the right- hand pages first, you should proceed scanning from the next left-hand page immediately following the first picture, or viceversa. For example, if the first page you scanned is the front cover, then when you turn the book and take the second set you should begin with the inside of the cover page, i.e., the front endpaper. The reason is that, to reorder the set of scanned pages, the script gives each image file a number with an increment of two, so that the first half is given odd incremental numbers (0001, 0003, 0005, 0007, etc.), while the second half receives even numbers (0002, 0004, 0006, 0008, etc.). Therefore, if the total number is not even, the script may end up skipping some photos. Computers are stupid, but humans too make mistakes, especially when taking hundreds of pictures in a row. It is a good idea to check that there arent any duplicates or missing pages before feeding the beast. If you realize that there are indeed duplicates or missing pages, you have to delete the former, and rename the latter so that they will be placed in the correct alpha-numeric position. For example, you can append a letter to the interpolated images filename: DSC2139, DSC2140, DSC2140a, DSC2141, etc.

1. Take a total even number of pages (2n), regardless of whether the first half consists in right- or left-hand ones; 2. Never take the same page twice, and dont skip any page, not even blank ones you can delete unwanted pages after the renaming step is done.

5 HOW TO PROCESS THE IMAGES Once you have shot all your photos, download them inside a new folder on your PC or Mac. Now launch the application called Homer, which Windows users should find on their Desktop (it is in fact a shortcut), while Mac users find on the Dock. From here you have to select the input folder containing the images to be renamed and rotated.

After you have selected the input folder, you will be prompted to choose among four alternative options. The first two allows to rename and rotate the images depending on whether you started scanning from the right- or from the left-hand pages; the third option is for renaming the images without rotating them (a quicker option for those who prefer using Scan Tailor to rotate the images after that); finally, the fourth option is for running the text recognition software (Tesseract OCR) and for converting the files into a single, searchable PDF. Between the first three options for reordering, and the fourth one for converting to PDF, stands a middle step, which is perhaps the most important one and which cannot be included in the Homer script, not only because it is too complex but also because there is already a full-blown application for that, which happens to be free too: the middle step consist in postprocessing the images, and the application is called Scan Tailor, available on all operating systems. 5.1 Step 1: Renaming and rotating When you press 1 or 2 on Homers startup menu, all the images inside the input folder are automatically renamed and rotated according to your preferences. The original files are left untouched, while the renamed files are saved in a new folder inside the input one. The script renames and rotates about 2 images per second on average, depending on the speed of your computer.

Homer for Mac displays a dialog window from where you can browse your hard drive and find the wanted folders, whereas the Windows version immediately starts within the Command Prompt, and asks you to enter the path to the input folder (e.g., "C:\Documents and Settings\cosimolupo\Desktop\input-folder"). But theres no need to be scared of the black window. Both Windows and Mac users can drag and drop the folder onto the icon of the Homer script, which will then regard it as input for processing. And Windows users dont need to digit the full path, but can also drag and drop the directory containing the images on the Command Prompt window itself. The OS will then take care of inserting the right path (enclosed in quotes if containing spaces).

In order to rotate the images, Homer uses a program called jpegtran, a commandline utility included in the libjpeg library, which has the advantage of performing lossless transformations: that is, the rotation is done without decompressing and recompressing the data, and so causing a reduction of image quality due to generation loss (cf. Libjpeg, on Wikipedia).

5.2 Step 2: Post-processing Scan Tailor is a truly powerful tool for enhancing the quality of scanned images, making them more readable, more similar to print than mere digital photos of a book. Its developer, Joseph Artsimovich, defines it as

Here we will not try to explain in detail how to use such a complex program. For that, there is already the Scan Tailor Wiki page, which includes a User Guide as well as video tutorials. Here we will only give a few brief instructions in order to obtain acceptable results without too many troubles. Actually, the best place to start is the Quick Start Guide on the same official wiki. What follows is basically a paraphrase from the latter.

An interactive post-processing tool for scanned pages. It performs operations such as page splitting, deskewing, adding/removing borders, and others. You give it raw scans, and you get pages ready to be printed or assembled into a PDF (About | Scan Tailor).

300 x 300 DPI is simply a rule of thumb that work on most circumstances. If you want to obtain the exact figure you need to measure the physical dimensions of the area of which the picture was taken using a ruler, converting centimeters to inches28; then divide it by the numbers of pixels to get the DPI (dots or pixels per inch). Mac users can use the built-in Preview.app and drag with the selection tool a box around one scanned page, which will show the exact number of pixels it contains. Lets say the page is 20 cm long in the real world, while it is 3000 pixels long in the digital one according to the resolution, the distance of the page from the lens and the zoom level of my digital camera. The fixed DPI level in this circumstance will be 3000 pixels /( 20 cm = 7,87 inches ) = 381.

1. Lauch ScanTailor and select New project to begin with a new set of images. 2. Browse to select the directory that contains the images you wish to process. 3. ScanTailor will create by default an out directory for processed images placed inside the input directory. Leave it like that. 4. At the next stage its necessary to set the dots-per-inch (DPI26) level. Click on All pages, and use the Custom drop-down menu to select 300 x 300 . 5. We may skip the Fix orientation step if we have already rotated the images using jpegtran. 6. Click to Split pages, and Scan Tailor will try to autodetect the page layout. In our case, with a single-camera book scanner taking one page at a time, the correct option is the central one in the Page Layout section (i.e., single page with something to crop at the edges). Then click on the > arrow to have ScanTailor batch process the remainder of the images according to the selected Page Layout option. You should always inspect individual pages in the thumbnails to the right of the main page, in order to prevent Scan Tailor from cutting away some portion of text or image. Clicking on a thumbnail will load that page to the main area and allow for manual adjustment of various parameters. 7. After having splitted the pages, you need to deskew or straighten up the inclination of the pages such that the text is correctly aligned. Once again use the > arrow to batch process as needed and use the thumbnails to quickly check each page.

5.3 Step 3: OCR and conversion to PDF The third and last stage of the overall procedure is in turn comprised of two smaller steps: first, we need to apply to our pictures the optical character recognition (OCR) engine, so that the text contained in them will lend itself to be copied & pasted in our word processor, or highlighted and searched in our PDF viewer; secondly, we want to combine the scanned images and the OCR-ed text thus produced into a single, portable document that will retain the appearance of the images but will include an invisible layer of text underneath. In order to recognize the text from the images, Homer employs another free software, currently sponsored by Google, called Tesseract. This OCR engine was originally devel- oped as proprietary software at Hewlett-Packard, and has been released as open source a few years ago. It is compatible with all three major operating systems and, as of version 3.00, it supports as many as 35 languages. Did I say its free?

8. Click on Select content and batch process (> right arrow), while always keeping an eye on the thumbnails. If something is not selected you should adjust it manually, by selecting the thumbnail and resizing the content box in the main page as needed (by dragging its edges). If no content is selected a content box may be manually entered by selecting that image and right-click in the main window, Add content box. Likewise one may remove a content box from a page by right-click and Delete. 9. Then move to the Margins section and adjust the various parameters according to your requirements. ScanTailor defaults work well for most cases. Again, click the > arrow and then go on to the final step. 10. In the Output section, you can select the type of image output desired. Black and white will produce a clean output image for simple text and line drawings. If some text appears to be missing try increasing the line thickness to see if it appears. Once you choose your settings, these may be applied to all pages and run through the batch process (> arrow). Alternatively for images with photographs or graphics you may select mixed or even colour/grayscale. Our recommendation is to stick to black & white whenever is possible, so that the file will load faster and have a smaller size; and to select either 300 or 400 DPI as Output resolution, that is, about the same as the input one (600 is maybe too much for simple text). Anyway, its always better to check the thumbnails particularly at this final stage , to make sure that the required content is not excluded by mistake. 11. The output batch process is usually the one that take the longest to complete, de- pending on the overall performaces of your computer. Set up Scan Tailor to beep when finished and go have a coffee or tea. The output files will be saved as TIFF in the default out directory inside the renamed directory.

Now, the output of Tesseract are HTML files text encoded in the hOCR format, but thats not yet a PDF. For binding together the TIFF images and the HTML files Homer

uses PDFbeads, a small Ruby utility developed by Alexey Kryukov. Besides creating a searchable PDF, the program also compresses any b/w TIFFs using the JBIG2 encoder, a very efficient image compression standard: for example, a book of 384 pages is contained in a single PDF file of 11.8 MB (including front and back covers in colour, and several illustrations in mixed mode). Both Tesseract and PDFbeads are command-line utilities, so they are well suited to be run through a bash script. As we have already mentioned, the option number 4 in the Homer script is meant to run Tesseract OCR on the out folder the one containing the TIFF images processed by Scan Tailor , and eventually merge those images and their OCR-ed text into a searchable PDF. This is done in the same way as for the renaming-rotating task. That is, by draggin the out folder on Homers icon (or on the Command Prompt window), and then selecting the option 4. The script will prompt you to specify two variables before starting the process:

Text recognition may take 1 or 2 seconds per page on average, even more if colour/ greyscale. You can watch the ongoing process on the Terminal or Command Prompt window but its a boring sequence of Processed image 0234.tif, etc.. When the process is finally completed, the window will come to foreground and you will be able to press any key to show the results!

1. the language in which the scanned pages are written, identified by its threecharacters label. To view the complete list of Tesseract supported languages inside Homer win- dow, leave the field blank and press ENTER (you can also read the list online). For each languange there is a corresponing threecharacters label in Tesseracts vocabu- lary: English is eng, Italian is ita, Portuguese is por, etc. We didnt modify the labels, but used the default ones from Tesseract (dont blame us if Spanish is spa and not esp, while French is fra and German is deu...). 2. the name of the final PDF: you dont need to append the .pdf extension, it is added automatically; the filename may contain spaces; the file will be saved on the Desktop by default.

Note that the quality of the text recognition may vary according to various factors like the quality the original shots, their resolution, the sort of typeface which is used in the printed book, and so on. If you are not satisfied with Tesseract and are willing to spend a few hundred pounds on it, we would recommend to try Adobe Acrobat (either Standard or Professional), not only for its quite good OCR engine but, above all, for its state-of-the- art ClearScan technology which turns pixelated images of text characters into smoothed vector curves. In other words, for each set of scanned images it creates a custom font matching the visual appearance of the printed text characters and embeds it into the PDF. Not just it looks better, but also produces smaller files that loads/scrolls faster on a PDF viewer than common raster graphics.

10

Try it now!

6 HOW YOU CAN HELP DEVELOPING HOMER

Follow the instructions above (chapter 5) and at the end of the process you should end up with a PDF document featuring selectable text, which you should be able to copy and paste in another text document.

If you want to help us, you could test the Homer software package on your Mac or PC to see if it works accordingly. Here is a compressed ZIP archive containing some test scanned images taken from a printed version of this Wiki. You can use these photos to test the software before deciding whether you are interested or not in building the single-camera cardboard-box scanner. download: Homer-TestImages.zip35

If you experience any errors during the installation or the usage of the Homer script and its supporting software, please report them to this page. Test it on Linux (or other OS) Another way you could help us is to test the Homer bash script on a Linux machine. You can download the standalone bash script from this link (section 7.1). The script requires the following packages: ImageMagick jpegtran (included in libjpeg) jbig2enc Ruby39 RMagick40, hpricot and PDFbeads ruby gems Tesseract OCR (additional languages have to be manually insalled in the tessdata folder)

While Scan Tailor is not strictly required to run the Homer bash script, you may find it useful to test the Tesseract + PDFbeads step. The source code of Scan Tailor for GNU/ Linux can be downloaded from here, but there must also be available .deb or .rpm packages in some repository. You may also find useful to consult the DIYBookScanner Forum for help about related issues. Let us know if you manage to make it run!

11

7 DOCUMENTATION

Options: -r, --rename" rename the first half of the files with incremental odd numbers, the second" half with incremental even numbers (JPEG only);" -R, --right" rename (as above) and rotate the right-hand pages 90 degrees clockwise, and" the left-hand pages 90 degrees counterclockwise, starting from the RIGHT " pages (JPEG only);" -L, --left" rename and rotate (as above) starting from the LEFT pages (JPEG only);" -l, --lang" run Tesseract OCR and convert the images into a searchable PDF (TIFF only)," type \"homer -l\" (or \"--lang\") to view the list of supported languages;" -o, --output" for [-r, -R, -L], the output is the path to the directory where the renamed" images should be saved (default is \$1/renamed);" for [-l], the output is the path to the final PDF, or its filename (default" is \$PWD/out.pdf)."

The script loads a directory of images which is expected to contain 2n images, and applies to them a series of manipulations. If no arguments are entered, the script returns the Usage info: Usage: homer /path/to/input/directory [-r, -R, -L, -l \"lang\"] [-o \"output\"]"

7.1 Homer bash script (Download link for the standalone script: homer.sh)

If only the first argument (i.e., the input directory) is entered, the script prompts the user to select whether to rename & rotate, simply rename, or run OCR engine and converting to PDF. The options -R, -L, and -r allow to reorder a batch of JPEG images such that the first half and the second half are interspersed: that is, the first half is renamed with incremental odd numbers, while the second half is renamed with incremental even numbers. Finally, the option -l runs Tesseract OCR to extract the text from a batch of TIFF images, and then uses PDFbeads to bind the images and the text into a single, searchable PDF. The -l option must be followed by the three-character label for the

The options -R and -L allow to fix the orientation of the JPEG images, by rotating the pages on the right-hand side of book 90 degrees clockwise, and those on the lefthand side of the book 90 degrees counterclockwise. 12

desired Tesseract language. To print the list of supported languages with their correspondni glabels, you can type homer -l or homer lang.

The renaming/rotating bit of the script is inspired by Matti Kariluoma and his RenameAll.exe script, which he wrote for the already mentioned Cardboard Bookscanner project appeared on Instructables.com. The installation script install.command found inside the Homer disk image was written in bash and made executable by typing chmod 755 and appending the .command extension in the filename. When the user double-clicks on it, Mac OS X automatically opens the Terminal.app window and runs the script. Depending on the ownership and permissions of the /usr/local folder, the script may require the user to authenticate as admin. 7.2 Homer installer for Mac (download script: install.command)

The -o option allows to specify the output location of the renamed/rotated files (a new folder will be created if it doesnt exist), the location where to save the final PDF document (saved as out.pdf if the no filename is specified); or the name of the PDF file (the *.pdf extension appended to the filename is not necessary but will be added automatically if not entered by the user). The option accepts both absolute and relative paths.

The script runs the a modified version of homebrew.rb installaiton script to allow an offline installation. That is, instead of downloading the tarball from GitHub, the script untars a local archive mxcl-homebrew-3545a8d.tar.gz, pre-downloaded from GitHub and included in the Homer installation package. If you wish to update homebrew to the latest version simply type brew update in the Terminal.app. Most of the included hombrew formulas would require XCode i.e. Apples OSX De- veloper Tools in order to be compiled from their source code. However, we decided to distribute pre-compiled binaries along with the Homer package for Mac, so that you wont necessarily need to install XCode to run the Homer script on your Mac. To compile them we used Homebrew and XCode 4.1 running OS X 10.6.8 and 10.7.1, respectively for the Snow Leopards and Lions version of the Homer installer for Mac, which thus comprise two different packages for the two latest version of the OSX. We couldnt compile it for Mac OS X 10.5 Leopard, as the latter is not compatible with the MacBook Air. For the same reason, the software included is compatible only with Intel Macs like the Air, and not also for older PowerPC Macs. If you manage to compile it with older versions of OS X and older architectures, you are welcome to share here with us the results. The package also include some pre-compiled Ruby gems (see the list below). However, these are not installed in the default /Library/Ruby/Gems/1.8 folder, which is owned by root:wheel and would thus require another sudo, but inside 13

Homebrews Cellar directory in the /usr/local folder, whose group ownership is set to admin by Homebrew installation script, and therefore does not require the super user privileges (provided the user actually belongs to admin group). To this purpose, a RubyGem plugin called Brewbygems is installed. This adds post-install and post-uninstall hooks to RubyGems that update the symlinks in your Homebrew /usr/local/bin/ folder. The users RubyGems prefix is also changed to /usr/local/Cellar/gems/1.8 by adding the corresponding $GEM_HOME variable to the /.bashrc profile, need to sudo. Please note that if you have already another copy of Homebrew installed in /usr/local, or if you have installed any of the following programs with another package manager (e.g., MacPorts, Fink, etc.), but you still want to use the automatic installer, then it is advisable to completely remove all those programs before running the Homer installer, to avoid un- expected errors or conflicts. Alternatively, you can install the various programs manually and then download the standalone Homer bash script from here. Software included The installation script installs the following programs into the specified locations: /usr/local/bin/brew /usr/local/Library/Formula/... /usr/local/Library/Homebrew/... Homebrew, the missing package manager for OS X:

/usr/local/Cellar/imagemagick/6.7.1-1/... /usr/local/Cellar/jpeg/8c/... /usr/local/Cellar/jasper/1.900.1/... /usr/local/Cellar/little-cms/1.19/... /usr/local/Cellar/libtiff/3.9.5/...

ImageMagick, open source software suite for manipulating images, with its depen- dencies (version 6.7.11, binaries compiled through Homebrew):

/usr/local/Cellar/jbig2enc/0.27-17b36fa/...

JBIG2 encoder, compression tool for bi-level images (binary compiled through Homebrew):

Tesseract-ORC, free open source OCR engine sponsored by Google, with Leptonica library for enhanced image processing (version 3.00, binary compiled through Homebrew):

14

/usr/local/Cellar/tesseract/3.00/... /usr/local/Cellar/leptonica/1.68/...

/usr/local/Cellar/gems/1.8/gems/hpricot-0.8.4/...

/usr/local/Cellar/gems/1.8/gems/brewbygems-0.4.0/... Hpricot, HTML parser (pre-compiled Ruby gem):

Brewbygems, making RubyGems and Homebrew play nice together:

/usr/local/Cellar/gems/1.8/gems/rmagick-2.13.1/...

RMagick, interface between the Ruby programming language and ImageMagick (pre-compiled Ruby gem): pdfbeads, Ruby utility to create searchable PDF:

/usr/local/Cellar/gems/1.8/bin/pdfbeads /usr/local/Cellar/gems/1.8/gems/pdfbeads-1.0.3/...

/Applications/ScanTailor.app Homer (chapter 5), command-line script and GUI app (made with Automator) for renaming, rotating and binding scanned pages: 7.3 Homer installer for Windows /usr/local/bin/homer /Applications/Homer/Homer.app

Scan Tailor, interactive post-processing tool for scanned pages (version 1.0.0beta11 with experimental Dewarping support):

The installation script Homer-install-exe for Windows was made using AutoIT v3, a freeware BASIC-like scripting language designed for automating the Windows GUI. The installation script for Windows takes longer to complete than its Mac counterpart, as some of the programs to install need in this case to be compiled from source. Also, the script may require administrative privileges to run depending on the installed Windows OS version (User Account Control is enabled by default on Windows Vista and Windows 7).

(download script: Homer-Install.au3)

AutoIT scripts allows to interact with the Windows GUI in the same way a user would do with his or her cursor and keyboard. We could have told the user to download each program and install through its own installer (when available, like in

15

most cases for Windows programs). But we decided to make the procedure even easier, by automating the whole setup trough a unattended installation script. The user will only need to click Install once and then wait for the installation to complete.

The Homer script was originally written in Bash, which comes pre-installed in OSX and Linux, but not in Windows. Moreover, PDFbeads the utility to convert the images into PDF requires Ruby, which again is not pre-installed on Windows. Finally, PDFbeads requires two other Ruby gems (hpricot and RMagick) which need to be compiled from source with the developer tools. The solution to these problems is to install the Development Kit provided by the RubyInstaller project: the Ruby DevKit for Windows is based upon MSYS and MinGW, which not only provide development tools to build native Ruby extensions or gem, but also include the Bash command line interpreter system. This allows Windows users to run the same Homer bash script inside Windows Command Prompt, by means of a dummy batch file (.bat or .cmd) that calls the bash interpreter and runs the Homer bash script. The installer copy most of the software in an newly created C:\opt folder (except Scan Tailor which is installed in the default C:\Program Files). This is necessary because the command-line utilities work easily if they reside in a path without spaces. Finally, the script also update the %PATH% environmental variable to include all the folders in C:\opt that contains binaries, thus making their execution smoother. Moreover, another variable is added to the registry for the current user: its called %DESKTOPDIR%, and returns thepathtotheusers Desktopdirectory (e.g.,C:\Documents and Settings\cosimolupo\Desktop). The latter is used by the Homer script to save the final PDF document in that location. It is simply trick to overcome the issue of Windows system folders labels being dependent from the language currently in use: thus, the same folder is called Desktop in the English version, while Scrivania in the Italian one.

Software included The script install the following programs into the specified locations:

If you have already installed any of the following programs, and still wish to use the auto- matic installer, we advise you to uninstall all those programs before running the automated installation script, in order to avoid any possible conflict. Otherwise, it is better to install all the applications manually and then download the standalone Homer bash script from here. ImageMagick, open source software suite for manipulating images (official Win- dows binary installer version 6.7.010-Q16): C:\opt\ImageMagick\

jpegtran, loseless jpeg transformations (as found inside the GNUWin32 build of JPEG 6b4 library for Windows):

16

C:\opt\bin\jpegtran.exe C:\opt\bin\jpeg62.dll

RubyInstaller, the easy way to install the Ruby programming language on Win- dows (includes the Development Kit to build native C/C++ extensions or gems - Ruby version 1.87): C:\opt\Ruby187\ C:\opt\DevKit\

Tesseract-ORC72, free open source OCR engine sponsored by Google, with Lepton- ica library for enhanced image processing (version 3.00): C:\opt\Tesseract-OCR\

JBIG2 encoder, compression tool for bi-level images (Windows version of agls jbig2enc compiled by RubyPDF software): C:\opt\bin\jbig2.exe

Hpricot, HTML parser: C:\opt\Ruby187\lib\ruby\gems\1.8\gems\hpricot0.8.4\ RMagick, interface between the Ruby programming language and ImageMagick: C:\opt\Ruby187\lib\ruby\gems\1.8\gems\rmagick-2.13.1\

pdfbeads, Ruby utility to create searchable PDF: C:\opt\Ruby187\lib\ruby\gems\1.8\gems\pdfbeads-1.0.3\ cmdow.exe, command-line utility used in Homer batch script to activate the Com- mand Prompt window upon completion: C:\opt\bin\cmdow.exe Scan Tailor, interactive post-processing tool for scanned pages (version 1.0.0beta11 with experimental Dewarping support): C:\Program Files\ScanTailor\ Homer (chapter 5), command-line bash script (controlled via a Windows batch file) for renaming, rotating and binding scanned pages:

C:\opt\bin\homer.cmd C:\opt\bin\homer.sh C:\Program Files\Homer\Homer.bat

17

ABOUT US/CONTACT US

We are two master students at UCL Anthropology department that love techn, but this is not an academic project. We worked on it on our free time and without any grants or other financial incentives.

Juliano Spyer: Project management, general assistance and documentation. Twitter: @jasper Blog: http://naozero.com.br/ (in Portuguese)

Cosimo Lupo: Developed the Homer bash script and the installers for Mac and Windows. Twitter: @cosimolupo

18