multilayer-sdk 0.1.0__py3-none-any.whl

multilayer/__init__.py

@@ -0,0 +1,51 @@
+# -*- coding: utf-8 -*-
+"""
+multilayer — Pure-Python Synchronized Multi-Panel Map Visualization & Spatial Comparison Engine.
+"""
+
+from __future__ import annotations
+
+from multilayer.core import MultiMap, Panel, SwipeMap, create_multimap
+from multilayer.grid import GridLayout, GridPreset
+from multilayer.layers import (
+    Layer,
+    RasterLayer,
+    TileLayer,
+    TileProvider,
+    VectorLayer,
+    get_tile_provider,
+)
+from multilayer.symbology import (
+    CategoricalStyle,
+    Choropleth,
+    ClassificationMethod,
+    ColorRamp,
+    GraduatedStyle,
+    StyleRule,
+)
+
+__version__ = "0.1.0"
+__author__ = "Yusuf Eminoğlu"
+__email__ = "yusufeminoglu@gmail.com"
+
+__all__ = [
+    "MultiMap",
+    "Panel",
+    "SwipeMap",
+    "create_multimap",
+    "GridLayout",
+    "GridPreset",
+    "Layer",
+    "VectorLayer",
+    "RasterLayer",
+    "TileLayer",
+    "TileProvider",
+    "get_tile_provider",
+    "Choropleth",
+    "ClassificationMethod",
+    "ColorRamp",
+    "StyleRule",
+    "GraduatedStyle",
+    "CategoricalStyle",
+    "__version__",
+]

multilayer/cli.py

@@ -0,0 +1,134 @@
+# -*- coding: utf-8 -*-
+"""Command Line Interface for multilayer-sdk."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import webbrowser
+
+from multilayer import __version__
+from multilayer.core import MultiMap, SwipeMap
+from multilayer.layers import TileProvider, VectorLayer
+
+
+def main(args: list[str] | None = None) -> int:
+    """Main CLI entrypoint."""
+    parser = argparse.ArgumentParser(
+        prog="multilayer",
+        description="Pure-Python Synchronized Multi-Panel Map Visualization & Spatial Comparison CLI.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="command", help="Available subcommands")
+
+    # Subcommand: build
+    build_parser = subparsers.add_parser("build", help="Build synchronized multi-panel HTML dashboard")
+    build_parser.add_argument("--layers", "-l", required=True, help="Comma-separated list of GeoJSON layer paths")
+    build_parser.add_argument("--grid", "-g", default="2x2", help="Grid preset: 1x2, 2x1, 1x3, 2x2, 2x3, 2x4 (default: 2x2)")
+    build_parser.add_argument("--title", "-t", default="MultiMap Workspace", help="Dashboard title")
+    build_parser.add_argument("--basemap", "-b", default="carto-dark-matter", help="Basemap provider (default: carto-dark-matter)")
+    build_parser.add_argument("--theme", default="dark", choices=["dark", "light"], help="Color theme (default: dark)")
+    build_parser.add_argument("--out", "-o", default="multimap_dashboard.html", help="Output HTML file path")
+    build_parser.add_argument("--open", action="store_true", help="Open generated HTML dashboard in default browser")
+
+    # Subcommand: compare (Swipe Map)
+    compare_parser = subparsers.add_parser("compare", help="Create split-screen curtain swipe map")
+    compare_parser.add_argument("left_layer", help="Left / Before GeoJSON file path")
+    compare_parser.add_argument("right_layer", help="Right / After GeoJSON file path")
+    compare_parser.add_argument("--left-title", default="Before", help="Left layer title")
+    compare_parser.add_argument("--right-title", default="After", help="Right layer title")
+    compare_parser.add_argument("--out", "-o", default="swipe_map.html", help="Output HTML file path")
+    compare_parser.add_argument("--open", action="store_true", help="Open generated swipe map in browser")
+
+    # Subcommand: inspect
+    inspect_parser = subparsers.add_parser("inspect", help="Inspect GeoJSON layer features, bounding box, and properties")
+    inspect_parser.add_argument("input_file", help="GeoJSON file path to inspect")
+
+    # Subcommand: tiles
+    subparsers.add_parser("tiles", help="List all built-in web map tile basemaps")
+
+    parsed_args = parser.parse_args(args)
+
+    if not parsed_args.command:
+        parser.print_help()
+        return 0
+
+    if parsed_args.command == "build":
+        layer_paths = [p.strip() for p in parsed_args.layers.split(",") if p.strip()]
+        mm = MultiMap(
+            grid=parsed_args.grid,
+            title=parsed_args.title,
+            theme=parsed_args.theme,
+            basemap=parsed_args.basemap,
+        )
+
+        for idx, lp in enumerate(layer_paths):
+            if not os.path.exists(lp):
+                print(f"Error: Layer file not found: {lp}", file=sys.stderr)
+                return 1
+            if idx < mm.panel_count:
+                vlyr = VectorLayer.from_geojson(lp)
+                mm.panel(idx).add_layer(vlyr)
+                mm.panel(idx).title = vlyr.name
+
+        out_path = os.path.abspath(parsed_args.out)
+        mm.to_html(out_path)
+        print(f"✓ Synchronized MultiMap dashboard generated: {out_path} ({os.path.getsize(out_path):,} bytes)")
+
+        if parsed_args.open:
+            webbrowser.open(f"file://{out_path}")
+        return 0
+
+    elif parsed_args.command == "compare":
+        if not os.path.exists(parsed_args.left_layer) or not os.path.exists(parsed_args.right_layer):
+            print("Error: One or both layer files not found.", file=sys.stderr)
+            return 1
+
+        sm = SwipeMap(
+            left_layer=parsed_args.left_layer,
+            right_layer=parsed_args.right_layer,
+            left_title=parsed_args.left_title,
+            right_title=parsed_args.right_title,
+        )
+        out_path = os.path.abspath(parsed_args.out)
+        sm.to_html(out_path)
+        print(f"✓ Split-screen Swipe Map generated: {out_path} ({os.path.getsize(out_path):,} bytes)")
+
+        if parsed_args.open:
+            webbrowser.open(f"file://{out_path}")
+        return 0
+
+    elif parsed_args.command == "inspect":
+        if not os.path.exists(parsed_args.input_file):
+            print(f"Error: File not found: {parsed_args.input_file}", file=sys.stderr)
+            return 1
+        with open(parsed_args.input_file, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        v = VectorLayer.from_geojson(data, name=parsed_args.input_file)
+        feats = data.get("features", [])
+        bounds = v.get_bounds()
+        props_keys = set()
+        for ft in feats:
+            props_keys.update(ft.get("properties", {}).keys())
+
+        print(f"Layer File     : {parsed_args.input_file}")
+        print(f"Feature Count  : {len(feats):,}")
+        print(f"Bounding Box   : {bounds}")
+        print(f"Properties ({len(props_keys)}) : {', '.join(sorted(props_keys))}")
+        return 0
+
+    elif parsed_args.command == "tiles":
+        print("Available Built-in Tile Providers in multilayer-sdk:")
+        for tp in TileProvider:
+            if tp != TileProvider.NONE:
+                print(f"  - {tp.value:<20} : {tp.url_template}")
+        return 0
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

multilayer/core.py

@@ -0,0 +1,232 @@
+# -*- coding: utf-8 -*-
+"""Core MultiMap and Panel container classes."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Any
+
+from multilayer.grid import GridLayout, GridPreset
+from multilayer.html_builder import build_multimap_html, build_swipe_map_html
+from multilayer.layers import Layer, TileLayer, VectorLayer, get_tile_provider
+
+
+@dataclass
+class Panel:
+    """Individual map viewport within a MultiMap grid."""
+
+    title: str = "Map Panel"
+    basemap: TileLayer = field(default_factory=lambda: get_tile_provider("carto-dark-matter"))
+    layers: list[Layer] = field(default_factory=list)
+    opacity: float = 1.0
+    sync_nav: bool = True
+
+    def add_layer(self, layer: Layer | str | dict[str, Any], **kwargs: Any) -> Panel:
+        """Add a vector or tile layer to this panel."""
+        if isinstance(layer, Layer):
+            self.layers.append(layer)
+        elif isinstance(layer, (str, dict)):
+            v_layer = VectorLayer.from_geojson(layer, **kwargs)
+            self.layers.append(v_layer)
+        else:
+            raise TypeError(f"Unsupported layer type: {type(layer)}")
+        return self
+
+    def set_basemap(self, basemap_or_name: TileLayer | str) -> Panel:
+        """Set or change the background basemap provider for this panel."""
+        if isinstance(basemap_or_name, TileLayer):
+            self.basemap = basemap_or_name
+        elif isinstance(basemap_or_name, str):
+            self.basemap = get_tile_provider(basemap_or_name)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "title": self.title,
+            "basemap": self.basemap.to_dict() if self.basemap else None,
+            "layers": [lyr.to_dict() for lyr in self.layers],
+            "opacity": self.opacity,
+            "sync_nav": self.sync_nav,
+        }
+
+    def get_bounds(self) -> tuple[float, float, float, float] | None:
+        """Calculate union bounding box of all layers in this panel."""
+        boxes = [lyr.get_bounds() for lyr in self.layers if lyr.get_bounds() is not None]
+        if not boxes:
+            return None
+        min_lon = min(b[0] for b in boxes)
+        min_lat = min(b[1] for b in boxes)
+        max_lon = max(b[2] for b in boxes)
+        max_lat = max(b[3] for b in boxes)
+        return min_lon, min_lat, max_lon, max_lat
+
+
+class MultiMap:
+    """Master synchronized multi-panel map container."""
+
+    def __init__(
+        self,
+        grid: str | GridPreset | GridLayout = "2x2",
+        title: str = "MultiMap Spatial Workspace",
+        theme: str = "dark",
+        basemap: str | TileLayer = "carto-dark-matter",
+        initial_center: tuple[float, float] | None = None,
+        initial_zoom: int | None = None,
+    ) -> None:
+        if isinstance(grid, str):
+            self.grid = GridLayout.from_string(grid)
+        elif isinstance(grid, GridPreset):
+            self.grid = GridLayout(preset=grid)
+        elif isinstance(grid, GridLayout):
+            self.grid = grid
+        else:
+            self.grid = GridLayout(preset=GridPreset.FOUR_GRID)
+
+        self.title = title
+        self.theme = theme
+        self.default_basemap = get_tile_provider(basemap) if isinstance(basemap, str) else basemap
+        self.initial_center = initial_center
+        self.initial_zoom = initial_zoom
+
+        # Initialize panels to match grid layout
+        self.panels: list[Panel] = []
+        for i in range(self.grid.panel_count):
+            self.panels.append(
+                Panel(
+                    title=f"Panel {i + 1}",
+                    basemap=self.default_basemap,
+                )
+            )
+
+    @property
+    def panel_count(self) -> int:
+        return len(self.panels)
+
+    def panel(self, index: int) -> Panel:
+        """Access a specific panel by 0-based index."""
+        if 0 <= index < len(self.panels):
+            return self.panels[index]
+        raise IndexError(f"Panel index {index} out of range (0 to {len(self.panels)-1})")
+
+    def add_layer(self, layer: Layer | str | dict[str, Any], panel_index: int | None = None, **kwargs: Any) -> MultiMap:
+        """Add a layer to a specific panel or to all panels if panel_index is None."""
+        if panel_index is not None:
+            self.panel(panel_index).add_layer(layer, **kwargs)
+        else:
+            for p in self.panels:
+                p.add_layer(layer, **kwargs)
+        return self
+
+    def set_basemap(self, basemap_or_name: TileLayer | str, panel_index: int | None = None) -> MultiMap:
+        """Set basemap for a specific panel or all panels."""
+        if panel_index is not None:
+            self.panel(panel_index).set_basemap(basemap_or_name)
+        else:
+            for p in self.panels:
+                p.set_basemap(basemap_or_name)
+        return self
+
+    def get_bounds(self) -> tuple[float, float, float, float] | None:
+        """Calculate union bounding box of all panels."""
+        boxes = [p.get_bounds() for p in self.panels if p.get_bounds() is not None]
+        if not boxes:
+            return None
+        min_lon = min(b[0] for b in boxes)
+        min_lat = min(b[1] for b in boxes)
+        max_lon = max(b[2] for b in boxes)
+        max_lat = max(b[3] for b in boxes)
+        return min_lon, min_lat, max_lon, max_lat
+
+    def to_html(self, output_path: str | None = None) -> str:
+        """Compile MultiMap to standalone interactive HTML and optionally save to file."""
+        html_str = build_multimap_html(self)
+        if output_path:
+            os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+            with open(output_path, "w", encoding="utf-8") as f:
+                f.write(html_str)
+        return html_str
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert MultiMap configuration to dictionary."""
+        return {
+            "title": self.title,
+            "theme": self.theme,
+            "grid": self.grid.preset.value,
+            "panels": [p.to_dict() for p in self.panels],
+            "bounds": self.get_bounds(),
+        }
+
+    def _repr_html_(self) -> str:
+        """Direct inline HTML representation inside Jupyter Notebook / Google Colab."""
+        html_data = self.to_html()
+        escaped = html_data.replace('"', '&quot;')
+        return f'<iframe srcdoc="{escaped}" width="100%" height="600px" style="border:1px solid #1e293b;border-radius:8px;"></iframe>'
+
+    def show(self) -> None:
+        """Display inline widget in Jupyter Notebook environments."""
+        try:
+            from IPython.display import HTML, display
+            display(HTML(self._repr_html_()))
+        except ImportError:
+            print(f"MultiMap({self.grid.preset.value}, panels={len(self.panels)}, title='{self.title}')")
+
+
+class SwipeMap:
+    """Split-screen 2-panel curtain swipe comparison map."""
+
+    def __init__(
+        self,
+        left_layer: Layer | str | dict[str, Any] | None = None,
+        right_layer: Layer | str | dict[str, Any] | None = None,
+        left_title: str = "Before (2020)",
+        right_title: str = "After (2026)",
+        title: str = "Swipe Map Comparison",
+        basemap: str | TileLayer = "carto-dark-matter",
+    ) -> None:
+        self.left_layer = VectorLayer.from_geojson(left_layer) if isinstance(left_layer, (str, dict)) else left_layer
+        self.right_layer = VectorLayer.from_geojson(right_layer) if isinstance(right_layer, (str, dict)) else right_layer
+        self.left_title = left_title
+        self.right_title = right_title
+        self.title = title
+        self.basemap = get_tile_provider(basemap) if isinstance(basemap, str) else basemap
+
+    def get_bounds(self) -> tuple[float, float, float, float] | None:
+        boxes: list[tuple[float, float, float, float]] = []
+        if self.left_layer and self.left_layer.get_bounds():
+            boxes.append(self.left_layer.get_bounds())  # type: ignore
+        if self.right_layer and self.right_layer.get_bounds():
+            boxes.append(self.right_layer.get_bounds())  # type: ignore
+        if not boxes:
+            return None
+        return min(b[0] for b in boxes), min(b[1] for b in boxes), max(b[2] for b in boxes), max(b[3] for b in boxes)
+
+    def to_html(self, output_path: str | None = None) -> str:
+        html_str = build_swipe_map_html(self)
+        if output_path:
+            os.makedirs(os.path.dirname(os.path.abspath(output_path)), exist_ok=True)
+            with open(output_path, "w", encoding="utf-8") as f:
+                f.write(html_str)
+        return html_str
+
+    def _repr_html_(self) -> str:
+        html_data = self.to_html()
+        escaped = html_data.replace('"', '&quot;')
+        return f'<iframe srcdoc="{escaped}" width="100%" height="600px" style="border:1px solid #1e293b;border-radius:8px;"></iframe>'
+
+
+def create_multimap(
+    layers: list[Layer | str | dict[str, Any]] | None = None,
+    grid: str = "2x2",
+    title: str = "MultiMap Workspace",
+    basemap: str = "carto-dark-matter",
+) -> MultiMap:
+    """Convenience factory to quickly create a MultiMap and assign layers to panels."""
+    m = MultiMap(grid=grid, title=title, basemap=basemap)
+    if layers:
+        for idx, lyr in enumerate(layers):
+            if idx < m.panel_count:
+                m.panel(idx).add_layer(lyr)
+                if hasattr(lyr, "name") and lyr.name:
+                    m.panel(idx).title = lyr.name
+    return m

multilayer/grid.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+"""Grid layout definitions and matrix configuration for MultiMap panels."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class GridPreset(str, Enum):
+    """Supported coordinated multi-panel grid presets."""
+
+    TWO_HORIZONTAL = "1x2"
+    TWO_VERTICAL = "2x1"
+    THREE_HORIZONTAL = "1x3"
+    FOUR_GRID = "2x2"
+    SIX_GRID = "2x3"
+    EIGHT_GRID = "2x4"
+
+    @property
+    def rows(self) -> int:
+        return int(self.value.split("x")[0])
+
+    @property
+    def cols(self) -> int:
+        return int(self.value.split("x")[1])
+
+    @property
+    def panel_count(self) -> int:
+        return self.rows * self.cols
+
+
+@dataclass
+class GridLayout:
+    """Manages panel geometry, CSS grid configurations, and responsive matrix sizing."""
+
+    preset: GridPreset = GridPreset.FOUR_GRID
+    custom_rows: int | None = None
+    custom_cols: int | None = None
+
+    @property
+    def rows(self) -> int:
+        return self.custom_rows if self.custom_rows is not None else self.preset.rows
+
+    @property
+    def cols(self) -> int:
+        return self.custom_cols if self.custom_cols is not None else self.preset.cols
+
+    @property
+    def panel_count(self) -> int:
+        return self.rows * self.cols
+
+    @classmethod
+    def from_string(cls, grid_str: str) -> GridLayout:
+        """Parse grid string such as '1x2', '2x2', '2x3', '2x4' or '4'."""
+        clean = grid_str.strip().lower()
+        if clean in [e.value for e in GridPreset]:
+            return cls(preset=GridPreset(clean))
+        if clean in ["2", "two"]:
+            return cls(preset=GridPreset.TWO_HORIZONTAL)
+        if clean in ["3", "three"]:
+            return cls(preset=GridPreset.THREE_HORIZONTAL)
+        if clean in ["4", "four"]:
+            return cls(preset=GridPreset.FOUR_GRID)
+        if clean in ["6", "six"]:
+            return cls(preset=GridPreset.SIX_GRID)
+        if clean in ["8", "eight"]:
+            return cls(preset=GridPreset.EIGHT_GRID)
+
+        if "x" in clean:
+            parts = clean.split("x")
+            try:
+                r, c = int(parts[0]), int(parts[1])
+                return cls(custom_rows=r, custom_cols=c)
+            except ValueError:
+                pass
+        return cls(preset=GridPreset.FOUR_GRID)
+
+    def to_css_grid(self) -> str:
+        """Return CSS grid-template-columns and grid-template-rows declaration."""
+        return f"grid-template-columns: repeat({self.cols}, 1fr); grid-template-rows: repeat({self.rows}, 1fr);"