geovizpy 0.1.5

A Python wrapper for the geoviz JavaScript library

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 excellent geoviz library. For detailed information on the underlying mapping logic, please refer to the original geoviz documentation.

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:

pip install geovizpy

Or install directly from the source repository:

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, which include playwright.

1. Install the extra dependencies:

   pip install "geovizpy[export]"
   

2. Install Playwright's browser binaries:

   playwright install
   

   On Linux, you may also need to install host dependencies:

   sudo playwright install-deps
   

Quick Start

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

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.