geovizpy 0.1.6

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

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.