------------------------------------------------------------------- THIS README EXPLAINS WHAT IS BEHIND THE SCAN SCRIPT FOR 3D SCANNING ------------------------------------------------------------------- Table of Contents 1. Introduction 2. Configuration 3. What the script does 3.1. Technical issues 3.2. Operational issues 4. Options 5. Bugs and known problems 6. What is yet to be done 7. Support and contact ---------------- 1. INTRODUCTION ---------------- The SCAN script is a command line system for structured light scanning. Its first feature was to control a KODAK camera connected to a PC computer using Linux. In order to achieve this, we used the kdcpi free library for KODAK cameras avaiable on the WEB. As we were adding more features we realized that the process of taking pictures of a object while projecting Graycode patterns was not only time consuming but also could lead to some imprecision because of the hardware manipulation by the user. Therefore, this script incorporated more tools to make the strucutred light scanning process a lot easier for those that use Linux. ---------------- 2. CONFIGURATION ---------------- The scan.sh file is the only shell script file needed for the scanning process to run properly. The script requires Linux bash shell to work. In the beggining of the file there are some variables that must be set in order to configure the script correctly. They are: libdir - This is the path to the kdcpi library directory. Example: /home/username/dirname/kdcpi-0.0.3/ speed - The default value is 115200. Since this script expects a serial KODAK camera to work you should leave the speed at this maximum value. Other values are 9600, 19200 and 38400. camera - The supported KODAK camera types are DC40, DC50, DC120, DC200 and DC210. The DC215+Zoom model can also be used with the DC210 settings. userdir - This variable contains the environment variable (CALIB_DIR) that represents the path to the directory where the script is. For example, if you put the SCAN.SH file in the directory "/home/username/documents/scan", CALIB_DIR should be set as /home/username/documents/. Be sure to set correctly all the above variables before start using the script. Note that all paths end with the "/" symbol instead of a directory name. Some of these notes can be found at the help option. ----------------------- 3. WHAT THE SCRIPT DOES ----------------------- This script was created to make easier the management of the scanning process. It uses the kdcpi library for KODAK cameras in order to make the communication between the Linux operating system and the camera used. The same idea can be expanded for other cameras, though a different library must be used. The script uses only the kdcpi features of download camera images, list all pictures already taken, delete all pictures taken, take a snapshot and check the camera status. Also, the script allows the user to make a 3 steps calibration, scan models and create directories for the scanned objects. The script automatically scans the object and create the image files needed for decoding and active triangulation. These two other steps must be implemented somewhere else. For more information go to http://www.visgraf.impa.br/3Dphotography/doc/decoding.html The are some things this script can't do: control the camera zoom, delete a specific picture taken and download a specific picture from the camera. Although some these features are part of the kdcpi library they were not implemented because we had no need of them. Also the script does not create Graycode patterns for projection. You need to created them separately in a different directory. 3.1 Technical issues ----------------------------------------------------------- Each option has its own technical overview, but as a general rule the script uses kdcpi commands to communicate with the camera in order to make the desired actions. The script was designed to lead the user during the scanning process without missing any important step. It also give all the needed commands for the OS in order to project the graycode images onto the object. The script was tested using a DC215+zoom KODAK serial camera. Probably, USB cameras can work better and faster but these were not tested yet. The multimedia projector used during the scanning sessions was a CTX Display System projector with 800x600 of maximum resolution. We used the RedHat 7.3 Linux distribution running on a 1,6 Ghz Pentium 4 machine with a GForce2 video card (NVIDIA driver). All Linux distributions that are supported by the kdcpi library can be used. More information can be found at http://www.berkhirt.com/HomerProductions/products/kdcpi/. 3.2 Operational issues ----------------------------------------------------------- Some important observations must be made about the script use and the scanning process. First, we are supposing that you have a multimedia projector correctly connected to the computer. Second, you should install the NVIDIA (www.nvidia.com) display driver for Linux and set the "TwinViewOrientation" option to "RightOf". This allows the script to open the Xloadimage program in the other half of the screen with the Graycode patterns. Third, the script need access to the serial or USB ports so the system administrator should set the correct permissions beforehand. Fourth, the Graycode patterns projected must be compatible with the projector resolution. This means that if you have a 1024x768 projector your Graycode patterns should have this same resolution or less. Images bigger than the display area are not correctly set by the Linux X server, nor are they clipped. The projected patterns will be cut and not centered. Fifth, be sure the object can be totally seen by the camera and that the projector focus enough to be visualized at higher resolutions (thin stripes) by the camera. Once the setup is done, make sure your camera is turned on and the flash is disabled. You can lock the camera exposition and zoom once you have a good position. ---------- 4. OPTIONS ---------- Option 0 - Help Displays the help. This command is straightfoward. Option 1 - Status Checks the camera status like number of pictures taken, if the flash is on, and so on. Option 2 - Dump Downloads all the pictures from the camera using the "dump all" command. The kdcpi library has an option "dump #" where "#" is the picture number in the camera. This variation is not being used. Option 3 - Snap Takes a single picture. Good if you want an image of the object without the patterns projected onto it. Option 4 - Delete Deletes all pictures from the camera. Like the dump option, it has a "delete #" version that is not being used. Option 5 - List Lists the pictures from the camera. Good if you want to know if the previous scan made was properly deleted. If not, use the delete option. Option 6 - Gphoto GUI Opens the Gphoto program. Obviously you must have it installed beforehand. The Gphoto program is a GUI interface to do the same things the kdcpi library does, with more features yet. Option 7 - Exit Exits program. Option 8 - Create 3D model directory This option allows you to create a directory for a future scanned model. Note that the the name you put on the directory will be the same name of the scanned images used for decoding and active triangulation. Never use spaces when creating names. Option 9 - Scan model Starts the scan process. The user has the option to create a directory for his model first, as in option 8. If so, the program goes back to the main menu again. If the user chooses to start the scan process, the system asks for the directory name, the path to this directory (if not already set as a environment variable) and the number of Graycode patterns to be projected. The script will send a command to project the pattern in the right side of the screen, exactly in the middle of the projection area, using the Xloadimage program. While the pattern is being projected the script sends a "delete all" command and then a "snap" command to the camera. The process is killed and a new pattern is projected. The projection-capture process continues until all Graycode patterns are projected. The pictures are downloaded ("dump all") and renamed. The first two pictures taken are a picture of the object with full ilumination of the projector (white pattern) and a picture of the object with no ilummination (black pattern). All picutres are saved in the .jpeg format. Note that the script looks for Graycode patterns with the following names: P0, N0, P1, N1, P2, N2, and so on, which means positive pattern 0, negative pattern 0, positive pattern 1, negative pattern 1, etc. The first pattern corresponds to the lesser resoltution Graycode (two stripes only). Remember to turn off any ambient lights while scanning. Option 10 - Calibrate hardware The calibration process can be made after or before the scanning process. Just make sure the hardware remains untouched. the scritp automatically deletes any previous images on the camera. The script will ask you to indicate where the checkboard pattern to be projected is and where you want to save to calibration images: cam.jpg and proj.jpg. The first command is to take a picture of the checkboard pattern. When this pattern is in the correct position type y and enter. The script will take the picture and ask you to put the white support into position. Click yes and enter and the script will project the checkboard pattern onto it. Then, the files will be downloaded and saved. Note that in order to take the original checkboard picture the ambient lights must be turned on. You must remember to turn the lights off when the projected pattern image is being captured. -------------------------- 5. BUGS AND KNOWN PROBLEMS -------------------------- No bugs were discovered during tests. We found two operational problems with the kdcpi library. The first occurs during the image download ("dump") step. Sometimes the library cannot communicate with the camera and simply does not download the images captured, which means the scanning process must start all over again. The camera must be turned off and on, or at least be put out of "connect mode" and in again. Note that if you turn the camera off, the flash, zoom and exposition already set will be lost. Therefore we strongly suggest the calibration step to be made AFTER the scanning step. The second problem found occurs when the downloaded pictures are being renamed. Since they are downloaded to the kdcpi directory by default, we noticed that kdcpi library files can be renamed in the place of an image by mistake. This occurs because the images are renamed after their ID code (which indicates its modification date on Linux). If an image is not correctly saved in the directory during the download step, the last modified ID can be found on a kdcpi library file. This means the file can be wrongly renamed and moved from the directory. If this happen, you must delete the kdcpi directory and untar the kdcpi files again. ------------------------- 6. WHAT IS YET TO BE DONE ------------------------- Support to other camera types. Support to all kdcpi options. Options to help scanning whole objects using rotative bases. --------------------- 7. SUPPOT AND CONTACT --------------------- For more information, go to http://www.???????????? Bug report or suggestions: ?????@visgraf.impa.br