multimodalrouter 0.1.4__py3-none-any.whl → 0.1.5__py3-none-any.whl

multimodalrouter/graph/dataclasses.py

@@ -50,6 +50,7 @@ class Hub:
         self.coords: list[float] = coords
         self.id = id
         self.hubType = hubType
+        # dict like {mode -> {dest_id -> EdgeMetadata}}
         self.outgoing: dict[str, dict[str, EdgeMetadata]] = {}
 
     def addOutgoing(self, mode: str, dest_id: str, metrics: EdgeMetadata):

multimodalrouter/graphics/__init__.py

@@ -0,0 +1 @@
+from .graphicsWrapper import GraphDisplay # noqa: F401

multimodalrouter/graphics/graphicsWrapper.py

@@ -0,0 +1,323 @@
+# dataclasses.py
+# Copyright (c) 2025 Tobias Karusseit
+# Licensed under the MIT License. See LICENSE file in the project root for full license information.
+
+
+from ..graph import RouteGraph
+import plotly.graph_objects as go
+
+
+class GraphDisplay():
+
+    def __init__(self, graph: RouteGraph, name: str = "Graph", iconSize: int = 10) -> None:
+        self.graph: RouteGraph = graph
+        self.name: str = name
+        self.iconSize: int = iconSize
+
+    def _toPlotlyFormat(
+        self,
+        nodeTransform=None,
+        edgeTransform=None
+    ):
+        """
+        transform the graph data into plotly format.to use the display function
+
+        args:
+            - nodeTransform: function to transform the node coordinates (default = None)
+            - edgeTransform: function to transform the edge coordinates (default = None)
+        returns:
+            - None (modifies self.nodes and self.edges)
+        """
+        self.nodes = {
+            f"{hub.hubType}-{hub.id}": {
+                "coords": hub.coords,
+                "hubType": hub.hubType,
+                "id": hub.id
+            }
+            for hub in self.graph._allHubs()
+        }
+
+        self.edges = [
+            {
+                "from": f"{hub.hubType}-{hub.id}",
+                "to": f"{self.graph.getHubById(dest).hubType}-{dest}",
+                **edge.allMetrics
+            }
+            for hub in self.graph._allHubs()
+            for _, edge in hub.outgoing.items()
+            for dest, edge in edge.items()
+        ]
+        self.dim = max(len(node.get("coords")) for node in self.nodes.values())
+
+        if nodeTransform is not None:
+            expandedCoords = [node.get("coords") + [0] * (self.dim - len(node.get("coords"))) for node in self.nodes.values()]
+            transformedCoords = nodeTransform(expandedCoords)
+            for node, coords in zip(self.nodes.values(), transformedCoords):
+                node["coords"] = coords
+
+            self.dim = max(len(node.get("coords")) for node in self.nodes.values())
+
+        if edgeTransform is not None:
+            starts = [edge["from"] for edge in self.edges]
+            startCoords = [self.nodes[start]["coords"] for start in starts]
+            ends = [edge["to"] for edge in self.edges]
+            endCoords = [self.nodes[end]["coords"] for end in ends]
+
+            transformedEdges = edgeTransform(startCoords, endCoords)
+            for edge, transformedEdge in zip(self.edges, transformedEdges):
+                edge["curve"] = transformedEdge
+
+    def display(
+        self,
+        nodeTransform=None,
+        edgeTransform=None,
+        displayEarth=False
+    ):
+        """
+        function to display any 2D or 3D RouteGraph
+
+        args:
+            - nodeTransform: function to transform the node coordinates (default = None)
+            - edgeTransform: function to transform the edge coordinates (default = None)
+            - displayEarth: whether to display the earth as a background (default = False, only in 3D)
+
+        returns:
+            - None (modifies self.nodes and self.edges opens the plot in a browser)
+
+        """
+        # transform the graph
+        self._toPlotlyFormat(nodeTransform, edgeTransform)
+        # init plotly placeholders
+        node_x, node_y, node_z, text, colors = [], [], [], [], []
+        edge_x, edge_y, edge_z, edge_text = [], [], [], []
+
+        # add all the nodes
+        for node_key, node_data in self.nodes.items():
+            x, y, *rest = node_data["coords"]
+            node_x.append(x)
+            node_y.append(y)
+            if self.dim == 3:
+                node_z.append(node_data["coords"][2])
+            text.append(f"{node_data['id']}<br>Type: {node_data['hubType']}")
+            colors.append(hash(node_data['hubType']) % 10)
+
+        # add all the edges
+        for edge in self.edges:
+            # check if edge has been transformed
+            if "curve" in edge:
+                curve = edge["curve"]
+                # add all the points of the edge
+                for point in curve:
+                    edge_x.append(point[0])
+                    edge_y.append(point[1])
+                    if self.dim == 3:
+                        edge_z.append(point[2])
+                edge_x.append(None)
+                edge_y.append(None)
+                # if 3d add the extra none to close the edge
+                if self.dim == 3:
+                    edge_z.append(None)
+            else:
+                source = self.nodes[edge["from"]]["coords"]
+                target = self.nodes[edge["to"]]["coords"]
+
+                edge_x += [source[0], target[0], None]
+                edge_y += [source[1], target[1], None]
+
+                if self.dim == 3:
+                    edge_z += [source[2], target[2], None]
+
+            # add text and hover display
+            hover = f"{edge['from']} → {edge['to']}"
+            metrics = {k: v for k, v in edge.items() if k not in ("from", "to", "curve")}
+            if metrics:
+                hover += "<br>" + "<br>".join(f"{k}: {v}" for k, v in metrics.items())
+            edge_text.append(hover)
+
+        if self.dim == 2:
+            # ceate the plot in 2d
+            node_trace = go.Scatter(
+                x=node_x,
+                y=node_y,
+                mode="markers",
+                hoverinfo="text",
+                text=text,
+                marker=dict(
+                    size=self.iconSize,
+                    color=colors,
+                    colorscale="Viridis",
+                    showscale=True
+                )
+            )
+
+            edge_trace = go.Scatter(
+                x=edge_x,
+                y=edge_y,
+                line=dict(width=2, color="#888"),
+                hoverinfo="text",
+                text=edge_text,
+                mode="lines"
+            )
+
+        elif self.dim == 3:
+            # create the plot in 3d
+            node_trace = go.Scatter3d(
+                x=node_x,
+                y=node_y,
+                z=node_z,
+                mode="markers",
+                hoverinfo="text",
+                text=text,
+                marker=dict(
+                    size=self.iconSize,
+                    color=colors,
+                    colorscale="Viridis",
+                    showscale=True
+                )
+            )
+
+            edge_trace = go.Scatter3d(
+                x=edge_x,
+                y=edge_y,
+                z=edge_z,
+                line=dict(width=1, color="#888"),
+                hoverinfo="text",
+                text=edge_text,
+                mode="lines",
+                opacity=0.6
+            )
+
+        # create the plotly figure
+        fig = go.Figure(data=[edge_trace, node_trace])
+        # render earth / sphere in 3d
+        if self.dim == 3 and displayEarth:
+            try:
+                import numpy as np
+                R = 6369.9  # sphere radius
+                u = np.linspace(0, 2 * np.pi, 50)   # azimuthal angle
+                v = np.linspace(0, np.pi, 50)       # polar angle
+                u, v = np.meshgrid(u, v)
+
+                # Cartesian coordinates
+                x = R * np.cos(u) * np.sin(v)
+                y = R * np.sin(u) * np.sin(v)
+                z = R * np.cos(v)
+            except ImportError:
+                raise ImportError("numpy is required to display the earth")
+
+            sphere_surface = go.Surface(
+                x=x, y=y, z=z,
+                colorscale='Blues',
+                opacity=1,
+                showscale=False,
+                hoverinfo='skip'
+            )
+
+            fig.add_trace(sphere_surface)
+
+        fig.update_layout(title="Interactive Graph", showlegend=False, hovermode="closest")
+        fig.show()
+
+    @staticmethod
+    def degreesToCartesian3D(coords):
+        try:
+            import torch
+            C = torch.tensor(coords)
+            if C.dim() == 1:
+                C = C.unsqueeze(0)
+            R = 6371.0
+            lat = torch.deg2rad(C[:, 0])
+            lng = torch.deg2rad(C[:, 1])
+            x = R * torch.cos(lat) * torch.cos(lng)
+            y = R * torch.cos(lat) * torch.sin(lng)
+            z = R * torch.sin(lat)
+            return list(torch.stack((x, y, z), dim=1).numpy())
+        except ImportError:
+            import math
+            R = 6371.0
+            output = []
+            for lat, lng in coords:
+                lat = math.radians(lat)
+                lng = math.radians(lng)
+                x = R * math.cos(lat) * math.cos(lng)
+                y = R * math.cos(lat) * math.sin(lng)
+                z = R * math.sin(lat)
+                output.append([x, y, z])
+            return output
+
+    @staticmethod
+    def curvedEdges(start, end, R=6371.0, H=0.05, n=20):
+        try:
+            # if torch and np are available calc vectorized graeter circle curves
+            import numpy as np
+            import torch
+
+            device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+
+            start_np = np.array(start, dtype=np.float32)
+            end_np = np.array(end, dtype=np.float32)
+
+            start = torch.tensor(start_np, device=device)
+            end = torch.tensor(end_np, device=device)
+            start = start.float()
+            end = end.float()
+
+            # normalize to sphere
+            start_norm = R * start / start.norm(dim=1, keepdim=True)
+            end_norm = R * end / end.norm(dim=1, keepdim=True)
+
+            # compute angle between vectors
+            dot = (start_norm * end_norm).sum(dim=1, keepdim=True) / (R**2)
+            dot = torch.clamp(dot, -1.0, 1.0)
+            theta = torch.acos(dot).unsqueeze(2)  # shape: (num_edges,1,1)
+
+            # linear interpolation along great circle
+            t = torch.linspace(0, 1, n, device=device).view(1, n, 1)
+            one_minus_t = 1 - t
+            sin_theta = torch.sin(theta)
+            sin_theta[sin_theta == 0] = 1e-6
+
+            factor_start = torch.sin(one_minus_t * theta) / sin_theta
+            factor_end = torch.sin(t * theta) / sin_theta
+
+            curve = factor_start * start_norm.unsqueeze(1) + factor_end * end_norm.unsqueeze(1)
+
+            # normalize to radius
+            curve = R * curve / curve.norm(dim=2, keepdim=True)
+
+            # apply radial lift at curve center using sin weight
+            weight = torch.sin(torch.pi * t)  # 0 at endpoints, 1 at center
+            curve = curve * (1 + H * weight)
+
+            return curve
+        except ImportError:
+            # fallback to calculating quadratic bezier curves with math
+            import math
+            curves_all = []
+
+            def multiply_vec(vec, factor):
+                return [factor * x for x in vec]
+
+            def add_vec(*vecs):
+                return [sum(items) for items in zip(*vecs)]
+
+            for startP, endP in zip(start, end):
+                mid = [(s + e) / 2 for s, e in zip(startP, endP)]
+                norm = math.sqrt(sum(c ** 2 for c in mid))
+                mid_proj = [R * c / norm for c in mid]
+                mid_arch = [c * (1 + H) for c in mid_proj]
+
+                curve = []
+                for i in range(n):
+                    t_i = i / (n - 1)
+                    one_minus_t = 1 - t_i
+                    point = add_vec(
+                        multiply_vec(startP, one_minus_t ** 2),
+                        multiply_vec(mid_arch, 2 * one_minus_t * t_i),
+                        multiply_vec(endP, t_i ** 2)
+                    )
+                    curve.append(point)
+
+                curves_all.append(curve)
+
+            return curves_all

{multimodalrouter-0.1.4.dist-info → multimodalrouter-0.1.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: multimodalrouter
-Version: 0.1.4
+Version: 0.1.5
 Summary: A graph-based routing library for dynamic routing.
 Author-email: Tobias Karusseit <karusseittobi@gmail.com>
 License: MIT License
@@ -19,6 +19,7 @@ Project-URL: Repository, https://github.com/K-T0BIAS/MultiModalRouter
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE.md
+License-File: NOTICE.md
 Requires-Dist: colorama>=0.4.6
 Requires-Dist: dill>=0.4.0
 Requires-Dist: filelock>=3.19.1
@@ -45,14 +46,15 @@ Provides-Extra: torch
 Requires-Dist: torch>=2.8.0; extra == "torch"
 Provides-Extra: dev
 Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: plotly>=6.3.0; extra == "dev"
+Provides-Extra: plotly
+Requires-Dist: plotly>=6.3.0; extra == "plotly"
 Dynamic: license-file
 
 # Multi Modal Router
 
 The Multi Modal Router is a graph-based routing engine that allows you to build and query any hub-based network. It supports multiple transport modes like driving, flying, or shipping, and lets you optimize routes by distance, time, or custom metrics. It can be expanded to any n-dimensional space making it versatile in any coordinate space
 
-> NEWS: v0.1.3 now on pypi ([installation guide](./docs/installation.md))
-
 > NOTE: This project is a work in progress and features might be added and or changed
 
 # In depth Documentation
@@ -97,6 +99,12 @@ The graph can be build from any data aslong as the required fields are present (
 
 ![example from the maze solver](./docs/solvedMaze1.png)
 
+## graph visualizations
+
+Use the build-in [visualization](./docs/visualization.md) tool to plot any `2D` or `3D` Graph.
+
+![example plot of flight paths](./docs/FlightPathPlot.png)
+
 ## Important considerations for your usecase
 
 Depending on your usecase and datasets some features may not be usable see solutions below
@@ -118,4 +126,6 @@ Depending on your usecase and datasets some features may not be usable see solut
 
 [see here](./LICENSE.md)
 
+[dependencies](./NOTICE.md)
+
 

{multimodalrouter-0.1.4.dist-info → multimodalrouter-0.1.5.dist-info}/RECORD

@@ -1,15 +1,18 @@
 multimodalrouter/__init__.py,sha256=Kva-wGkYdCi4GveSLe6emkTjd13C3K_ynhihADTQxZY,256
 multimodalrouter/graph/__init__.py,sha256=zvKvSpZ8PbuOpG6DL14CJPV34ZLYderNJV4Amw1jsLI,150
-multimodalrouter/graph/dataclasses.py,sha256=HC8oyaiM6IjgB4uAh9ybxCa8bNsasSQes_m8xgZLyXE,4407
+multimodalrouter/graph/dataclasses.py,sha256=-vCA3VRGBeLTEOZpYyYrGM5O24jnGRS36eGwZWDKISQ,4464
 multimodalrouter/graph/graph.py,sha256=k20ynHXPwVdZcjjp8a3dzCOuEHBPtEjnpauHtcvry9Y,23314
+multimodalrouter/graphics/__init__.py,sha256=F_KttIwUySzJs_C9OCDR2Zptu-tsuaF3gauSZyZyimo,56
+multimodalrouter/graphics/graphicsWrapper.py,sha256=8k6XidKINOVpe7sPQqjGkRNVsYgS78_ex4l-4iKCFGk,11850
 multimodalrouter/router/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 multimodalrouter/router/build.py,sha256=jrGcFyVS7-Qg6CXAVVwiXM_krLBHBoRH85Slknmutns,2843
 multimodalrouter/router/route.py,sha256=5RZGFgrTYm930RJX6i26d8f8_k7CGnp5lKZJBM1gcKk,1956
 multimodalrouter/utils/__init__.py,sha256=jsZ7cBB-9otxzMiN9FVviGuknxnOPmaG2RBbZuiezeg,53
 multimodalrouter/utils/preprocessor.py,sha256=45ya0cg0PGCV3YMk680_HZUve1QGJ7JHPSHoRvYdleY,6333
-multimodalrouter-0.1.4.dist-info/licenses/LICENSE.md,sha256=CRtvaQsLnzHvSIzusV5sHHw-e8w8gytXq8R7AP1GBmE,1092
-multimodalrouter-0.1.4.dist-info/METADATA,sha256=LThCkDktNOaUhROpecvapLoXZxT8BZHvrhCTbsIA4LY,6048
-multimodalrouter-0.1.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-multimodalrouter-0.1.4.dist-info/entry_points.txt,sha256=vp177Z2KMWPGJkS_dVpX05LVtBYssdlyYhTCG0kYmjo,138
-multimodalrouter-0.1.4.dist-info/top_level.txt,sha256=4RYMG9hyl8mDNJ_gTrlh8QdYjZNXLDBzFVK1PcTpAYg,17
-multimodalrouter-0.1.4.dist-info/RECORD,,
+multimodalrouter-0.1.5.dist-info/licenses/LICENSE.md,sha256=CRtvaQsLnzHvSIzusV5sHHw-e8w8gytXq8R7AP1GBmE,1092
+multimodalrouter-0.1.5.dist-info/licenses/NOTICE.md,sha256=Fv3AK0KmlZGgmf0_4yM8ZtOTbv2mIfQVHQkZ4hFZXb8,3313
+multimodalrouter-0.1.5.dist-info/METADATA,sha256=gjV64EK-1p_dUxfW02Y0bJqEbzpvAx4GNU6xvQ74vek,6333
+multimodalrouter-0.1.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+multimodalrouter-0.1.5.dist-info/entry_points.txt,sha256=vp177Z2KMWPGJkS_dVpX05LVtBYssdlyYhTCG0kYmjo,138
+multimodalrouter-0.1.5.dist-info/top_level.txt,sha256=4RYMG9hyl8mDNJ_gTrlh8QdYjZNXLDBzFVK1PcTpAYg,17
+multimodalrouter-0.1.5.dist-info/RECORD,,

multimodalrouter-0.1.5.dist-info/licenses/NOTICE.md

@@ -0,0 +1,44 @@
+# Dependencies and Licenses
+
+This project `MultiModalRouter` depends on the following libraries. All licenses are permissive and compatible with MIT licensing for this project.  
+
+| Package | Version | License | License Link |
+|---------|---------|---------|--------------|
+| colorama | >=0.4.6 | BSD 3-Clause | [License](https://github.com/tartley/colorama/blob/master/LICENSE) |
+| dill | >=0.4.0 | BSD | [License](https://github.com/uqfoundation/dill/blob/main/LICENSE) |
+| filelock | >=3.19.1 | MIT | [License](https://github.com/tox-dev/py-filelock/blob/main/LICENSE) |
+| fsspec | >=2025.9.0 | Apache 2.0 | [License](https://github.com/fsspec/filesystem_spec/blob/main/LICENSE) |
+| Jinja2 | >=3.1.6 | BSD-3-Clause | [License](https://github.com/pallets/jinja/blob/main/LICENSE) |
+| MarkupSafe | >=3.0.2 | BSD-3-Clause | [License](https://github.com/pallets/markupsafe/blob/main/LICENSE) |
+| mpmath | >=1.3.0 | BSD | [License](https://github.com/fredrik-johansson/mpmath/blob/master/LICENSE) |
+| networkx | >=3.5 | BSD | [License](https://github.com/networkx/networkx/blob/main/LICENSE.txt) |
+| numpy | >=2.3.3 | BSD | [License](https://github.com/numpy/numpy/blob/main/LICENSE.txt) |
+| pandas | >=2.3.2 | BSD-3-Clause | [License](https://github.com/pandas-dev/pandas/blob/main/LICENSE) |
+| parquet | >=1.3.1 | Apache 2.0 | [License](https://github.com/urschrei/parquet-python/blob/master/LICENSE) |
+| ply | >=3.11 | BSD | [License](https://github.com/dabeaz/ply/blob/master/LICENSE.txt) |
+| pyarrow | >=21.0.0 | Apache 2.0 | [License](https://github.com/apache/arrow/blob/master/LICENSE) |
+| python-dateutil | >=2.9.0.post0 | BSD | [License](https://github.com/dateutil/dateutil/blob/master/LICENSE.txt) |
+| pytz | >=2025.2 | MIT | [License](https://github.com/stub42/pytz/blob/master/LICENSE) |
+| setuptools | >=80.9.0 | MIT | [License](https://github.com/pypa/setuptools/blob/main/LICENSE) |
+| six | >=1.17.0 | MIT | [License](https://github.com/benjaminp/six/blob/master/LICENSE) |
+| sympy | >=1.14.0 | BSD | [License](https://github.com/sympy/sympy/blob/master/LICENSE) |
+| thriftpy2 | >=0.5.3 | MIT | [License](https://github.com/Thriftpy/thriftpy2/blob/master/LICENSE) |
+| tqdm | >=4.67.1 | MPL 2.0 | [License](https://github.com/tqdm/tqdm/blob/master/LICENSE) |
+| typing_extensions | >=4.15.0 | PSF | [License](https://github.com/python/typing_extensions/blob/main/LICENSE) |
+| tzdata | >=2025.2 | Public Domain | [License](https://github.com/python/tzdata) |
+
+## Optional Dependencies
+
+| Package | Version | License | License Link |
+|---------|---------|---------|--------------|
+| torch | >=2.8.0 | BSD | [License](https://github.com/pytorch/pytorch/blob/master/LICENSE) |
+| plotly | >=6.3.0 | MIT | [License](https://github.com/plotly/plotly.py/blob/master/LICENSE) |
+| pytest | >=8.0 | MIT | [License](https://github.com/pytest-dev/pytest/blob/main/LICENSE) |
+
+---
+
+### Notes
+
+1. All packages listed above are permissively licensed (MIT, BSD, Apache 2.0, or Public Domain), so they are compatible with MIT licensing for this project.  
+2. If distributing this library, include this `DEPENDENCIES.md` file and your own MIT license file to give proper attribution.  
+3. Optional dependencies should be listed in documentation or `pyproject.toml` extras.