Jupyter Notebooks¶

Interactive tutorials and examples for the Nautical Graph Toolkit. Each notebook demonstrates real-world workflows with actual S-57 ENC data.

📚 Available Notebooks¶

S-57 Data Import & Conversion¶

Transform raw S-57 ENC data into geospatial databases.

S-57 Import Guide - Import ENC files into databases
ENC Factory Deep Test - Comprehensive ENC processing
S-57 Utilities - S-57 attribute lookups and data inspection

Maritime Graph Creation¶

Build routing networks with different backends and resolutions.

PostGIS Workflows¶

BaseGraph - PostGIS - Coarse 0.3 NM grid on PostGIS
FineGraph - PostGIS - Detailed 0.02-0.3 NM refinement
Weighted Routing - PostGIS - Graph weighting & optimization

GeoPackage Workflows¶

BaseGraph - GeoPackage - Coarse grid on GeoPackage
FineGraph - GeoPackage - Detailed refinement
Weighted Routing - GeoPackage - Graph weighting

SpatiaLite Workflows¶

Graph - SpatiaLite - Complete workflow on lightweight SpatiaLite

Utilities & Analysis¶

Helper functions and data inspection tools.

Port Utilities - World Port Index integration & port queries
Layer Inspection - Analyze ENC layer contents and attributes
Geometry Utilities - Buffer and Bearing operations demo
Edge Inspection - Edge weight inspection and analysis

Advanced Analysis¶

Performance benchmarking and algorithm comparison.

Pathfinding Comparison - A* algorithm variant comparison
Performance Metrics - Workflow performance benchmarking

🚀 How to Use¶

Option 1: View Online¶

Each notebook link above will open in Jupyter nbviewer (read-only).

Option 2: Run Locally¶

Prerequisites¶

Install the toolkit following the Installation Guide, then verify Jupyter is available:

python -c "from jupyter import __version__; print(f'Jupyter {__version__} installed')"

Start Jupyter¶

# From project root
jupyter notebook

# Or use Jupyter Lab (recommended)
jupyter lab

Then navigate to docs/notebooks/ and select a notebook.

Option 3: Google Colab (Cloud)¶

Several notebooks are Colab-compatible for cloud execution without local setup.

📊 Notebook Categories¶

Beginner¶

Start here if you're new to the toolkit.

Intermediate¶

Deep dives into specific features.

Advanced¶

Production workflows and optimization.

💾 Backend Comparison¶

These notebooks demonstrate the same workflows across different backends. See the Setup Guide — Backend Comparison for a full feature table.

Recommendation: Start with GeoPackage for simplicity, scale to PostGIS for production.

⚙️ Prerequisites¶

All notebooks require:

Python 3.11+
GDAL 3.10.3 (installed via Conda)
Nautical Graph Toolkit installed in editable mode
Sample S-57 ENC data (included in tests/data/ENC_ROOT/)

📝 Tips for Running Notebooks¶

Cell-by-cell execution: Run cells individually to explore intermediate results
Check memory: Large ENC datasets may need >4GB RAM
Enable outputs: Use jupyter notebook --NotebookApp.trust_xsrfless_cookies=False
Export results: Save GeoJSON outputs and open in QGIS for visualization

🐛 Troubleshooting¶

Issue: GDAL not found

# Verify GDAL is installed in conda environment
python -c "from osgeo import gdal; print(gdal.__version__)"

Issue: Database connection errors

# Check PostGIS is running (if using PostGIS)
docker-compose ps

# Or verify GeoPackage file exists
ls -la maritime.gpkg

Issue: Notebook doesn't start

# Ensure Jupyter is installed in the activated environment
mamba activate nautical
pip install jupyter jupyterlab

💡 Want to Contribute?¶

Notebooks are a great way to contribute! If you have interesting examples or improvements:

Create your notebook in docs/notebooks/
Test thoroughly with multiple backends
Add it to this index
Submit via GitHub

See Contributing Guide for details.

Happy exploring! 🚢⚓