hittekaart_py package
=====================

.. module:: hittekaart_py

    The ``hittekaart_py`` module provides a Python interface for hittekaart__
    heatmap generation. Unlike previous modules, this is a binding using
    PyO3__, and not a subprocess wrapper.

.. __: https://gitlab.com/dunj3/hittekaart
.. __: https://crates.io/crates/pyo3

Example
-------

.. code-block:: python

    from hittekaart_py import (
        Track, HeatmapRenderer, Settings, Storage, generate
    )

    settings = Settings(threads=3)
    tracks = [
        Track.from_file(b"Documents/track.gpx", None),
        Track.from_coordinates([(45.0, 47.0)]),
    ]
    storage = Storage.Sqlite(b"/tmp/tiles.sqlite")
    generate(settings, tracks, HeatmapRenderer(), storage)

Input and output
----------------

.. class:: Track

    An in-memory representation of a track.

    .. staticmethod:: from_file(path, compression)

        Loads a track from the given file.

        :param path: Path to the file.
        :type path: bytes
        :param compression: Decompression algorithm to use when reading the
            file. Can be :obj:`None`, ``"gzip"`` or ``"brotli"``.
        :type compression: str | None
        :return: The created track.
        :rtype: Track

    .. staticmethod:: from_coordinates(coordinates)

        Directly represents the given coordinates as a track.

        :param coordinates: The coordinates as a list of longitude-latitude
            pairs.
        :type coordinates: list[tuple[float, float]]
        :return: The created track.
        :rtype: Track


.. class:: Storage

    Represents the output storage.

    .. staticmethod:: Folder(path)

        Output the tiles to the given folder. This will create a subdirectory
        for every zoom level, then a directory for the x coordinate, then a
        file ``y.png``.

        Note that this will create many small files, which can waste space.

        :param path: Path to the folder.
        :type path: bytes
        :return: The created storage.
        :rtype: Storage

    .. staticmethod:: Sqlite(path)

        Output the tiles to the given SQLite database.

        :param path: Path to the database.
        :type path: bytes
        :return: The created storage.
        :rtype: Storage

Renderers
---------

.. class:: HeatmapRenderer()

    The renderer that generates a heatmap.

.. class:: MarktileRenderer()

    The renderer that will only mark visited tiles.

.. class:: TilehuntRenderer(zoom)

    The renderer that will mark visisted tiles at a fixed zoom level.

    :param zoom: The zoom level.
    :type zoom: int

Tile generation
---------------

.. class:: Settings(min_zoom=1, max_zoom=19, threads=0)

    Settings that apply to all renderers.

    .. attribute:: min_zoom
        :type: int

        Smalles zoom level to generate tiles for.

    .. attribute:: max_zoom
        :type: int

        Largest zoom level to generate tiles for.

    .. attribute:: threads
        :type: int

        Number of threads to use for tile generation.

        Setting this to 0 will automatically determine the number of available
        cores and use that many threads.

.. function:: generate(settings, items, renderer, storage)

    Generates the tiles using the given renderer, and saves them to the given
    storage.

    :param settings: The settings.
    :type settings: Settings
    :param items: The tracks to render.
    :type items: ~typing.Iterable[Track]
    :param renderer: The renderer to use.
    :type renderer: HeatmapRenderer | MarktileRenderer | TilehuntRenderer
    :param storage: The storage to output to.
    :type storage: Storage

Errors
------

.. exception:: HitteError

    Catch-all error for underlying hittekaart errors. See the string
    description for the error cause.