lsurf.visualization.detector_plots

Detector Visualization - Individual Axis Functions

Functions for plotting detector-related data: beam profiles, wavelength distributions, detection counts, arrival times, and scan results. Each function draws on a single axis, enabling flexible composition.

Functions

`create_beam_profile_figure`(rays[, axis, ...])	Create figure showing beam profile at multiple slices.
`create_detector_scan_figure`(...[, ...])	Create comprehensive detector scan figure.
`create_wavelength_figure`(rays[, bins, ...])	Create figure with wavelength histograms.
`plot_angular_histogram`(ax, ...[, bins, ...])	Plot histogram of all arrival angles.
`plot_arrival_angle_distribution`(ax, ...[, ...])	Plot mean arrival angle vs detector position.
`plot_beam_profile`(rays[, axis, num_slices, ...])	Create figure showing beam profile at multiple slices.
`plot_beam_slice`(ax, rays[, axis, ...])	Plot beam profile at a specific slice along propagation axis.
`plot_detection_counts`(ax, ...[, color, ...])	Plot detection counts vs detector angle.
`plot_detection_efficiency`(ax, ...[, color, ...])	Plot detection efficiency vs detector angle.
`plot_detector_scan_results`(...[, ...])	Create comprehensive detector scan visualization with multiple subplots.
`plot_mean_arrival_time`(ax, ...[, std_times, ...])	Plot mean arrival time vs detector angle.
`plot_statistics_evolution`(stats_history[, ...])	Create figure showing evolution of ray statistics over propagation.
`plot_timing_distribution`(ax, ...[, ...])	Plot arrival time distributions for multiple detector positions.
`plot_wavelength_distribution`(rays[, bins, ...])	Create figure showing wavelength distribution of rays.
`plot_wavelength_histogram`(ax, rays[, bins, ...])	Plot histogram of ray wavelengths.
`plot_wavelength_intensity_histogram`(ax, rays)	Plot intensity-weighted histogram of ray wavelengths.

lsurf.visualization.detector_plots.plot_beam_slice(ax, rays, axis='z', slice_value=0.0, slice_width=0.1, color_by='intensity', point_size=20, alpha=0.6, show_colorbar=True)[source]

Plot beam profile at a specific slice along propagation axis.

Parameters:

ax (Axes) – Matplotlib axes.
rays (RayBatch) – Ray batch.
axis (str) – Propagation axis: ‘x’, ‘y’, or ‘z’.
slice_value (float) – Position along axis to slice.
slice_width (float) – Width of slice.
color_by (str) – Color by: ‘intensity’, ‘wavelength’.
point_size (float) – Scatter point size.
alpha (float) – Transparency.
show_colorbar (bool) – Whether to add colorbar.

Returns:

ScalarMappable for external colorbar.

Return type:

scatter or None

lsurf.visualization.detector_plots.plot_wavelength_histogram(ax, rays, bins=50, alpha=0.7, color='steelblue', edgecolor='black', label=None, weight_by_intensity=False)[source]

Plot histogram of ray wavelengths.

Parameters:

ax (Axes) – Matplotlib axes.
rays (RayBatch) – Ray batch.
bins (int) – Number of histogram bins.
alpha (float) – Bar transparency.
color (str) – Bar color.
edgecolor (str) – Edge color.
label (str, optional) – Legend label.
weight_by_intensity (bool) – If True, weight histogram by ray intensities.

lsurf.visualization.detector_plots.plot_wavelength_intensity_histogram(ax, rays, bins=50, alpha=0.7, color='orange', edgecolor='black', label=None)[source]

Plot intensity-weighted histogram of ray wavelengths.

Deprecated: Use plot_wavelength_histogram(weight_by_intensity=True) instead.

Parameters:

ax (Axes) – Matplotlib axes.
rays (RayBatch) – Ray batch.
bins (int) – Number of histogram bins.
alpha (float) – Bar transparency.
color (str) – Bar color.
edgecolor (str) – Edge color.
label (str, optional) – Legend label.

lsurf.visualization.detector_plots.plot_detection_counts(ax, detector_angles_deg, detection_counts, color='blue', marker='o', linewidth=2, markersize=8, label=None)[source]

Plot detection counts vs detector angle.

Parameters:

ax (Axes) – Matplotlib axes.
detector_angles_deg (ndarray) – Detector angles in degrees.
detection_counts (ndarray) – Number of rays detected.
color (str) – Line color.
marker (str) – Marker style.
linewidth (float) – Line width.
markersize (float) – Marker size.
label (str, optional) – Legend label.

lsurf.visualization.detector_plots.plot_detection_efficiency(ax, detector_angles_deg, detected_intensities, total_source_intensity, color='magenta', marker='o', linewidth=2, markersize=8, label=None)[source]

Plot detection efficiency vs detector angle.

Parameters:

ax (Axes) – Matplotlib axes.
detector_angles_deg (ndarray) – Detector angles in degrees.
detected_intensities (ndarray) – Total intensity detected.
total_source_intensity (float) – Total source intensity.
color (str) – Line color.
marker (str) – Marker style.
linewidth (float) – Line width.
markersize (float) – Marker size.
label (str, optional) – Legend label.

lsurf.visualization.detector_plots.plot_mean_arrival_time(ax, detector_angles_deg, mean_times, std_times=None, detection_counts=None, color='cyan', marker='o', linewidth=2, markersize=8, label=None)[source]

Plot mean arrival time vs detector angle.

Parameters:

ax (Axes) – Matplotlib axes.
detector_angles_deg (ndarray) – Detector angles in degrees.
mean_times (ndarray) – Mean arrival times in seconds.
std_times (ndarray, optional) – Standard deviation of arrival times.
detection_counts (ndarray, optional) – For masking invalid data.
color (str) – Line color.
marker (str) – Marker style.
linewidth (float) – Line width.
markersize (float) – Marker size.
label (str, optional) – Legend label.

lsurf.visualization.detector_plots.plot_timing_distribution(ax, all_time_distributions, detector_angles_deg, log_scale=True, show_legend=True, max_curves=10)[source]

Plot arrival time distributions for multiple detector positions.

Parameters:

ax (Axes) – Matplotlib axes.
all_time_distributions (list) – List of (times, intensities, angles) tuples for each detector.
detector_angles_deg (ndarray) – Detector angles in degrees.
log_scale (bool) – Whether to use log scales.
show_legend (bool) – Whether to show legend.
max_curves (int) – Maximum number of curves to plot.

lsurf.visualization.detector_plots.plot_arrival_angle_distribution(ax, detector_angles_deg, mean_angles, std_angles=None, detection_counts=None, color='magenta', marker='o', linewidth=2, markersize=8)[source]

Plot mean arrival angle vs detector position.

Parameters:

ax (Axes) – Matplotlib axes.
detector_angles_deg (ndarray) – Detector position angles.
mean_angles (ndarray) – Mean arrival angles to normal.
std_angles (ndarray, optional) – Standard deviation.
detection_counts (ndarray, optional) – For masking invalid data.
color (str) – Line color.
marker (str) – Marker style.
linewidth (float) – Line width.
markersize (float) – Marker size.

lsurf.visualization.detector_plots.plot_angular_histogram(ax, all_time_distributions, detection_counts, bins=50, color='purple', alpha=0.7)[source]

Plot histogram of all arrival angles.

Parameters:

ax (Axes) – Matplotlib axes.
all_time_distributions (list) – List of (times, intensities, angles) tuples.
detection_counts (ndarray) – Detection counts per position.
bins (int) – Number of histogram bins.
color (str) – Bar color.
alpha (float) – Transparency.

lsurf.visualization.detector_plots.create_wavelength_figure(rays, bins=50, figsize=(10, 5), title='Wavelength Distribution', save_path=None)[source]

Create figure with wavelength histograms.

Parameters:

rays (RayBatch) – Ray batch.
bins (int) – Histogram bins.
figsize (tuple) – Figure size.
title (str) – Figure title.
save_path (str, optional) – Save path.

Returns:

Matplotlib figure.

Return type:

Figure

lsurf.visualization.detector_plots.create_beam_profile_figure(rays, axis='z', num_slices=5, figsize=(15, 4), title=None, save_path=None)[source]

Create figure showing beam profile at multiple slices.

Parameters:

rays (RayBatch) – Ray batch.
axis (str) – Propagation axis.
num_slices (int) – Number of slices.
figsize (tuple) – Figure size.
title (str, optional) – Figure title.
save_path (str, optional) – Save path.

Returns:

Matplotlib figure.

Return type:

Figure

lsurf.visualization.detector_plots.create_detector_scan_figure(detector_angles_deg, detection_counts, detected_intensities, total_source_intensity, mean_arrival_times=None, std_arrival_times=None, mean_angles_to_normal=None, std_angles_to_normal=None, all_time_distributions=None, figsize=(16, 12), title='Detector Scan Results', save_path=None)[source]

Create comprehensive detector scan figure.

Parameters:

detector_angles_deg (ndarray) – Detector angles in degrees.
detection_counts (ndarray) – Number of rays detected.
detected_intensities (ndarray) – Total intensity detected.
total_source_intensity (float) – Source intensity.
mean_arrival_times (ndarray, optional) – Mean arrival times.
std_arrival_times (ndarray, optional) – Std of arrival times.
mean_angles_to_normal (ndarray, optional) – Mean arrival angles.
std_angles_to_normal (ndarray, optional) – Std of arrival angles.
all_time_distributions (list, optional) – Timing data.
figsize (tuple) – Figure size.
title (str) – Figure title.
save_path (str, optional) – Save path.

Returns:

Matplotlib figure.

Return type:

Figure

lsurf.visualization.detector_plots.plot_detector_scan_results(detector_angles_deg, detection_counts, detected_intensities, reflected_rays, surface, total_source_intensity, mean_arrival_times=None, std_arrival_times=None, mean_angles_to_normal=None, std_angles_to_normal=None, all_time_distributions=None, detector_distance=1000.0, detector_radius=5.0, water_normal=None, figsize=(24, 14), save_path=None)[source]

Create comprehensive detector scan visualization with multiple subplots.

This is the full production visualization with all panels including the wave surface and ray visualizations.

Parameters:

detector_angles_deg (ndarray) – Detector angles in degrees (0-90).
detection_counts (ndarray) – Number of rays detected at each position.
detected_intensities (ndarray) – Total intensity detected at each position.
reflected_rays (RayBatch) – Batch of reflected rays.
surface (Surface) – The surface object (must have _surface_z method).
total_source_intensity (float) – Total intensity of source rays.
mean_arrival_times (ndarray, optional) – Mean arrival time at each detector position.
std_arrival_times (ndarray, optional) – Standard deviation of arrival times.
mean_angles_to_normal (ndarray, optional) – Mean angle to normal at each detector.
std_angles_to_normal (ndarray, optional) – Standard deviation of angles.
all_time_distributions (list, optional) – List of (times, intensities, angles) tuples for each detector.
detector_distance (float) – Distance to detector in meters.
detector_radius (float) – Detector radius in meters.
water_normal (ndarray) – Normal vector for water surface.
figsize (tuple) – Figure size (width, height).
save_path (str, optional) – Path to save figure.

Returns:

Matplotlib figure with comprehensive visualization.

Return type:

Figure

lsurf.visualization.detector_plots.plot_statistics_evolution(stats_history, figsize=(15, 10), save_path=None)[source]

Create figure showing evolution of ray statistics over propagation.

This is a convenience function for visualizing how beam properties change during propagation.

Parameters:

stats_history (List[RayStatistics]) – List of RayStatistics objects at different propagation steps.
figsize (tuple) – Figure size.
save_path (str, optional) – Path to save figure.

Returns:

Matplotlib figure with statistics evolution.

Return type:

Figure

lsurf.visualization.detector_plots.plot_beam_profile(rays, axis='z', num_slices=5, figsize=(15, 4), save_path=None)[source]

Create figure showing beam profile at multiple slices.

This is an alias for create_beam_profile_figure for backward compatibility.

Parameters:

rays (RayBatch) – Ray batch.
axis (str) – Propagation axis: ‘x’, ‘y’, ‘z’.
num_slices (int) – Number of slices to show.
figsize (tuple) – Figure size.
save_path (str, optional) – Path to save figure.

Returns:

Matplotlib figure.

Return type:

Figure

lsurf.visualization.detector_plots.plot_wavelength_distribution(rays, bins=50, figsize=(10, 6), save_path=None)[source]

Create figure showing wavelength distribution of rays.

This is a convenience function for quick visualization. For custom layouts, use plot_wavelength_histogram() on a single axis.

Parameters:

rays (RayBatch) – Ray batch.
bins (int) – Number of histogram bins.
figsize (tuple) – Figure size.
save_path (str, optional) – Path to save figure.

Returns:

Matplotlib figure with wavelength histogram.

Return type:

Figure