author | Tero Marttila <terom@qmsk.net> |
Mon, 03 Jul 2017 23:15:14 +0300 | |
changeset 177 | b2768f3982f3 |
parent 163 | 7c929ba47ba6 |
permissions | -rw-r--r-- |
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
1 |
# libpngtile |
28 | 2 |
|
3 |
Constant-time/memory tile-based handling of large PNG images. |
|
4 |
||
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
5 |
## About |
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
6 |
pngtile is a C library (and associated command-line utility) offering efficient random access to partial regions of |
28 | 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 |
||
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
12 |
## Notes |
28 | 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 |
||
73
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
20 |
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
|
21 |
format versions. |
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
22 |
|
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
23 |
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
|
24 |
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
|
25 |
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
|
26 |
|
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
27 |
## Build |
28 | 28 |
The library depends on libpng and pthreads. The code was developed and tested using: |
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
29 |
|
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
30 |
* libpng12-dev png.h 1.2.15~beta5-3ubuntu0.1 |
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
31 |
* libc6-dev pthread.h NPTL 2.7 (glibc 2.7-10ubuntu5) |
28 | 32 |
|
156
01a05c807e82
Makefile: do no link bin/pngtile directly with libpngtile, but rather use -lpngtile and -Rlib; add install target
Tero Marttila <terom@qmsk.net>
parents:
132
diff
changeset
|
33 |
To compile: |
28 | 34 |
|
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
35 |
$ make |
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
36 |
|
123
81d1cad8b588
docfix README for new Makefile
Tero Marttila <terom@fixme.fi>
parents:
74
diff
changeset
|
37 |
The libpngtile.so and pypngtile.so libraries will be placed under lib/, and the 'pngtile' binary under bin/. |
81d1cad8b588
docfix README for new Makefile
Tero Marttila <terom@fixme.fi>
parents:
74
diff
changeset
|
38 |
|
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
39 |
## Usage |
28 | 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 |
||
74 | 46 |
pngtile -v data/*.png |
73
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
47 |
|
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
48 |
Use -v/--verbose for more detailed output. |
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
49 |
|
28 | 50 |
|
74 | 51 |
To render a tile from some image, provide appropriate -W/-H and -x/-y options to pngtile: |
28 | 52 |
|
74 | 53 |
pngtile data/*.png -W 1024 -H 1024 -x 8000 -y 4000 |
28 | 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 |
||
74 | 60 |
pngtile --force-update data/*.png |
28 | 61 |
|
73
5dfb245b814d
docfix: README and --background
Tero Marttila <terom@fixme.fi>
parents:
29
diff
changeset
|
62 |
Alternatively, to not update an image's cache, use the -N/--no-update option. |
28 | 63 |
|
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
64 |
## Issues |
28 | 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 |
||
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
71 |
# pypngtile |
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
72 |
|
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
73 |
Python extension for pngtile |
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
74 |
|
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
75 |
## Dependencies |
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
76 |
|
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
77 |
* python-cython |
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
78 |
* python-dev |
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
79 |
|
157
0d8674e64221
setup.py: use rpath to find lib/libpngtile.so
Tero Marttila <terom@qmsk.net>
parents:
156
diff
changeset
|
80 |
## Development |
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
81 |
|
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
82 |
$ python setup.py build_ext |
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
83 |
|
157
0d8674e64221
setup.py: use rpath to find lib/libpngtile.so
Tero Marttila <terom@qmsk.net>
parents:
156
diff
changeset
|
84 |
## Install |
163 | 85 |
$ virtualenv /opt/pngtile |
86 |
$ make -B install PREFIX=/opt/pngtile |
|
87 |
$ /opt/pngtile/bin/pip install -r requirements.txt |
|
157
0d8674e64221
setup.py: use rpath to find lib/libpngtile.so
Tero Marttila <terom@qmsk.net>
parents:
156
diff
changeset
|
88 |
$ /opt/pngtile/bin/python setup.py build_ext -I /opt/pngtile/include -L /opt/pngtile/lib -R /opt/pngtile/lib |
0d8674e64221
setup.py: use rpath to find lib/libpngtile.so
Tero Marttila <terom@qmsk.net>
parents:
156
diff
changeset
|
89 |
$ /opt/pngtile/bin/python setup.py install |
132
0260aeca943c
cleanup readme, drop pypngtile bits from Makefile, fixup setup.py for pypngtile
Tero Marttila <terom@paivola.fi>
parents:
123
diff
changeset
|
90 |
|
157
0d8674e64221
setup.py: use rpath to find lib/libpngtile.so
Tero Marttila <terom@qmsk.net>
parents:
156
diff
changeset
|
91 |