dotted-map 0.1.0__tar.gz

dotted_map-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,24 @@
+# Publishes a release to PyPI when a tag such as v0.2.0 is pushed, by trusted
+# publishing (no token is stored): on PyPI, the project's publisher is this
+# repository, this workflow (release.yml) and the environment "pypi".
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+      - name: The tag matches the version in pyproject.toml
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv run --locked pytest
+      - run: uv build
+      - run: uv publish --trusted-publishing always

dotted_map-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,38 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.15"]
+    steps:
+      - uses: actions/checkout@v7
+      # rsvg-convert, and the Cairo library that CairoSVG needs, so that
+      # both converters are tested.
+      - run: sudo apt-get update && sudo apt-get install -y librsvg2-bin
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+      - run: uv run --locked --python ${{ matrix.python }} pytest
+
+  oldest:
+    # The oldest versions of the dependencies that pyproject.toml allows.
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+      - run: uv venv --python 3.10
+      # A block scalar, because ":all: " would end a plain YAML value.
+      - run: |
+          uv pip install --resolution lowest-direct --only-binary :all: -e . "pytest>=8"
+      - run: .venv/bin/python -m pytest tests
+
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
+      - run: uv run --locked --python 3.14 --group docs sphinx-build -W --keep-going -b html docs docs/_build/html

dotted_map-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.venv/
+dist/
+.coverage
+docs/_build/
+docs/_generated/
+# Maps drawn while trying things out; the README picture is kept.
+/*.svg
+/*.png
+/*.pdf
+/*.json

dotted_map-0.1.0/.readthedocs.yaml

@@ -0,0 +1,19 @@
+# How Read the Docs builds the documentation at
+# https://dotted-map.readthedocs.io/ (see
+# https://docs.readthedocs.com/platform/stable/config-file/v2.html).
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.14"
+  jobs:
+    # dotted-map with the docs dependency group of pyproject.toml, which
+    # needs pip 25.1 or later.
+    install:
+      - python -m pip install --upgrade pip
+      - python -m pip install . --group docs
+
+sphinx:
+  configuration: docs/conf.py
+  fail_on_warning: true

dotted_map-0.1.0/CHANGELOG.md

@@ -0,0 +1,9 @@
+# Changelog
+
+## 0.1.0 (2026-11-15)
+
+The first release: dotted maps of any area, in any projection, framed on,
+highlighted by or restricted to countries, continents and subregions, with
+pins and curved routes, drawn as SVG, PNG, PDF or JSON from Python or the
+command line. It replaces the code of the scipython.com post
+[Making a map out of dots](https://scipython.com/blog/making-a-map-out-of-dots/).

dotted_map-0.1.0/CITATION.cff

@@ -0,0 +1,41 @@
+cff-version: 1.2.0
+message: If you use this software, please cite it as below.
+type: software
+title: dotted-map
+abstract: >-
+  Draw maps on which land is a regular lattice of dots, as SVG, PNG and PDF
+  images for graphic design and infographics.
+authors:
+  - given-names: Christian
+    family-names: Hill
+license: BSD-3-Clause
+repository-code: "https://github.com/xnx/dotted-map"
+url: "https://dotted-map.readthedocs.io"
+keywords:
+  - cartography
+  - dotted map
+  - graphic design
+  - halftone
+  - map projection
+references:
+  - type: data
+    title: Natural Earth
+    url: "https://www.naturalearthdata.com"
+    version: 5.1.2
+    authors:
+      - name: Natural Earth
+  - type: article
+    title: The Equal Earth map projection
+    authors:
+      - given-names: Bojan
+        family-names: Šavrič
+      - given-names: Tom
+        family-names: Patterson
+      - given-names: Bernhard
+        family-names: Jenny
+    journal: International Journal of Geographical Information Science
+    volume: 33
+    issue: 3
+    start: 454
+    year: 2019
+    doi: 10.1080/13658816.2018.1504949

dotted_map-0.1.0/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, Christian Hill
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

dotted_map-0.1.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: dotted-map
+Version: 0.1.0
+Summary: Draw maps on which land is a regular lattice of dots, as SVG, PNG or PDF images
+Project-URL: Documentation, https://dotted-map.readthedocs.io
+Project-URL: Repository, https://github.com/xnx/dotted-map
+Project-URL: Issues, https://github.com/xnx/dotted-map/issues
+Project-URL: Changelog, https://github.com/xnx/dotted-map/blob/main/CHANGELOG.md
+Author: Christian Hill
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Keywords: cartography,dots,graphic design,halftone,map,svg
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics
+Classifier: Topic :: Scientific/Engineering :: GIS
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pyproj>=3.6
+Requires-Dist: shapely>=2.0
+Provides-Extra: cairo
+Requires-Dist: cairosvg>=2.7; extra == 'cairo'
+Description-Content-Type: text/markdown
+
+# dotted-map
+
+[![PyPI](https://img.shields.io/pypi/v/dotted-map)](https://pypi.org/project/dotted-map/)
+[![Python versions](https://img.shields.io/pypi/pyversions/dotted-map)](https://pypi.org/project/dotted-map/)
+[![Tests](https://github.com/xnx/dotted-map/actions/workflows/tests.yml/badge.svg)](https://github.com/xnx/dotted-map/actions/workflows/tests.yml)
+[![Documentation](https://app.readthedocs.org/projects/dotted-map/badge/?version=stable)](https://dotted-map.readthedocs.io/en/stable/)
+
+Draw maps on which land is a regular lattice of dots, as SVG, PNG and PDF
+images for graphic design and infographics.
+
+![A dotted map of the world, with eight cities marked in orange and joined by curved routes](https://raw.githubusercontent.com/xnx/dotted-map/main/docs/_static/world.png)
+
+The maps are drawn in an equal-area projection, or any other that
+[PROJ](https://proj.org) supports, with coastlines found from the fraction of
+each dot's cell that is land. The land and country outlines of
+[Natural Earth](https://www.naturalearthdata.com) are built in, so a country,
+continent or subregion can be named to frame the map, to highlight it or to
+draw it alone. The documentation is at https://dotted-map.readthedocs.io.
+
+## Command line
+
+```console
+$ dotted-map -o world.svg
+$ dotted-map --region France --highlight 'France=#0055a4' --colour '#c5cad3' -o france.png
+$ dotted-map --region Italy --only Italy --shape hexagon --halftone -o italy.pdf
+$ dotted-map --region GBR IRL --pin London=-0.13,51.51 --pin Dublin=-6.26,53.35 --arc London Dublin -o uk.svg
+$ dotted-map --projection '+proj=ortho +lon_0=-30 +lat_0=30' --sea '#dde1e8' -o globe.svg
+$ dotted-map --list-regions
+```
+
+## Python
+
+```python
+from dotted_map import DottedMap
+
+m = DottedMap(region="Japan", width=600, spacing=8)
+m.add_pin(139.69, 35.69)                # Tokyo.
+m.save("japan.svg", colour="#bc002d", sea="#dde1e8", halftone=True)
+
+data = m.to_dict()                      # Every dot, for use elsewhere.
+```
+
+Colours and sizes can be functions of longitude and latitude, for maps of
+data.
+
+## Installation
+
+```console
+$ pip install dotted-map
+```
+
+The dotted-map package needs Python 3.10 or later, NumPy, pyproj and Shapely.
+PNG and PDF output also needs [CairoSVG](https://cairosvg.org)
+(`pip install "dotted-map[cairo]"`) or the `rsvg-convert` program of
+[librsvg](https://gitlab.gnome.org/GNOME/librsvg).
+
+## Licence
+
+BSD-3-Clause. The land and country outlines are made from Natural Earth's
+1:50m data, which is in the public domain.

dotted_map-0.1.0/README.md

@@ -0,0 +1,60 @@
+# dotted-map
+
+[![PyPI](https://img.shields.io/pypi/v/dotted-map)](https://pypi.org/project/dotted-map/)
+[![Python versions](https://img.shields.io/pypi/pyversions/dotted-map)](https://pypi.org/project/dotted-map/)
+[![Tests](https://github.com/xnx/dotted-map/actions/workflows/tests.yml/badge.svg)](https://github.com/xnx/dotted-map/actions/workflows/tests.yml)
+[![Documentation](https://app.readthedocs.org/projects/dotted-map/badge/?version=stable)](https://dotted-map.readthedocs.io/en/stable/)
+
+Draw maps on which land is a regular lattice of dots, as SVG, PNG and PDF
+images for graphic design and infographics.
+
+![A dotted map of the world, with eight cities marked in orange and joined by curved routes](https://raw.githubusercontent.com/xnx/dotted-map/main/docs/_static/world.png)
+
+The maps are drawn in an equal-area projection, or any other that
+[PROJ](https://proj.org) supports, with coastlines found from the fraction of
+each dot's cell that is land. The land and country outlines of
+[Natural Earth](https://www.naturalearthdata.com) are built in, so a country,
+continent or subregion can be named to frame the map, to highlight it or to
+draw it alone. The documentation is at https://dotted-map.readthedocs.io.
+
+## Command line
+
+```console
+$ dotted-map -o world.svg
+$ dotted-map --region France --highlight 'France=#0055a4' --colour '#c5cad3' -o france.png
+$ dotted-map --region Italy --only Italy --shape hexagon --halftone -o italy.pdf
+$ dotted-map --region GBR IRL --pin London=-0.13,51.51 --pin Dublin=-6.26,53.35 --arc London Dublin -o uk.svg
+$ dotted-map --projection '+proj=ortho +lon_0=-30 +lat_0=30' --sea '#dde1e8' -o globe.svg
+$ dotted-map --list-regions
+```
+
+## Python
+
+```python
+from dotted_map import DottedMap
+
+m = DottedMap(region="Japan", width=600, spacing=8)
+m.add_pin(139.69, 35.69)                # Tokyo.
+m.save("japan.svg", colour="#bc002d", sea="#dde1e8", halftone=True)
+
+data = m.to_dict()                      # Every dot, for use elsewhere.
+```
+
+Colours and sizes can be functions of longitude and latitude, for maps of
+data.
+
+## Installation
+
+```console
+$ pip install dotted-map
+```
+
+The dotted-map package needs Python 3.10 or later, NumPy, pyproj and Shapely.
+PNG and PDF output also needs [CairoSVG](https://cairosvg.org)
+(`pip install "dotted-map[cairo]"`) or the `rsvg-convert` program of
+[librsvg](https://gitlab.gnome.org/GNOME/librsvg).
+
+## Licence
+
+BSD-3-Clause. The land and country outlines are made from Natural Earth's
+1:50m data, which is in the public domain.

dotted_map-0.1.0/docs/_static/custom.css

@@ -0,0 +1,6 @@
+/* The example maps have dark dots on a transparent background: give them
+   a light background, so that they show in the dark theme too. */
+img.dotted-map-example {
+  background: #fbfbfc;
+  border-radius: 0.25rem;
+}

dotted_map-0.1.0/docs/api.rst

@@ -0,0 +1,38 @@
+*************
+API reference
+*************
+
+These names can be imported from ``dotted_map``.
+
+.. currentmodule:: dotted_map
+
+Maps
+====
+
+.. autoclass:: DottedMap
+   :members: svg, save, to_dict, add_pin, add_arc, nearest, lonlat_to_px,
+             px_to_lonlat
+
+.. autofunction:: auto_projection
+
+.. data:: WORLD
+
+   The extent of the whole world, ``(-180, 180, -90, 90)``.
+
+Regions and land
+================
+
+.. autofunction:: region
+
+.. autofunction:: countries
+
+.. autoclass:: Country
+
+.. autofunction:: land
+
+.. autofunction:: read_geojson
+
+Errors
+======
+
+.. autoexception:: ExportError

dotted_map-0.1.0/docs/conf.py

@@ -0,0 +1,147 @@
+# conf.py
+# Configuration for the Sphinx documentation of dotted-map.
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+import contextlib
+import io
+import os
+import shlex
+import sys
+from pathlib import Path
+
+from docutils import nodes
+from docutils.parsers.rst import directives
+from docutils.statemachine import StringList
+from sphinx.util.docutils import SphinxDirective
+
+import dotted_map
+from dotted_map.cli import main
+
+project = "dotted-map"
+author = "Christian Hill"
+copyright = "2026, Christian Hill"
+release = dotted_map.__version__
+version = ".".join(release.split(".")[:2])
+
+extensions = ["sphinx.ext.autodoc", "sphinx.ext.napoleon"]
+autodoc_member_order = "bysource"
+napoleon_numpy_docstring = False
+default_role = "py:obj"
+exclude_patterns = ["_build"]
+
+html_theme = "furo"
+html_title = f"dotted-map {release}"
+html_static_path = ["_static"]
+html_css_files = ["custom.css"]
+
+# The pictures, the table of regions and the command-line help are made by
+# the package itself whenever the documentation is built, so that they
+# always match the code.
+GENERATED = Path(__file__).parent / "_generated"
+GENERATED.mkdir(exist_ok=True)
+
+
+def _write(name, text):
+    (GENERATED / name).write_text(text, encoding="utf-8")
+
+
+class _Example(SphinxDirective):
+    """Show an example and the picture it draws, as name.svg.
+
+    The content is run, so the picture always matches it."""
+
+    required_arguments = 1
+    has_content = True
+    option_spec = {"alt": directives.unchanged_required}
+
+    def run(self):
+        name = self.arguments[0]
+        lines = [line.rstrip() for line in self.content]
+        self.draw(name, lines)
+        if not (GENERATED / f"{name}.svg").exists():
+            raise self.error(f"the example did not write {name}.svg")
+        rst = [f".. code-block:: {self.language}", ""]
+        rst += ["   " + line for line in self.display(name, lines)]
+        rst += ["", f".. image:: /_generated/{name}.svg",
+                "   :class: dotted-map-example",
+                f"   :alt: {self.options['alt']}", ""]
+        node = nodes.container()
+        self.state.nested_parse(StringList(rst), self.content_offset, node)
+        return node.children
+
+
+class CommandExample(_Example):
+    """A dotted-map command; the content is its arguments, apart from -o.
+
+        .. dotted-map:: italy
+           :alt: Italy, drawn in green hexagons.
+
+           --region Italy --only Italy --shape hexagon --colour '#009246'
+    """
+
+    language = "console"
+
+    def draw(self, name, lines):
+        args = shlex.split(" ".join(line.rstrip("\\") for line in lines))
+        with contextlib.redirect_stderr(io.StringIO()) as messages:
+            status = main([*args, "-o", str(GENERATED / f"{name}.svg")])
+        if status:
+            raise self.error(f"dotted-map exited with status {status}: "
+                             f"{messages.getvalue()}")
+
+    def display(self, name, lines):
+        lines = [f"$ dotted-map {lines[0]}"] + [f"      {line.lstrip()}"
+                                               for line in lines[1:]]
+        lines[-1] += f" -o {name}.svg"
+        return lines
+
+
+class PythonExample(_Example):
+    """Python code that saves a map as name.svg."""
+
+    language = "python"
+
+    def draw(self, name, lines):
+        with contextlib.chdir(GENERATED):
+            exec("\n".join(lines), {"__name__": "example"})
+
+    def display(self, name, lines):
+        return lines
+
+
+def setup(app):
+    app.add_directive("dotted-map", CommandExample)
+    app.add_directive("dotted-map-python", PythonExample)
+
+
+# The picture on the front page, which is also in the README.
+sys.path.insert(0, str(Path(__file__).parent.parent / "tools"))
+from showcase import STYLE, world  # noqa: E402
+
+_write("world.svg", world().svg(**STYLE))
+
+# The table of the countries that can be named.
+_rows = [".. list-table::", "   :header-rows: 1", "",
+         "   * - Code", "     - ISO alpha-2", "     - Name",
+         "     - Continent", "     - Subregion"]
+for _c in dotted_map.countries():
+    _rows += [f"   * - ``{_c.code}``",
+              f"     - ``{_c.iso_a2}``" if _c.iso_a2 else "     -",
+              f"     - {_c.name}", f"     - {_c.continent}",
+              f"     - {_c.subregion}"]
+_write("countries.inc", "\n".join(_rows) + "\n")
+_write("groups.inc", "\n".join([
+    "**Continents:** " + ", ".join(sorted(
+        {c.continent for c in dotted_map.countries()})) + ".",
+    "",
+    "**Subregions:** " + ", ".join(sorted(
+        {c.subregion for c in dotted_map.countries()})) + ".", ""]))
+
+# The command-line help.
+os.environ["COLUMNS"] = "79"
+os.environ["NO_COLOR"] = "1"
+_help = io.StringIO()
+with contextlib.redirect_stdout(_help), contextlib.suppress(SystemExit):
+    main(["--help"])
+_write("help.txt", _help.getvalue())