oscura 0.7.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

oscura/utils/triggering/window.py

@@ -97,7 +97,7 @@ class WindowTrigger(Trigger):
             List of trigger events for window crossings.
         """
         data = trace.data
-        sample_period = trace.metadata.time_base
+        sample_period = 1.0 / trace.metadata.sample_rate
         events: list[TriggerEvent] = []
 
         # Determine if each sample is inside the window
@@ -182,7 +182,7 @@ class ZoneTrigger(Trigger):
             List of trigger events.
         """
         data = trace.data
-        sample_period = trace.metadata.time_base
+        sample_period = 1.0 / trace.metadata.sample_rate
         time_vector = np.arange(len(data)) * sample_period
         events: list[TriggerEvent] = []
 
@@ -396,7 +396,7 @@ class MaskTrigger(Trigger):
         mask_path = Path(self.mask_points)
 
         data = trace.data
-        sample_period = trace.metadata.time_base
+        sample_period = 1.0 / trace.metadata.sample_rate
         time_vector = np.arange(len(data)) * sample_period
 
         # Create points array for containment test

oscura/validation/hil_testing.py

@@ -35,7 +35,7 @@ from enum import Enum
 from typing import Any, Protocol
 
 try:
-    import can  # type: ignore[import-untyped]
+    import can
 except ImportError:
     can = None  # type: ignore[assignment]
 
@@ -46,18 +46,18 @@ except ImportError:
     # Create module structure for test patching even when pyusb unavailable
     import types
 
-    usb = types.ModuleType("usb")  # type: ignore[assignment]
+    usb = types.ModuleType("usb")
     usb.core = None  # type: ignore[attr-defined]
 
 try:
     import spidev  # type: ignore[import-not-found]
 except ImportError:
-    spidev = None  # type: ignore[assignment]
+    spidev = None
 
 try:
     from smbus2 import SMBus  # type: ignore[import-not-found]
 except ImportError:
-    SMBus = None  # type: ignore[assignment]
+    SMBus = None
 
 try:
     import RPi.GPIO as GPIO  # type: ignore[import-untyped]
@@ -65,23 +65,23 @@ except ImportError:
     try:
         import gpiod  # type: ignore[import-not-found]
 
-        GPIO = None  # type: ignore[assignment]
+        GPIO = None
     except ImportError:
-        GPIO = None  # type: ignore[assignment]
-        gpiod = None  # type: ignore[assignment]
+        GPIO = None
+        gpiod = None
 
 try:
     from scapy.all import IP, UDP, Packet, wrpcap  # type: ignore[attr-defined]
 except ImportError:
-    IP = None  # type: ignore[assignment]
-    UDP = None  # type: ignore[assignment]
+    IP = None
+    UDP = None
     Packet = None  # type: ignore[assignment,misc]
     wrpcap = None  # type: ignore[assignment]
 
 try:
     import serial  # type: ignore[import-untyped]
 except ImportError:
-    serial = None  # type: ignore[assignment]
+    serial = None
 
 from oscura.utils.serial import connect_serial_port
 
@@ -960,7 +960,7 @@ class HILTester:
             # Create UDP packet for received data if present
             if recv_data:
                 pkt = IP(src="192.168.1.1") / UDP(sport=12345) / bytes(recv_data)
-                pkt.time = timestamp + 0.001  # Slight offset
+                pkt.time = timestamp + 0.001
                 packets.append(pkt)
 
         if packets:

oscura/visualization/__init__.py

@@ -1,330 +1,93 @@
 """Visualization module for Oscura.
 
-Provides plotting functions for waveforms, spectra, and other signal data,
-plus optimization utilities, style presets, and intelligent rendering.
+Provides simple matplotlib-based plotting functions for waveforms, spectra,
+and digital signals. All functions accept and return matplotlib axes for
+composability.
 
 **Requires matplotlib:**
-This module requires matplotlib to be installed. Install with:
-    pip install oscura[visualization]    # Just visualization
-    pip install oscura[standard]         # Recommended
-    pip install oscura[all]              # Everything
+Install with: pip install oscura[visualization]
 
 Example:
-    >>> from oscura.visualization import plot_waveform, plot_spectrum
-    >>> from oscura.visualization import plot_timing, plot_eye
-    >>> from oscura.visualization import plot_bode, plot_histogram
-    >>> from oscura.visualization import apply_style_preset
     >>> import matplotlib.pyplot as plt
-    >>> with apply_style_preset("publication"):
-    ...     plot_waveform(trace, time_unit="us")
-    ...     plt.savefig("figure.pdf")
+    >>> import oscura as osc
+    >>> from oscura.visualization import plot_waveform, plot_fft
+    >>>
+    >>> trace = osc.load("signal.wfm")
+    >>> fig, (ax1, ax2) = plt.subplots(2, 1)
+    >>> plot_waveform(ax1, trace)
+    >>> plot_fft(ax2, trace)
+    >>> plt.savefig("analysis.png")
 """
 
-# NOTE: Matplotlib is optional - individual functions will check and raise
-# helpful errors if matplotlib is not installed when they're called.
-# The module itself can be imported without matplotlib.
-
-# Import plot module as namespace for DSL compatibility
-from oscura.visualization import plot
-from oscura.visualization.accessibility import (
-    FAIL_SYMBOL,
-    LINE_STYLES,
-    PASS_SYMBOL,
-    KeyboardHandler,
-    add_plot_aria_attributes,
-    format_pass_fail,
-    generate_alt_text,
-    get_colorblind_palette,
-    get_multi_line_styles,
-)
-
-# Phase 30 enhancements
-from oscura.visualization.annotations import (
-    Annotation as EnhancedAnnotation,
-)
-from oscura.visualization.annotations import (
-    PlacedAnnotation as EnhancedPlacedAnnotation,
-)
-from oscura.visualization.annotations import (
-    create_priority_annotation,
-    filter_by_zoom_level,
-    place_annotations,
-)
-from oscura.visualization.axis_scaling import (
-    calculate_axis_limits,
-    calculate_multi_channel_limits,
-    suggest_tick_spacing,
-)
-from oscura.visualization.colors import (
-    COLORBLIND_SAFE_QUALITATIVE,
-    DIVERGING_COOLWARM,
-    SEQUENTIAL_VIRIDIS,
-    select_optimal_palette,
-)
-from oscura.visualization.digital import (
-    plot_logic_analyzer,
-    plot_timing,
-)
-from oscura.visualization.eye import (
+# Import core plotting functions
+# Import batch utilities
+from oscura.visualization import batch
+from oscura.visualization.batch import fig_to_base64, generate_all_plots
+from oscura.visualization.plot import (
     plot_bathtub,
     plot_eye,
-)
-from oscura.visualization.histogram import (
-    calculate_bin_edges,
-    calculate_optimal_bins,
-)
-from oscura.visualization.interactive import (
-    CursorMeasurement,
-    ZoomState,
-    add_measurement_cursors,
-    enable_zoom_pan,
-    plot_bode,
+    plot_fft,
     plot_histogram,
-    plot_phase,
-    plot_waterfall,
-    plot_with_cursors,
-)
-from oscura.visualization.layout import (
-    Annotation,
-    ChannelLayout,
-    PlacedAnnotation,
-    layout_stacked_channels,
-    optimize_annotation_placement,
-)
-from oscura.visualization.optimization import (
-    InterestingRegion,
-    calculate_grid_spacing,
-    calculate_optimal_x_window,
-    calculate_optimal_y_range,
-    decimate_for_display,
-    detect_interesting_regions,
-    optimize_db_range,
-)
-from oscura.visualization.presets import (
-    DARK_THEME_PRESET,
-    IEEE_DOUBLE_COLUMN_PRESET,
-    IEEE_PUBLICATION_PRESET,
-    VisualizationPreset,
-    apply_preset,
-    get_preset_colors,
-)
-from oscura.visualization.presets import (
-    create_custom_preset as create_custom_visualization_preset,
-)
-from oscura.visualization.presets import (
-    list_presets as list_visualization_presets,
-)
-from oscura.visualization.protocols import (
-    plot_can_decode,
-    plot_i2c_decode,
+    plot_logic_analyzer,
+    plot_multi_channel,
     plot_protocol_decode,
-    plot_spi_decode,
-    plot_uart_decode,
-)
-from oscura.visualization.render import (
-    RenderPreset,
-    apply_rendering_config,
-    configure_dpi_rendering,
-)
-from oscura.visualization.rendering import (
-    StreamingRenderer,
-    downsample_for_memory,
-    estimate_memory_usage,
-    progressive_render,
-    render_with_lod,
-)
-
-# Reverse Engineering Visualizations (HIGH-2)
-from oscura.visualization.reverse_engineering import (
-    plot_crc_parameters,
-    plot_field_confidence_heatmap,
-    plot_message_field_layout,
-    plot_message_type_distribution,
-    plot_pipeline_timing,
-    plot_protocol_candidates,
-    plot_re_summary,
-)
-from oscura.visualization.specialized import (
-    ProtocolSignal,
-    StateTransition,
-    plot_protocol_timing,
-    plot_state_machine,
-)
-from oscura.visualization.spectral import (
-    plot_fft,
     plot_psd,
     plot_quality_summary,
     plot_spectrogram,
     plot_spectrum,
+    plot_state_machine,
     plot_thd_bars,
-)
-from oscura.visualization.styles import (
-    PRESENTATION_PRESET,
-    PRINT_PRESET,
-    PUBLICATION_PRESET,
-    SCREEN_PRESET,
-    StylePreset,
-    apply_style_preset,
-    create_custom_preset,
-)
-from oscura.visualization.thumbnails import (
-    render_thumbnail,
-    render_thumbnail_multichannel,
-)
-from oscura.visualization.time_axis import (
-    TimeUnit,
-    calculate_major_ticks,
-    convert_time_values,
-    create_relative_time,
-    format_cursor_readout,
-    format_time_labels,
-    select_time_unit,
-)
-from oscura.visualization.waveform import (
-    plot_multi_channel,
+    plot_timing,
     plot_waveform,
     plot_xy,
 )
 
+# Import styling utilities
+from oscura.visualization.styles import (
+    COLORBLIND_PALETTE,
+    FAIL_SYMBOL,
+    IEEE_STYLE,
+    LINE_STYLES,
+    PASS_SYMBOL,
+    apply_ieee_style,
+    apply_presentation_style,
+    format_pass_fail,
+    get_colorblind_cmap,
+    get_colorblind_palette,
+    get_line_styles,
+    get_multi_line_styles,
+)
+
 __all__ = [
-    "COLORBLIND_SAFE_QUALITATIVE",
-    "DARK_THEME_PRESET",
-    "DIVERGING_COOLWARM",
+    "COLORBLIND_PALETTE",
     "FAIL_SYMBOL",
-    "IEEE_DOUBLE_COLUMN_PRESET",
-    "IEEE_PUBLICATION_PRESET",
+    "IEEE_STYLE",
     "LINE_STYLES",
     "PASS_SYMBOL",
-    "PRESENTATION_PRESET",
-    "PRINT_PRESET",
-    "PUBLICATION_PRESET",
-    "SCREEN_PRESET",
-    "SEQUENTIAL_VIRIDIS",
-    "Annotation",
-    # Layout functions (VIS-015, VIS-016)
-    "ChannelLayout",
-    # Interactive (VIS-008)
-    "CursorMeasurement",
-    # Phase 30: Enhanced modules
-    "EnhancedAnnotation",
-    "EnhancedPlacedAnnotation",
-    "InterestingRegion",
-    "KeyboardHandler",
-    "PlacedAnnotation",
-    "ProtocolSignal",
-    "RenderPreset",
-    "StateTransition",
-    "StreamingRenderer",
-    "StylePreset",
-    "TimeUnit",
-    "VisualizationPreset",
-    # Interactive (VIS-007)
-    "ZoomState",
-    # Interactive (VIS-008)
-    "add_measurement_cursors",
-    "add_plot_aria_attributes",
-    "apply_preset",
-    "apply_rendering_config",
-    # Styles
-    "apply_style_preset",
-    "calculate_axis_limits",
-    "calculate_bin_edges",
-    "calculate_grid_spacing",
-    "calculate_major_ticks",
-    "calculate_multi_channel_limits",
-    # Histogram
-    "calculate_optimal_bins",
-    "calculate_optimal_x_window",
-    # Optimization functions (VIS-013, VIS-014, VIS-019, VIS-020, VIS-022)
-    "calculate_optimal_y_range",
-    # Rendering functions (VIS-017)
-    "configure_dpi_rendering",
-    "convert_time_values",
-    "create_custom_preset",
-    "create_custom_visualization_preset",
-    "create_priority_annotation",
-    "create_relative_time",
-    "decimate_for_display",
-    "detect_interesting_regions",
-    "downsample_for_memory",
-    # Interactive (VIS-007)
-    "enable_zoom_pan",
-    "estimate_memory_usage",
-    "filter_by_zoom_level",
-    "format_cursor_readout",
+    "apply_ieee_style",
+    "apply_presentation_style",
+    "batch",
+    "fig_to_base64",
     "format_pass_fail",
-    "format_time_labels",
-    "generate_alt_text",
-    # Accessibility (ACC-001, ACC-002, ACC-003)
+    "generate_all_plots",
+    "get_colorblind_cmap",
     "get_colorblind_palette",
+    "get_line_styles",
     "get_multi_line_styles",
-    "get_preset_colors",
-    "layout_stacked_channels",
-    "list_visualization_presets",
-    "optimize_annotation_placement",
-    "optimize_db_range",
-    "place_annotations",
-    "plot",
-    # Eye diagram (VIS-006)
     "plot_bathtub",
-    # Interactive (VIS-010)
-    "plot_bode",
-    # Protocol decode visualization (VIS-030)
-    "plot_can_decode",
-    # Reverse Engineering Visualization (HIGH-2)
-    "plot_crc_parameters",
     "plot_eye",
-    # Spectral plotting
     "plot_fft",
-    # Reverse Engineering Visualization (HIGH-2)
-    "plot_field_confidence_heatmap",
-    # Interactive (VIS-012)
     "plot_histogram",
-    # Protocol decode visualization (VIS-030)
-    "plot_i2c_decode",
-    # Digital visualization (VIS-005)
     "plot_logic_analyzer",
-    # Reverse Engineering Visualization (HIGH-2)
-    "plot_message_field_layout",
-    "plot_message_type_distribution",
     "plot_multi_channel",
-    # Interactive (VIS-009)
-    "plot_phase",
-    # Reverse Engineering Visualization (HIGH-2)
-    "plot_pipeline_timing",
-    # Protocol decode visualization (VIS-030)
-    "plot_protocol_candidates",
     "plot_protocol_decode",
-    "plot_protocol_timing",
     "plot_psd",
-    # Signal quality summary (IEEE 1241-2010)
     "plot_quality_summary",
-    # Reverse Engineering Visualization (HIGH-2)
-    "plot_re_summary",
     "plot_spectrogram",
     "plot_spectrum",
-    # Protocol decode visualization (VIS-030)
-    "plot_spi_decode",
     "plot_state_machine",
-    # THD harmonic bar chart
     "plot_thd_bars",
     "plot_timing",
-    # Protocol decode visualization (VIS-030)
-    "plot_uart_decode",
-    # Interactive (VIS-011)
-    "plot_waterfall",
-    # Waveform plotting
     "plot_waveform",
-    # Interactive (VIS-008)
-    "plot_with_cursors",
     "plot_xy",
-    "progressive_render",
-    # Thumbnails
-    "render_thumbnail",
-    "render_thumbnail_multichannel",
-    "render_with_lod",
-    # Colors
-    "select_optimal_palette",
-    "select_time_unit",
-    "suggest_tick_spacing",
 ]

oscura/visualization/batch.py

@@ -0,0 +1,160 @@
+"""Batch plot generation for comprehensive signal visualization.
+
+Generate multiple related plots from signal traces in a single operation,
+useful for comprehensive analysis reports.
+
+Example:
+    >>> from oscura.visualization import batch
+    >>> trace = osc.load("signal.wfm")
+    >>> plots = batch.generate_all_plots(trace)
+    >>> # Returns: {"waveform": <base64>, "fft": <base64>, ...}
+"""
+
+from __future__ import annotations
+
+import base64
+from io import BytesIO
+from typing import TYPE_CHECKING
+
+import matplotlib
+
+matplotlib.use("Agg")  # Non-interactive backend
+import matplotlib.pyplot as plt
+
+from oscura.core.types import DigitalTrace, WaveformTrace
+
+if TYPE_CHECKING:
+    from matplotlib.figure import Figure
+
+# Plot configuration
+PLOT_DPI = 150
+FIGURE_SIZE = (10, 6)
+
+
+def fig_to_base64(fig: Figure, *, dpi: int = PLOT_DPI) -> str:
+    """Convert matplotlib figure to base64-encoded PNG.
+
+    Args:
+        fig: Matplotlib figure object.
+        dpi: Resolution in dots per inch.
+
+    Returns:
+        Base64-encoded PNG image string with data URI prefix.
+
+    Example:
+        >>> fig, ax = plt.subplots()
+        >>> ax.plot([1, 2, 3])
+        >>> b64 = fig_to_base64(fig)
+    """
+    buf = BytesIO()
+    fig.savefig(buf, format="png", dpi=dpi, bbox_inches="tight", facecolor="white")
+    buf.seek(0)
+    img_base64 = base64.b64encode(buf.read()).decode("utf-8")
+    plt.close(fig)
+    return f"data:image/png;base64,{img_base64}"
+
+
+def generate_all_plots(
+    trace: WaveformTrace | DigitalTrace,
+    *,
+    verbose: bool = True,
+) -> dict[str, str]:
+    """Generate all applicable plots for a signal trace.
+
+    Automatically detects signal type and generates appropriate plots:
+    - Analog: waveform, FFT, histogram, spectrogram
+    - Digital: waveform, timing diagram
+
+    Args:
+        trace: WaveformTrace or DigitalTrace to visualize.
+        verbose: Print progress messages.
+
+    Returns:
+        Dictionary mapping plot names to base64 image strings.
+
+    Example:
+        >>> trace = osc.load("signal.wfm")
+        >>> plots = generate_all_plots(trace)
+        >>> len(plots)  # 4-5 plots for analog signal
+        4
+    """
+    from oscura.visualization.plot import (
+        plot_fft,
+        plot_histogram,
+        plot_spectrogram,
+        plot_timing,
+        plot_waveform,
+    )
+
+    plots = {}
+
+    # Always generate waveform (handle both analog and digital)
+    try:
+        fig, ax = plt.subplots(figsize=FIGURE_SIZE)
+        if isinstance(trace, WaveformTrace):
+            plot_waveform(ax, trace)
+        else:
+            # Digital trace
+            plot_timing(ax, trace)
+        plots["waveform"] = fig_to_base64(fig)
+        if verbose:
+            print("  ✓ Generated waveform plot")
+    except Exception as e:
+        if verbose:
+            print(f"  ⚠ Waveform plot failed: {e}")
+
+    if isinstance(trace, WaveformTrace):
+        # FFT spectrum
+        try:
+            fig, ax = plt.subplots(figsize=FIGURE_SIZE)
+            plot_fft(ax, trace)
+            plots["fft"] = fig_to_base64(fig)
+            if verbose:
+                print("  ✓ Generated FFT spectrum")
+        except Exception as e:
+            if verbose:
+                print(f"  ⚠ FFT plot failed: {e}")
+
+        # Histogram
+        try:
+            fig, ax = plt.subplots(figsize=FIGURE_SIZE)
+            plot_histogram(ax, trace.data)
+            plots["histogram"] = fig_to_base64(fig)
+            if verbose:
+                print("  ✓ Generated histogram")
+        except Exception as e:
+            if verbose:
+                print(f"  ⚠ Histogram plot failed: {e}")
+
+        # Spectrogram
+        try:
+            fig, ax = plt.subplots(figsize=FIGURE_SIZE)
+            plot_spectrogram(ax, trace)
+            plots["spectrogram"] = fig_to_base64(fig)
+            if verbose:
+                print("  ✓ Generated spectrogram")
+        except Exception as e:
+            if verbose:
+                print(f"  ⚠ Spectrogram plot failed: {e}")
+
+    elif isinstance(trace, DigitalTrace):
+        # Timing diagram
+        try:
+            fig, ax = plt.subplots(figsize=FIGURE_SIZE)
+            plot_timing(ax, trace)
+            plots["timing"] = fig_to_base64(fig)
+            if verbose:
+                print("  ✓ Generated timing diagram")
+        except Exception as e:
+            if verbose:
+                print(f"  ⚠ Timing plot failed: {e}")
+
+    return plots
+
+
+__all__ = [
+    "FIGURE_SIZE",
+    "PLOT_DPI",
+    "fig_to_base64",
+    "generate_all_plots",
+]