feat[viz]: fill argument for sim.plot_structures()

Author: yaugenst-flex

CHANGELOG.md

@@ -7,6 +7,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+- `fill` and `fill_structures` argument in `td.Simulation.plot_structures()` and `td.Simulation.plot()` respectively to disable fill and plot outlines of structures only.
+
 ## [2.8.1] - 2025-03-20
 
 ### Added

tests/test_components/test_viz.py

@@ -1,14 +1,26 @@
 """Tests visualization operations."""
 
+import matplotlib as mpl
 import matplotlib.pyplot as plt
 import pydantic.v1 as pd
 import pytest
 import tidy3d as td
+from tidy3d import Box, Medium, Simulation, Structure
 from tidy3d.components.viz import Polygon, set_default_labels_and_title
 from tidy3d.constants import inf
 from tidy3d.exceptions import Tidy3dKeyError
 
 
+@pytest.fixture(scope="module", autouse=True)
+def mpl_config():
+    """Configure matplotlib non-interactive backend for all tests in this module."""
+    original_backend = mpl.get_backend()
+    mpl.use("Agg")
+    yield
+    plt.close("all")
+    mpl.use(original_backend)
+
+
 def test_make_polygon_dict():
     p = Polygon(context={"coordinates": [(1, 0), (0, 1), (0, 0)]})
     p.interiors
@@ -38,8 +50,6 @@ def test_0d_plot(center_z, len_collections):
     # if a point is plotted, a single collection will be present, otherwise nothing
     assert len(ax.collections) == len_collections
 
-    plt.close()
-
 
 def test_2d_boundary_plot():
     """
@@ -102,8 +112,6 @@ def test_set_default_labels_title():
             axis_labels=axis_labels, axis=2, position=0, ax=ax, plot_length_units="inches"
         )
 
-    plt.close()
-
 
 def test_make_viz_spec():
     """
@@ -144,7 +152,6 @@ def test_plot_from_structure():
     structure = td.Structure(geometry=geometry, medium=medium)
 
     structure.plot(z=0)
-    plt.close()
 
 
 def test_plot_from_simulation():
@@ -158,7 +165,6 @@ def test_plot_from_simulation():
     )
 
     refine_box.plot(z=0)
-    plt.close()
 
 
 def plot_with_viz_spec(alpha, facecolor, edgecolor=None, use_viz_spec=True):
@@ -263,3 +269,59 @@ def test_plot_multi_from_structure_local(rng):
         rng=rng,
         use_viz_spec=False,
     )
+
+
+def test_sim_plot_fill_structures():
+    """Test fill_structures in Simulation.plot()"""
+    box = Box(size=(1, 1, 1))
+    struct = Structure(geometry=box, medium=Medium(permittivity=2.0))
+    sim = Simulation(
+        size=(2, 2, 2),
+        structures=[struct],
+        grid_spec=td.GridSpec(wavelength=1.0),
+        run_time=1e-12,
+    )
+
+    fig1, ax1 = plt.subplots()
+    sim.plot(x=0, fill_structures=False, ax=ax1)
+    structure_patches = [p for p in ax1.patches if isinstance(p, mpl.patches.PathPatch)]
+    for patch in structure_patches[:1]:  # only one structure, rest is PML etc
+        assert not patch.get_fill(), "Should be unfilled when False"
+        assert patch.get_edgecolor() != "none"
+
+    fig2, ax2 = plt.subplots()
+    sim.plot(x=0, fill_structures=True, ax=ax2)
+    structure_patches = [p for p in ax2.patches if isinstance(p, mpl.patches.PathPatch)]
+    for patch in structure_patches[:1]:
+        assert patch.get_fill(), "Should be filled when True"
+
+
+def test_sim_plot_structures_fill():
+    """Test fill_structures in Simulation.plot_structures()"""
+    box = Box(size=(1, 1, 1))
+    struct = Structure(geometry=box, medium=Medium(permittivity=2.0))
+    sim = Simulation(
+        size=(2, 2, 2),
+        structures=[struct],
+        grid_spec=td.GridSpec(wavelength=1.0),
+        run_time=1e-12,
+    )
+
+    fig1, ax1 = plt.subplots()
+    sim.plot_structures(x=0, fill=False, ax=ax1)
+    structure_patches = [p for p in ax1.patches if isinstance(p, mpl.patches.PathPatch)]
+    assert len(structure_patches) > 0, "No structures plotted"
+
+    for patch in structure_patches[:1]:
+        assert not patch.get_fill(), "Should be unfilled when False"
+        assert patch.get_edgecolor() != "none", "Edges should be visible"
+        assert patch.get_linewidth() > 0, "Edge width should be positive"
+
+    fig2, ax2 = plt.subplots()
+    sim.plot_structures(x=0, fill=True, ax=ax2)
+    structure_patches = [p for p in ax2.patches if isinstance(p, mpl.patches.PathPatch)]
+    assert len(structure_patches) > 0, "No structures plotted"
+
+    for patch in structure_patches[:1]:
+        assert patch.get_fill(), "Should be filled when True"
+        assert patch.get_facecolor() != "none", "Face color should be set"

tidy3d/components/base_sim/simulation.py

@@ -228,6 +228,7 @@ def plot(
         monitor_alpha: float = None,
         hlim: Tuple[float, float] = None,
         vlim: Tuple[float, float] = None,
+        fill_structures: bool = True,
         **patch_kwargs,
     ) -> Ax:
         """Plot each of simulation's components on a plane defined by one nonzero x,y,z coordinate.
@@ -250,7 +251,8 @@ def plot(
             The x range if plotting on xy or xz planes, y range if plotting on yz plane.
         vlim : Tuple[float, float] = None
             The z range if plotting on xz or yz planes, y plane if plotting on xy plane.
-
+        fill_structures : bool = True
+            Whether to fill structures with color or just draw outlines.
         Returns
         -------
         matplotlib.axes._subplots.Axes
@@ -261,7 +263,9 @@ def plot(
             bounds=self.simulation_bounds, x=x, y=y, z=z, hlim=hlim, vlim=vlim
         )
 
-        ax = self.scene.plot_structures(ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim)
+        ax = self.scene.plot_structures(
+            ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim, fill=fill_structures
+        )
         ax = self.plot_sources(ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim, alpha=source_alpha)
         ax = self.plot_monitors(ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim, alpha=monitor_alpha)
         ax = Scene._set_plot_bounds(
@@ -492,6 +496,7 @@ def plot_structures(
         ax: Ax = None,
         hlim: Tuple[float, float] = None,
         vlim: Tuple[float, float] = None,
+        fill: bool = True,
     ) -> Ax:
         """Plot each of simulation's structures on a plane defined by one nonzero x,y,z coordinate.
 
@@ -509,7 +514,8 @@ def plot_structures(
             The x range if plotting on xy or xz planes, y range if plotting on yz plane.
         vlim : Tuple[float, float] = None
             The z range if plotting on xz or yz planes, y plane if plotting on xy plane.
-
+        fill : bool = True
+            Whether to fill structures with color or just draw outlines.
         Returns
         -------
         matplotlib.axes._subplots.Axes
@@ -520,7 +526,9 @@ def plot_structures(
             bounds=self.simulation_bounds, x=x, y=y, z=z, hlim=hlim, vlim=vlim
         )
 
-        return self.scene.plot_structures(x=x, y=y, z=z, ax=ax, hlim=hlim_new, vlim=vlim_new)
+        return self.scene.plot_structures(
+            x=x, y=y, z=z, ax=ax, hlim=hlim_new, vlim=vlim_new, fill=fill
+        )
 
     @equal_aspect
     @add_ax_if_none

tidy3d/components/scene.py

@@ -372,6 +372,7 @@ def plot(
         ax: Ax = None,
         hlim: Tuple[float, float] = None,
         vlim: Tuple[float, float] = None,
+        fill_structures: bool = True,
         **patch_kwargs,
     ) -> Ax:
         """Plot each of scene's components on a plane defined by one nonzero x,y,z coordinate.
@@ -390,6 +391,8 @@ def plot(
             The x range if plotting on xy or xz planes, y range if plotting on yz plane.
         vlim : Tuple[float, float] = None
             The z range if plotting on xz or yz planes, y plane if plotting on xy plane.
+        fill_structures : bool = True
+            Whether to fill structures with color or just draw outlines.
 
         Returns
         -------
@@ -399,7 +402,7 @@ def plot(
 
         hlim, vlim = Scene._get_plot_lims(bounds=self.bounds, x=x, y=y, z=z, hlim=hlim, vlim=vlim)
 
-        ax = self.plot_structures(ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim)
+        ax = self.plot_structures(ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim, fill=fill_structures)
         ax = self._set_plot_bounds(bounds=self.bounds, ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim)
         return ax
 
@@ -413,6 +416,7 @@ def plot_structures(
         ax: Ax = None,
         hlim: Tuple[float, float] = None,
         vlim: Tuple[float, float] = None,
+        fill: bool = True,
     ) -> Ax:
         """Plot each of scene's structures on a plane defined by one nonzero x,y,z coordinate.
 
@@ -430,6 +434,8 @@ def plot_structures(
             The x range if plotting on xy or xz planes, y range if plotting on yz plane.
         vlim : Tuple[float, float] = None
             The z range if plotting on xz or yz planes, y plane if plotting on xy plane.
+        fill : bool = True
+            Whether to fill structures with color or just draw outlines.
 
         Returns
         -------
@@ -443,7 +449,13 @@ def plot_structures(
         medium_map = self.medium_map
         for medium, shape in medium_shapes:
             mat_index = medium_map[medium]
-            ax = self._plot_shape_structure(medium=medium, mat_index=mat_index, shape=shape, ax=ax)
+            ax = self._plot_shape_structure(
+                medium=medium,
+                mat_index=mat_index,
+                shape=shape,
+                ax=ax,
+                fill=fill,
+            )
 
         # clean up the axis display
         axis, _ = Box.parse_xyz_kwargs(x=x, y=y, z=z)
@@ -456,15 +468,27 @@ def plot_structures(
         return ax
 
     def _plot_shape_structure(
-        self, medium: MultiPhysicsMediumType3D, mat_index: int, shape: Shapely, ax: Ax
+        self,
+        medium: MultiPhysicsMediumType3D,
+        mat_index: int,
+        shape: Shapely,
+        ax: Ax,
+        fill: bool = True,
     ) -> Ax:
         """Plot a structure's cross section shape for a given medium."""
-        plot_params_struct = self._get_structure_plot_params(medium=medium, mat_index=mat_index)
+        plot_params_struct = self._get_structure_plot_params(
+            medium=medium,
+            mat_index=mat_index,
+            fill=fill,
+        )
         ax = self.box.plot_shape(shape=shape, plot_params=plot_params_struct, ax=ax)
         return ax
 
     def _get_structure_plot_params(
-        self, mat_index: int, medium: MultiPhysicsMediumType3D
+        self,
+        mat_index: int,
+        medium: MultiPhysicsMediumType3D,
+        fill: bool = True,
     ) -> PlotParams:
         """Constructs the plot parameters for a given medium in scene.plot()."""
 
@@ -508,6 +532,11 @@ def _get_structure_plot_params(
                 if medium.viz_spec is not None:
                     plot_params = plot_params.override_with_viz_spec(medium.viz_spec)
 
+        if not fill:
+            plot_params = plot_params.copy(update={"fill": False})
+            if plot_params.linewidth == 0:
+                plot_params = plot_params.copy(update={"linewidth": 1})
+
         return plot_params
 
     @staticmethod

tidy3d/components/simulation.py

@@ -385,12 +385,15 @@ def plot(
         lumped_element_alpha: float = None,
         hlim: Tuple[float, float] = None,
         vlim: Tuple[float, float] = None,
+        fill_structures: bool = True,
         **patch_kwargs,
     ) -> Ax:
         """Plot each of simulation's components on a plane defined by one nonzero x,y,z coordinate.
 
         Parameters
         ----------
+        fill_structures : bool = True
+            Whether to fill structures with color or just draw outlines.
         x : float = None
             position of plane in x direction, only one of x, y, z must be specified to define plane.
         y : float = None
@@ -426,7 +429,16 @@ def plot(
             bounds=self.simulation_bounds, x=x, y=y, z=z, hlim=hlim, vlim=vlim
         )
 
-        ax = self.plot_structures(ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim)
+        ax = self.scene.plot(
+            x=x,
+            y=y,
+            z=z,
+            ax=ax,
+            hlim=hlim,
+            vlim=vlim,
+            fill_structures=fill_structures,
+        )
+
         ax = self.plot_sources(ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim, alpha=source_alpha)
         ax = self.plot_monitors(ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim, alpha=monitor_alpha)
         ax = self.plot_lumped_elements(
@@ -438,6 +450,7 @@ def plot(
             bounds=self.simulation_bounds, ax=ax, x=x, y=y, z=z, hlim=hlim, vlim=vlim
         )
         ax = self.plot_boundaries(ax=ax, x=x, y=y, z=z)
+
         return ax
 
     @equal_aspect