Basemap
=======

.. _fig_basemap_actor:
.. figure:: ./figs/basemap/actorref_basemap.webp
    :figwidth: 100%
    :align: left
    :alt: Basemap actor displaying a map

    Basemap actor.

Overview
--------

The basemap actor renders a background map into the scene and provides geographic
context lines (graticule, coastlines, country borders) as integrated sub-components.

Key features:

* By default, the actor uses a `Natural Earth`_ raster basemap, which is automatically 
  downloaded with the Met.3D binaries and installation.
* Alternatively, any geo-referenced **GeoTIFF** file can be loaded as a custom basemap.
* The visible region (bounding box) can be customized to display only a subset of a 
  larger map file.
* Graticule, coastlines, and country borders can be toggled independently and their 
  colour and thickness adjusted.
* Custom shapefiles can be loaded for alternative or higher-resolution coastline and 
  border data.


Loading a Custom Basemap
------------------------

To load a custom map image:

1. Open the **Base map** → **Configuration** panel.
2. In the **Map file (GeoTIFF)** tab, click on ``...`` to open a file browser.
3. Select any geo-referenced GeoTIFF file from your system.


Graticule
---------

The graticule is configured directly within the basemap actor under
**Base map** → **Configuration** → **Graticule**.

* Toggle visibility with the **enabled** checkbox.
* Adjust line **colour** and **thickness**.
* Define the longitude range and spacing in the **Longitudes** field using the format
  ``[western boundary, eastern boundary, spacing]``, e.g. ``[-180, 180, 10]``.
* Define the latitude range and spacing in the **Latitudes** field analogously,
  e.g. ``[-90, 90, 10]``.
* Adjust label positions and font size in the **Labels** sub-section.
* Click **Execute** (Compute graticule) to apply the updated spacing or label settings.

Coastlines and Country Borders
-------------------------------

Coastlines and country border lines are also part of the basemap actor, available under
**Base map** → **Configuration** → **Coastlines** and **Country borders**.

For each:

* Toggle visibility with the **enabled** checkbox.
* Adjust line **colour** and **thickness**.
* Optionally load a custom **shapefile** via the file selector to replace the built-in
  Natural Earth data, for example to use higher-resolution or region-specific boundaries.

.. _`Natural Earth`: http://www.naturalearthdata.com/