dimahkiin/osm2gmns repository overview

⁠dimahkiin/osm2gmns

osm2gmns converts OpenStreetMap road network data (.osm XML or .osm.pbf) into GMNS-format CSV files. It produces a routable graph at three levels of detail: macroscopic (plus a movements layer), mesoscopic (lane-level) and microscopic (cell-based). It is a batch CLI that reads an input file, writes CSV files and exits - it is not a server and listens on no ports.

Source code: https://github.com/LdDl/osm2gmns⁠

⁠Configuration

Configuration is entirely through command-line flags. The image reads no environment variables, no configuration file, and exposes no HTTP endpoints. ENTRYPOINT is the binary itself, so flags are appended directly to docker run; with no arguments the image runs --help.

Minimal working invocation:

docker run --rm -v "$(pwd):/data" dimahkiin/osm2gmns:latest -input /data/map.osm

Notes that are not obvious:

• Paths must be paths inside the container. The tool never downloads anything; the OSM file has to be mounted in.
• Flags use Go's flag package: a boolean must be written as -verbose=false, not -verbose false (the latter is parsed as a positional argument and silently ignored).
• Requesting -networks micro generates the movement and meso layers internally as prerequisites, but exports only the levels you list.
• The container runs as root by default, so CSV files land on the host mount owned by root. Pass --user "$(id -u):$(id -g)" to keep them owned by you.
• The image is built FROM scratch: there is no shell, so docker run ... sh and docker exec will not work, and docker cp or a bind mount is the only way to move files.

⁠Usage

# Convert ./map.osm and write all CSV levels to ./results on the host
docker run --rm \
    --user "$(id -u):$(id -g)" \
    -v "$(pwd):/data" \
    dimahkiin/osm2gmns:latest \
    -input /data/map.osm \
    -output /data/results

# Macro + movement only, cars only, quiet
docker run --rm \
    --user "$(id -u):$(id -g)" \
    -v "$(pwd):/data" \
    dimahkiin/osm2gmns:latest \
    -input /data/map.osm.pbf \
    -output /data/results \
    -networks macro,movement \
    -agents auto \
    -verbose=false

# Named volume instead of a bind mount
docker volume create osm-data
docker run --rm -v osm-data:/data dimahkiin/osm2gmns:latest \
    -input /data/map.osm -output /data/results

# Version / help
docker run --rm dimahkiin/osm2gmns:latest -version
docker run --rm dimahkiin/osm2gmns:latest

⁠Ports

⁠Paths inside the container

Files written into -output, depending on -networks:

⁠Environment

The image uses no environment variables. Version, build time and git commit are baked in at build time via -ldflags (VERSION, BUILD_TIME, GIT_COMMIT build args) and are readable with -version.

⁠Image

Built in two stages: golang:1.23-alpine compiles a static binary (CGO_ENABLED=0, -ldflags "-s -w"), and the runtime stage is FROM scratch containing only that binary. Size is approximately 6.5 MB uncompressed - the binary is the whole image. No shell, no package manager, no CA certificates.

⁠License

The repository does not ship a license file, so no license is declared for this image: https://github.com/LdDl/osm2gmns⁠

The project is a Go port of OSM2GMNS⁠; see go-gmns⁠ for the GMNS data format documentation.