# HG changeset patch
# User Tero Marttila <terom@fixme.fi>
# Date 1262273880 -7200
# Node ID 094893cdbab78f14b4570df4c5c18cbbbcb6d8d4
# Parent  e5c5a89d8308940cdad1981422f94f33d201c86b
README

diff -r e5c5a89d8308 -r 094893cdbab7 README
--- /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.
+