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, Storage, generate
    )

    tracks = [
        Track.from_file(b"Documents/track.gpx", None),
        Track.from_coordinates([(45.0, 47.0)]),
    ]
    storage = Storage.Sqlite(b"/tmp/tiles.sqlite")
    generate(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

Functions
---------

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

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

    :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

.. function:: set_threads(threads)

    Set the number of threads that hittekaart will use.

    Note that this is a global function, it will affect all subsequent calls.

    Note further that you may only call this function once, at startup. Calls
    after the thread pool has been initialized (e.g. via a :func:`generate` or
    :func:`set_threads` call) will raise an exception.

    :param threads: Number of threads to use.
    :type threads: int

Errors
------

.. exception:: HitteError

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