geovizpy 0.1.4__py3-none-any.whl → 0.1.6__py3-none-any.whl

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/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})

geovizpy/renderer.py

@@ -0,0 +1,421 @@
+"""Module for rendering the map to HTML and JSON."""
+
+import json
+import tempfile
+import os
+import time
+import html
+import sys
+import subprocess
+
+class RendererMixin:
+    """Mixin class for rendering the map."""
+
+    def get_config(self):
+        """Return the configuration as a JSON-compatible list of commands."""
+        def process_args(args):
+            new_args = {}
+            for k, v in args.items():
+                if v is None:
+                    continue
+                if isinstance(v, str) and (v.strip().startswith("(") or v.strip().startswith("function") or "=>" in v):
+                     new_args[k] = {"__js_func__": v}
+                elif isinstance(v, dict):
+                    new_args[k] = process_args(v)
+                else:
+                    new_args[k] = v
+            return new_args
+
+        processed_commands = []
+        for cmd in self.commands:
+            processed_commands.append({"name": cmd["name"], "args": process_args(cmd["args"])})
+        
+        return processed_commands
+
+    def to_json(self):
+        """Return the configuration as a JSON string."""
+        return json.dumps(self.get_config())
+
+    def _get_html_content(self):
+        """Generate the full HTML content string."""
+        json_commands = self.to_json()
+        
+        layer_control_js = self._get_layer_control_js()
+        export_control_js = self._get_export_control_js()
+
+        return f"""
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8" />
+  <link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Tangerine"/>
+  <script src="https://cdn.jsdelivr.net/npm/d3@7"></script>
+  <script src="https://cdn.jsdelivr.net/npm/geoviz@0.9.8"></script>
+  <style>
+    body {{ margin: 0; padding: 0; overflow: hidden; }}
+    button {{ background: #f8f9fa; border: 1px solid #ddd; border-radius: 3px; }}
+    button:hover {{ background: #e2e6ea; }}
+  </style>
+</head>
+<body>
+<script>
+  const commands = {json_commands};
+  let svg;
+
+  // Helper to revive functions
+  function revive(obj) {{
+    if (typeof obj === 'object' && obj !== null) {{
+      if (obj.hasOwnProperty('__js_func__')) {{
+         try {{
+            return eval(obj['__js_func__']);
+         }} catch (e) {{
+            console.error("Failed to eval function:", obj['__js_func__'], e);
+            return null;
+         }}
+      }} else {{
+         for (let key in obj) {{
+            obj[key] = revive(obj[key]);
+         }}
+      }}
+    }}
+    return obj;
+  }}
+
+  const revivedCommands = revive(commands);
+
+  revivedCommands.forEach(cmd => {{
+    if (cmd.name === "create") {{
+      svg = geoviz.create(cmd.args);
+    }} else {{
+      const parts = cmd.name.split(".");
+      if (parts.length === 1) {{
+         if (svg[parts[0]]) {{
+            svg[parts[0]](cmd.args);
+         }} else {{
+            console.warn("Method " + parts[0] + " not found");
+         }}
+      }} else if (parts.length === 2) {{
+         if (svg[parts[0]] && svg[parts[0]][parts[1]]) {{
+            svg[parts[0]][parts[1]](cmd.args);
+         }} else {{
+            console.warn("Method " + cmd.name + " not found");
+         }}
+      }}
+    }}
+  }});
+
+  if (svg) {{
+    document.body.appendChild(svg.render());
+  }}
+  
+  {layer_control_js}
+  {export_control_js}
+</script>
+</body>
+</html>
+"""
+
+    def render_html(self, filename="map.html"):
+        """Render the map to an HTML file."""
+        html_content = self._get_html_content()
+        with open(filename, "w") as f:
+            f.write(html_content)
+        print(f"Map saved to {filename}")
+
+    def show(self, width=800, height=600):
+        """
+        Display the map in a Jupyter notebook using an IFrame.
+        
+        Args:
+            width (int/str): Width of the display area (default 800).
+            height (int/str): Height of the display area (default 600).
+        """
+        try:
+            from IPython.display import IFrame
+            import base64
+        except ImportError:
+            print("IPython is required to display the map. Please install it with 'pip install ipython'.")
+            return
+
+        html_content = self._get_html_content()
+        b64_content = base64.b64encode(html_content.encode('utf-8')).decode('utf-8')
+        data_uri = f"data:text/html;base64,{b64_content}"
+        
+        return IFrame(src=data_uri, width=width, height=height)
+
+    def save(self, filename="map.html"):
+        """
+        Save the map to a file.
+        
+        If filename ends with .html, saves the interactive map.
+        If filename ends with .png or .svg, saves a static image.
+        
+        For image export, 'playwright' is required. Install it with:
+        pip install geovizpy[export]
+        playwright install
+        """
+        if filename.endswith(".html"):
+            self.render_html(filename)
+        elif filename.endswith(".png") or filename.endswith(".svg"):
+            self._save_image(filename)
+        else:
+            print("Error: filename must end with .html, .png, or .svg")
+
+    def _save_image(self, filename):
+        """Internal method to save as PNG or SVG using Playwright via a subprocess."""
+        
+        # Check if playwright is installed
+        try:
+            import playwright
+        except ImportError:
+            print("Error: Playwright is required for image export.")
+            print("Please install it with: pip install geovizpy[export] && playwright install")
+            return
+
+        # Create a temporary HTML file
+        with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".html") as tmp_file:
+            self.render_html(tmp_file.name)
+            tmp_path = tmp_file.name
+
+        # Create a temporary Python script to run Playwright
+        # This isolates Playwright from the current asyncio loop (Jupyter)
+        script_content = f"""
+import os
+from playwright.sync_api import sync_playwright
+
+def run():
+    try:
+        with sync_playwright() as p:
+            browser = p.chromium.launch()
+            page = browser.new_page(viewport={{"width": 1000, "height": 800}})
+            page.goto(f"file://{{os.path.abspath('{tmp_path}')}}")
+            page.wait_for_timeout(2000)
+
+            if "{filename}".endswith(".svg"):
+                svg_outer = page.locator("svg").first.evaluate("el => el.outerHTML")
+                with open("{filename}", "w") as f:
+                    f.write(svg_outer)
+            else:
+                page.locator("svg").first.screenshot(path="{filename}")
+            
+            browser.close()
+            print(f"Image saved to {filename}")
+    except Exception as e:
+        print(f"Error in subprocess: {{e}}")
+        exit(1)
+
+if __name__ == "__main__":
+    run()
+"""
+        
+        with tempfile.NamedTemporaryFile(mode="w", delete=False, suffix=".py") as tmp_script:
+            tmp_script.write(script_content)
+            tmp_script_path = tmp_script.name
+
+        try:
+            # Run the script in a subprocess
+            result = subprocess.run([sys.executable, tmp_script_path], capture_output=True, text=True)
+            if result.returncode != 0:
+                print(f"Error saving image: {result.stderr}")
+            else:
+                print(result.stdout.strip())
+        finally:
+            # Cleanup
+            if os.path.exists(tmp_path):
+                os.remove(tmp_path)
+            if os.path.exists(tmp_script_path):
+                os.remove(tmp_script_path)
+
+    def _get_layer_control_js(self):
+        if not self.layer_control_config:
+            return ""
+        config = self.layer_control_config
+        layers_json = json.dumps(config["layers"]) if config["layers"] else "null"
+        return f"""
+            const layerConfig = {{
+                layers: {layers_json},
+                pos: "{config.get('pos')}",
+                x: {config.get('x', 10)},
+                y: {config.get('y', 10)},
+                title: "{config.get('title', 'Layers')}"
+            }};
+            
+            function createLayerControl() {{
+                const wrapper = document.createElement("div");
+                wrapper.style.position = "absolute";
+                wrapper.style.zIndex = "1000";
+                
+                const button = document.createElement("div");
+                button.innerHTML = `<svg width="24" height="24" viewBox="0 0 24 24" fill="#333"><path d="M11.99 18.54l-7.37-5.73L3 14.07l9 7 9-7-1.63-1.27-7.38 5.74zM12 16l7.36-5.73L21 9l-9-7-9 7 1.63 1.27L12 16z"/></svg>`;
+                button.style.width = "32px";
+                button.style.height = "32px";
+                button.style.cursor = "pointer";
+                button.style.border = "1px solid #ccc";
+                button.style.borderRadius = "4px";
+                button.style.backgroundColor = "white";
+                button.style.display = "flex";
+                button.style.alignItems = "center";
+                button.style.justifyContent = "center";
+                button.style.boxShadow = "0 1px 3px rgba(0,0,0,0.2)";
+                
+                const panel = document.createElement("div");
+                panel.style.display = "none";
+                panel.style.backgroundColor = "white";
+                panel.style.padding = "10px";
+                panel.style.border = "1px solid #ccc";
+                panel.style.borderRadius = "5px";
+                panel.style.fontFamily = "sans-serif";
+                panel.style.fontSize = "12px";
+                panel.style.boxShadow = "0 2px 4px rgba(0,0,0,0.2)";
+                panel.style.marginTop = "5px";
+                panel.style.minWidth = "100px";
+
+                wrapper.addEventListener("mouseenter", () => panel.style.display = "block");
+                wrapper.addEventListener("mouseleave", () => panel.style.display = "none");
+
+                if (layerConfig.pos === "top-right") {{
+                    wrapper.style.top = "10px"; wrapper.style.right = "10px";
+                }} else if (layerConfig.pos === "bottom-right") {{
+                    wrapper.style.bottom = "10px"; wrapper.style.right = "10px";
+                }} else if (layerConfig.pos === "bottom-left") {{
+                    wrapper.style.bottom = "10px"; wrapper.style.left = "10px";
+                }} else {{
+                    wrapper.style.top = `${{layerConfig.y}}px`;
+                    wrapper.style.left = `${{layerConfig.x}}px`;
+                }}
+                
+                const title = document.createElement("div");
+                title.innerText = layerConfig.title;
+                title.style.fontWeight = "bold";
+                title.style.marginBottom = "8px";
+                title.style.borderBottom = "1px solid #eee";
+                title.style.paddingBottom = "5px";
+                panel.appendChild(title);
+
+                let layers = layerConfig.layers;
+                if (!layers) {{
+                    layers = Array.from(svg.selectAll("g[id]").nodes()).map(n => n.id);
+                }}
+
+                let count = 0;
+                layers.forEach(layerId => {{
+                    const layer = svg.select("#" + layerId);
+                    if (!layer.empty()) {{
+                        count++;
+                        const row = document.createElement("div");
+                        row.style.marginBottom = "5px";
+                        row.style.display = "flex";
+                        row.style.alignItems = "center";
+                        
+                        const checkbox = document.createElement("input");
+                        checkbox.type = "checkbox";
+                        checkbox.id = "chk_" + layerId;
+                        checkbox.checked = true;
+                        checkbox.style.marginRight = "8px";
+                        checkbox.style.cursor = "pointer";
+                        
+                        checkbox.addEventListener("change", (e) => {{
+                            const display = e.target.checked ? "inline" : "none";
+                            layer.style("display", display);
+                            const legLayer = svg.select("#leg_" + layerId);
+                            if (!legLayer.empty()) legLayer.style("display", display);
+                        }});
+                        
+                        const label = document.createElement("label");
+                        label.htmlFor = "chk_" + layerId;
+                        label.innerText = layerId;
+                        label.style.cursor = "pointer";
+                        
+                        row.appendChild(checkbox);
+                        row.appendChild(label);
+                        panel.appendChild(row);
+                    }}
+                }});
+                
+                if (count > 0) {{
+                    wrapper.appendChild(button);
+                    wrapper.appendChild(panel);
+                    document.body.appendChild(wrapper);
+                }}
+            }}
+            setTimeout(createLayerControl, 100);
+        """
+
+    def _get_export_control_js(self):
+        if not self.export_control_config:
+            return ""
+        ex_config = self.export_control_config
+        return f"""
+            const exportConfig = {{
+                pos: "{ex_config.get('pos')}",
+                x: {ex_config.get('x', 10)},
+                y: {ex_config.get('y', 50)},
+                title: "{ex_config.get('title', 'Export')}"
+            }};
+
+            function createExportControl() {{
+                const wrapper = document.createElement("div");
+                wrapper.style.position = "absolute";
+                wrapper.style.zIndex = "1000";
+
+                const button = document.createElement("div");
+                button.innerHTML = `<svg width="24" height="24" viewBox="0 0 24 24" fill="#333"><path d="M19 9h-4V3H9v6H5l7 7 7-7zM5 18v2h14v-2H5z"/></svg>`;
+                button.style.width = "32px";
+                button.style.height = "32px";
+                button.style.cursor = "pointer";
+                button.style.border = "1px solid #ccc";
+                button.style.borderRadius = "4px";
+                button.style.backgroundColor = "white";
+                button.style.display = "flex";
+                button.style.alignItems = "center";
+                button.style.justifyContent = "center";
+                button.style.boxShadow = "0 1px 3px rgba(0,0,0,0.2)";
+
+                const panel = document.createElement("div");
+                panel.style.display = "none";
+                panel.style.backgroundColor = "white";
+                panel.style.padding = "5px";
+                panel.style.border = "1px solid #ccc";
+                panel.style.borderRadius = "5px";
+                panel.style.marginTop = "5px";
+                panel.style.boxShadow = "0 2px 4px rgba(0,0,0,0.2)";
+                panel.style.display = "none";
+                panel.style.flexDirection = "column";
+                panel.style.gap = "5px";
+
+                wrapper.addEventListener("mouseenter", () => panel.style.display = "flex");
+                wrapper.addEventListener("mouseleave", () => panel.style.display = "none");
+
+                if (exportConfig.pos === "top-right") {{
+                    wrapper.style.top = "50px"; wrapper.style.right = "10px";
+                }} else if (exportConfig.pos === "bottom-right") {{
+                    wrapper.style.bottom = "50px"; wrapper.style.right = "10px";
+                }} else {{
+                    wrapper.style.top = `${{exportConfig.y}}px`;
+                    wrapper.style.left = `${{exportConfig.x}}px`;
+                }}
+
+                const btnSVG = document.createElement("button");
+                btnSVG.innerText = "SVG";
+                btnSVG.style.cursor = "pointer";
+                btnSVG.style.padding = "5px 10px";
+                btnSVG.onclick = () => {{
+                    geoviz.exportSVG(svg, {{filename: "map.svg"}});
+                }};
+
+                const btnPNG = document.createElement("button");
+                btnPNG.innerText = "PNG";
+                btnPNG.style.cursor = "pointer";
+                btnPNG.style.padding = "5px 10px";
+                btnPNG.onclick = () => {{
+                    geoviz.exportPNG(svg, {{filename: "map.png"}});
+                }};
+
+                panel.appendChild(btnSVG);
+                panel.appendChild(btnPNG);
+                wrapper.appendChild(button);
+                wrapper.appendChild(panel);
+                document.body.appendChild(wrapper);
+            }}
+            setTimeout(createExportControl, 100);
+        """