eas-3d-pattern 0.1.4__tar.gz → 0.2.0__tar.gz

{eas_3d_pattern-0.1.4 → eas_3d_pattern-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: eas-3d-pattern
-Version: 0.1.4
+Version: 0.2.0
 Summary: A tool to visualize 3D antenna pattern files in JSON format.
 License: MIT License
          

{eas_3d_pattern-0.1.4 → eas_3d_pattern-0.2.0}/pyproject.toml

@@ -38,7 +38,7 @@ classifiers = [
     "Operating System :: OS Independent",
     "Topic :: Scientific/Engineering :: Visualization",
 ]
-version = "0.1.4"
+version = "0.2.0"
 
 [project.urls]
 homepage = "https://www.ericsson.com/antenna-system"
@@ -60,6 +60,11 @@ ruff = "^0.11.12"
 mypy = "^1.16.0"
 pre-commit = "^4.2.0"
 pytest = "^8.0"
+jupyterlab = "^4.6.2"
+matplotlib = "^3.10.0"
+pytest-mpl = "^0.17.0"
+pytest-cov = "^7.0.0"
+scipy = "^1.14"
 
 [tool.poetry.group.typing.dependencies]
 pandas-stubs = "2.2.2.240909"
@@ -142,6 +147,9 @@ ignore = [
 "src/eas_3d_pattern/parser.py" = [
     "D102", # Missing docstring in public method (very common for test methods)
 ]
+"tests/**" = [
+    "D102", # Test method names are self-documenting; class docstrings cover intent
+]
 
 [tool.ruff.lint.pydocstyle]
 convention = "google"
@@ -159,8 +167,16 @@ docstring-code-format = true
 minversion = "8.0"
 testpaths = ["tests"]
 addopts = "-q"
+markers = [
+    "image: compares a rendered figure against a PNG baseline; deselect with -m 'not image' if a runner's renderer differs",
+    "slow: exercises a multi-megabyte bundled sample; deselect with -m 'not slow'",
+]
 filterwarnings = [
     "ignore::DeprecationWarning",
+    # The library's own deprecations are FutureWarning (visible to end users by
+    # default). Promote them to errors so internal code and tests cannot quietly
+    # depend on a deprecated entry point; assert them with pytest.warns instead.
+    "error::FutureWarning",
 ]
 
 [tool.mypy]

{eas_3d_pattern-0.1.4 → eas_3d_pattern-0.2.0}/src/eas_3d_pattern/__init__.py

@@ -3,8 +3,8 @@ from importlib.metadata import PackageNotFoundError, version
 
 from .parser import AntennaPattern
 from .sample_data import SAMPLE_JSON
-from .schema_manager import NGMNSchema
-from .sector_definitions import SectorDefinition
+from .schema_manager import NGMNSchema, SchemaSource
+from .sector import SectorDefinition
 from .util_func.report import generate_report_eas
 
 LIBRARY_PACKAGE_NAME = __name__
@@ -20,6 +20,7 @@ __all__ = [
     "SAMPLE_JSON",
     "AntennaPattern",
     "NGMNSchema",
+    "SchemaSource",
     "SectorDefinition",
     "generate_report_eas",
 ]

eas_3d_pattern-0.2.0/src/eas_3d_pattern/metrics/__init__.py

@@ -0,0 +1,36 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025-2026 Ericsson
+#
+# Author: Mattia Milani <mattia.milani@ericsson.com>
+#
+# This file is part of eas-3d-pattern and is distributed under the terms of the
+# MIT License. See the LICENSE file at the repository root for the full text,
+# including the warranty disclaimer and redistribution conditions.
+"""Antenna pattern metrics.
+
+Figures of merit derived from the processed pattern dataset — directivity,
+ohmic losses, and the shared solid-angle quadrature weights they integrate
+against. Implemented as pure functions taking the dataset, so they can be used
+and tested without constructing an ``AntennaPattern``.
+
+Not re-exported from the top-level package: ``AntennaPattern`` remains the
+supported entry point while the API-naming work (plan section 2.9 / M2-14) is
+still open.
+"""
+
+from __future__ import annotations
+
+from eas_3d_pattern.metrics.directivity import directivity, losses
+from eas_3d_pattern.metrics.efficiency import beam_efficiency
+from eas_3d_pattern.metrics.peak import find_peak, top_3db_border
+from eas_3d_pattern.metrics.quadrature import DOMEGA, ensure_domega
+
+__all__ = [
+    "DOMEGA",
+    "beam_efficiency",
+    "directivity",
+    "ensure_domega",
+    "find_peak",
+    "losses",
+    "top_3db_border",
+]

eas_3d_pattern-0.2.0/src/eas_3d_pattern/metrics/directivity.py

@@ -0,0 +1,75 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025-2026 Ericsson
+#
+# Author: Mattia Milani <mattia.milani@ericsson.com>
+#
+# This file is part of eas-3d-pattern and is distributed under the terms of the
+# MIT License. See the LICENSE file at the repository root for the full text,
+# including the warranty disclaimer and redistribution conditions.
+"""Directivity and ohmic-loss metrics.
+
+Pure functions over the processed pattern dataset: data in, number out. Neither
+reads nor mutates ``AntennaPattern`` state, beyond the deliberate ``dOmega``
+cache injected by :func:`~eas_3d_pattern.metrics.quadrature.ensure_domega`.
+
+Split out of ``parser.py`` (Phase 3a of the god-class decomposition, plan
+section 2.1.3).
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import cast
+
+import numpy as np
+import xarray as xr
+
+from eas_3d_pattern.metrics.quadrature import DOMEGA, ensure_domega
+from eas_3d_pattern.util_func.guards import verify
+
+logger = logging.getLogger(__name__)
+
+
+def directivity(pattern_3d: xr.Dataset) -> float:
+    """Calculate the directivity of the antenna pattern data.
+
+    Directivity is calculated with the average radiation intensity over the whole
+    sphere and the maximum radiation intensity. Can only be calculated if data is
+    complete (full sphere). Regular grids are advised.
+
+    Args:
+        pattern_3d (xr.Dataset): Processed pattern dataset. Gains a ``dOmega``
+            data variable as a side effect if it is not already present.
+
+    Returns:
+        float: The directivity value in dBi.
+    """
+    logger.debug("AntennaPattern: Calculating directivity of antenna pattern data.")
+    ensure_domega(pattern_3d)
+    Umax = float(pattern_3d["P_tp_lin"].max())
+    Uavg = float(
+        (pattern_3d["P_tp_lin"] * pattern_3d[DOMEGA]).sum(("Theta", "Phi"))
+        / (pattern_3d[DOMEGA].sum())
+    )
+    return float(10 * np.log10(Umax / Uavg))
+
+
+def losses(pattern_3d: xr.Dataset, gain_dbi: float | None) -> float:
+    """Calculate the ohmic losses of the antenna pattern data.
+
+    Antenna losses are the declared header gain minus the calculated directivity.
+
+    Args:
+        pattern_3d (xr.Dataset): Processed pattern dataset.
+        gain_dbi (float | None): Declared gain in dBi from the pattern metadata.
+
+    Raises:
+        ValueError: If no gain is declared in the pattern metadata.
+
+    Returns:
+        float: The loss value in dB (gain - directivity).
+    """
+    logger.debug("AntennaPattern: Calculating losses of antenna pattern data.")
+    verify(gain_dbi is not None, "AntennaPattern: 'Gain' not provided, it's required.")
+    # verify() guarantees gain_dbi is non-None; cast narrows for mypy.
+    return float(cast("float", gain_dbi) - directivity(pattern_3d))

eas_3d_pattern-0.2.0/src/eas_3d_pattern/metrics/efficiency.py

@@ -0,0 +1,128 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025-2026 Ericsson
+#
+# Author: Mattia Milani <mattia.milani@ericsson.com>
+#
+# This file is part of eas-3d-pattern and is distributed under the terms of the
+# MIT License. See the LICENSE file at the repository root for the full text,
+# including the warranty disclaimer and redistribution conditions.
+"""Beam efficiency over sector definitions.
+
+Solid-angle-weighted power fraction falling inside each declared sector. Pure
+function over the processed pattern dataset and a
+:class:`~eas_3d_pattern.sector.SectorDefinition`.
+
+Preset *dispatch* deliberately stays on ``AntennaPattern``: choosing a preset
+requires pattern-derived inputs (the measured 3 dB border, the beam peak) that
+are produced by side-effecting methods, and threading those through a pure
+function would change which dataset attributes end up published.
+
+Split out of ``parser.py`` (Phase 3c of the god-class decomposition, plan
+section 2.1.3).
+"""
+
+from __future__ import annotations
+
+import logging
+import operator
+from collections.abc import Callable
+from types import MappingProxyType
+
+import xarray as xr
+
+from eas_3d_pattern.metrics.quadrature import DOMEGA, ensure_domega
+from eas_3d_pattern.sector import BoundaryBox, Sector
+from eas_3d_pattern.util_func.guards import verify
+
+logger = logging.getLogger(__name__)
+
+#: Component holding the linear total-power pattern.
+POWER_COMPONENT_LIN = "P_tp_lin"
+#: Component holding the linear co-polar pattern.
+COPOLAR_COMPONENT_LIN = "P_co_lin"
+
+#: Comparison operators a sector boundary may declare. Read-only lookup table.
+BOUNDARY_OPERATORS: MappingProxyType[str, Callable[[float, float], bool]] = (
+    MappingProxyType(
+        {
+            "<": operator.lt,
+            "<=": operator.le,
+            ">": operator.gt,
+            ">=": operator.ge,
+        }
+    )
+)
+
+
+def beam_efficiency(
+    pattern: xr.Dataset,
+    sectors: Sector,
+    powersum: bool = True,
+) -> dict[str, float]:
+    """Calculate the beam efficiency of the antenna pattern data.
+
+    Beam efficiency is the ratio of the solid-angle-weighted power inside each
+    sector to the overall weighted power. Calculations are based only on the
+    summation method for now.
+
+    Args:
+        pattern (xr.Dataset): Processed pattern dataset. Gains a ``dOmega``
+            data variable as a side effect if it is not already present.
+        sectors (Sector): Sector boundaries to integrate over.
+        powersum (bool, optional): If True, efficiency is calculated on total
+            power. If False, on the co-polar pattern. Defaults to True.
+
+    Raises:
+        ValueError: If the overall power sums to zero, which would make every
+            efficiency nan or inf.
+        TypeError: If any sector is not a ``BoundaryBox``.
+
+    Returns:
+        dict[str, float]: Sector name to efficiency fraction.
+    """
+    logger.debug("AntennaPattern: Calculating beam efficiency of antenna pattern data.")
+    component = POWER_COMPONENT_LIN if powersum else COPOLAR_COMPONENT_LIN
+    field_values = pattern[component]
+
+    ensure_domega(pattern)
+
+    weighted_field_values = pattern[DOMEGA] * field_values
+    Sp_overall = float(weighted_field_values.sum())
+    verify(Sp_overall != 0, "Overall power is zero; cannot compute beam efficiency.")
+
+    efficiency = {}
+    for sector_name, box in sectors.sectors.items():
+        verify(isinstance(box, BoundaryBox),
+               f"Sector Definitions need to be class 'BoundaryBox' but is class {type(box)}.",
+               TypeError)
+        efficiency[sector_name] = float(
+            _sector_sum(weighted_field_values, box) / Sp_overall
+        )
+
+    return efficiency
+
+
+def _sector_sum(
+    weighted_field_values: xr.DataArray, box: BoundaryBox
+) -> xr.DataArray:
+    """Sum the weighted field inside one rectangular sector.
+
+    Args:
+        weighted_field_values (xr.DataArray): Field already multiplied by ``dOmega``.
+        box (BoundaryBox): Theta/Phi bounds, each paired with the comparison
+            operator to apply.
+
+    Returns:
+        xr.DataArray: Zero-dimensional array holding the weighted power inside the sector.
+    """
+    theta = weighted_field_values.Theta
+    phi = weighted_field_values.Phi
+    return (
+        weighted_field_values.where(
+            BOUNDARY_OPERATORS[box.theta_min[1]](box.theta_min[0], theta), drop=True
+        )
+        .where(BOUNDARY_OPERATORS[box.theta_max[1]](theta, box.theta_max[0]), drop=True)
+        .where(BOUNDARY_OPERATORS[box.phi_min[1]](box.phi_min[0], phi), drop=True)
+        .where(BOUNDARY_OPERATORS[box.phi_max[1]](phi, box.phi_max[0]), drop=True)
+        .sum()
+    )

eas_3d_pattern-0.2.0/src/eas_3d_pattern/metrics/peak.py

@@ -0,0 +1,133 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025-2026 Ericsson
+#
+# Author: Mattia Milani <mattia.milani@ericsson.com>
+#
+# This file is part of eas-3d-pattern and is distributed under the terms of the
+# MIT License. See the LICENSE file at the repository root for the full text,
+# including the warranty disclaimer and redistribution conditions.
+"""Beam peak location and the top 3 dB border.
+
+Pure functions over the processed pattern dataset. Neither reads nor mutates
+``AntennaPattern`` state: the dataset attributes that ``util_func/report.py``
+depends on (``peak_coordinates``, ``top_3db_point``) are published by the
+``AntennaPattern`` wrappers, which own that side effect.
+
+``top_3db_border`` takes the peak as an argument rather than locating it itself,
+so the caller decides whether locating the peak should also publish it.
+
+Split out of ``parser.py`` (Phase 3b of the god-class decomposition, plan
+section 2.1.3).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import xarray as xr
+
+from eas_3d_pattern.util_func.guards import verify
+
+logger = logging.getLogger(__name__)
+
+#: Component holding the total-power pattern in dB.
+POWER_COMPONENT = "P_tp_dB"
+#: Component holding the co-polar pattern in dB.
+COPOLAR_COMPONENT = "P_co_dB"
+#: Half-power level relative to the beam peak, in dB.
+HALF_POWER_DB = -3.0
+#: Grid step assumed when the theta axis has too few points to measure one.
+FALLBACK_GRID_STEP_DEG = 1.0
+
+
+def component_name(power: bool) -> str:
+    """Return the dataset component to search for a given ``power`` flag.
+
+    Args:
+        power (bool): Whether to use the total-power component instead of co-polar.
+
+    Returns:
+        str: Name of the data variable to read.
+    """
+    return POWER_COMPONENT if power else COPOLAR_COMPONENT
+
+
+def find_peak(pattern: xr.Dataset, power: bool = False) -> tuple[float, float]:
+    """Find the Theta/Phi coordinates of the pattern peak.
+
+    Searches for the maximum value within the pattern data array. If two points
+    represent a maximum value, the first one is returned.
+
+    Args:
+        pattern (xr.Dataset): Processed pattern dataset.
+        power (bool, optional): Whether to search the power component instead of
+            the co-polarized one. Defaults to False.
+
+    Raises:
+        ValueError: If the component yields no peak coordinate pair, which happens
+            when the dataset is not indexed by both Theta and Phi.
+
+    Returns:
+        tuple[float, float]: (theta, phi) coordinates of the peak in degrees.
+    """
+    component = component_name(power)
+    logger.debug(f"AntennaPattern: Searching for peak of component {component}")
+    peak_tuple = (
+        pattern.stack(pt=("Theta", "Phi")).idxmax("pt")[component].values.item()
+    )
+    verify(isinstance(peak_tuple, tuple),
+           "AntennaPattern: Failed to find peak coordinates for the component. Make sure to select a component with data.")
+    theta_val_peak, phi_val_peak = peak_tuple
+    logger.debug(f"AntennaPattern: Peak coordinates found: {peak_tuple}")
+    return theta_val_peak, phi_val_peak
+
+
+def top_3db_border(
+    pattern: xr.Dataset,
+    theta_peak: float,
+    phi_peak: float,
+    power: bool = False,
+) -> float:
+    """Find the Theta border where the beam falls 3 dB below its peak.
+
+    No interpolation is done; this is a simplistic search for the last point
+    reported above -3 dB, advanced by one theta grid step.
+
+    Args:
+        pattern (xr.Dataset): Processed pattern dataset.
+        theta_peak (float): Theta coordinate of the beam peak, in degrees.
+        phi_peak (float): Phi coordinate of the beam peak, in degrees.
+        power (bool, optional): Whether to cut the power component instead of the
+            co-polarized one. Defaults to False, which complies with the NGMN standard.
+
+    Returns:
+        float: Theta border for the top 3 dB point in degrees.
+    """
+    vertical_cut = pattern.sel(Phi=phi_peak)
+    vertical_cut_normed = vertical_cut[component_name(power)]
+
+    # Fallback: if no point at/below -3 dB exists above the peak (e.g. a very
+    # narrow beam peaking at the top of the cut), the 3 dB border collapses to
+    # the peak theta itself instead of leaving ``top_border`` unbound.
+    top_border = float(theta_peak)
+
+    # Advance the border by the actual theta grid step rather than a hardcoded
+    # 1 deg, so the result is correct for any sampling resolution.
+    theta_axis = np.sort(vertical_cut_normed["Theta"].values)
+    if theta_axis.size > 1:
+        grid_step = float(np.median(np.diff(theta_axis)))
+    else:
+        grid_step = FALLBACK_GRID_STEP_DEG
+
+    for theta_val in np.flip(
+        vertical_cut_normed.sel(Theta=slice(0, theta_peak))["Theta"]
+    ):
+        if vertical_cut_normed.sel(Theta=theta_val) <= HALF_POWER_DB:
+            top_border = float(theta_val.values) + grid_step
+            break
+    else:
+        logger.warning(
+            "AntennaPattern: No -3 dB crossing found above the peak; using peak theta as top 3 dB border."
+        )
+    return top_border

eas_3d_pattern-0.2.0/src/eas_3d_pattern/metrics/quadrature.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025-2026 Ericsson
+#
+# Author: Mattia Milani <mattia.milani@ericsson.com>
+#
+# This file is part of eas-3d-pattern and is distributed under the terms of the
+# MIT License. See the LICENSE file at the repository root for the full text,
+# including the warranty disclaimer and redistribution conditions.
+"""Solid-angle quadrature weights for integration over the sphere.
+
+Provides the ``dOmega`` weights that turn a plain sum over grid points into a
+solid-angle-weighted integral. Shared by the directivity and beam-efficiency
+metrics, which is why this lives in its own module rather than beside either.
+
+Split out of ``parser.py`` (Phase 3a of the god-class decomposition, plan
+section 2.1.3).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import xarray as xr
+
+#: Name of the data variable holding the solid-angle weights on the dataset.
+DOMEGA = "dOmega"
+
+
+def ensure_domega(pattern_3d: xr.Dataset) -> None:
+    """Ensure the solid-angle weight ``dOmega`` exists on ``pattern_3d``.
+
+    Computes ``dOmega = sin(theta) * dTheta * dPhi`` and injects it as a data variable,
+    which is what turns a plain sum over grid points into a solid-angle-weighted
+    integral over the sphere. No-op if it is already present, so the cost is paid once
+    per pattern.
+
+    ``np.gradient`` is applied to the coordinate arrays themselves, so it yields the
+    local spacing at each point and therefore handles unevenly spaced grids as well as
+    regular ones.
+
+    Args:
+        pattern_3d (xr.Dataset): Processed pattern dataset, modified in place.
+
+    Note:
+        This mutates ``pattern_3d`` in place. The side effect is deliberate and relied
+        upon as a cache by the directivity and beam-efficiency metrics.
+    """
+    if DOMEGA in pattern_3d.data_vars:
+        return
+
+    # The transpose operation for 1D vectors has no effect
+    weight = np.repeat(
+        np.sin(np.deg2rad(pattern_3d.Theta.values)).T[:, None],
+        len(pattern_3d.Phi),
+        axis=1,
+    )
+    dTheta = np.abs(np.gradient(np.deg2rad(pattern_3d["Theta"]))).reshape(-1, 1)
+    dPhi = np.abs(np.gradient(np.deg2rad(pattern_3d["Phi"]))).reshape(1, -1)
+    pattern_3d[DOMEGA] = xr.DataArray(
+        weight * (dTheta * dPhi),
+        dims=("Theta", "Phi"),
+        coords={"Theta": pattern_3d.Theta, "Phi": pattern_3d.Phi},
+        name=DOMEGA,
+    )

eas_3d_pattern-0.2.0/src/eas_3d_pattern/ngmn/__init__.py

@@ -0,0 +1,41 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025-2026 Ericsson
+#
+# Author: Mattia Milani <mattia.milani@ericsson.com>
+#
+# This file is part of eas-3d-pattern and is distributed under the terms of the
+# MIT License. See the LICENSE file at the repository root for the full text,
+# including the warranty disclaimer and redistribution conditions.
+"""NGMN BASTA domain package.
+
+Groups code bound to the NGMN BASTA specification: reading and validating 3drp
+JSON files (:mod:`~eas_3d_pattern.ngmn.loader`), the read-only :class:`Metadata`
+accessors, and the coordinate-system conversions
+(:mod:`~eas_3d_pattern.ngmn.coordinates`).
+"""
+
+from __future__ import annotations
+
+from eas_3d_pattern.ngmn.coordinates import (
+    DEFAULT_INTERNAL_COORD_SYSTEM,
+    EXPECTED_COORDINATE_SYSTEMS,
+    to_internal_frame,
+)
+from eas_3d_pattern.ngmn.loader import (
+    json_load,
+    load_json_file,
+    normalize_keys,
+    validate_against_schema,
+)
+from eas_3d_pattern.ngmn.metadata import Metadata
+
+__all__ = [
+    "DEFAULT_INTERNAL_COORD_SYSTEM",
+    "EXPECTED_COORDINATE_SYSTEMS",
+    "Metadata",
+    "json_load",
+    "load_json_file",
+    "normalize_keys",
+    "to_internal_frame",
+    "validate_against_schema",
+]

eas_3d_pattern-0.2.0/src/eas_3d_pattern/ngmn/coordinates.py

@@ -0,0 +1,129 @@
+# SPDX-License-Identifier: MIT
+# SPDX-FileCopyrightText: 2025-2026 Ericsson
+#
+# Author: Mattia Milani <mattia.milani@ericsson.com>
+#
+# This file is part of eas-3d-pattern and is distributed under the terms of the
+# MIT License. See the LICENSE file at the repository root for the full text,
+# including the warranty disclaimer and redistribution conditions.
+"""NGMN spherical pattern coordinate systems and conversion to the internal frame.
+
+All calculations in this library run in ``SPCS_Ericsson``, which matches
+``SPCS_Polar`` except that phi is defined on [-180, 179]. This module owns the
+per-system transforms into that frame and the post-condition checks that reject
+out-of-spec input.
+
+Split out of ``parser.py`` (Phase 4a of the god-class decomposition, plan
+section 2.1.3).
+"""
+
+from __future__ import annotations
+
+import logging
+
+import numpy as np
+import xarray as xr
+
+from eas_3d_pattern.util_func.guards import verify
+
+logger = logging.getLogger(__name__)
+
+#: Coordinate systems named by the NGMN BASTA specification, plus the internal frame.
+#: Currently informational only — the transform whitelist is ``_TO_ERICSSON``.
+EXPECTED_COORDINATE_SYSTEMS = [
+    "SPCS_Polar",
+    "SPCS_CW",
+    "SPCS_CCW",
+    "SPCS_Geo",
+    "SPCS_Ericsson",
+]
+
+#: The frame every calculation in this library is performed in.
+DEFAULT_INTERNAL_COORD_SYSTEM = "SPCS_Ericsson"
+
+#: Valid theta range of the internal frame, in degrees.
+THETA_RANGE_DEG = (0, 180)
+#: Valid phi range of the internal frame, in degrees.
+PHI_RANGE_DEG = (-180, 179)
+
+# Coordinate transforms into the internal SPCS_Ericsson frame.
+# Each entry maps (theta, phi) arrays -> (theta, phi) arrays. The phi operator
+# (>= vs >) and the leading negation differ per system and are load-bearing:
+# CW/Geo negate the wrapped value, so phi=180 maps consistently to -180 across
+# all four systems. The dict keys also serve as the whitelist of source systems.
+_TO_ERICSSON = {
+    "SPCS_Polar": lambda t, p: (t, np.where(p >= 180, p - 360, p)),
+    "SPCS_CW": lambda t, p: (t + 90, -np.where(p > 180, p - 360, p)),
+    "SPCS_CCW": lambda t, p: (t + 90, np.where(p >= 180, p - 360, p)),
+    "SPCS_Geo": lambda t, p: (np.flip(t), -np.where(p > 180, p - 360, p)),
+}
+
+
+def to_internal_frame(
+    pattern_3d: xr.Dataset,
+    from_system: str,
+    to_system: str,
+) -> xr.Dataset:
+    """Convert the Theta/Phi index of a pattern dataset into the internal frame.
+
+    Args:
+        pattern_3d (xr.Dataset): Pattern dataset indexed by Theta and Phi.
+        from_system (str): Declared source coordinate system.
+        to_system (str): Target system. Only ``SPCS_Ericsson`` is implemented.
+
+    Raises:
+        NotImplementedError: If ``to_system`` is not ``SPCS_Ericsson``.
+        ValueError: If ``from_system`` is not a supported source system, or if the
+            transformed theta/phi fall outside the internal ranges, which means the
+            input was out of spec for the declared system.
+
+    Returns:
+        xr.Dataset: Dataset re-indexed into the internal frame and sorted by Theta, Phi.
+
+    Note:
+        ``SPCS_Ericsson`` uses the same coordinate system as ``SPCS_Polar``, however
+        phi is defined between -180 and 179.
+    """
+    verify(to_system == DEFAULT_INTERNAL_COORD_SYSTEM,
+           f"Antenna Pattern: Change to coordinate system {to_system} not implemented yet. Use the default ({DEFAULT_INTERNAL_COORD_SYSTEM}) for now.",
+           NotImplementedError)
+    transformable_systems = tuple(_TO_ERICSSON)
+    verify(from_system in _TO_ERICSSON,
+           f"AntennaPattern: Unsupported source coordinate system '{from_system}'. Expected one of {transformable_systems}.")
+
+    phi = pattern_3d.coords["Phi"].values
+    theta = pattern_3d.coords["Theta"].values
+    # to_system is guaranteed SPCS_Ericsson by the guard above.
+    new_theta, new_phi = _TO_ERICSSON[from_system](theta, phi)
+    pattern_3d = pattern_3d.assign_coords(
+        Theta=("Theta", new_theta),
+        Phi=("Phi", new_phi),
+    )
+
+    _reject_out_of_range(pattern_3d, from_system)
+
+    pattern_3d = pattern_3d.assign_attrs(
+        coordinate_system=to_system,
+    )
+    return pattern_3d.sortby(["Theta", "Phi"])
+
+
+def _reject_out_of_range(pattern_3d: xr.Dataset, from_system: str) -> None:
+    """Raise if transformed coordinates left the valid internal ranges.
+
+    Args:
+        pattern_3d (xr.Dataset): Dataset already re-indexed into the internal frame.
+        from_system (str): Source system, named in the error for diagnosis.
+
+    Raises:
+        ValueError: If theta or phi fall outside the internal frame's ranges.
+    """
+    theta_min, theta_max = THETA_RANGE_DEG
+    new_theta = pattern_3d.coords["Theta"].values
+    verify(new_theta.min() >= theta_min and new_theta.max() <= theta_max,
+           f"AntennaPattern: Transformed theta out of range [{theta_min}, {theta_max}] ([{new_theta.min()}, {new_theta.max()}]) converting from '{from_system}'. Input data is likely out of spec for that system.")
+
+    phi_min, phi_max = PHI_RANGE_DEG
+    new_phi = pattern_3d.coords["Phi"].values
+    verify(new_phi.min() >= phi_min and new_phi.max() <= phi_max,
+           f"AntennaPattern: Transformed phi out of range [{phi_min}, {phi_max}] ([{new_phi.min()}, {new_phi.max()}]) converting from '{from_system}'. Input data is likely out of spec for that system.")