Metadata-Version: 2.4
Name: moos-map
Version: 1.1.0
Summary: Build exact-crop TIFF background maps for MOOS-IvP
License-Expression: GPL-3.0-only
Project-URL: Repository, https://github.com/cbenjamin23/moos-map
Project-URL: Issues, https://github.com/cbenjamin23/moos-map/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi<1,>=0.115
Requires-Dist: httpx<1,>=0.27
Requires-Dist: Pillow<13,>=10.4
Requires-Dist: pydantic<3,>=2
Requires-Dist: uvicorn<1,>=0.30
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Dynamic: license-file

# 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](https://pypi.org/project/moos-map/)

## Install

MOOS Map requires Python 3.11 or newer and [pipx](https://pipx.pypa.io/). On
macOS, install pipx and add its application directory to your shell path once:

```sh
brew install pipx
pipx ensurepath
```

Then install MOOS Map in its own managed environment:

```sh
pipx install moos-map
```

Then launch the UI:

```sh
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:

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

For an existing mission, supply its origin:

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

Useful commands:

```sh
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:

```text
~/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

```sh
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](docs/architecture.md) for module boundaries,
[docs/validation.md](docs/validation.md) for the MIT pMarineViewer comparison,
and [TODO.md](TODO.md) for deferred work.

## License

GPL-3.0-only. See [LICENSE](LICENSE).
