1

# libpngtile

     2

     3

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

     4

     5

## About

     6

    pngtile is a C 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

## Notes

    13

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

    14

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

    15

    provided under python/.

    16

    17

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

    18

    WSGI application).

    19

    20

    The .cache files are not portable across different architectures, nor are they compatible across different cache

    21

    format versions.

    22

    23

    The library supports sparse cache files. A pixel-format byte pattern can be provided with --background using

    24

    hexadecimal notation (--background 0xFFFFFF - for 24bpp RGB white), and consecutive regions of that color will

    25

    be omitted in the cache file, which may provide significant gains in space efficiency.

    26

    27

## Build

    28

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

    29

    30

        * libpng12-dev      png.h       1.2.15~beta5-3ubuntu0.1

    31

        * libc6-dev         pthread.h   NPTL 2.7 (glibc 2.7-10ubuntu5)

    32

    33

    To compile:

    34

    35

        $ make

    36

    37

    The libpngtile.so and pypngtile.so libraries will be placed under lib/, and the 'pngtile' binary under bin/.

    38

    39

## Usage

    40

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

    41

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

    42

    43

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

    44

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

    45

    46

        pngtile -v data/*.png

    47

    48

    Use -v/--verbose for more detailed output.

    49

    50

    51

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

    52

    53

        pngtile data/*.png -W 1024 -H 1024 -x 8000 -y 4000

    54

    55

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

    56

    57

    58

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

    59

    60

        pngtile --force-update data/*.png

    61

    62

    Alternatively, to not update an image's cache, use the -N/--no-update option.

    63

    64

## Issues

    65

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

    66

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

    67

    68

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

    69

    render operation's accesses to the underlying pt_cache object.

    70

    71

# pypngtile

    72

    73

Python extension for pngtile

    74

    75

## Dependencies

    76

    77

    * python-cython

    78

    * python-dev

    79

    80

## Development

    81

    82

    $ python setup.py build_ext

    83

    84

## Install

    85

    $ virtualenv /opt/pngtile

    86

    $ make -B install PREFIX=/opt/pngtile

    87

    $ /opt/pngtile/bin/pip install -r requirements.txt

    88

    $ /opt/pngtile/bin/python setup.py build_ext -I /opt/pngtile/include -L /opt/pngtile/lib -R /opt/pngtile/lib

    89

    $ /opt/pngtile/bin/python setup.py install

    90

    91