← Back to usersum index

Roads NoDb Controller

Converts uploaded road linework into Roads-scoped WEPP runs by segmenting inslope roads, mapping them to receiving hillslopes/channels, and regenerating Roads results and reports.

See also: AGENTS.md for NoDb controller conventions and specification.md for the full Roads phase-1 contract.

Overview

wepppy.nodb.mods.roads is the phase-1 Roads integration for WEPPcloud runs that already have a baseline WEPP watershed solution. It lets a user upload roads as GeoJSON, inspect discovered feature properties, map those properties to Roads semantics, prepare monotonic road segments, and then run a Roads-specific watershed update.

The module is centered on the run-scoped Roads NoDb controller in roads.py. It persists state to roads.nodb, stages uploaded GeoJSON under roads/, writes prepared segment artifacts under wepp/roads/segments/, and writes Roads run outputs under wepp/roads/output/.

Primary users are WEPPcloud operators and analysts who need to test how inslope roads change runoff, sediment, and watershed results without modifying the baseline run. Primary developers are people working in NoDb, Roads UI/routes, and Roads RQ orchestration.

Workflow

1. Run baseline WEPP for the project.
2. Enable the Roads mod from the WEPPcloud run page.
3. Upload a Roads GeoJSON file.
4. Review the discovered attribute catalog and map GeoJSON fields to design, surface, and traffic.
5. Choose fallback values for surface and traffic.
6. Click Prepare Segment Candidates to create monotonic segments and low-point attribution artifacts.
7. Click Run WEPPcloud Roads to execute Roads segment runs, combine pass files, rerun the Roads-scoped watershed, and regenerate Roads report resources.
8. Review Roads status, Roads-scoped report links, regenerated resources, and diagnostics.

Components

GeoJSON Preparation

Required format

Roads uploads must be:

• GeoJSON FeatureCollection
• containing LineString or MultiLineString features only
• small enough to fit the Roads upload limit (max_upload_mb, default 50)
• described in the run input CRS or with a valid GeoJSON crs.properties.name

The controller only inspects top-level feature.properties keys for attribute discovery and mapping. Nested property-path mapping is out of scope for this phase.

Eligible road designs

Only the following designs are eligible for inslope segment processing in phase 1:

• Inslope_bd
• Inslope_rd

If a feature maps to any other design, it can remain in the uploaded GeoJSON but it will not become an eligible Roads segment for prepare/run work.

Recommended properties

The Roads UI can map arbitrary top-level property names, but these are the canonical semantics:

If surface or traffic is missing or invalid:

• when a mapping is set, Roads falls back to the user-selected default value
• when a mapping is unset, Roads falls back to legacy property keys and then to the configured default

Recommended authoring rules

• Put the road attributes you care about directly on feature.properties.
• Use one feature per logical road segment when possible.
• Keep the road centerline geometry clean; self-intersections and noisy vertex order make monotonic splitting harder to interpret.
• Use consistent casing for enumerated values even though the controller normalizes many aliases.
• If you already know the Roads semantics, include explicit design, surface, and traffic fields to reduce UI mapping work.

Minimal example

{
  "type": "FeatureCollection",
  "crs": {
    "type": "name",
    "properties": {
      "name": "EPSG:4326"
    }
  },
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "LineString",
        "coordinates": [
          [-116.0, 45.0],
          [-116.0005, 45.0005]
        ]
      },
      "properties": {
        "ROADTYPE": "Inslope_bd",
        "SURF_CLASS": "asphalt",
        "TRAF_LEVEL": "low"
      }
    }
  ]
}

In the Roads UI, that upload would typically be mapped as:

• design -> ROADTYPE
• surface -> SURF_CLASS
• traffic -> TRAF_LEVEL

User Interface Guide

Prerequisites on the run page

Before Roads is useful, the run must already have:

• a baseline WEPP solution
• a WBT-based delineation backend

Roads is backend-gated. Non-WBT runs cannot enable the mod.

Upload and attribute discovery

After upload, the Roads control shows:

• the uploaded GeoJSON path and feature count
• a discovered attribute catalog
• sample values for discovered fields
• persisted mapping controls for design, surface, and traffic

This discovery catalog is specific to the current upload. Uploading a new file resets stale mapping state and then attempts best-effort remapping by exact field-name match.

Mapping controls

The Roads control exposes five mapping-related controls:

Click Apply Attribute Mapping after changing the mapping/default controls. This persists the settings to the run-scoped Roads controller and clears stale prepare/run state.

Prepare Segment Candidates

Prepare Segment Candidates runs the deterministic preprocessing stage. It:

• splits the uploaded linework into monotonic segments
• orients segments from high point to low point
• identifies low points
• attributes channel and receiving-hillslope Topaz IDs for eligible inslope segments
• writes segment preparation artifacts and summary diagnostics

The prepare stage is where bad design mapping shows up first. If the mapped design field does not resolve to Inslope_bd or Inslope_rd, the feature will not become an eligible Roads segment.

Run WEPPcloud Roads

Run WEPPcloud Roads uses the latest prepared segments and:

• builds single-OFE road segment runs from the legacy-derived soil/management templates
• executes segment WEPP runs
• injects segment pass effects into watershed routing
• runs the Roads-scoped watershed update
• regenerates Roads-scoped report resources under wepp/roads/output/interchange/

If the upload or Roads parameters changed after prepare, the run stage requires a fresh prepare cycle.

Results and Artifacts

What the user sees

After a successful Roads run, the WEPPcloud Roads UI and Roads results page expose:

• controller status and run summary state
• Roads-scoped report links
• regenerated resource inventory
• diagnostics JSON for roads_status and roads_summary

The Roads results summary page is rendered from summary.htm.

Important output locations

Report links

When regeneration succeeds, Roads results can include links such as:

• Watershed Loss Summary
• Return Periods
• Yearly Water Balance
• Daily Streamflow
• Average Annual Water Balance
• GL Dashboard
• Storm Event Analyzer
• Road Segment Loss Summary (Parquet and on-demand CSV)

These links are gated by the presence of Roads-scoped regenerated resources. If a required output is missing, the link is hidden rather than routed to stale baseline content.

Configuration

The controller persists Roads settings in roads_params.

Attribute discovery profiling is also configurable through the Roads params contract:

• attribute_discovery_profile_feature_limit
• attribute_discovery_value_preview_limit
• attribute_discovery_value_max_chars

Key Concepts

Developer Notes

Public module surface

The package exports:

• Roads
• MonotonicConversionSummary
• convert_geojson_file_to_monotonic_segments
• convert_geojson_to_monotonic_segments
• convert_geojson_to_monotonic_segments_with_low_points

See init.py for the canonical export list.

Integration points

• NoDb controller: roads.py
• Segment utility: monotonic_segments.py
• WEPPcloud routes: roads_bp.py
• Run-page control: roads_pure.htm
• Frontend controller: roads.js

Validation entry points

Use these focused checks when changing Roads behavior:

wctl run-pytest tests/nodb/mods/test_roads_controller.py --maxfail=1
wctl run-pytest tests/nodb/mods/test_roads_monotonic_segments.py --maxfail=1
wctl run-pytest tests/weppcloud/routes/test_roads_bp.py --maxfail=1
wctl run-pytest tests/weppcloud/routes/test_pure_controls_render.py --maxfail=1
wctl run-npm test -- roads
wctl run-npm lint

For final handoff, run:

wctl run-pytest tests --maxfail=1

Operational Notes

• Roads persists to roads.nodb and follows standard NoDb locking semantics.
• Parameter changes and new uploads clear stale prepare/run summaries and return the controller to idle.
• Warning diagnostics are summarized in prepare/run outputs when mapped fields are missing or invalid.
• Roads requires baseline WEPP outputs and does not replace the baseline wepp/output/ dataset tree.

Further Reading

• specification.md
• NoDb AGENTS.md
• Roads routes in NoDb API
• Roads GeoJSON attribute mapping work package