geovizpy 0.1.3__tar.gz → 0.1.5__tar.gz

geovizpy-0.1.5/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: geovizpy
+Version: 0.1.5
+Summary: A Python wrapper for the geoviz JavaScript library
+Author: fbxyz
+Project-URL: Source, https://codeberg.org/fbxyz/geovizpy
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.6
+Description-Content-Type: text/markdown
+Provides-Extra: export
+Requires-Dist: playwright; extra == "export"
+Dynamic: author
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: project-url
+Dynamic: provides-extra
+Dynamic: requires-python
+Dynamic: summary
+
+# 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](https://github.com/neocarto/geoviz).
+
+## 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, which include `playwright`.
+
+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://your-username.github.io/geovizpy/). 
+

geovizpy-0.1.5/README.md

@@ -0,0 +1,95 @@
+# 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](https://github.com/neocarto/geoviz).
+
+## 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, which include `playwright`.
+
+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://your-username.github.io/geovizpy/). 
+

geovizpy-0.1.5/geovizpy/__init__.py

@@ -0,0 +1,7 @@
+"""
+Geovizpy: A Python wrapper for the geoviz JavaScript library.
+"""
+
+from .geoviz import Geoviz
+
+__all__ = ["Geoviz"]

geovizpy-0.1.5/geovizpy/controls.py

@@ -0,0 +1,31 @@
+"""Module for interactive map controls."""
+
+class ControlsMixin:
+    """Mixin class for interactive map controls."""
+
+    def add_layer_control(self, layers=None, pos=None, x=10, y=10, title="Layers"):
+        """
+        Add a collapsible layer control widget (expands on hover).
+        
+        Args:
+            layers (list): List of layer IDs to control. If None, finds all layers with IDs.
+            pos (string): Predefined position ("top-right", "top-left", etc.). Overrides x, y.
+            x (int): X position of the control.
+            y (int): Y position of the control.
+            title (string): Title of the control panel.
+        """
+        self.layer_control_config = {"layers": layers, "pos": pos, "x": x, "y": y, "title": title}
+        return self
+
+    def add_export_control(self, pos=None, x=10, y=50, title="Export"):
+        """
+        Add a download button to export the map as SVG or PNG (expands on hover).
+        
+        Args:
+            pos (string): Predefined position ("top-right", "top-left", etc.). Overrides x, y.
+            x (int): X position of the control.
+            y (int): Y position of the control.
+            title (string): Title of the button.
+        """
+        self.export_control_config = {"pos": pos, "x": x, "y": y, "title": title}
+        return self

geovizpy-0.1.5/geovizpy/effects.py

@@ -0,0 +1,48 @@
+"""Module for visual effects."""
+
+class EffectsMixin:
+    """Mixin class for visual effects."""
+
+    def effect_blur(self, **kwargs):
+        """
+        Apply a blur effect.
+        
+        Args:
+            id (string): ID of the effect.
+            stdDeviation (number): Standard deviation of the blur.
+        """
+        return self._add_command("effect.blur", kwargs)
+
+    def effect_shadow(self, **kwargs):
+        """
+        Apply a shadow effect.
+        
+        Args:
+            id (string): ID of the effect.
+            dx (number): X offset.
+            dy (number): Y offset.
+            stdDeviation (number): Blur amount.
+            opacity (number): Opacity of the shadow.
+            color (string): Color of the shadow.
+        """
+        return self._add_command("effect.shadow", kwargs)
+
+    def effect_radialGradient(self, **kwargs):
+        """
+        Apply a radial gradient effect.
+        
+        Args:
+            id (string): ID of the effect.
+            stops (list): List of stops (e.g., [{"offset": "0%", "color": "white"}, ...]).
+        """
+        return self._add_command("effect.radialGradient", kwargs)
+
+    def effect_clipPath(self, **kwargs):
+        """
+        Apply a clip path effect.
+        
+        Args:
+            id (string): ID of the effect.
+            datum (object): GeoJSON to use as clip path.
+        """
+        return self._add_command("effect.clipPath", kwargs)

geovizpy-0.1.5/geovizpy/geoviz.py

@@ -0,0 +1,43 @@
+"""Main Geoviz class that assembles all modules."""
+
+from .marks import MarksMixin
+from .plots import PlotsMixin
+from .legends import LegendsMixin
+from .effects import EffectsMixin
+from .controls import ControlsMixin
+from .renderer import RendererMixin
+
+class Geoviz(
+    MarksMixin,
+    PlotsMixin,
+    LegendsMixin,
+    EffectsMixin,
+    ControlsMixin,
+    RendererMixin
+):
+    """
+    A Python wrapper for the geoviz JavaScript library.
+    Allows creating maps by chaining commands and rendering them to an HTML file.
+    """
+    def __init__(self, **kwargs):
+        """
+        Initialize the Geoviz object.
+        
+        Args:
+            width (int): Width of the SVG.
+            height (int): Height of the SVG.
+            margin (list): Margins [top, right, bottom, left].
+            domain (object): GeoJSON to define the domain.
+            projection (string): Projection name (e.g., "mercator", "EqualEarth").
+            zoomable (bool): If True, the map is zoomable.
+            background (string): Background color.
+        """
+        self.commands = []
+        self.commands.append({"name": "create", "args": kwargs})
+        self.layer_control_config = None
+        self.export_control_config = None
+
+    def _add_command(self, name, args):
+        """Add a command to the list of commands to be executed."""
+        self.commands.append({"name": name, "args": args})
+        return self

geovizpy-0.1.5/geovizpy/legends.py

@@ -0,0 +1,60 @@
+"""Module for map legends."""
+
+class LegendsMixin:
+    """Mixin class for map legends."""
+
+    def legend_circles_nested(self, **kwargs):
+        """Draw a nested circles legend."""
+        return self._add_command("legend.circles_nested", kwargs)
+
+    def legend_circles(self, **kwargs):
+        """Draw a circles legend."""
+        return self._add_command("legend.circles", kwargs)
+
+    def legend_squares(self, **kwargs):
+        """Draw a squares legend."""
+        return self._add_command("legend.squares", kwargs)
+
+    def legend_squares_nested(self, **kwargs):
+        """Draw a nested squares legend."""
+        return self._add_command("legend.squares_nested", kwargs)
+
+    def legend_circles_half(self, **kwargs):
+        """Draw a half-circles legend."""
+        return self._add_command("legend.circles_half", kwargs)
+
+    def legend_spikes(self, **kwargs):
+        """Draw a spikes legend."""
+        return self._add_command("legend.spikes", kwargs)
+
+    def legend_mushrooms(self, **kwargs):
+        """Draw a mushrooms legend."""
+        return self._add_command("legend.mushrooms", kwargs)
+
+    def legend_choro_vertical(self, **kwargs):
+        """Draw a vertical choropleth legend."""
+        return self._add_command("legend.choro_vertical", kwargs)
+
+    def legend_choro_horizontal(self, **kwargs):
+        """Draw a horizontal choropleth legend."""
+        return self._add_command("legend.choro_horizontal", kwargs)
+
+    def legend_typo_vertical(self, **kwargs):
+        """Draw a vertical typology legend."""
+        return self._add_command("legend.typo_vertical", kwargs)
+
+    def legend_typo_horizontal(self, **kwargs):
+        """Draw a horizontal typology legend."""
+        return self._add_command("legend.typo_horizontal", kwargs)
+
+    def legend_symbol_vertical(self, **kwargs):
+        """Draw a vertical symbol legend."""
+        return self._add_command("legend.symbol_vertical", kwargs)
+
+    def legend_symbol_horizontal(self, **kwargs):
+        """Draw a horizontal symbol legend."""
+        return self._add_command("legend.symbol_horizontal", kwargs)
+
+    def legend_box(self, **kwargs):
+        """Draw a box legend."""
+        return self._add_command("legend.box", kwargs)

geovizpy-0.1.5/geovizpy/marks.py

@@ -0,0 +1,184 @@
+"""Module containing low-level drawing marks."""
+
+class MarksMixin:
+    """Mixin class for drawing marks on the map."""
+
+    def outline(self, **kwargs):
+        """
+        Add an outline to the map (graticule sphere).
+        
+        Args:
+            fill (string): Fill color.
+            stroke (string): Stroke color.
+            strokeWidth (number): Stroke width.
+        """
+        return self._add_command("outline", kwargs)
+
+    def graticule(self, **kwargs):
+        """
+        Add a graticule to the map.
+        
+        Args:
+            stroke (string): Stroke color.
+            strokeWidth (number): Stroke width.
+            step (list): Step [x, y] in degrees.
+        """
+        return self._add_command("graticule", kwargs)
+
+    def path(self, **kwargs):
+        """
+        Draw a path (geometry) on the map.
+        
+        Args:
+            datum (object): GeoJSON Feature or FeatureCollection.
+            fill (string): Fill color.
+            stroke (string): Stroke color.
+            strokeWidth (number): Stroke width.
+        """
+        return self._add_command("path", kwargs)
+
+    def header(self, **kwargs):
+        """
+        Add a header (title) to the map.
+        
+        Args:
+            text (string): Title text.
+            fontSize (number): Font size.
+            fontFamily (string): Font family.
+            fill (string): Text color.
+            anchor (string): Text anchor ("start", "middle", "end").
+        """
+        return self._add_command("header", kwargs)
+
+    def footer(self, **kwargs):
+        """
+        Add a footer (source, author) to the map.
+        
+        Args:
+            text (string): Footer text.
+            fontSize (number): Font size.
+            fill (string): Text color.
+            anchor (string): Text anchor.
+        """
+        return self._add_command("footer", kwargs)
+
+    def circle(self, **kwargs):
+        """
+        Draw circles on the map (low-level mark).
+        For proportional circles with legend, use prop().
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            r (string|number): Radius value or property name.
+            fill (string): Fill color.
+            stroke (string): Stroke color.
+            tip (string|bool): Tooltip content.
+        """
+        return self._add_command("circle", kwargs)
+
+    def square(self, **kwargs):
+        """
+        Draw squares on the map (low-level mark).
+        For proportional squares with legend, use prop(symbol="square").
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            side (string|number): Side length or property name.
+            fill (string): Fill color.
+        """
+        return self._add_command("square", kwargs)
+
+    def spike(self, **kwargs):
+        """
+        Draw spikes on the map (low-level mark).
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            height (string|number): Height value or property name.
+            width (number): Width of the spike.
+            fill (string): Fill color.
+        """
+        return self._add_command("spike", kwargs)
+
+    def text(self, **kwargs):
+        """
+        Add text labels to the map.
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            text (string): Property name for the text.
+            fontSize (number): Font size.
+            fill (string): Text color.
+        """
+        return self._add_command("text", kwargs)
+
+    def tile(self, **kwargs):
+        """
+        Add a tile layer (basemap).
+        
+        Args:
+            url (string): URL template or keyword (e.g., "worldStreet", "openstreetmap").
+            opacity (number): Opacity (0 to 1).
+        """
+        return self._add_command("tile", kwargs)
+
+    def scalebar(self, **kwargs):
+        """
+        Add a scale bar.
+        
+        Args:
+            x (number): X position.
+            y (number): Y position.
+            units (string): "km" or "mi".
+        """
+        return self._add_command("scalebar", kwargs)
+
+    def north(self, **kwargs):
+        """
+        Add a north arrow.
+        
+        Args:
+            x (number): X position.
+            y (number): Y position.
+            width (number): Width of the arrow.
+        """
+        return self._add_command("north", kwargs)
+
+    def plot(self, **kwargs):
+        """
+        Generic plot function.
+        
+        Args:
+            type (string): Type of plot ("choro", "prop", "typo", etc.).
+            data (object): GeoJSON data.
+            var (string): Variable to map.
+        """
+        return self._add_command("plot", kwargs)
+
+    def tissot(self, **kwargs):
+        """Draw Tissot's indicatrix to visualize distortion."""
+        return self._add_command("tissot", kwargs)
+
+    def rhumbs(self, **kwargs):
+        """Draw rhumb lines."""
+        return self._add_command("rhumbs", kwargs)
+
+    def earth(self, **kwargs):
+        """Draw the earth (background)."""
+        return self._add_command("earth", kwargs)
+
+    def empty(self, **kwargs):
+        """Create an empty layer."""
+        return self._add_command("empty", kwargs)
+
+    def halfcircle(self, **kwargs):
+        """Draw half-circles."""
+        return self._add_command("halfcircle", kwargs)
+
+    def symbol(self, **kwargs):
+        """Draw symbols."""
+        return self._add_command("symbol", kwargs)
+
+    def grid(self, **kwargs):
+        """Draw a grid."""
+        return self._add_command("grid", kwargs)

geovizpy-0.1.5/geovizpy/plots.py

@@ -0,0 +1,86 @@
+"""Module for thematic map plots."""
+
+class PlotsMixin:
+    """Mixin class for thematic map plots."""
+
+    def choro(self, **kwargs):
+        """
+        Draw a choropleth map.
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            var (string): Variable name containing numeric values.
+            method (string): Classification method ('quantile', 'jenks', 'equal', etc.).
+            nb (int): Number of classes.
+            colors (string|list): Color palette name or list of colors.
+            legend (bool): Whether to show the legend (default: True).
+            leg_pos (list): Legend position [x, y].
+            leg_title (string): Legend title.
+        """
+        return self._add_command("plot", {"type": "choro", **kwargs})
+
+    def typo(self, **kwargs):
+        """
+        Draw a typology map (categorical data).
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            var (string): Variable name containing categories.
+            colors (string|list): Color palette or list.
+            legend (bool): Show legend.
+        """
+        return self._add_command("plot", {"type": "typo", **kwargs})
+
+    def prop(self, **kwargs):
+        """
+        Draw a proportional symbol map.
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            var (string): Variable name containing numeric values.
+            symbol (string): Symbol type ("circle", "square", "spike").
+            k (number): Size of the largest symbol.
+            fill (string): Fill color.
+            legend (bool): Show legend.
+            leg_type (string): Legend style ("nested", "separate").
+        """
+        return self._add_command("plot", {"type": "prop", **kwargs})
+
+    def propchoro(self, **kwargs):
+        """
+        Draw proportional symbols colored by a choropleth variable.
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            var (string): Variable for symbol size.
+            var2 (string): Variable for color.
+            method (string): Classification method for color.
+            colors (string|list): Color palette.
+        """
+        return self._add_command("plot", {"type": "propchoro", **kwargs})
+
+    def proptypo(self, **kwargs):
+        """
+        Draw proportional symbols colored by categories.
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            var (string): Variable for symbol size.
+            var2 (string): Variable for category color.
+        """
+        return self._add_command("plot", {"type": "proptypo", **kwargs})
+
+    def picto(self, **kwargs):
+        """Draw a pictogram map."""
+        return self._add_command("plot", {"type": "picto", **kwargs})
+
+    def bertin(self, **kwargs):
+        """
+        Draw a Bertin map (dots).
+        
+        Args:
+            data (object): GeoJSON FeatureCollection.
+            var (string): Variable name.
+            n (int): Number of dots per unit.
+        """
+        return self._add_command("plot", {"type": "bertin", **kwargs})