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 Additionally, the library contains a thread pool for doing asynchronous tile render operations in parallel. |
|
13 |
|
14 |
12 |
15 NOTES: |
13 NOTES: |
16 The command-line utility is mainly intended for maintining the image caches and testing, primary usage is expected |
14 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 |
15 to be performed using the library interface directly. A simple Cython wrapper for a Python extension module is |
18 provided under python/. |
16 provided under python/. |
19 |
17 |
20 There is a separate project that provides a web-based tile viewer using Javascript (implemented in Python as a |
18 There is a separate project that provides a web-based tile viewer using Javascript (implemented in Python as a |
21 WSGI application). |
19 WSGI application). |
22 |
20 |
23 The .cache files are not portable across different architectures. |
21 The .cache files are not portable across different architectures, nor are they compatible across different cache |
|
22 format versions. |
|
23 |
|
24 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 |
|
26 be omitted in the cache file, which may provide significant gains in space efficiency. |
24 |
27 |
25 |
28 |
26 COMPILING: |
29 COMPILING: |
27 The library depends on libpng and pthreads. The code was developed and tested using: |
30 The library depends on libpng and pthreads. The code was developed and tested using: |
28 |
31 |
29 * libpng 1.2.15~beta5-3ubuntu0.1 |
32 * libpng 1.2.15~beta5-3ubuntu0.1 |
30 * NPTL 2.7 (glibc 2.7-10ubuntu5) |
33 * NPTL 2.7 (glibc 2.7-10ubuntu5) |
31 |
|
32 The code was verified to compile and run on cc.hut.fi's Ubuntu computers, e.g. asterix.hut.fi. |
|
33 |
34 |
34 To compile, simply execute |
35 To compile, simply execute |
35 |
36 |
36 make |
37 make |
37 |
38 |
44 |
45 |
45 Provide any number of *.png paths as arguments to the ./bin/util command. Each will be opened, and automatically |
46 Provide any number of *.png paths as arguments to the ./bin/util command. Each will be opened, and automatically |
46 updated if the cache doesn't exist yet, or is stale: |
47 updated if the cache doesn't exist yet, or is stale: |
47 |
48 |
48 ./bin/util -v data/*.png |
49 ./bin/util -v data/*.png |
|
50 |
|
51 Use -v/--verbose for more detailed output. |
|
52 |
49 |
53 |
50 To render a tile from some image, provide appropriate -W/-H and -x/-y options to ./bin/util: |
54 To render a tile from some image, provide appropriate -W/-H and -x/-y options to ./bin/util: |
51 |
55 |
52 ./bin/util data/*.png -W 1024 -H 1024 -x 8000 -y 4000 |
56 ./bin/util data/*.png -W 1024 -H 1024 -x 8000 -y 4000 |
53 |
57 |
54 The output PNG tiles will be written to temporary files, the names of which are shown in the [INFO] output. |
58 The output PNG tiles will be written to temporary files, the names of which are shown in the [INFO] output. |
55 |
59 |
56 |
60 |
57 |
|
58 To force-update an image's cache, use the -U/--force-update option: |
61 To force-update an image's cache, use the -U/--force-update option: |
59 |
62 |
60 ./bin/util --force-update data/*.png |
63 ./bin/util --force-update data/*.png |
61 |
64 |
62 To change the number of threads used for tile-render operations, use -j/--threads: |
65 Alternatively, to not update an image's cache, use the -N/--no-update option. |
63 |
|
64 time ./bin/util -q data/* -W 4096 -H 4096 -x 8000 -y 4000 -j 1 |
|
65 > real 0m3.866s |
|
66 |
|
67 time ./bin/util -q data/* -W 4096 -H 4096 -x 8000 -y 4000 -j 4 |
|
68 > real 0m1.463s |
|
69 |
66 |
70 (measured on an Intel Core 2 Duo, compiled without optimizations) |
|
71 |
|
72 |
67 |
73 TODO/BUGS: |
68 TODO/BUGS: |
74 At this stage, the library is primarily designed to handle a specific set of PNG images, and hence does not support |
69 At this stage, the library is primarily designed to handle a specific set of PNG images, and hence does not support |
75 all aspects of the PNG format, nor any other image formats. |
70 all aspects of the PNG format, nor any other image formats. |
76 |
71 |
77 Cache updated operations are not executed using the thread pool. |
|
78 |
|
79 The pt_images opened by main() are not cleaned up before process exit, due to the asynchronous nature of the tile |
72 The pt_images opened by main() are not cleaned up before process exit, due to the asynchronous nature of the tile |
80 render operation's accesses to the underlying pt_cache object. |
73 render operation's accesses to the underlying pt_cache object. |
81 |
74 |