riverjoin 0.1.0__tar.gz

riverjoin-0.1.0/PKG-INFO

@@ -0,0 +1,47 @@
+Metadata-Version: 2.4
+Name: riverjoin
+Version: 0.1.0
+Summary: This is a river join implementation in Python.
+Author-email: Supath Dhital <sdhital@crimson.ua.edu>, Yixian Chen <ychen223@ua.edu>
+Project-URL: Homepage, https://github.com/sdmlua/riverjoin_py
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: geopandas
+Requires-Dist: pathlib
+Requires-Dist: fiona
+Requires-Dist: folium
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: black; extra == "dev"
+
+# Framework for Spatially Joining two Hydrofabric Flowlines
+<hr style="border: 1px solid black; margin: 0;"> 
+
+## Update the code
+```bash
+git clone https://github.com/sdmlua/riverjoin_py
+cd riverjoin_py
+```
+
+Use the ```uv``` to work and update the code,
+```bash
+pip install uv
+
+#Create a virtual env and start collabortaing the code
+uv venv
+
+#activate the virtual environment
+source .venv/bin/activate
+
+#Install all the dependencies and all development packages into it
+uv pip install e .
+uv pip install -e ".[dev]"
+
+#Then add/edit modules under the src/ and run the code through the tests
+#For instance
+pytest tests/spatial_join.py
+```
+Once all changes are made, update the code style with ```black``` code formatter.
+```bash
+black .
+```

riverjoin-0.1.0/README.md

@@ -0,0 +1,31 @@
+# Framework for Spatially Joining two Hydrofabric Flowlines
+<hr style="border: 1px solid black; margin: 0;"> 
+
+## Update the code
+```bash
+git clone https://github.com/sdmlua/riverjoin_py
+cd riverjoin_py
+```
+
+Use the ```uv``` to work and update the code,
+```bash
+pip install uv
+
+#Create a virtual env and start collabortaing the code
+uv venv
+
+#activate the virtual environment
+source .venv/bin/activate
+
+#Install all the dependencies and all development packages into it
+uv pip install e .
+uv pip install -e ".[dev]"
+
+#Then add/edit modules under the src/ and run the code through the tests
+#For instance
+pytest tests/spatial_join.py
+```
+Once all changes are made, update the code style with ```black``` code formatter.
+```bash
+black .
+```

riverjoin-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "riverjoin"
+version = "0.1.0"
+description = "This is a river join implementation in Python."
+authors = [
+  { name = "Supath Dhital", email = "sdhital@crimson.ua.edu" },
+  { name = "Yixian Chen", email = "ychen223@ua.edu" }
+]
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+  "geopandas",
+  "pathlib",
+  "fiona",
+  "folium",
+]
+
+[project.urls]
+Homepage = "https://github.com/sdmlua/riverjoin_py"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[build-system]
+requires = ["setuptools>=61.0"]
+build-backend = "setuptools.build_meta"
+
+[project.optional-dependencies]
+dev = [
+  "pytest",
+  "black"
+]

riverjoin-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

riverjoin-0.1.0/src/riverjoin/__init__.py

@@ -0,0 +1,55 @@
+import warnings
+
+warnings.simplefilter("ignore")
+
+from riverjoin.modules.project_initialization import setup_project
+from riverjoin.modules.setup_hydrofabric import clip_flowlines
+
+from riverjoin.modules.project_initialization import setup_project
+from riverjoin.modules.setup_hydrofabric import clip_flowlines
+from riverjoin.modules.flowlines_buffer import StreamNetworkExtractor
+from riverjoin.modules.traced_downstream import traced_downstream
+from riverjoin.modules.situation_checker import check_situation
+from riverjoin.modules.perpendicularlines import (
+    create_nodes,
+    generate_perpendicular_lines,
+    PerpendicularCleaner,
+    SpatialJoinWithPerpendicularlines,
+    merge_and_drop_duplicates,
+    ReconstructDisconnectedSegments,
+)
+from riverjoin.modules.interactive_map import VizualizeOutputInteractively
+from riverjoin.modules.compare_linelength import compare_linelength
+from riverjoin.modules.attribute_transfer import (
+    NodeExtractor,
+    JoinNearestFlowLineAttributes,
+    AggregateJoinedFlowlines,
+)
+
+
+# utilities
+from riverjoin.utilis import FlowlineFieldViewer
+
+# Combined seamless workflow
+from riverjoin.combined_workflow import run_riverjoin
+
+__all__ = [
+    "setup_project",
+    "clip_flowlines",
+    "StreamNetworkExtractor",
+    "traced_downstream",
+    "check_situation",
+    "create_nodes",
+    "generate_perpendicular_lines",
+    "PerpendicularCleaner",
+    "SpatialJoinWithPerpendicularlines",
+    "merge_and_drop_duplicates",
+    "ReconstructDisconnectedSegments",
+    "VizualizeOutputInteractively",
+    "compare_linelength",
+    "NodeExtractor",
+    "JoinNearestFlowLineAttributes",
+    "AggregateJoinedFlowlines",
+    "FlowlineFieldViewer",
+    "run_riverjoin",
+]

riverjoin-0.1.0/src/riverjoin/combined_workflow.py

@@ -0,0 +1,218 @@
+"""
+This code is the compiled workflow where all the steps are combined into a single script for easier execution.
+
+Author: Supath Dhital, Yixian Chen
+Date: Nov 13, 2025
+"""
+
+import os
+from pathlib import Path
+from typing import Optional, Union, List
+
+from riverjoin.modules.project_initialization import setup_project
+
+from riverjoin.modules.setup_hydrofabric import clip_flowlines
+from riverjoin.modules.flowlines_buffer import StreamNetworkExtractor
+from riverjoin.modules.traced_downstream import traced_downstream
+from riverjoin.modules.situation_checker import check_situation
+from riverjoin.modules.perpendicularlines import (
+    create_nodes,
+    generate_perpendicular_lines,
+    PerpendicularCleaner,
+    SpatialJoinWithPerpendicularlines,
+    merge_and_drop_duplicates,
+    ReconstructDisconnectedSegments,
+)
+from riverjoin.modules.compare_linelength import compare_linelength
+
+from riverjoin.modules.attribute_transfer import (
+    NodeExtractor,
+    JoinNearestFlowLineAttributes,
+    AggregateJoinedFlowlines,
+)
+
+
+# Combined workflow
+class run_riverjoin:
+    """
+    First it initializes the project structure using setup_project class.
+    then Setup the hydrofabric--> which includes clipping the flowlines based on user defined boundary or bbox
+    the extract the flowlines with multiple steps including buffer intersection, tracing downstream disconnected segments,
+    situation check, creating perpendicular nodes, generating perpendicular lines, cleaning the perpendicular lines,
+    spatial join with perpendicular lines, merging and dropping duplicates, reconstructing disconnected segments if any.
+    finally visualizing the output interactively.
+
+    And, Finally attribute will be transferred from one network to another.
+    """
+
+    def __init__(
+        self,
+        join_fl: str,
+        target_fl: str,
+        unique_id: str,
+        unique_id_nextDown: str,
+        target_reach_unique_id_field: str,
+        join_fl_layer: Optional[str] = None,
+        target_fl_layer: Optional[str] = None,
+        boundary: Optional[str] = None,
+        boundary_layer: Optional[str] = None,
+        output_clip_layer: Optional[str] = None,
+        identifier: Optional[str] = None,
+        node_output_layer: Optional[str] = None,
+        strm_order_field: Optional[str] = None,
+        filter_eqn: Optional[Union[str, List[str]]] = None,
+        node_number: Optional[int] = None,
+        node_spacing: Optional[float] = None,
+        transfer_attributes: bool = True,
+        buffer_distance: int = 100,
+        spacing_join_fl: float = 500,
+        perp_line_length: float = 600,
+        min_join_count: int = 5,
+        min_strm_order: int = 2,
+    ):
+        self.join_fl = join_fl
+        self.target_fl = target_fl
+        self.join_fl_layer = join_fl_layer
+        self.target_fl_layer = target_fl_layer
+        self.boundary = boundary
+        self.boundary_layer = boundary_layer
+        self.output_clip_layer = output_clip_layer
+        self.unique_id = unique_id
+        self.unique_id_nextDown = unique_id_nextDown
+        self.target_reach_unique_id_field = target_reach_unique_id_field
+        self.buffer_distance = buffer_distance
+        self.spacing = spacing_join_fl
+        self.node_spacing = node_spacing
+        self.node_number = node_number
+        self.perp_line_length = perp_line_length
+        self.identifier = identifier
+        self.node_output_layer = node_output_layer
+        self.min_join_count = min_join_count
+        self.min_strm_order = min_strm_order
+        self.strm_order_field = strm_order_field
+        self.filter_eqn = filter_eqn
+        self.transfer_attributes = transfer_attributes
+
+        # Initialize project structure
+        self.project_paths = setup_project()
+        self.output_fl = self.project_paths.output_reach_gpkg
+        self.extracted_fl = self.project_paths.output_final_reach_gpkg
+
+        # Clip flowlines
+        clip_flowlines(
+            join_fl=self.join_fl,
+            target_fl=self.target_fl,
+            join_fl_layer=self.join_fl_layer,
+            target_fl_layer=self.target_fl_layer,
+            boundary=self.boundary,
+            boundary_layer=self.boundary_layer,
+            output_clip_layer=self.output_clip_layer,
+        )
+
+        # Buffer intersection
+        StreamNetworkExtractor(
+            join_fl=self.join_fl,
+            unique_id=self.unique_id,
+            buffer_distance=self.buffer_distance,
+            join_fl_layer=self.join_fl_layer,
+            output_clip_layer=self.output_clip_layer,
+            identifier=self.identifier,
+        )
+
+        # Check the situation of the extraction--> maybe need to terminate the process here if no or all flowlines got extracted!!
+        cs = check_situation(
+            identifier=self.identifier,
+        )
+
+        # Run the next steps or terminate based on situation
+        if cs.situation == "extract_upstream_others":
+            # tracing the downstream segments
+            traced_downstream(
+                unique_id=self.unique_id,
+                unique_id_nextDown=self.unique_id_nextDown,
+                join_fl=self.join_fl,
+                join_fl_layer=self.join_fl_layer,
+                identifier=self.identifier,
+            )
+
+            # create nodes for perpendicular lines for further extraction
+            create_nodes(
+                target_reach_unique_id_field=self.target_reach_unique_id_field,
+                output_clip_layer=self.output_clip_layer,
+                identifier=self.identifier,
+                spacing=self.spacing,
+            )
+
+            # Generate perpendicular lines along the created nodes
+            generate_perpendicular_lines(
+                spacing=self.spacing,
+                perp_line_length=self.perp_line_length,
+                identifier=self.identifier,
+                node_output_layer=self.node_output_layer,
+            )
+
+            # Perpendicular lines cleaning
+            PerpendicularCleaner(
+                spacing=self.spacing,
+                perp_line_length=self.perp_line_length,
+                identifier=self.identifier,
+            )
+
+            # Spatial join with perpendicular lines
+            SpatialJoinWithPerpendicularlines(
+                join_fl=self.join_fl,
+                unique_id=self.unique_id,
+                min_join_count=self.min_join_count,
+                min_strm_order=self.min_strm_order,
+                join_fl_layer=self.join_fl_layer,
+                strm_order_field=self.strm_order_field,
+                identifier=self.identifier,
+                filter_eqn=self.filter_eqn,
+            )
+
+            # Merging and dropping duplicates
+            merge_and_drop_duplicates(
+                join_fl=self.join_fl,
+                join_fl_layer=self.join_fl_layer,
+                identifier=self.identifier,
+            )
+
+            # Reconstructing disconnected segments if any
+            ReconstructDisconnectedSegments(
+                unique_id=self.unique_id,
+                unique_id_nextDown=self.unique_id_nextDown,
+                join_fl=self.join_fl,
+                join_fl_layer=self.join_fl_layer,
+                identifier=self.identifier,
+            )
+
+            # Compare the basic statistics of line length between the extracted and target flowlines
+            compare_linelength(
+                identifier=self.identifier,
+                output_fl=self.output_fl,
+                extracted_fl=self.extracted_fl,
+                output_layer=self.output_clip_layer,
+            )
+
+            # Transfer the attribute from one network to another
+            if self.transfer_attributes:
+                NodeExtractor(
+                    target_network_unique_id_field=self.unique_id,
+                    identifier=self.identifier,
+                    spacing=self.node_spacing,
+                    node_number=self.node_number,
+                )
+
+                JoinNearestFlowLineAttributes(
+                    target_network_unique_id_field=self.unique_id,
+                    identifier=self.identifier,
+                )
+
+                AggregateJoinedFlowlines(
+                    target_network_unique_id_field=self.unique_id,
+                    join_network_unique_id_field=self.target_reach_unique_id_field,
+                    identifier=self.identifier,
+                )
+        else:
+            id_msg = f" for {self.identifier}" if self.identifier is not None else ""
+            print(f"Terminating further processing as '{cs.situation}'{id_msg}.")

riverjoin-0.1.0/src/riverjoin/modules/__init__.py

@@ -0,0 +1,47 @@
+from riverjoin.modules.project_initialization import setup_project
+from riverjoin.modules.setup_hydrofabric import clip_flowlines
+
+from riverjoin.modules.project_initialization import setup_project
+from riverjoin.modules.setup_hydrofabric import clip_flowlines
+from riverjoin.modules.flowlines_buffer import StreamNetworkExtractor
+from riverjoin.modules.traced_downstream import traced_downstream
+from riverjoin.modules.situation_checker import check_situation
+from riverjoin.modules.perpendicularlines import (
+    create_nodes,
+    generate_perpendicular_lines,
+    PerpendicularCleaner,
+    SpatialJoinWithPerpendicularlines,
+    merge_and_drop_duplicates,
+    ReconstructDisconnectedSegments,
+)
+from riverjoin.modules.interactive_map import VizualizeOutputInteractively
+from riverjoin.modules.compare_linelength import compare_linelength
+from riverjoin.modules.attribute_transfer import (
+    NodeExtractor,
+    JoinNearestFlowLineAttributes,
+    AggregateJoinedFlowlines,
+)
+
+
+# utilities
+from riverjoin.utilis import FlowlineFieldViewer
+
+__all__ = [
+    "setup_project",
+    "clip_flowlines",
+    "StreamNetworkExtractor",
+    "traced_downstream",
+    "check_situation",
+    "create_nodes",
+    "generate_perpendicular_lines",
+    "PerpendicularCleaner",
+    "SpatialJoinWithPerpendicularlines",
+    "merge_and_drop_duplicates",
+    "ReconstructDisconnectedSegments",
+    "VizualizeOutputInteractively",
+    "compare_linelength",
+    "NodeExtractor",
+    "JoinNearestFlowLineAttributes",
+    "AggregateJoinedFlowlines",
+    "FlowlineFieldViewer",
+]