gammasimtools 0.24.0__py3-none-any.whl → 0.26.0__py3-none-any.whl

simtools/visualization/legend_handlers.py

@@ -1,22 +1,29 @@
 """Helper functions for legend handlers used for plotting."""
 
+# pylint: disable=too-few-public-methods
+
 import matplotlib.colors as mcolors
 import matplotlib.patches as mpatches
 import numpy as np
 
-"""
-Define properties of different telescope types for visualization purposes.
-
-Radii are relative to a reference radius (REFERENCE_RADIUS).
-"""
+# Define properties of different telescope types for visualization purposes.
+# Radii are relative to a reference radius (REFERENCE_RADIUS).
 TELESCOPE_CONFIG = {
     "LST": {"color": "darkorange", "radius": 12.5, "shape": "circle", "filled": False},
-    "MST": {"color": "dodgerblue", "radius": 9.15, "shape": "circle", "filled": True},
-    "SCT": {"color": "black", "radius": 7.15, "shape": "square", "filled": True},
-    "SST": {"color": "darkgreen", "radius": 3.0, "shape": "circle", "filled": True},
+    "MST": {"color": "dodgerblue", "radius": 9.15, "shape": "circle", "filled": False},
+    "SCT": {"color": "black", "radius": 7.15, "shape": "square", "filled": False},
+    "SST": {"color": "darkgreen", "radius": 3.0, "shape": "circle", "filled": False},
     "HESS": {"color": "grey", "radius": 6.0, "shape": "hexagon", "filled": True},
     "MAGIC": {"color": "grey", "radius": 8.5, "shape": "hexagon", "filled": True},
     "VERITAS": {"color": "grey", "radius": 6.0, "shape": "hexagon", "filled": True},
+    "CEI": {"color": "purple", "radius": 2.0, "shape": "hexagon", "filled": True},
+    "RLD": {"color": "brown", "radius": 2.0, "shape": "hexagon", "filled": True},
+    "STP": {"color": "olive", "radius": 2.0, "shape": "hexagon", "filled": True},
+    "MSP": {"color": "teal", "radius": 2.0, "shape": "hexagon", "filled": True},
+    "ILL": {"color": "red", "radius": 2.0, "shape": "hexagon", "filled": False},
+    "WST": {"color": "maroon", "radius": 2.0, "shape": "hexagon", "filled": True},
+    "ASC": {"color": "cyan", "radius": 2.0, "shape": "hexagon", "filled": True},
+    "DUS": {"color": "magenta", "radius": 2.0, "shape": "hexagon", "filled": True},
 }
 
 REFERENCE_RADIUS = 12.5
@@ -30,7 +37,7 @@ def get_telescope_config(telescope_type):
 
     Parameters
     ----------
-    telescope_type : str
+    telescope_type : str, None
         The type of the telescope (e.g., "LSTN", "MSTS").
 
     Returns
@@ -38,10 +45,12 @@ def get_telescope_config(telescope_type):
     dict
         The configuration dictionary for the telescope type.
     """
+    if telescope_type is None:
+        return {"color": "blue", "radius": 2.0, "shape": "hexagon", "filled": True}
     config = TELESCOPE_CONFIG.get(telescope_type)
     if not config and len(telescope_type) >= 3:
         config = TELESCOPE_CONFIG.get(telescope_type[:3])
-    return config
+    return config.copy() if config else None
 
 
 def calculate_center(handlebox, width_factor=3, height_factor=3):
@@ -262,6 +271,8 @@ class BaseLegendHandler:
             x0, y0 = calculate_center(handlebox)
             radius = handlebox.height
             patch = self._create_hexagon(handlebox, x0, y0, radius)
+        else:
+            raise ValueError(f"Unknown shape: {shape}")
 
         handlebox.add_artist(patch)
         return patch

simtools/visualization/plot_array_layout.py

@@ -2,16 +2,91 @@
 """Plot array elements for a layout."""
 
 from collections import Counter
+from typing import NamedTuple
 
 import astropy.units as u
+import matplotlib as mpl
 import matplotlib.patches as mpatches
 import matplotlib.pyplot as plt
+import numpy as np
+from adjustText import adjust_text
 from astropy.table import Column
 from matplotlib.collections import PatchCollection
 
 from simtools.utils import geometry as transf
 from simtools.utils import names
 from simtools.visualization import legend_handlers as leg_h
+from simtools.visualization import visualize
+
+
+class PlotBounds(NamedTuple):
+    """Axis-aligned bounds for the layout in meters.
+
+    Attributes
+    ----------
+    x_lim : tuple[float, float]
+        Min/max for x (meters).
+    y_lim : tuple[float, float]
+        Min/max for y (meters).
+    """
+
+    x_lim: tuple[float, float]
+    y_lim: tuple[float, float]
+
+
+def plot_array_layouts(args_dict, output_path, layouts, background_layout=None):
+    """
+    Plot multiple array layouts.
+
+    Parameters
+    ----------
+    args_dict : dict
+        Application arguments.
+    output_path : Path
+        Output path for figures.
+    layouts : dict
+        Dictionary of layout name to telescope table.
+    background_layout : Table or None
+        Optional background telescope table.
+
+    Returns
+    -------
+    figs : dict
+        Dictionary of layout name to matplotlib figure object.
+
+    """
+    mpl.use("Agg")
+    for layout in layouts:
+        fig_out = plot_array_layout(
+            telescopes=layout["array_elements"],
+            show_tel_label=args_dict["show_labels"],
+            axes_range=args_dict["axes_range"],
+            marker_scaling=args_dict["marker_scaling"],
+            background_telescopes=background_layout,
+            grayed_out_elements=args_dict["grayed_out_array_elements"],
+            highlighted_elements=args_dict["highlighted_array_elements"],
+            legend_location=args_dict["legend_location"],
+            bounds_mode=args_dict["bounds"],
+            padding=args_dict["padding"],
+            x_lim=tuple(args_dict["x_lim"]) if args_dict["x_lim"] else None,
+            y_lim=tuple(args_dict["y_lim"]) if args_dict["y_lim"] else None,
+        )
+        site_string = ""
+        if layout.get("site") is not None:
+            site_string = f"_{layout['site']}"
+        elif args_dict["site"] is not None:
+            site_string = f"_{args_dict['site']}"
+        coordinate_system_string = (
+            f"_{args_dict['coordinate_system']}"
+            if args_dict["coordinate_system"] not in layout["name"]
+            else ""
+        )
+        plot_file_name = args_dict["figure_name"] or (
+            f"array_layout_{layout['name']}{site_string}{coordinate_system_string}"
+        )
+
+        visualize.save_figure(fig_out, output_path / plot_file_name, dpi=400)
+        plt.close()
 
 
 def plot_array_layout(
@@ -23,6 +98,10 @@ def plot_array_layout(
     grayed_out_elements=None,
     highlighted_elements=None,
     legend_location="best",
+    bounds_mode="exact",
+    padding=0.1,
+    x_lim=None,
+    y_lim=None,
 ):
     """
     Plot telescope array layout.
@@ -50,10 +129,25 @@ def plot_array_layout(
     -------
     fig : Figure
         Matplotlib figure object.
+
+    Other Parameters
+    ----------------
+    bounds_mode : {"symmetric", "exact"}
+        Controls axis limits calculation. "symmetric" uses +-R where R is the padded
+        maximum extent (default), while "exact" uses individual x/y min/max bounds.
+    padding : float
+        Fractional padding applied around computed extents (used for both modes).
+    x_lim, y_lim : tuple(float, float), optional
+        Explicit axis limits in meters. If provided, these override axes_range and bounds_mode
+        for the respective axis. If only one is provided, the other axis is derived per mode.
     """
     fig, ax = plt.subplots(1)
 
-    patches, plot_range, highlighted_patches = get_patches(
+    # If explicit limits are provided (one or both), filter patches accordingly
+    filter_x = x_lim
+    filter_y = y_lim
+
+    patches, plot_range, highlighted_patches, bounds, text_objects = get_patches(
         ax,
         telescopes,
         show_tel_label,
@@ -61,20 +155,145 @@ def plot_array_layout(
         marker_scaling,
         grayed_out_elements,
         highlighted_elements,
+        filter_x_lim=filter_x,
+        filter_y_lim=filter_y,
+    )
+
+    plot_range, bounds = _get_patches_for_background_telescopes(
+        ax,
+        background_telescopes,
+        axes_range,
+        marker_scaling,
+        bounds_mode,
+        plot_range,
+        bounds,
+        filter_x_lim=filter_x,
+        filter_y_lim=filter_y,
+    )
+
+    if legend_location != "no_legend":
+        update_legend(ax, telescopes, grayed_out_elements, legend_location)
+
+    x_lim, y_lim = _get_axis_limits(
+        axes_range, bounds_mode, padding, plot_range, bounds, x_lim, y_lim
     )
 
-    if background_telescopes is not None:
-        bg_patches, bg_range, _ = get_patches(
-            ax, background_telescopes, False, axes_range, marker_scaling
+    finalize_plot(ax, patches, "Easting [m]", "Northing [m]", x_lim, y_lim, highlighted_patches)
+
+    if text_objects:
+        adjust_text(
+            text_objects,
+            ax=ax,
+            arrowprops={"arrowstyle": "->", "color": "grey", "alpha": 0.8, "lw": 0.8, "ls": "--"},
+            expand=(2.0, 2.0),
+            prevent_crossings=True,
+            min_arrow_len=8,
+            ensure_inside_axes=True,
         )
-        ax.add_collection(PatchCollection(bg_patches, match_original=True, alpha=0.1))
-        if axes_range is None:
+
+    return fig
+
+
+def _get_axis_limits(
+    axes_range,
+    bounds_mode,
+    padding,
+    plot_range,
+    bounds,
+    x_lim_override=None,
+    y_lim_override=None,
+):
+    """Get axis limits based on mode and padding."""
+
+    def _derive_axis(axis: str) -> tuple[float, float]:
+        if bounds_mode == "exact":
+            if axis == "x":
+                span = bounds.x_lim[1] - bounds.x_lim[0]
+                pad = padding * span
+                return (bounds.x_lim[0] - pad, bounds.x_lim[1] + pad)
+            span = bounds.y_lim[1] - bounds.y_lim[0]
+            pad = padding * span
+            return (bounds.y_lim[0] - pad, bounds.y_lim[1] + pad)
+        # symmetric
+        sym = plot_range
+        padf = max(0.0, min(1.0, float(padding))) if padding is not None else 0.0
+        sym *= 1.0 + padf
+        return (-sym, sym)
+
+    # Highest priority: explicit overrides (per axis)
+    if x_lim_override is not None or y_lim_override is not None:
+        x_lim = x_lim_override if x_lim_override is not None else _derive_axis("x")
+        y_lim = y_lim_override if y_lim_override is not None else _derive_axis("y")
+        return x_lim, y_lim
+
+    if axes_range is not None:
+        return (-axes_range, axes_range), (-axes_range, axes_range)
+    # Derive both axes using selected mode
+    return _derive_axis("x"), _derive_axis("y")
+
+
+def _get_patches_for_background_telescopes(
+    ax,
+    background_telescopes,
+    axes_range,
+    marker_scaling,
+    bounds_mode,
+    plot_range,
+    bounds,
+    filter_x_lim=None,
+    filter_y_lim=None,
+):
+    """Get background telescope patches and update plot range/bounds."""
+    if background_telescopes is None:
+        return plot_range, bounds
+
+    bg_patches, bg_range, _, bg_bounds, _ = get_patches(
+        ax,
+        background_telescopes,
+        False,
+        axes_range,
+        marker_scaling,
+        None,
+        None,
+        filter_x_lim=filter_x_lim,
+        filter_y_lim=filter_y_lim,
+    )
+    ax.add_collection(PatchCollection(bg_patches, match_original=True, alpha=0.1))
+    if axes_range is None:
+        if bounds_mode == "symmetric":
             plot_range = max(plot_range, bg_range)
+        else:
+            bounds = PlotBounds(
+                x_lim=(
+                    min(bounds.x_lim[0], bg_bounds.x_lim[0]),
+                    max(bounds.x_lim[1], bg_bounds.x_lim[1]),
+                ),
+                y_lim=(
+                    min(bounds.y_lim[0], bg_bounds.y_lim[0]),
+                    max(bounds.y_lim[1], bg_bounds.y_lim[1]),
+                ),
+            )
+    return plot_range, bounds
 
-    update_legend(ax, telescopes, grayed_out_elements, legend_location)
-    finalize_plot(ax, patches, "Easting [m]", "Northing [m]", plot_range, highlighted_patches)
 
-    return fig
+def _apply_limits_filter(telescopes, pos_x, pos_y, filter_x_lim, filter_y_lim):
+    """Filter telescope table and positions by optional axis limits."""
+    if filter_x_lim is None and filter_y_lim is None:
+        return telescopes, pos_x, pos_y
+
+    px = np.asarray(pos_x.to_value(u.m))
+    py = np.asarray(pos_y.to_value(u.m))
+    mask = np.ones(px.shape, dtype=bool)
+    if filter_x_lim is not None:
+        mask &= (px >= float(filter_x_lim[0])) & (px <= float(filter_x_lim[1]))
+    if filter_y_lim is not None:
+        mask &= (py >= float(filter_y_lim[0])) & (py <= float(filter_y_lim[1]))
+
+    if mask.size and mask.any():
+        return telescopes[mask], pos_x[mask], pos_y[mask]
+
+    # No telescopes within limits
+    return telescopes[:0], pos_x[:0], pos_y[:0]
 
 
 def get_patches(
@@ -85,6 +304,8 @@ def get_patches(
     marker_scaling,
     grayed_out_elements=None,
     highlighted_elements=None,
+    filter_x_lim=None,
+    filter_y_lim=None,
 ):
     """
     Get plot patches and axis range.
@@ -111,38 +332,63 @@ def get_patches(
     patches : list
         List of telescope patches.
     axes_range : float
-        Calculated or input axis range.
+        Calculated or input symmetric axis range (meters).
     highlighted_patches : list
         List of highlighted telescope patches.
+    bounds : PlotBounds
+        Min/max for x and y in meters.
+    text_objects : list
+        List of text objects for labels.
     """
     pos_x, pos_y = get_positions(telescopes)
-    telescopes["pos_x_rotated"] = Column(pos_x)
-    telescopes["pos_y_rotated"] = Column(pos_y)
+    tel_table, pos_x, pos_y = _apply_limits_filter(
+        telescopes, pos_x, pos_y, filter_x_lim, filter_y_lim
+    )
+
+    tel_table["pos_x_rotated"] = Column(pos_x)
+    tel_table["pos_y_rotated"] = Column(pos_y)
 
-    patches, radii, highlighted_patches = create_patches(
-        telescopes, marker_scaling, show_tel_label, ax, grayed_out_elements, highlighted_elements
+    patches, radii, highlighted_patches, text_objects = create_patches(
+        tel_table, marker_scaling, show_tel_label, ax, grayed_out_elements, highlighted_elements
     )
 
+    if len(radii) == 0:
+        r = 0.0
+    else:
+        radii_q = u.Quantity(radii)
+        r = float(np.nanmax(radii_q).to_value(u.m))
+
+    if len(pos_x) == 0:
+        bounds = PlotBounds(x_lim=(0.0, 0.0), y_lim=(0.0, 0.0))
+        if axes_range:
+            return patches, axes_range, highlighted_patches, bounds, text_objects
+        return patches, 0.0, highlighted_patches, bounds, text_objects
+
+    x_min = float(np.nanmin(pos_x).to_value(u.m)) - r
+    x_max = float(np.nanmax(pos_x).to_value(u.m)) + r
+    y_min = float(np.nanmin(pos_y).to_value(u.m)) - r
+    y_max = float(np.nanmax(pos_y).to_value(u.m)) + r
+    bounds = PlotBounds(x_lim=(x_min, x_max), y_lim=(y_min, y_max))
+
     if axes_range:
-        return patches, axes_range, highlighted_patches
+        return patches, axes_range, highlighted_patches, bounds, text_objects
 
-    r = max(radii).value
-    max_x = max(abs(pos_x.min().value), abs(pos_x.max().value)) + r
-    max_y = max(abs(pos_y.min().value), abs(pos_y.max().value)) + r
+    max_x = max(abs(x_min), abs(x_max))
+    max_y = max(abs(y_min), abs(y_max))
     updated_axes_range = max(max_x, max_y) * 1.1
 
-    return patches, updated_axes_range, highlighted_patches
+    return patches, updated_axes_range, highlighted_patches, bounds, text_objects
 
 
 @u.quantity_input(x=u.m, y=u.m, radius=u.m)
-def get_telescope_patch(name, x, y, radius, is_grayed_out=False):
+def get_telescope_patch(tel_type, x, y, radius, is_grayed_out=False):
     """
     Create patch for a telescope.
 
     Parameters
     ----------
-    name : str
-        Telescope name.
+    tel_type: str
+        Telescope type.
     x : Quantity
         X position.
     y : Quantity
@@ -157,24 +403,34 @@ def get_telescope_patch(name, x, y, radius, is_grayed_out=False):
     patch : Patch
         Circle or rectangle patch.
     """
-    tel_type = names.get_array_element_type_from_name(name)
+    config = leg_h.get_telescope_config(tel_type)
     x, y, r = x.to(u.m), y.to(u.m), radius.to(u.m)
 
-    color = "gray" if is_grayed_out else leg_h.get_telescope_config(tel_type)["color"]
+    color = "gray" if is_grayed_out else config["color"]
+    fill_flag = True if is_grayed_out else bool(config.get("filled", True))
 
-    if tel_type == "SCTS":
+    if config.get("shape", "circle") == "square":
         return mpatches.Rectangle(
             ((x - r / 2).value, (y - r / 2).value),
             width=r.value,
             height=r.value,
-            fill=is_grayed_out,
+            fill=fill_flag,
+            color=color,
+        )
+    if config.get("shape") == "hexagon":
+        return mpatches.RegularPolygon(
+            (x.value, y.value),
+            numVertices=6,
+            radius=r.value * np.sqrt(3) / 2,
+            orientation=np.pi / 6,
+            fill=fill_flag,
             color=color,
         )
 
     return mpatches.Circle(
         (x.value, y.value),
         radius=r.value,
-        fill=is_grayed_out or tel_type.startswith("MST"),
+        fill=fill_flag,
         alpha=0.5 if is_grayed_out else 1.0,
         color=color,
     )
@@ -232,8 +488,10 @@ def create_patches(
         Telescope radii.
     highlighted_patches : list
         List of highlighted telescope patches.
+    text_objects : list
+        List of text objects for labels.
     """
-    patches, radii, highlighted_patches = [], [], []
+    patches, radii, highlighted_patches, text_objects = [], [], [], []
     fontsize, scale_factor = (4, 2) if len(telescopes) > 30 else (8, 1)
 
     grayed_out_set = set(grayed_out_elements) if grayed_out_elements else set()
@@ -243,7 +501,10 @@ def create_patches(
         name = get_telescope_name(tel)
         radius = get_sphere_radius(tel)
         radii.append(radius)
-        tel_type = names.get_array_element_type_from_name(name)
+        try:
+            tel_type = names.get_array_element_type_from_name(name)
+        except ValueError:
+            tel_type = None
 
         is_grayed_out = name in grayed_out_set
         is_highlighted = name in highlighted_set
@@ -269,16 +530,18 @@ def create_patches(
             highlighted_patches.append(highlight_patch)
 
         if show_label:
-            ax.text(
-                tel["pos_x_rotated"].value,
-                tel["pos_y_rotated"].value + scale_factor * radius.value,
-                name,
-                ha="center",
-                va="bottom",
-                fontsize=fontsize,
+            text_objects.append(
+                ax.text(
+                    tel["pos_x_rotated"].value,
+                    tel["pos_y_rotated"].value + scale_factor * radius.value,
+                    name,
+                    ha="center",
+                    va="center",
+                    fontsize=fontsize * 0.8,
+                )
             )
 
-    return patches, radii, highlighted_patches
+    return patches, radii, highlighted_patches, text_objects
 
 
 def get_telescope_name(tel):
@@ -344,7 +607,15 @@ def update_legend(ax, telescopes, grayed_out_elements=None, legend_location="bes
     ax.legend(objs, labels, handler_map=handler_map, prop={"size": 11}, loc=legend_location)
 
 
-def finalize_plot(ax, patches, x_title, y_title, axes_range, highlighted_patches=None):
+def finalize_plot(
+    ax,
+    patches,
+    x_title,
+    y_title,
+    x_lim=None,
+    y_lim=None,
+    highlighted_patches=None,
+):
     """Finalize plot appearance and limits."""
     ax.add_collection(PatchCollection(patches, match_original=True))
 
@@ -354,7 +625,7 @@ def finalize_plot(ax, patches, x_title, y_title, axes_range, highlighted_patches
     ax.set(xlabel=x_title, ylabel=y_title)
     ax.tick_params(labelsize=8)
     ax.axis("square")
-    if axes_range:
-        ax.set_xlim(-axes_range, axes_range)
-        ax.set_ylim(-axes_range, axes_range)
+    if x_lim is not None and y_lim is not None:
+        ax.set_xlim(*x_lim)
+        ax.set_ylim(*y_lim)
     plt.tight_layout()