Usage
=====

Here is a simple example of how to use geovizpy to create a map.

Basic Example
-------------

.. code-block:: python

    from geovizpy import Geoviz
    import json

    # Load your GeoJSON data
    with open("world.json") as f:
        world_data = json.load(f)

    # Initialize the map
    viz = Geoviz(projection="EqualEarth", width=800)

    # Add layers
    viz.outline()
    viz.graticule()

    # Add a choropleth layer
    viz.choro(
        data=world_data,
        var="gdppc",
        colors="Reds",
        legend=True,
        leg_title="GDP per Capita"
    )

    # Render to HTML
    viz.render_html("map.html")

Interactive Features
--------------------

geovizpy adds interactive controls to your maps that are not available in the standard static export.

Layer Control
~~~~~~~~~~~~~

You can add a collapsible widget to toggle the visibility of specific layers.
To use this, you must assign an ``id`` to the layers you want to control.

.. code-block:: python

    # 1. Assign IDs to your layers
    viz.choro(..., id="my_choropleth")
    viz.prop(..., id="my_bubbles")
    viz.graticule(..., id="my_grid")

    # 2. Add the control widget
    viz.add_layer_control(
        layers=["my_choropleth", "my_bubbles", "my_grid"],
        title="Map Layers",
        pos="top-left"  # or use x=10, y=10
    )

The widget will appear as a layers icon on the map. Hover over it to expand the list of layers. Unchecking a layer will hide it along with its associated legend (if the legend ID follows the convention ``leg_{layer_id}``, which is automatic for most plots).

Export Control
~~~~~~~~~~~~~~

You can add a download button to allow users to save the map as an image.

.. code-block:: python

    viz.add_export_control(
        pos="top-right",
        title="Download"
    )

This adds a download icon. Hovering over it reveals options to download the map as **SVG** (vector) or **PNG** (raster).

Opacity Control
~~~~~~~~~~~~~~~

You can add a control widget with sliders to adjust the fill opacity of one or multiple layers. This is useful for seeing through layers or adjusting the visual balance of the map.

.. code-block:: python

    # Add an opacity control for one or more layers
    viz.add_opacity_control(
        layers=["my_choropleth", "my_bubbles"],
        title="Layer Opacity",
        pos="top-left",
        y=90  # Position it below the layer control
    )

This will create a widget that, when hovered, reveals individual sliders for each specified layer. The sliders control the `fill-opacity`, meaning that strokes and text labels will remain fully opaque.

The initial position of each slider will reflect the `fill_opacity` set when the layer was created (e.g., in `viz.choro(..., fill_opacity=0.8)`).

Saving Maps
-----------

You can save your map as an interactive HTML file or as a static image (PNG or SVG).

.. code-block:: python

    # Save as an interactive HTML file
    viz.save("my_map.html")

    # Save as a static PNG image
    viz.save("my_map.png")

    # Save as a static SVG image
    viz.save("my_map.svg")

**Note:** Saving as PNG or SVG requires the optional `export` dependencies. You can install them with:

.. code-block:: bash

    pip install geovizpy[export]
    playwright install