Pro Tools Technical Reference

Overview

This manual provides customer-facing technical documentation for Whitebox Workflows Pro tools, organized across six functional bundles:

1. Earth Observation and SAR Operations — Remote sensing analysis, SAR processing, and multi-sensor integration
2. Environmental Risk and Compliance — Risk assessment, environmental monitoring, and compliance workflows
3. Terrain and Infrastructure Siting — Site suitability analysis for renewable energy, infrastructure, and utility planning
4. LiDAR and Forest Analytics — Point cloud analysis, terrain products, and forestry intelligence
5. Precision Agriculture Intelligence — Soil-crop-climate integration, yield analysis, and field operations
6. Network Planning and Operations — Linear asset management, service area optimization, and routing

Audience

This reference is designed for:

• Customers deploying licensed Pro workflows in production
• GIS practitioners integrating Whitebox Pro tools into existing pipelines
• Technical analysts validating outputs for decision and reporting workflows
• Customer teams onboarding new users to repeatable Pro workflows

Entitlement Note

Your organization may license a subset of the full Pro catalog. Use this manual as a complete reference, then focus on the tool chapters included in your licensed bundles.

If a tool appears in this manual but not in your runtime environment, contact your account administrator or support channel to confirm bundle access.

Document Structure

Each tool documentation includes:

• Purpose — What the tool does and typical use cases
• Background — Conceptual foundation, algorithms, and methodological context
• Inputs — Data requirements, formats, and validation rules
• Parameters — Complete parameter guide with default values, valid ranges, and interdependencies
• Outputs — Output data formats, metadata, and interpretation
• Validation — Quality checks, common errors, and diagnostic guidance
• Troubleshooting — Known issues, workarounds, and performance considerations
• Example — Real-world workflow example with sample data and expected results
• References — Publications, standards, and related tools

Getting Help

• For API usage questions, refer to the Whitebox Workflows Python/R API Documentation
• For QGIS plugin integration, see the QGIS Plugin User Guide
• For licensing and Pro tool access, contact support through your organization's support channel

Last Updated: May 2026 Whitebox Geospatial Inc.

Customer Quickstart

Goal

Use this quickstart to get productive with your licensed Whitebox Workflows Pro tools as quickly as possible.

Recommended First Steps

1. Confirm which bundles and tools your organization has licensed.
2. Open the relevant bundle overview chapter in this manual.
3. Start with the first workflow listed in that bundle order.
4. Run the tool once on a small pilot area before full production use.
5. Validate outputs using the chapter's validation and troubleshooting sections.

Minimal First-Run Workflow

1. Identify your tool chapter in the table of contents.
2. Read sections in this order:
   • Purpose
   • Inputs
   • Parameters
   • Outputs
   • Example
3. Copy the example and adapt file paths and parameters to your dataset.
4. Run on pilot data.
5. Review output quality before scaling.

Validation Checklist Before Production

• Inputs are in compatible CRS, resolution, and extent.
• Required preprocessing (if any) has been completed.
• Parameters are documented for reproducibility.
• Output looks spatially plausible and matches expected behavior.
• Confidence and quality indicators are reviewed where available.

Common Onboarding Mistakes

• Running full extents before validating on a pilot area.
• Skipping input harmonization checks.
• Reusing parameters from unrelated use cases.
• Ignoring confidence or QA outputs.

Getting Support Faster

When contacting support, include:

1. Tool name
2. Data type and source
3. Parameter set used
4. Error message or unexpected behavior
5. Sample output screenshot or summary

Next Steps

After your first successful run:

1. Save your parameters as a standard profile.
2. Define acceptance criteria for your team.
3. Repeat on full project extents.
4. Track output consistency across reporting cycles.

Environmental Risk and Compliance Bundle

Overview

The Environmental Risk and Compliance bundle provides specialized tools for environmental assessment, risk quantification, and compliance tracking. Applications include wetland management, urban impact analysis, natural hazard assessment, carbon accounting, and reclamation monitoring.

Key Concepts

Hydrogeomorphic Classification

Classification of wetlands by hydrologic source, outlet type, and geomorphic setting to predict function and vulnerability.

Landscape Risk Assessment

Quantitative evaluation of susceptibility to hazards (landslides, wildfire, flooding) using terrain, geology, and climate data.

Environmental Compliance

Tracking and auditing environmental attributes against regulatory standards (wetland delineation, riparian buffers, habitat quality).

Verification and Audit

Independent quantification and documentation of environmental outcomes (carbon sequestration, habitat restoration) for certification programs.

Typical Workflows

Wetland Mapping and Assessment

1. Delineate potential wetland areas using topography, imagery, soils
2. Classify by hydrogeomorphic type (Wetland Hydrogeomorphic Classification)
3. Assess ecological function and vulnerability
4. Report for regulatory compliance

Landslide Risk Assessment

1. Prepare terrain (DEM, slope, aspect, curvature)
2. Compile geological/soil data (lithology, depth, cohesion)
3. Calculate susceptibility index (Landslide Susceptibility Assessment)
4. Prioritize mitigation areas
5. Monitor post-mitigation recovery

Carbon Verification Workflow

1. Estimate baseline carbon stock (forest structure, soil)
2. Implement restoration or conservation practice
3. Monitor post-intervention carbon outcomes (repeat imagery, field surveys)
4. Audit results against claims (Carbon Verification Audit)
5. Generate verification report for carbon market or compliance program

Recommended Workflow Start Order

The workflow order below is a practical starting sequence that gets most teams to usable, validated outputs quickly:

1. Carbon Verification Audit
2. Wildfire Fuel Risk Analysis
3. Landslide Susceptibility Assessment
4. Mine Reclamation Compliance Tracker
5. Urban Expansion Impact Assessment
6. Wetland Hydrogeomorphic Classification
7. River Corridor Health Assessment

Performance and Compliance Considerations

• Regulatory alignment: Wetland classifications must match applicable standards (Cowardin, HGM, regional variants)
• Precision requirements: Hazard mapping should reflect actual field-verified risk classes
• Temporal resolution: Monitoring workflows require consistent acquisition schedules
• Audit documentation: All methods, data sources, and calculations must be documented for compliance review

References

• Ramsar Convention on Wetlands (1971, as amended)
• USGS Wetland Classification (Cowardin et al., 1979)
• Intergovernmental Panel on Climate Change (IPCC) Guidelines for Greenhouse Gas Inventories

Recommended Results Package

For customer delivery, this bundle performs best when packaged as a compliance-ready workflow set rather than isolated analyses.

Recommended packaging:

1. Baseline condition map package
2. Risk/compliance classification package
3. Validation and uncertainty appendix
4. Executive summary with pass/fail and priority actions

This structure helps non-technical decision makers quickly understand what changed, why it matters, and what action is required.

Deployment Notes

• A practical rollout pattern is to begin with one high-priority use case (for example wetland permitting support or reclamation audit), then expand to adjacent workflows once outputs are validated.
• Include a reproducibility annex (inputs, parameter profile, run timestamp, software version) to reduce audit friction.
• For regulated customers, prioritize conservative thresholds in production and reserve exploratory thresholds for technical review mode.

Carbon Verification Audit

Purpose

Carbon Verification Audit quantifies and verifies carbon sequestration outcomes in forests, wetlands, or agricultural lands against baseline and project claims. Generates audit documentation for carbon markets, regulatory compliance, and ESG reporting.

Typical Questions This Tool Helps Answer

• Does the NDVI-based carbon proxy show net vegetation gain or loss between baseline and current scenes, and what is the magnitude of change relative to per-pixel uncertainty?
• What fraction of the study area shows confirmed vegetation recovery versus loss, and how does biome-calibrated NDVI-to-carbon scaling affect the net proxy estimate?
• What methodology reference and MRV template are recorded in the audit contract, and are the gain/loss classification thresholds appropriate for the selected profile and biome?

Background

Environmental risk workflows are built around source-pathway-receptor logic: identify stressors, model transport or exposure pathways, and estimate consequence to assets or ecosystems. Inputs and model assumptions define the validity envelope, so uncertainty documentation is as important as the final risk score.

In practice, these tools are most defensible when used comparatively across scenarios, with explicit thresholds and confidence narratives. Interpretation should focus on rank ordering and mitigation prioritization, not absolute certainty.

Carbon sequestration auditing links biomass/land-cover dynamics to accounting-ready carbon stock and flux estimates. Traceability requirements demand clear lineage from input assumptions through summary metrics.

Methodological Considerations

• Calibrate thresholds and class boundaries against local context whenever possible; transferred defaults should be treated as provisional.
• Evaluate scenario sensitivity explicitly so mitigation priorities are robust to uncertainty in assumptions.
• Keep lineage between assumptions, intermediate metrics, and summary outputs for audit-ready interpretation.

Practical Interpretation Pitfalls

A frequent mistake is interpreting risk classes as deterministic outcomes. These products are comparative planning aids and should be paired with field validation and expert review.

Inputs

Parameters

• biome_class (optional): biome coefficient pack (tropical_forest, boreal_forest, grassland_shrub, agricultural_cropland, wetland_aquatic, none).
• profile (optional): conservative, balanced, aggressive.
• zone_block_cells (optional): block size for verification polygons; default 16.
• baseline_date and current_date (optional): valid calendar dates in YYYY-MM-DD format.
• mrv_template (optional): verra_vcs_vm0010, american_carbon_registry, gold_standard, none.
• methodology_reference (optional): carbon methodology string included in output contract.
• output_prefix (required): base output name used for all emitted artifacts.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Important MRV note

The workflow explicitly labels outputs as remote-sensing-derived carbon proxy results. Field-based verification is still required for formal credit issuance.

Summary contract also includes:

• output_semantics
• confidence_contract
• interpretation_warnings

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.carbon_sequestration_verification_audit(
        baseline_bundle="baseline_scene.tif",
        baseline_red_band_index=0,
        baseline_nir_band_index=1,
        current_bundle="current_scene.tif",
        current_red_band_index=0,
        current_nir_band_index=1,
        biomass_proxy="forest_structure_biomass_proxy.tif",
        biome_class="tropical_forest",
        profile="balanced",
        zone_block_cells=16,
        baseline_date="2021-06-15",
        current_date="2024-06-20",
        mrv_template="verra_vcs_vm0010",
        methodology_reference="Verra VM0010 v1.3",
        output_prefix="outputs/carbon_audit"
)

References

• IPCC (2019). "2019 Refinement to the 2006 IPCC Guidelines." UNFCCC Secretariat.
• Verified Carbon Standard (VCS) Agriculture, Forestry & Other Land Use Methodology Standards.

Parameter Interaction Notes

Results are most sensitive to profile thresholds, biome pack choice, and time separation between dates.

• Conservative profile reduces false positives but may under-detect subtle change.
• Aggressive profile increases sensitivity and should be paired with careful QA.
• Date separation affects temporal uncertainty terms in the contract.

QA and Acceptance Criteria

Use a staged acceptance approach for Carbon Verification Audit:

1. Validate bundle bands and index mappings.
2. Validate optional dates and MRV template selection.
3. Confirm output artifacts are present and consistent with contract metadata.
4. Review gain/loss/uncertainty outputs with domain experts.

Recommended acceptance checks:

• audit_contract.workflow is correct.
• Summary fractions are coherent and bounded.
• Uncertainty output and decomposition fields are populated.

Advanced Operational Guidance

For production deployment of Carbon Verification Audit:

• Keep methodology references and template choices consistent across reporting cycles.
• Archive contracts and reports for audit reproducibility.
• Use verification zones for targeted field sampling design.

Implementation Patterns

Common implementation patterns with Carbon Verification Audit:

• Monitoring run for periodic trend tracking.
• Biomass-enhanced run when LiDAR proxy is available.
• Compliance-prep run with full MRV metadata fields.

Related Tools

Use Carbon Verification Audit together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Carbon Verification Audit is best used when you need defensible outputs for permitting, compliance reporting, or external audit review.

What this workflow helps you achieve:

• Reduces interpretation ambiguity by standardizing method and output structure.
• Produces documentation-ready outputs that can be shared with regulators and stakeholders.
• Shortens time from analysis to decision package.

Results Delivery Checklist

Before handing results to a customer or regulator:

1. Confirm AOI, CRS, and temporal scope match project statement of work.
2. Verify assumptions and threshold values are documented in the run metadata.
3. Export both primary outputs and summary tables for non-technical stakeholders.
4. Include at least one validation artifact (field check, independent layer comparison, or sensitivity run).
5. Archive parameter profile used for reproducibility.

Common Questions

Q: Can this output be used directly in compliance submissions?
A: It is suitable for pre-verification evidence packaging, but formal issuance still requires field-validated MRV workflows.

Q: How do we explain uncertainty to a non-technical reviewer?
A: Use the uncertainty raster plus the contract decomposition (spectral, temporal, atmospheric, biome model terms).

Q: What is the most common failure mode in delivery?
A: Incorrect band mapping or date/metadata mismatches between reporting cycles.

Q: Why is confidence low even where vegetation seems to increase?
A: Confidence also reflects signal quality and threshold behavior, not only directional change.

Q: Why is biomass information not reflected in one run?
A: Biomass blending occurs only when the biomass raster can be loaded and harmonized to the baseline grid.

Q: Why do gain/loss percentages change after switching profile?
A: Profile settings adjust sensitivity thresholds, so classification fractions shift by design.

Q: How do we choose the right biome class?
A: Use the dominant biome for the project area because biome class affects proxy scaling and uncertainty assumptions.

Q: Why do uncertainty values appear similar across large areas?
A: The uncertainty model uses run-level propagated components, so variation is often more temporal/parameter-driven than spatial.

Q: What should we tell stakeholders about the MRV disclaimer?
A: The outputs are audit-support evidence, not final certified credits; field verification and formal program steps remain required.

Q: Why are zone classes different from pixel-level patterns?
A: Verification zones aggregate block-level behavior for planning and reporting, which smooths local variation.

Q: How should we compare two reporting periods fairly?
A: Keep profile, biome class, and preprocessing choices consistent and ensure valid paired dates.

Q: What does methodology_reference do in practice?
A: It records lineage in the contract so auditors can trace which methodology framing guided interpretation.

Wildfire Fuel Risk Analysis

What This Tool Does

Wildfire Fuel Risk Analysis combines moisture, fuel structure, optional terrain, and optional weather context to map wildfire risk and produce planning zones.

Typical Questions This Tool Helps Answer

• Which landscape units have the highest combined fuel loading and terrain-amplified fire spread potential this season?
• Where does ladder fuel continuity create high crown-fire transition risk that warrants priority treatment or prescribed burn planning?
• Which high-risk fuel zones overlap structures, evacuation routes, or suppression assets and should be addressed first?

When To Use

• Fuel-risk screening over large areas
• Mitigation prioritization and treatment planning
• Scenario comparisons with different weather or sensitivity profiles

What You Need

Key Settings

Available fuel models: temperate_mixed_forest, boreal_sparse, mediterranean_shrub, tropical_dense, grassland_savanna, none.

What You Get

risk_zones fields: ZONE_ID, MEAN_RISK, MAX_RISK, DOM_FUEL, RISK_TIER, PIXEL_COUNT.

Runtime Output Keys

result.outputs["moisture_index"]
result.outputs["fuel_load_class"]
result.outputs["ladder_fuel_continuity"]
result.outputs["risk_matrix"]
result.outputs["risk_zones"]
result.outputs["summary"]
result.outputs["html_report"]

Common Questions

Q: Which output should incident teams review first? A: Start with summary.high_risk_fraction and summary.extreme_risk_fraction, then map priority blocks using risk_zones.RISK_TIER.

Q: What is a common interpretation mistake? A: Treating dominant fuel class (DOM_FUEL) as final risk severity without considering moisture and terrain/weather amplification.

Q: Which settings most change extreme-risk area? A: dry_moisture_threshold, wet_moisture_threshold, and dryness_severity_factor usually have the largest effect.

Q: How should operations use these outputs? A: Use high-risk zones to prioritize fuels treatment and response pre-positioning, then refine by access and suppression constraints.

Results Delivery Checklist

• Band indices were verified against the optical bundle
• Optional inputs were confirmed to align to analysis grid
• Risk matrix and risk zones were visually reviewed
• Summary fractions and weather factors were checked

Purpose

Wildfire Fuel Risk Analysis quantifies landscape fuel characteristics (woody biomass, canopy structure, continuity) and integrates with climate/topography to assess wildfire ignition and spread risk. Enables prevention planning and fire management prioritization.

Background

Wildfire fuel-risk analysis combines vegetation condition, structural continuity, and terrain-weather amplification into a comparative hazard surface. A useful conceptual model is:

$$R(x)=w_m M(x)+w_f F(x)+w_l L(x)+w_t T(x)+w_w W(x)$$

Where $M$ is moisture stress, $F$ is fuel load class pressure, $L$ is ladder-fuel continuity, $T$ is terrain amplification, and $W$ is weather modulation.

Fuel and Moisture Interaction

Moisture indicators (for example NDMI/NDWI-style proxies) help distinguish currently receptive fuels from structurally loaded but less active areas. In practice, high structural load with low dryness may rank lower than moderate load under acute dryness.

Zone-Level Aggregation Logic

Risk-zone polygons summarize cell-level behavior into operational blocks. Zone statistics (mean/max risk, dominant fuel label, tier assignment) are intended for treatment sequencing and patrol planning, not parcel-level deterministic prediction.

Methodological Considerations

• Validate input band semantics and index modes before interpreting moisture-driven risk variation.
• Treat weather fields as scenario controls; report assumptions with each run.
• Re-run with sensitivity perturbations on moisture thresholds and severity factors before final prioritization.

Practical Interpretation Pitfalls

Common errors include treating dominant fuel label as final risk severity, ignoring uncertainty introduced by missing optional context layers, and over-committing to a single threshold configuration.

Inputs

Required runtime argument:

• optical_bundle

Common runtime arguments:

• red_band_index, nir_band_index, swir_band_index
• biomass_proxy, slope, aspect
• fuel_model, profile, zone_block_cells
• output_prefix (required)
• air_temperature_c, relative_humidity_pct, wind_speed_kmh

Parameters

Defaults and behavior:

• profile defaults to balanced.
• fuel_model defaults to none.
• zone_block_cells defaults to 20.
• swir_band_index is optional; when absent, the workflow uses an NDWI-style moisture proxy.

Outputs

Primary runtime outputs:

• moisture_index
• fuel_load_class
• ladder_fuel_continuity
• risk_matrix
• risk_zones
• summary
• html_report

risk_zones includes ZONE_ID, MEAN_RISK, MAX_RISK, DOM_FUEL, RISK_TIER, and PIXEL_COUNT.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.wildfire_fuel_loading_and_risk_matrix(
	optical_bundle="optical_scene.tif",
	red_band_index=0,
	nir_band_index=1,
	swir_band_index=2,
	biomass_proxy="forest_structure_biomass_proxy.tif",
	slope="slope.tif",
	aspect="aspect.tif",
	fuel_model="temperate_mixed_forest",
	profile="balanced",
	zone_block_cells=20,
	output_prefix="wildfire_risk"
)

References

• Tool implementation: wbtools_pro/src/tools/workflow_products/wildfire_fuel_loading_and_risk_matrix.rs
• Wildland fire behavior interpretation practice (fuel/moisture/terrain/weather decomposition)

Parameter Interaction Notes

Prioritize sensitivity checks on profile/threshold settings that materially change output distributions and decision classes.

QA and Acceptance Criteria

Minimum acceptance:

• Band indices validated against the optical bundle layout.
• Optional rasters aligned to the analysis grid.
• summary includes risk fractions and weather/modulation context fields.
• risk_zones contains tier and dominant-fuel attributes expected by dispatch/planning workflows.

Advanced Operational Guidance

For production use, preserve run metadata, lock approved profiles, and version output packages for reproducibility and auditability.

Implementation Patterns

Common pattern: baseline run, sensitivity run on 1-2 parameters, then locked-profile production run for delivery.

Related Tools

See upstream conditioning and downstream validation tools in the same bundle for end-to-end workflow consistency.

When To Use This Workflow

Use Wildfire Fuel Risk Analysis when you need repeatable, source-contract-aligned outputs for planning, reporting, and stakeholder review.

Landslide Susceptibility Assessment

Purpose

Landslide Susceptibility Assessment quantifies landscape susceptibility to shallow and deep-seated landslides using terrain, geology, and hydrologic data. Outputs probability-based susceptibility maps for hazard zoning, planning, and risk reduction.

Typical Questions This Tool Helps Answer

• Which areas of the study region have the highest combined slope, curvature, and elevation susceptibility score, and what fraction exceeds the high-risk threshold?
• How does susceptibility change when elevated rainfall intensity is added, and which areas shift from moderate to high or extreme risk class?
• Which high-susceptibility slopes intersect infrastructure corridors or settlement footprints and require priority mitigation attention?

Background

Environmental risk workflows are built around source-pathway-receptor logic: identify stressors, model transport or exposure pathways, and estimate consequence to assets or ecosystems. Inputs and model assumptions define the validity envelope, so uncertainty documentation is as important as the final risk score.

In practice, these tools are most defensible when used comparatively across scenarios, with explicit thresholds and confidence narratives. Interpretation should focus on rank ordering and mitigation prioritization, not absolute certainty.

Susceptibility mapping combines terrain predisposition, hydrologic forcing proxies, and material/land-cover context to rank likely failure zones. Outputs are probabilistic or relative-risk indicators, not deterministic failure predictions.

Methodological Considerations

• Calibrate thresholds and class boundaries against local context whenever possible; transferred defaults should be treated as provisional.
• Evaluate scenario sensitivity explicitly so mitigation priorities are robust to uncertainty in assumptions.
• Keep lineage between assumptions, intermediate metrics, and summary outputs for audit-ready interpretation.

Practical Interpretation Pitfalls

A frequent mistake is interpreting risk classes as deterministic outcomes. These products are comparative planning aids and should be paired with field validation and expert review.

Inputs

Parameters

Profile setting adjusts relative factor influence:

• fast: stronger slope weighting for rapid screening.
• balanced: mixed slope/curvature/elevation/rain weighting.
• conservative: higher curvature emphasis for stricter terrain interpretation.

Factor contribution mode controls summary explainability detail:

• none: hides factor-weight details.
• basic: includes core weights and dominant factor.
• detailed: includes ranked factor percentages.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Output filenames:

• <output_prefix>_susceptibility.tif
• <output_prefix>_trigger_pressure.tif
• <output_prefix>_confidence.tif
• <output_prefix>_risk_zones.gpkg
• <output_prefix>_summary.json
• <output_prefix>_report.html

Risk-zone attributes:

• ZONE_ID
• SUSC
• CONF
• CLASS

Summary-contract additions:

• output_semantics: machine-readable output intent and certification scope for each output key.
• confidence_contract: confidence metric declaration including threshold and low-confidence fraction.
• interpretation_warnings: plain-language warnings describing proxy limits and run-to-run comparison constraints.

Validation

• Confirm inputs and parameter ranges are valid.
• Verify threshold and profile values in summary JSON.
• Verify zone count is bounded by max_zone_features.
• Review explainability notes before external delivery.
• Confirm summary includes output_semantics, confidence_contract, and interpretation_warnings.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.landslide_susceptibility_assessment(
        dem="dem_10m_region.tif",
        rainfall_intensity="rainfall_intensity_norm.tif",
        profile="balanced",
        factor_contribution_mode="basic",
        susceptibility_threshold=0.65,
        max_zone_features=5000,
        output_prefix="outputs/landslide/assessment"
)

References

• Guzzetti, F., Carrara, A., Cardinali, M., & Reichenbach, P. (1999). "Landslide Hazard Evaluation." Eng. Geol. 58(3–4), 353–372.

Parameter Interaction Notes

Results are most sensitive to profile selection, rainfall availability, and threshold choice.

• Higher thresholds produce fewer high-risk zones.
• Lower thresholds broaden warning areas and zone counts.
• If rainfall is absent, the workflow uses a neutral trigger proxy and this should be documented.

QA and Acceptance Criteria

Use a staged acceptance approach for Landslide Susceptibility Assessment:

1. Confirm DEM and optional rainfall inputs are valid.
2. Confirm expected rasters, vector zones, and summary outputs are generated.
3. Validate susceptibility threshold and resulting high-risk fractions.
4. Confirm factor contribution detail level matches selected mode.

Recommended acceptance checks:

• Summary workflow ID is correct.
• High-risk fraction aligns with mapped hotspots.
• Zone output size is within operational limits.

Advanced Operational Guidance

For production deployment of Landslide Susceptibility Assessment:

• Use basic mode for internal operations and detailed mode for formal reporting.
• Tune threshold + zone cap together to control delivery volume.
• Archive summary JSON with project records.

Implementation Patterns

Common implementation patterns with Landslide Susceptibility Assessment:

• Baseline screening run (balanced, basic).
• Explainability run (detailed) for stakeholder package.
• Threshold sensitivity run to bracket operational risk.

Related Tools

Use Landslide Susceptibility Assessment together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Landslide Susceptibility Assessment is best used when you need defensible outputs for permitting, compliance reporting, or external audit review.

What this workflow helps you achieve:

• Reduces interpretation ambiguity by standardizing method and output structure.
• Produces documentation-ready outputs that can be shared with regulators and stakeholders.
• Shortens time from analysis to decision package.

Results Delivery Checklist

Before handing results to a customer or regulator:

1. Confirm AOI, CRS, and temporal scope match project statement of work.
2. Verify assumptions and threshold values are documented in the run metadata.
3. Export both primary outputs and summary tables for non-technical stakeholders.
4. Include at least one validation artifact (field check, independent layer comparison, or sensitivity run).
5. Archive parameter profile used for reproducibility.

Common Questions

Q: Can this output be used directly in compliance submissions?
A: Yes, when accompanied by documented inputs, parameter profile, and validation evidence.

Q: How do we explain uncertainty to a non-technical reviewer?
A: Use confidence/quality layers and summarize uncertainty in plain-language ranges (high/moderate/low confidence).

Q: What is the most common failure mode in delivery?
A: Scope mismatch (extent, date range, or baseline assumptions) rather than algorithmic failure.

Q: What does factor_contribution_mode=none do?
A: It intentionally suppresses factor-weight details in summary outputs.

Q: Why are there many risk-zone polygons?
A: Each qualifying high-risk area can generate many features; adjust threshold and max_zone_features to control output volume.

Q: What should teams inspect first?
A: Review susceptibility and confidence together, then check summary high-risk fraction and zone counts.

Q: Is rainfall required?
A: No. It is optional, but including it improves trigger realism.

Mine Reclamation Compliance Tracker

Purpose

Mine Reclamation Compliance Tracker monitors mine site reclamation progress against regulatory closure plans and performance standards. Tracks landform stability, vegetation recovery, water quality, and habitat restoration. Generates compliance reports for regulatory agencies.

Typical Questions This Tool Helps Answer

• Is the site on track to meet closure plan milestones for vegetation recovery and slope stability at the next regulatory review, and what is the current overall compliance grade?
• Which reclamation performance indicators are currently below the required threshold, and where are those failures concentrated on the site?
• Which areas require remedial intervention before the next scheduled inspection, and what evidence supports that prioritization?

Background

Environmental risk workflows are built around source-pathway-receptor logic: identify stressors, model transport or exposure pathways, and estimate consequence to assets or ecosystems. Inputs and model assumptions define the validity envelope, so uncertainty documentation is as important as the final risk score.

In practice, these tools are most defensible when used comparatively across scenarios, with explicit thresholds and confidence narratives. Interpretation should focus on rank ordering and mitigation prioritization, not absolute certainty.

Reclamation compliance tracking compares observed site condition against staged criteria for slope stability, vegetation recovery, drainage behavior, and disturbance footprint. Temporal consistency and threshold governance are central to defensible reporting.

Methodological Considerations

• Calibrate thresholds and class boundaries against local context whenever possible; transferred defaults should be treated as provisional.
• Evaluate scenario sensitivity explicitly so mitigation priorities are robust to uncertainty in assumptions.
• Keep lineage between assumptions, intermediate metrics, and summary outputs for audit-ready interpretation.

Practical Interpretation Pitfalls

A frequent mistake is interpreting risk classes as deterministic outcomes. These products are comparative planning aids and should be paired with field validation and expert review.

Inputs

Parameters

Key runtime behaviors:

• Computes NDVI baseline/current and NDVI recovery.
• Computes progress-to-target per cell.
• Applies milestone grading for vegetation and optional slope.
• Creates compliance zones and zone narratives.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Output files:

• <output_prefix>_ndvi_baseline.tif
• <output_prefix>_ndvi_current.tif
• <output_prefix>_vegetation_recovery.tif
• <output_prefix>_reclamation_progress.tif
• <output_prefix>_compliance_zones.gpkg
• <output_prefix>_compliance_contract.json
• <output_prefix>_validation_diagnostics.json
• <output_prefix>_report.html

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.mine_site_reclamation_compliance_tracker(
    baseline_bundle="baseline_scene.tif",
    baseline_red_band_index=0,
    baseline_nir_band_index=1,
    current_bundle="current_scene.tif",
    current_red_band_index=0,
    current_nir_band_index=1,
    slope="slope_deg.tif",
    reclamation_target_ndvi=0.35,
    slope_stability_max_deg=30.0,
    jurisdiction="none",
    monitoring_epoch=2,
    site_name="Permit BC-2021-0047",
    zone_block_cells=20,
    output_prefix="outputs/reclamation_compliance"
)

References

• OSMRE (Office of Surface Mining Reclamation and Enforcement) Regulations 30 CFR 816–817.

Parameter Interaction Notes

Outputs are most sensitive to red/NIR band indexing and threshold context.

• Incorrect band assignment can invert or flatten recovery interpretation.
• Jurisdiction template settings may supersede local threshold assumptions.
• Smaller zone blocks increase spatial detail but also variability.

QA and Acceptance Criteria

Use a staged acceptance approach for Mine Reclamation Compliance Tracker:

1. Confirm bundle inputs and band indices are valid.
2. Confirm output rasters and compliance contract are generated.
3. Verify milestone statuses and overall grade against project expectations.
4. Review per-zone rationale for high-priority remediation areas.

Recommended acceptance checks:

• Contract workflow ID is correct.
• Target achievement and recovered area metrics are plausible.
• Slope milestone state (pass/conditional/fail/not_evaluated) is expected.

Advanced Operational Guidance

For production deployment of Mine Reclamation Compliance Tracker:

• Keep jurisdiction setting fixed within a compliance cycle.
• Track monitoring_epoch consistently over time.
• Archive contract JSON with permit documentation.

Implementation Patterns

Common implementation patterns with Mine Reclamation Compliance Tracker:

• NDVI-only compliance pass.
• NDVI + slope full compliance pass.
• Periodic epoch-based tracking pass.

Related Tools

Use Mine Reclamation Compliance Tracker together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Mine Reclamation Compliance Tracker is best used when you need defensible outputs for permitting, compliance reporting, or external audit review.

What this workflow helps you achieve:

• Reduces interpretation ambiguity by standardizing method and output structure.
• Produces documentation-ready outputs that can be shared with regulators and stakeholders.
• Shortens time from analysis to decision package.

Results Delivery Checklist

Before handing results to a customer or regulator:

1. Confirm AOI, CRS, and temporal scope match project statement of work.
2. Verify assumptions and threshold values are documented in the run metadata.
3. Export both primary outputs and summary tables for non-technical stakeholders.
4. Include at least one validation artifact (field check, independent layer comparison, or sensitivity run).
5. Archive parameter profile used for reproducibility.

Common Questions

Q: Can this output be used directly in compliance submissions?
A: Yes, when accompanied by documented inputs, parameter profile, and validation evidence.

Q: How do we explain uncertainty to a non-technical reviewer?
A: Use confidence/quality layers and summarize uncertainty in plain-language ranges (high/moderate/low confidence).

Q: What is the most common failure mode in delivery?
A: Scope mismatch (extent, date range, or baseline assumptions) rather than algorithmic failure.

Q: What should teams inspect first after a run?
A: Start with compliance contract summary and milestone status, then check zone rationales.

Q: Why did overall grade drop despite improving NDVI mean?
A: Grade also depends on target achievement fractions and optional slope-stability milestones.

Q: What happens if jurisdiction is set to none?
A: User thresholds are used directly without jurisdiction override templates.

Q: Can this workflow run without slope?
A: Yes, slope milestone is set to not_evaluated and vegetation milestones still run.

Q: Why are some zones marked high priority?
A: Zone rationale flags low vegetation target attainment and/or slope instability constraints.

Urban Expansion Impact Assessment

What This Tool Does

Urban Expansion Impact Assessment compares a baseline and scenario urban footprint to quantify impact severity and habitat loss, and then scores streams that intersect the impact surface. It returns rasters, an affected-streams layer, a summary JSON, and an HTML report.

Typical Questions This Tool Helps Answer

• How much new urban area was added between the baseline and scenario extents, and where is expansion most spatially concentrated?
• Where does the new urban expansion most severely affect stream channels and sensitive habitat areas, and which stream segments are classified as high impact?
• What is the projected ecological footprint of the proposed development scenario relative to the no-development baseline?

When To Use

• Environmental review of growth alternatives
• Permitting and compliance narratives tied to urban expansion
• Stream-impact screening for proposed growth scenarios

What You Need

Key Settings

What You Get

Summary-contract additions in summary:

• output_semantics: machine-readable output intent and certification scope per output key.
• confidence_contract: confidence metric declaration including threshold and low-confidence fraction.
• interpretation_warnings: plain-language warnings on proxy limits and threshold-sensitive comparisons.

Runtime Output Keys

result.outputs["impact_severity"]
result.outputs["affected_streams"]
result.outputs["habitat_loss"]
result.outputs["summary"]
result.outputs["html_report"]

The affected-streams layer includes STREAM_ID, IMP_MEAN, IMP_MAX, and IMP_CLASS fields.

Common Questions

Q: Which outputs should policy teams review first? A: Start with summary.new_urban_area_ha and summary.high_impact_streams, then inspect affected_streams.IMP_CLASS hotspots.

Q: What is a common interpretation mistake? A: Judging impact by expansion area alone; even modest expansion can generate concentrated high stream impact.

Q: Which settings most change outcomes? A: scenario_template selection is usually the strongest driver, and adding habitat_sensitivity often changes habitat-loss concentration.

Q: How should planners use these results? A: Use stream-impact and habitat-loss hotspots to prioritize mitigation packages before selecting a preferred growth scenario.

Results Delivery Checklist

• Baseline and scenario rasters were aligned and validated
• affected_streams was reviewed in GIS software
• The chosen scenario template matches the planning narrative
• summary["new_urban_area_ha"] and summary["high_impact_streams"] were checked before delivery
• summary["output_semantics"], summary["confidence_contract"], and summary["interpretation_warnings"] were reviewed before delivery

Purpose

Urban Expansion Impact Assessment quantifies landscape and ecological impacts of urban growth, including habitat loss, fragmentation, hydrologic alteration, and infrastructure encroachment. Enables impact assessment for environmental review and planning.

Background

Urban expansion impact assessment evaluates how scenario growth footprints alter ecological and hydrologic exposure pathways. A simple framing is:

$$I(x)=\Delta U(x)\cdot S(x)$$

Where $\Delta U$ represents newly urbanized extent and $S$ represents receptor sensitivity (for example habitat or stream-exposure susceptibility).

Scenario Template Logic

Scenario templates encode different development philosophies (infill-heavy, corridor-led, conservation-priority, mixed growth). Their value is comparative: they expose trade-offs among growth accommodation, stream impact concentration, and habitat-loss distribution.

Stream and Habitat Coupling

Stream impact and habitat-loss layers should be interpreted jointly. A scenario with moderate total expansion can still produce severe localized stream stress if growth concentrates near vulnerable corridor segments.

Methodological Considerations

• Treat scenario templates as policy hypotheses and test multiple alternatives before selecting a preferred pathway.
• Document whether habitat sensitivity was supplied; omission changes loss-pattern interpretation.
• Use hotspot stability checks across templates to identify robust mitigation targets.

Practical Interpretation Pitfalls

Common pitfalls include interpreting area-growth percentage alone, ignoring receptor distribution, and making mitigation decisions without checking scenario sensitivity.

Inputs

Required runtime arguments:

• baseline_urban
• scenario_urban
• streams

Optional runtime arguments:

• habitat_sensitivity
• scenario_template
• output_prefix (required)

Parameters

Defaults and behavior:

• scenario_template defaults to balanced_growth.
• output_prefix is required.
• habitat_sensitivity is optional; when supplied, habitat-loss concentration is weighted by sensitivity.

Outputs

Primary runtime outputs:

• impact_severity
• affected_streams
• habitat_loss
• summary
• html_report

affected_streams includes STREAM_ID, IMP_MEAN, IMP_MAX, and IMP_CLASS.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.urban_expansion_impact_assessment(
	baseline_urban="urban_2010.tif",
	scenario_urban="urban_2024.tif",
	streams="streams.gpkg",
	habitat_sensitivity="habitat_sensitivity.tif",
	scenario_template="balanced_growth",
	output_prefix="urban_expansion"
)

References

• Tool implementation: wbtools_pro/src/tools/workflow_products/urban_expansion_impact_assessment.rs
• Environmental impact assessment scenario-comparison practice

Parameter Interaction Notes

Prioritize sensitivity checks on profile/threshold settings that materially change output distributions and decision classes.

QA and Acceptance Criteria

Minimum acceptance:

• Baseline/scenario rasters aligned in dimensions and georeferencing.
• summary includes new_urban_area_ha, high_impact_streams, and interpretation blocks.
• affected_streams schema contains expected impact fields and class labels.

Advanced Operational Guidance

For production use, preserve run metadata, lock approved profiles, and version output packages for reproducibility and auditability.

Implementation Patterns

Common pattern: baseline run, sensitivity run on 1-2 parameters, then locked-profile production run for delivery.

Related Tools

See upstream conditioning and downstream validation tools in the same bundle for end-to-end workflow consistency.

When To Use This Workflow

Use Urban Expansion Impact Assessment when you need repeatable, source-contract-aligned outputs for planning, reporting, and stakeholder review.

Wetland Hydrogeomorphic Classification

What This Tool Does

Wetland Hydrogeomorphic Classification classifies wetland areas into hydrogeomorphic classes and produces confidence and polygon outputs for mapping and reporting.

Typical Questions This Tool Helps Answer

• What HGM class does each wetland unit belong to, and what ecological function and vulnerability profile does that classification imply?
• Which wetland polygons have high classification confidence versus uncertain or mixed-class assignments that warrant field verification?
• Are the mapped wetland types consistent with what is expected given the surrounding landscape geomorphology and hydrology?

When To Use

• Wetland inventory and screening
• Regional wetland function mapping
• Regulatory and planning workflows requiring class plus confidence outputs

What You Need

Key Settings

Available wetland_region values: temperate_forested, glaciated_boreal, prairie_pothole, coastal_tidal, appalachian_montane, subtropical_floodplain, none.

What You Get

The wetland polygon layer includes REGION_ID, CELL_COUNT, CLASS_CODE, CLASS_NAME, and MEAN_CONF.

Runtime Output Keys

result.outputs["hgm_class"]
result.outputs["wetland_polygons"]
result.outputs["confidence"]
result.outputs["summary"]
result.outputs["html_report"]

Common Questions

Q: Which output should I review first? A: Start with summary.class_distribution and polygon MEAN_CONF to see where class assignment is strong versus uncertain.

Q: What is a common interpretation mistake? A: Treating low-confidence class labels as definitive instead of field-check priorities.

Q: Which settings most change class results? A: The selected wetland_region pack and max_polygon_features can materially shift class balance and polygon granularity.

Q: How should wetland teams use these outputs? A: Use class and confidence together to prioritize field validation routes and regulatory documentation focus.

Results Delivery Checklist

• DEM and wetland mask dimensions were confirmed to match
• HGM class and confidence rasters were visually reviewed
• Wetland polygon attributes were spot-checked
• Summary class distribution and confidence ranges were reviewed

Purpose

Wetland Hydrogeomorphic Classification classifies wetlands by hydrologic source, outlet type, and geomorphic setting to predict ecological function and vulnerability. Outputs align with Ramsar and Cowardin wetland classification systems.

Background

Hydrogeomorphic (HGM) classification maps wetlands into functional setting classes by combining terrain position, hydrologic context, and connectivity cues. Conceptually, class assignment can be viewed as a rule-based partition over feature space:

$$c(x)=\arg\max_k;s_k(z_x)$$

Where $z_x$ is the local feature vector (relief, slope, wetness/connectivity indicators) and $s_k$ is class-specific evidence for class $k$.

Regional Calibration Rationale

HGM boundaries are physiographically dependent. Parameter packs calibrated to regional terrain-hydrology regimes reduce systematic bias that appears when one threshold set is transferred to different landscapes.

Confidence and Polygon Interpretation

Cell-level class confidence and polygon-level mean confidence should be interpreted together. Large polygons with low confidence often indicate transitional environments where field verification is required before regulatory or restoration commitments.

Methodological Considerations

• Confirm DEM conditioning quality; local relief artifacts can propagate directly into class logic.
• Use regional packs as priors, then validate against local wetland inventories where available.
• Cap polygon output volume thoughtfully so simplification does not erase operationally relevant heterogeneity.

Practical Interpretation Pitfalls

A frequent mistake is reading class codes as fixed ground truth regardless of confidence. These outputs are decision-support hypotheses that should be finalized with field evidence.

Inputs

Required runtime arguments:

• dem
• wetland_mask

Optional runtime arguments:

• max_polygon_features
• wetland_region
• output_prefix (required)

Parameters

Defaults and behavior:

• max_polygon_features defaults to 10000.
• wetland_region defaults to none and controls regional calibration thresholds.
• output_prefix is required.

Outputs

Primary runtime outputs:

• hgm_class
• wetland_polygons
• confidence
• summary
• html_report

wetland_polygons includes REGION_ID, CELL_COUNT, CLASS_CODE, CLASS_NAME, and MEAN_CONF.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.wetland_hydrogeomorphic_classification(
	dem="dem.tif",
	wetland_mask="wetlands.tif",
	wetland_region="temperate_forested",
	max_polygon_features=10000,
	output_prefix="wetland_hgm"
)

References

• Tool implementation: wbtools_pro/src/tools/workflow_products/wetland_hydrogeomorphic_classification.rs
• Ramsar Convention and Cowardin terminology (contextual alignment)

Parameter Interaction Notes

Prioritize sensitivity checks on profile/threshold settings that materially change output distributions and decision classes.

QA and Acceptance Criteria

Minimum acceptance:

• DEM and wetland mask dimensions match exactly.
• hgm_class and confidence rasters align in grid/extent.
• summary.class_distribution and polygon confidence fields are present and interpretable.

Advanced Operational Guidance

For production use, preserve run metadata, lock approved profiles, and version output packages for reproducibility and auditability.

Implementation Patterns

Common pattern: baseline run, sensitivity run on 1-2 parameters, then locked-profile production run for delivery.

Related Tools

See upstream conditioning and downstream validation tools in the same bundle for end-to-end workflow consistency.

When To Use This Workflow

Use Wetland Hydrogeomorphic Classification when you need repeatable, source-contract-aligned outputs for planning, reporting, and stakeholder review.

River Corridor Health Assessment

Purpose

River Corridor Health Assessment evaluates riparian buffer integrity, stream channel stability, vegetation composition, and hydrologic connectivity along river segments. Outputs health scores and recommendations for restoration priority.

Typical Questions This Tool Helps Answer

• Which river reaches have the lowest riparian integrity and should be prioritized for restoration investment this planning cycle?
• Where is DEM-derived erosion pressure highest along the stream network, and which segments are classified as At-Risk or Critical based on the health score?
• How does corridor health score vary across the watershed, and which tributary catchments drive the aggregate condition index?

Background

Environmental risk workflows are built around source-pathway-receptor logic: identify stressors, model transport or exposure pathways, and estimate consequence to assets or ecosystems. Inputs and model assumptions define the validity envelope, so uncertainty documentation is as important as the final risk score.

In practice, these tools are most defensible when used comparatively across scenarios, with explicit thresholds and confidence narratives. Interpretation should focus on rank ordering and mitigation prioritization, not absolute certainty.

River corridor health assessment integrates channel condition, riparian structure, and disturbance indicators into a multi-metric condition narrative. Trend consistency and local calibration are critical for fair reach-to-reach comparison.

Methodological Considerations

• Calibrate thresholds and class boundaries against local context whenever possible; transferred defaults should be treated as provisional.
• Evaluate scenario sensitivity explicitly so mitigation priorities are robust to uncertainty in assumptions.
• Keep lineage between assumptions, intermediate metrics, and summary outputs for audit-ready interpretation.

Practical Interpretation Pitfalls

A frequent mistake is interpreting risk classes as deterministic outcomes. These products are comparative planning aids and should be paired with field validation and expert review.

Inputs

Parameters

The runtime also accepts output as an alias for output_prefix.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Health classes and actions

Important summary fields

Returned payload keys

The workflow returns these output keys:

• erosion_pressure
• corridor_confidence
• stream_health_score
• restoration_zones
• summary
• html_report

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.river_corridor_health_assessment(
        dem="dem_10m.tif",
        streams="streams.gpkg",
        profile="balanced",
        restoration_priority_mode="cost_weighted",
        output_prefix="river_health_2026",
)

References

• Montgomery, D. R., & Buffington, J. M. (1997). Channel-reach morphology in mountain drainage basins. Geological Society of America Bulletin.
• Wohl, E. (2017). Connectivity in rivers. Progress in Physical Geography.

Parameter Interaction Notes

• profile changes the erosion-pressure raster and therefore can shift stream classes.
• restoration_priority_mode changes the ordering of restoration candidates, not whether a stream is stable or unstable.
• output_prefix controls one tightly linked delivery package of rasters, vectors, JSON, and HTML.

QA and Acceptance Criteria

1. Verify only dem and streams are documented as required inputs.
2. Verify the example uses the real runtime argument names.
3. Verify the GeoPackage field names match the documented schema.
4. Verify the summary JSON contains inputs, parameters, summary, interpretation, output_semantics, confidence_contract, interpretation_warnings, and outputs.
5. Verify the returned payload contains the documented output keys.
6. Verify class thresholds and restoration actions match the implementation.

The workflow fails if inputs are missing or unreadable, if profile or restoration_priority_mode is invalid, if a provided output prefix is empty, or if stream reprojection is needed but the stream layer lacks CRS EPSG metadata.

Advanced Operational Guidance

• Treat stream_health_score.gpkg as the primary classification layer and restoration_zones.gpkg as the intervention shortlist.
• Review EROS_P90 together with HEALTH to understand why otherwise similar streams may rank differently.
• Check the CRS harmonization block before operational use when source data came from multiple systems.
• If stream geometry is sparse, consider densifying it upstream of this workflow to sample erosion pressure more frequently.

Implementation Patterns

• Baseline screening run: profile=balanced, restoration_priority_mode=health_score_only.
• Cost-sensitive planning run: restoration_priority_mode=cost_weighted.
• Erosion-driven triage run: restoration_priority_mode=ecological_gradient.
• Delivery run: publish both rasters, both GeoPackages, the summary JSON, and the HTML report together.

Related Tools

• terrain_constraint_and_conflict_analysis
• utility_corridor_encroachment_intelligence
• wetland_hydrogeomorphic_classification

When To Use This Workflow

Use this workflow when you need a reproducible stream-health triage package derived from terrain and stream geometry, rather than a broad riparian inventory.

What this workflow helps you do:

• Classify streams into stable and restoration-needed groups.
• Compare different restoration ranking strategies.
• Deliver both spatial outputs and a summary that explains the ranking logic.

Results Delivery Checklist

1. Deliver both rasters, both GeoPackages, the summary JSON, and the HTML report together.
2. Record the selected profile and restoration_priority_mode.
3. Review the CRS harmonization block before downstream use.
4. Confirm class counts and urgency classification in the summary.
5. If budget scenarios are being used for planning, note which one informed the decision.

Common Questions

Q: Why can a stream move up or down in priority without changing class?
A: Because class is based on HEALTH, while priority ranking depends on the selected restoration_priority_mode.

Q: What is the main misinterpretation risk in this workflow?
A: Assuming it uses vegetation or land-use inputs. This workflow scores streams from DEM-derived erosion pressure sampled along the stream network.

Q: Which setting matters most for planning scenarios?
A: restoration_priority_mode, because it changes how non-stable streams are ordered for intervention.

Q: When should teams choose ecological_gradient?
A: Choose it when high erosion pressure should weigh more heavily than treatment efficiency or segment length.

Network Planning and Operations Bundle

Overview

The Network Planning and Operations bundle provides specialized tools for transportation and utility network analysis: service area optimization, route event management for linear-referenced assets, emergency response planning, and market/site accessibility. Supports logistics, infrastructure operations, and strategic siting.

Key Concepts

Service Area Analysis

Delineation of areas served by facilities (fire stations, hospitals, distribution centers) within specified time or distance thresholds. Identifies coverage gaps and overlap.

Linear Referencing and Route Events

Management of attributes (signs, guardrails, pavement condition, utilities) distributed along linear routes using measure values (distance along route) rather than Cartesian coordinates.

Accessibility and Connectivity

Evaluation of network connectivity and travel time/distance from origin nodes to destination areas, considering topography and infrastructure constraints.

Fleet Optimization

Algorithms for efficient vehicle routing, driver scheduling, and last-mile delivery optimization minimizing distance, time, and vehicle count.

Typical Workflows

Emergency Response Dispatch

1. Map critical facilities (schools, hospitals, high-density population)
2. Define coverage zones (e.g., response time ≤ 8 min)
3. Identify coverage gaps
4. Use Network Readiness and Diagnostics to verify path quality
5. Optimize Emergency Scenario Routing for rapid deployment

Utility Asset Management

1. Create linear route network (roads, utility corridors)
2. Establish linear referencing system (measure from route start)
3. Inventory assets (poles, transformers, valves) with route/measure location
4. Use Route Event Governance to track asset lifecycle (installation, maintenance, replacement)

Market Penetration Analysis

1. Identify customer base and competitor locations
2. Compute service areas and accessibility (Market Access and Site Planning)
3. Identify underserved areas and expansion opportunities
4. Optimize distribution network

Recommended Workflow Start Order

The workflow order below is a practical starting sequence that gets most teams to usable, validated outputs quickly:

1. Fleet Routing and Dispatch Optimizer
2. Network Readiness and Diagnostics
3. Service Area Planning and Coverage Optimization
4. Market Access and Site Planning
5. Emergency Accessibility Scenario Planning
6. Route Event Governance
7. Utility Corridor Access Planning
8. Parcel Fabric Topology Compliance

Performance Considerations

• Network Topology: Clean topology (no duplicate edges, proper connectivity) essential for accurate routing
• Impedance Factors: Travel time varies with speed limits, congestion, terrain; representative impedance model improves accuracy
• Node/Intersection Delay Modeling: For service-area driven workflows, optional node-entry costs (node_cost_points, node_cost_field, node_cost_snap_distance) capture intersection delays not represented by edge cost alone
• Coverage Thresholds: Drive-time isochrones vs. distance rings; drive-time more realistic but computationally heavier

References

• ESRI Network Analyst Best Practices
• APTA (American Public Transportation Association) Transit Guidelines

Recommended Results Package

For customer adoption, this bundle should be delivered as a KPI-driven operational improvement package.

Recommended package components:

1. Baseline network performance dashboard
2. Optimized scenario outputs with assumptions
3. Stress-test scenarios (disruption, demand surge, resource loss)
4. Change-management summary for dispatch and operations teams

This packaging improves executive confidence by connecting technical routing outputs directly to measurable service outcomes.

Deployment Notes

• Start with one tactical use case (dispatch optimization or service area gap closure), then extend to strategic planning cycles.
• Keep tactical and strategic parameter profiles separate to avoid overfitting day-to-day operations.
• Standardize KPI reporting across reruns (on-time rate, cost-to-serve, response time, utilization) for longitudinal performance tracking.

Fleet Routing and Dispatch Optimizer

Purpose

Fleet Routing and Dispatch Optimizer solves practical vehicle routing and dispatch scheduling under real operational constraints.

It supports:

• Multi-vehicle route planning
• Capacity-constrained dispatch
• Time-window-aware service sequencing
• Trade-off optimization (distance, time, fleet size)

Use this tool when dispatch decisions must be reproducible, explainable, and cost-accountable.

Typical Questions This Tool Helps Answer

• What is the lowest-cost dispatch plan that still respects capacity and time-window constraints?
• How many vehicles are actually required to meet today's service commitments?
• Which stops are most at risk of lateness or unmet demand under current fleet assumptions?

Problem Class

This tool addresses variants of VRP (Vehicle Routing Problem):

• CVRP: capacitated VRP
• VRPTW: VRP with time windows
• Multi-depot routing
• Soft-constraint scenarios with penalty costs

Background

Fleet routing and dispatch optimization solves a constrained vehicle-routing problem (VRP) where objective quality and operational feasibility must be balanced. A common scalarized form is:

$$\min\left(w_d D + w_t T + w_v V + w_p P\right)$$

Where $D$ is total distance, $T$ is total travel/service time, $V$ is vehicles used, and $P$ aggregates violation penalties (late arrivals, overtime, unmet demand).

Constraint System

Operational feasibility is defined by interacting constraints:

• Vehicle capacity and compatibility.
• Depot start/end and shift limits.
• Time-window feasibility at each stop.
• Service-time inclusion and break rules.

Small data-quality errors in any constraint dimension can invalidate apparently strong objective scores.

Solver Strategy and Trade-Offs

Practical pipelines often use fast constructive seeds (for example Clarke-Wright/sweep), then local or metaheuristic improvement (2-opt, relocate/swap, tabu, GA, annealing). The key trade-off is solve time versus marginal quality gain and scenario throughput.

Robustness and Scenario Use

Dispatch recommendations should be stress-tested under demand variance, closure events, and travel-time inflation. Robust plans maintain acceptable KPI behavior across perturbations, not only in a nominal run.

Methodological Considerations

• Validate constraint completeness before objective tuning.
• Compare alternative weight vectors to expose Pareto-like trade-offs.
• Report both objective values and violation diagnostics for governance.

Practical Interpretation Pitfalls

A lower objective score is not automatically operationally superior if it relies on brittle assumptions or pushes service equity below acceptable policy thresholds.

Inputs

Critical Input Hygiene

• Ensure network connectivity (no disconnected critical subgraphs)
• Use projected CRS for network/depots/stops (tool enforces projected CRS when known)
• Ensure demand and capacity units match (weight, volume, pallets, etc.)
• Ensure stop demand values are non-negative and realistic for fleet capacity

Vector Attribute Expectations

• depots attribute lookup priority for depot id: depot_id, DEPOT_ID, id, ID.
• stops attribute lookup priority for stop id: stop_id, STOP_ID, id, ID.
• stops demand field lookup: demand, DEMAND (default when missing: 1.0).
• stops service time field lookup: service_time_minutes, SERVICE_TIME_MINUTES, service_time, SERVICE_TIME (default when missing: 10.0).

vehicles_csv Schema (Authoritative)

Header (recommended):

vehicle_id,capacity,available_time_minutes,cost_per_minute,cost_per_km,depot_id

• Exactly 6 columns are required per non-empty row.
• Header row is optional but, if present, must include vehicle_id on row 1 to be auto-detected as header.
• capacity, available_time_minutes, cost_per_minute, and cost_per_km must parse as numeric values.

Example:

vehicle_id,capacity,available_time_minutes,cost_per_minute,cost_per_km,depot_id
truck_01,1200,540,0.65,1.20,depot_west
truck_02,800,480,0.58,1.05,depot_east

restrictions Schema (Optional)

Required columns:

from_x,from_y,to_x,to_y

Optional columns:

• penalty_factor (alias: penalty) default 1.0
• closed (alias: is_closed) default false

Accepted truthy values for closure: 1, true, yes, y (case-insensitive).

Example:

from_x,from_y,to_x,to_y,closed,penalty_factor
500120.0,4820030.0,500240.0,4820035.0,true,1.0
500300.0,4820100.0,500410.0,4820108.0,false,1.8

Parameters

objective

• minimize_distance: fuel and mileage focus
• minimize_time: SLA/response-time focus
• minimize_cost: direct optimization of (distance_km * cost_per_km) + (time_minutes * cost_per_minute)
• balanced: compromise score across distance, time, and cost

Output Path Parameters (Required)

• routes_output: path extension controls vector format (for example .shp, .geojson, .gpkg).
• assignment_csv_output: written as CSV with assignment rows.
• route_kpis_csv_output: written as CSV with per-route rows and a FLEET_TOTAL summary row.
• exceptions_csv_output: written as CSV with one row per failed stop assignment.

html_report

• If provided, an HTML summary file is generated in addition to CSV/vector outputs.
• HTML report includes run summary counts and key output paths for packaging.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Output File Schemas

routes_output attributes:

• ROUTE_ID
• VEHICLE_ID
• DEPOT_ID
• STOP_COUNT
• DIST_KM
• TIME_MIN
• COST

assignment_csv_output columns:

stop_id,route_id,vehicle_id,sequence_order,arrival_time_minutes,departure_time_minutes

route_kpis_csv_output columns:

vehicle_id,route_id,capacity_utilization_pct,distance_km,time_minutes,cost_units,stop_count

Notes:

• Includes a final fleet aggregate row with vehicle_id=FLEET_TOTAL and route_id=FLEET_TOTAL.

exceptions_csv_output columns:

stop_id,reason

Common reason values:

• demand_exceeds_max_vehicle_capacity
• no_feasible_route

Result Payload Keys

In addition to output files, the run result contains keys for orchestration and auditing:

• status
• routes_count
• stops_assigned
• stops_failed
• objective
• routes
• assignment_csv
• route_kpis_csv
• exceptions_csv
• summary
• html_report (only when requested)

Interpreting KPIs in route_kpis_csv_output

• capacity_utilization_pct: percentage of route capacity consumed by assigned stop demand.
• distance_km: full loop distance including return to depot.
• time_minutes: travel plus service time, including return leg travel time.
• cost_units: computed from distance and time using per-vehicle coefficients.

Validation Workflow

Before Operational Use

1. Run baseline scenario with historical dispatch data
2. Compare against known outcomes (distance, overtime, late stops)
3. Validate stop sequence plausibility with dispatch team

Sensitivity Testing

1. Vary demand by +/-10%
2. Remove one vehicle and compare service impact
3. Tighten time windows and inspect infeasibility growth

Field Validation

1. Pilot with one depot/day
2. Capture driver deviations and ground truth constraints
3. Feed corrections back into network and timing assumptions

Troubleshooting

Example: Daily Last-Mile Dispatch

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()
wbe.working_directory = "/data/logistics_daily"

wbe.fleet_routing_and_dispatch_optimizer(
        network="metro_network.shp",
        depots="depots.shp",
        stops="orders_2026_05_14.shp",
        vehicles_csv="fleet_profile.csv",
        objective="balanced",
        restrictions="road_restrictions.csv",
        edge_cost_field="MINUTES",
        routes_output="out/routes_2026_05_14.geojson",
        assignment_csv_output="out/assignment_2026_05_14.csv",
        route_kpis_csv_output="out/kpis_2026_05_14.csv",
        exceptions_csv_output="out/exceptions_2026_05_14.csv",
        html_report="out/fleet_dispatch_2026_05_14.html"
)

Any WbEnvironment instance name is valid (wbe above is only an example).

Example: Emergency Utility Service Calls

wbe.fleet_routing_and_dispatch_optimizer(
        network="utility_response_network.shp",
        depots="service_crews.shp",
        stops="incident_calls.shp",
        vehicles_csv="crew_truck_capabilities.csv",
        objective="minimize_time",
        edge_cost_field="MINUTES",
        routes_output="out/utility_routes.geojson",
        assignment_csv_output="out/utility_assignments.csv",
        route_kpis_csv_output="out/utility_kpis.csv",
        exceptions_csv_output="out/utility_exceptions.csv"
)

Implementation Practices

• Store each run with a scenario ID and immutable input snapshot
• Publish only routes that pass dispatch sanity checks
• Maintain separate tactical (fast) and strategic (deep) optimization profiles

Related Tools

• network_readiness_and_diagnostics_intelligence
• service_area_planning_and_coverage_optimization
• emergency_scenario_routing_and_accessibility_simulator

References

• Toth, P., & Vigo, D. (2014). Vehicle Routing: Problems, Methods, and Applications (2nd ed.). SIAM.
• Laporte, G. (2009). Fifty years of vehicle routing. Transportation Science, 43(4), 408-416.

Parameter Interaction Notes

For Fleet Routing and Dispatch Optimizer, output quality is most sensitive to parameter combinations rather than single values in isolation.

• objective and vehicle cost coefficients interact strongly: - minimize_cost only behaves as expected when cost_per_minute and cost_per_km are calibrated to real economics. - balanced can reduce extreme route shapes but may not minimize any single KPI.
• available_time_minutes and service_time_minutes jointly control assignment feasibility; high service durations can dominate travel-time improvements.
• Restriction closures (closed=true) can rapidly increase infeasibility; inspect exceptions_csv_output after each closure scenario.

QA and Acceptance Criteria

Use a staged acceptance approach for Fleet Routing and Dispatch Optimizer:

1. Input integrity: validate projected CRS, network connectivity, depot-stop coverage, and CSV schema correctness.
2. Method validity: run a pilot dispatch day and compare route order against dispatch-team expectation.
3. Output plausibility: verify route loops return to depot and KPI magnitudes are operationally realistic.
4. Reproducibility: rerun with identical inputs and confirm stable assignment/KPI outputs.

Recommended acceptance checks:

• Every output artifact exists at the requested path.
• assignment_csv_output rows are consistent with route stop counts.
• route_kpis_csv_output contains the final FLEET_TOTAL row.
• exceptions_csv_output reasons are explainable and actionable.

Advanced Operational Guidance

For production deployment of Fleet Routing and Dispatch Optimizer:

• Maintain a versioned parameter profile (e.g., exploratory, standard, compliance).
• Store run metadata with input hashes, parameter JSON, and timestamp for auditability.
• Lock route output format by extension (for example, .gpkg for enterprise geodatabases, .geojson for interoperability).
• Use scenario-specific restrictions files rather than editing network geometry for temporary closures.

Implementation Patterns

Common implementation patterns with Fleet Routing and Dispatch Optimizer:

• Baseline run: produce first-pass outputs with balanced defaults.
• Sensitivity run: vary 1-2 high-impact parameters to assess stability.
• Production run: lock accepted profile and generate deliverables.
• Monitoring run: repeat with identical profile on new data for change tracking.

Related Tools

Use Fleet Routing and Dispatch Optimizer together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Fleet Routing and Dispatch Optimizer is most valuable when teams need measurable service-level improvements (coverage, response time, cost-to-serve) with governance-ready transparency.

What this workflow helps you achieve:

• Translates network complexity into decision-ready options.
• Supports defensible operational planning with explicit constraints.
• Creates repeatable workflows for quarterly and annual optimization cycles.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Confirm objective function matches business KPI priorities.
3. Document constraints (capacity, time windows, exclusions) in deliverable notes.
4. Provide baseline-vs-optimized comparison metrics.
5. Include at least one scenario stress test (demand spike, outage, or route closure).

Common Questions

Q: Which result should I review first? A: Start with baseline-vs-optimized KPI changes for coverage, response time, and cost-to-serve.

Q: What is a common interpretation mistake? A: Assuming a better objective score means the plan is deployable without verifying all constraints are respected.

Q: Which settings most affect recommended routes? A: Demand assumptions, enabled constraints, and objective weighting usually have the largest effect on dispatch outcomes.

Q: How should teams use these outputs operationally? A: Pilot the optimized schedule in a controlled service window, compare realized KPIs to baseline, then scale rollout if performance holds.

Network Readiness and Diagnostics

Purpose

Network Readiness and Diagnostics validates network topology and connectivity, identifies missing edges/nodes, and rates overall network quality and fitness for routing analysis.

Typical Questions This Tool Helps Answer

• Is this network ready for routing and optimization, or do data-quality issues make results unreliable?
• Where are the key topology defects (dead ends, disconnected components, broken continuity) that need correction?
• Does the current dataset pass readiness gates for production decision workflows?

Background

Network readiness diagnostics assess whether a transport graph is fit for optimization and scenario analysis. In a weighted graph $G=(V,E,w)$, path cost is typically:

$$c(P)=\sum_{e\in P} w(e)$$

So missing or inconsistent impedance attributes directly bias travel-time, accessibility, and optimization outcomes.

Readiness Dimensions

• Topological validity: connectivity, dangling structures, disconnected components, turn-model consistency.
• Impedance completeness: travel-time/speed consistency, directional restrictions, temporal rule coverage.
• Operational expressiveness: representation of capacities, time windows, closures, and policy constraints.

Diagnostic Metrics and Decision Use

A practical readiness approach combines structural metrics (for example component count, invalid edge ratio) with operational metrics (for example constrained-route solvability rate). The objective is not only data correctness, but decision stability under realistic operating assumptions.

Methodological Considerations

• Run diagnostics before optimization; post-hoc quality checks are far more expensive.
• Track metric drift across data refreshes to detect silent regression in network quality.
• Include stress scenarios (closure sets, demand spikes) to evaluate robustness of the modeled rules.

Practical Interpretation Pitfalls

Passing a single QA indicator can hide major operational blind spots. Readiness should be judged as a composite gate, not a one-metric pass/fail.

Inputs

Input Requirements

• network must contain line geometries (LineString or MultiLineString).
• If CRS is known, projected CRS is required for reliable geometric diagnostics.
• Networks with no usable vertices fail fast.

Parameters

Output Path Behavior

• diagnostics_layer format is inferred from file extension.
• If extension cannot be resolved, writer falls back to GeoJSON.
• Parent directory for diagnostics_layer is created automatically if needed.

Outputs

Runtime output keys (returned in ToolRunResult.outputs):

QA Findings CSV Schema (qa_report)

severity,check_type,count,description,feature_ids_sample

feature_ids_sample is semicolon-delimited in-cell text.

Diagnostics Layer Schema (diagnostics_layer)

Geometry type: Point

Attributes:

• CHECK_TYPE
• SEVERITY
• MESSAGE

Common CHECK_TYPE values:

• dead_end
• disconnected_component
• disconnected_edge

Readiness JSON Schema (readiness_score)

Top-level keys:

• overall_score
• connectivity_score
• cost_consistency_score
• pass_fail_gate
• fragmentation_penalty
• unreachability_penalty
• cost_variance_zscore
• assessment_timestamp
• schema_version

Scoring Logic (Current Implementation)

The current implementation computes:

• Connected-component structure from network topology
• Dead-end node counts
• Cost-consistency outliers from geometric segment-length variance

Current score formula:

$$ \text{connectivity_score} = 100,(1 - p_f - p_u) $$

$$ \text{cost_consistency_score} = 100,\left(1 - \min\left(\frac{z}{5},1\right)\right) $$

$$ \text{overall_score} = 0.6,\text{connectivity_score} + 0.4,\text{cost_consistency_score} $$

Where:

• $p_f$ is fragmentation_penalty
• $p_u$ is unreachability_penalty
• $z$ is cost_variance_zscore

Pass/fail gate is true only when all conditions are met:

• overall_score >= 80
• fragmentation_penalty < 0.1
• unreachability_penalty < 0.05

Example

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()
wbe.network_readiness_and_diagnostics_intelligence(
        network="road_network.shp",
        qa_report="out/network_readiness_findings.csv",
        diagnostics_layer="out/network_readiness_diagnostics.geojson",
        readiness_score="out/network_readiness_score.json",
        html_report="out/network_readiness_report.html"
)

Any WbEnvironment instance name is valid (wbe above is only an example).

References

• Rigaux, P., Scholl, M. O., & Voisard, A. (2002). Spatial Databases with Application to GIS. Morgan Kaufmann.

Parameter Interaction Notes

For Network Readiness and Diagnostics, output quality is most sensitive to parameter combinations rather than single values in isolation.

• Small disconnected subnetworks can sharply reduce pass/fail status even when most of the network is visually complete.
• Dense cul-de-sac neighborhoods increase dead-end diagnostics; treat these as context-sensitive, not automatically incorrect.
• Very uneven segment-length distributions increase cost_variance_zscore and depress cost_consistency_score.

QA and Acceptance Criteria

Use a staged acceptance approach for Network Readiness and Diagnostics:

1. Input integrity: validate projected CRS, line geometry type, and non-empty network extent.
2. Method validity: verify expected dead-end and disconnected-area diagnostics against known weak zones.
3. Output plausibility: confirm diagnostics layer aligns spatially with topology defects.
4. Reproducibility: rerun with identical inputs and confirm stable findings and score outputs.

Recommended acceptance checks:

• qa_report exists and includes header row plus expected check types.
• diagnostics_layer contains features when known defects are present.
• readiness_score includes all documented keys.
• Pass/fail gate matches expected policy for known-good and known-bad test networks.

Advanced Operational Guidance

For production deployment of Network Readiness and Diagnostics:

• Maintain a versioned readiness policy (score thresholds and remediation SLA).
• Store run metadata with input hashes, parameter JSON, and timestamp for auditability.
• Gate downstream routing/service-area tools on pass_fail_gate where governance requires it.
• Track recurring disconnected components to prioritize durable network editing backlogs.

Implementation Patterns

Common implementation patterns with Network Readiness and Diagnostics:

• Baseline run: score the current authoritative network snapshot.
• Remediation run: fix flagged defects and rerun readiness scoring.
• Release gate run: require pass before publishing operational route products.
• Monitoring run: rerun after network updates or quarterly governance checkpoints.

Related Tools

Use Network Readiness and Diagnostics together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Network Readiness and Diagnostics is most valuable when teams need reliable routing and coverage outputs backed by an auditable network QA gate.

What this workflow helps you achieve:

• Converts topology quality into a measurable go/no-go readiness decision.
• Reduces false confidence in downstream routing analyses.
• Creates a repeatable QA cycle for network maintenance governance.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Verify readiness scoring and pass/fail gate against agreed thresholds.
3. Document each finding class and remediation owner.
4. Provide before/after scores for remediated network versions.
5. Include at least one known-defect regression case in acceptance evidence.

Common Questions

Q: Why did the readiness score drop even though we only edited a small area?
A: A small disconnected edit can increase both fragmentation and unreachability penalties, which heavily influence the overall score and gate.

Q: Why are we seeing many dead-end warnings in suburban neighborhoods?
A: Dead-end checks are structural and include cul-de-sacs; treat them as review flags, then classify valid cul-de-sacs separately from true data defects.

Q: Does this tool use our travel-time impedance field directly?
A: Current implementation derives cost-consistency from geometric segment-length variance; if policy requires impedance-field QA, pair this with dedicated impedance validation tooling.

Service Area Planning and Coverage Optimization

Purpose

Service Area Planning and Coverage Optimization delineates areas reachable from facilities (ambulance stations, distribution centers, cell towers) within time, distance, or cost thresholds. Identifies coverage gaps, overlap, and optimization opportunities.

Use this tool for coverage diagnostics around an existing facility network. For candidate site generation/selection workflows (for example top-N new-site selection), use market_access_and_site_intelligence_workflow.

Typical Questions This Tool Helps Answer

• Which neighborhoods are reachable from our current facilities within 5, 10, and 15 minutes?
• Where are the uncovered demand gaps after applying realistic travel-time, turn, and impedance constraints?
• If one or more facilities close, how much coverage do we lose and where?

Background

Service-area planning estimates reachability from facilities under impedance constraints, then uses demand overlays to evaluate coverage quality and candidate expansion strategies.

For a demand location $i$ and facility set $F$, a common reachability criterion is:

$$\min_{f\in F} c(i,f) \le \tau$$

Where $c(i,f)$ is network travel cost and $\tau$ is a service threshold (for example response-time target).

Coverage and Equity Framing

Coverage optimization can be represented as maximizing covered demand mass under budget/facility constraints:

$$\max \sum_i d_i z_i, \quad z_i\in{0,1}$$

With optional equity controls to prevent improvements that systematically bypass low-access populations.

Methodological Considerations

• Validate impedance and turn restrictions before catchment construction.
• Evaluate multiple threshold values ($\tau$) to expose sensitivity of underserved-area mapping.
• Compare baseline and candidate-network states under disruption scenarios, not just normal operating conditions.

Practical Interpretation Pitfalls

Common mistakes include reading coverage gain without equity context, ignoring threshold sensitivity, and over-trusting edge-of-network catchments where data quality is weaker.

Inputs

Input Requirements

• network must contain line geometries.
• facilities must contain point geometries.
• If CRS is known, projected CRS is required.
• ring_costs must be numeric and strictly greater than zero.
• scenarios file path must exist when provided.
• candidate_sites is required when optimization_mode=expansion and candidate_mode=user_supplied.

scenarios CSV Schema (Authoritative)

Expected columns (in order):

scenario_id,facility_id,is_open,capacity

capacity is optional.

Accepted truthy values for is_open: 1, true, yes, y, open.

Example:

scenario_id,facility_id,is_open,capacity
all_open,1,true,100
all_open,2,true,100
one_open,1,true,100
one_open,2,false,0

Temporal Profile CSV Schema (Time-of-Day Routing)

The temporal_cost_profile CSV uses one row per edge and time window.

Expected columns:

edge_id,dow,start_minute,end_minute,value

Column definitions:

• edge_id: Edge key matching temporal_edge_id_field in the network layer.
• dow: Day of week (1..7, Monday=1).
• start_minute: Inclusive minute-of-day (0..1439).
• end_minute: Exclusive minute-of-day (1..1440, must be greater than start_minute).
• value: Positive temporal modifier.

temporal_mode determines how value is interpreted:

• multiplier: applies value as a multiplier to static edge cost.
• absolute: treats value as the full edge cost for that time window.

Example (weekday AM peak slowdown on selected edges):

edge_id,dow,start_minute,end_minute,value
A_B,1,420,600,1.8
B_C,1,420,600,1.6
A_B,2,420,600,1.8
B_C,2,420,600,1.6

Set temporal_fallback to:

• static_cost to use non-temporal impedance when no matching row exists.
• error to fail fast when a temporal row is missing.

Parameters

Output Path Behavior

• Vector format is inferred from extension for service_areas and uncovered_demand.
• Unsupported vector extensions fail validation.
• html_report is emitted only when path is provided.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

uncovered_demand Schema

Geometry type: Point

Attributes:

• demand_id

scenario_summary_csv Schema

scenario_id,total_demand_covered_pct,avg_accessibility,outlier_count

Notes:

• Includes a baseline row.
• total_demand_covered_pct is coverage percentage.
• avg_accessibility is currently populated from the largest configured ring cost.

ranked_candidates_csv Schema

candidate_id,coverage_gain_pct,avg_network_travel_cost,rank

Result Payload Keys

• service_areas
• uncovered_demand
• scenario_summary_csv
• ranked_candidates_csv
• summary
• html_report (when requested)

Example

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()
wbe.service_area_planning_and_coverage_optimization(
        network="road_network.shp",
        facilities="fire_stations.shp",
        demand_points="residential_blocks.shp",
        ring_costs=[4.0, 8.0, 12.0],
        service_area_merge_origins=True,
        scenarios="coverage_scenarios.csv",
        service_areas="out/service_areas.geojson",
        uncovered_demand="out/uncovered_demand.geojson",
        scenario_summary_csv="out/scenario_summary.csv",
        ranked_candidates_csv="out/ranked_candidates.csv",
        html_report="out/service_area_report.html"
)

The example below adds time-of-day routing and turn penalties for a peak-hour coverage analysis.

wbe.service_area_planning_and_coverage_optimization(
        network="road_network.shp",
        facilities="fire_stations.shp",
        demand_points="residential_blocks.shp",
        ring_costs=[4.0, 8.0, 12.0],
        scenarios="coverage_scenarios.csv",
        edge_cost_field="MINUTES",
        one_way_field="ONEWAY",
        node_cost_points="intersection_delay_points.shp",
        node_cost_field="DELAY_MIN",
        node_cost_snap_distance=25.0,
        turn_penalty=0.3,
        u_turn_penalty=2.0,
        forbid_u_turns=True,
        temporal_cost_profile="am_peak_profiles.csv",
        temporal_edge_id_field="EDGE_ID",
        departure_time="2024-06-15T08:00:00Z",
        temporal_mode="multiplier",
        temporal_fallback="static_cost",
        service_areas="out/service_areas_am_peak.geojson",
        uncovered_demand="out/uncovered_demand_am_peak.geojson",
        scenario_summary_csv="out/scenario_summary_am_peak.csv",
        ranked_candidates_csv="out/ranked_candidates_am_peak.csv",
        html_report="out/service_area_report_am_peak.html"
)

Any WbEnvironment instance name is valid (wbe above is only an example).

Isochrone Map Recipe (Pro Tier)

To produce map-ready drive-time isochrones from facilities:

1. Set ring_costs to your target bands (for example [5, 10, 15] minutes).
2. Use a travel-time edge impedance field (for example edge_cost_field="MINUTES").
3. Write service_areas to a polygon-capable output format (.gpkg, .geojson, .shp).
4. Optionally add turn_penalty, u_turn_penalty, and node_cost_points for realistic intersection behavior.
5. Optionally add temporal_cost_profile + departure_time for time-of-day isochrones.

Minimal multi-band isochrone example:

wbe.service_area_planning_and_coverage_optimization(
        network="road_network.gpkg",
        facilities="clinics.gpkg",
        ring_costs=[5.0, 10.0, 15.0],
        edge_cost_field="MINUTES",
        one_way_field="ONEWAY",
        service_areas="out/isochrones_5_10_15.gpkg",
        uncovered_demand="out/uncovered.gpkg",
        scenario_summary_csv="out/scenario_summary.csv",
        ranked_candidates_csv="out/ranked_candidates.csv"
)

References

• Church, R., & ReVelle, C. (1974). "The Maximal Covering Location Problem." Papers and Proceedings of the Regional Science Association 32(1), 101–118.

Parameter Interaction Notes

For Service Area Planning and Coverage Optimization, output quality is most sensitive to parameter combinations rather than single values in isolation.

• Wider ring_costs raise coverage but can reduce discriminative power in candidate ranking.
• Sparse facilities can produce high uncovered-demand counts even with large rings when network topology is fragmented.
• Scenario toggles in scenarios can shift rank ordering substantially; compare against baseline before acting.

QA and Acceptance Criteria

Use a staged acceptance approach for Service Area Planning and Coverage Optimization:

1. Input integrity: validate projected CRS, network/facility geometry types, and positive ring costs.
2. Method validity: verify baseline coverage against known served and unserved demand points.
3. Output plausibility: confirm uncovered demand points are outside generated service polygons.
4. Reproducibility: rerun with identical inputs and confirm stable scenario and ranking outputs.

Recommended acceptance checks:

• All four required output artifacts are present and readable.
• scenario_summary_csv includes baseline and any scenario IDs supplied.
• ranked_candidates_csv ranks candidates from 1..N with no missing IDs.
• uncovered_demand feature count aligns with expected coverage gaps.

Advanced Operational Guidance

For production deployment of Service Area Planning and Coverage Optimization:

• Maintain fixed ring profiles (e.g., tactical, planning, policy) and avoid ad hoc threshold drift.
• Store run metadata with input hashes, parameter JSON, and timestamp for auditability.
• Use scenario IDs that map directly to planning decisions (for example, depot closure simulations).
• Gate relocation recommendations on consistent baseline-vs-scenario deltas.

Implementation Patterns

Common implementation patterns with Service Area Planning and Coverage Optimization:

• Baseline run: produce current-state service area and uncovered-demand diagnostics.
• Scenario run: toggle facilities via scenarios CSV for closure/expansion analysis.
• Candidate run: compare rank shifts using ranked_candidates_csv.
• Release run: publish decision package with baseline + scenario evidence.

Related Tools

Use Service Area Planning and Coverage Optimization together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Service Area Planning and Coverage Optimization is most valuable when teams need defendable service-coverage decisions across baseline and what-if facility scenarios.

What this workflow helps you achieve:

• Converts network accessibility into scenario-ready planning evidence.
• Quantifies uncovered demand to support expansion or relocation decisions.
• Creates a repeatable coverage governance workflow.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Confirm ring-cost profile aligns with policy and service-level commitments.
3. Document baseline and scenario assumptions in the deliverable package.
4. Provide uncovered-demand deltas and candidate rank changes.
5. Include at least one stress scenario (closure or demand shift).

Common Questions

Q: Why did candidate ranking change so much after a small ring-cost change?
A: Candidate ranking is sensitive to threshold cutoffs; small ring adjustments can move many demand points across covered/uncovered boundaries.

Q: What does avg_accessibility represent in the scenario summary?
A: In current implementation it is populated from the largest configured ring-cost threshold and should be interpreted as a planning proxy, not a per-demand mean travel-time statistic.

Q: Why do we still have uncovered demand with large service rings?
A: Uncovered points often indicate network disconnects or facility placement limitations, not just threshold selection.

Market Access and Site Planning

Purpose

Market Access and Site Planning evaluates market accessibility, trade area definition, site suitability for retail/commercial facilities, and competitive positioning. Supports site selection and market penetration strategy.

Typical Questions This Tool Helps Answer

• Which candidate site gives the strongest coverage gain with acceptable competitive overlap?
• Are we under-served, balanced, or saturated in each target area?
• How do candidate rankings change under peak-hour impedance and routing restrictions?

Background

Network planning workflows use graph-theoretic representations of roads, routes, or linear assets, where node-edge topology and impedance attribution directly control results. Missing restrictions, incorrect turn logic, or stale demand assumptions can dominate outcome quality.

These tools are best interpreted as constrained optimization and diagnostics frameworks. Decisions should be based on trade-offs across service, resilience, and cost objectives rather than any single metric.

Market-access intelligence merges catchment logic, travel impedance, and competitive overlap to rank candidate sites. Decision confidence improves when sensitivity to demand assumptions is explicitly reviewed.

Methodological Considerations

• Topology validation should precede optimization or scenario simulation.
• Explicitly represent operational constraints (time windows, restrictions, capacities, closures) before comparing objective outcomes.
• Test outcomes under stress scenarios so selected plans remain stable under realistic disruptions.

Practical Interpretation Pitfalls

Single-metric improvements can hide degraded resilience or equity; compare candidate plans across multiple KPIs and scenario conditions.

Inputs

Role Split (Important)

• sites_existing: your incumbent baseline sites used for existing coverage and coverage-gain calculations.
• competition_sites: optional separate competitor layer used for overlap pressure.
• If competition_sites is not provided, overlap is computed against sites_existing.
• For most business scenarios, place your current sites in sites_existing and other providers in competition_sites.

Parameters

• ring_costs (required): JSON array of positive numeric thresholds, for example [5.0, 10.0, 15.0].
• The model uses max(ring_costs) as the catchment threshold.
• Units follow your network impedance units.

Candidate Generation and Selection

• candidate_mode (optional): user_supplied (default) or generated.
• num_sites_to_select (optional, default 1): number of top sites to flag as selected.
• selection_strategy (optional, default single_best): single_best or top_k_greedy.
• min_new_site_separation (optional): minimum separation distance between selected sites.
• max_generated_candidates (optional, default 250): max generated seed candidates when candidate_mode="generated".

Optional Routing Cost Parameters

Forwarded routing parameters:

• cost_method
• edge_cost_field
• one_way_field (accepts FT/TF/B codes and legacy boolean values)
• mode_field
• default_mode_speed
• mode_speed_overrides
• allowed_modes
• temporal_cost_profile
• temporal_edge_id_field
• departure_time
• temporal_mode
• temporal_fallback
• turn_penalty
• u_turn_penalty
• forbid_u_turns
• forbid_left_turns
• forbid_right_turns
• turn_restrictions_csv
• node_cost_points
• node_cost_field
• node_cost_snap_distance

How Ranking Works

Per candidate site:

• Demand coverage percent: share of demand points within threshold.
• Average distance to demand: mean network cost to demand points.
• Competitive overlap percent: share of competitor points within threshold.
• Accessibility score: normalized inverse average-distance score on a 0-100 scale.
• Composite rank score: 0.50 * demand_coverage_pct + 0.25 * accessibility_score + 0.25 * (100 - competitive_overlap_pct).

Opportunity band definitions:

• expand_now: composite >= 80, coverage gain > 5, overlap < 40
• pilot: composite >= 65 and coverage gain > 0
• saturated: overlap >= 60
• monitor: everything else

Outputs

Map interpretation note:

• catchments_output stores one polygon per candidate site; these are candidate trade-area polygons, not separate ring-band isochrone polygons.
• Catchments are built as convex hulls of covered demand points plus each candidate point.
• When a hull cannot be formed (insufficient valid geometry), a small fallback square polygon is written.
• overlap_analysis_output is a point layer. If you see squares there, it is typically point marker symbology.

Runtime output keys (returned in ToolRunResult.outputs):

catchments_output fields

• SITE_ID, COV_PCT, ACC_SCORE, OVR_PCT, RANK

overlap_analysis_output fields

• SITE_ID, OVR_PCT, GAIN_PCT, OPP_BAND, CMP_SCORE, TOT_COMP

candidate_rank_csv columns

rank,site_id,x,y,demand_coverage_pct,coverage_gain_pct,unmet_demand_count,avg_distance_to_demand,competitive_overlap_pct,accessibility_score,composite_rank_score,opportunity_band,selected_in_top_k

market_action_queue_csv columns (optional)

rank,site_id,opportunity_band,coverage_gain_pct,composite_rank_score,recommended_action

executive_summary_json keys

• analysis_timestamp, schema_version, total_candidates_evaluated, total_demand_points
• market_metrics, top_ranked_candidates, decision_rationale, recommendation, decision_gate

Decision gate rule:

• decision_gate=true when average candidate coverage is above 70% and average overlap is below 50%.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.market_access_and_site_intelligence_workflow(
  network="street_network.gpkg",
  sites_existing="existing_sites.gpkg",
  sites_candidates="candidate_sites.gpkg",
  demand_surface="demand_points.gpkg",
  competition_sites="competitors.gpkg",
  ring_costs=[5.0, 10.0, 15.0],
  catchments_output="outputs/candidate_catchments.gpkg",
  overlap_analysis_output="outputs/competitive_overlap.gpkg",
  candidate_rank_csv="outputs/candidate_ranking.csv",
  executive_summary_json="outputs/market_summary.json",
  market_action_queue_csv="outputs/market_action_queue.csv",
  html_report="outputs/market_access_report.html"
)

Generated-candidate mode with temporal and turn-aware routing:

env.market_access_and_site_intelligence_workflow(
  network="street_network.gpkg",
  sites_existing="existing_sites.gpkg",
  demand_surface="demand_points.gpkg",
  competition_sites="competitors.gpkg",
  ring_costs=[5.0, 10.0, 15.0],
  candidate_mode="generated",
  selection_strategy="top_k_greedy",
  num_sites_to_select=5,
  min_new_site_separation=1000.0,
  max_generated_candidates=250,
  edge_cost_field="MINUTES",
  one_way_field="ONEWAY",
  node_cost_points="intersection_delay_points.shp",
  node_cost_field="DELAY_MIN",
  node_cost_snap_distance=25.0,
  turn_penalty=0.3,
  u_turn_penalty=2.0,
  forbid_u_turns=True,
  temporal_cost_profile="am_peak_profiles.csv",
  temporal_edge_id_field="EDGE_ID",
  departure_time="2024-06-15T08:00:00Z",
  temporal_mode="multiplier",
  temporal_fallback="static_cost",
  catchments_output="outputs/candidate_catchments_peak.gpkg",
  overlap_analysis_output="outputs/competitive_overlap_peak.gpkg",
  candidate_rank_csv="outputs/candidate_ranking_peak.csv",
  executive_summary_json="outputs/market_summary_peak.json",
  market_action_queue_csv="outputs/market_action_queue_peak.csv",
  html_report="outputs/market_access_report_peak.html"
)

References

• Huff, D. L. (1963). "A Probabilistic Analysis of Shopping Center Trade Areas." Land Economics 39(1), 81–90.

Parameter Interaction Notes

ring_costs selection is the highest-impact control:

• Lower thresholds produce tighter catchments and usually lower overlap.
• Higher thresholds increase coverage and often increase overlap in dense markets.
• Always interpret scores in context of demand-point quality and completeness.

QA and Acceptance Criteria

Use a staged acceptance approach for Market Access and Site Planning:

1. Validate projected CRS and non-empty network/candidate/demand point inputs.
2. Confirm all required output paths are set and writable.
3. Verify candidate ranking aligns with known market context.
4. Re-run with same inputs to confirm deterministic outputs.

Recommended acceptance checks:

• Candidate count in CSV matches evaluated candidate points.
• Output layers contain expected attribute fields.
• Executive summary includes valid top candidates and decision gate.

Advanced Operational Guidance

For production deployment of Market Access and Site Planning:

• Keep demand and competitor snapshots date-stamped for consistent comparisons.
• Use the action queue as a planning filter, then run standard site due diligence before commitment.

Implementation Patterns

Common implementation patterns with Market Access and Site Planning:

• Baseline run with current market snapshot.
• Sensitivity run with alternate ring_costs arrays.
• Governance run with archived summary JSON and ranking CSV.

Related Tools

Use Market Access and Site Planning together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Market Access and Site Planning is most valuable when teams need measurable service-level improvements (coverage, response time, cost-to-serve) with governance-ready transparency.

What this workflow helps you achieve:

• Translates network complexity into decision-ready options.
• Supports defensible operational planning with explicit constraints.
• Creates repeatable workflows for quarterly and annual optimization cycles.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Confirm objective function matches business KPI priorities.
3. Document constraints (capacity, time windows, exclusions) in deliverable notes.
4. Provide baseline-vs-optimized comparison metrics.
5. Include at least one scenario stress test (demand spike, outage, or route closure).

Common Questions

Q: Why does a high-coverage candidate sometimes rank lower?
A: Ranking also penalizes high competition overlap and poor relative accessibility.

Q: What does decision_gate=false mean?
A: Average candidate coverage did not exceed 70% and/or average overlap was not below 50%.

Q: Are catchments true isochrone polygons?
A: Current implementation outputs hull-based catchment polygons from covered demand points.

Q: Can polygon demand data be used directly?
A: Convert polygon demand to centroid points first for reliable scoring.

Emergency Accessibility Scenario Planning

Purpose

Emergency Accessibility Scenario Planning computes rapid-response dispatch routes from emergency facilities (fire, police, ambulance) under multiple scenarios (blocked roads, facility unavailability, cascading demand), enabling contingency planning and resilience assessment.

Typical Questions This Tool Helps Answer

• Under each disruption scenario, which populations and facilities fall outside our response-time targets?
• Which scenario produces the worst accessibility loss and by how much versus baseline?
• Which closure or blockage assumptions should be prioritized for mitigation planning?

Background

Network planning workflows use graph-theoretic representations of roads, routes, or linear assets, where node-edge topology and impedance attribution directly control results. Missing restrictions, incorrect turn logic, or stale demand assumptions can dominate outcome quality.

These tools are best interpreted as constrained optimization and diagnostics frameworks. Decisions should be based on trade-offs across service, resilience, and cost objectives rather than any single metric.

Emergency routing simulation stress-tests accessibility under disruptions, closures, and demand spikes. Value comes from comparing resilience trade-offs across scenarios rather than relying on single-run outputs.

Methodological Considerations

• Topology validation should precede optimization or scenario simulation.
• Explicitly represent operational constraints (time windows, restrictions, capacities, closures) before comparing objective outcomes.
• Test outcomes under stress scenarios so selected plans remain stable under realistic disruptions.

Practical Interpretation Pitfalls

Single-metric improvements can hide degraded resilience or equity; compare candidate plans across multiple KPIs and scenario conditions.

Inputs

Parameters

• scenario_template (optional): custom, flood, wildfire, earthquake.
• scenario_block_source_field (optional): network field used with blocked_value to block scenario edges.
• baseline_service_areas (required): baseline output polygons path.
• worst_case_service_areas (required): worst-scenario output polygons path.
• scenario_summary_csv (required): scenario KPI output CSV path.
• simulation_report (required): summary JSON output path.
• html_report (optional): optional HTML report path.

Optional Routing Cost Parameters

Scenario CSV Rules

Required columns:

• scenario_id
• max_cost_multiplier

Optional column:

• blocked_value

Notes:

• Quoted commas are supported.
• max_cost_multiplier must be finite and > 0.
• Blank rows are ignored.

Template checks:

• flood: requires block-source field and at least one blocked_value; all multipliers must be <= 1.2.
• wildfire: each multiplier must be in [0.5, 1.0].
• earthquake: requires block-source field and at least one blocked_value.

Outputs

Runtime output keys (returned in ToolRunResult.outputs):

scenario_summary_csv schema

scenario_id,max_cost_multiplier,blocked_value,covered_count,total_count,covered_pct,delta_from_baseline_pct

simulation_report schema

Top-level keys:

• workflow
• scenario_template
• baseline
• scenario_count
• best_scenario
• worst_scenario
• scenarios

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.emergency_scenario_routing_and_accessibility_simulator(
        network="city_network.gpkg",
        critical_facilities="critical_facilities.gpkg",
        demand_points="demand_points.gpkg",
        ring_costs=[5.0, 10.0, 15.0],
        scenario_csv="scenarios.csv",
        scenario_template="flood",
        scenario_block_source_field="STATUS",
        baseline_service_areas="outputs/em_baseline.gpkg",
        worst_case_service_areas="outputs/em_worst.gpkg",
        scenario_summary_csv="outputs/em_scenarios.csv",
        simulation_report="outputs/em_report.json",
        html_report="outputs/em_report.html"
)

The example below adds travel-time impedance, turn penalties, and a peak-hour speed profile to make scenario comparisons more realistic.

env.emergency_scenario_routing_and_accessibility_simulator(
        network="city_network.gpkg",
        critical_facilities="critical_facilities.gpkg",
        demand_points="demand_points.gpkg",
        ring_costs=[5.0, 10.0, 15.0],
        scenario_csv="scenarios.csv",
        scenario_template="flood",
        scenario_block_source_field="STATUS",
        edge_cost_field="MINUTES",
        one_way_field="ONEWAY",
        node_cost_points="intersection_delay_points.shp",
        node_cost_field="DELAY_MIN",
        node_cost_snap_distance=25.0,
        turn_penalty=0.3,
        u_turn_penalty=2.0,
        forbid_u_turns=True,
        temporal_cost_profile="am_peak_profiles.csv",
        temporal_edge_id_field="EDGE_ID",
        departure_time="2024-06-15T08:00:00Z",
        temporal_mode="multiplier",
        temporal_fallback="static_cost",
        baseline_service_areas="outputs/em_baseline_peak.gpkg",
        worst_case_service_areas="outputs/em_worst_peak.gpkg",
        scenario_summary_csv="outputs/em_scenarios_peak.csv",
        simulation_report="outputs/em_report_peak.json",
        html_report="outputs/em_report_peak.html"
)

References

• FEMA (Federal Emergency Management Agency) Hazard Mitigation Planning Guidelines

Parameter Interaction Notes

Results are most sensitive to scenario multipliers and demand-point completeness.

• Larger ring costs and multipliers tend to increase measured coverage.
• Missing or sparse demand points can make scenario comparisons look unrealistically favorable.

QA and Acceptance Criteria

Use a staged acceptance approach for Emergency Accessibility Scenario Planning:

1. Validate geometry types and scenario CSV schema.
2. Confirm required output paths are writable.
3. Verify scenario summary rows match parsed scenarios.
4. Confirm worst-case output corresponds to lowest covered_pct.

Recommended acceptance checks:

• simulation_report.scenario_count matches expected scenario count.
• delta_from_baseline_pct values match scenario vs baseline coverage math.
• Worst scenario in JSON is reflected in worst_case_service_areas output.

Advanced Operational Guidance

For production deployment of Emergency Accessibility Scenario Planning:

• Version control scenario CSVs and template choices for auditability.
• Keep block-source coding dictionaries standardized across departments.
• Validate scenario assumptions before interpreting policy decisions.

Implementation Patterns

Common implementation patterns with Emergency Accessibility Scenario Planning:

• Baseline + full scenario batch run.
• Targeted stress scenarios for known bottlenecks.
• Governance run with archived CSV/JSON artifacts.

Related Tools

Use Emergency Accessibility Scenario Planning together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Emergency Accessibility Scenario Planning is most valuable when teams need measurable service-level improvements (coverage, response time, cost-to-serve) with governance-ready transparency.

What this workflow helps you achieve:

• Translates network complexity into decision-ready options.
• Supports defensible operational planning with explicit constraints.
• Creates repeatable workflows for quarterly and annual optimization cycles.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Confirm objective function matches business KPI priorities.
3. Document constraints (capacity, time windows, exclusions) in deliverable notes.
4. Provide baseline-vs-optimized comparison metrics.
5. Include at least one scenario stress test (demand spike, outage, or route closure).

Common Questions

Q: Why do all scenarios look similar to baseline?
A: Multipliers may be too mild or blocked values may not match network attribute values.

Q: Why is coverage always 100%?
A: If demand points are omitted, KPI coverage defaults to 100%.

Q: What does blocked_value control?
A: It selects which network edges are blocked in a scenario when mapped through scenario_block_source_field.

Route Event Governance

Purpose

Route Event Governance establishes and manages a linear referencing system (LRS) for route networks, enables attribute management using route/measure location, and provides tools for asset inventory, lifecycle tracking, and spatiotemporal querying of linear assets (poles, segments, intersections).

Typical Questions This Tool Helps Answer

• Where do route events contain gaps, overlaps, or invalid measure direction that break LRS consistency?
• Which event records violate attribute domain or policy rules?
• What portion of event issues can be auto-corrected versus escalated for manual governance review?

Background

Network planning workflows use graph-theoretic representations of roads, routes, or linear assets, where node-edge topology and impedance attribution directly control results. Missing restrictions, incorrect turn logic, or stale demand assumptions can dominate outcome quality.

These tools are best interpreted as constrained optimization and diagnostics frameworks. Decisions should be based on trade-offs across service, resilience, and cost objectives rather than any single metric.

Route-event governance formalizes linear referencing events with temporal and spatial consistency controls. Strong governance depends on reproducible event segmentation and audit-grade lineage.

Methodological Considerations

• Topology validation should precede optimization or scenario simulation.
• Explicitly represent operational constraints (time windows, restrictions, capacities, closures) before comparing objective outcomes.
• Test outcomes under stress scenarios so selected plans remain stable under realistic disruptions.

Practical Interpretation Pitfalls

Single-metric improvements can hide degraded resilience or equity; compare candidate plans across multiple KPIs and scenario conditions.

Inputs

Parameters

• gap_tolerance (optional): gap size below this value is ignored; default 0.0.
• overlap_tolerance (optional): overlap size below this value is ignored; default 0.0.
• auto_fix (optional): if true, fix descending intervals and trim overlaps when possible.
• domain_rules_json (optional): per-field domain policy file.
• governed_events (required): output path for governed events.
• issues_csv (required): output path for issue log.
• corrected_events (optional): output path for corrected records.
• governance_report (required): output path for governance summary JSON.
• remediation_queue_csv (optional): output path for prioritized remediation queue.
• html_report (optional): output path for HTML summary.

Domain Rules JSON (Optional)

Per-field rules can include:

• allowed_values
• regex
• min
• max

Violations are reported as domain_validation issues.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

governed_events added fields

• GOVERNANCE_STATUS: PASSED or CORRECTED
• CORRECTIONS: none, descending_fix, overlap_trim, or descending_fix+overlap_trim

issues_csv schema

event_id,route_id,rule_violated,severity,description,measure_start,measure_end

remediation_queue_csv schema

priority,event_id,route_id,rule_violated,severity,recommended_action

governance_report keys

• total_events
• passed_events
• failed_events
• pass_rate_percent
• rules_violated
• severity_distribution
• correctable_count
• domain_rules_applied

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.route_event_governance_for_linear_assets(
        events="route_events.gpkg",
        route_id_field="route_id",
        from_measure_field="from_m",
        to_measure_field="to_m",
        auto_fix=True,
        domain_rules_json="domain_rules.json",
        governed_events="outputs/governed_events.gpkg",
        issues_csv="outputs/issues.csv",
        corrected_events="outputs/corrected_events.gpkg",
        governance_report="outputs/governance_report.json",
        remediation_queue_csv="outputs/remediation_queue.csv",
        html_report="outputs/governance_report.html"
)

References

• OGC (Open Geospatial Consortium) Linear Reference Systems Standard

Parameter Interaction Notes

Output strictness depends on tolerance settings and auto-fix policy.

Note: This workflow validates linear-referencing event intervals and does not build a routing graph, so one-way routing parameters (for example one_way_field with FT/TF/B values) are not applicable.

• Tight tolerances catch more defects but may increase noise from minor measure jitter.
• Looser tolerances reduce issue counts but can hide meaningful defects.
• Auto-fix improves throughput for fixable issues, but review is still recommended before publication.

QA and Acceptance Criteria

Use a staged acceptance approach for Route Event Governance:

1. Validate required fields and measure data quality.
2. Validate domain-rules JSON format when used.
3. Confirm issue counts align with known data conditions.
4. Confirm correction outputs match governance expectations.

Recommended acceptance checks:

• passed_events + failed_events equals total_events.
• issues_csv includes all expected issue categories.
• governed_events contains governance status columns.
• corrected_events is present only when correction records exist.

Advanced Operational Guidance

For production deployment of Route Event Governance:

• Treat domain-rules JSON as a governed policy artifact.
• Use remediation queue output for data stewardship backlogs.
• Archive run artifacts (issues_csv, governance_report) for audit trails.

Implementation Patterns

Common implementation patterns with Route Event Governance:

• Compliance scan (auto_fix=false) for strict diagnostics.
• Corrective scan (auto_fix=true) for fast recovery of fixable defects.
• Release-ready scan with frozen rule policy and archived outputs.

Related Tools

Use Route Event Governance together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Route Event Governance is most valuable when teams need measurable service-level improvements (coverage, response time, cost-to-serve) with governance-ready transparency.

What this workflow helps you achieve:

• Translates network complexity into decision-ready options.
• Supports defensible operational planning with explicit constraints.
• Creates repeatable workflows for quarterly and annual optimization cycles.

Results Delivery Checklist

Before sharing results with stakeholders:

1. Validate network topology and impedance attributes for all served areas.
2. Confirm objective function matches business KPI priorities.
3. Document constraints (capacity, time windows, exclusions) in deliverable notes.
4. Provide baseline-vs-optimized comparison metrics.
5. Include at least one scenario stress test (demand spike, outage, or route closure).

Common Questions

Q: Why are some events missing from governed output?
A: Error-level failing events are excluded if not fixable (or when auto-fix is off).

Q: Why is corrected output missing?
A: Corrected output is written only when auto_fix=true, a path is supplied, and at least one correction occurs.

Q: How should we interpret CORRECTED status?
A: The event passed after automatic correction; review is still recommended before publication.

Utility Corridor Access Planning

What This Tool Does

Utility Corridor Access Planning prioritizes encroachment hotspots near utility corridors and pairs them with the nearest access points for field-response planning.

Typical Questions This Tool Helps Answer

• Which encroachments are highest priority based on corridor proximity and access difficulty?
• What is the nearest viable access point for each hotspot and what response SLA category applies?
• What ranked field-response queue should operations execute first this week?

When To Use

• Utility corridor patrol planning
• Encroachment triage for line, pipe, or right-of-way assets
• Dispatch queue generation for maintenance response teams

What You Need

Key Settings

What You Get

The hotspot layer includes corridor, access, risk, priority, SLA, access-difficulty, and lineage fields. The CSV lists the same records in ranked order.

Runtime Output Keys

result.outputs["hotspots"]
result.outputs["priority_csv"]
result.outputs["planning_report"]
result.outputs["summary"]
result.outputs["response_queue_csv"]
result.outputs["html_report"]

Common Questions

Q: Which output should I review first for decision-making? A: Start with priority_csv and planning_report.counts_by_priority_band, then confirm urgency in hotspot PRIORITY and SLA_HOURS.

Q: What is a common interpretation mistake? A: Treating distance to corridor alone as urgency. Priority combines RISK_SCORE, ACCESS_DIST, and corridor proximity.

Q: Which settings most change outcomes? A: corridor_influence_distance and high_risk_distance usually drive the biggest shift in critical hotspot counts.

Q: How should operations use the outputs? A: Use response_queue_csv for dispatch sequencing and validate top critical records with field confirmation before issuing final work orders.

Results Delivery Checklist

• The corridor, encroachment, and access layers were checked for alignment
• hotspots was reviewed in GIS software
• The top rows in priority_csv were confirmed
• The chosen response queue matches the operations plan

Operational Notes

• This workflow does not build or traverse a road-routing graph.
• One-way routing parameters (for example one_way_field with FT/TF/B values) are not used.
• Prioritize sensitivity testing on corridor_influence_distance and high_risk_distance before locking production thresholds.

Related Tools

• network_readiness_and_diagnostics_intelligence
• service_area_planning_and_coverage_optimization
• emergency_scenario_routing_and_accessibility_simulator

When To Use This Workflow

Use Utility Corridor Access Planning when you need a repeatable hotspot-prioritization and access-assignment package for dispatch and field-response planning.

Parcel Fabric Topology Compliance

Purpose

Parcel Fabric Topology Compliance validates cadastral parcel and administrative boundary topology, detects overlaps and gaps, and enforces compliance with land fabric standards enabling authoritative reference data maintenance.

Typical Questions This Tool Helps Answer

• Which parcels violate topology rules (overlaps, gaps, slivers) and where are they located?
• Will our parcel fabric pass jurisdiction-specific quality thresholds before publication?
• What can be safely auto-fixed now versus what requires manual cadastral review?

Background

Network planning workflows use graph-theoretic representations of roads, routes, or linear assets, where node-edge topology and impedance attribution directly control results. Missing restrictions, incorrect turn logic, or stale demand assumptions can dominate outcome quality.

These tools are best interpreted as constrained optimization and diagnostics frameworks. Decisions should be based on trade-offs across service, resilience, and cost objectives rather than any single metric.

Land-fabric topology compliance checks enforce geometric and adjacency integrity so downstream governance and analytics are legally and operationally defensible. Error classes should be triaged by business impact.

Methodological Considerations

• Topology validation should precede optimization or scenario simulation.
• Explicitly represent operational constraints (time windows, restrictions, capacities, closures) before comparing objective outcomes.
• Test outcomes under stress scenarios so selected plans remain stable under realistic disruptions.

Practical Interpretation Pitfalls

Single-metric improvements can hide degraded resilience or equity; compare candidate plans across multiple KPIs and scenario conditions.

Inputs

For sliver detection, the workflow first measures parcel area from geometry. If that is unavailable, it falls back to an existing area field named gis_area, shape_area, shape_starea__, st_area, or area.

Parameters

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Important JSON report fields

Returned payload keys

The workflow returns these output keys:

• topology_violations
• issues_csv
• compliance_report
• summary (same file as compliance_report)
• corrected_parcels when auto-fix is enabled
• remediation_queue_csv when requested
• html_report when requested

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.parcel_and_land_fabric_topology_compliance_workflow(
        parcels="county_parcels.gpkg",
        jurisdiction_template="ontario_mpac",
        min_sliver_area=2.0,
        auto_fix=True,
        topology_violations="/tmp/parcel_violations.gpkg",
        issues_csv="/tmp/parcel_issues.csv",
        compliance_report="/tmp/parcel_compliance.json",
        corrected_parcels="/tmp/parcel_corrected.gpkg",
        remediation_queue_csv="/tmp/parcel_remediation_queue.csv",
        html_report="/tmp/parcel_compliance_report.html",
)

References

• NSDI cadastral data standards
• Ontario MPAC parcel-fabric operating practices reflected by the ontario_mpac template

Parameter Interaction Notes

• If you omit min_sliver_area, the workflow uses the default attached to jurisdiction_template.
• If you supply min_sliver_area, that explicit value overrides the template default.
• pass_fail and rule counts are based on the pre-fix audit stage, even when auto_fix=true.
• sliver_calibration_profile is useful for deciding whether your current sliver threshold is too aggressive or too permissive.

QA and Acceptance Criteria

1. Confirm the parcel layer is polygon or multipolygon geometry in a projected CRS.
2. Confirm the example arguments match the runtime names exactly.
3. Verify issues_csv uses the header feature_fid,geometry_type,issue_type,detail.
4. Verify topology_violations contains the documented fields.
5. Verify compliance_report includes the documented keys, including pass_fail and sliver_calibration_profile.
6. If auto-fix is enabled, verify corrected_parcels exists and auto_fix_enabled=true in the JSON report.
7. If remediation_queue_csv is requested, verify its header is priority,issue_type,rule_or_code,count,recommended_action.

The workflow fails if the parcel layer is unreadable, not polygonal, not projected when CRS metadata is known, missing required output arguments, missing corrected_parcels while auto_fix=true, or uses an unsupported jurisdiction_template.

Advanced Operational Guidance

• Review issues_csv and topology_violations together. The CSV is better for spreadsheet triage; the point layer is better for map review.
• Be cautious when increasing min_sliver_area. Small valid parcels can be reclassified as remediation items if the threshold is too high.
• Use auto-fix only inside a controlled review workflow. It helps with cleanup, but it does not replace parcel governance.
• If you intend to standardize thresholds across jurisdictions, compare calibration profiles first rather than copying one template blindly.

Implementation Patterns

• Baseline audit: run without auto-fix to produce the compliance package.
• Review triage: add remediation_queue_csv to split overlap, gap, and sliver work.
• Controlled cleanup: enable auto-fix, review autofix_changes_applied, then rerun the workflow if you need a refreshed compliance status.
• Threshold calibration: compare multiple min_sliver_area settings before locking a program standard.

Related Tools

• topology_validation_report
• topology_rule_validate
• topology_rule_autofix
• crs_harmonization

When To Use This Workflow

Use this workflow when parcel-fabric maintenance needs a complete QA package rather than a one-off geometry repair. It is especially useful when you need to separate geometry QA, rule-based violations, sliver threshold review, and remediation planning into one repeatable deliverable.

What this workflow helps you do:

• Measure parcel-fabric compliance in a repeatable way.
• Prioritize cleanup work by issue type.
• Document pre-fix condition separately from remediation activity.

Results Delivery Checklist

1. Deliver issues_csv, topology_violations, and compliance_report together.
2. State clearly whether generic or ontario_mpac defaults were used.
3. If auto-fix was enabled, call out that compliance metrics describe the pre-fix state.
4. Review sliver_calibration_profile before finalizing any policy recommendation around sliver thresholds.
5. Include remediation_queue_csv when the next step is operational cleanup assignment.

Common Questions

Q: Why can pass_fail still be false even when corrected_parcels was written successfully?
A: Because pass_fail reflects the pre-fix audit result. Auto-fix activity is reported separately through auto_fix_enabled and autofix_changes_applied.

Q: What does share_pct in sliver_calibration_profile mean?
A: It is the share of parcels smaller than each threshold in the calibration table. It helps you choose a threshold; it is not a legal compliance label by itself.

Q: Which setting most strongly affects sliver findings?
A: min_sliver_area. Even small changes can noticeably increase or decrease sliver_count, especially in dense urban fabrics.

Q: How should operations use remediation_queue_csv?
A: Use it to assign overlap, gap, and sliver work by priority. It is a work-planning output, not a substitute for the feature-level details in issues_csv.

LiDAR and Forest Analytics Bundle

Overview

The LiDAR and Forest Analytics bundle provides specialized point cloud and remote sensing tools for forest inventory, biomass quantification, disturbance detection, and landscape change monitoring. Leverages high-resolution LiDAR elevation and intensity data alongside optical imagery.

Key Concepts

Point Cloud Processing

3D data filtering, classification, and metric derivation from airborne LiDAR (ALS) or terrestrial LiDAR (TLS) acquisitions.

Terrain Modeling

Digital Elevation Models (DEMs), Digital Surface Models (DSMs), and Canopy Height Models (CHMs) derived from point cloud data.

Forest Structure Quantification

Inventory metrics including crown height, crown area, aboveground biomass, basal area, and stem density derived from multispectral and LiDAR data.

Change Detection and Disturbance

Multi-temporal analysis quantifying forest disturbance (harvesting, mortality, insect damage, fire) and recovery trajectories.

Accessibility and Safety

Analysis of terrain and vegetation for pedestrian accessibility, UAV navigability, and hazard identification.

Typical Workflows

Forest Inventory Workflow

1. Acquire LiDAR and hyperspectral imagery
2. Quality control and evaluate point cloud metrics (LiDAR QA and Confidence)
3. Generate terrain and canopy products (LiDAR Terrain Product Suite)
4. Extract structure metrics and estimate biomass (Forestry Structure and Biomass Analysis)
5. Validate with field plots
6. Report inventory maps and statistics

Disturbance Monitoring

1. Establish baseline forest conditions from LiDAR and imagery
2. Conduct annual/bi-annual re-acquisition
3. Detect structural change (LiDAR Change and Disturbance Analysis)
4. Classify disturbance type (harvesting, insects, disease, fire)
5. Map recovery progression
6. Generate disturbance trajectory maps and statistics

Urban Vegetation and Accessibility

1. Acquire high-resolution LiDAR in urban area
2. Classify point cloud (ground, vegetation, building, urban features)
3. Assess vegetation clearance for sidewalk accessibility (Sidewalk Vegetation Accessibility Monitoring)
4. Identify maintenance priorities
5. Track year-to-year maintenance compliance

Recommended Workflow Start Order

The workflow order below is a practical starting sequence that gets most teams to usable, validated outputs quickly:

1. LiDAR QA and Confidence
2. LiDAR Terrain Product Suite
3. LiDAR Change and Disturbance Analysis
4. Forestry Structure and Biomass Analysis
5. Sidewalk Vegetation Accessibility Monitoring

Performance and Data Requirements

• Point Density: Minimum 4–8 pts/m² for forest inventory; ≥15 pts/m² for detailed structure; ≥50 pts/m² for urban vegetation
• Vertical Accuracy: ±0.15 m (forest), ±0.10 m (urban) necessary for reliable metrics
• Multi-Spectral Alignment: Optical data must be coregistered to LiDAR with <0.5 m horizontal accuracy
• Temporal Consistency: Repeat acquisitions should use same acquisition parameters (sensor, time-of-year, weather)

References

• ASPRS LiDAR Standards and Best Practices
• NEON Protocol: Airborne Observation Platform (AOP)
• Wulder, M. A., et al. (2019). "Lidar and SfM Data Fusion for Measuring Forest Change." Remote Sens. Ecol. Conserv. 5(2), 140–156.

LiDAR QA and Confidence

What It Does

LiDAR QA and Confidence runs a full QA pass for LiDAR ground-surface readiness and produces confidence diagnostics, uncertainty products, QA flags, hotspot outputs, and a summary report for acceptance decisions.

Typical Questions This Tool Helps Answer

• Does this LiDAR delivery meet the density, accuracy, and classification standards required to proceed to DEM or canopy product generation?
• Which flight lines or spatial areas have inadequate coverage, low point density, or classification inconsistencies that must be resolved before use?
• Can we accept this dataset and move to downstream processing, or does it need formal remediation or re-delivery from the contractor?

Background

LiDAR QA and confidence assessment is a data-readiness gate that quantifies whether a delivery can support downstream terrain, vegetation, and corridor workflows with defensible uncertainty bounds.

A useful framing is a composite confidence function over diagnostics:

$$C(x)=g\left(\text{density}(x), \text{classification_consistency}(x), \text{surface_residual}(x), \text{artifact_flags}(x)\right)$$

Where lower confidence indicates higher risk that derived products are unstable or acceptance-sensitive.

QA Dimensions

• Coverage and density adequacy.
• Classification consistency and plausibility.
• Surface residual quality relative to expected terrain behavior.
• Artifact prevalence and hotspot concentration.

These dimensions support pass/review/reprocess gating with auditable rationale.

Methodological Considerations

• Treat profile mode (strict, balanced, permissive) as governance policy, not cosmetic tuning.
• Use checkpoint validation when available to ground vertical confidence in external control.
• Compare hotspot severity and fail fraction together before acceptance decisions.

Practical Interpretation Pitfalls

Typical misreads include using mean confidence without hotspot context, interpreting fast-mode outputs as full QA equivalence, and approving borderline datasets without documenting residual risk.

Source-Verified Contract

Tool id: lidar_qa_and_confidence

Required Input

Optional Settings

Output Artifacts

Important Fast Mode Note

Even in fast mode, the workflow still emits a qa_hotspots artifact path. The hotspot layer is written as empty rather than omitted.

Example: Standard QA

import whitebox_workflows as wbw

wbe = wbw.WbEnvironment()

wbe.lidar_qa_and_confidence(
    input="site_delivery.laz",
    qa_mode="balanced",
    output_prefix="site_delivery_qa",
    output="site_delivery_classified.laz"
)

Example: Compliance-Oriented QA

wbe.lidar_qa_and_confidence(
    input="contract_block_11.laz",
    qa_mode="strict",
    elev_threshold=0.12,
    high_confidence_threshold=0.85,
    checkpoints="contract_block_11_checkpoints.gpkg",
    checkpoint_z_field="z_control",
    hotspot_rank_top_n=20,
    output_prefix="contract_block_11_qa",
    output="contract_block_11_classified.laz"
)

Example: Fast Intake Triage

wbe.lidar_qa_and_confidence(
    input="incoming.laz",
    qa_mode="auto",
    fast_mode=True,
    output_prefix="incoming_quickqa"
)

When To Use This Workflow

• You need a single QA workflow before downstream terrain or corridor products.
• You need repeatable confidence and uncertainty diagnostics for acceptance reviews.
• You need consistent report artifacts for operations, audit, or vendor feedback.

Results Delivery Checklist

• Confirm summary JSON (summary) exists and is archived.
• Confirm confidence/uncertainty/QA-flag rasters are generated.
• Confirm hotspot artifact exists for every run (including fast mode).
• Confirm optional checkpoints are only configured when checkpoint data is available.

Common Questions

Does this workflow require checkpoints?

No. checkpoints is optional.

What is the best default mode?

balanced is the default and a good starting point for most production QA.

Can I reduce runtime for exploratory checks?

Yes. Set fast_mode=true.

Does qa_mode=auto pick a unique model?

No. auto currently resolves to balanced behavior.

Related Workflows

• lidar_terrain_product_suite
• lidar_change_and_disturbance_analysis

LiDAR Terrain Product Suite

Purpose

LiDAR Terrain Product Suite generates a comprehensive set of terrain analysis products from point cloud data: Digital Elevation Models (DEMs), Digital Surface Models (DSMs), Canopy Height Models (CHMs), and derived topographic attributes (slope, aspect, curvature). Enables terrain-based analysis and landform characterization.

Typical Questions This Tool Helps Answer

• What is the bare-earth terrain surface and which derived topographic attributes (slope, aspect, curvature) are needed for the next analysis step?
• Which terrain features are visible at this acquisition resolution that would be missed or smoothed out in coarser reference DEMs?
• Are the DEM and DSM products of sufficient quality and resolution for hydrological conditioning, flow routing, and further terrain analysis?

Background

Terrain product suites transform raw point clouds into hydrologically and geomorphically meaningful surfaces. Typical derivatives include slope, aspect, curvature, roughness, and drainage-support layers derived from a conditioned terrain model.

A foundational relation is local gradient magnitude:

$$|\nabla z| = \sqrt{\left(\frac{\partial z}{\partial x}\right)^2 + \left(\frac{\partial z}{\partial y}\right)^2}$$

From these derivatives, downstream terrain interpretations are scale-dependent and sensitive to smoothing/conditioning choices.

Product-Scale Dependency

Fine-resolution products preserve microtopography but amplify noise; coarser products improve stability but can erase operationally relevant features. End-use should drive scale and filtering strategy.

Hydrologic Conditioning Context

Depression treatment, breach/fill rules, and stream-initiation assumptions can materially alter flow-support derivatives. These are modeling assumptions and should be documented as part of delivery.

Methodological Considerations

• Validate ground classification before DEM/DTM derivation.
• Keep derivative parameter settings consistent across adjacent tiles to avoid seam artifacts.
• Use suitability checks for each derivative relative to target workflow scale.

Practical Interpretation Pitfalls

Frequent mistakes include mixing derivatives generated with incompatible conditioning rules and interpreting artifacts at tile boundaries as real geomorphic signals.

Inputs

Parameters

Profile presets adjust threshold behavior:

• strict: tighter acceptance behavior
• balanced: default behavior
• permissive: broader acceptance behavior

QA status categories:

• pass: terrain package ready for normal use
• review: flagged zones should be checked
• reprocess: elevated QA issues, rerun advised

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Output filenames:

• <output_prefix>_dtm.tif
• <output_prefix>_dsm.tif
• <output_prefix>_slope.tif
• <output_prefix>_hillshade.tif
• <output_prefix>_confidence.tif
• <output_prefix>_uncertainty.tif
• <output_prefix>_metadata.json
• <output_prefix>_report.html

Metadata-contract additions in summary/metadata:

• output_semantics: machine-readable output intent and certification scope per output key.
• confidence_contract: confidence metric declaration including threshold and low-confidence fraction.
• interpretation_warnings: plain-language warnings on proxy limits and profile/threshold comparability.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.lidar_terrain_product_suite(
        input="survey_2026.laz",
        profile="balanced",
        block_size=1.0,
        max_building_size=150.0,
        slope_threshold=15.0,
        elev_threshold=0.15,
        z_factor=1.0,
        hillshade_azimuth=315.0,
        hillshade_altitude=45.0,
        high_confidence_threshold=0.8,
        output_prefix="outputs/terrain_suite",
        output="outputs/terrain_suite_classified.laz"
)

• What is the bare-earth terrain surface and which derived products - slope and hillshade - are suitable for the next analysis step, and does the QA status indicate the outputs are production-ready?

• How much did ground-point density and classification quality improve after filtering and interpolation?

• Are the generated DTM and DSM surfaces clean and reliable enough for hydrologic, engineering, or ecological downstream workflows?

• Kraus, K., & Pfeifer, N. (1998). "Determination of Terrain Models in Wooded Areas with Airborne Laser Scanning Data." ISPRS J. Photogramm. Remote Sens. 53(4), 193–203.

Parameter Interaction Notes

Output quality is most affected by profile choice, block size, and terrain-filter thresholds.

• Smaller cells increase detail and sensitivity.
• More aggressive terrain filtering can suppress non-ground artifacts but may over-smooth edges.
• Confidence threshold influences high-confidence fraction in summary metrics.

QA and Acceptance Criteria

Use a staged acceptance approach for LiDAR Terrain Product Suite:

1. Confirm all expected outputs are generated.
2. Check metadata status (pass/review/reprocess).
3. Review confidence and uncertainty maps in flagged areas.
4. Validate slope/hillshade plausibility versus terrain knowledge.
5. Confirm metadata includes output_semantics, confidence_contract, and interpretation_warnings.

Recommended acceptance checks:

• Metadata workflow ID is correct.
• High-confidence fraction is reasonable for data quality.
• reprocess runs are escalated before delivery.

Advanced Operational Guidance

For production deployment of LiDAR Terrain Product Suite:

• Standardize profile defaults across teams.
• Archive metadata JSON for audit and reproducibility.
• Use strict profile for high-stakes regulatory outputs.

Implementation Patterns

Common implementation patterns with LiDAR Terrain Product Suite:

• Standard balanced production run.
• Strict QA run for delivery sign-off.
• Sensitivity run around block size and thresholds.

Related Tools

Use LiDAR Terrain Product Suite together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

Common Questions

Q: What should teams inspect first?
A: Start with metadata status and confidence/uncertainty summaries, then inspect DTM and slope outputs.

Q: Why did we get review instead of pass?
A: Warning/fail fractions exceeded conservative QA cutoffs but not full reprocess criteria.

Q: What does reprocess imply?
A: QA failure fractions are high enough that rerunning with revised settings or data checks is recommended.

Q: Is CHM generated directly by this workflow?
A: No direct CHM output is emitted by this tool; outputs focus on DTM/DSM/derivatives and QA surfaces.

Q: When should output be provided?
A: Provide it when you need a persisted classified/filtered LiDAR product in addition to raster outputs.

LiDAR Change and Disturbance Analysis

What This Tool Does

LiDAR Change and Disturbance Analysis compares baseline and monitoring LiDAR tile sets to produce per-tile change rasters, QA diagnostics, and optional attribution products.

What You Need

What You Get

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
result = env.lidar_change_and_disturbance_analysis(
        baseline_tiles=["baseline/tile_001.laz", "baseline/tile_002.laz"],
        monitor_tiles=["monitor/tile_001.laz", "monitor/tile_002.laz"],
        reference_perimeters="reference/harvest_blocks.gpkg",
        attribution_buffer_meters=10.0,
        min_overlap_fraction=0.15,
        output_prefix="outputs/lidar_change"
)

Common Questions

Q: Why can a run fail even when tile counts match? A: Pairing is key-based, not count-based. Duplicate or unmatched normalized keys are rejected.

Q: When are attribution files written? A: Only when reference_perimeters is provided.

Q: What does review status mean in summary? A: One or more QA warnings were triggered and should be inspected before operational use.

Forestry Structure and Biomass Analysis

Purpose

Forestry Structure and Biomass Analysis estimates forest structure classes, canopy-height metrics, stand units, confidence, and a terrain-adaptive biomass proxy from LiDAR. Outputs are suitable for carbon accounting, resource management, and inventory planning.

Typical Questions This Tool Helps Answer

• What are the estimated carbon stocks and dominant canopy-height metrics across this forest inventory area?
• Which stand units have sufficient LiDAR point density to support high-confidence biomass estimation versus where are results provisional?
• How does forest structure vary spatially across the landscape and are the patterns consistent with reported stand age and disturbance history?

Background

Forest-structure and biomass inference from LiDAR is based on vertical return distribution, canopy height metrics, and terrain-normalized geometry. A common conceptual relation is:

$$B(x) = f\left(H_{p95}(x), \text{cover}(x), \sigma_z(x), \text{density}(x)\right)$$

Where $B$ is biomass proxy, $H_{p95}$ is high-percentile canopy height, and remaining terms describe cover and structural variability.

Structural Signal Components

• Height distribution metrics capture stand vertical development.
• Point-density support drives confidence and output robustness.
• Terrain-adaptive biomass scaling helps reduce underestimation in heterogeneous stands.

Because LiDAR sampling is discrete, metric reliability depends on point density, occlusion, scan geometry, and normalization quality.

Methodological Considerations

• Verify ground normalization quality before interpreting canopy-height derivatives.
• Use density/confidence diagnostics to bound where biomass interpretation is decision-grade.
• Match metric scale to management question (stand-level planning versus fine-scale habitat mapping).

Practical Interpretation Pitfalls

Frequent errors include treating low-density areas as true low biomass, mixing acquisitions with incompatible pulse geometry, and using a single structural metric as a complete ecological condition signal.

Inputs

Parameters

• profile (optional): fast, balanced, strict; default balanced.
• resolution (optional): output raster resolution; default 2.0.
• stand_block_cells (optional): stand aggregation block size; default 12, minimum 2.
• biomass_cap (optional): max biomass proxy value; default 25.0.
• terrain_adaptation (optional): off, moderate, strong; default moderate.
• output_prefix (optional): output naming prefix; default forest_structure.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Summary contract also includes:

• output_semantics
• confidence_contract
• interpretation_warnings

Runtime note:

• This workflow is Pro-only and requires include_pro=True with a valid Pro/Enterprise runtime.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment(include_pro=True, tier="pro")
lidar = wbw.Lidar("survey_classified.laz")
env.forestry_structure_and_biomass_intelligence(
        input=lidar,
        profile="balanced",
        resolution=2.0,
        stand_block_cells=12,
        biomass_cap=25.0,
        terrain_adaptation="moderate",
        output_prefix="outputs/forest_structure"
)

• What is the biomass proxy and dominant canopy-height metric distribution across this forest inventory area, and which stand units show the strongest structure signal?

• Which stands show structural complexity consistent with mature habitat conditions versus simplified plantation-like structure?

• Where do canopy-gap and understory-density indicators suggest priority locations for thinning, regeneration support, or biodiversity interventions?

• Chave, J., et al. (2014). "Improved Allometric Models to Estimate the Aboveground Biomass of Tropical Trees." J. Ecol. 102(3), 726–736.

Parameter Interaction Notes

Results are sensitive to profile, terrain adaptation, and stand block size.

• Strict profile tends to classify fewer cells into the tallest structure classes.
• Strong terrain adaptation can raise biomass proxy in high-relief stands.
• Larger stand blocks provide smoother but less local detail.

QA and Acceptance Criteria

Use a staged acceptance approach for Forestry Structure and Biomass Analysis:

1. Confirm LiDAR input quality and expected coverage.
2. Confirm all outputs are generated with the selected prefix.
3. Validate stand summaries against known forest compartments.
4. Review confidence map before operational targeting.

Recommended acceptance checks:

• Summary workflow id is correct.
• Class distributions are plausible for forest condition.
• Stand-unit attributes are populated and usable.

Advanced Operational Guidance

For production deployment of Forestry Structure and Biomass Analysis:

• Keep profile/settings fixed within annual reporting cycles.
• Use confidence and complexity outputs to prioritize field validation.
• Archive summary contracts for program governance and audit trails.

Implementation Patterns

Common implementation patterns with Forestry Structure and Biomass Analysis:

• Baseline stand intelligence run.
• Terrain-sensitivity comparison run.
• Executive reporting run with coarser stand aggregation.

Related Tools

Use Forestry Structure and Biomass Analysis together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

When To Use This Workflow

Use this workflow when teams need integrated forest structure and biomass-proxy outputs from LiDAR without stitching multiple intermediate tools manually.

Results Delivery Checklist

1. Include raster outputs, stand vector layer, summary JSON, and report HTML.
2. Document profile, terrain adaptation, and resolution settings.
3. Flag low-confidence zones before tactical decisions.
4. Provide stand-level interpretation notes for non-technical stakeholders.
5. Archive run metadata for repeatability.

Common Questions

Q: Is biomass proxy equivalent to formal biomass certification?
A: No. It is a planning and prioritization proxy, not a formal certification output by itself.

Q: Why did class maps change after switching from balanced to strict?
A: Profile changes adaptive thresholds and therefore alters class assignment behavior.

Q: Why do some areas have good biomass proxy but lower confidence?
A: Biomass and confidence are separate diagnostics; low point-density support can reduce confidence even with strong biomass proxy signals.

Q: What does stand complexity represent?
A: It is a normalized stand-level indicator derived from mean height, biomass proxy, and height variability.

Q: Why are small stand patches disappearing with larger stand blocks?
A: Larger block aggregation smooths local variability and merges fine-grained patterns.

Q: How should we use the confidence layer operationally?
A: Prioritize high-confidence zones for immediate decisions and route low-confidence zones for validation.

Q: Can we compare outputs from different resolutions?
A: Yes, but comparisons should account for resolution-driven differences in structure detail and aggregation.

Q: What causes many nodata cells in outputs?
A: Gaps in LiDAR support or invalid cells during intermediate gridding steps can propagate nodata.

Q: Which output is best for stand-level planning meetings?
A: stand_structure_units paired with biomass_proxy and confidence usually provides the best decision context.

Q: How often should this be rerun?
A: Typically after major LiDAR updates or when management planning cycles require refreshed stand intelligence.

Sidewalk Vegetation Accessibility Monitoring

What This Tool Does

Sidewalk Vegetation Accessibility Monitoring uses LiDAR point cloud data to assess vegetation clearance along sidewalk corridors. It classifies each sidewalk segment as obstructed, clear, or no_lidar_coverage and delivers a GeoPackage with per-segment metrics, a JSON summary report, and an HTML report.

Typical Questions This Tool Helps Answer

• Which sidewalk or trail segments have vegetation encroachment that currently violates minimum pedestrian clearance standards?
• Where is the maintenance backlog most severe, and which corridor segments should be prioritized for this season's vegetation crew?
• What percentage of total corridor length currently meets versus fails the clearance requirements based on this LiDAR survey?

When To Use

• Systematic vegetation clearance compliance audits against a minimum clearance height
• Dispatch prioritization for maintenance crews based on LiDAR-identified obstructions
• Pre-growing-season and post-storm screening of pedestrian corridor accessibility
• Monitoring program baselines for year-over-year clearance trend tracking

What You Need

Key Settings

What You Get

The output GeoPackage contains a field STATUS with values obstructed, clear, or no_lidar_coverage for each analysis unit, plus MAX_OBSTR (maximum vegetation height m), MEAN_OBSTR (mean obstruction m), and TILE_HITS (number of tiles covering the unit).

Reading the Summary Report

The JSON summary key items to review:

• status: "pass" (coverage adequate) or "review" (coverage below 75% threshold)
• summary.coverage_fraction: proportion of sidewalk units with LiDAR data
• summary.obstructed_fraction_of_observed: fraction of covered units classified as obstructed
• summary.no_lidar_coverage_features: count of units without data (coverage gaps)
• interpretation.qa_assessment: plain-language guidance based on run statistics

Runtime Output Keys

result.outputs["sidewalk_accessibility"]  # path to output GeoPackage
result.outputs["summary"]                 # path to summary JSON
result.outputs["html_report"]             # path to HTML report

Common Questions

Q: What does STATUS=no_lidar_coverage mean? A: No LiDAR tiles with data were found near that segment. These units are not included in obstruction statistics. Confirm tile coverage extent and reprocess after adding missing tiles if applicable.

Q: The obstruction fraction looks higher than expected. What should I check? A: First confirm clearance_height_m matches the local standard — a lower threshold will flag more units. Also check season: summer LiDAR will include full-leaf canopy. Values above 80% in a relatively open area should trigger a spot-check of several obstructed units in the field.

Q: Why does the output have many more features than my input sidewalk layer? A: The tool splits line features into segments of segment_length_m (default 10 m) for fine-grained location of obstructions. Each output segment has a SOURCE_FID field pointing back to the original sidewalk feature.

Q: How do I filter just the obstructed segments for field dispatch? A: In QGIS or ArcGIS, filter the GeoPackage layer by STATUS = 'obstructed'. For severe priority, add a secondary filter on MAX_OBSTR (e.g., MAX_OBSTR > 3.5).

Results Delivery Checklist

• summary["status"] confirmed as "pass" (or coverage gaps documented)
• Output GeoPackage reviewed — STATUS field populated for all analysis units
• obstructed_fraction_of_observed reviewed for plausibility given season and land cover
• HTML report reviewed and archived with project deliverables
• clearance_height_m and segment_length_m values recorded in project documentation

Operational Notes

• This workflow classifies each analysis unit strictly as obstructed, clear, or no_lidar_coverage using LiDAR-derived obstruction heights and local coverage.
• Priority dispatch should be based on STATUS plus obstruction magnitude (MAX_OBSTR, MEAN_OBSTR), not on corridor length alone.
• This workflow does not output a separate confidence raster; QA confidence is represented through coverage and summary diagnostics (status, coverage_fraction, and tile-hit statistics).

Related Tools

• lidar_change_and_disturbance_analysis
• lidar_terrain_product_suite
• lidar_qa_and_confidence

References

• Runtime implementation: wbtools_pro/src/tools/lidar_processing/change_and_accessibility.rs
• LiDAR and Forest Analytics bundle overview: manual/pro-tools-customer/src/lidar_forest/overview.md

When To Use This Workflow

Use Sidewalk Vegetation Accessibility Monitoring when you need repeatable, segment-level accessibility screening from LiDAR tiles to drive maintenance triage and dispatch planning.

Terrain and Infrastructure Siting Bundle

Overview

The Terrain and Infrastructure Siting bundle provides specialized tools for assessing site suitability, terrain constraints, and constructability for renewable energy infrastructure, utility corridors, and linear transportation networks.

Key Concepts

Suitability Analysis

Multi-criteria evaluation combining terrain, environmental, economic, and social factors to identify optimal locations for specific infrastructure types.

Terrain Constraints

Identification and quantification of physical limitations: slope steepness, soil bearing capacity, hydrologic hazards (flooding, erosion), and geomorphic instability.

Constructability Assessment

Evaluation of development feasibility considering terrain, cost implications, environmental mitigation, and schedule risk.

Infrastructure Routing

Least-cost path and corridor analysis balancing terrain, environmental, and economic objectives.

Typical Workflows

Wind Farm Siting

1. Acquire wind resource data (speed, direction, turbulence intensity)
2. Identify high-wind locations (Wind Turbine Siting Analysis)
3. Assess terrain constructability (Terrain Constructability and Cost Analysis)
4. Evaluate environmental constraints (viewshed, habitat, noise)
5. Optimize turbine placement and access roads

Solar Farm Development

1. Evaluate solar irradiance and shading (Solar Site Suitability Analysis)
2. Assess topographic slope and aspect suitability
3. Check soil conditions and foundation requirements
4. Plan electrical interconnection and transmission routing

Corridor Planning

1. Define corridor endpoints and width constraints
2. Evaluate environmental sensitivity (Corridor Mapping and Route Planning)
3. Assess terrain for constructability (Terrain Constraint and Conflict Analysis)
4. Identify conflict zones and alternatives
5. Generate routing options and cost estimates

Recommended Workflow Start Order

The workflow order below is a practical starting sequence that gets most teams to usable, validated outputs quickly:

1. Solar Site Suitability Analysis
2. Corridor Mapping and Route Planning
3. Wind Turbine Siting Analysis
4. Terrain Constraint and Conflict Analysis
5. Utility Corridor Encroachment Detection
6. Terrain Constructability and Cost Analysis

Performance Considerations

• Spatial resolution: 10–30 m resolution sufficient for infrastructure planning; finer for detailed site design
• Multi-criteria weighting: Weights should reflect stakeholder priorities (renewable energy, environmental protection, cost)
• Sensitivity analysis: Test weighting variations to ensure robust siting recommendations

References

• National Renewable Energy Laboratory (NREL) Siting Tools and Guidelines
• ESRI Site Suitability Analysis Best Practices

Solar Site Suitability Analysis

Purpose

Solar Site Suitability Analysis creates a terrain-based suitability map, visual-impact proxy, and ranked candidate sites for early solar siting.

Typical Questions This Tool Helps Answer

• Which candidate areas are strongest when balancing terrain suitability and visual impact?
• How much do transmission lines, substations, and roads change candidate ranking?
• Are top candidates stable under threshold/profile sensitivity checks?

Background

Solar siting is a screening and prioritization workflow, not a final approval workflow. This chapter is designed to support early-stage shortlist generation by combining terrain-derived suitability with optional infrastructure-aware reranking.

The workflow separates base score and final reranked score so teams can explain why rank changes occurred when infrastructure context is introduced. Final decisions still require permitting, interconnection, land-control, and environmental review.

Methodological Considerations

• Use a DEM appropriate to your planning scale and keep it consistent across comparisons.
• Add infrastructure layers when you want practical deployment-aware ranking behavior.
• Use sweep outputs to test shortlist stability before operational decisions.

Practical Interpretation Pitfalls

Common mistakes include treating top-ranked outputs as final decisions, ignoring sensitivity diagnostics, and comparing runs with different profile/threshold settings without documenting those differences.

Inputs

Outputs

Candidate-site attributes include RANK, SCORE, VIS_IMPACT, FINAL_SCORE, INFRA_BONUS, GRID_DIST_M, and ACCESS_DIST_M.

When sweep_spec is supplied, summary includes an executed sweep block and companion run-matrix/sensitivity artifacts for scenario traceability, including primary_relative_span and stability_class.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
result = env.solar_site_suitability_analysis(
        dem="dem_30m.tif",
        transmission_lines="grid/transmission_lines.gpkg",
        substations="grid/substations.gpkg",
        road_network="transport/roads.gpkg",
        infra_weight_profile="grid_priority",
        output_prefix="solar_siting"
)

Common Questions

Q: What changes when infrastructure layers are added? A: Candidate ranking is adjusted using infrastructure bonus, and reranking impact is reported in summary metrics.

Q: Which setting usually changes shortlist size the most? A: candidate_threshold, followed by separation and max-site limits.

Q: Are top scores always final decisions? A: No. Use this as screening output and combine with land-control, permitting, and interconnection checks.

Corridor Mapping and Route Planning

Purpose

Corridor Mapping and Route Planning identifies optimal transportation, utility, or recreational corridor routes that balance cost, environmental sensitivity, and stakeholder constraints. Generates multiple routing alternatives and comparative analysis.

Typical Questions This Tool Helps Answer

• Which route corridor minimizes combined environmental impact, terrain construction cost, and stakeholder conflict under our stated constraint priorities?
• How do the alternative corridor routes compare against each other when different constraint weights or thresholds are applied?
• Which corridor segment has the highest conflict concentration and requires the most detailed engineering and permitting review?

Background

Terrain siting workflows convert topographic and contextual constraints into suitability or conflict surfaces. The methodological goal is to compress many physical and operational factors into transparent, reviewable decision layers.

Because suitability is relative to assumptions, the recommended practice is to run sensitivity scenarios and compare candidate zones under alternative thresholds before final siting commitments.

Corridor mapping intelligence consolidates terrain, access, and constraint surfaces into reviewable corridor alternatives. Background interpretation should emphasize trade-off transparency rather than single-score dominance.

Methodological Considerations

• Treat suitability/conflict scores as relative rankings under stated assumptions.
• Run threshold sensitivity tests to identify stable candidate zones.
• Preserve assumptions and parameter profiles in decision records for reproducibility.

Practical Interpretation Pitfalls

Over-interpreting a single scoring run as a final siting decision can conceal constraint trade-offs that emerge under alternate but reasonable parameter settings.

Inputs

Parameters

• cost_profile (optional): slope_only, slope_roughness, conservative.
• terminal_anchor_strategy (optional): mixed, centroid_only, boundary_only.
• corridor_tolerance (optional): fraction above optimum cost used to define corridor suitability band.
• output_prefix (optional): output naming prefix.

Outputs

Output artifact keys below are runtime outputs, not input parameters.

Route metrics in optimal output

• Route length
• Mean slope along route
• Accumulated route cost
• Cost profile used

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
env.corridor_mapping_intelligence(
        dem="dem_10m.tif",
        start_features="route_start.gpkg",
        end_features="route_end.gpkg",
        constraints="protected_areas.gpkg",
        cost_profile="slope_roughness",
        terminal_anchor_strategy="mixed",
        corridor_tolerance=0.15,
        output_prefix="outputs/corridor"
)

References

• Dijkstra, E. W. (1959). "A Note on Two Problems in Connexion with Graphs." Numerische Mathematik 1(1), 269–271.

Parameter Interaction Notes

Planning outcomes are sensitive to profile, terminal strategy, and tolerance settings.

• Conservative profile tends to avoid rough terrain more aggressively.
• Anchor strategy can shift route origin/destination cells when polygons are used.
• Larger tolerance produces wider corridors suitable for alternatives screening.

QA and Acceptance Criteria

Use a staged acceptance approach for Corridor Mapping and Route Planning:

1. Confirm endpoints and optional constraints are valid and in compatible CRS.
2. Confirm route output is generated and includes expected metrics.
3. Confirm corridor suitability aligns with project tolerance intent.
4. Validate summary interpretation notes for anchor stability and reprojection actions.

Recommended acceptance checks:

• Route is present and continuous.
• Cost and suitability outputs are non-empty for feasible scenarios.
• Summary output paths align with generated artifacts.

Advanced Operational Guidance

For production deployment of Corridor Mapping and Route Planning:

• Use centroid-only anchors when strict repeatability is required.
• Keep constraints layer governance-controlled for design review cycles.
• Archive summary JSON and report for route approval packages.

Implementation Patterns

Common implementation patterns with Corridor Mapping and Route Planning:

• Baseline corridor feasibility run.
• Tolerance sweep for corridor-width decision support.
• Constraint update rerun for permitting iterations.

Related Tools

Use Corridor Mapping and Route Planning together with upstream conditioning and downstream validation tools in the same bundle to ensure end-to-end consistency and stronger decision confidence.

Common Questions

Q: Why did the route move after changing anchor strategy?
A: Polygon terminals can provide many candidate anchor points; strategy controls how candidates are chosen.

Q: Why is corridor area much larger than expected?
A: Corridor area scales with corridor_tolerance; lowering tolerance tightens the feasible band.

Q: Why are some areas completely avoided?
A: Constraint polygons are rasterized as impassable cells.

Wind Turbine Siting Analysis

Purpose

Wind Turbine Siting Analysis produces a siting score, confidence map, candidate points, high-confidence zones, and threshold-sensitivity diagnostics.

Typical Questions This Tool Helps Answer

• Which candidate locations satisfy terrain and settlement-visibility constraints while maintaining strong confidence?
• How sensitive is the shortlist to threshold changes and selected profile settings?
• Where are high-score zones that are also confidence-stable for feasibility follow-up?

Background

Wind siting is a constrained screening process where physical suitability and uncertainty must be interpreted together. This workflow explicitly separates siting_score (suitability) and confidence (stability/reliability) so ranking decisions are easier to explain.

The output is designed for early-stage planning and prioritization. Final wind deployment decisions still require grid studies, land access confirmation, permitting, environmental review, and local policy compliance.

Methodological Considerations

• Ensure DEM and settlement data are in aligned projected coordinates.
• Keep profile selection (fast, balanced, quality) consistent across alternatives when comparing results.
• Use threshold and sweep diagnostics to assess shortlist robustness before selecting field targets.

Practical Interpretation Pitfalls

Common mistakes include interpreting high score as high certainty, comparing runs with inconsistent profile/threshold settings, and skipping threshold-sensitivity diagnostics.

Inputs

Outputs

When sweep_spec is supplied, summary includes an executed sweep block and companion run-matrix/sensitivity artifacts for scenario traceability, including primary_relative_span and stability_class.

Example

import whitebox_workflows as wbw

env = wbw.WbEnvironment()
result = env.wind_turbine_siting(
        dem="dem.tif",
        settlements="settlements.shp",
        transmission_region="dense_grid",
        profile="balanced",
        output_prefix="wind_siting"
)

Common Questions

Q: Why is EPSG required for CSV settlements? A: CSV files do not carry CRS metadata, so EPSG is needed to align with the DEM.

Q: What is the difference between score and confidence? A: Score ranks suitability; confidence indicates how stable that score is across components.

Q: Where do I check threshold robustness? A: Review threshold_sensitivity_summary and the threshold_sensitivity section in summary JSON.

Utility Corridor Encroachment Intelligence

Background: Why Corridor Encroachment Monitoring Matters

Linear utility infrastructure such as transmission powerlines, distribution lines, gas pipelines, telecom corridors, drainage canals, and electrified rail corridors all share a persistent operational problem: the corridor changes continuously between inspections.

Vegetation regrowth can quickly reduce safety clearances along transmission lines, increase wildfire risk, and obstruct access roads. Along pipelines, unmanaged brush and tree growth can hide signs of ground movement, complicate access for integrity crews, and create higher-cost maintenance windows. In mixed utility rights-of-way, multiple assets and ownership boundaries make prioritization even harder.

Traditional patrol methods are valuable but expensive and episodic. They also do not always provide a consistent, quantitative record of where risk is increasing and how fast conditions are changing.

This tool addresses that gap by converting dense LiDAR point clouds into actionable corridor intelligence:

• It isolates points inside a configurable corridor of interest.
• It estimates local ground elevation and height-above-ground for each retained point.
• It classifies points into operational categories (vegetation, infrastructure, ground, unknown).
• It detects clustered encroachment events and merges them into maintenance intervals.
• It aggregates risk windows along chainage for dispatch-ready planning.
• It optionally writes GIS-ready spatial layers for mapping and work assignment.

What This Tool Does

Utility Corridor Encroachment Intelligence is a corridor-first LiDAR workflow for detecting and prioritizing encroachment risk. It produces both summary statistics and optional spatial outputs that can be loaded directly into standard GIS software.

Typical Questions This Tool Helps Answer

• Which segments of this transmission or pipeline corridor have vegetation encroachment that exceeds the safety clearance thresholds requiring immediate response?
• Where are clearance violations most severe and concentrated, and what is the ranked field-response priority queue for this patrol cycle?
• What is the total linear extent of at-risk corridor segments, and how does the risk profile compare to the previous survey cycle?

When To Use

• Routine corridor inspections and annual or seasonal vegetation assessments
• Pre-fire-season screening for transmission and distribution corridors
• Pipeline right-of-way condition audits and access planning
• Maintenance prioritization and crew dispatch planning
• Compliance reporting and right-of-way documentation
• Multi-epoch monitoring to compare encroachment growth over time

Required Inputs

Supported corridor types:

• pipeline
• powerline_transmission
• powerline_distribution
• telecom_aerial
• rail_overhead_electrified
• canal_drainage_infrastructure
• mixed_utility_row
• generic_linear_utility

Key Parameters

Outputs

How To Read the Results

Event Layer

Represents localized encroachment clusters. Use this layer to identify precise intervention targets and confirm recurring hotspots near structures.

Interval Layer

Represents merged event zones along corridor chainage. Use this layer for budgeting and planning contiguous treatment blocks instead of isolated point actions.

Risk Window Layer

Represents regular chainage windows with class counts, mean/max HAG, risk score, and priority band. Use this for crew allocation and week-by-week work packaging.

Summary JSON

Use the summary for program-level metrics:

• Total points seen and retained in the corridor ROI
• Counts by class label
• Number of events, intervals, and risk windows
• Culling diagnostics and timing by phase

Common Workflow

1. Validate overlap between corridor centerlines and LiDAR coverage.
2. Start with defaults (hag_reuse_cell_m = 2.0, k_neighbors = 9).
3. Generate all optional spatial outputs for mapping and operational review.
4. Review event/interval/risk-window densities with corridor managers.
5. Export selected zones to field operations for verification and treatment.

Troubleshooting Tips

• No retained ROI points: verify CRS alignment and increase corridor_width_m.
• Very low event count in dense vegetation: review corridor type selection and ground settings.
• Runtime too high: keep hag_reuse_cell_m enabled and split very large AOIs into manageable runs.

Operational Notes

The strongest value of this tool is repeatability. Running the same corridor with the same parameters over multiple LiDAR acquisition dates provides a stable basis for trend analysis, vegetation growth tracking, and defensible maintenance prioritization.

Terrain Constraint and Conflict Analysis

What This Tool Does

Terrain Constraint and Conflict Analysis scores terrain conflict severity from slope and optional wetness, flood-risk, and landcover-penalty rasters. It outputs a conflict score raster, a conflict class raster, a summary JSON, and an HTML report.

Typical Questions This Tool Helps Answer

• Which areas of this study region have terrain and environmental constraints severe enough to effectively preclude cost-effective development?
• Where do multiple constraint types overlap to create compounded conflict zones that will drive the highest mitigation costs?
• Which candidate development footprints fall in low-conflict terrain versus areas requiring significant engineering mitigation?

When To Use

• Early siting review where terrain and environmental constraints need a single comparable score
• Corridor or project screening before more detailed engineering review
• Rapid ranking of high-risk terrain areas for mitigation planning

What You Need

Key Settings

What You Get

The summary status becomes review when the high-conflict fraction exceeds 0.40.

Runtime Output Keys

result.outputs["conflict_score"]
result.outputs["conflict_class"]
result.outputs["summary"]
result.outputs["html_report"]

Common Questions

Q: Which result should I review first? A: Start with summary.high_conflict_fraction, then inspect where classes 3 and 4 concentrate in conflict_class.

Q: What is a common interpretation mistake? A: Assuming class 2 is always acceptable without checking local slope and wetness conditions.

Q: Which settings most change outcomes? A: slope_limit_deg and optional layers (wetness, flood_risk, landcover_penalty) have the largest influence on high-conflict footprint.

Q: How should planning teams use the outputs? A: Use high-conflict clusters to screen or reroute alignments before committing to final site or corridor decisions.

Results Delivery Checklist

• summary["status"] was reviewed
• conflict_class was inspected in GIS software
• Any high-conflict hotspots were checked before siting or mitigation decisions

Operational Notes

• Conflict class 3 and 4 cells should be treated as redesign or mitigation triggers in early siting workflows.
• slope_limit_deg is the highest-leverage parameter; adjust it intentionally and compare high_conflict_fraction across scenarios.
• Optional layers (wetness, flood_risk, landcover_penalty) are expected to be normalized to [0,1] for stable scoring behavior.

Related Tools

• terrain_constructability_and_cost_analysis
• corridor_mapping_intelligence
• utility_corridor_encroachment_intelligence

References

• Runtime implementation: wbtools_pro/src/tools/siting/terrain_constraint_and_cost.rs
• Terrain and Infrastructure Siting bundle overview: manual/pro-tools-customer/src/terrain_siting/overview.md

When To Use This Workflow

Use Terrain Constraint and Conflict Analysis when you need a repeatable conflict surface to screen and compare candidate routes or development footprints before detailed design.

Terrain Constructability and Cost Analysis

What This Tool Does

Terrain Constructability and Cost Analysis converts terrain, conflict, wetness, and access context into constructability and relative cost surfaces. It produces a constructability raster, a cost-class raster, a summary JSON, and an HTML report.

Typical Questions This Tool Helps Answer

• What is the relative construction cost surface for this project area, and which zones drive the highest grading and site preparation costs?
• Which portions of the proposed development footprint can be built at acceptable cost with minimal earthwork and site preparation?
• How does constructability and relative cost compare across the candidate site alternatives under review?

When To Use

• Preliminary constructability screening
• Relative cost comparison between development alternatives
• Early budget framing before detailed engineering estimates

What You Need

Key Settings

What You Get