1 pngtile

     2 

     3 Constant-time/memory tile-based handling of large PNG images.

     4 

     5 ABOUT:

     6     pngtile is a library (and associated command-line utility) offering efficient random access to partial regions of

     7     very large PNG images (gigapixel range).

     8 

     9     For this purpose, the library linearly decodes the PNG image to an uncompressed memory-mapped file, which can then

    10     be later used to encode a portion of this raw pixel data back into a PNG image.

    11 

    12     Additionally, the library contains a thread pool for doing asynchronous tile render operations in parallel.

    13 

    14 

    15 NOTES:

    16     The command-line utility is mainly intended for maintining the image caches and testing, primary usage is expected

    17     to be performed using the library interface directly. A simple Cython wrapper for a Python extension module is

    18     provided under python/.

    19 

    20     There is a separate project that provides a web-based tile viewer using Javascript (implemented in Python as a

    21     WSGI application).

    22 

    23 COMPILING:

    24     The library depends on libpng and pthreads. The code was developed and tested using:

    25 

    26         * libpng 1.2.15~beta5-3ubuntu0.1

    27         * NPTL 2.7 (glibc 2.7-10ubuntu5)

    28 

    29     To compile, simply execute

    30 

    31         make

    32 

    33     The libpngtile.so will be placed under lib/, and the 'util' binary under bin/.

    34 

    35 USAGE:

    36     Store the .png data files in a directory. You must have write access to the directory when updating the caches,

    37     which are written as a .cache file alongside the .png file.

    38 

    39     Provide any number of *.png paths as arguments to the ./bin/util command. Each will be opened, and automatically

    40     updated if the cache doesn't exist yet, or is stale:

    41 

    42         ./bin/util -v data/*.png

    43 

    44     To render a tile from some image, provide appropriate -W/-H and -x/-y options to ./bin/util:

    45         

    46         ./bin/util data/*.png -W 1024 -H 1024 -x 8000 -y 4000

    47 

    48     The output PNG tiles will be written to temporary files, the names of which are shown in the [INFO] output.

    49 

    50 

    51 

    52     To force-update an image's cache, use the -U/--force-update option:

    53 

    54         ./bin/util --force-update data/*.png

    55 

    56     To change the number of threads used for tile-render operations, use -j/--threads:

    57         

    58         time ./bin/util -q data/* -W 4096 -H 4096 -x 8000 -y 4000 -j 1

    59         > real    0m3.866s

    60         

    61         time ./bin/util -q data/* -W 4096 -H 4096 -x 8000 -y 4000 -j 4

    62         > real    0m1.463s

    63 

    64         (measured on an Intel Core 2 Duo, compiled without optimizations)

    65     

    66 

    67 TODO/BUGS:

    68     At this stage, the library is primarily designed to handle a specific set of PNG images, and hence does not support

    69     all aspects of the PNG format, nor any other image formats.

    70 

    71     Cache updated operations are not executed using the thread pool.

    72 

    73     The pt_images opened by main() are not cleaned up before process exit, due to the asynchronous nature of the tile

    74     render operation's accesses to the underlying pt_cache object.

    75