# karttapullautin2tiles

[![Tests][badge-tests]][tests]

[badge-tests]: https://img.shields.io/github/actions/workflow/status/grst/karttapullautin2tiles/test.yaml?branch=main
[badge-docs]: https://img.shields.io/readthedocs/karttapullautin2tiles

Convert the output of [karttapullautin](https://github.com/karttapullautin/karttapullautin) into web mercator tiles.

[karttapullautin](https://github.com/karttapullautin/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

```bash
k2t list-tiles --zoom 12 karttapullautin/out | k2t make-tiles 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](https://www.gnu.org/software/parallel/) to distribute the task
across multiple processes:

```bash
k2t list-tiles --zoom 12 karttapullautin/out | \
  parallel --pipe -j 6 --block 1 k2t make-tiles karttapullautin/out karttapullautin/tiles
```

## Command reference

The commands allow a certain degree of customization, e.g. specifying the projection used by the LIDAR files (default assumes `EPSG:25832`)
and the zoom levels you want to generate.

### `k2t list-tiles`

```console
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 [default: EPSG:25832]                    │
│    --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`

```console
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 [default:    │
│                           EPSG:25832]                                                     │
│    --pattern              Search pattern for pgw files in the input directory [default:   │
│                           *depr*.pgw]                                                     │
│    --max-zoom             Maximum zoom level to generate tiles for [default: 17]          │
│    --include-viewer       If enabled, include a HTML file to preview the generated tiles  │
│      --no-include-viewer  [default: True]                                                 │
╰───────────────────────────────────────────────────────────────────────────────────────────╯
```


## 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][]:

```bash
uv tool install karttapullautin2tiles

# or using pip
pip install karttapullautin2tiles
```

2) Run `k2t` without installation using [uv][]:

```bash
uvx --from karttapullautin2tiles k2t
```

3. Install the latest development version:

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

## Release notes

See the [changelog][].

## Contact

Please use the [issue tracker][].


[uv]: https://github.com/astral-sh/uv
[issue tracker]: https://github.com/grst/karttapullautin2tiles/issues
[tests]: https://github.com/grst/karttapullautin2tiles/actions/workflows/test.yaml
[documentation]: https://karttapullautin2tiles.readthedocs.io
[changelog]: https://karttapullautin2tiles.readthedocs.io/en/latest/changelog.html
[api documentation]: https://karttapullautin2tiles.readthedocs.io/en/latest/api.html
[pypi]: https://pypi.org/project/karttapullautin2tiles
