author | Tero Marttila <terom@fixme.fi> |
Mon, 25 Jan 2010 22:03:41 +0200 | |
changeset 100 | aee9d0b12fe9 |
parent 74 | 7c8226668e87 |
child 123 | 81d1cad8b588 |
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 |
||
13 |
NOTES: |
|
14 |
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 |
|
16 |
provided under python/. |
|
17 |
||
18 |
There is a separate project that provides a web-based tile viewer using Javascript (implemented in Python as a |
|
19 |
WSGI application). |
|
20 |
||
73
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
21 |
The .cache files are not portable across different architectures, nor are they compatible across different cache |
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
22 |
format versions. |
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
23 |
|
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
24 |
The library supports sparse cache files. A pixel-format byte pattern can be provided with --background using |
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
25 |
hexadecimal notation (--background 0xFFFFFF - for 24bpp RGB white), and consecutive regions of that color will |
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
26 |
be omitted in the cache file, which may provide significant gains in space efficiency. |
29
88691556661f
include include in dist, more README
Tero Marttila <terom@fixme.fi>
parents:
28
diff
changeset
|
27 |
|
88691556661f
include include in dist, more README
Tero Marttila <terom@fixme.fi>
parents:
28
diff
changeset
|
28 |
|
28 | 29 |
COMPILING: |
30 |
The library depends on libpng and pthreads. The code was developed and tested using: |
|
31 |
||
32 |
* libpng 1.2.15~beta5-3ubuntu0.1 |
|
33 |
* NPTL 2.7 (glibc 2.7-10ubuntu5) |
|
34 |
||
35 |
To compile, simply execute |
|
36 |
||
37 |
make |
|
38 |
||
74 | 39 |
The libpngtile.so will be placed under lib/, and the 'pngtile' binary under bin/. |
28 | 40 |
|
29
88691556661f
include include in dist, more README
Tero Marttila <terom@fixme.fi>
parents:
28
diff
changeset
|
41 |
|
28 | 42 |
USAGE: |
43 |
Store the .png data files in a directory. You must have write access to the directory when updating the caches, |
|
44 |
which are written as a .cache file alongside the .png file. |
|
45 |
||
46 |
Provide any number of *.png paths as arguments to the ./bin/util command. Each will be opened, and automatically |
|
47 |
updated if the cache doesn't exist yet, or is stale: |
|
48 |
||
74 | 49 |
pngtile -v data/*.png |
73
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
50 |
|
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
51 |
Use -v/--verbose for more detailed output. |
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
52 |
|
28 | 53 |
|
74 | 54 |
To render a tile from some image, provide appropriate -W/-H and -x/-y options to pngtile: |
28 | 55 |
|
74 | 56 |
pngtile data/*.png -W 1024 -H 1024 -x 8000 -y 4000 |
28 | 57 |
|
58 |
The output PNG tiles will be written to temporary files, the names of which are shown in the [INFO] output. |
|
59 |
||
60 |
||
61 |
To force-update an image's cache, use the -U/--force-update option: |
|
62 |
||
74 | 63 |
pngtile --force-update data/*.png |
28 | 64 |
|
73
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
65 |
Alternatively, to not update an image's cache, use the -N/--no-update option. |
28 | 66 |
|
67 |
||
68 |
TODO/BUGS: |
|
69 |
At this stage, the library is primarily designed to handle a specific set of PNG images, and hence does not support |
|
70 |
all aspects of the PNG format, nor any other image formats. |
|
71 |
||
72 |
The pt_images opened by main() are not cleaned up before process exit, due to the asynchronous nature of the tile |
|
73 |
render operation's accesses to the underlying pt_cache object. |
|
74 |