lsurf 1.0.0__py3-none-any.whl

lsurf/cli/interactive.py

@@ -0,0 +1,850 @@
+# The Clear BSD License
+#
+# Copyright (c) 2026 Tobias Heibges
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted (subject to the limitations in the disclaimer
+# below) provided that the following conditions are met:
+#
+#      * Redistributions of source code must retain the above copyright notice,
+#      this list of conditions and the following disclaimer.
+#
+#      * Redistributions in binary form must reproduce the above copyright
+#      notice, this list of conditions and the following disclaimer in the
+#      documentation and/or other materials provided with the distribution.
+#
+#      * Neither the name of the copyright holder nor the names of its
+#      contributors may be used to endorse or promote products derived from this
+#      software without specific prior written permission.
+#
+# NO EXPRESS OR IMPLIED LICENSES TO ANY PARTY'S PATENT RIGHTS ARE GRANTED BY
+# THIS LICENSE. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
+# CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
+# PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
+# BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER
+# IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""Interactive wizard helpers for L-SURF CLI.
+
+This module provides questionary-based interactive prompts for building
+geometry configurations step-by-step.
+"""
+
+from typing import Any
+
+import questionary
+from questionary import Style
+
+from .config_schema import (
+    DetectorConfig,
+    LSURFConfig,
+    MediaConfig,
+    OutputConfig,
+    SourceConfig,
+    SurfaceConfig,
+)
+from ..simulation import SimulationConfig
+
+# Custom style for questionary prompts
+LSURF_STYLE = Style(
+    [
+        ("qmark", "fg:cyan bold"),
+        ("question", "bold"),
+        ("answer", "fg:green"),
+        ("pointer", "fg:cyan bold"),
+        ("highlighted", "fg:cyan bold"),
+        ("selected", "fg:green"),
+        ("separator", "fg:gray"),
+        ("instruction", "fg:gray"),
+    ]
+)
+
+
+# =============================================================================
+# Pre-built Templates
+# =============================================================================
+
+TEMPLATES: dict[str, dict[str, Any]] = {
+    "ocean": {
+        "description": "Ocean surface reflection with exponential atmosphere",
+        "config": {
+            "version": "1.0",
+            "media": {
+                "atmosphere": {
+                    "type": "exponential_atmosphere",
+                    "params": {"scale_height": 8500.0, "n_sea_level": 1.000293},
+                },
+                "ocean": {"type": "water", "params": {}},
+            },
+            "background": "atmosphere",
+            "source": {
+                "type": "collimated_beam",
+                "params": {
+                    "center": [0.0, 0.0, 100000.0],
+                    "direction": [0.0, 0.0, -1.0],
+                    "beam_radius": 0.005,
+                    "num_rays": 100000,
+                    "wavelength": 532e-9,
+                },
+            },
+            "surfaces": [
+                {
+                    "name": "ocean_surface",
+                    "type": "curved_wave",
+                    "role": "optical",
+                    "front_medium": "atmosphere",
+                    "back_medium": "ocean",
+                    "params": {
+                        "amplitude": 0.5,
+                        "wavelength": 100.0,
+                        "direction": [1.0, 0.0],
+                        "earth_center": [0.0, 0.0, -6.371e6],
+                        "earth_radius": 6.371e6,
+                    },
+                }
+            ],
+            "detectors": [
+                {
+                    "name": "sky_detector",
+                    "type": "recording_sphere",
+                    "params": {"center": [0.0, 0.0, -6.371e6], "radius": 6.404e6},
+                }
+            ],
+            "simulation": {
+                "step_size": 100.0,
+                "max_bounces": 1,
+                "polarization": "unpolarized",
+                "use_gpu": True,
+            },
+            "output": {"directory": "./results", "format": "hdf5"},
+        },
+    },
+    "glass": {
+        "description": "Light passing through a glass plate",
+        "config": {
+            "version": "1.0",
+            "media": {
+                "air": {"type": "air", "params": {}},
+                "glass": {"type": "glass", "params": {"refractive_index": 1.5168}},
+            },
+            "background": "air",
+            "source": {
+                "type": "collimated_beam",
+                "params": {
+                    "center": [0.0, 0.0, -0.1],
+                    "direction": [0.0, 0.0, 1.0],
+                    "beam_radius": 0.01,
+                    "num_rays": 10000,
+                    "wavelength": 632.8e-9,
+                },
+            },
+            "surfaces": [
+                {
+                    "name": "front_surface",
+                    "type": "plane",
+                    "role": "optical",
+                    "front_medium": "air",
+                    "back_medium": "glass",
+                    "params": {"point": [0.0, 0.0, 0.0], "normal": [0.0, 0.0, -1.0]},
+                },
+                {
+                    "name": "back_surface",
+                    "type": "plane",
+                    "role": "optical",
+                    "front_medium": "glass",
+                    "back_medium": "air",
+                    "params": {"point": [0.0, 0.0, 0.01], "normal": [0.0, 0.0, -1.0]},
+                },
+            ],
+            "detectors": [
+                {
+                    "name": "detector",
+                    "type": "planar",
+                    "params": {
+                        "center": [0.0, 0.0, 0.1],
+                        "normal": [0.0, 0.0, -1.0],
+                        "width": 0.1,
+                        "height": 0.1,
+                    },
+                }
+            ],
+            "simulation": {"step_size": 0.001, "max_bounces": 4, "use_gpu": True},
+            "output": {"directory": "./results", "format": "numpy"},
+        },
+    },
+    "atmosphere": {
+        "description": "Atmospheric refraction with exponential profile",
+        "config": {
+            "version": "1.0",
+            "media": {
+                "atmosphere": {
+                    "type": "exponential_atmosphere",
+                    "params": {"scale_height": 8500.0},
+                }
+            },
+            "background": "atmosphere",
+            "source": {
+                "type": "collimated_beam",
+                "params": {
+                    "center": [0.0, 0.0, 0.0],
+                    "direction": [0.0, 0.0, 1.0],
+                    "beam_radius": 0.001,
+                    "num_rays": 1000,
+                    "wavelength": 550e-9,
+                },
+            },
+            "surfaces": [],
+            "detectors": [
+                {
+                    "name": "altitude_detector",
+                    "type": "recording_sphere",
+                    "params": {"center": [0.0, 0.0, -6.371e6], "radius": 6.406e6},
+                }
+            ],
+            "simulation": {
+                "step_size": 100.0,
+                "max_bounces": 0,
+                "bounding_radius": 50000.0,
+                "use_gpu": True,
+            },
+            "output": {"directory": "./results", "format": "hdf5"},
+        },
+    },
+}
+
+
+def get_template_names() -> list[str]:
+    """Return list of available template names."""
+    return list(TEMPLATES.keys())
+
+
+def get_template(name: str) -> dict[str, Any] | None:
+    """Get a template configuration by name."""
+    template = TEMPLATES.get(name)
+    return template["config"] if template else None
+
+
+def get_template_description(name: str) -> str:
+    """Get a template description by name."""
+    template = TEMPLATES.get(name)
+    return template["description"] if template else ""
+
+
+# =============================================================================
+# Interactive Prompts
+# =============================================================================
+
+
+def prompt_media() -> dict[str, MediaConfig]:
+    """Interactively configure media/materials."""
+    media: dict[str, MediaConfig] = {}
+
+    questionary.print("\n=== Media Configuration ===", style="bold fg:cyan")
+    questionary.print(
+        "Define the materials/media for your simulation.\n", style="fg:gray"
+    )
+
+    # Always add at least one medium
+    while True:
+        name = questionary.text(
+            "Medium name (e.g., 'air', 'water', 'atmosphere'):",
+            style=LSURF_STYLE,
+        ).ask()
+
+        if not name:
+            if not media:
+                questionary.print("At least one medium is required.", style="fg:red")
+                continue
+            break
+
+        media_type = questionary.select(
+            f"Type for '{name}':",
+            choices=[
+                questionary.Choice("vacuum - Perfect vacuum (n=1.0)", value="vacuum"),
+                questionary.Choice("air - Air at STP (n=1.000293)", value="air"),
+                questionary.Choice("water - Water (n=1.333)", value="water"),
+                questionary.Choice(
+                    "glass - BK7 optical glass (n=1.5168)", value="glass"
+                ),
+                questionary.Choice(
+                    "homogeneous - Custom refractive index", value="homogeneous"
+                ),
+                questionary.Choice(
+                    "exponential_atmosphere - Exponential density profile",
+                    value="exponential_atmosphere",
+                ),
+            ],
+            style=LSURF_STYLE,
+        ).ask()
+
+        params: dict[str, Any] = {}
+
+        if media_type == "homogeneous":
+            n = questionary.text(
+                "Refractive index:",
+                default="1.5",
+                style=LSURF_STYLE,
+            ).ask()
+            params["refractive_index"] = float(n)
+
+            absorption = questionary.text(
+                "Absorption coefficient (m^-1, 0 for none):",
+                default="0.0",
+                style=LSURF_STYLE,
+            ).ask()
+            if float(absorption) > 0:
+                params["absorption_coef"] = float(absorption)
+
+        elif media_type == "exponential_atmosphere":
+            scale_height = questionary.text(
+                "Scale height (m):",
+                default="8500.0",
+                style=LSURF_STYLE,
+            ).ask()
+            params["scale_height"] = float(scale_height)
+
+            n_sea = questionary.text(
+                "Refractive index at sea level:",
+                default="1.000293",
+                style=LSURF_STYLE,
+            ).ask()
+            params["n_sea_level"] = float(n_sea)
+
+        media[name] = MediaConfig(type=media_type, params=params)
+
+        add_more = questionary.confirm(
+            "Add another medium?",
+            default=False,
+            style=LSURF_STYLE,
+        ).ask()
+
+        if not add_more:
+            break
+
+    return media
+
+
+def prompt_background(media_names: list[str]) -> str | None:
+    """Prompt for background medium selection."""
+    if not media_names:
+        return None
+
+    questionary.print("\n=== Background Medium ===", style="bold fg:cyan")
+
+    background = questionary.select(
+        "Select the background medium for ray propagation:",
+        choices=media_names + ["(none)"],
+        style=LSURF_STYLE,
+    ).ask()
+
+    return background if background != "(none)" else None
+
+
+def prompt_source() -> SourceConfig:
+    """Interactively configure the ray source."""
+    questionary.print("\n=== Source Configuration ===", style="bold fg:cyan")
+
+    source_type = questionary.select(
+        "Source type:",
+        choices=[
+            questionary.Choice(
+                "collimated_beam - Parallel rays (laser, sun)", value="collimated_beam"
+            ),
+            questionary.Choice("point - Isotropic point source", value="point"),
+            questionary.Choice(
+                "diverging_beam - Cone-shaped beam (LED, fiber)", value="diverging_beam"
+            ),
+            questionary.Choice(
+                "gaussian_beam - Paraxial Gaussian beam", value="gaussian_beam"
+            ),
+        ],
+        style=LSURF_STYLE,
+    ).ask()
+
+    params: dict[str, Any] = {}
+
+    # Common parameters
+    num_rays = questionary.text(
+        "Number of rays:",
+        default="10000",
+        style=LSURF_STYLE,
+    ).ask()
+    params["num_rays"] = int(num_rays)
+
+    wavelength = questionary.text(
+        "Wavelength (m, e.g., 532e-9 for green laser):",
+        default="532e-9",
+        style=LSURF_STYLE,
+    ).ask()
+    params["wavelength"] = float(wavelength)
+
+    if source_type == "collimated_beam":
+        center = _prompt_vector("Beam center position [x, y, z]:", "[0, 0, 100000]")
+        params["center"] = center
+
+        direction = _prompt_vector("Beam direction [x, y, z]:", "[0, 0, -1]")
+        params["direction"] = direction
+
+        radius = questionary.text(
+            "Beam radius (m):",
+            default="0.005",
+            style=LSURF_STYLE,
+        ).ask()
+        params["beam_radius"] = float(radius)
+
+    elif source_type == "point":
+        position = _prompt_vector("Source position [x, y, z]:", "[0, 0, 0]")
+        params["position"] = position
+
+    elif source_type == "diverging_beam":
+        origin = _prompt_vector("Origin position [x, y, z]:", "[0, 0, 0]")
+        params["origin"] = origin
+
+        direction = _prompt_vector("Mean direction [x, y, z]:", "[0, 0, 1]")
+        params["mean_direction"] = direction
+
+        angle = questionary.text(
+            "Divergence half-angle (radians):",
+            default="0.1",
+            style=LSURF_STYLE,
+        ).ask()
+        params["divergence_angle"] = float(angle)
+
+    elif source_type == "gaussian_beam":
+        waist_pos = _prompt_vector("Waist position [x, y, z]:", "[0, 0, 0]")
+        params["waist_position"] = waist_pos
+
+        direction = _prompt_vector("Propagation direction [x, y, z]:", "[0, 0, 1]")
+        params["direction"] = direction
+
+        waist_radius = questionary.text(
+            "Waist radius (m):",
+            default="0.001",
+            style=LSURF_STYLE,
+        ).ask()
+        params["waist_radius"] = float(waist_radius)
+
+    return SourceConfig(type=source_type, params=params)
+
+
+def prompt_surfaces(media_names: list[str]) -> list[SurfaceConfig]:
+    """Interactively configure surfaces."""
+    surfaces: list[SurfaceConfig] = []
+
+    questionary.print("\n=== Surface Configuration ===", style="bold fg:cyan")
+    questionary.print(
+        "Define optical surfaces for ray interactions.\n", style="fg:gray"
+    )
+
+    while True:
+        add_surface = questionary.confirm(
+            "Add a surface?" if not surfaces else "Add another surface?",
+            default=not surfaces,  # Default yes for first surface
+            style=LSURF_STYLE,
+        ).ask()
+
+        if not add_surface:
+            break
+
+        name = questionary.text(
+            "Surface name:",
+            default=f"surface_{len(surfaces) + 1}",
+            style=LSURF_STYLE,
+        ).ask()
+
+        surface_type = questionary.select(
+            "Surface type:",
+            choices=[
+                questionary.Choice("plane - Infinite flat plane", value="plane"),
+                questionary.Choice(
+                    "bounded_plane - Finite rectangular plane", value="bounded_plane"
+                ),
+                questionary.Choice("sphere - Spherical surface", value="sphere"),
+                questionary.Choice(
+                    "curved_wave - Ocean wave (curved Earth)", value="curved_wave"
+                ),
+                questionary.Choice(
+                    "gerstner_wave - Ocean wave (flat Earth)", value="gerstner_wave"
+                ),
+            ],
+            style=LSURF_STYLE,
+        ).ask()
+
+        role = questionary.select(
+            "Surface role:",
+            choices=[
+                questionary.Choice(
+                    "optical - Reflect/refract rays (Fresnel)", value="optical"
+                ),
+                questionary.Choice(
+                    "detector - Record and terminate rays", value="detector"
+                ),
+                questionary.Choice("absorber - Apply absorption", value="absorber"),
+            ],
+            style=LSURF_STYLE,
+        ).ask()
+
+        # Media selection for optical surfaces
+        front_medium = None
+        back_medium = None
+        if role == "optical" and media_names:
+            front_medium = questionary.select(
+                "Front medium (rays coming from):",
+                choices=media_names + ["(none)"],
+                style=LSURF_STYLE,
+            ).ask()
+            if front_medium == "(none)":
+                front_medium = None
+
+            back_medium = questionary.select(
+                "Back medium (rays going to):",
+                choices=media_names + ["(none)"],
+                style=LSURF_STYLE,
+            ).ask()
+            if back_medium == "(none)":
+                back_medium = None
+
+        params: dict[str, Any] = {}
+
+        if surface_type == "plane":
+            point = _prompt_vector("Point on plane [x, y, z]:", "[0, 0, 0]")
+            params["point"] = point
+
+            normal = _prompt_vector("Surface normal [x, y, z]:", "[0, 0, 1]")
+            params["normal"] = normal
+
+        elif surface_type == "bounded_plane":
+            point = _prompt_vector("Center point [x, y, z]:", "[0, 0, 0]")
+            params["point"] = point
+
+            normal = _prompt_vector("Surface normal [x, y, z]:", "[0, 0, 1]")
+            params["normal"] = normal
+
+            width = questionary.text(
+                "Width (m):", default="1.0", style=LSURF_STYLE
+            ).ask()
+            params["width"] = float(width)
+
+            height = questionary.text(
+                "Height (m):", default="1.0", style=LSURF_STYLE
+            ).ask()
+            params["height"] = float(height)
+
+        elif surface_type == "sphere":
+            center = _prompt_vector("Sphere center [x, y, z]:", "[0, 0, 0]")
+            params["center"] = center
+
+            radius = questionary.text(
+                "Radius (m, positive=convex, negative=concave):",
+                default="1.0",
+                style=LSURF_STYLE,
+            ).ask()
+            params["radius"] = float(radius)
+
+        elif surface_type in ("curved_wave", "gerstner_wave"):
+            amplitude = questionary.text(
+                "Wave amplitude (m):",
+                default="0.5",
+                style=LSURF_STYLE,
+            ).ask()
+            params["amplitude"] = float(amplitude)
+
+            wave_length = questionary.text(
+                "Wave wavelength (m):",
+                default="100.0",
+                style=LSURF_STYLE,
+            ).ask()
+            params["wavelength"] = float(wave_length)
+
+            direction = _prompt_vector("Wave direction [x, y]:", "[1, 0]")
+            params["direction"] = direction[:2] if len(direction) > 2 else direction
+
+            if surface_type == "curved_wave":
+                earth_center = _prompt_vector(
+                    "Earth center [x, y, z]:", "[0, 0, -6.371e6]"
+                )
+                params["earth_center"] = earth_center
+
+                earth_radius = questionary.text(
+                    "Earth radius (m):",
+                    default="6.371e6",
+                    style=LSURF_STYLE,
+                ).ask()
+                params["earth_radius"] = float(earth_radius)
+
+        surfaces.append(
+            SurfaceConfig(
+                name=name,
+                type=surface_type,
+                role=role,
+                front_medium=front_medium,
+                back_medium=back_medium,
+                params=params,
+            )
+        )
+
+    return surfaces
+
+
+def prompt_detectors() -> list[DetectorConfig]:
+    """Interactively configure detectors."""
+    detectors: list[DetectorConfig] = []
+
+    questionary.print("\n=== Detector Configuration ===", style="bold fg:cyan")
+    questionary.print(
+        "Define detectors to record ray intersections.\n", style="fg:gray"
+    )
+
+    while True:
+        add_detector = questionary.confirm(
+            "Add a detector?" if not detectors else "Add another detector?",
+            default=not detectors,  # Default yes for first detector
+            style=LSURF_STYLE,
+        ).ask()
+
+        if not add_detector:
+            break
+
+        name = questionary.text(
+            "Detector name:",
+            default=f"detector_{len(detectors) + 1}",
+            style=LSURF_STYLE,
+        ).ask()
+
+        detector_type = questionary.select(
+            "Detector type:",
+            choices=[
+                questionary.Choice(
+                    "recording_sphere - Spherical surface at altitude",
+                    value="recording_sphere",
+                ),
+                questionary.Choice(
+                    "spherical - Small spherical detector", value="spherical"
+                ),
+                questionary.Choice(
+                    "planar - Flat rectangular detector", value="planar"
+                ),
+                questionary.Choice(
+                    "directional - Detector with acceptance angle", value="directional"
+                ),
+            ],
+            style=LSURF_STYLE,
+        ).ask()
+
+        params: dict[str, Any] = {}
+
+        if detector_type == "recording_sphere":
+            center = _prompt_vector("Sphere center [x, y, z]:", "[0, 0, -6.371e6]")
+            params["center"] = center
+
+            radius = questionary.text(
+                "Radius (m):",
+                default="6.404e6",
+                style=LSURF_STYLE,
+            ).ask()
+            params["radius"] = float(radius)
+
+        elif detector_type == "spherical":
+            center = _prompt_vector("Center [x, y, z]:", "[0, 0, 0]")
+            params["center"] = center
+
+            radius = questionary.text(
+                "Radius (m):",
+                default="0.01",
+                style=LSURF_STYLE,
+            ).ask()
+            params["radius"] = float(radius)
+
+        elif detector_type == "planar":
+            center = _prompt_vector("Center [x, y, z]:", "[0, 0, 1]")
+            params["center"] = center
+
+            normal = _prompt_vector("Normal [x, y, z]:", "[0, 0, -1]")
+            params["normal"] = normal
+
+            width = questionary.text(
+                "Width (m):", default="0.1", style=LSURF_STYLE
+            ).ask()
+            params["width"] = float(width)
+
+            height = questionary.text(
+                "Height (m):", default="0.1", style=LSURF_STYLE
+            ).ask()
+            params["height"] = float(height)
+
+        elif detector_type == "directional":
+            position = _prompt_vector("Position [x, y, z]:", "[0, 0, 1]")
+            params["position"] = position
+
+            direction = _prompt_vector("Look direction [x, y, z]:", "[0, 0, -1]")
+            params["direction"] = direction
+
+            angle = questionary.text(
+                "Acceptance half-angle (radians):",
+                default="0.1",
+                style=LSURF_STYLE,
+            ).ask()
+            params["acceptance_angle"] = float(angle)
+
+            radius = questionary.text(
+                "Detector radius (m):",
+                default="0.01",
+                style=LSURF_STYLE,
+            ).ask()
+            params["radius"] = float(radius)
+
+        detectors.append(DetectorConfig(name=name, type=detector_type, params=params))
+
+    return detectors
+
+
+def prompt_simulation() -> SimulationConfig:
+    """Interactively configure simulation parameters."""
+    questionary.print("\n=== Simulation Parameters ===", style="bold fg:cyan")
+
+    use_defaults = questionary.confirm(
+        "Use default simulation parameters?",
+        default=True,
+        style=LSURF_STYLE,
+    ).ask()
+
+    if use_defaults:
+        return SimulationConfig()
+
+    step_size = questionary.text(
+        "Step size (m):",
+        default="100.0",
+        style=LSURF_STYLE,
+    ).ask()
+
+    max_bounces = questionary.text(
+        "Maximum bounces:",
+        default="10",
+        style=LSURF_STYLE,
+    ).ask()
+
+    polarization = questionary.select(
+        "Polarization:",
+        choices=[
+            questionary.Choice("unpolarized", value="unpolarized"),
+            questionary.Choice("s-polarized", value="s"),
+            questionary.Choice("p-polarized", value="p"),
+        ],
+        style=LSURF_STYLE,
+    ).ask()
+
+    use_gpu = questionary.confirm(
+        "Use GPU acceleration?",
+        default=True,
+        style=LSURF_STYLE,
+    ).ask()
+
+    return SimulationConfig(
+        step_size=float(step_size),
+        max_bounces=int(max_bounces),
+        polarization=polarization,
+        use_gpu=use_gpu,
+    )
+
+
+def prompt_output() -> OutputConfig:
+    """Interactively configure output options."""
+    questionary.print("\n=== Output Configuration ===", style="bold fg:cyan")
+
+    directory = questionary.text(
+        "Output directory:",
+        default="./results",
+        style=LSURF_STYLE,
+    ).ask()
+
+    output_format = questionary.select(
+        "Output format:",
+        choices=[
+            questionary.Choice("hdf5 - Hierarchical Data Format", value="hdf5"),
+            questionary.Choice("numpy - NumPy binary files", value="numpy"),
+            questionary.Choice("csv - CSV text files", value="csv"),
+        ],
+        style=LSURF_STYLE,
+    ).ask()
+
+    save_paths = questionary.confirm(
+        "Save full ray paths? (large files)",
+        default=False,
+        style=LSURF_STYLE,
+    ).ask()
+
+    return OutputConfig(
+        directory=directory,
+        format=output_format,
+        save_ray_paths=save_paths,
+    )
+
+
+def run_interactive_wizard() -> LSURFConfig:
+    """Run the full interactive configuration wizard.
+
+    Returns:
+        Complete LSURFConfig ready for serialization.
+    """
+    questionary.print("\n" + "=" * 60, style="fg:cyan")
+    questionary.print("  L-SURF Configuration Wizard", style="bold fg:cyan")
+    questionary.print("=" * 60 + "\n", style="fg:cyan")
+
+    # Step 1: Media
+    media = prompt_media()
+    media_names = list(media.keys())
+
+    # Step 2: Background
+    background = prompt_background(media_names)
+
+    # Step 3: Source
+    source = prompt_source()
+
+    # Step 4: Surfaces
+    surfaces = prompt_surfaces(media_names)
+
+    # Step 5: Detectors
+    detectors = prompt_detectors()
+
+    # Step 6: Simulation
+    simulation = prompt_simulation()
+
+    # Step 7: Output
+    output = prompt_output()
+
+    questionary.print("\n" + "=" * 60, style="fg:green")
+    questionary.print("  Configuration Complete!", style="bold fg:green")
+    questionary.print("=" * 60 + "\n", style="fg:green")
+
+    return LSURFConfig(
+        version="1.0",
+        media=media,
+        background=background,
+        source=source,
+        surfaces=surfaces,
+        detectors=detectors,
+        simulation=simulation,
+        output=output,
+    )
+
+
+def _prompt_vector(message: str, default: str) -> list[float]:
+    """Prompt for a vector input and parse it."""
+    value = questionary.text(
+        message,
+        default=default,
+        style=LSURF_STYLE,
+    ).ask()
+
+    # Parse the vector string
+    # Remove brackets and split by comma
+    cleaned = value.strip("[]() ")
+    parts = [p.strip() for p in cleaned.split(",")]
+    return [float(p) for p in parts]