MedChart is an open-source research software project for building reproducible Mediterranean marine geospatial products and Signal K-compatible nautical-chart MBTiles from publicly redistributable datasets.
The repository is intentionally organized as a monorepo with two Python components:
packages/medchart-data— reproducible acquisition, source discovery, provenance, checksums, frozen snapshots, and source registries.packages/medchart-preprocess— deterministic normalization, multi-source fusion reference algorithms, quality gates, cartographic post-processing, publication figures, and Signal K-ready MBTiles generation.
The current software release is 1.0.0. The project is MIT licensed; downloaded third-party datasets retain their own licences and attribution requirements.
MedChart derivatives are multi-source scientific products. Every map, MBTiles file, figure, service, paper, and release must visibly credit every dataset that actually contributed cells or features and must ship its machine-readable provenance. The MIT software licence does not relicense any input data.
The authoritative, source-by-source register is
docs/data_sources_and_citation.md. It gives full
bibliographic citations, mandatory map acknowledgements, licences, persistent identifiers,
coverage/resolution limitations, frozen-manifest locations, and a FAIR release checklist.
For the current From Gaeta to Maratea production build, acknowledge:
- JammeGaia22/MGDS bathymetry: Foglini, F., Tonielli, R., & Rovere, M. (2024), Multi-Resolution bathymetry grids of the Naples and Pozzuoli Gulf and Amalfi Coastal Area, Jamme_Gaia22 (2022), https://doi.org/10.60521/331667, CC BY 4.0.
- EMODnet fallback bathymetry: EMODnet Bathymetry Consortium (2024), EMODnet Digital Bathymetry (DTM 2024), https://doi.org/10.12770/cf51df64-56f9-4a99-b1aa-36b8d7b743a1, CC BY 4.0. EMODnet is used only where JammeGaia22 contains no finite measurement.
- Land/coastline: GSHHG 2.3.7 (Wessel & Smith, 1996, https://doi.org/10.1029/96JB00104) and, when enabled, S2Coast-2023 (Duan et al., https://doi.org/10.5281/zenodo.17092775, CC BY 4.0). These remain separate topology and high-water-line facts.
- Navigation and land context:
© OpenStreetMap contributors, ODbL 1.0, https://www.openstreetmap.org/copyright.
The required short-form map credit is:
Bathymetry: Foglini, Tonielli & Rovere (2024), JammeGaia22/MGDS, doi:10.60521/331667; EMODnet Bathymetry Consortium DTM 2024, doi:10.12770/cf51df64-56f9-4a99-b1aa-36b8d7b743a1. Land/coastline: GSHHG 2.3.7 and S2Coast-2023. Context: © OpenStreetMap contributors, ODbL 1.0. Not for navigation.
Do not list GMRT, GEBCO, EMODnet thematic products, or ISPRA as contributors unless the specific run manifest proves that they were used. Citation is source-specific evidence, not a generic project boilerplate.
public marine datasets
|
v
medchart-data
acquisition + provenance
|
v
immutable raw snapshots
|
v
medchart-preprocess
normalization + partitioning
|
v
MCB v2 reference computation
|
v
quality-aware cartographic post-processing
|
v
XYZ / MBTiles / TileJSON / Signal K metadata
The current Gulf-of-Naples production policy requires explicit land polygons, processed coastline geometry, and genuine high-resolution shallow-water bathymetry for detailed chart scales. The software fails closed rather than manufacturing harbour-scale detail from coarse bathymetry.
Each package is independently installable from the monorepo:
python -m venv .venv
source .venv/bin/activate
pip install -e 'packages/medchart-data[dev]'
pip install -e 'packages/medchart-preprocess[dev,osm,viz]'Run the test suites with:
pytest packages/medchart-data/tests
pytest packages/medchart-preprocess/testsGitHub Actions validates both packages on Python 3.11 and 3.12. Each CI job installs
the package from its declared metadata, checks Ruff formatting and lint, runs MyPy,
audits documentation links and release metadata, and executes the deterministic test
suite with coverage. A dependent job builds both source and wheel distributions only
after every quality job succeeds. Tests set Matplotlib's non-interactive backend and do
not download scientific datasets. The runner checks out the repository beneath its
ephemeral data/ directory and executes every package and distribution command from
that checkout root; the repository-level /data/ tree is ignored locally in its
entirety so raw or derived scientific artifacts cannot be committed accidentally.
Detailed, academic-level documentation is maintained inside each component:
docs/getting_started.md— end-to-end, copy-paste production guide using/datafor downloads, immutable snapshots, intermediate artifacts, quality gates, MBTiles, and final figures.docs/data_sources_and_citation.md— authoritative dataset register, acknowledgements, complete citations, licences, persistent identifiers, and FAIR provenance/release requirements.docs/from_gaeta_to_maratea.md— exact regional profile and JammeGaia22-to-native-EMODnet fallback workflow for the Gaeta–Maratea chart.docs/dissemination_and_deployment.md— legal publication gate, release packaging, online dissemination, and rollback-safe Signal K deployment and verification.packages/medchart-data/docspackages/medchart-preprocess/docs
The acquisition documentation covers NOAA/NCEI GSHHG, S2Coast-2023, ISPRA PNRR MER shallow-source contracts, EMODnet, GEBCO, OSM navigation context, MGDS/JammeGaia22, EMODnet Human Activities, EMODnet Geology, EUSeaMap, provenance, licensing, and source-resolution hierarchy.
The preprocessing documentation covers the HPC input/output contracts, FAIR methodology, normalization, multi-resolution fusion, coastline quality, production quality gates, sequential reference algorithms, nautical portrayal, MBTiles/Signal K integration, validation, publication figures, and production orchestration.
The Python sequential reference implementation is the executable scientific specification for the future C++ heterogeneous implementation using MPI/OpenMPI, node-level CPU parallelism, and CUDA. Parallel implementations must consume the same normalized inputs and reproduce the normative output contract before performance results are accepted.
MedChart produces research/recreational cartographic products. It does not create official ENCs, certified ECDIS products, or a substitute for official navigation charts. Source authority, survey resolution, temporal currency, licences, and vertical datums remain explicit provenance properties.
Source code is distributed under the MIT License. Third-party datasets are not relicensed by this repository.