author | Tero Marttila <terom@fixme.fi> |
Mon, 25 Jan 2010 02:48:41 +0200 | |
changeset 71 | 01b021e406e9 |
parent 29 | 88691556661f |
child 73 | 5dfb245b814d |
permissions | -rw-r--r-- |
28 | 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 |
||
29
88691556661f
include include in dist, more README
Tero Marttila <terom@fixme.fi>
parents:
28
diff
changeset
|
23 |
The .cache files are not portable across different architectures. |
88691556661f
include include in dist, more README
Tero Marttila <terom@fixme.fi>
parents:
28
diff
changeset
|
24 |
|
88691556661f
include include in dist, more README
Tero Marttila <terom@fixme.fi>
parents:
28
diff
changeset
|
25 |
|
28 | 26 |
COMPILING: |
27 |
The library depends on libpng and pthreads. The code was developed and tested using: |
|
28 |
||
29 |
* libpng 1.2.15~beta5-3ubuntu0.1 |
|
30 |
* NPTL 2.7 (glibc 2.7-10ubuntu5) |
|
31 |
||
29
88691556661f
include include in dist, more README
Tero Marttila <terom@fixme.fi>
parents:
28
diff
changeset
|
32 |
The code was verified to compile and run on cc.hut.fi's Ubuntu computers, e.g. asterix.hut.fi. |
88691556661f
include include in dist, more README
Tero Marttila <terom@fixme.fi>
parents:
28
diff
changeset
|
33 |
|
28 | 34 |
To compile, simply execute |
35 |
||
36 |
make |
|
37 |
||
38 |
The libpngtile.so will be placed under lib/, and the 'util' binary under bin/. |
|
39 |
||
29
88691556661f
include include in dist, more README
Tero Marttila <terom@fixme.fi>
parents:
28
diff
changeset
|
40 |
|
28 | 41 |
USAGE: |
42 |
Store the .png data files in a directory. You must have write access to the directory when updating the caches, |
|
43 |
which are written as a .cache file alongside the .png file. |
|
44 |
||
45 |
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 |
||
48 |
./bin/util -v data/*.png |
|
49 |
||
50 |
To render a tile from some image, provide appropriate -W/-H and -x/-y options to ./bin/util: |
|
51 |
||
52 |
./bin/util data/*.png -W 1024 -H 1024 -x 8000 -y 4000 |
|
53 |
||
54 |
The output PNG tiles will be written to temporary files, the names of which are shown in the [INFO] output. |
|
55 |
||
56 |
||
57 |
||
58 |
To force-update an image's cache, use the -U/--force-update option: |
|
59 |
||
60 |
./bin/util --force-update data/*.png |
|
61 |
||
62 |
To change the number of threads used for tile-render operations, use -j/--threads: |
|
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 |
||
70 |
(measured on an Intel Core 2 Duo, compiled without optimizations) |
|
71 |
||
72 |
||
73 |
TODO/BUGS: |
|
74 |
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. |
|
76 |
||
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 |
|
80 |
render operation's accesses to the underlying pt_cache object. |
|
81 |