OSMCOASTLINE(1)

📦
version 2.5.0 · 5 versions
, in ubuntu stonking

✨ osmcoastline ✨

okay bestie, gather round, because osmcoastline is literally the main character of OpenStreetMap coastline extraction and i need you to know her 💖

🌊 NAME 🌊

osmcoastline — pulls the coastline out of OpenStreetMap data, no cap 🌊🦋

📜 SYNOPSIS 📜

osmcoastline [OPTIONS] --output-database=OUTPUT-DB INPUT-FILE

💅 DESCRIPTION 💅

so here's the vibe: osmcoastline takes your INPUT-FILE — usually a planet file (or, and this is the glow-up move, the output of the osmcoastline_filter program, more on that below 👇) — and it extracts all the coastline data out of it, then assembles every little piece into polygons so map renderers and friends can actually use them. it's giving puzzle night but make it cartography 🧩

everything it makes gets written into the Spatialite database OUTPUT-DB. depending on which options you pass, that db will hold your coastlines in different formats. the deets are down in the options section below, and also in README.md if you want the full director's cut ✨

🎀 OPTIONS 🎀

  • -h, --help — shows you the usage info. the "help me help you" of it all 🫶
  • -b, --bbox-overlap=OVERLAP — when polygons are just Too Big™ they get split into two halves (and recursively again and again if they still can't behave). wherever those polygons touch, this OVERLAP gets added, because two polygons that merely kiss tend to cause rendering drama. the value is in whatever units your projection uses (so for WGS84 (EPSG: 4326) it's in degrees, and for Mercator (EPSG: 3857) it's in meters). set it too small and you'll get rendering artefacts at the touching points. set it bigger and your output polygons get bigger too. the ideal value depends on the map scale or zoom level you're prepping data for. set it to 0 to disable the overlap entirely. default is 0.0001 for WGS84 and 10 for Mercator. 💀 pick wisely
  • -c, --close-distance=DISTANCE — osmcoastline stitches ways tagged natural=coastline into rings, but sometimes the OSM data has a little gap in the coastline (rude). if that gap is smaller than DISTANCE, osmcoastline will close it for you. use 0 to turn this feature off completely.
  • -d, --debug — turns on debugging output. for when you need to see everything 👀
  • -e, --exit-ignore-warnings — exit with code 0 even if warnings happened. "i'm choosing peace" mode 😌
  • -f, --overwrite — overwrites the output file if it's already there. no hesitation, no mercy 💅
  • -g, --gdal-driver=DRIVER — lets you pick literally any GDAL driver. fair warning though: only the "SQLite", "GPKG" and "ESRI Shapefile" GDAL drivers have actually been tested. default is "SQLite".
  • -i, --no-index — skips creating spatial indexes in the output db. default is to create those indexes, which makes the db chunkier but data access faster. so this flag = smaller db, slower lookups. your call bestie ⚖️
  • -l, --output-lines — outputs the coastlines as lines into the database file.
  • -m, --max-points=NUM — set this to 0 and no splitting of large polygons and linestrings will happen, periodt. set it to any other positive integer and osmcoastline will try to split polygons/linestrings so they never have more than this many points. heads up: depending on the overlap you set with -b and the actual shape of the polygons, sometimes it's just not possible to get them small enough 😭 and osmcoastline will warn you on STDERR when that happens. default is 1000.
  • -o, --output-database=FILE — the Spatialite database file for output. this option is mandatory, like genuinely you cannot skip it. 🔥
  • -p, --output-polygons=land|water|both|none — which polygons get written out. default is land. pick your fighter 🌊🏝️
  • -r, --output-rings — outputs rings into the database file. this one's for debugging, iykyk 🔍
  • -s, --srs=EPSGCODE — sets the spatial reference system / projection. use 4326 for WGS84, or 3857 for "Web Mercator". if you're doing the usual tiled web maps, 3857 is probably the right call. for other stuff — especially if you want to re-project into some other projection — 4326 is probably right. other projections are currently not supported, sorry babe 🙈 default is 4326.
  • -S, --write-segments=FILENAME — writes out all coastline segments to the file you name. a segment is a connection between two points. these get written in an internal format that's meant for use with the osmcoastline_segments program only. the file contains all segments actually in the OSM data and only those. gaps are (possibly) closed at a later stage of osmcoastline's run, but those closing segments won't be in this file. so no, don't expect them 👑
  • -v, --verbose — gives you detailed info on what osmcoastline is doing, including timing. the play-by-play commentary 🎙️
  • -V, --version — displays the program version and license information.

📝 NOTES 📝

to speed up processing you might want to run the osmcoastline_filter program first. check its man page for the details, bestie 🏃♀️💨

🚨 DIAGNOSTICS 🚨

osmcoastline exits with exit code:

  • 0 — if everything was okay. we love a clean run ✨
  • 1 — if there were warnings while processing the coastline (unless -e is set).
  • 2 — if there were errors while processing the coastline.
  • 3 — if there was a fatal error when running the program.
  • 4 — if there was a problem with the command line arguments. we've all been there 😭

🌈 EXAMPLES 🌈

run osmcoastline on a planet file using the default options:

osmcoastline -o coastline.db planet.osm.pbf

running osmcoastline_filter first (the speedrun strat):

osmcoastline_filter -o coastline.osm.pbf planet.osm.pbf
osmcoastline -o coastline.db coastline.osm.pbf

👀 SEE ALSO 👀

Copyright (C) 2012-2026 Jochen Topf <jochen@topf.org>. License GPLv3+: GNU GPL version 3 or later <https://gnu.org/licenses/gpl.html>. This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. 📜 (yes that's the whole vibe, and yes you do have to keep it)

💌 CONTACT 💌

got questions? found a bug? wanna report it? go to <https://osmcode.org/contact.html> — they're nice, promise 🫶

👑 AUTHORS 👑

Jochen Topf <jochen@topf.org>.

and that's the whole page, bestie 💖 this was osmcoastline version 2.5.0, mwah, go make some beautiful coastlines 🌊✨

📦 where this page comes from