dotted-map 0.1.0__py3-none-any.whl

dotted_map/__init__.py

@@ -0,0 +1,26 @@
+"""Draw maps on which land is a regular lattice of dots.
+
+    from dotted_map import DottedMap
+
+    m = DottedMap(region="Japan", width=600, spacing=8)
+    m.save("japan.svg", colour="#bc002d")
+"""
+
+from importlib.metadata import version
+
+from .core import WORLD, DottedMap, auto_projection
+from .export import ExportError
+from .regions import Country, countries, land, read_geojson, region
+
+__all__ = [
+    "WORLD",
+    "Country",
+    "DottedMap",
+    "ExportError",
+    "auto_projection",
+    "countries",
+    "land",
+    "read_geojson",
+    "region",
+]
+__version__ = version("dotted-map")

dotted_map/__main__.py

@@ -0,0 +1,5 @@
+"""Support `python -m dotted_map`."""
+
+from .cli import main
+
+raise SystemExit(main())

dotted_map/cli.py

@@ -0,0 +1,274 @@
+"""The command-line interface: a thin layer over DottedMap."""
+
+import argparse
+import csv
+import os
+import sys
+
+from . import __version__, countries, read_geojson
+from .core import GRIDS, SHAPES, DottedMap
+from .export import ExportError
+from .regions import _lookup
+
+KINDS = (".svg", ".png", ".pdf", ".json")
+
+
+def positive(kind):
+    def convert(text):
+        value = kind(text)
+        if value <= 0:
+            raise argparse.ArgumentTypeError("must be positive")
+        return value
+    convert.__name__ = kind.__name__
+    return convert
+
+
+def fraction(text):
+    value = float(text)
+    if not 0 < value <= 1:
+        raise argparse.ArgumentTypeError("must be greater than 0 and at "
+                                         "most 1")
+    return value
+
+
+def region_name(text):
+    try:
+        _lookup(text)
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(str(error)) from None
+    return text
+
+
+def highlight(text):
+    """Parse NAME=COLOUR, as in GBR=#e4572e."""
+    name, _, colour = text.partition("=")
+    if not (name and colour):
+        raise argparse.ArgumentTypeError(
+            "use NAME=COLOUR, as in GBR=#e4572e")
+    return region_name(name), colour
+
+
+def lon_lat(text):
+    """Return (lon, lat) from LON,LAT."""
+    try:
+        lon, lat = (float(v) for v in text.split(","))
+    except ValueError:
+        raise ValueError(f"{text!r} is not LON,LAT") from None
+    if not (-180 <= lon <= 180 and -90 <= lat <= 90):
+        raise ValueError(f"{text!r} is not a valid longitude and latitude")
+    return lon, lat
+
+
+def pin(text):
+    """Parse [NAME=]LON,LAT, as in London=-0.13,51.51."""
+    name, _, coords = text.rpartition("=")
+    try:
+        return name, *lon_lat(coords), None
+    except ValueError as error:
+        raise argparse.ArgumentTypeError(
+            f"{error}: use [NAME=]LON,LAT, as in London=-0.13,51.51"
+        ) from None
+
+
+def read_pins(path):
+    """Return the pins in a CSV file with columns lon, lat and, optionally,
+    name and colour, as (name, lon, lat, colour) tuples."""
+    with open(path, newline="", encoding="utf-8-sig") as f:
+        rows = list(csv.DictReader(f))
+    pins = []
+    for n, row in enumerate(rows, start=2):
+        row = {k.strip().lower(): (v or "").strip()
+               for k, v in row.items() if k}
+        try:
+            lon, lat = lon_lat(f"{row['lon']},{row['lat']}")
+        except (KeyError, ValueError) as error:
+            raise ValueError(f"{path}, line {n}: needs columns lon and lat "
+                             f"with valid values ({error})") from None
+        pins.append((row.get("name", ""), lon, lat,
+                     row.get("colour") or row.get("color") or None))
+    return pins
+
+
+def list_regions():
+    rows = countries()
+    for c in rows:
+        print(f"{c.code:4} {c.iso_a2:3} {c.name:32} "
+              f"{c.continent}: {c.subregion}")
+    print("\nContinents:", ", ".join(sorted({c.continent for c in rows})))
+    print("Subregions:", ", ".join(sorted({c.subregion for c in rows})))
+
+
+def build_parser():
+    parser = argparse.ArgumentParser(
+        prog="dotted-map",
+        description="Draw a map on which land is a regular lattice of dots.",
+        epilog="Region names can be ISO 3166-1 codes (GBR or GB), English "
+               "names (\"United Kingdom\"), continents (Africa) or "
+               "subregions (\"Western Europe\"): --list-regions lists them. "
+               "Colours can be any SVG colour; put a colour such as #e4572e "
+               "in quotes. Documentation: https://dotted-map.readthedocs.io")
+    parser.add_argument("--version", action="version",
+                        version=f"%(prog)s {__version__}")
+
+    group = parser.add_argument_group("output")
+    group.add_argument("-o", "--output", default="map.svg", metavar="FILE",
+                       help="the file to write, of a type given by its "
+                            "extension: .svg, .png, .pdf or .json; or - "
+                            "for SVG on standard output (default: map.svg)")
+    group.add_argument("--scale", type=positive(float), default=2,
+                       help="the size of a PNG image relative to its size "
+                            "in px (default: 2)")
+    group.add_argument("--list-regions", action="store_true",
+                       help="list the countries, continents and subregions "
+                            "that can be named, and exit")
+
+    group = parser.add_argument_group(
+        "area", "The whole world, unless --extent or --region is given.")
+    area = group.add_mutually_exclusive_group()
+    area.add_argument("--extent", type=float, nargs=4,
+                      metavar=("LON_MIN", "LON_MAX", "LAT_MIN", "LAT_MAX"),
+                      help="the area to map, in degrees")
+    area.add_argument("--region", type=region_name, nargs="+",
+                      metavar="NAME",
+                      help="frame the map on these countries, continents or "
+                           "subregions")
+    group.add_argument("--projection", metavar="PROJ",
+                       help="the map projection, as an EPSG code or PROJ "
+                            "string (default: Lambert azimuthal equal-area, "
+                            "or Equal Earth for the world)")
+    group.add_argument("--padding", type=float, default=0.05,
+                       help="with --region, the space around the region, as "
+                            "a fraction of the longer side (default: 0.05)")
+
+    group = parser.add_argument_group("lattice")
+    group.add_argument("--width", type=positive(int), default=800,
+                       metavar="PX", help="image width (default: 800)")
+    group.add_argument("--spacing", type=positive(float), default=8,
+                       metavar="PX",
+                       help="distance between neighbouring dots (default: 8)")
+    group.add_argument("--grid", choices=GRIDS, default="hex",
+                       help="the lattice (default: hex)")
+    group.add_argument("--margin", type=float, metavar="PX",
+                       help="space around the lattice (default: the "
+                            "spacing)")
+    group.add_argument("--samples", type=positive(int), default=5,
+                       metavar="N",
+                       help="find each dot's land fraction from N x N "
+                            "points (default: 5)")
+
+    group = parser.add_argument_group(
+        "land", "Natural Earth's 1:50m land, without lakes, by default.")
+    land = group.add_mutually_exclusive_group()
+    land.add_argument("--only", type=region_name, nargs="+", metavar="NAME",
+                      help="draw only the land in these regions")
+    land.add_argument("--land", metavar="FILE",
+                      help="a GeoJSON file of the land to draw instead")
+
+    group = parser.add_argument_group("style")
+    group.add_argument("--colour", "--color", default="#222",
+                       help="land dot colour (default: #222)")
+    group.add_argument("--size", type=positive(float), default=0.6,
+                       help="dot diameter, as a fraction of the spacing "
+                            "(default: 0.6)")
+    group.add_argument("--shape", choices=SHAPES, default="circle",
+                       help="dot shape; all have the same area "
+                            "(default: circle)")
+    group.add_argument("--halftone", action="store_true",
+                       help="size each dot by its land fraction, for "
+                            "smoother coastlines")
+    group.add_argument("--threshold", type=fraction,
+                       help="smallest land fraction drawn (default: 0.5, "
+                            "or 0.15 with --halftone)")
+    group.add_argument("--highlight", type=highlight, action="append",
+                       default=[], metavar="NAME=COLOUR",
+                       help="colour the land in a region; repeat for more")
+    group.add_argument("--sea", metavar="COLOUR",
+                       help="draw dots in the sea, in this colour")
+    group.add_argument("--sea-size", type=positive(float), metavar="SIZE",
+                       help="sea dot diameter (default: --size)")
+    group.add_argument("--background", metavar="COLOUR",
+                       help="background colour (default: transparent)")
+    group.add_argument("--title", default="Dotted map",
+                       help="the SVG document's title (default: Dotted map)")
+
+    group = parser.add_argument_group("places")
+    group.add_argument("--pin", type=pin, action="append", default=[],
+                       metavar="[NAME=]LON,LAT",
+                       help="mark a place; repeat for more")
+    group.add_argument("--pins", metavar="FILE",
+                       help="mark the places in a CSV file with columns "
+                            "lon, lat and, optionally, name and colour")
+    group.add_argument("--pin-colour", "--pin-color", default="#e4572e",
+                       metavar="COLOUR", help="(default: #e4572e)")
+    group.add_argument("--pin-size", type=positive(float), default=1.5,
+                       metavar="SIZE",
+                       help="pin diameter relative to a dot (default: 1.5)")
+    group.add_argument("--rings", type=int, default=2, metavar="N",
+                       help="rings around each pin (default: 2)")
+    group.add_argument("--arc", nargs=2, action="append", default=[],
+                       metavar="NAME",
+                       help="join two named pins with a curve; repeat for "
+                            "more")
+    group.add_argument("--bend", type=float, default=0.3,
+                       help="how far the curves bow (default: 0.3)")
+    group.add_argument("--dash", metavar="PATTERN",
+                       help="dash the curves, as in '4 3'")
+    return parser
+
+
+def draw(args):
+    if args.output != "-" and not args.output.lower().endswith(KINDS):
+        raise ValueError(f"{args.output}: the file name must end in "
+                         f"{', '.join(KINDS[:-1])} or {KINDS[-1]}")
+    pins = list(args.pin)
+    if args.pins:
+        pins += read_pins(args.pins)
+    names = {name for name, *_ in pins if name}
+    for a, b in args.arc:
+        for name in (a, b):
+            if name not in names:
+                raise ValueError(f"--arc: no pin named {name!r}")
+
+    land = read_geojson(args.land) if args.land else args.only
+    m = DottedMap(args.extent, region=args.region,
+                  projection=args.projection, padding=args.padding,
+                  width=args.width, spacing=args.spacing, grid=args.grid,
+                  margin=args.margin, samples=args.samples, land=land)
+    index = {}
+    for name, lon, lat, colour in pins:
+        index[name] = m.add_pin(lon, lat, colour=colour or args.pin_colour,
+                                size=args.pin_size, rings=args.rings)
+    for a, b in args.arc:
+        m.add_arc(index[a], index[b], bend=args.bend, dash=args.dash)
+
+    style = dict(colour=args.colour, size=args.size, shape=args.shape,
+                 halftone=args.halftone, threshold=args.threshold,
+                 sea=args.sea, sea_size=args.sea_size,
+                 highlight=dict(args.highlight))
+    if not args.output.lower().endswith(".json"):
+        style.update(background=args.background, title=args.title)
+    if args.output == "-":
+        sys.stdout.write(m.svg(**style))
+        sys.stdout.flush()
+    else:
+        m.save(args.output, scale=args.scale, **style)
+        print(f"wrote {args.output}", file=sys.stderr)
+    return 0
+
+
+def main(argv=None):
+    """Run the command line, returning the process's exit status."""
+    args = build_parser().parse_args(argv)
+    try:
+        if args.list_regions:
+            list_regions()
+            return 0
+        return draw(args)
+    except BrokenPipeError:
+        # The reader went away, as with `| head`. Stop quietly, and stop
+        # Python reporting the same error when it flushes stdout on exit.
+        os.dup2(os.open(os.devnull, os.O_WRONLY), sys.stdout.fileno())
+        return 1
+    except (OSError, ValueError, ExportError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1

dotted_map/core.py

@@ -0,0 +1,589 @@
+"""The DottedMap class: a map on which land is a regular lattice of dots."""
+
+import json
+from html import escape
+from pathlib import Path
+
+import numpy as np
+import shapely
+from pyproj import CRS, Transformer
+
+from . import export, regions
+
+#: The extent of the whole world, (lon_min, lon_max, lat_min, lat_max).
+WORLD = (-180, 180, -90, 90)
+GRIDS = ("hex", "square")
+SHAPES = ("circle", "hexagon", "square")
+#: The default diameter of a dot, as a fraction of the spacing.
+DEFAULT_SIZE = 0.6
+DEFAULT_PIN_COLOUR = "#e4572e"
+#: Parts of a region farther than this from its largest landmass, or from
+#: a part within this distance of it, are left out of its frame (metres).
+REGION_GAP = 500e3
+# The number of lattice sites whose land fraction is found at a time, which
+# limits the memory used for large maps.
+_CHUNK = 20000
+
+
+def auto_projection(extent):
+    """Return a PROJ string for a projection suited to an extent.
+
+    Args:
+        extent: (lon_min, lon_max, lat_min, lat_max), in degrees. If lon_min
+            is greater than lon_max, the extent crosses the antimeridian
+            (180 degrees).
+
+    The projection is Equal Earth (an equal-area projection designed for
+    world maps) for extents wider than 180 degrees of longitude, and
+    otherwise the Lambert azimuthal equal-area projection centred on the
+    extent.
+    """
+    lon_min, lon_max, lat_min, lat_max = extent
+    width = (lon_max - lon_min) % 360 or 360
+    lon_0 = (lon_min + width / 2 + 180) % 360 - 180
+    if width > 180:
+        return "+proj=eqearth" + (f" +lon_0={lon_0:g}" if lon_0 else "")
+    return f"+proj=laea +lon_0={lon_0:g} +lat_0={(lat_min + lat_max) / 2:g}"
+
+
+def _extent_bounds(transformer, extent, n=201):
+    """Return the bounds, in projected coordinates, of an extent.
+
+    The extent is sampled at n x n points, inside it as well as on its
+    edges, because its projection's extremes can lie inside it: the bottom
+    of an orthographic globe, for example. Points that the projection
+    cannot show, as on the far side of a globe, are ignored.
+    """
+    lon_min, lon_max, lat_min, lat_max = extent
+    if lon_max <= lon_min:
+        lon_max += 360
+    lon, lat = np.meshgrid(np.linspace(lon_min, lon_max, n),
+                           np.linspace(lat_min, lat_max, n))
+    lon = np.where(lon > 180, lon - 360, lon)
+    with np.errstate(invalid="ignore"):
+        X, Y = transformer.transform(lon, lat)
+    ok = np.isfinite(X) & np.isfinite(Y)
+    if not ok.any():
+        raise ValueError(f"the projection cannot show the extent {extent}")
+    return X[ok].min(), Y[ok].min(), X[ok].max(), Y[ok].max()
+
+
+def _project(geom, transformer):
+    """Return geometries transformed by a pyproj Transformer."""
+    return shapely.transform(
+        geom, lambda xy: np.column_stack(transformer.transform(*xy.T)))
+
+
+def _frame(geom, padding, projection=None):
+    """Return a projection and bounds that frame a region's main landmass.
+
+    The frame holds the region's largest part, and the parts within
+    REGION_GAP of it or of each other, with padding (a fraction of the
+    larger side) all round. The projection, unless given, is the Lambert
+    azimuthal equal-area projection centred on the largest part.
+    """
+    parts = shapely.get_parts(geom)
+    # Find the largest part from its area in an equal-area projection.
+    ee = Transformer.from_crs("EPSG:4326", "+proj=eqearth", always_xy=True)
+    areas = shapely.area(_project(parts, ee))
+    main = int(np.argmax(areas))
+    if projection is None:
+        centre = shapely.centroid(_project(parts[main], ee))
+        lon_0, lat_0 = ee.transform(centre.x, centre.y, direction="INVERSE")
+        projection = f"+proj=laea +lon_0={lon_0:.3f} +lat_0={lat_0:.3f}"
+    fwd = Transformer.from_crs("EPSG:4326", projection, always_xy=True)
+    with np.errstate(invalid="ignore"):
+        parts = _project(parts, fwd)
+    # Leave out parts that the projection cannot show (e.g. on the far
+    # side of a globe).
+    finite = np.isfinite(shapely.bounds(parts)).all(axis=1)
+    chosen = np.zeros(len(parts), dtype=bool)
+    chosen[main] = True
+    while True:
+        cluster = shapely.multipolygons(parts[chosen])
+        near = (~chosen & finite
+                & (shapely.distance(parts, cluster) < REGION_GAP))
+        if not near.any():
+            break
+        chosen |= near
+    xmin, ymin, xmax, ymax = shapely.total_bounds(parts[chosen])
+    pad = padding * max(xmax - xmin, ymax - ymin)
+    return projection, (xmin - pad, ymin - pad, xmax + pad, ymax + pad)
+
+
+def _land_test(land):
+    """Return a function of longitude and latitude arrays that returns
+    True for points on land, from the land argument of DottedMap."""
+    if callable(land):
+        return land
+    world = regions.land()
+    if land is None:
+        return lambda lon, lat: shapely.contains_xy(world, lon, lat)
+    if isinstance(land, shapely.Geometry):
+        geom = land
+        shapely.prepare(geom)
+        return lambda lon, lat: shapely.contains_xy(geom, lon, lat)
+    area = regions.region(land)
+    return lambda lon, lat: (shapely.contains_xy(world, lon, lat)
+                             & shapely.contains_xy(area, lon, lat))
+
+
+class DottedMap:
+    """A map on which land is drawn as a regular lattice of dots.
+
+    Making a DottedMap lays out the lattice and finds the fraction of each
+    lattice cell that is land; svg(), save() and to_dict() then draw it, in
+    any style.
+
+    The area mapped is set by one of `extent`, `region` or `bounds`. With
+    none of them, the map is of the whole world.
+
+    Args:
+        extent: (lon_min, lon_max, lat_min, lat_max), in degrees. If
+            lon_min is greater than lon_max, the extent crosses the
+            antimeridian.
+        region: the name of a country, continent or subregion, or a list
+            of them, as for `region()`. The map is framed on the region's
+            largest landmass and any land within 500 km of it, so that a
+            map of France includes Corsica but not French Guiana.
+        projection: anything that pyproj.CRS accepts, such as an EPSG code
+            or a PROJ string. By default, `auto_projection` (extent), or a
+            Lambert azimuthal equal-area projection centred on the region.
+        bounds: (xmin, ymin, xmax, ymax), in the projection's coordinates
+            (usually metres), to set the area mapped directly. The
+            projection must be given too.
+        padding: with `region`, the space around the region's land, as a
+            fraction of the longer side of the frame.
+        width: the width of the image, px. Its height follows from the
+            area mapped.
+        spacing: the distance between neighbouring dots, px.
+        grid: "hex", a hexagonal lattice, on which each dot has six
+            equidistant neighbours, or "square".
+        margin: the space between the lattice and the edge of the image,
+            px (by default, the spacing).
+        samples: each cell's land fraction is found from a samples x
+            samples array of points within it.
+        land: what counts as land. By default, the land of Natural Earth's
+            1:50m outlines, without its lakes. It can be the name of a
+            region, or a list of them, to draw only the land within them;
+            a shapely geometry in longitude and latitude (see
+            `read_geojson()`); or a function that takes arrays of longitude
+            and latitude and returns an array that is True for points on
+            land.
+
+    Raises:
+        ValueError: for inconsistent or invalid arguments, such as an
+            unknown region.
+
+    Attributes:
+        x: an array of the x coordinate of each lattice site, px.
+        y: an array of the y coordinate of each lattice site, px,
+            downwards from the top of the image.
+        land: an array of the fraction of each site's cell that is land.
+        inside: an array of the fraction of each site's cell within the
+            projection's domain (as within the outline of a world map).
+        lon: an array of the longitude of the point that stands for each
+            site, which colour and size functions are given: its cell's
+            sample on land nearest to its centre or, if it has none, its
+            nearest sample within the projection's domain (NaN if there is
+            none).
+        lat: an array of the latitude of the same points.
+        width: the width of the image, px.
+        height: the height of the image, px.
+        crs: the projection, as a pyproj.CRS.
+        pins: a list of the pins added, as dicts.
+        arcs: a list of the arcs added, as dicts.
+    """
+
+    def __init__(self, extent=None, *, region=None, projection=None,
+                 bounds=None, padding=0.05, width=800, spacing=8,
+                 grid="hex", margin=None, samples=5, land=None):
+        if sum(x is not None for x in (extent, region, bounds)) > 1:
+            raise ValueError("give only one of extent, region and bounds")
+        if grid not in GRIDS:
+            raise ValueError(f"unknown grid {grid!r}: use hex or square")
+        if not (width > 0 and spacing > 0 and samples >= 1):
+            raise ValueError("width, spacing and samples must be positive")
+        if margin is not None and margin < 0:
+            raise ValueError("margin must not be negative")
+
+        if region is not None:
+            projection, bounds = _frame(regions.region(region), padding,
+                                        projection)
+        elif bounds is not None:
+            if projection is None:
+                raise ValueError("bounds are in the projection's "
+                                 "coordinates: give the projection too")
+        else:
+            extent = WORLD if extent is None else extent
+            projection = projection or auto_projection(extent)
+        self.crs = CRS(projection)
+        self._fwd = Transformer.from_crs("EPSG:4326", self.crs,
+                                         always_xy=True)
+        self._inv = Transformer.from_crs(self.crs, "EPSG:4326",
+                                         always_xy=True)
+        if bounds is None:
+            bounds = _extent_bounds(self._fwd, extent)
+        self.bounds = tuple(float(b) for b in bounds)
+        self.xmin, self.ymin, self.xmax, self.ymax = self.bounds
+        if not (self.xmax > self.xmin and self.ymax > self.ymin):
+            raise ValueError(f"empty bounds: {self.bounds}")
+
+        self.spacing = s = spacing
+        self.grid = grid
+        self.margin = m = spacing if margin is None else margin
+        # The image scale (px per unit of the projection, usually metres)
+        # and size (px).
+        self.scale = (width - 2 * m) / (self.xmax - self.xmin)
+        self.width = width
+        self.height = round((self.ymax - self.ymin) * self.scale + 2 * m)
+
+        # The lattice: rows dy apart; on a hexagonal lattice, odd rows are
+        # offset by s/2 so that each dot has six equidistant neighbours.
+        dy = s * np.sqrt(3) / 2 if grid == "hex" else s
+        nx = max(int((width - 2 * m) // s), 1)
+        ny = max(int((self.height - 2 * m) // dy), 1)
+        i, j = np.meshgrid(np.arange(nx, dtype=float), np.arange(ny))
+        x = i * s
+        if grid == "hex":
+            x += (j % 2) * s / 2
+        y = j * dy
+        # Centre the lattice in the image.
+        self.x = (x + (self.width - x.max()) / 2).ravel()
+        self.y = (y + (self.height - y.max()) / 2).ravel()
+        self._find_land(_land_test(land), samples, dy)
+        self.pins = []
+        self.arcs = []
+
+    def _find_land(self, is_land, samples, dy):
+        """Find the land fraction of each cell, and the point that stands
+        for it.
+
+        Each cell is a rectangle spacing wide and dy high, so that the
+        cells tile the plane, and is sampled at samples x samples points.
+        The point that stands for a cell, whose longitude and latitude are
+        given to colour and size functions, is its sample on land nearest
+        to its centre or, if it has none, its nearest sample within the
+        projection's domain.
+        """
+        u = (np.arange(samples) + 0.5) / samples - 0.5
+        du, dv = (a.ravel() for a in np.meshgrid(u * self.spacing, u * dy))
+        order = np.argsort(np.hypot(du, dv), kind="stable")
+        du, dv = du[order], dv[order]
+        n = len(self.x)
+        self.land = np.empty(n)
+        self.inside = np.empty(n)
+        self.lon = np.full(n, np.nan)
+        self.lat = np.full(n, np.nan)
+        for start in range(0, n, _CHUNK):
+            cells = slice(start, start + _CHUNK)
+            lon, lat, valid = self.px_to_lonlat(self.x[cells, None] + du,
+                                                self.y[cells, None] + dv)
+            on = np.zeros_like(valid)
+            on[valid] = np.asarray(is_land(lon[valid], lat[valid]),
+                                   dtype=bool)
+            self.land[cells] = on.mean(axis=1)
+            # The fraction of each cell within the projection's domain
+            # (e.g. within the outline of a world map or the disc of a
+            # globe).
+            self.inside[cells] = valid.mean(axis=1)
+            pick = np.where(on.any(axis=1), on.argmax(axis=1),
+                            valid.argmax(axis=1))
+            rows = np.arange(len(pick))
+            ok = valid[rows, pick]
+            self.lon[cells] = np.where(ok, lon[rows, pick], np.nan)
+            self.lat[cells] = np.where(ok, lat[rows, pick], np.nan)
+
+    def px_to_lonlat(self, x, y):
+        """Return the longitude and latitude of image points (x, y), and an
+        array that is True for the points within the projection's domain."""
+        X = self.xmin + (np.asarray(x) - self.margin) / self.scale
+        Y = self.ymax - (np.asarray(y) - self.margin) / self.scale
+        tolerance = 1e-6 * max(self.xmax - self.xmin, self.ymax - self.ymin)
+        with np.errstate(invalid="ignore"):
+            lon, lat = self._inv.transform(X, Y)
+            # Some inverse projections return finite but meaningless values
+            # outside their domain: a round trip identifies these.
+            X2, Y2 = self._fwd.transform(lon, lat)
+            valid = (np.isfinite(lon) & np.isfinite(lat)
+                     & (np.hypot(X2 - X, Y2 - Y) < tolerance)
+                     & (np.abs(lat) <= 90) & (np.abs(lon) <= 180))
+        return lon, lat, valid
+
+    def lonlat_to_px(self, lon, lat):
+        """Return the image coordinates of the point (lon, lat)."""
+        X, Y = self._fwd.transform(lon, lat)
+        return (self.margin + (X - self.xmin) * self.scale,
+                self.margin + (self.ymax - Y) * self.scale)
+
+    def nearest(self, lon, lat):
+        """Return the index of the lattice site nearest to (lon, lat)."""
+        x, y = self.lonlat_to_px(lon, lat)
+        if not (np.isfinite(x) and np.isfinite(y)):
+            raise ValueError(f"({lon}, {lat}) is not on the map")
+        return int(np.argmin(np.hypot(self.x - x, self.y - y)))
+
+    def add_pin(self, lon, lat, *, colour=DEFAULT_PIN_COLOUR, size=1.5,
+                rings=2):
+        """Mark a place with a pin: the dot nearest to it, enlarged, with
+        concentric rings around it.
+
+        Args:
+            lon, lat: the place's longitude and latitude, in degrees.
+            colour: the colour of the pin and its rings.
+            size: the pin's diameter, relative to that of a land dot.
+            rings: the number of rings, each fainter than the one inside.
+
+        Returns:
+            An index for the pin, for use with `add_arc()`.
+        """
+        self.pins.append({"site": self.nearest(lon, lat), "colour": colour,
+                          "size": size, "rings": rings, "lon": lon,
+                          "lat": lat})
+        return len(self.pins) - 1
+
+    def add_arc(self, pin1, pin2, *, colour=None, width=None, bend=0.3,
+                dash=None):
+        """Join two pins with a curve that bows upwards.
+
+        Args:
+            pin1, pin2: indexes returned by `add_pin()`.
+            colour: the colour of the curve (by default, that of pin1).
+            width: its stroke width, px (by default, a fifth of the
+                spacing).
+            bend: the curve is a quadratic Bezier curve whose control point
+                is displaced from the midpoint of the chord by bend times
+                the chord's length.
+            dash: an SVG stroke-dasharray, as in "4 3", for a dashed curve.
+        """
+        for pin in (pin1, pin2):
+            if not 0 <= pin < len(self.pins):
+                raise ValueError(f"no pin {pin}")
+        self.arcs.append({"pins": (pin1, pin2),
+                          "colour": colour or self.pins[pin1]["colour"],
+                          "width": width or self.spacing / 5, "bend": bend,
+                          "dash": dash})
+
+    def _layout(self, colour="#222", size=DEFAULT_SIZE, shape="circle",
+                halftone=False, threshold=None, sea=None, sea_size=None,
+                highlight=None):
+        """Return the land dots and sea dots to draw, each as arrays of
+        lattice site indexes, radii (px) and colours."""
+        if shape not in SHAPES:
+            raise ValueError(f"unknown shape {shape!r}: use "
+                             f"{', '.join(SHAPES)}")
+        if threshold is None:
+            threshold = 0.15 if halftone else 0.5
+        if not 0 < threshold <= 1:
+            raise ValueError("threshold must be greater than 0 and at "
+                             "most 1")
+        pinned = np.zeros(len(self.x), dtype=bool)
+        pinned[[pin["site"] for pin in self.pins]] = True
+        on_land = (self.land >= threshold) & ~pinned
+
+        idx = np.flatnonzero(on_land)
+        lon, lat = self.lon[idx], self.lat[idx]
+        d = (np.asarray(size(lon, lat), dtype=float) if callable(size)
+             else np.full(len(idx), float(size)))
+        radii = d * self.spacing / 2
+        if halftone:
+            radii *= np.sqrt(self.land[idx])
+        colours = np.empty(len(idx), dtype=object)
+        colours[:] = colour(lon, lat) if callable(colour) else colour
+        for key, c in (highlight or {}).items():
+            geom = (key if isinstance(key, shapely.Geometry)
+                    else regions.region(key))
+            colours[shapely.contains_xy(geom, lon, lat)] = c
+        keep = radii > 0
+        land = idx[keep], radii[keep], colours[keep]
+
+        if sea is None:
+            sea_dots = np.array([], dtype=int), np.array([]), np.array([])
+        else:
+            if sea_size is None:
+                sea_size = DEFAULT_SIZE if callable(size) else size
+            idx = np.flatnonzero(~on_land & ~pinned & (self.inside >= 0.5))
+            sea_dots = (idx, np.full(len(idx), sea_size * self.spacing / 2),
+                        np.full(len(idx), sea, dtype=object))
+        pin_r = (DEFAULT_SIZE if callable(size) else size) * self.spacing / 2
+        return land, sea_dots, pin_r, shape
+
+    def svg(self, colour="#222", *, size=DEFAULT_SIZE, shape="circle",
+            halftone=False, threshold=None, sea=None, sea_size=None,
+            highlight=None, background=None, title="Dotted map"):
+        """Return the map as an SVG document.
+
+        The document's groups have ids for each layer, from the bottom up:
+        "sea", "land", "arcs" and "pins". Within "land", there is a group
+        for each colour.
+
+        Args:
+            colour: the colour of the land dots, or a function that takes
+                arrays of longitude and latitude and returns a colour for
+                each.
+            size: the diameter of a land dot, as a fraction of the spacing,
+                or a function that takes arrays of longitude and latitude
+                and returns a diameter for each.
+            shape: "circle", "hexagon" or "square"; each has the area of a
+                circle of the given diameter.
+            halftone: if True, make the area of each dot proportional to
+                its cell's land fraction, which smooths the coastlines and
+                keeps small islands.
+            threshold: the smallest land fraction of a cell drawn as land
+                (by default, 0.5, or 0.15 with `halftone`).
+            sea: if given, the colour of dots drawn in the sea.
+            sea_size: the diameter of a sea dot, as a fraction of the
+                spacing (by default, that of a land dot, or 0.6 if `size`
+                is a function).
+            highlight: a dict from region names (as for `region()`), or
+                shapely geometries, to colours: the land dots within each
+                are drawn in its colour. Later entries take precedence.
+            background: if given, the background colour; otherwise the
+                background is transparent.
+            title: the document's title, for accessibility.
+        """
+        land, sea_dots, pin_r, shape = self._layout(
+            colour, size, shape, halftone, threshold, sea, sea_size,
+            highlight)
+        out = [f'<svg xmlns="http://www.w3.org/2000/svg" '
+               f'viewBox="0 0 {self.width} {self.height}" '
+               f'width="{self.width}" height="{self.height}">',
+               f'<title>{escape(title)}</title>']
+        if background:
+            out.append(f'<rect width="100%" height="100%" '
+                       f'fill="{escape(background)}"/>')
+        if sea is not None:
+            idx, radii, _ = sea_dots
+            out.append(f'<g id="sea" fill="{escape(sea)}">')
+            out += [_marker(self.x[k], self.y[k], r, shape)
+                    for k, r in zip(idx, radii, strict=True)]
+            out.append('</g>')
+
+        # Land dots, in a group for each colour.
+        groups = {}
+        for k, r, c in zip(*land, strict=True):
+            groups.setdefault(str(c), []).append(
+                _marker(self.x[k], self.y[k], r, shape))
+        out.append('<g id="land">')
+        for c, markers in groups.items():
+            out += [f'<g fill="{escape(c)}">', *markers, '</g>']
+        out.append('</g>')
+
+        out.append('<g id="arcs" fill="none" stroke-linecap="round">')
+        for arc in self.arcs:
+            dash = (f' stroke-dasharray="{escape(arc["dash"])}"'
+                    if arc["dash"] else "")
+            out.append(f'<path d="{self._arc_path(arc)}" '
+                       f'stroke="{escape(arc["colour"])}" '
+                       f'stroke-width="{arc["width"]:.2f}"{dash}/>')
+        out.append('</g>')
+
+        out.append('<g id="pins">')
+        for pin in self.pins:
+            x, y = self.x[pin["site"]], self.y[pin["site"]]
+            r = pin_r * pin["size"]
+            fill = escape(pin["colour"])
+            # Concentric rings, fainter with distance from the pin.
+            for n in range(pin["rings"], 0, -1):
+                out.append(f'<circle cx="{x:.2f}" cy="{y:.2f}" '
+                           f'r="{r * (1 + 0.9 * n):.2f}" fill="none" '
+                           f'stroke="{fill}" stroke-width="{pin_r / 2:.2f}" '
+                           f'stroke-opacity="{0.9 / (n + 1):.2f}"/>')
+            out.append(f'<g fill="{fill}">{_marker(x, y, r, shape)}</g>')
+        out.append('</g>')
+        out.append('</svg>')
+        return "\n".join(out) + "\n"
+
+    def _arc_path(self, arc):
+        """Return the SVG path data of an arc."""
+        k1, k2 = (self.pins[p]["site"] for p in arc["pins"])
+        x1, y1, x2, y2 = self.x[k1], self.y[k1], self.x[k2], self.y[k2]
+        # Displace the control point perpendicular to the chord, upwards
+        # (towards negative y).
+        dx, dy = x2 - x1, y2 - y1
+        nx, ny = (dy, -dx) if dx >= 0 else (-dy, dx)
+        cx = (x1 + x2) / 2 + arc["bend"] * nx
+        cy = (y1 + y2) / 2 + arc["bend"] * ny
+        return f"M{x1:.2f},{y1:.2f} Q{cx:.2f},{cy:.2f} {x2:.2f},{y2:.2f}"
+
+    def to_dict(self, colour="#222", **style):
+        """Return the map as a dict that can be written as JSON, for use
+        with other software (e.g. to draw or animate the map on a web page).
+
+        It takes the same arguments as `svg()`, apart from `background`
+        and `title`. The dict has the image's "width" and "height" (px),
+        the "spacing", the "shape" of the dots, and lists of "dots", "pins"
+        and "arcs". Each dot has its centre, "x" and "y", its radius "r"
+        (that of a circle of the same area, for hexagons and squares), its
+        "fill" colour, its "layer" ("land" or "sea"), and the "lon" and
+        "lat" of the point that stands for it (see `lon`).
+        """
+        land, sea_dots, pin_r, shape = self._layout(colour, **style)
+
+        def number(v):
+            return None if np.isnan(v) else round(float(v), 4)
+
+        dots = []
+        for layer, (idx, radii, colours) in (("sea", sea_dots),
+                                             ("land", land)):
+            dots += [{"x": round(float(self.x[k]), 2),
+                      "y": round(float(self.y[k]), 2),
+                      "r": round(float(r), 2), "fill": str(c),
+                      "layer": layer, "lon": number(self.lon[k]),
+                      "lat": number(self.lat[k])}
+                     for k, r, c in zip(idx, radii, colours, strict=True)]
+        pins = [{"x": round(float(self.x[p["site"]]), 2),
+                 "y": round(float(self.y[p["site"]]), 2),
+                 "r": round(pin_r * p["size"], 2), "fill": p["colour"],
+                 "rings": p["rings"], "lon": p["lon"], "lat": p["lat"]}
+                for p in self.pins]
+        arcs = [{"pins": list(a["pins"]), "d": self._arc_path(a),
+                 "stroke": a["colour"], "width": round(a["width"], 2),
+                 "dash": a["dash"]} for a in self.arcs]
+        return {"width": self.width, "height": self.height,
+                "spacing": self.spacing, "shape": shape, "dots": dots,
+                "pins": pins, "arcs": arcs}
+
+    def save(self, path, *, scale=2, **style):
+        """Write the map to a file, of a type given by its extension.
+
+        PNG and PDF output needs the CairoSVG package (installed with
+        ``pip install "dotted-map[cairo]"``) or the rsvg-convert program.
+
+        Args:
+            path: a file name ending in .svg, .png, .pdf or .json.
+            scale: the size of a PNG image, relative to the SVG image's
+                size in px; 2 suits high-resolution screens.
+            **style: as for `svg()`, or `to_dict()` for JSON.
+
+        Raises:
+            ExportError: if a PNG or PDF image cannot be made.
+        """
+        path = Path(path)
+        kind = path.suffix.lower().lstrip(".")
+        if kind == "json":
+            path.write_text(json.dumps(self.to_dict(**style)) + "\n",
+                            encoding="utf-8")
+        elif kind == "svg":
+            path.write_text(self.svg(**style), encoding="utf-8")
+        elif kind in ("png", "pdf"):
+            export.convert(self.svg(**style), path, kind, scale)
+        else:
+            raise ValueError(f"unknown file type {path.suffix!r}: use .svg, "
+                             ".png, .pdf or .json")
+
+
+def _marker(x, y, r, shape):
+    """Return an SVG element for a marker of area pi r^2 centred at (x, y)."""
+    if shape == "circle":
+        return f'<circle cx="{x:.2f}" cy="{y:.2f}" r="{r:.2f}"/>'
+    if shape == "hexagon":
+        # Pointy-topped, so that hexagons nest on a hexagonal lattice.
+        R = r * np.sqrt(2 * np.pi / (3 * np.sqrt(3)))
+        theta = np.radians(np.arange(30, 360, 60))
+        pts = " ".join(f"{x + R * np.cos(t):.2f},{y + R * np.sin(t):.2f}"
+                       for t in theta)
+        return f'<polygon points="{pts}"/>'
+    a = r * np.sqrt(np.pi)
+    return (f'<rect x="{x - a / 2:.2f}" y="{y - a / 2:.2f}" '
+            f'width="{a:.2f}" height="{a:.2f}"/>')

dotted_map/export.py

@@ -0,0 +1,50 @@
+"""Conversion of SVG documents to PNG and PDF images."""
+
+import shutil
+import subprocess
+
+
+class ExportError(RuntimeError):
+    """Raised when an SVG document cannot be converted."""
+
+
+def convert(svg, path, kind, scale=2):
+    """Write an SVG document to a file as a PNG or PDF image.
+
+    Uses the CairoSVG package if it is installed, or else the rsvg-convert
+    program (part of librsvg).
+
+    Args:
+        svg: the SVG document, as a string.
+        path: the file to write.
+        kind: "png" or "pdf".
+        scale: the size of a PNG image relative to the SVG image's size in
+            px. A PDF image is vector graphics, 0.75 pt for each px (at 96
+            px to the inch), whatever the scale.
+    """
+    if kind not in ("png", "pdf"):
+        raise ValueError(f"unknown image type {kind!r}: use png or pdf")
+    if scale <= 0:
+        raise ValueError("scale must be positive")
+    zoom = scale if kind == "png" else 1
+    try:
+        import cairosvg
+    except (ImportError, OSError):
+        # OSError: CairoSVG is installed but cannot find the Cairo library.
+        cairosvg = None
+    if cairosvg is not None:
+        write = cairosvg.svg2png if kind == "png" else cairosvg.svg2pdf
+        write(bytestring=svg.encode(), write_to=str(path), scale=zoom)
+        return
+    program = shutil.which("rsvg-convert")
+    if program is None:
+        raise ExportError(
+            f"{kind.upper()} output needs CairoSVG "
+            "(pip install \"dotted-map[cairo]\") or rsvg-convert (part of "
+            "librsvg); or save the map as SVG")
+    result = subprocess.run(
+        [program, "-f", kind, "-z", str(zoom), "-o", str(path)],
+        input=svg.encode(), capture_output=True)
+    if result.returncode:
+        raise ExportError(f"rsvg-convert failed: "
+                          f"{result.stderr.decode().strip()}")

dotted_map/regions.py

@@ -0,0 +1,159 @@
+"""The land and country outlines of Natural Earth, bundled with dotted-map.
+
+Natural Earth (https://www.naturalearthdata.com) is in the public domain.
+The files are made from its 1:50m data by tools/make_data.py.
+"""
+
+import difflib
+import gzip
+import json
+import unicodedata
+from functools import cache
+from importlib.resources import files
+from typing import NamedTuple
+
+import shapely
+from shapely.geometry import shape
+
+
+class Country(NamedTuple):
+    """A country, or another area that Natural Earth treats as one."""
+
+    code: str  #: ISO 3166-1 alpha-3 code, or Natural Earth's own if none.
+    iso_a2: str  #: ISO 3166-1 alpha-2 code, or "" if none.
+    name: str  #: Short English name, as in "United Kingdom".
+    continent: str  #: Natural Earth's continent, as in "Europe".
+    subregion: str  #: UN geoscheme subregion, as in "Northern Europe".
+
+
+def _read(name):
+    """Return the features of a bundled GeoJSON file."""
+    data = (files("dotted_map") / "data" / f"{name}.geojson.gz").read_bytes()
+    return json.loads(gzip.decompress(data))["features"]
+
+
+def _code(value):
+    return "" if value == "-99" else value
+
+
+@cache
+def land():
+    """Return the land, without its lakes, as a shapely geometry.
+
+    The outlines are those of Natural Earth's 1:50m land and lakes, which
+    show coastlines to within a few kilometres.
+    """
+    geom = shapely.multipolygons([shape(f["geometry"])
+                                  for f in _read("land")])
+    shapely.prepare(geom)
+    return geom
+
+
+@cache
+def _countries():
+    """Return a dict from each Natural Earth ADM0_A3 code to a tuple of the
+    country's properties and outline."""
+    return {f["properties"]["ADM0_A3"]: (f["properties"],
+                                         shape(f["geometry"]))
+            for f in _read("countries")}
+
+
+@cache
+def _index():
+    """Return a dict from each lower-case name or code to the ADM0_A3 codes
+    of the countries it names."""
+    index = {}
+    items = _countries().items()
+    for adm0, (p, _) in items:
+        for key in ("CONTINENT", "SUBREGION"):
+            index.setdefault(p[key].lower(), set()).add(adm0)
+    # Later entries replace earlier ones: countries' names and codes take
+    # precedence over the names of continents and subregions (as with
+    # "Antarctica"), and a code belongs to the country whose own code it is
+    # rather than to its territories (as with "AUS" for Australia, not for
+    # the Ashmore and Cartier Islands).
+    items = sorted(items, key=lambda item: item[0] == item[1][0]["ISO_A3_EH"])
+    for key in ("NAME_LONG", "ADMIN", "NAME", "ISO_A2_EH", "ISO_A3_EH",
+                "ADM0_A3"):
+        for adm0, (p, _) in items:
+            if value := _code(p[key]):
+                index[value.lower()] = {adm0}
+    return index
+
+
+def countries():
+    """Return a list of the countries that can be named in a region, as
+    Country tuples, in alphabetical order of name."""
+    def own(code, adm0):
+        """Return code if it names this country (and no other), else ""."""
+        return code if _index().get(code.lower()) == {adm0} else ""
+
+    out = []
+    for adm0, (p, _) in _countries().items():
+        out.append(Country(own(_code(p["ISO_A3_EH"]), adm0) or adm0,
+                           own(_code(p["ISO_A2_EH"]), adm0), p["NAME"],
+                           p["CONTINENT"], p["SUBREGION"]))
+    # Sort on the names without accents or case, so that Åland comes
+    # first and eSwatini among the Es.
+    return sorted(out, key=lambda c: unicodedata.normalize(
+        "NFKD", c.name).encode("ascii", "ignore").decode().casefold())
+
+
+def _lookup(name):
+    try:
+        return _index()[name.strip().lower()]
+    except KeyError:
+        names = [c.name for c in countries()]
+        names += sorted({c.continent for c in countries()}
+                        | {c.subregion for c in countries()})
+        close = difflib.get_close_matches(name, names, n=3)
+        hint = f"; did you mean {' or '.join(close)}?" if close else ""
+        raise ValueError(f"unknown region {name!r}{hint}") from None
+
+
+def region(names):
+    """Return the outline of one or more regions as a shapely geometry.
+
+    Args:
+        names: a name, or a list of names. Each can be a country's ISO
+            3166-1 alpha-3 or alpha-2 code (as in "GBR" or "GB"), its name
+            in English (as in "United Kingdom"), or the name of a continent
+            or a UN geoscheme subregion (as in "Africa" or "Western
+            Europe"), in any case. The countries are listed by
+            `countries()`.
+
+    Raises:
+        ValueError: for an unknown name.
+    """
+    if isinstance(names, str):
+        names = [names]
+    codes = set()
+    for name in names:
+        codes |= _lookup(name)
+    return _union(frozenset(codes))
+
+
+@cache
+def _union(codes):
+    geoms = [_countries()[code][1] for code in sorted(codes)]
+    geom = shapely.union_all(geoms) if len(geoms) > 1 else geoms[0]
+    shapely.prepare(geom)
+    return geom
+
+
+def read_geojson(path):
+    """Return the union of the geometries in a GeoJSON file, which can hold
+    a FeatureCollection, a Feature or a bare geometry, with coordinates in
+    degrees of longitude and latitude."""
+    with open(path, encoding="utf-8") as f:
+        data = json.load(f)
+    if data.get("type") == "FeatureCollection":
+        geoms = [shape(f["geometry"]) for f in data["features"]
+                 if f.get("geometry")]
+    elif data.get("type") == "Feature":
+        geoms = [shape(data["geometry"])]
+    else:
+        geoms = [shape(data)]
+    geom = shapely.union_all(geoms)
+    shapely.prepare(geom)
+    return geom

dotted_map-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+dotted_map/__init__.py,sha256=MGnK4XXtxBlWA4ZvvFl2aPgeL97gR9yK7oAwdSm3tDU,592
+dotted_map/__main__.py,sha256=_ugeMi3j-XFoI7IP7YEcARvJ2WOZFRfXRr1UmtzsY8o,87
+dotted_map/cli.py,sha256=zW0peFRM8TnFGUjx9yb4Argn7qHgmJBDXJv2tvpULHs,12163
+dotted_map/core.py,sha256=tjB0ZT5xx_mcrieGuWrUFmkLy0hA9wlimS9HPO5B2hA,27731
+dotted_map/export.py,sha256=-E19kAVgXz4zrOhAWShYAdiJi-TgTIOV00aBQehiBlo,1847
+dotted_map/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dotted_map/regions.py,sha256=hAufFCqjJwyI78xthcNywtJ3Hc76Ky_k1FkLC4sRx-k,5616
+dotted_map/data/countries.geojson.gz,sha256=GbQwLDeZpcXMwgE5zXf8UheSy57aq2G02YdzL37FjWc,573369
+dotted_map/data/land.geojson.gz,sha256=0eEgI8L8Tqvq1Twp9jUZMpqDBNtkUr49e3SCJlyZ8og,440200
+dotted_map-0.1.0.dist-info/METADATA,sha256=OvSbymJvBV18Ag4oqGVyCuiGE1zY-X1kwWziAAuQJh0,3530
+dotted_map-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+dotted_map-0.1.0.dist-info/entry_points.txt,sha256=rZpaqg0Tm9g6_kGKzlMllvyex3yNz_gZwjbQ7mABe4E,51
+dotted_map-0.1.0.dist-info/licenses/LICENSE,sha256=ATVszkWIu32IrI6wo8Sdxbr05TILannMDG-0wD_lNKQ,1501
+dotted_map-0.1.0.dist-info/RECORD,,

dotted_map-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dotted_map-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dotted-map = dotted_map.cli:main

dotted_map-0.1.0.dist-info/licenses/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.