MOOS Map Builder

Build cropped TIFF background maps for MOOS-IvP through a local browser UI or the moos-map command. Both interfaces use the same map sources, crop logic, cache, and MOOS compatibility checks.

PyPI Project

Install

MOOS Map requires Python 3.11 or newer and pipx. On macOS, install pipx and add its application directory to your shell path once:

brew install pipx
pipx ensurepath

Then install MOOS Map in its own managed environment:

pipx install moos-map

Then launch the UI:

moos-map ui

UI

Click any two diagonally opposite corners to select a region. Click-hold-drag pans the map; another single click starts a replacement selection. Review the summary and choose Build Map.

Use Find a place or enter lat, lon above the map to move the preview to a known location. Place-name autocomplete uses the public Photon service and requires an internet connection; direct coordinates work locally. Search only moves the preview viewport and never changes the selected export region, mission origin, or export zoom.

Esri World Imagery and zoom 17 are the defaults. The origin defaults to the map center. For an existing mission, open 04 Advanced placement and enter its LatOrigin and LongOrigin, or drag the red origin dot.

CLI

Build with the same defaults by supplying any two diagonal corners as latitude longitude pairs:

moos-map build \
  --corners 42.358 -71.088 42.359 -71.087 \
  --name harbor

For an existing mission, supply its origin:

moos-map build \
  --corners 42.358 -71.088 42.359 -71.087 \
  --origin 42.358436 -71.087448 \
  --name harbor

Useful commands:

moos-map sources
moos-map plan --corners 42.358 -71.088 42.359 -71.087
moos-map verify ~/moos-maps/harbor/harbor.tif
moos-map build -h

build downloads immediately; running sources or plan first is optional. Use --zoom, --source, or --output-dir to override defaults. Builds include a .moos snippet and replace same-named bundles safely by default. See moos-map build -h for opt-out and cache controls.

Output

Each map gets its own directory:

~/moos-maps/harbor/
├── harbor.tif
├── harbor.info
└── harbor.moos

Copy the .tif and .info files into a mission directory, or add that exact map directory to IVP_IMAGE_DIRS. Then add the generated harbor.moos settings to the mission. pMarineViewer does not recursively search ~/moos-maps.

The TIFF is cropped to the selected coordinates; extra downloaded tile margins are discarded. Source and requested-bound provenance is kept as ignored // comments in the .info; no JSON sidecar is created.

Sources

Built-ins include Esri World Imagery, Google Satellite, Google Hybrid, Google Maps, and Esri World Topographic. Local MBTiles and custom XYZ services are also supported. Native detail varies by location. A listed provider is not a grant of export rights; check its current terms before downloading hosted imagery.

The tile cache is ${XDG_CACHE_HOME:-~/.cache}/moos-map/tiles.

Development

git clone https://github.com/cbenjamin23/moos-map.git
cd moos-map
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[test]'
python -m pytest

See docs/architecture.md for module boundaries, docs/validation.md for the MIT pMarineViewer comparison, and TODO.md for deferred work.

License

GPL-3.0-only. See LICENSE.

Acknowledgements

MOOS Map grew out of earlier map-building work in the MOOS-IvP community. We are grateful to:

• HeroCC/AnaxiMap for demonstrating a practical tile-download and stitching workflow that inspired MOOS Map's map acquisition pipeline.
• Raymond Turrisi for his map-building prototype, which helped shape the practical workflow and direction of this project.