topolib 0.5.0__py3-none-any.whl → 0.7.0__py3-none-any.whl

topolib/elements/__init__.py

@@ -2,7 +2,4 @@
 from .node import Node
 from .link import Link
 
-# Hide re-exported Link from Sphinx index to avoid duplicate warnings
-Link.__doc__ = """.. :noindex:"""
-
 __all__ = ["Node", "Link"]

topolib/elements/link.py

@@ -7,10 +7,7 @@ if TYPE_CHECKING:
 
 
 class Link:
-
     """
-    .. :noindex:
-
     Represents a link between two nodes.
 
     Parameters
@@ -24,17 +21,6 @@ class Link:
     length : float
         Length of the link (must be non-negative).
 
-    Attributes
-    ----------
-    id : int
-        Unique identifier for the link.
-    source : :class:`topolib.elements.node.Node`
-        Source node of the link.
-    target : :class:`topolib.elements.node.Node`
-        Target node of the link.
-    length : float
-        Length of the link.
-
     Examples
     --------
     >>> link = Link(1, nodeA, nodeB, 10.5)
@@ -50,8 +36,6 @@ class Link:
     @property
     def id(self) -> int:
         """
-        .. :noindex:
-
         int: Unique identifier for the link.
         """
         return self._id
@@ -66,8 +50,6 @@ class Link:
     @property
     def source(self) -> "Node":
         """
-        .. :noindex:
-
         :class:`topolib.elements.node.Node`: Source node of the link.
         """
         return self._source
@@ -80,15 +62,12 @@ class Link:
         required_attrs = ("id", "name", "latitude", "longitude")
         for attr in required_attrs:
             if not hasattr(value, attr):
-                raise TypeError(
-                    f"source must behave like a Node (missing {attr})")
+                raise TypeError(f"source must behave like a Node (missing {attr})")
         self._source = value
 
     @property
     def target(self) -> "Node":
         """
-        .. :noindex:
-
         :class:`topolib.elements.node.Node`: Target node of the link.
         """
         return self._target
@@ -101,15 +80,12 @@ class Link:
         required_attrs = ("id", "name", "latitude", "longitude")
         for attr in required_attrs:
             if not hasattr(value, attr):
-                raise TypeError(
-                    f"target must behave like a Node (missing {attr})")
+                raise TypeError(f"target must behave like a Node (missing {attr})")
         self._target = value
 
     @property
     def length(self) -> float:
         """
-        .. :noindex:
-
         float: Length of the link (non-negative).
         """
         return self._length
@@ -142,4 +118,4 @@ class Link:
         """
         Return a string representation of the Link.
         """
-        return f"Link(id={self._id}, source={self._source.id}, target={self._target.id}, length={self._length})"
+        return f"Link(id={self._id}, source={self._source.id} ({self.source.name}), target={self._target.id} ({self.target.name}), length={self._length})"

topolib/elements/node.py

@@ -9,8 +9,6 @@ from typing import Tuple
 
 class Node:
     """
-    .. :noindex:
-
     Represents a node in an optical network topology.
 
     :param id: Unique identifier for the node.
@@ -219,3 +217,14 @@ class Node:
         :rtype: Tuple[float, float]
         """
         return self._latitude, self._longitude
+
+    def __repr__(self) -> str:
+        """Return a concise representation of the Node.
+
+        Includes id, name, latitude, longitude and additional attributes.
+        """
+        return (
+            f"Node(id={self._id}, name={self._name!r}, latitude={self._latitude}, "
+            f"longitude={self._longitude}, weight={self._weight}, pop={self._pop}, "
+            f"dc={self._dc}, ixp={self._ixp})"
+        )

topolib/topology/topology.py

@@ -10,12 +10,23 @@ https://github.com/networkx/networkx/blob/main/LICENSE.txt
 
 from typing import List, Optional, Any
 from numpy.typing import NDArray
-import numpy as np
-import networkx as nx
+
+
+# Standard library imports
 import json
-import jsonschema
 import csv
+from pathlib import Path
+
+# Third-party imports
+import numpy as np
 import networkx as nx
+import jsonschema
+import matplotlib.pyplot as plt
+import contextily as ctx
+import geopandas as gpd
+from shapely.geometry import Point
+
+# Local imports
 from topolib.elements.node import Node
 from topolib.elements.link import Link
 
@@ -144,7 +155,8 @@ class Topology:
         # Crear un dict para mapear id a Node
         node_dict = {n.id: n for n in nodes}
         links = [
-            Link(l["id"], node_dict[l["src"]], node_dict[l["dst"]], l["length"])
+            Link(l["id"], node_dict[l["src"]],
+                 node_dict[l["dst"]], l["length"])
             for l in data["links"]
         ]
         name = data.get("name", None)
@@ -217,40 +229,35 @@ class Topology:
 
     def export_to_json(self, file_path: str) -> None:
         """
-        Exporta la topología actual al formato JSON usado en la carpeta assets.
+        Export the current topology to the JSON format used in the assets folder.
 
-        :param file_path: Ruta donde se guardará el archivo JSON.
+        :param file_path: Path where the JSON file will be saved.
         :type file_path: str
 
-        **Ejemplo de uso**
-            >>> topo.export_to_json("/ruta/salida.json")
-
-        **Ejemplo de formato de salida**
-        {
-            "name": "Abilene",
-            "nodes": [
-                {
-                    "id": 0,
-                    "name": "Seattle",
-                    "weight": 0,
-                    "longitude": -122.3328481,
-                    "latitude": 47.6061389,
-                    "pop": 780995,
-                    "DC": 58,
-                    "IXP": 5
-                },
-                # ...
-            ],
-            "links": [
-                {
-                    "id": 0,
-                    "src": 0,
-                    "dst": 1,
-                    "length": 1482.26
-                },
-                # ...
-            ]
-        }
+        Example usage::
+
+            topo.export_to_json("/path/output.json")
+
+        Example output format::
+
+            {
+                "name": "Abilene",
+                "nodes": [
+                    {
+                        "id": 0,
+                        "name": "Seattle",
+                        ...
+                    }
+                ],
+                "links": [
+                    {
+                        "id": 0,
+                        "src": 0,
+                        "dst": 1,
+                        "length": 1482.26
+                    }
+                ]
+            }
         """
         nodes_list: list[dict[str, Any]] = []
         for n in self.nodes:
@@ -300,7 +307,8 @@ class Topology:
             writer = csv.writer(f)
             # Header
             writer.writerow(
-                ["id", "name", "weight", "latitude", "longitude", "pop", "DC", "IXP"]
+                ["id", "name", "weight", "latitude",
+                    "longitude", "pop", "DC", "IXP"]
             )
             for n in self.nodes:
                 writer.writerow(
@@ -376,21 +384,23 @@ class Topology:
         :param k: Number of shortest paths to compute for each node pair (default: 3).
         :type k: int
 
-        The output format matches Flex Net Sim's routes.json:
-        {
-            "name": self.name,
-            "alias": self.name,
-            "routes": [
-                {"src": <id>, "dst": <id>, "paths": [[id, ...], ...]},
-                ...
-            ]
-        }
+        Example output format::
+
+            {
+                "name": self.name,
+                "alias": self.name,
+                "routes": [
+                    {"src": <id>, "dst": <id>, "paths": [[id, ...], ...]},
+                    ...
+                ]
+            }
         """
 
         # Build a weighted graph using link length as edge weight
         G = nx.DiGraph()
         for l in self.links:
-            G.add_edge(l.source.id, l.target.id, weight=getattr(l, "length", 1))
+            G.add_edge(l.source.id, l.target.id,
+                       weight=getattr(l, "length", 1))
         routes = []
         node_ids = [n.id for n in self.nodes]
         for src in node_ids:
@@ -399,7 +409,8 @@ class Topology:
                     continue
                 try:
                     # Compute k shortest paths using link length as weight
-                    paths_gen = nx.shortest_simple_paths(G, src, dst, weight="weight")
+                    paths_gen = nx.shortest_simple_paths(
+                        G, src, dst, weight="weight")
                     paths = []
                     for i, path in enumerate(paths_gen):
                         if i >= k:
@@ -415,3 +426,88 @@ class Topology:
         }
         with open(file_path, "w", encoding="utf-8") as f:
             json.dump(data, f, indent=4, ensure_ascii=False)
+
+    @classmethod
+    def list_available_topologies(cls) -> list[dict]:
+        """
+        List available topologies in the assets folder.
+
+        Returns a list of dictionaries with keys:
+        - 'name': topology name (filename without extension)
+        - 'nodes': number of nodes
+        - 'links': number of links
+
+        :return: List of available topologies with metadata.
+        :rtype: list[dict]
+        """
+        asset_dir = Path(__file__).parent.parent / "assets"
+        result = []
+        for json_path in asset_dir.glob("*.json"):
+            try:
+                topo = cls.from_json(str(json_path))
+                result.append({
+                    "name": json_path.stem,
+                    "nodes": len(topo.nodes),
+                    "links": len(topo.links),
+                })
+            except Exception:
+                continue
+        return result
+
+    @staticmethod
+    def load_default_topology(name: str) -> "Topology":
+        """
+        Load a default topology from the assets folder by name (filename without extension).
+
+        :param name: Name of the topology asset (without .json extension)
+        :type name: str
+        :return: Topology instance loaded from the asset file
+        :rtype: Topology
+        :raises FileNotFoundError: If the asset file does not exist
+        """
+        asset_dir = Path(__file__).parent.parent / "assets"
+        asset_path = asset_dir / f"{name}.json"
+        if not asset_path.exists():
+            raise FileNotFoundError(
+                f"Topology asset '{name}.json' not found in assets directory.")
+        return Topology.from_json(str(asset_path))
+
+    def export_graph_png(self, filename: str, dpi: int = 150) -> None:
+        """
+        Export the topology graph as a PNG image using Matplotlib and Contextily.
+
+        :param filename: Output PNG file path.
+        :type filename: str
+        :param dpi: Dots per inch for the saved image (default: 150).
+        :type dpi: int
+        """
+        lons = [node.longitude for node in self.nodes]
+        lats = [node.latitude for node in self.nodes]
+        names = [node.name for node in self.nodes]
+        gdf = gpd.GeoDataFrame(
+            {"name": names},
+            geometry=[Point(x, y) for x, y in zip(lons, lats)],
+            crs="EPSG:4326",
+        )
+        gdf = gdf.to_crs(epsg=3857)
+        node_id_to_xy = {node.id: (pt.x, pt.y)
+                         for node, pt in zip(self.nodes, gdf.geometry)}
+        topo_name = self.name if self.name else "Topology"
+        fig, ax = plt.subplots(figsize=(10, 7))
+        fig.suptitle(topo_name, fontsize=16)
+        for link in self.links:
+            src_id = link.source.id
+            tgt_id = link.target.id
+            if src_id in node_id_to_xy and tgt_id in node_id_to_xy:
+                x0, y0 = node_id_to_xy[src_id]
+                x1, y1 = node_id_to_xy[tgt_id]
+                ax.plot([x0, x1], [y0, y1], color="gray",
+                        linewidth=1, alpha=0.7, zorder=2)
+        gdf.plot(ax=ax, color="blue", markersize=40, zorder=5)
+        for x, y, name in zip(gdf.geometry.x, gdf.geometry.y, gdf["name"]):
+            ax.text(x, y, name, fontsize=8, ha="right",
+                    va="bottom", color="black")
+        ax.set_axis_off()
+        plt.tight_layout()
+        plt.savefig(filename, dpi=dpi)
+        plt.close(fig)

topolib/visualization/mapview.py

@@ -4,30 +4,120 @@ MapView class for visualizing network topologies.
 This module provides visualization methods for Topology objects.
 """
 
-from typing import Any
+from typing import Any, Optional
 from topolib.topology import Topology
 import matplotlib.pyplot as plt
+from matplotlib.widgets import Button, TextBox
 import contextily as ctx
 import geopandas as gpd
 from shapely.geometry import Point
+import pyproj
+from topolib.elements.link import Link
+from topolib.elements.node import Node
+from matplotlib.widgets import Button as _ContButton
 
 
 class MapView:
+    def _add_zoom_buttons(self):
+        """Add custom zoom buttons to the figure.
+
+        Adds two small Matplotlib Button widgets to the figure to allow the
+        user to zoom in and out. The buttons are placed in figure coordinates
+        near the bottom-left corner.
+
+        This method mutates ``self._fig`` by adding new axes and stores the
+        created Button widgets on this instance.
+        """
+        # Zoom in button
+        zoomin_ax = self._fig.add_axes([0.01, 0.01, 0.08, 0.06])
+        self._zoomin_btn = Button(zoomin_ax, "+", color="lightgray", hovercolor="0.975")
+        self._zoomin_btn.on_clicked(self._on_zoom_in)
+
+        # Zoom out button
+        zoomout_ax = self._fig.add_axes([0.10, 0.01, 0.08, 0.06])
+        self._zoomout_btn = Button(
+            zoomout_ax, "-", color="lightgray", hovercolor="0.975"
+        )
+        self._zoomout_btn.on_clicked(self._on_zoom_out)
+
+    def _on_zoom_in(self, event):
+        """Zoom in one step.
+
+        This is a short wrapper that calls :meth:`_zoom` with a scale factor
+        greater than 1 to zoom into the map center.
+
+        :param event: Matplotlib click event (ignored).
+        :type event: matplotlib.backend_bases.Event
+        """
+        self._zoom(1.2)
+
+    def _on_zoom_out(self, event):
+        """Zoom out one step.
+
+        Wrapper for :meth:`_zoom` that uses a scale factor smaller than 1.
+
+        :param event: Matplotlib click event (ignored).
+        :type event: matplotlib.backend_bases.Event
+        """
+        self._zoom(1 / 1.2)
+
+    def _zoom(self, scale):
+        """Zoom the map by a scale factor while keeping the current center.
+
+        The method computes new axis limits that are scaled around the
+        current center of ``self._ax`` and triggers a redraw of the map
+        content via :meth:`_redraw_map`.
+
+        :param scale: Scale factor (>1 zooms in, <1 zooms out)
+        :type scale: float
+        """
+        xlim = self._ax.get_xlim()
+        ylim = self._ax.get_ylim()
+        xmid = (xlim[0] + xlim[1]) / 2
+        ymid = (ylim[0] + ylim[1]) / 2
+        xsize = (xlim[1] - xlim[0]) / scale
+        ysize = (ylim[1] - ylim[0]) / scale
+        new_xlim = [xmid - xsize / 2, xmid + xsize / 2]
+        new_ylim = [ymid - ysize / 2, ymid + ysize / 2]
+        self._redraw_map(xlim=new_xlim, ylim=new_ylim)
+
     """
     Provides visualization methods for Topology objects.
     """
 
     def __init__(self, topology: Topology) -> None:
-        """
-        Initialize MapView with a Topology object.
-        :param topology: Topology object
+        """Create a MapView instance for a :class:`topolib.topology.Topology`.
+
+        :param topology: Topology object to visualize and mutate.
+        :type topology: topolib.topology.Topology
         """
         self.topology = topology
+        # Interactive add node mode state
+        self._add_node_mode = False
+        self._add_node_button = None
+        self._cid_click = None
+        self._fig = None
+        self._ax = None
+        # Interactive add link mode state
+        self._add_link_mode = False
+        self._link_button = None
+        self._cid_link_click = None
+        self._link_start_node: Optional[object] = None
+        # Node form state
+        self._node_form_artists: list = []
+        # Artists used to show a provisional node on the map before confirmation
+        self._provisional_artists: list = []
 
     def show_map(self) -> None:
-        """
-        Show all nodes and links of the topology on an OpenStreetMap base using contextily and Matplotlib.
-        The figure and plot title will be the topology name if available.
+        """Render the interactive map window with nodes and links.
+
+        This method prepares a Matplotlib figure and axes, renders all
+        current nodes and links projected to Web Mercator (EPSG:3857), adds
+        a contextily basemap, and installs the interactive widgets for
+        adding nodes/links and zooming. The figure is displayed with
+        :func:`matplotlib.pyplot.show`.
+
+        :returns: None
         """
         lons: list[float] = [node.longitude for node in self.topology.nodes]
         lats: list[float] = [node.latitude for node in self.topology.nodes]
@@ -53,7 +143,19 @@ class MapView:
             topo_name = "Topology"
 
         fig, ax = plt.subplots(figsize=(10, 7))
+        self._fig = fig
+        self._ax = ax
+        # Continue flag used by the 'Continue' button to close the map and resume execution
+        self._continue_pressed = False
         fig.suptitle(topo_name, fontsize=16)
+        # Hide the default matplotlib toolbar for a cleaner UI
+        try:
+            fig.canvas.manager.toolbar.hide()
+        except Exception:
+            try:
+                fig.canvas.toolbar_visible = False
+            except Exception:
+                pass
         # Draw links as simple lines
         for link in getattr(self.topology, "links", []):
             src_id = getattr(link, "source").id
@@ -66,10 +168,668 @@ class MapView:
                 )
         # Draw nodes
         gdf.plot(ax=ax, color="blue", markersize=40, zorder=5)
+        for x, y, name in zip(gdf.geometry.x, gdf.geometry.y, gdf["name"]):
+            ax.text(
+                x,
+                y,
+                name,
+                fontsize=8,
+                ha="right",
+                va="bottom",
+                color="black",
+                clip_on=True,
+            )
+        ctx.add_basemap(ax, source=ctx.providers.OpenStreetMap.Mapnik)
+        ax.set_axis_off()
+        ax.set_title(f"Nodes and links ({topo_name})")
+        # plt.tight_layout()  # Removed to avoid warning with widgets
+
+        # Add interactive button for 'Add Node' mode
+        self._add_interactive_add_node_button()
+        # Add zoom in/out buttons
+        self._add_zoom_buttons()
+        # Add interactive button for 'Add Link' mode
+        self._add_interactive_add_link_button()
+        # Add continue button to close the map and continue execution
+        self._add_continue_button()
+        plt.show()
+
+    def _add_interactive_add_node_button(self):
+        """Create and attach the "Add Node" Button widget.
+
+        When clicked the button enables a one-shot mode where the next
+        click on the map will place a provisional marker and open the
+        node-edit dialog.
+        """
+        # Place button in a new axes
+        button_ax = self._fig.add_axes([0.81, 0.01, 0.15, 0.06])
+        self._add_node_button = Button(
+            button_ax, "Add Node", color="lightgray", hovercolor="0.975"
+        )
+        self._add_node_button.on_clicked(self._on_add_node_button_clicked)
+
+    def _add_interactive_add_link_button(self):
+        """Create and attach the "Add Link" Button widget.
+
+        When enabled the map will accept two node selections and will
+        create a bidirectional link (two Link objects) between them.
+        """
+        # Place button in a new axes (left of Add Node button)
+        link_ax = self._fig.add_axes([0.63, 0.01, 0.15, 0.06])
+        self._link_button = Button(
+            link_ax, "Add Link", color="lightgray", hovercolor="0.975"
+        )
+        self._link_button.on_clicked(self._on_add_link_button_clicked)
+
+    def _add_continue_button(self):
+        """Add a 'Continue' button.
+
+        The button closes the map window and allows the calling code to
+        continue executing (``show_map`` returns after the figure
+        window is closed via this button).
+        """
+        cont_ax = self._fig.add_axes([0.81, 0.08, 0.15, 0.06])
+
+        self._cont_button = _ContButton(
+            cont_ax, "Continue", color="lightgray", hovercolor="0.975"
+        )
+        self._cont_button.on_clicked(self._on_continue_clicked)
+
+    def _on_continue_clicked(self, event):
+        """Handle clicks on the Continue button.
+
+        Sets an internal flag and attempts to close the Matplotlib figure.
+
+        :param event: Matplotlib click event (ignored)
+        :type event: matplotlib.backend_bases.Event
+        """
+        self._continue_pressed = True
+        try:
+            plt.close(self._fig)
+        except Exception:
+            pass
+
+    def _on_add_link_button_clicked(self, event):
+        """Toggle the persistent "Add Link" mode.
+
+        When the mode is active the map will listen to clicks and allow the
+        user to select two nodes to create a link. The button's appearance
+        is changed to provide feedback about the active state.
+
+        :param event: Matplotlib click event (ignored)
+        :type event: matplotlib.backend_bases.Event
+        """
+        self._add_link_mode = not self._add_link_mode
+        if self._add_link_mode:
+            # connect click handler
+            if self._cid_link_click is None:
+                self._cid_link_click = self._fig.canvas.mpl_connect(
+                    "button_press_event", self._on_map_click_add_link
+                )
+            # visually mark button pressed by changing color
+            try:
+                self._link_button.color = "lightblue"
+            except Exception:
+                pass
+            self._link_start_node = None
+        else:
+            # disconnect handler
+            if self._cid_link_click is not None:
+                self._fig.canvas.mpl_disconnect(self._cid_link_click)
+                self._cid_link_click = None
+            try:
+                self._link_button.color = "lightgray"
+            except Exception:
+                pass
+            self._link_start_node = None
+
+    def _on_map_click_add_link(self, event):
+        """Handle map clicks while in "Add Link" mode.
+
+        The handler finds the nearest node to the click (within a tolerance)
+        and treats the first selection as a "start" node and the second
+        one as the "end" node. When both nodes are selected two Link
+        instances are created (forward and reverse) and added to the
+        topology. Link length is computed using geodesic distance (WGS84)
+        and stored in kilometers.
+
+        :param event: Matplotlib mouse event containing ``xdata``/``ydata``
+        :type event: matplotlib.backend_bases.MouseEvent
+        """
+        if not self._add_link_mode or event.inaxes != self._ax:
+            return
+        if event.xdata is None or event.ydata is None:
+            return
+
+        # We have projected coordinates in xdata,ydata (EPSG:3857)
+        click_x, click_y = event.xdata, event.ydata
+
+        # Build projected GeoDataFrame of nodes to find nearest
+        lons = [node.longitude for node in self.topology.nodes]
+        lats = [node.latitude for node in self.topology.nodes]
+        gdf_nodes = gpd.GeoDataFrame(
+            {"id": [n.id for n in self.topology.nodes]},
+            geometry=[Point(x, y) for x, y in zip(lons, lats)],
+            crs="EPSG:4326",
+        ).to_crs(epsg=3857)
+
+        # Find the nearest node within a tolerance (in meters/pixels depending on map scale).
+        # We'll use a simple distance-based tolerance (e.g., 10000 meters) but adjust if necessary.
+        tol = 100000  # meters in projected coordinates; conservative default
+        nearest = None
+        min_dist = float("inf")
+        for idx, geom in enumerate(gdf_nodes.geometry):
+            dx = geom.x - click_x
+            dy = geom.y - click_y
+            dist = (dx * dx + dy * dy) ** 0.5
+            if dist < min_dist and dist <= tol:
+                min_dist = dist
+                nearest = self.topology.nodes[idx]
+
+        if nearest is None:
+            # nothing clicked near a node
+            return
+
+        # If start node not selected yet, set it and highlight
+        if self._link_start_node is None:
+            self._link_start_node = nearest
+            # optionally highlight by drawing a red marker
+            self._ax.plot(
+                [gdf_nodes.geometry[self.topology.nodes.index(nearest)].x],
+                [gdf_nodes.geometry[self.topology.nodes.index(nearest)].y],
+                marker="o",
+                color="red",
+                markersize=12,
+                zorder=10,
+            )
+            self._fig.canvas.draw_idle()
+            return
+
+        # If start selected and clicked on a different node, create link
+        if nearest.id != self._link_start_node.id:
+            # determine new link ids (reserve two consecutive ids)
+            max_id = max([l.id for l in self.topology.links], default=0)
+            id1 = max_id + 1
+            id2 = max_id + 2
+
+            # compute geodesic distance between the two nodes (meters)
+            lon1 = self._link_start_node.longitude
+            lat1 = self._link_start_node.latitude
+            lon2 = nearest.longitude
+            lat2 = nearest.latitude
+            geod = pyproj.Geod(ellps="WGS84")
+            _, _, distance = geod.inv(lon1, lat1, lon2, lat2)
+            distance_km = distance / 1000.0
+
+            # create forward and reverse links with same length (in km)
+            new_link = Link(id1, self._link_start_node, nearest, distance_km)
+            new_link_rev = Link(id2, nearest, self._link_start_node, distance_km)
+            self.topology.add_link(new_link)
+            self.topology.add_link(new_link_rev)
+            # redraw map to show new links
+            self._redraw_map()
+
+        # Reset start node selection but keep add-link mode active until toggled
+        self._link_start_node = None
+
+    def _on_add_node_button_clicked(self, event):
+        """Enable "Add Node" mode and wait for a map click.
+
+        After this method runs, the next valid click inside the map axes
+        will place a provisional marker and open the node editor dialog.
+
+        :param event: Matplotlib click event (ignored)
+        :type event: matplotlib.backend_bases.Event
+        """
+        self._add_node_mode = True
+        # Connect click event if not already connected
+        if self._cid_click is None:
+            self._cid_click = self._fig.canvas.mpl_connect(
+                "button_press_event", self._on_map_click_add_node
+            )
+        # Now waiting for a click on the map to place the provisional marker and open the dialog
+
+    def _on_map_click_add_node(self, event):
+        """Handle a map click when in "Add Node" mode.
+
+        Places a provisional marker and label at the clicked position (in
+        Web Mercator coordinates), computes the corresponding longitude
+        and latitude and opens a modal dialog to edit the new node
+        attributes. The provisional marker is removed when the dialog is
+        closed (confirmed or cancelled).
+
+        :param event: Matplotlib mouse event (must have ``xdata`` and ``ydata``)
+        :type event: matplotlib.backend_bases.MouseEvent
+        """
+        if not self._add_node_mode or event.inaxes != self._ax:
+            return
+        if event.xdata is None or event.ydata is None:
+            return
+
+        # Convert from Web Mercator (EPSG:3857) to lon/lat (EPSG:4326)
+        proj_3857 = pyproj.CRS("EPSG:3857")
+        proj_4326 = pyproj.CRS("EPSG:4326")
+        transformer = pyproj.Transformer.from_crs(proj_3857, proj_4326, always_xy=True)
+        lon, lat = transformer.transform(event.xdata, event.ydata)
+
+        # Prepare default id and name
+        next_id = max([n.id for n in self.topology.nodes], default=0) + 1
+        default_name = f"new node {next_id}"
+
+        # Draw a provisional node marker and label on the map so the user sees it immediately
+        try:
+            marker_line = self._ax.plot(
+                [event.xdata],
+                [event.ydata],
+                marker="o",
+                color="green",
+                markersize=10,
+                zorder=20,
+            )[0]
+            txt = self._ax.text(
+                event.xdata,
+                event.ydata,
+                default_name,
+                fontsize=8,
+                ha="right",
+                va="bottom",
+                color="green",
+                zorder=21,
+            )
+            self._provisional_artists = [marker_line, txt]
+            try:
+                self._fig.canvas.draw()
+            except Exception:
+                try:
+                    self._fig.canvas.draw_idle()
+                except Exception:
+                    pass
+            # Give the GUI event loop a small chance to render the canvas so the provisional
+            # marker becomes visible before opening the modal tkinter dialog.
+            try:
+                plt.pause(0.05)
+            except Exception:
+                try:
+                    plt.pause(0.01)
+                except Exception:
+                    pass
+        except Exception:
+            self._provisional_artists = []
+
+        # Show interactive form to enter node details (prefill id, name, lon/lat)
+        self._show_node_form(
+            event.xdata,
+            event.ydata,
+            lon,
+            lat,
+            prefill_id=next_id,
+            prefill_name=default_name,
+        )
+
+        # After showing form, disable add-node mode (user must re-click button to add more)
+        self._add_node_mode = False
+        if self._cid_click is not None:
+            self._fig.canvas.mpl_disconnect(self._cid_click)
+            self._cid_click = None
+
+    def _close_node_form(self):
+        """Remove any Matplotlib widgets/axes used by the node form.
+
+        This method attempts to remove stored widget axes from the
+        figure (if any) and requests a canvas redraw.
+        """
+        for a in self._node_form_artists:
+            try:
+                a.remove()
+            except Exception:
+                pass
+        self._node_form_artists = []
+        try:
+            self._fig.canvas.draw_idle()
+        except Exception:
+            pass
+
+    def _show_node_form(
+        self,
+        x_proj,
+        y_proj,
+        lon_prefill,
+        lat_prefill,
+        prefill_id: Optional[int] = None,
+        prefill_name: Optional[str] = None,
+    ):
+        """Open a native tkinter modal dialog to edit node attributes.
+
+        This dialog is modal and will block until the user confirms or
+        cancels. The dialog is pre-filled with the provided longitude and
+        latitude and a suggested id and name. If the dialog is confirmed
+        a new :class:`topolib.elements.node.Node` is created and added to
+        the topology; otherwise the provisional marker is removed.
+
+        Note: tkinter must be available in the Python environment. On
+        many Linux distributions the package providing tkinter is called
+        ``python3-tk``.
+
+        :param x_proj: Click X coordinate in Web Mercator (EPSG:3857).
+        :param y_proj: Click Y coordinate in Web Mercator (EPSG:3857).
+        :param lon_prefill: Suggested longitude (EPSG:4326).
+        :param lat_prefill: Suggested latitude (EPSG:4326).
+        :param prefill_id: Suggested node id, if any.
+        :param prefill_name: Suggested node name, if any.
+        :returns: None
+        """
+        # Use a native tkinter modal dialog for reliable popup behavior across backends.
+        try:
+            import tkinter as tk
+
+            # Prepare defaults
+            if prefill_id is None:
+                prefill_id = max([n.id for n in self.topology.nodes], default=0) + 1
+            if prefill_name is None:
+                prefill_name = f"new node {prefill_id}"
+
+            root = tk.Tk()
+            root.withdraw()  # hide main root
+
+            dialog = tk.Toplevel(root)
+            dialog.title("Add node")
+            dialog.resizable(False, False)
+            dialog.grab_set()  # modal
+
+            # Labels and entries
+            tk.Label(dialog, text="ID").grid(
+                row=0, column=0, sticky="e", padx=6, pady=4
+            )
+            en_id = tk.Entry(dialog)
+            en_id.insert(0, str(prefill_id))
+            en_id.grid(row=0, column=1, padx=6, pady=4)
+
+            tk.Label(dialog, text="Name").grid(
+                row=1, column=0, sticky="e", padx=6, pady=4
+            )
+            en_name = tk.Entry(dialog)
+            en_name.insert(0, prefill_name)
+            en_name.grid(row=1, column=1, padx=6, pady=4)
+
+            tk.Label(dialog, text="Latitude").grid(
+                row=2, column=0, sticky="e", padx=6, pady=4
+            )
+            en_lat = tk.Entry(dialog)
+            en_lat.insert(0, str(lat_prefill))
+            en_lat.grid(row=2, column=1, padx=6, pady=4)
+
+            tk.Label(dialog, text="Longitude").grid(
+                row=3, column=0, sticky="e", padx=6, pady=4
+            )
+            en_lon = tk.Entry(dialog)
+            en_lon.insert(0, str(lon_prefill))
+            en_lon.grid(row=3, column=1, padx=6, pady=4)
+
+            # Additional node attributes (initialize to zero)
+            tk.Label(dialog, text="Weight").grid(
+                row=4, column=0, sticky="e", padx=6, pady=4
+            )
+            en_weight = tk.Entry(dialog)
+            en_weight.insert(0, "0")
+            en_weight.grid(row=4, column=1, padx=6, pady=4)
+
+            tk.Label(dialog, text="Pop").grid(
+                row=5, column=0, sticky="e", padx=6, pady=4
+            )
+            en_pop = tk.Entry(dialog)
+            en_pop.insert(0, "0")
+            en_pop.grid(row=5, column=1, padx=6, pady=4)
+
+            tk.Label(dialog, text="DC").grid(
+                row=6, column=0, sticky="e", padx=6, pady=4
+            )
+            en_dc = tk.Entry(dialog)
+            en_dc.insert(0, "0")
+            en_dc.grid(row=6, column=1, padx=6, pady=4)
+
+            tk.Label(dialog, text="IXP").grid(
+                row=7, column=0, sticky="e", padx=6, pady=4
+            )
+            en_ixp = tk.Entry(dialog)
+            en_ixp.insert(0, "0")
+            en_ixp.grid(row=7, column=1, padx=6, pady=4)
+
+            result = {"ok": False}
+
+            def on_confirm():
+                try:
+                    nid = int(en_id.get().strip())
+                    name = en_name.get().strip() or f"new node {nid}"
+                    lat = float(en_lat.get().strip())
+                    lon = float(en_lon.get().strip())
+                except Exception:
+                    # invalid input: ignore (or add dialog message)
+                    return
+                # parse additional attributes, default to 0 on parse error
+                try:
+                    weight = float(en_weight.get().strip())
+                except Exception:
+                    weight = 0
+                try:
+                    pop = int(en_pop.get().strip())
+                except Exception:
+                    pop = 0
+                try:
+                    dc = int(en_dc.get().strip())
+                except Exception:
+                    dc = 0
+                try:
+                    ixp = int(en_ixp.get().strip())
+                except Exception:
+                    ixp = 0
+
+                # Check id uniqueness
+                if any(n.id == nid for n in self.topology.nodes):
+                    return
+                # Create and add node with additional attributes
+                new_node = Node(nid, name, lat, lon, weight, pop, dc, ixp)
+                self.topology.add_node(new_node)
+                result.update({"ok": True})
+                dialog.destroy()
+
+            def on_cancel():
+                dialog.destroy()
+
+            btn_frame = tk.Frame(dialog)
+            btn_frame.grid(row=8, column=0, columnspan=2, pady=(4, 8))
+            tk.Button(btn_frame, text="Confirm", command=on_confirm, bg="#9fdf9f").pack(
+                side="left", padx=6
+            )
+            tk.Button(btn_frame, text="Cancel", command=on_cancel).pack(
+                side="right", padx=6
+            )
+
+            # Center the dialog relative to the main figure window if possible
+            try:
+                mgr = getattr(self._fig.canvas, "manager", None)
+                if mgr is not None:
+                    win = getattr(mgr, "window", None)
+                    if win is not None and hasattr(win, "winfo_rootx"):
+                        # For TkAgg integration, position near the plot window
+                        try:
+                            x = win.winfo_rootx() + 50
+                            y = win.winfo_rooty() + 50
+                            dialog.geometry(f"+{x}+{y}")
+                            # make dialog transient/child of the plot window and lift it
+                            try:
+                                dialog.transient(win)
+                                dialog.lift()
+                                dialog.attributes("-topmost", True)
+                                dialog.attributes("-topmost", False)
+                            except Exception:
+                                try:
+                                    dialog.lift()
+                                except Exception:
+                                    pass
+                        except Exception:
+                            pass
+            except Exception:
+                pass
+
+            root.wait_window(dialog)
+            try:
+                root.destroy()
+            except Exception:
+                pass
+
+            # If the dialog confirmed and node added, redraw map
+            if result.get("ok"):
+                try:
+                    # clear provisional artists (they will be redrawn from topology)
+                    for a in self._provisional_artists:
+                        try:
+                            a.remove()
+                        except Exception:
+                            pass
+                    self._provisional_artists = []
+                except Exception:
+                    pass
+                try:
+                    self._redraw_map()
+                except Exception:
+                    pass
+            else:
+                # user cancelled: remove provisional marker and redraw to erase it
+                try:
+                    for a in self._provisional_artists:
+                        try:
+                            a.remove()
+                        except Exception:
+                            pass
+                    self._provisional_artists = []
+                except Exception:
+                    pass
+                try:
+                    self._fig.canvas.draw()
+                except Exception:
+                    try:
+                        self._fig.canvas.draw_idle()
+                    except Exception:
+                        pass
+            return
+        except Exception:
+            # Fallback: do nothing if tkinter not available
+            return
+
+    def _redraw_map(self, xlim=None, ylim=None):
+        """Redraw the map content (nodes and links) on the existing axes.
+
+        The axes are cleared and nodes/links are re-plotted from the
+        current topology. Optionally, axis limits can be supplied so the
+        view is preserved after redraw.
+
+        :param xlim: Optional 2-tuple with x-axis limits in projected units.
+        :type xlim: Optional[tuple(float, float)]
+        :param ylim: Optional 2-tuple with y-axis limits in projected units.
+        :type ylim: Optional[tuple(float, float)]
+        :returns: None
+        """
+        # geopandas, shapely Point and contextily already imported at module level
+
+        # Clear axes
+        self._ax.clear()
+        if xlim is not None:
+            self._ax.set_xlim(xlim)
+        if ylim is not None:
+            self._ax.set_ylim(ylim)
+        lons = [node.longitude for node in self.topology.nodes]
+        lats = [node.latitude for node in self.topology.nodes]
+        names = [node.name for node in self.topology.nodes]
+        gdf = gpd.GeoDataFrame(
+            {"name": names},
+            geometry=[Point(x, y) for x, y in zip(lons, lats)],
+            crs="EPSG:4326",
+        )
+        gdf = gdf.to_crs(epsg=3857)
+        node_id_to_xy = {
+            node.id: (pt.x, pt.y) for node, pt in zip(self.topology.nodes, gdf.geometry)
+        }
+        topo_name = getattr(self.topology, "name", None)
+        if topo_name is None:
+            topo_name = getattr(self.topology, "_name", None)
+        if topo_name is None:
+            topo_name = "Topology"
+        # Draw links
+        for link in getattr(self.topology, "links", []):
+            src_id = getattr(link, "source").id
+            tgt_id = getattr(link, "target").id
+            if src_id in node_id_to_xy and tgt_id in node_id_to_xy:
+                x0, y0 = node_id_to_xy[src_id]
+                x1, y1 = node_id_to_xy[tgt_id]
+                self._ax.plot(
+                    [x0, x1], [y0, y1], color="gray", linewidth=1, alpha=0.7, zorder=2
+                )
+        # Draw nodes
+        gdf.plot(ax=self._ax, color="blue", markersize=40, zorder=5)
+        for x, y, name in zip(gdf.geometry.x, gdf.geometry.y, gdf["name"]):
+            self._ax.text(
+                x,
+                y,
+                name,
+                fontsize=8,
+                ha="right",
+                va="bottom",
+                color="black",
+                clip_on=True,
+            )
+        ctx.add_basemap(self._ax, source=ctx.providers.OpenStreetMap.Mapnik)
+        self._ax.set_axis_off()
+        self._ax.set_title(f"Nodes and links ({topo_name})")
+        self._fig.suptitle(topo_name, fontsize=16)
+        # self._fig.tight_layout()  # Removed to avoid warning with widgets
+        self._fig.canvas.draw_idle()
+
+    def export_map_png(self, filename: str, dpi: int = 150) -> None:
+        """
+        Export the topology map as a PNG image using Matplotlib and Contextily.
+
+        :param filename: Output PNG file path.
+        :type filename: str
+        :param dpi: Dots per inch for the saved image (default: 150).
+        :type dpi: int
+        """
+        lons: list[float] = [node.longitude for node in self.topology.nodes]
+        lats: list[float] = [node.latitude for node in self.topology.nodes]
+        names: list[str] = [node.name for node in self.topology.nodes]
+        gdf: gpd.GeoDataFrame = gpd.GeoDataFrame(
+            {"name": names},
+            geometry=[Point(x, y) for x, y in zip(lons, lats)],
+            crs="EPSG:4326",
+        )
+        gdf = gdf.to_crs(epsg=3857)
+
+        node_id_to_xy = {
+            node.id: (pt.x, pt.y) for node, pt in zip(self.topology.nodes, gdf.geometry)
+        }
+
+        topo_name = getattr(self.topology, "name", None)
+        if topo_name is None:
+            topo_name = getattr(self.topology, "_name", None)
+        if topo_name is None:
+            topo_name = "Topology"
+
+        fig, ax = plt.subplots(figsize=(10, 7))
+        fig.suptitle(topo_name, fontsize=16)
+        for link in getattr(self.topology, "links", []):
+            src_id = getattr(link, "source").id
+            tgt_id = getattr(link, "target").id
+            if src_id in node_id_to_xy and tgt_id in node_id_to_xy:
+                x0, y0 = node_id_to_xy[src_id]
+                x1, y1 = node_id_to_xy[tgt_id]
+                ax.plot(
+                    [x0, x1], [y0, y1], color="gray", linewidth=1, alpha=0.7, zorder=2
+                )
+        gdf.plot(ax=ax, color="blue", markersize=40, zorder=5)
         for x, y, name in zip(gdf.geometry.x, gdf.geometry.y, gdf["name"]):
             ax.text(x, y, name, fontsize=8, ha="right", va="bottom", color="black")
         ctx.add_basemap(ax, source=ctx.providers.OpenStreetMap.Mapnik)
         ax.set_axis_off()
         ax.set_title(f"Nodes and links ({topo_name})")
         plt.tight_layout()
-        plt.show()
+        plt.savefig(filename, dpi=dpi)
+        plt.close(fig)

{topolib-0.5.0.dist-info → topolib-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: topolib
-Version: 0.5.0
+Version: 0.7.0
 Summary: A compact Python library for modeling, analyzing, and visualizing optical network topologies.
 License: MIT
 License-File: LICENSE
@@ -31,7 +31,6 @@ Project-URL: Homepage, https://gitlab.com/DaniloBorquez/topolib
 Project-URL: Repository, https://gitlab.com/DaniloBorquez/topolib
 Description-Content-Type: text/markdown
 
-# Topolib 🚀
 # Topolib 🚀
 
 [![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)
@@ -50,8 +49,12 @@ Description-Content-Type: text/markdown
 
 ## 📂 Examples
 
-Explore ready-to-run usage examples in the [`examples/`](examples/) folder!  
-- [Show topology on a map](examples/show_topology_in_map.py) 🗺️  
+
+Explore ready-to-run usage examples in the [`examples/`](examples/) folder!
+
+- [Show topology on a map](examples/show_topology_in_map.py) 🗺️
+- [Show default topology in map](examples/show_default_topology_in_map.py) 🗺️
+- [Export topology as PNG](examples/export_topology_png.py) 🖼️
 - [Export topology to CSV and JSON](examples/export_csv_json.py) 📄
 - [Export topology and k-shortest paths for FlexNetSim](examples/export_flexnetsim.py) 🔀
 

{topolib-0.5.0.dist-info → topolib-0.7.0.dist-info}/RECORD

@@ -33,15 +33,15 @@ topolib/assets/Telefonica-21.json,sha256=Wom5SQn3lLL-z-ESZ3Du_Fz_ZQ2bzP2_bNhzmnm
 topolib/assets/Turk_Telekom.json,sha256=5yO0cgtJOmh6ulCCIb8g_nDFSmv8Wn52Yt_Oyoc1Y0w,11533
 topolib/assets/UKNet.json,sha256=9BEkRM9YFeMMpih5kyDY34TsOGFzt5KBGsmgWd6KoB0,14210
 topolib/assets/Vega_Telecom.json,sha256=E07ZCvG4exRj1a5DV8lqS3Sdo5tRm_Lc07IzIjP2EW0,17324
-topolib/elements/__init__.py,sha256=ZWSd5uwVtppJtMnZ30zrAdzXhUAYIK62RrUaH9rsWu0,180
-topolib/elements/link.py,sha256=BwjdCR8peh7dDpKunZodlIsjKcfvwjKxyQ3tmp1obb8,3778
-topolib/elements/node.py,sha256=uOnljwA3jcVR4utUfI-om4SIt_QBsEQt8QLW9uvjr3Y,4974
+topolib/elements/__init__.py,sha256=RIQGFgI3_R7Saf679LaP8o8D8kVtM-JadZt6XufJcQ4,75
+topolib/elements/link.py,sha256=2YDEkKdCt91Nv8oiv6gfyECWoeYQaShyhi5DGRvKN2o,3376
+topolib/elements/node.py,sha256=ytxxYvIV9kcsnEV8R0IEFpaXT3-cL5g-djcSkcesBOI,5374
 topolib/topology/__init__.py,sha256=2VRhVm4ZvKBiTDB2T8BDmLZBpwGCVFRF3fvtxxC_d28,86
 topolib/topology/path.py,sha256=oUNwmpBcS6LMMAJIxokROm3MVqr7vRR44M3Fh5ADq_w,2057
-topolib/topology/topology.py,sha256=pRmbn8vaFh35Fi0dtSy-fl_3VNVz6MqW-iqfeh3BvPw,14896
+topolib/topology/topology.py,sha256=LfMfBtxCu8GIJJG3Dmmw_hIQwDWDTeDA31zwOpBcVnc,18354
 topolib/visualization/__init__.py,sha256=wv065-KB5uDbTaQIASPVfMMW5sE76Bs-q0oai48vAzk,29
-topolib/visualization/mapview.py,sha256=4iKJMYsH6oFNj9tOcgSKLVRtoYfUuH3XLjShsGwUXcM,2799
-topolib-0.5.0.dist-info/METADATA,sha256=8jZNgjgAyWsX3d63Lxo5bI6T6JDCAmKUbu_PQ2svtXM,4169
-topolib-0.5.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
-topolib-0.5.0.dist-info/licenses/LICENSE,sha256=kbnIP0XU6f2ualiTjEawdlU81IGPBbwc-_GF3N-1e9E,1081
-topolib-0.5.0.dist-info/RECORD,,
+topolib/visualization/mapview.py,sha256=7oZsA0Dam8DJfS_59Csvi1y68Do142D44zj9vIS9PBg,32631
+topolib-0.7.0.dist-info/METADATA,sha256=U-fMdGPorQ-CoAu3I1tbt36UHIiW7xnolmPFFhDnGE4,4303
+topolib-0.7.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+topolib-0.7.0.dist-info/licenses/LICENSE,sha256=kbnIP0XU6f2ualiTjEawdlU81IGPBbwc-_GF3N-1e9E,1081
+topolib-0.7.0.dist-info/RECORD,,