Add site and sector KML map creator

app.py

@@ -200,7 +200,7 @@ if check_password():
             ),
             st.Page(
                 "apps/sector_kml_generator.py",
-                title="Sector KML Generator",
+                title="Site & Sector KML Creator",
                 icon=":material/map:",
             ),
             st.Page(
@@ -313,7 +313,7 @@ if check_password():
             ),
             st.Page(
                 "documentations/sector_kml_doc.py",
-                title="Sector KML Generator Documentation",
+                title="Site & Sector KML Creator Documentation",
                 icon=":material/menu_book:",
             ),
             st.Page(

apps/sector_kml_generator.py

@@ -1,95 +1,445 @@
 from datetime import datetime
+from pathlib import Path
 
 import pandas as pd
+import plotly.graph_objects as go
 import streamlit as st
 
-from utils.kml_creator import generate_kml_from_df
+from utils.kml_creator import (
+    DEFAULT_SITE_ICON,
+    generate_kml_from_df,
+    generate_site_kml_from_df,
+    kml_color_to_rgba,
+    sector_polygon_coordinates,
+)
 
-st.title(":material/map: Telecom Sector KML Generator")
+st.title(":material/map: Site & Sector KML Creator")
 
+REQUIRED_SECTOR_COLUMNS = {
+    "code",
+    "name",
+    "Azimut",
+    "Longitude",
+    "Latitude",
+    "size",
+    "color",
+}
 
-# display mandatory columns
+SITE_ICON_OPTIONS = {
+    "Yellow pin": {
+        "href": "http://maps.google.com/mapfiles/kml/pushpin/ylw-pushpin.png",
+        "preview_color": "#FACC15",
+        "size": 16,
+    },
+    "Red pin": {
+        "href": "http://maps.google.com/mapfiles/kml/pushpin/red-pushpin.png",
+        "preview_color": "#DC2626",
+        "size": 16,
+    },
+    "Blue pin": {
+        "href": "http://maps.google.com/mapfiles/kml/pushpin/blue-pushpin.png",
+        "preview_color": "#2563EB",
+        "size": 16,
+    },
+    "Green pin": {
+        "href": "http://maps.google.com/mapfiles/kml/pushpin/grn-pushpin.png",
+        "preview_color": "#16A34A",
+        "size": 16,
+    },
+    "Purple pin": {
+        "href": "http://maps.google.com/mapfiles/kml/pushpin/purple-pushpin.png",
+        "preview_color": "#7C3AED",
+        "size": 16,
+    },
+    "Pink pin": {
+        "href": "http://maps.google.com/mapfiles/kml/pushpin/pink-pushpin.png",
+        "preview_color": "#DB2777",
+        "size": 16,
+    },
+    "Light blue pin": {
+        "href": "http://maps.google.com/mapfiles/kml/pushpin/ltblu-pushpin.png",
+        "preview_color": "#38BDF8",
+        "size": 16,
+    },
+    "Circle": {
+        "href": DEFAULT_SITE_ICON,
+        "preview_color": "#E4572E",
+        "size": 13,
+    },
+    "Target": {
+        "href": "http://maps.google.com/mapfiles/kml/shapes/target.png",
+        "preview_color": "#2563EB",
+        "size": 15,
+    },
+    "Square": {
+        "href": "http://maps.google.com/mapfiles/kml/shapes/square.png",
+        "preview_color": "#16A34A",
+        "size": 13,
+    },
+    "Triangle": {
+        "href": "http://maps.google.com/mapfiles/kml/shapes/triangle.png",
+        "preview_color": "#D97706",
+        "size": 14,
+    },
+    "Star": {
+        "href": "http://maps.google.com/mapfiles/kml/shapes/star.png",
+        "preview_color": "#CA8A04",
+        "size": 15,
+    },
+    "Info": {
+        "href": "http://maps.google.com/mapfiles/kml/shapes/info-i.png",
+        "preview_color": "#7C3AED",
+        "size": 14,
+    },
+}
 
-col1, col2 = st.columns(2)
 
-with col1:
-    st.write("Mandatory columns:")
-    st.markdown(
-        """
-    | Column Name | Description |
-    | --- | --- |
-    | code| code of the site |
-    | name | Name of the sector |
-    | Azimut | Azimuth of the sector |
-    | Longitude | Longitude of the sector |
-    | Latitude | Latitude of the sector |
-    | Size | Size of the sector ex:100 |
-    | colors | Color of the sector |
-    """
+def _timestamp() -> str:
+    return datetime.now().strftime("%Y%m%d_%H%M%S")
+
+
+def _read_uploaded_table(uploaded_file) -> pd.DataFrame:
+    suffix = Path(uploaded_file.name).suffix.lower()
+    if suffix == ".csv":
+        return pd.read_csv(uploaded_file, keep_default_na=False)
+    return pd.read_excel(uploaded_file, keep_default_na=False)
+
+
+def _default_column(columns: list[str], candidates: list[str]) -> str:
+    normalized = {str(col).strip().lower(): col for col in columns}
+    for candidate in candidates:
+        if candidate.lower() in normalized:
+            return normalized[candidate.lower()]
+
+    for candidate in candidates:
+        for col in columns:
+            if candidate.lower() in str(col).strip().lower():
+                return col
+
+    return columns[0]
+
+
+def _prepare_coordinate_df(df: pd.DataFrame, lat_col: str, lon_col: str) -> pd.DataFrame:
+    map_df = df.copy()
+    map_df[lat_col] = pd.to_numeric(map_df[lat_col], errors="coerce")
+    map_df[lon_col] = pd.to_numeric(map_df[lon_col], errors="coerce")
+    map_df = map_df.dropna(subset=[lat_col, lon_col])
+    map_df = map_df[
+        map_df[lat_col].between(-90, 90) & map_df[lon_col].between(-180, 180)
+    ]
+    return map_df
+
+
+def _estimate_zoom(df: pd.DataFrame, lat_col: str, lon_col: str) -> float:
+    if df.empty:
+        return 5
+
+    lat_span = float(df[lat_col].max() - df[lat_col].min())
+    lon_span = float(df[lon_col].max() - df[lon_col].min())
+    span = max(lat_span, lon_span)
+
+    if span <= 0.01:
+        return 13
+    if span <= 0.05:
+        return 11
+    if span <= 0.2:
+        return 9
+    if span <= 1:
+        return 7
+    if span <= 5:
+        return 5
+    return 3
+
+
+def _rgba_css(rgba: list[int], alpha_override: float | None = None) -> str:
+    red, green, blue, alpha = rgba
+    alpha_float = alpha / 255 if alpha_override is None else alpha_override
+    return f"rgba({red}, {green}, {blue}, {alpha_float:.3f})"
+
+
+def _hover_text(row: pd.Series) -> str:
+    return "<br>".join(
+        f"<b>{column}</b>: {value}" for column, value in row.items()
     )
-    st.write(
-        "All other columns added in the file will be displayed in the KML description for each sector."
+
+
+def _show_site_position_map(
+    df: pd.DataFrame,
+    site_col: str,
+    lat_col: str,
+    lon_col: str,
+    title: str,
+    show_labels: bool = True,
+    marker_color: str = "#E4572E",
+    marker_size: int = 13,
+) -> None:
+    map_df = _prepare_coordinate_df(df, lat_col, lon_col)
+
+    if map_df.empty:
+        st.warning("No valid coordinates available for map display.")
+        return
+
+    fig = go.Figure()
+    mode = "markers+text" if show_labels else "markers"
+    fig.add_trace(
+        go.Scattermapbox(
+            lat=map_df[lat_col],
+            lon=map_df[lon_col],
+            mode=mode,
+            text=map_df[site_col].astype(str),
+            textposition="top center",
+            marker={"size": marker_size, "color": marker_color},
+            hovertext=map_df.apply(_hover_text, axis=1),
+            hoverinfo="text",
+            name="Sites",
+        )
     )
 
-with col2:
-    st.markdown(
-        """
-    | Color Name | KML Color Code (AABBGGRR) |
-    | --- | --- |
-    | Red | 7f0000ff |
-    | Green | 7f00ff00 |
-    | Blue | 7fff0000 |
-    | Yellow | 7f00ffff |
-    | Cyan | 7fffff00 |
-    | Magenta | 7fff00ff |
-    | Orange | 7f007fff |
-    | Purple | 7f7f00ff |
-    | Pink | 7fcc99ff |
-    | Brown | 7f2a2aa5 |
-    """
+    fig.update_layout(
+        title=title,
+        mapbox_style="open-street-map",
+        mapbox_center={
+            "lat": float(map_df[lat_col].mean()),
+            "lon": float(map_df[lon_col].mean()),
+        },
+        mapbox_zoom=_estimate_zoom(map_df, lat_col, lon_col),
+        height=620,
+        margin={"r": 0, "t": 45, "l": 0, "b": 0},
     )
+    st.plotly_chart(fig, use_container_width=True)
 
-sector_kml_sample_file = "samples/Sector_kml.xlsx"
 
-# Create a download button
-st.download_button(
-    label="Download Sector KML sample File",
-    data=open(sector_kml_sample_file, "rb").read(),
-    file_name="Sector_kml.xlsx",
-    mime="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
-)
+def _show_sector_map(df: pd.DataFrame, show_labels: bool = True) -> None:
+    map_df = _prepare_coordinate_df(df, "Latitude", "Longitude")
+
+    if map_df.empty:
+        st.warning("No valid sector coordinates available for map display.")
+        return
+
+    numeric_cols = ["Azimut", "size"]
+    for col in numeric_cols:
+        map_df[col] = pd.to_numeric(map_df[col], errors="coerce")
+    map_df = map_df.dropna(subset=numeric_cols)
+
+    if map_df.empty:
+        st.warning("No valid azimuth/size values available for sector map display.")
+        return
+
+    fig = go.Figure()
+    df_sorted = map_df.sort_values(by="size", ascending=False)
+
+    for _, row in df_sorted.iterrows():
+        coords = sector_polygon_coordinates(row)
+        lons = [coord[0] for coord in coords]
+        lats = [coord[1] for coord in coords]
+        rgba = kml_color_to_rgba(row["color"])
+        fig.add_trace(
+            go.Scattermapbox(
+                lon=lons,
+                lat=lats,
+                mode="lines",
+                fill="toself",
+                fillcolor=_rgba_css(rgba),
+                line={"color": "black", "width": 1},
+                hovertext=_hover_text(row),
+                hoverinfo="text",
+                name=str(row["name"]),
+                showlegend=False,
+            )
+        )
+
+    site_df = map_df.drop_duplicates(subset=["code"]).copy()
+    mode = "markers+text" if show_labels else "markers"
+    fig.add_trace(
+        go.Scattermapbox(
+            lat=site_df["Latitude"],
+            lon=site_df["Longitude"],
+            mode=mode,
+            text=site_df["code"].astype(str),
+            textposition="top center",
+            marker={"size": 10, "color": "#111111"},
+            hovertext=site_df.apply(_hover_text, axis=1),
+            hoverinfo="text",
+            name="Sites",
+        )
+    )
+
+    fig.update_layout(
+        title="Sector map preview",
+        mapbox_style="open-street-map",
+        mapbox_center={
+            "lat": float(map_df["Latitude"].mean()),
+            "lon": float(map_df["Longitude"].mean()),
+        },
+        mapbox_zoom=_estimate_zoom(map_df, "Latitude", "Longitude"),
+        height=650,
+        margin={"r": 0, "t": 45, "l": 0, "b": 0},
+    )
+    st.plotly_chart(fig, use_container_width=True)
 
 
-st.write("Upload an excel file containing sectors data to generate a KML file.")
-# Upload CSV file
-uploaded_file = st.file_uploader("Upload XLSX file", type=["xlsx"])
+def _render_sector_help() -> None:
+    col1, col2 = st.columns(2)
+
+    with col1:
+        st.write("Mandatory columns:")
+        st.markdown(
+            """
+        | Column Name | Description |
+        | --- | --- |
+        | code | Code of the site |
+        | name | Name of the sector |
+        | Azimut | Azimuth of the sector |
+        | Longitude | Longitude of the sector |
+        | Latitude | Latitude of the sector |
+        | size | Size of the sector, for example `100` |
+        | color | KML color code |
+        """
+        )
+        st.write(
+            "All other columns added in the file will be displayed in the KML description for each sector."
+        )
+
+    with col2:
+        st.markdown(
+            """
+        | Color Name | KML Color Code (AABBGGRR) |
+        | --- | --- |
+        | Red | 7f0000ff |
+        | Green | 7f00ff00 |
+        | Blue | 7fff0000 |
+        | Yellow | 7f00ffff |
+        | Cyan | 7fffff00 |
+        | Magenta | 7fff00ff |
+        | Orange | 7f007fff |
+        | Purple | 7f7f00ff |
+        | Pink | 7fcc99ff |
+        | Brown | 7f2a2aa5 |
+        """
+        )
+
+
+def _render_sector_generator() -> None:
+    _render_sector_help()
+
+    sector_kml_sample_file = "samples/Sector_kml.xlsx"
+    st.download_button(
+        label="Download Sector KML sample File",
+        data=open(sector_kml_sample_file, "rb").read(),
+        file_name="Sector_kml.xlsx",
+        mime="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+    )
+
+    st.write("Upload an Excel file containing sectors data to generate a KML file.")
+    uploaded_file = st.file_uploader(
+        "Upload sector XLSX file", type=["xlsx"], key="sector_kml_file"
+    )
+
+    if uploaded_file is None:
+        return
 
-if uploaded_file is not None:
-    # Read CSV
     df = pd.read_excel(uploaded_file, keep_default_na=False)
+    missing_columns = REQUIRED_SECTOR_COLUMNS.difference(df.columns)
+
+    if missing_columns:
+        st.error(f"Uploaded file must contain columns: {', '.join(sorted(missing_columns))}")
+        return
+
+    kml_data = generate_kml_from_df(df)
+    st.download_button(
+        label="Download Sector KML",
+        data=kml_data,
+        file_name=f"Sectors_kml_{_timestamp()}.kml",
+        mime="application/vnd.google-earth.kml+xml",
+    )
+
+    st.success("Sector KML file generated successfully.")
+    st.dataframe(df.head(100), use_container_width=True)
+    show_labels = st.checkbox("Show site labels on map", value=True, key="sector_labels")
+    _show_sector_map(df, show_labels=show_labels)
 
-    # Check if required columns exist
-    required_columns = {
-        "code",
-        "name",
-        "Azimut",
-        "Longitude",
-        "Latitude",
-        "size",
-        "color",
-    }
-    if not required_columns.issubset(df.columns):
-        st.error(f"Uploaded file must contain columns: {', '.join(required_columns)}")
-    else:
-        # Generate KML
-        kml_data = generate_kml_from_df(df)
-
-        # Download button
-        st.download_button(
-            label="Download KML",
-            data=kml_data,
-            file_name=f"Sectors_kml_{datetime.now()}.kml",
-            mime="application/vnd.google-earth.kml+xml",
+
+def _render_site_position_generator() -> None:
+    st.write(
+        "Upload an Excel or CSV file containing site positions. Minimum required data: site name/code, latitude, longitude."
+    )
+    uploaded_file = st.file_uploader(
+        "Upload site position file", type=["xlsx", "csv"], key="site_position_file"
+    )
+
+    if uploaded_file is None:
+        return
+
+    df = _read_uploaded_table(uploaded_file)
+    if df.empty:
+        st.warning("Uploaded file is empty.")
+        return
+
+    columns = df.columns.tolist()
+    col1, col2, col3, col4 = st.columns(4)
+
+    with col1:
+        site_col = st.selectbox(
+            "Site column",
+            columns,
+            index=columns.index(_default_column(columns, ["site", "code", "name", "site_code"])),
+        )
+    with col2:
+        lat_col = st.selectbox(
+            "Latitude column",
+            columns,
+            index=columns.index(_default_column(columns, ["Latitude", "lat", "y"])),
         )
+    with col3:
+        lon_col = st.selectbox(
+            "Longitude column",
+            columns,
+            index=columns.index(_default_column(columns, ["Longitude", "lon", "lng", "x"])),
+        )
+    with col4:
+        icon_name = st.selectbox(
+            "Site icon",
+            list(SITE_ICON_OPTIONS.keys()),
+            index=0,
+        )
+
+    map_df = _prepare_coordinate_df(df, lat_col, lon_col)
+    if map_df.empty:
+        st.warning("No valid latitude/longitude rows found after cleaning.")
+        return
+
+    icon_config = SITE_ICON_OPTIONS[icon_name]
+    kml_data = generate_site_kml_from_df(
+        map_df,
+        site_col,
+        lat_col,
+        lon_col,
+        icon_href=icon_config["href"],
+    )
+    st.download_button(
+        label="Download Site Position KML",
+        data=kml_data,
+        file_name=f"Site_positions_{_timestamp()}.kml",
+        mime="application/vnd.google-earth.kml+xml",
+    )
+
+    st.success(f"Site position KML generated successfully for {len(map_df)} valid sites.")
+    st.dataframe(map_df.head(100), use_container_width=True)
+    show_labels = st.checkbox("Show site labels on map", value=True, key="site_labels")
+    _show_site_position_map(
+        map_df,
+        site_col=site_col,
+        lat_col=lat_col,
+        lon_col=lon_col,
+        title="Site position map preview",
+        show_labels=show_labels,
+        marker_color=icon_config["preview_color"],
+        marker_size=icon_config["size"],
+    )
+
 
-        st.success("KML file generated successfully.")
+tab_sectors, tab_sites = st.tabs(["Sectors", "Site positions"])
+with tab_sectors:
+    _render_sector_generator()
+with tab_sites:
+    _render_site_position_generator()

documentations/sector_kml_doc.py

@@ -2,22 +2,25 @@
 
 st.markdown(
     """
-# Sector KML Generator Documentation
+# Site & Sector KML Creator Documentation
 
 ## 1. Objective
-Generate a KML file from sector-level Excel data for geographic visualization.
+Generate KML files and map previews from sector-level or site-position input data.
 
 ## 2. When to use this tool
 Use this page when you need to:
 - visualize telecom sectors in GIS/KML viewers
+- preview sectors directly on an OpenStreetMap map before download
+- plot simple site positions without sector polygons
 - share sector orientation and metadata
 - prepare map overlays for field/optimization teams
 
 ## 3. Input files and accepted formats
-- Required: one `.xlsx` file containing sector data.
+- Sector mode: one `.xlsx` file containing sector data.
+- Site positions mode: one `.xlsx` or `.csv` file containing at least site, latitude, and longitude columns.
 
 ## 4. Required columns
-The uploaded file must contain all required columns:
+For sector generation, the uploaded file must contain all required columns:
 - `code`
 - `name`
 - `Azimut`
@@ -28,36 +31,57 @@ The uploaded file must contain all required columns:
 
 Any additional column is exported in sector description metadata.
 
+For site-position generation, select the columns that represent:
+- site name/code
+- latitude
+- longitude
+
+Any additional column is exported in site description metadata.
+The selected site icon is applied to the generated KML point placemarks.
+
 ## 5. Step-by-step usage
-1. Open `Apps > Sector KML Generator`.
+1. Open `Apps > Site & Sector KML Creator`.
 2. (Optional) Download sample file from the page.
-3. Upload your Excel file.
-4. Ensure required columns are present.
-5. Download generated KML.
+3. Choose `Sectors` or `Site positions`.
+4. Upload your file.
+5. Ensure required columns are present or select the matching site/latitude/longitude columns.
+6. Review the map preview.
+7. Download generated KML.
 
 ## 6. Outputs generated
-- downloadable KML file named like `Sectors_kml_<timestamp>.kml`
+- downloadable sector KML file named like `Sectors_kml_<timestamp>.kml`
+- downloadable site-position KML file named like `Site_positions_<timestamp>.kml`
+- interactive map preview inside the app
 
 ## 7. Frequent errors and fixes
 - Missing required columns error.
   - Fix: rename columns exactly as required.
 - Empty/invalid geometry in output.
   - Fix: verify `Latitude`/`Longitude` and azimuth values.
+- Empty map preview.
+  - Fix: verify selected latitude/longitude columns contain decimal coordinates.
 - Unexpected style/color rendering.
   - Fix: validate color codes and supported color naming.
 
 ## 8. Minimal reproducible example
-- Input: `samples/Sector_kml.xlsx`
-- Action: upload file and click download when generated.
-- Expected result: valid KML file ready for map tools.
+- Sector input: `samples/Sector_kml.xlsx`
+- Action: upload file, review preview map, then download generated KML.
+- Expected result: valid KML file ready for map tools and matching map preview.
+
+Site-position minimal input:
+
+| site | lat | lon |
+| --- | --- | --- |
+| S001 | 12.3 | -7.1 |
 
 ## 9. Known limitations
 - Input schema is case-sensitive for required column names.
-- Only `.xlsx` is supported.
+- Sector mode supports `.xlsx`.
+- Site-position mode supports `.xlsx` and `.csv`.
 - Invalid coordinate values may produce unusable geometry.
 
 ## 10. Version and update date
-- Documentation version: 1.0
-- Last update: 2026-02-23
+- Documentation version: 1.1
+- Last update: 2026-05-02
 """
 )

tests/test_kml_creator.py

@@ -1,6 +1,11 @@
 import pandas as pd
 
-from utils.kml_creator import generate_kml_from_df
+from utils.kml_creator import (
+    generate_kml_from_df,
+    generate_site_kml_from_df,
+    kml_color_to_rgba,
+    sector_polygon_coordinates,
+)
 
 
 def test_generate_kml_from_df_formats_integer_like_site_codes_without_decimal():
@@ -24,3 +29,48 @@ def test_generate_kml_from_df_formats_integer_like_site_codes_without_decimal():
 
     assert "<name>694</name>" in kml_text
     assert "<name>694.0</name>" not in kml_text
+
+
+def test_sector_polygon_coordinates_closes_polygon():
+    row = {
+        "Longitude": -7.1,
+        "Latitude": 12.3,
+        "Azimut": 90,
+        "size": 100,
+    }
+
+    coords = sector_polygon_coordinates(row)
+
+    assert len(coords) == 22
+    assert coords[0] == (-7.1, 12.3)
+    assert coords[-1] == coords[0]
+
+
+def test_kml_color_to_rgba_converts_aabbggrr():
+    assert kml_color_to_rgba("7f0000ff") == [255, 0, 0, 127]
+    assert kml_color_to_rgba("bad") == [31, 119, 180, 127]
+
+
+def test_generate_site_kml_from_df_exports_site_points_and_metadata():
+    df = pd.DataFrame(
+        [
+            {
+                "site": "S001",
+                "lat": 12.3,
+                "lon": -7.1,
+                "region": "North",
+            }
+        ]
+    )
+
+    icon_href = "http://maps.google.com/mapfiles/kml/shapes/star.png"
+    kml_text = (
+        generate_site_kml_from_df(df, "site", "lat", "lon", icon_href=icon_href)
+        .getvalue()
+        .decode("utf-8")
+    )
+
+    assert "<name>S001</name>" in kml_text
+    assert f"<href>{icon_href}</href>" in kml_text
+    assert "&lt;b&gt;region:&lt;/b&gt; North&lt;br&gt;" in kml_text
+    assert "-7.1,12.3,0.0" in kml_text

utils/kml_creator.py

@@ -6,6 +6,11 @@ import pandas as pd
 import simplekml
 
 
+DEFAULT_SITE_ICON = "http://maps.google.com/mapfiles/kml/shapes/placemark_circle.png"
+DEFAULT_SITE_COLOR = "ff1f77b4"
+DEFAULT_SECTOR_COLOR_RGBA = [31, 119, 180, 127]
+
+
 def _format_kml_value(value) -> str:
     """Render integer-like numeric values without a trailing .0 in KML text."""
     if pd.isna(value):
@@ -26,42 +31,70 @@ def _format_kml_value(value) -> str:
     return str(value)
 
 
-def create_sector(kml: simplekml.Kml, row, arc_angle=65):
-    """Create a sector shape for the telecom antenna in KML with sector details."""
-    code, name, azimuth, lon, lat, size, color = (
-        _format_kml_value(row["code"]),
-        _format_kml_value(row["name"]),
-        row["Azimut"],
-        row["Longitude"],
-        row["Latitude"],
-        row["size"],
-        row["color"],
-    )
+def _kml_bytes(kml: simplekml.Kml) -> io.BytesIO:
+    kml_data = io.BytesIO()
+    kml_data.write(kml.kml().encode("utf-8"))
+    kml_data.seek(0)
+    return kml_data
+
+
+def _row_description(row, title: str) -> str:
+    description = f"<b>{title}</b><br>"
+    for column, value in row.items():
+        description += f"<b>{column}:</b> {_format_kml_value(value)}<br>"
+    return description
+
+
+def kml_color_to_rgba(color) -> list[int]:
+    """Convert KML AABBGGRR colors to pydeck/Plotly RGBA values."""
+    value = str(color).strip().lstrip("#")
+    if len(value) != 8:
+        return DEFAULT_SECTOR_COLOR_RGBA.copy()
+
+    try:
+        alpha = int(value[0:2], 16)
+        blue = int(value[2:4], 16)
+        green = int(value[4:6], 16)
+        red = int(value[6:8], 16)
+    except ValueError:
+        return DEFAULT_SECTOR_COLOR_RGBA.copy()
+
+    return [red, green, blue, alpha]
+
+
+def sector_polygon_coordinates(row, arc_angle=65, num_points=20) -> list[tuple[float, float]]:
+    """Return sector polygon coordinates as (lon, lat), matching the KML geometry."""
+    azimuth = row["Azimut"]
+    lon = row["Longitude"]
+    lat = row["Latitude"]
+    size = row["size"]
 
-    num_points = 20  # Number of points for smooth arc
     start_angle = azimuth - (arc_angle / 2)
     end_angle = azimuth + (arc_angle / 2)
+    coords = [(lon, lat)]
 
-    coords = [(lon, lat)]  # Start with the site location (center point)
-
-    # Generate points for the sector arc
     for angle in np.linspace(start_angle, end_angle, num_points):
         angle_rad = math.radians(angle)
         arc_lon = lon + (size / 111320) * math.sin(angle_rad)
         arc_lat = lat + (size / 111320) * math.cos(angle_rad)
         coords.append((arc_lon, arc_lat))
 
-    coords.append((lon, lat))  # Close the polygon
+    coords.append((lon, lat))
+    return coords
 
-    # Create the sector polygon
-    pol = kml.newpolygon(name=name, outerboundaryis=coords)
 
-    # Dynamically create the description from all DataFrame columns
-    description = "<b>Sector Details:</b><br>"
-    for column, value in row.items():
-        description += f"<b>{column}:</b> {_format_kml_value(value)}<br>"
+def create_sector(kml: simplekml.Kml, row, arc_angle=65):
+    """Create a sector shape for the telecom antenna in KML with sector details."""
+    name, color = (
+        _format_kml_value(row["name"]),
+        row["color"],
+    )
+
+    coords = sector_polygon_coordinates(row, arc_angle=arc_angle)
 
-    pol.description = description
+    # Create the sector polygon
+    pol = kml.newpolygon(name=name, outerboundaryis=coords)
+    pol.description = _row_description(row, "Sector Details:")
     pol.style.polystyle.color = color  # Set color from DataFrame
     pol.style.polystyle.outline = 1  # Outline enabled
     pol.style.linestyle.color = "ff000000"  # Black outline
@@ -84,17 +117,36 @@ def generate_kml_from_df(df: pd.DataFrame):
         # Add site name as a point only once
         if code not in site_added:
             pnt = kml.newpoint(name=code, coords=[(lon, lat)])
-            pnt.style.iconstyle.icon.href = (
-                "http://maps.google.com/mapfiles/kml/shapes/placemark_circle.png"
-            )
+            pnt.style.iconstyle.icon.href = DEFAULT_SITE_ICON
             pnt.style.labelstyle.scale = 1.2  # Adjust label size
             pnt.description = f"Site: {code}<br>Location: {lat}, {lon}"
             site_added.add(code)
 
         create_sector(kml, row)
 
-    kml_data = io.BytesIO()
-    kml_str = kml.kml()  # Get KML as string
-    kml_data.write(kml_str.encode("utf-8"))  # Write KML to BytesIO
-    kml_data.seek(0)  # Move to beginning of BytesIO
-    return kml_data
+    return _kml_bytes(kml)
+
+
+def generate_site_kml_from_df(
+    df: pd.DataFrame,
+    site_col: str = "site",
+    lat_col: str = "Latitude",
+    lon_col: str = "Longitude",
+    icon_href: str = DEFAULT_SITE_ICON,
+    icon_color: str = DEFAULT_SITE_COLOR,
+):
+    """Generate a KML file from site coordinates without sector polygons."""
+    kml = simplekml.Kml()
+
+    for _, row in df.iterrows():
+        site_name = _format_kml_value(row[site_col])
+        lat = row[lat_col]
+        lon = row[lon_col]
+
+        pnt = kml.newpoint(name=site_name, coords=[(lon, lat)])
+        pnt.style.iconstyle.icon.href = icon_href
+        pnt.style.iconstyle.color = icon_color
+        pnt.style.labelstyle.scale = 1.1
+        pnt.description = _row_description(row, "Site Details:")
+
+    return _kml_bytes(kml)