PTStitcherNG 0.2a, Fast Stitcher and Blender ============================================ 1. Introduction =============== This is the second testrelease of PTStitcherNG, the next generation of my panorama stitcher and blender PTStitcher. PTStitcherNG is written for multicore processors capable of executing SIMD-instructions. The current release is implemented for the IBM/Sony/Toshiba Cell-Processor and runs on the Sony Playstation 3 with Yellow Dog Linux 6. It should run without changes on other cellprocessor based systems like the IBM CellBlades. PTStitcherNG is compatible with PanoTools and runs off the usual stitcher scripts created by many authoring tools. Output should be compatible with previous versions of "PTStitcher" combined with multiresolution blending a la "Enblend". PTStitcherNG can be used to quickly generate huge, gigapixel sized panoramas, or to generate large amounts of panoramas in realtime, eg create panoramic movies with PS3-clusters. 1.b. Performance on the Sony Playstation 3 ========================================== This new release for cellprocessors is by far the fastest available stitcher/blender according to Bernhard Vogls Gigapixel speedtest . It beats an autopano-equipped 8-core-32GB-ram AMD system by more than a factor of 2, not to speak of the much slower competing stitchers (ptgui, hugin, ...). And, unlike many other stitchers, both warping and blending is done in full HDR-resolution (128bit-float4-RGBA-pixels). Some test results obtained on the Sony Playstation 3 with Yellow Dog Linux 6: 3 x 5 MPixel -------> 10 MPixel equirect 6.4 sec 3 x 11 MPixel -------> 18 MPixel equirect 17.2 sec 337 x 6 MPixel ------->1433 MPixel cylinder 8min 50sec 337 x 6 MPixel -------> 14 MPixel cylinder 24 sec On the PS3, PTStitcherNG excels in the case of many small to medium sized input images. Due to the Playstation's small memory size it is less powerfull, but still quite fast in the case of large input images (see 3x11 case above). PTStitcherNG also runs on other cellprocessor based systems like the IBM-CellBlades with more memory, but this is untested. The Playstation can be remotely operated by a main workstation running Windows/MacOS/Linux (this is how I have set things up), or connected to screen, usb-mouse and keyboard, and used as standalone computer (not recommended, but required during installation and configuration). The Playstation must be running Linux, preferrably Yellow Dog Linux 6. Free installation dvd-images can be downloaded from the terrasoft website , or, more conveniently, preconfigured Playstations may be purchased from them. Testers should be familiar with PanoTools/PTStitcher and have some basic Linux-experience. Installation instructions for PTStitcherNG and the program binaries are available from this address: This release may only be used for tests and evaluations. It is limited to JPEG-formatted input and it expires in 3 months. Please report bugs and suggestions to der(at)hs.furtwangen.de 2. Installing and Configuring Linux: ==================================== Linux on the Playstation: Download Yellow Dog Linux 6 or get an installation DVD from Terrasoft and install it on the Playstation. Use the default 32bit-user-space kernel for installation, and all other default options. You may wish to use a larger than suggested hard disk partition size and swap-space, at the cost of less gaming resources. Or buy and install a larger disk, standard 2.5' SATA-models should fit. I am using the standard 40GByte model with 24 GByte linux partition and 512MByte swap-space. Configuration Steps: 1. Optional, highly recommended: Connect the Playstation to your PC via Ethernet cable. Install X and an ssh-client (eg Putty) on your PC. You can then login using a command window, and run GUI-applications like the gimp and texteditors like gedit on your Playstation using your PC's resources. 2. Optional, highly recommended: Configure a NFS-shared volume. I am using the directory /share on the Playstation to exchange data between PC and PS3. 3. Required: Configure Linux on the Playstation to run in runlevel 3 (without graphical user interface). The default runlevel 5 consumes too much ram. To accomplish this change, open the file /etc/inittab as root: >> gedit /etc/inittab change the line id:5:initdefault: to id:3:initdefault: Next time the system will start into runlevel 3. 4. Required: Configure Linux to allow more than the default 1024 open files. This is required for large panorama projects. Open the file /etc/security/limits.conf as root: >> gedit /etc/security/limits.conf and insert the lines (using your login name) your_login_name hard nofile 4096 your_login_name soft nofile 4096 3. Installing and Testing PTStitcherNG: ======================================= Move the file PTStitcherNG0.2a.tar.gz to your home directory on the PS3. Issue the command >> tar xzf PTStitcherNG0.2a.tar.gz To test the application, run the small sample project included in the distribution: >> cd PTStitcherNG0.2a >> ./PTStitcherNG -u 2 -f test/Project.txt -o pano.tif test/*.JPG The panorama "pano.tif" will be created while PTStitcherNG reports a few messages. Conversion time should be around 1 sec. To view the panorama: >> gimp pano.tif To repeat Bernhard Vogls gigapixel-benchmark, download and unzip the project: >> mkdir speedtest >> unzip -d speedtest speedtest.zip The ptgui-script is not completely compliant with PTStitcher's syntax, use the script "speedtest.gigapixel" from my distribution instead. It uses bilinear interpolation and layered tiff output. >> mv test/speedtest.gigapixel speedtest/ >> ./PTStitcherNG -q 1 -u 2 -s -f speedtest/speedtest.gigapixel -o pano.tif Conversion time should be around 530s. Do not try to open the file "pano.tif" on the Playstation! To use the same settings as the original script, change the interpolator to cubic (+2min )by editing the line m g1.000000 i5 f0 to m g1.000000 i0 f0 and use flat instead of layered tif (+ 10min) by editing the line p w81628 h17557 f1 v123.000000 u20 n"TIFF_m" to p w81628 h17557 f1 v123.000000 u20 n"TIFF" To create an image viewable on the Playstation, create a smaller image by changing this line to p w8163 h1756 f1 v123.000000 u20 n"TIFF" and rerun >> ./PTStitcherNG -q 1 -s -f speedtest/speedtest.gigapixel -o pano.tif >> gimp pano.tif 5. Usage: ========= PTStitcherNG supports a subset of PTStitcher options, and a few new ones: 1.Invocation: PTStitcherNG [ options ] [ inputfiles ] where options are -f scriptfile specify scriptfile. This is the "usual" PTStitcher/ptgui script. See notes below for syntax. Default: "script.txt" -o outputfile specify name of outputfile. Default: "pano.tif" -u use_ram_disk specify 0 (don't use ramdisk), 1 (use ram disk for one tempimage), 2 (use ram disk for all temp-images, will fail for huge images). Default: 1. -s Sort images for fastest stitching/blending. Only makes sense for large (>30 images) projects. -q dest-rect 0(default) or 1. Specify mode for calculating the destination rectangle for each input image. Only affects the initialization step before warping and stitching occurs. Either use all input pixels (slower, mode 0), or just the edge pixels (faster, mode 1). Usually, mode 1 is sufficient for cylinders, while equirectangular usually requires mode 0. If in doubt, test both cases, or leave mode=0. inputfiles may be specified on the commandline (in that case they should be supplied in the same order as they appear in the scriptfile), or their names may be listed in the scriptfile. 2.Script Syntax: The PanoTools-syntax for stitcher scripts (see PanoTools-wiki) is used by PTStitcherNG; see the example project and the script for the gigapixel-speedtest. ptgui-scripts need some editing before they can be used with PtStitcherNG: - remove or comment the o-line preceded by the label "...'dummy image' containing some global parameters". All global parameters specified in this line must be transfered to the respective o-lines. Changes and additions to PanoTools: - image format "TIFF_m" and "TIFF_mask" create a layered tiff-file with rectangular layers but without alpha masks. To create a flat image file simply collapse these layers without any blending. - output image formats are the two mentioned above, plus "TIFF", "PPM", and "JPEG" for flat images. No additional options may be specified like JPEG quality. This will be added in future releases. To create a "BigTIFF" file required for huge images, use the filename extension "tf8" or "btf" for the panorama file. - none of the alpha-mask options of PTStitcher is supported. All blending is performed using the new multiresolution blender. Seam placement is usually the center of the overlap region. To change seam positions, add an alpha mask to the respective source image, and make unwanted areas transparent. - equisolid fisheye projection is now supported (f5: circular image, f10: rectangular image) in addition to the previous fisheye equidistant (f3, f4). 6. Limitations: =============== - This test release has several built-in limitations, which will be removed in the future: Input is limited to baseline-JPEG-compressed RGB-images without restart markers. If your JPEGs do not work, they can be converted using the free djpeg/cjpeg utilities which should be available on your YDL-equipped PS3: decompress the jpeg images to ppm format using djpeg, then recompress using cjpeg. The final PTStitcherNG version will use a raw-format input module. The jpeg-module will be used for streaming MJPEG-input. This 0.2alpha version of PTStitcherNG will expire in 2 months. - PTStitcherNG does not create scripts. Control point selection and creation of a suitable stitcher script must be handled by other tools (eg PTOptimizer/PTEditor,...). - The timing results have shown so far, that the largest speedup is obtained for cylindrical or rectilinear images containing many source-images. Spherical panoramas are not accelerated by the same amount and may even fail completely for large panorama sizes. This is due to the huge zenith/nadir regions in equirectangular projection mode. I am working on a solution to create zenith/nadir regions separately, and insert those later. - The fastest conversion speed is obtained using layered tiff as output-format. All other formats require an additional, sometimes lengthy, format conversion step at the end. In this case, required diskspace increases to the final panorama-file's size plus one row of input images. 7. Licenses: =========== This release of PTStitcherNG is licensed for tests and evaluation purposes only, and may not be redistributed, changed, or used for any other purpose. This license and the program PTStitcherNG expire in July 2008. PTStitcherNG uses the following resources which have their own license: (1) libTIFF4.0.0alpha: This version supports large files which the version included in yellow-dog-linux 6 does not support. Copyright (c) 1988-1997 Sam Leffler Copyright (c) 1991-1997 Silicon Graphics, Inc. Permission to use, copy, modify, distribute, and sell this software and its documentation for any purpose is hereby granted without fee, provided that (i) the above copyright notices and this permission notice appear in all copies of the software and related documentation, and (ii) the names of Sam Leffler and Silicon Graphics may not be used in any advertising or publicity relating to the software without the specific, prior written permission of Sam Leffler and Silicon Graphics. THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND, OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. (2) spe-jpeg (spu-jpeg decoder) // // Copyright (c) 2007, Vitaly Vidmirov // // Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated // documentation files (the "Software"), to deal in the Software without restriction, including without // limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of // the Software, and to permit persons to whom the Software is furnished to do so, subject to the following // conditions: // // The above copyright notice and this permission notice shall be included in all copies or substantial // portions of the Software. // // THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT // LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO // EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN // AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE // OR OTHER DEALINGS IN THE SOFTWARE. (3) cp_fatan-cbe-spu (atan2-function for spu) // ## Version 1.0 // ## // ## Copyright (c) 2006 Mike Acton // ## // ## Permission is hereby granted, free of charge, to any person obtaining // ## a copy of this software and associated documentation files // ## (the "Software"), to deal in the Software without restriction, including // ## without limitation the rights to use, copy, modify, merge, publish, // ## distribute, sublicense, and/or sell copies of the Software, and to permit // ## persons to whom the Software is furnished to do so, subject to the // ## following conditions: // ## // ## The above copyright notice and this permission notice shall be included // ## in all copies or substantial portions of the Software. // ## // ## THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS // ## OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, // ## FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE // ## AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER // ## LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, // ## OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN // ## THE SOFTWARE. (4) libsimdmath Copyright (C) 2006, 2007 Sony Computer Entertainment Inc. License: SIMD math library functions for both the PowerPC (PPU) and the SPU. Copyright (C) 2006, 2007 Sony Computer Entertainment Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the Sony Computer Entertainment Inc nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. (5) libjpeg, glibc (the standard c-library, GLPL), libspe and other standard and system libraries are dynamically linked to PTStitcherNG. (C)Copyright 2001,2008 Helmut Dersch