terom@28: pngtile
terom@28: 
terom@28: Constant-time/memory tile-based handling of large PNG images.
terom@28: 
terom@28: ABOUT:
terom@28:     pngtile is a library (and associated command-line utility) offering efficient random access to partial regions of
terom@28:     very large PNG images (gigapixel range).
terom@28: 
terom@28:     For this purpose, the library linearly decodes the PNG image to an uncompressed memory-mapped file, which can then
terom@28:     be later used to encode a portion of this raw pixel data back into a PNG image.
terom@28: 
terom@28:     Additionally, the library contains a thread pool for doing asynchronous tile render operations in parallel.
terom@28: 
terom@28: 
terom@28: NOTES:
terom@28:     The command-line utility is mainly intended for maintining the image caches and testing, primary usage is expected
terom@28:     to be performed using the library interface directly. A simple Cython wrapper for a Python extension module is
terom@28:     provided under python/.
terom@28: 
terom@28:     There is a separate project that provides a web-based tile viewer using Javascript (implemented in Python as a
terom@28:     WSGI application).
terom@28: 
terom@29:     The .cache files are not portable across different architectures.
terom@29: 
terom@29: 
terom@28: COMPILING:
terom@28:     The library depends on libpng and pthreads. The code was developed and tested using:
terom@28: 
terom@28:         * libpng 1.2.15~beta5-3ubuntu0.1
terom@28:         * NPTL 2.7 (glibc 2.7-10ubuntu5)
terom@28: 
terom@29:     The code was verified to compile and run on cc.hut.fi's Ubuntu computers, e.g. asterix.hut.fi.
terom@29: 
terom@28:     To compile, simply execute
terom@28: 
terom@28:         make
terom@28: 
terom@28:     The libpngtile.so will be placed under lib/, and the 'util' binary under bin/.
terom@28: 
terom@29: 
terom@28: USAGE:
terom@28:     Store the .png data files in a directory. You must have write access to the directory when updating the caches,
terom@28:     which are written as a .cache file alongside the .png file.
terom@28: 
terom@28:     Provide any number of *.png paths as arguments to the ./bin/util command. Each will be opened, and automatically
terom@28:     updated if the cache doesn't exist yet, or is stale:
terom@28: 
terom@28:         ./bin/util -v data/*.png
terom@28: 
terom@28:     To render a tile from some image, provide appropriate -W/-H and -x/-y options to ./bin/util:
terom@28:         
terom@28:         ./bin/util data/*.png -W 1024 -H 1024 -x 8000 -y 4000
terom@28: 
terom@28:     The output PNG tiles will be written to temporary files, the names of which are shown in the [INFO] output.
terom@28: 
terom@28: 
terom@28: 
terom@28:     To force-update an image's cache, use the -U/--force-update option:
terom@28: 
terom@28:         ./bin/util --force-update data/*.png
terom@28: 
terom@28:     To change the number of threads used for tile-render operations, use -j/--threads:
terom@28:         
terom@28:         time ./bin/util -q data/* -W 4096 -H 4096 -x 8000 -y 4000 -j 1
terom@28:         > real    0m3.866s
terom@28:         
terom@28:         time ./bin/util -q data/* -W 4096 -H 4096 -x 8000 -y 4000 -j 4
terom@28:         > real    0m1.463s
terom@28: 
terom@28:         (measured on an Intel Core 2 Duo, compiled without optimizations)
terom@28:     
terom@28: 
terom@28: TODO/BUGS:
terom@28:     At this stage, the library is primarily designed to handle a specific set of PNG images, and hence does not support
terom@28:     all aspects of the PNG format, nor any other image formats.
terom@28: 
terom@28:     Cache updated operations are not executed using the thread pool.
terom@28: 
terom@28:     The pt_images opened by main() are not cleaned up before process exit, due to the asynchronous nature of the tile
terom@28:     render operation's accesses to the underlying pt_cache object.
terom@28: