Quickstart
==========

``mappyng`` produces self-contained SVG maps from GeoDataFrame objects.
No display server or GUI is required, output is a plain ``.svg`` file or
a standalone HTML file.

A map is composed by adding **layer objects** with :meth:`~mappyng.Map.add`
and configuring the chrome (title, source, scale bar, north arrow):

.. code-block:: python

   from mappyng import Map, BasemapLayer
   from mappyng.data import load_france_departments

   gdf = load_france_departments()

   m = Map(gdf, width=800, height="auto", facecolor="#B9D9EB")
   m.add(BasemapLayer())
   m.title("Départements français")
   m.scale_bar()
   m.source("Source : IGN")
   m.render("france.svg")

``width="auto"`` / ``height="auto"`` size the canvas to the data aspect
ratio so the map is not letterboxed; :meth:`~mappyng.Map.autosize`
recomputes it on demand.

``Map`` constructor parameters
-------------------------------

.. list-table::
   :header-rows: 1
   :widths: 22 15 63

   * - Parameter
     - Default
     - Description
   * - ``gdf``
     - required
     - Base GeoDataFrame, defines extent and basemap geometry.
   * - ``bbox``
     - ``None``
     - ``[minx, miny, maxx, maxy]``.  Computed from ``gdf`` if omitted.
   * - ``width``
     - 800
     - SVG document width in pixels, or ``"auto"`` to derive it from the
       data aspect ratio.
   * - ``height``
     - 600
     - SVG document height in pixels, or ``"auto"`` (recommended) to
       derive it from the data so the map is not letterboxed.
   * - ``padding``
     - 10
     - Document-level padding in pixels.
   * - ``style``
     - ``"classic"``
     - Preset name (``"classic"``, ``"modern"``) or override dict
       (``{"base": "classic", "title_color": "#333"}``).
   * - ``facecolor``
     - ``None``
     - Ocean / background color drawn inside each viewport.
   * - ``background``
     - ``None``
     - Document background color (default white).
   * - ``basemap_color``
     - ``None``
     - Override fill color for basemap polygons.
   * - ``border_radius``
     - 4
     - Corner radius of the main map viewport (SVG px, 0 = sharp).
   * - ``box_shadow``
     - ``None``
     - Drop shadow on the main map: ``True`` (defaults), ``False``, or
       dict (keys: ``dx``, ``dy``, ``blur``, ``color``, ``opacity``).
   * - ``glow``
     - ``None``
     - Outer glow on the main map: same format as ``box_shadow``.
   * - ``cartouche_params``
     - ``None``
     - Inset map definitions.  Dict keyed by integer index, each value
       a dict with required ``bbox`` and ``crs``, and optional
       ``cartouche_title``, ``size``, ``spacing``, ``border_radius``,
       ``box_shadow``, ``glow``.
   * - ``cartouche_spacing``
     - ``None``
     - Global vertical spacing between cartouches (SVG px).
   * - ``font_scale``
     - ``"auto"``
     - Global font size multiplier.  ``"auto"`` (default) scales to the
       document area; pass a float to override.

Output methods
--------------

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Method
     - Description
   * - ``m.render("map.svg")``
     - Render to a file; format inferred from the extension (``.svg``
       native, ``.png`` / ``.pdf`` via the ``export`` extra). Returns
       ``self``.
   * - ``m.to_string()``
     - Return SVG markup as a string.
   * - ``m.to_interactive(...)``
     - Return :class:`~mappyng.interactive.InteractiveMap` with hover tooltips.
   * - ``m.save_interactive("map.html")``
     - Save as standalone HTML file.
   * - ``m.to_yaml("map.yaml")``
     - Serialise the map's intent (layers + chrome) to YAML.
   * - ``Map.from_yaml("map.yaml", gdf=gdf)``
     - Rebuild a map from YAML, reattaching the supplied geometry.
   * - ``Map.from_yaml("map.yaml")``
     - Build from a YAML that declares its own ``data:`` sources, no
       geometry argument needed.
   * - ``python -m mappyng map.yaml -o map.svg``
     - Render a source-bearing YAML to a file from the shell
       (``.svg`` / ``.png`` / ``.pdf`` / ``.html``).

.. note::

   ``m.save(...)`` is a deprecated alias of ``m.render(...)`` and emits a
   ``DeprecationWarning``. Use ``render`` in new code.

Building a map from YAML
------------------------

A map serialises to a YAML document that captures the configuration, the
ordered layers with every parameter, and the chrome. An *exported* map
references its geometry (pass it back with ``gdf=``), but a hand-written
document can declare where its data comes from and then build with no
Python:

.. code-block:: yaml

   mappyng: 1
   map: {width: 820, height: auto}
   layers:
   - type: ChoroplethLayer
     data:
       dataset: france_departments   # a built-in dataset (or path: file.geojson)
       crs: 2154                       # optional reprojection
       filter: COD_GEO.str.len() == 2  # optional pandas query
       join:                           # optional CSV attribute join
         path: deaths.csv
         left_on: COD_GEO
         right_on: code_dep
     params: {column: rate, cmap: RdBu, method: StdMean, num_classes: 7}
   chrome:
     title: {text: Mortality}

.. code-block:: bash

   python -m mappyng map.yaml -o map.svg      # also .png, .pdf, .html

.. warning::

   Loading a YAML executes its declared sources (file reads and the
   pandas ``filter`` expression), so only build documents you trust.

Style customization
-------------------

.. code-block:: python

   # Use a preset
   m = Map(gdf, style="modern")

   # Override specific values
   m = Map(gdf, style={"base": "classic", "title_color": "#1a1a2e",
                        "basemap_fill": "#f5f5f5"})

   # Register a custom style for reuse
   from mappyng.config import ConfigManager
   ConfigManager.add_style("my_style", {
       "base": "classic",
       "title_color": "#1a1a2e",
       "basemap_fill": "#e8e8e8",
       "basemap_edge_color": "#999999",
   })
   m = Map(gdf, style="my_style")