Span Management
===============

A *span* is a named collection of geographic coordinates (latitude/longitude pairs) that represents
a segment of a high-voltage overhead line.  All spans are private to the authenticated user who
created them.

Creating a span
---------------

You can create a span in two ways:

**From a CSV file (recommended)**

1. Prepare a CSV file with at least two columns: ``lat`` and ``lon`` (decimal degrees, WGS 84).
   Additional columns are ignored. Example::

       lat,lon
       51.5074,-0.1278
       51.5080,-0.1265
       51.5090,-0.1250

2. Navigate to **Spans → Upload**.
3. Select your CSV file, enter a unique name, and optionally add a description.
4. Click **Upload**. The backend validates and stores up to **1000 coordinate points** per span.

**From JSON (API)**

Send a ``POST /api/v1/spans/`` request with a JSON body:

.. code-block:: json

   {
     "name": "MyLine-Section-A",
     "description": "Northern feeder between substations A and B",
     "coordinates": [
       {"lat": 51.5074, "lon": -0.1278},
       {"lat": 51.5080, "lon": -0.1265}
     ]
   }

See :doc:`api-reference` for the full request/response schemas.

Viewing spans
-------------

The **Spans** page lists all spans belonging to the current user.  Click a span name to open its
detail view, which shows:

* The span's name and description.
* An interactive map with the coordinates rendered as a polyline.
* Buttons to request a forecast or delete the span.

Editing a span
--------------

From the span detail view, click **Edit** to update the name, description, or coordinate list.
The ``PUT /api/v1/spans/{span_id}`` API endpoint accepts partial updates (only the fields you
include are changed).

Deleting a span
---------------

From the span detail view, click **Delete** and confirm the prompt.  This permanently removes the
span and its coordinates from the database.

CSV format reference
--------------------

.. list-table::
   :header-rows: 1
   :widths: 20 20 60

   * - Column
     - Required
     - Description
   * - ``lat``
     - Yes
     - Latitude in decimal degrees (WGS 84). Range: ``–90`` to ``90``.
   * - ``lon``
     - Yes
     - Longitude in decimal degrees (WGS 84). Range: ``–180`` to ``180``.

* The header row must be present.
* Column names are case-insensitive.
* Rows with missing or non-numeric values are silently dropped.
* The upload is rejected if fewer than two valid points remain after cleaning.
* A maximum of **1000 points** is stored per span.