Usage

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

Basic Example

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.

# 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.

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.

# 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).

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

pip install geovizpy[export]
playwright install