Metadata-Version: 2.4
Name: nds-mapviewer
Version: 2026.3.0
Summary: CLI to run the NDS MapViewer Docker container for visualizing map data (NDS.Live, GeoJSON, and more)
Author-email: NDS Association <support@nds-association.org>
License: Proprietary
Project-URL: Homepage, https://developer.nds.live/tools/mapviewer
Project-URL: Documentation, https://developer.nds.live/tools/mapviewer
Keywords: nds,ndslive,mapviewer,docker,maps
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: textual>=1.0.0
Provides-Extra: browser
Requires-Dist: playwright>=1.40.0; extra == "browser"
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12; extra == "dev"
Requires-Dist: pytest-order>=1.2; extra == "dev"

# NDS MapViewer CLI

Visualize NDS.Live, NDS.Classic, and GeoJSON map data on a deck.gl-based map
with live style editing, feature inspection, and layer management — all from
a single `mapviewer` command. No container-runtime knowledge required.

> **Beta** — This Python package is in early development. The CLI interface may
> change between releases. Feedback and bug reports are welcome via the
> [NDS developer portal](https://developer.nds.live/tools/mapviewer).

Full documentation: **https://developer.nds.live/tools/mapviewer**

## Features

- **Map visualization** powered by [deck.gl](https://deck.gl/) via [erdblick](https://github.com/ndsev/erdblick)
- **Multiple data formats** — NDS.Live, GeoJSON, NDS.Classic (member edition)
- **Live style editing** — modify map styles in real time with YAML-based rules
- **Feature inspection** — click any map feature to explore its attributes and relations
- **Local and remote data** — view SmartLayer folders, FileStore files, or remote services
- **Guided setup** — interactive wizard for creating data source configs
- **Config management** — save, switch, and delete configs from the RunScreen (`c`)

## Getting Started

The recommended way to set up your NDS.Live environment (credentials, container registry, pip index) is via [`ndslive-setup`](https://pypi.org/project/ndslive-setup/):

```bash
pip install ndslive-setup
ndslive-setup
```

This interactive wizard configures everything you need in one step, including installing `nds-mapviewer`.

Either Docker or [Podman](https://podman.io) works as the container runtime — Podman is a free alternative if you cannot use Docker Desktop's commercial license.

## Usage

```bash
mapviewer                         # HomeScreen (or auto-loads ~/.nds/config.yaml)

mapviewer /path/to/data.ndslive   # View a local FileStore
mapviewer /path/to/folder         # View a local SmartLayer folder
mapviewer /path/to/geojson/       # View a GeoJSON folder
mapviewer https://host/openapi.json  # Connect to a remote service (unauthenticated)
mapviewer --demo                  # Try it with NDS Islands sample data

mapviewer mywork                  # Load a saved config by name
mapviewer /path/a.ndslive /path/b # Multiple sources at once

mapviewer --demo --debug          # Enable debug logging in the container
mapviewer --demo --env KEY=VALUE  # Set a custom container env var (repeatable)
mapviewer --demo --network host   # Run the container on the host network
```

All commands accept `-e community|member` and `-i VERSION`.

### Remote service URLs

A source can be an http(s) service URL (e.g. `mapviewer https://my-host/openapi.json`),
which is turned into a `SmartLayerTileService`. The bare-URL form configures **no
authentication** — for protected services, proxy them through `ndslive-server` or
declare the service in a `config.yaml` with an `http-settings` block (api-key, basic,
bearer, OAuth2, proxy).

For a service running on your own machine, use `localhost`/`127.0.0.1`
(e.g. `mapviewer http://127.0.0.1:8080/openapi.json`) — it is automatically
rewritten to `host.docker.internal` so the container can reach it. You do **not**
need `--network host` for this.

### Container environment variables

`--debug` turns on verbose logging in the MapViewer container (shorthand for
`--env HTTP_LOG_LEVEL=debug`). Use `--env KEY=VALUE` (repeatable, short form
`-E`) to pass arbitrary environment variables into the container; explicit
`--env` entries override `--debug` on key collision. The resulting `-e` flags
appear in the Docker screen's "Copy Command" output.

### Container network

`--network NAME` attaches the container to a specific network (e.g. a custom
bridge or `host`). With `--network host` the container binds the host's port
directly, so `--port`/`--bind` are ignored and the MapViewer is reached on its
internal port (8089). Host networking behaves differently across platforms and
runtimes — it is intended as a connectivity workaround.

If `~/.nds/config.yaml` exists, `mapviewer` (with no arguments) loads it
automatically and goes straight to the RunScreen.

If you edit `~/.nds/config.yaml` manually, use host paths there, not container
paths. The CLI translates them into the correct container mounts when it starts
the container runtime.

The run screen shows, below the info banner, the source you passed (a config
file or a directly-given data-source path such as a `*.ndslive` filestore) and
the mapped config that was generated and mounted into the container.

## Editions

| Edition | Formats | Access |
|---------|---------|--------|
| **community** | NDS.Live, GeoJSON, open formats | Free — [nds.live](https://nds.live) |
| **member** | + NDS.Classic | [NDS membership](https://nds-association.org/#contact) |

## Open-Source Building Blocks

- **[mapget](https://github.com/ndsev/mapget)** — tile-based map data server with caching
- **[erdblick](https://github.com/ndsev/erdblick)** — deck.gl-based web frontend with live style editing and inspection tools

## License

The MapViewer is a proprietary product of the NDS Association. License terms
and conditions are governed by the account type used to access the Docker
image — registering for a community or member account includes accepting the
applicable licensing terms for the MapViewer and its components.
