lsurf.visualization.raytracing_plots

Ray Tracing Visualization - Individual Axis Functions

Functions for plotting ray paths, intersections, and propagation. Each function draws on a single axis, enabling flexible composition.

Functions

create_ray_overview_figure(rays, surface[, ...])

Create comprehensive ray tracing overview figure.

plot_bounce_points(ax, bounce_positions[, ...])

Plot ray bounce points on surface.

plot_incoming_rays(ax, rays, surface[, ...])

Plot incoming ray segments from origin to surface intersection.

plot_multi_bounce_paths(ax, ray_paths[, ...])

Plot multi-bounce ray paths from trace_rays_multi_bounce output.

plot_production_ray_overview(original_rays, ...)

Create production simulation ray overview with surface bounce points.

plot_ray_endpoints(rays[, plane, color_by, ...])

Create figure with scatter and histogram of ray endpoints.

plot_ray_endpoints_histogram(ax, rays[, ...])

Plot 2D histogram of ray endpoint density.

plot_ray_endpoints_scatter(ax, rays[, ...])

Plot ray endpoint positions as scatter plot.

plot_ray_paths_2d(ray_history[, max_rays, ...])

Create figure with three 2D projections of ray paths.

plot_ray_paths_projection(ax, ray_history[, ...])

Plot ray paths as a 2D projection on given axis.

plot_ray_paths_with_surface(rays, ...[, ...])

Plot full ray paths (incoming, reflected, and refracted) with wave surface.

plot_reflected_rays(ax, rays[, length, ...])

Plot reflected ray segments from current position.

plot_surface_profile(ax, surface[, x_range, ...])

Plot surface height profile along x-axis.

plot_wave_surface_detail(reflected_rays, surface)

Plot wave surface detail with ray intersection points.
lsurf.visualization.raytracing_plots.plot_ray_paths_projection(ax, ray_history, projection='xz', max_rays=100, color_by='wavelength', alpha=0.6, linewidth=0.5, show_colorbar=True)[source]

Plot ray paths as a 2D projection on given axis.

Parameters:

  • ax (Axes) – Matplotlib axes to draw on.

  • ray_history (List[RayBatch]) – List of ray batches at different time steps.

  • projection (str) – Projection plane: ‘xy’, ‘xz’, or ‘yz’.

  • max_rays (int) – Maximum rays to plot for performance.

  • color_by (str) – Color rays by: ‘wavelength’, ‘intensity’, ‘generation’, ‘index’.

  • alpha (float) – Line transparency.

  • linewidth (float) – Line width.

  • show_colorbar (bool) – Whether to add colorbar.

Returns:

sm – ScalarMappable for external colorbar, or None.

Return type:

ScalarMappable or None

lsurf.visualization.raytracing_plots.plot_ray_endpoints_scatter(ax, rays, projection='xy', color_by='intensity', alpha=0.5, size=5, show_colorbar=True)[source]

Plot ray endpoint positions as scatter plot.

Parameters:

  • ax (Axes) – Matplotlib axes.

  • rays (RayBatch) – Ray batch.

  • projection (str) – Plane: ‘xy’, ‘xz’, ‘yz’.

  • color_by (str) – Color by: ‘intensity’, ‘wavelength’, ‘generation’, ‘time’.

  • alpha (float) – Point transparency.

  • size (float) – Point size.

  • show_colorbar (bool) – Whether to add colorbar.

Returns:

sm – For external colorbar.

Return type:

ScalarMappable or None

lsurf.visualization.raytracing_plots.plot_ray_endpoints_histogram(ax, rays, projection='xy', bins=50, cmap='hot')[source]

Plot 2D histogram of ray endpoint density.

Parameters:

  • ax (Axes) – Matplotlib axes.

  • rays (RayBatch) – Ray batch.

  • projection (str) – Plane: ‘xy’, ‘xz’, ‘yz’.

  • bins (int) – Number of histogram bins.

  • cmap (str) – Colormap name.

lsurf.visualization.raytracing_plots.plot_surface_profile(ax, surface, x_range=(-200, 200), y=0.0, n_points=1000, color='blue', linewidth=2.0, label='Surface')[source]

Plot surface height profile along x-axis.

Parameters:

  • ax (Axes) – Matplotlib axes.

  • surface (Surface) – Surface object with _surface_z method.

  • x_range (tuple) – (x_min, x_max) range.

  • y (float) – Y-coordinate for profile.

  • n_points (int) – Number of sample points.

  • color (str) – Line color.

  • linewidth (float) – Line width.

  • label (str) – Legend label.

lsurf.visualization.raytracing_plots.plot_bounce_points(ax, bounce_positions, bounce_number=1, color=None, size=20, alpha=0.7, projection='xz', label=None)[source]

Plot ray bounce points on surface.

Parameters:

  • ax (Axes) – Matplotlib axes.

  • bounce_positions (ndarray) – (N, 3) array of bounce positions.

  • bounce_number (int) – Bounce index (for color selection).

  • color (str, optional) – Override color.

  • size (float) – Marker size.

  • alpha (float) – Transparency.

  • projection (str) – Coordinate projection (‘xz’, ‘xy’, ‘yz’).

  • label (str, optional) – Legend label.

lsurf.visualization.raytracing_plots.plot_incoming_rays(ax, rays, surface, projection='xz', color='gold', alpha=0.3, linewidth=0.5, max_rays=100)[source]

Plot incoming ray segments from origin to surface intersection.

Parameters:

  • ax (Axes) – Matplotlib axes.

  • rays (RayBatch) – Ray batch before intersection.

  • surface (Surface) – Surface for intersection calculation.

  • projection (str) – Coordinate projection.

  • color (str) – Ray color.

  • alpha (float) – Transparency.

  • linewidth (float) – Line width.

  • max_rays (int) – Maximum rays to plot.

lsurf.visualization.raytracing_plots.plot_reflected_rays(ax, rays, length=100.0, projection='xz', color='cyan', alpha=0.3, linewidth=0.5, max_rays=100)[source]

Plot reflected ray segments from current position.

Parameters:

  • ax (Axes) – Matplotlib axes.

  • rays (RayBatch) – Reflected ray batch.

  • length (float) – Length of ray segments to draw.

  • projection (str) – Coordinate projection.

  • color (str) – Ray color.

  • alpha (float) – Transparency.

  • linewidth (float) – Line width.

  • max_rays (int) – Maximum rays to plot.

lsurf.visualization.raytracing_plots.plot_multi_bounce_paths(ax, ray_paths, projection='xz', reflected_color='cyan', refracted_color='orange', alpha=0.3, linewidth=0.5, max_paths=100)[source]

Plot multi-bounce ray paths from trace_rays_multi_bounce output.

Parameters:

  • ax (Axes) – Matplotlib axes.

  • ray_paths (dict) – Dictionary with ‘reflected_paths’ and/or ‘refracted_paths’ lists.

  • projection (str) – Coordinate projection.

  • reflected_color (str) – Color for reflected paths.

  • refracted_color (str) – Color for refracted paths.

  • alpha (float) – Transparency.

  • linewidth (float) – Line width.

  • max_paths (int) – Maximum paths to plot.

lsurf.visualization.raytracing_plots.create_ray_overview_figure(rays, surface, reflected_rays=None, bounce_points=None, figsize=(16, 10), x_range=(-500, 500), title='Ray Tracing Overview', save_path=None)[source]

Create comprehensive ray tracing overview figure.

Parameters:

  • rays (RayBatch) – Initial rays.

  • surface (Surface) – Wave surface.

  • reflected_rays (RayBatch, optional) – Reflected rays.

  • bounce_points (List[ndarray], optional) – List of bounce position arrays per bounce.

  • figsize (tuple) – Figure size.

  • x_range (tuple) – X-axis range.

  • title (str) – Figure title.

  • save_path (str, optional) – Path to save figure.

Returns:

Matplotlib figure.

Return type:

Figure

lsurf.visualization.raytracing_plots.plot_production_ray_overview(original_rays, surface, config, output_path, timestamp, max_bounces=2)[source]

Create production simulation ray overview with surface bounce points.

Shows incoming rays, bounce points on wave surface (colored by bounce number), and reflected rays toward recording sphere.

Parameters:

  • original_rays (RayBatch) – Original rays before tracing.

  • surface (Surface) – The wave surface (e.g., CurvedWaveSurface).

  • config (dict) – Simulation configuration with keys: - grazing_angle: Beam grazing angle in degrees - beam_radius: Beam radius in meters - earth_radius: Earth radius in meters - recording_altitude: Recording sphere altitude in meters - source_distance: Source distance in meters

  • output_path (str) – Directory to save figure.

  • timestamp (str) – Timestamp for filename.

  • max_bounces (int) – Maximum number of bounces to visualize (default: 2).

Returns:

Matplotlib figure.

Return type:

Figure

lsurf.visualization.raytracing_plots.plot_wave_surface_detail(reflected_rays, surface, x_range=(-200, 200), figsize=(12, 6), save_path=None)[source]

Plot wave surface detail with ray intersection points.

Parameters:

  • reflected_rays (RayBatch) – Batch of reflected rays.

  • surface (Surface) – The surface object (must have _surface_z method).

  • x_range (tuple) – X-axis range for plotting.

  • figsize (tuple) – Figure size (width, height).

  • save_path (str, optional) – Path to save figure.

Returns:

Matplotlib figure.

Return type:

Figure

lsurf.visualization.raytracing_plots.plot_ray_paths_with_surface(rays, reflected_rays, surface, detector_distance=1000.0, source_distance=1000.0, refracted_rays=None, ray_paths=None, figsize=(16, 10), save_path=None)[source]

Plot full ray paths (incoming, reflected, and refracted) with wave surface.

Parameters:

  • rays (RayBatch) – Initial ray batch (before interaction).

  • reflected_rays (RayBatch) – Reflected ray batch (after interaction).

  • surface (Surface) – The surface object.

  • detector_distance (float) – Detector distance in meters.

  • source_distance (float) – Source distance in meters (unused, for API compatibility).

  • refracted_rays (RayBatch, optional) – Refracted ray batch (after interaction).

  • ray_paths (dict, optional) – Dictionary with ray path data from trace_rays_multi_bounce containing: - ‘reflected_paths’: list of Nx3 arrays, one per ray - ‘refracted_paths’: list of Nx3 arrays for refracted rays - ‘reflected_final_dirs’: final direction for each reflected path - ‘refracted_final_dirs’: final direction for each refracted path

  • figsize (tuple) – Figure size.

  • save_path (str, optional) – Path to save figure.

Returns:

Matplotlib figure.

Return type:

Figure

lsurf.visualization.raytracing_plots.plot_ray_paths_2d(ray_history, max_rays=100, color_by='wavelength', alpha=0.4, linewidth=0.8, figsize=(15, 5), save_path=None)[source]

Create figure with three 2D projections of ray paths.

This is a convenience function for quick visualization. For custom layouts, use plot_ray_paths_projection() on individual axes.

Parameters:

  • ray_history (List[RayBatch]) – List of ray batches at different propagation steps.

  • max_rays (int) – Maximum rays to plot (sampled uniformly if exceeded).

  • color_by (str) – Color rays by: ‘wavelength’, ‘intensity’, ‘generation’, ‘index’.

  • alpha (float) – Line transparency.

  • linewidth (float) – Line width.

  • figsize (tuple) – Figure size.

  • save_path (str, optional) – Path to save figure.

Returns:

Matplotlib figure with three subplots (XY, XZ, YZ).

Return type:

Figure

lsurf.visualization.raytracing_plots.plot_ray_endpoints(rays, plane='xy', color_by='wavelength', bins=50, figsize=(12, 5), save_path=None)[source]

Create figure with scatter and histogram of ray endpoints.

This is a convenience function for quick visualization. For custom layouts, use plot_ray_endpoints_scatter() and plot_ray_endpoints_histogram().

Parameters:

  • rays (RayBatch) – Ray batch with endpoint positions.

  • plane (str) – Projection plane: ‘xy’, ‘xz’, ‘yz’.

  • color_by (str) – Color scatter by: ‘wavelength’, ‘intensity’.

  • bins (int) – Histogram bins.

  • figsize (tuple) – Figure size.

  • save_path (str, optional) – Path to save figure.

Returns:

Matplotlib figure with scatter and histogram.

Return type:

Figure