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