1 pngtile |
1 # libpngtile |
2 |
2 |
3 Constant-time/memory tile-based handling of large PNG images. |
3 Constant-time/memory tile-based handling of large PNG images. |
4 |
4 |
5 ABOUT: |
5 ## About |
6 pngtile is a library (and associated command-line utility) offering efficient random access to partial regions of |
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). |
7 very large PNG images (gigapixel range). |
8 |
8 |
9 For this purpose, the library linearly decodes the PNG image to an uncompressed memory-mapped file, which can then |
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. |
10 be later used to encode a portion of this raw pixel data back into a PNG image. |
11 |
11 |
12 |
12 ## Notes |
13 NOTES: |
|
14 The command-line utility is mainly intended for maintining the image caches and testing, primary usage is expected |
13 The command-line utility is mainly intended for maintining the image caches and testing, primary usage is expected |
15 to be performed using the library interface directly. A simple Cython wrapper for a Python extension module is |
14 to be performed using the library interface directly. A simple Cython wrapper for a Python extension module is |
16 provided under python/. |
15 provided under python/. |
17 |
16 |
18 There is a separate project that provides a web-based tile viewer using Javascript (implemented in Python as a |
17 There is a separate project that provides a web-based tile viewer using Javascript (implemented in Python as a |
23 |
22 |
24 The library supports sparse cache files. A pixel-format byte pattern can be provided with --background using |
23 The library supports sparse cache files. A pixel-format byte pattern can be provided with --background using |
25 hexadecimal notation (--background 0xFFFFFF - for 24bpp RGB white), and consecutive regions of that color will |
24 hexadecimal notation (--background 0xFFFFFF - for 24bpp RGB white), and consecutive regions of that color will |
26 be omitted in the cache file, which may provide significant gains in space efficiency. |
25 be omitted in the cache file, which may provide significant gains in space efficiency. |
27 |
26 |
28 |
27 ## Build |
29 COMPILING: |
|
30 The library depends on libpng and pthreads. The code was developed and tested using: |
28 The library depends on libpng and pthreads. The code was developed and tested using: |
31 |
29 |
32 * libpng 1.2.15~beta5-3ubuntu0.1 |
30 * libpng12-dev png.h 1.2.15~beta5-3ubuntu0.1 |
33 * NPTL 2.7 (glibc 2.7-10ubuntu5) |
31 * libc6-dev pthread.h NPTL 2.7 (glibc 2.7-10ubuntu5) |
34 |
32 |
35 To compile dist versions, simply execute |
33 To compile dist versions, simply execute |
36 |
34 |
37 make |
35 $ make |
|
36 |
|
37 To compile source versions, execute: |
|
38 |
|
39 $ make dirs |
|
40 $ make |
38 |
41 |
39 The libpngtile.so and pypngtile.so libraries will be placed under lib/, and the 'pngtile' binary under bin/. |
42 The libpngtile.so and pypngtile.so libraries will be placed under lib/, and the 'pngtile' binary under bin/. |
40 |
43 |
41 XXX: If compiling the pypngtile.so library with make fails, then `setup.py build_ext -i` should build it. |
44 XXX: If compiling the pypngtile.so library with make fails, then `setup.py build_ext -i` should build it. |
42 |
45 |
43 |
46 ## Usage |
44 USAGE: |
|
45 Store the .png data files in a directory. You must have write access to the directory when updating the caches, |
47 Store the .png data files in a directory. You must have write access to the directory when updating the caches, |
46 which are written as a .cache file alongside the .png file. |
48 which are written as a .cache file alongside the .png file. |
47 |
49 |
48 Provide any number of *.png paths as arguments to the ./bin/util command. Each will be opened, and automatically |
50 Provide any number of *.png paths as arguments to the ./bin/util command. Each will be opened, and automatically |
49 updated if the cache doesn't exist yet, or is stale: |
51 updated if the cache doesn't exist yet, or is stale: |
64 |
66 |
65 pngtile --force-update data/*.png |
67 pngtile --force-update data/*.png |
66 |
68 |
67 Alternatively, to not update an image's cache, use the -N/--no-update option. |
69 Alternatively, to not update an image's cache, use the -N/--no-update option. |
68 |
70 |
69 |
71 ## Issues |
70 TODO/BUGS: |
|
71 At this stage, the library is primarily designed to handle a specific set of PNG images, and hence does not support |
72 At this stage, the library is primarily designed to handle a specific set of PNG images, and hence does not support |
72 all aspects of the PNG format, nor any other image formats. |
73 all aspects of the PNG format, nor any other image formats. |
73 |
74 |
74 The pt_images opened by main() are not cleaned up before process exit, due to the asynchronous nature of the tile |
75 The pt_images opened by main() are not cleaned up before process exit, due to the asynchronous nature of the tile |
75 render operation's accesses to the underlying pt_cache object. |
76 render operation's accesses to the underlying pt_cache object. |
76 |
77 |
|
78 # pypngtile |
|
79 |
|
80 Python extension for pngtile |
|
81 |
|
82 ## Dependencies |
|
83 |
|
84 * python-cython |
|
85 * python-dev |
|
86 |
|
87 ## Build |
|
88 |
|
89 $ python setup.py build_ext |
|
90 |
|
91 |