karttapullautin2tiles

Convert the output of karttapullautin into web mercator tiles.

karttapullautin is a command-line tool that converts LIDAR data into orienteering maps. Karttapullautin tool generates one png image per LIDAR tile. karttapullautin2tiles (k2t) addresses the task of merging these tiles and generating a x/y/z web mercator tile directory that is compatible with many map viewers.

Usage

After a successful karttapullautin run, you typically end up with a out directory containing *.png and corresponding *.pgw files, e.g.

576_5265.laz_depr.pgw
576_5265.laz_depr.png
576_5265.laz.pgw
576_5265.laz.png
576_5266.laz_depr.pgw
576_5266.laz_depr.png
576_5266.laz.pgw
576_5266.laz.png

Given such a directory, you can generate a web tile directory using

k2t list-tiles --proj EPSG:25832 --zoom 12 karttapullautin/out | k2t make-tiles --proj EPSG:25832 karttapullautin/out karttapullautin/tiles

The tool is separated into list-tiles and make-tiles, because it quite naturally allows for parallelization across multiple processes, or even machines. For instance, you can use GNU parallel to distribute the task across multiple processes:

k2t list-tiles --proj EPSG:25832 --zoom 12 karttapullautin/out | \
  parallel --pipe -j 6 --block 1 k2t make-tiles --proj EPSG:25832 karttapullautin/out karttapullautin/tiles

Command reference

The commands allow a certain degree of customization, e.g. specifying the projection used by the LIDAR files and the zoom levels you want to generate.

k2t list-tiles

Usage: k2t list-tiles [ARGS] [OPTIONS]

List the tiles that are covered by the karttapullautin output directory at the given zoom
level.

The main purpose of this command is to generate a list of tiles that can be passed (possibly
in chunks) to the make-tiles command.

╭─ Parameters ──────────────────────────────────────────────────────────────────────────────╮
│ *  DIR --dir  Input directory (karttapullautin output dir) [required]                     │
│ *  --proj     EPSG string of the projection used [required]                               │
│    --pattern  Search pattern for the pgw files [default: *depr*.pgw]                      │
│    --zoom     Zoom level to generate tiles for. When running make-tiles, all              │
│               karttapullautin png files for this tile need to fit in memory. [default:    │
│               12]                                                                         │
╰───────────────────────────────────────────────────────────────────────────────────────────╯

k2t make-tiles

Usage: k2t make-tiles [ARGS] [OPTIONS]

Create a web mercator tiles from karttapullautin output, given a list of tile coordinates.

The list of tiles is typically generated by the list-tiles command. You can split it in
chunks and pass it to multiple instances of make-tiles, e.g. to parallelize (see examples).
The format of the tile list is one json record per row, of the format {"x": 2162, "y": 1432,
"z": 12}. The list of tiles defines the lowest zoom level for which tiles will be generated.
All "child" tiles up to max_zoom will also be generated.

Note that all images required for a tile at min_zoom need to fit in memory. If you have
memory issues, consider setting a higher zoom level.

╭─ Parameters ────────────────────────────────────────────────────────────────────────────╮
│ *  IN-DIR --in-dir        Input directory containing karttapullautin output files       │
│                           [required]                                                    │
│ *  OUT-DIR --out-dir      Output directory for tiles (z/x/y folder structure)           │
│                           [required]                                                    │
│    TILE-LIST --tile-list  File with tiles to process. If not provided as file, will be  │
│                           read from stdin. This file is typically generated by k2t      │
│                           list-tiles. The file must contain one json string per row of  │
│                           the format {"x": 2162, "y": 1432, "z": 12}                    │
│ *  --proj                 EPSG string of the projection used by input images [required] │
│    --pattern              Search pattern for pgw files in the input directory [default: │
│                           *depr*.pgw]                                                   │
│    --max-zoom             Maximum zoom level to generate tiles for [default: 17]        │
│    --format               Output image format. Both are lossless; webp produces roughly │
│                           25% smaller files than png and decodes faster, but png is     │
│                           available for consumers that cannot read webp. [choices:      │
│                           webp, png] [default: webp]                                    │
│    --webp-method          libwebp compression effort between 0 and 6, defaults to 2.    │
│                           Higher is smaller but slower to write, and has no effect on   │
│                           how fast the tiles decode. Only valid with --format webp.     │
│    --include-viewer       If enabled, include a HTML file to preview the generated      │
│      --no-include-viewer  tiles [default: True]                                         │
╰─────────────────────────────────────────────────────────────────────────────────────────╯

Output format

Tiles are written as lossless WebP ({z}/{x}/{y}.webp) by default, which is about 25% smaller than PNG and decodes slightly faster, at no cost in quality. Pass --format png if you need to serve the tiles to a consumer that cannot read WebP.

--webp-method trades encoding time for file size and has no effect on decoding speed. The default of 2 sits at the knee of that curve; raising it to 3 costs roughly 2.3x the encoding time for another 3% off, and 6 is about 40x slower for 15%. Since make-tiles parallelizes well (see above), a higher setting is affordable if you are generating tiles once and serving them many times.

Installation

You need to have Python 3.10 or newer installed on your system. If you don't have Python installed, we recommend installing uv.

There are several alternative options to install karttapullautin2tiles:

1. Install the latest release of karttapullautin2tiles from PyPI:

uv tool install karttapullautin2tiles

# or using pip
pip install karttapullautin2tiles

2. Run k2t without installation using uv:

uvx --from karttapullautin2tiles k2t

3. Install the latest development version:

pip install git+https://github.com/grst/karttapullautin2tiles.git@main

Release notes

See the changelog.

Contact

Please use the issue tracker.