# geovizpy

**geovizpy** is a Python wrapper for the `geoviz` JavaScript library, designed to bring the power of D3.js-based thematic mapping to Python. It allows you to create high-quality, interactive maps directly from Python scripts or Jupyter notebooks.

This library is a wrapper around the  `geoviz` library. For detailed information on the underlying mapping logic, please refer to the [original geoviz documentation](https://github.com/neocarto/geoviz).

![Choropleth Map Example](https://codeberg.org/fbxyz/geovizpy/raw/branch/main/docs/source/_static/choropleth.png)

## Features

- **Simple, chainable API**: Build complex maps by chaining intuitive methods.
- **Variety of Map Types**: Create choropleth, proportional symbol, typology, and other thematic maps.
- **Interactive Controls**: Add hover-to-expand controls for toggling layer visibility and exporting the map as SVG or PNG.
- **Customizable**: Extensive options to customize colors, legends, strokes, and more.
- **Standalone HTML**: Renders self-contained HTML files with no server required.
- **Image Export**: Save maps directly to PNG or SVG from Python (requires optional dependencies).

## Installation

### Standard Installation

You can install the core library using pip:

```bash
pip install geovizpy
```

Or install directly from the source repository:

```bash
pip install git+https://codeberg.org/fbxyz/geovizpy.git
```

### For Image Export

To save maps as PNG or SVG files directly from Python, you need to install the optional `export` dependencies:

1.  **Install the extra dependencies:**

    ```bash
    pip install "geovizpy[export]"
    ```

2.  **Install Playwright's browser binaries:**

    ```bash
    playwright install
    ```

    On Linux, you may also need to install host dependencies:
    
    ```bash
    sudo playwright install-deps
    ```

## Quick Start

Here is a simple example of how to create a choropleth map:

```python
from geovizpy import Geoviz
import json

# Load your GeoJSON data
# (Assuming 'world.json' is in a 'data' subdirectory)
with open("data/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="Blues",
    legend=True,
    leg_title="GDP per Capita"
)

# Add interactive controls
viz.add_layer_control(layers=["choropleth_gdp"])
viz.add_export_control()

# Save the map
viz.save("my_map.html")  # Renders an interactive HTML file
# viz.save("my_map.png")   # Renders a static PNG image (requires export dependencies)
```

## Documentation

For more detailed information on all available methods and parameters, please see the [full documentation](https://geovizpy.readthedocs.io/en/latest/).
