Skip to content

Scripts Directory Guide

This directory contains production-ready Python scripts for maritime analysis and routing workflows.

Quick Overview

Script Purpose Backend(s) Use When
import_s57.py Import S-57 ENC data into GIS formats PostGIS, GeoPackage, SpatiaLite Converting raw S-57 charts to usable databases
maritime_graph_postgis_workflow.py End-to-end maritime routing workflow PostGIS Need complete workflow with server-based database
maritime_graph_geopackage_workflow.py End-to-end maritime routing workflow GeoPackage/SpatiaLite Need portable, file-based workflow

Script Descriptions

1. import_s57.py

Purpose: Convert S-57 Electronic Navigational Chart (ENC) data into GIS-ready formats with flexible modes and backends.

Key Features:

  • 3 conversion modes: Base (one-to-one), Advanced (layer-centric with source tracking), Updater (incremental updates)
  • 3 backend support: PostGIS, GeoPackage, SpatiaLite
  • Comprehensive validation and verification
  • Performance benchmarking
  • Supports all S-57 object classes

Quick Start: 

# Convert to GeoPackage with verification
python scripts/import_s57.py --mode advanced --input-path data/ENC_SF_LA/ENC_ROOT \
  --output-format gpkg --schema enc_west --verify

# Convert to PostGIS
python scripts/import_s57.py --mode advanced --input-path data/ENC_SF_LA/ENC_ROOT \
  --output-format postgis --schema enc_west --verify

Related Guide: See docs/user-guides/workflow-s57-import-guide.md for comprehensive documentation.

2. maritime_graph_postgis_workflow.py

Purpose: Orchestrate complete maritime navigation graph creation and routing workflow using PostGIS backend.

Workflow Steps:

  1. Create base graph (0.3 NM resolution)
  2. Create fine/H3 graph (0.02-0.3 NM or hexagonal)
  3. Apply three-tier weighting (static, directional, dynamic)
  4. Calculate optimal routes

Key Features:

  • Configuration-driven (YAML)
  • Automatic schema management
  • Performance benchmarking
  • Support for custom vessel parameters
  • Production-grade logging

Quick Start: 

# Full workflow with PostGIS backend
python scripts/maritime_graph_postgis_workflow.py --config config/workflow_config.yml

# Skip base graph (already exists)
python scripts/maritime_graph_postgis_workflow.py --config config/workflow_config.yml --skip-base

# Custom vessel draft
python scripts/maritime_graph_postgis_workflow.py --config config/workflow_config.yml --vessel-draft 12.0

Related Guide: See docs/user-guides/workflow-postgis-guide.md for detailed workflow documentation.

3. maritime_graph_geopackage_workflow.py

Purpose: Orchestrate complete maritime navigation graph creation and routing workflow using file-based backend (GeoPackage/SpatiaLite).

Workflow Steps: Same as PostGIS workflow (base → fine → weighting → pathfinding) but stores results in portable GeoPackage files instead of database.

Key Features:

  • No server required (file-based)
  • Fully portable and offline-capable
  • Same weighting and routing as PostGIS
  • Ideal for single-user and portable deployments

Quick Start: 

# Full workflow with GeoPackage backend
python scripts/maritime_graph_geopackage_workflow.py --config config/workflow_config.yml

# Use fine grid instead of H3
python scripts/maritime_graph_geopackage_workflow.py --config config/workflow_config.yml --graph-mode fine

# INFO mode: Clean logs, ~1MB per file (default)
python scripts/maritime_graph_geopackage_workflow.py --config config/workflow_config.yml --log-level INFO

# DEBUG mode: Full debugging, ~5-10MB per file
# Third-party verbose logging automatically suppressed
python scripts/maritime_graph_geopackage_workflow.py --config config/workflow_config.yml --log-level DEBUG

Related Guide: See docs/user-guides/workflow-geopackage-guide.md for detailed workflow documentation.

Decision Guide: Which Script to Use?

Scenario 1: "I have raw S-57 ENC files and need to prepare them for analysis"

→ Use import_s57.py

  • Choose backend: PostGIS (server), GeoPackage (portable), or SpatiaLite (lightweight)
  • Choose mode: Base (simple), Advanced (recommended), or Updater (update existing)
  • Example: python scripts/import_s57.py --mode advanced --input-path data/ENC_ROOT --output-format gpkg --verify

Scenario 2: "I have S-57 data in PostGIS and want complete maritime routing workflow"

→ Use maritime_graph_postgis_workflow.py

  • Assumes S-57 data already loaded in PostGIS schema (enc_west or custom)
  • Handles all steps: graph creation, weighting, routing
  • Best for production and large datasets
  • Example: python scripts/maritime_graph_postgis_workflow.py

Scenario 3: "I need portable, offline maritime routing (no server)"

→ Use maritime_graph_geopackage_workflow.py

  • File-based, single-file output (.gpkg)
  • Works offline, shareable between systems
  • Slightly slower but fully portable
  • Example: python scripts/maritime_graph_geopackage_workflow.py

Scenario 4: "I need to update existing S-57 data with new charts"

→ Use import_s57.py with update mode

  • Updates existing database/GeoPackage incrementally
  • Transactional (all-or-nothing)
  • Example: python scripts/import_s57.py --mode update --update-source data/ENC_ROOT_UPDATE --output-format postgis --schema enc_west --force-update

Common Usage Patterns

Pattern 1: Quick Testing (5 minutes)

# 1. Convert sample S-57 data
python scripts/import_s57.py --mode base --input-path data/ENC_ROOT \
  --output-format gpkg --schema test_data --dry-run

# 2. Run full workflow
python scripts/maritime_graph_geopackage_workflow.py --dry-run

Pattern 2: Production Setup (PostGIS)

# 1. Convert all ENC data to PostGIS
python scripts/import_s57.py --mode advanced --input-path data/ENC_SF_LA/ENC_ROOT \
  --output-format postgis --schema enc_west --verify --verbose

# 2. Run complete workflow
python scripts/maritime_graph_postgis_workflow.py

# 3. Monitor with comprehensive logging
# INFO mode (recommended): Clean logs, essential info only
python scripts/maritime_graph_postgis_workflow.py --log-level INFO

# DEBUG mode: Full debugging with third-party suppression
python scripts/maritime_graph_postgis_workflow.py --log-level DEBUG

Pattern 3: Portable Deployment (GeoPackage)

# 1. Convert S-57 to GeoPackage once
python scripts/import_s57.py --mode advanced --input-path data/ENC_SF_LA/ENC_ROOT \
  --output-format gpkg --schema enc_west --verify

# 2. Run workflow (no server needed)
python scripts/maritime_graph_geopackage_workflow.py

# 3. Share output/*.gpkg files (fully portable)

Test Data Available

The project includes test data for quick evaluation:

Location Size Use Case
data/ENC_ROOT/ 6 ENCs Quick testing, verification
data/ENC_SF_LA/ENC_ROOT/ 47 ENCs LA-SF route, realistic testing
data/enc_west.gpkg 47 ENCs converted Pre-converted reference (GeoPackage format)

Quick test example: 

# Test import_s57.py with 6 sample ENCs
python scripts/import_s57.py --mode advanced --input-path data/ENC_ROOT \
  --output-format gpkg --schema test --verify

# Expected time: ~20-24 seconds
# Output: test.gpkg with verified maritime layers

Installation & Requirements

Prerequisites

  • Python 3.11+
  • GDAL 3.10.3
  • Dependencies: pip install -e . or Conda+uv setup
  • For PostGIS: PostgreSQL 16+ with PostGIS extension + .env credentials

Basic Setup

# Install project and dependencies
mamba env update -f environment.yml --prune
pip install uv
uv pip compile requirements.in -o requirements.txt  # Optional: skip to use tested snapshot
uv pip install --no-deps -r requirements.txt
uv pip install -e .

# Set database credentials (if using PostGIS)
cp .env.example .env
# Edit .env with your PostgreSQL connection details

Common Options

All Scripts Support:

  • --help - Show all available options
  • --verbose - Enable debug logging
  • --dry-run - Validate without execution (import_s57.py, workflow scripts)

import_s57.py Specific:

  • --mode - Conversion mode: base, advanced, update
  • --output-format - Backend: postgis, gpkg, spatialite
  • --verify - Run post-conversion verification
  • --force-update - Force clean install instead of incremental update
  • --benchmark-output - Export performance metrics to CSV
  • --schema - Custom schema/database name

Workflow Scripts Specific:

  • --config - Custom configuration YAML file (default: config/workflow_config.yml)
  • --data-dir - Override ENC data directory (default: data/)
  • --skip-base / --skip-fine / --skip-weighting / --skip-pathfinding - Skip steps
  • --graph-mode - Graph type: fine (grid) or h3 (hexagonal)
  • --vessel-draft - Override vessel draft in meters
  • --log-level - Console output level: INFO or DEBUG

Detailed Documentation

For comprehensive guides, see:

  • S-57 Import: docs/user-guides/workflow-s57-import-guide.md - All modes, backends, examples, troubleshooting
  • PostGIS Workflow: docs/user-guides/workflow-postgis-guide.md - Server-based complete workflow
  • GeoPackage Workflow: docs/user-guides/workflow-geopackage-guide.md - File-based complete workflow
  • Setup Guide: docs/getting-started/setup.md - Environment setup and data requirements
  • Quick Start: docs/getting-started/workflow-quickstart.md - Get started in 5 minutes
  • Troubleshooting: docs/reference/troubleshooting.md - Common issues and solutions

Next Steps

  1. Choose your workflow - See decision guide above
  2. Review test data - Use data/ENC_ROOT/ for quick testing
  3. Run a script - Start with --dry-run to validate setup
  4. Check detailed guides - Reference links above for comprehensive documentation
  5. Monitor execution - Use --verbose or --log-level DEBUG for debugging

Support

  • Check docs/reference/troubleshooting.md for common issues
  • Use --help on any script for complete option reference
  • Enable verbose logging with --verbose for debugging
  • Review script docstrings for implementation details