oscura 0.5.0__py3-none-any.whl → 0.6.0__py3-none-any.whl

oscura/visualization/thumbnails.py

@@ -15,7 +15,7 @@ References:
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 import numpy as np
 
@@ -83,10 +83,25 @@ def render_thumbnail(
     if not HAS_MATPLOTLIB:
         raise ImportError("matplotlib is required for visualization")
 
-    # Default sample rate if not provided
-    if sample_rate is None:
-        sample_rate = 1.0
+    sample_rate = sample_rate if sample_rate is not None else 1.0
+    _validate_thumbnail_params(signal, sample_rate, max_samples)
+    size = _compute_thumbnail_size(size, width, height)
 
+    with plt.rc_context(_get_fast_rendering_config()):
+        fig, ax = _create_thumbnail_figure(size, dpi)
+        decimated_signal = _decimate_uniform(signal, max_samples)
+        total_time = len(signal) / sample_rate
+        time_scaled, time_unit = _prepare_time_axis(decimated_signal, total_time, time_unit)
+        _plot_thumbnail_signal(ax, time_scaled, decimated_signal, time_unit, title)
+        fig.tight_layout(pad=0.5)
+
+    return fig
+
+
+def _validate_thumbnail_params(
+    signal: NDArray[np.float64], sample_rate: float, max_samples: int
+) -> None:
+    """Validate thumbnail rendering parameters."""
     if len(signal) == 0:
         raise ValueError("Signal cannot be empty")
     if sample_rate <= 0:
@@ -94,70 +109,75 @@ def render_thumbnail(
     if max_samples < 10:
         raise ValueError("max_samples must be >= 10")
 
-    # Handle width/height as alternative to size
+
+def _compute_thumbnail_size(
+    size: tuple[int, int], width: int | None, height: int | None
+) -> tuple[int, int]:
+    """Compute thumbnail size from width/height or size tuple."""
     if width is not None:
         h = height if height is not None else int(width * 0.75)
-        size = (width, h)
-    elif height is not None:
-        size = (int(height * 4 / 3), height)
-
-    # Configure matplotlib for fast rendering (no anti-aliasing, etc.)
-    with plt.rc_context(
-        {
-            "path.simplify": True,
-            "path.simplify_threshold": 1.0,
-            "agg.path.chunksize": 1000,
-            "lines.antialiased": False,
-            "patch.antialiased": False,
-            "text.antialiased": False,
-        }
-    ):
-        # Calculate figure size in inches
-        width_inches = size[0] / dpi
-        height_inches = size[1] / dpi
-
-        # Create figure with no fancy features
-        fig, ax = plt.subplots(figsize=(width_inches, height_inches), dpi=dpi)
-
-        # Decimate signal to max_samples
-        decimated_signal = _decimate_uniform(signal, max_samples)
-
-        # Create time vector for decimated signal
-        total_time = len(signal) / sample_rate
-        time = np.linspace(0, total_time, len(decimated_signal))
-
-        # Auto-select time unit
-        if time_unit == "auto":
-            if total_time < 1e-6:
-                time_unit = "ns"
-            elif total_time < 1e-3:
-                time_unit = "us"
-            elif total_time < 1:
-                time_unit = "ms"
-            else:
-                time_unit = "s"
-
-        time_multipliers = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
-        multiplier = time_multipliers.get(time_unit, 1.0)
-        time_scaled = time * multiplier
-
-        # Plot with simplified style
-        ax.plot(time_scaled, decimated_signal, "b-", linewidth=0.5, antialiased=False)
-
-        # Minimal labels (no grid, no fancy formatting)
-        ax.set_xlabel(f"Time ({time_unit})", fontsize=8)
-        ax.set_ylabel("Amplitude", fontsize=8)
-
-        if title:
-            ax.set_title(title, fontsize=9)
-
-        # Reduce tick label size
-        ax.tick_params(labelsize=7)
-
-        # Tight layout to maximize plot area
-        fig.tight_layout(pad=0.5)
-
-    return fig
+        return (width, h)
+    if height is not None:
+        return (int(height * 4 / 3), height)
+    return size
+
+
+def _get_fast_rendering_config() -> dict[str, bool | float]:
+    """Get matplotlib configuration for fast rendering."""
+    return {
+        "path.simplify": True,
+        "path.simplify_threshold": 1.0,
+        "agg.path.chunksize": 1000,
+        "lines.antialiased": False,
+        "patch.antialiased": False,
+        "text.antialiased": False,
+    }
+
+
+def _create_thumbnail_figure(size: tuple[int, int], dpi: int) -> tuple[Figure, Any]:
+    """Create matplotlib figure for thumbnail."""
+    width_inches = size[0] / dpi
+    height_inches = size[1] / dpi
+    return plt.subplots(figsize=(width_inches, height_inches), dpi=dpi)
+
+
+def _prepare_time_axis(
+    decimated_signal: NDArray[np.float64], total_time: float, time_unit: str
+) -> tuple[NDArray[np.float64], str]:
+    """Prepare time axis with auto unit selection."""
+    time = np.linspace(0, total_time, len(decimated_signal))
+    if time_unit == "auto":
+        time_unit = _auto_select_time_unit(total_time)
+    time_multipliers = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    multiplier = time_multipliers.get(time_unit, 1.0)
+    return time * multiplier, time_unit
+
+
+def _auto_select_time_unit(total_time: float) -> str:
+    """Auto-select appropriate time unit based on signal duration."""
+    if total_time < 1e-6:
+        return "ns"
+    if total_time < 1e-3:
+        return "us"
+    if total_time < 1:
+        return "ms"
+    return "s"
+
+
+def _plot_thumbnail_signal(
+    ax: Any,
+    time_scaled: NDArray[np.float64],
+    decimated_signal: NDArray[np.float64],
+    time_unit: str,
+    title: str | None,
+) -> None:
+    """Plot signal on thumbnail axes."""
+    ax.plot(time_scaled, decimated_signal, "b-", linewidth=0.5, antialiased=False)
+    ax.set_xlabel(f"Time ({time_unit})", fontsize=8)
+    ax.set_ylabel("Amplitude", fontsize=8)
+    if title:
+        ax.set_title(title, fontsize=9)
+    ax.tick_params(labelsize=7)
 
 
 def _decimate_uniform(signal: NDArray[np.float64], target_samples: int) -> NDArray[np.float64]:
@@ -220,89 +240,98 @@ def render_thumbnail_multichannel(
     References:
         VIS-018: Thumbnail Mode
     """
+    _validate_multichannel_params(signals, sample_rate)
+    n_channels = len(signals)
+    names = channel_names if channel_names is not None else _default_channel_names(n_channels)
+    time_unit_resolved, multiplier = _resolve_time_unit(signals[0], sample_rate, time_unit)
+
+    with plt.rc_context(_get_fast_rendering_config()):
+        fig, axes = _create_multichannel_figure(n_channels, size, dpi)
+        _plot_multichannel_signals(
+            axes, signals, names, sample_rate, max_samples, multiplier, time_unit_resolved
+        )
+        fig.tight_layout(pad=0.3)
+
+    return fig
+
+
+def _validate_multichannel_params(signals: list[NDArray[np.float64]], sample_rate: float) -> None:
+    """Validate multichannel thumbnail parameters."""
     if not HAS_MATPLOTLIB:
         raise ImportError("matplotlib is required for visualization")
-
     if len(signals) == 0:
         raise ValueError("Must provide at least one signal")
     if sample_rate <= 0:
         raise ValueError("Sample rate must be positive")
 
+
+def _default_channel_names(n_channels: int) -> list[str]:
+    """Generate default channel names."""
+    return [f"CH{i + 1}" for i in range(n_channels)]
+
+
+def _resolve_time_unit(
+    first_signal: NDArray[np.float64], sample_rate: float, time_unit: str
+) -> tuple[str, float]:
+    """Resolve time unit and multiplier."""
+    if len(first_signal) > 0 and time_unit == "auto":
+        total_time = len(first_signal) / sample_rate
+        time_unit = _auto_select_time_unit(total_time)
+    elif time_unit == "auto":
+        time_unit = "s"
+
+    time_multipliers = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    multiplier = time_multipliers.get(time_unit, 1.0)
+    return time_unit, multiplier
+
+
+def _create_multichannel_figure(
+    n_channels: int, size: tuple[int, int], dpi: int
+) -> tuple[Figure, Any]:
+    """Create matplotlib figure for multichannel display."""
+    width_inches = size[0] / dpi
+    height_inches = size[1] / dpi
+
+    fig, axes = plt.subplots(
+        n_channels,
+        1,
+        figsize=(width_inches, height_inches),
+        dpi=dpi,
+        sharex=True,
+    )
+
+    if n_channels == 1:
+        axes = [axes]
+
+    return fig, axes
+
+
+def _plot_multichannel_signals(
+    axes: Any,
+    signals: list[NDArray[np.float64]],
+    names: list[str],
+    sample_rate: float,
+    max_samples: int,
+    multiplier: float,
+    time_unit: str,
+) -> None:
+    """Plot all channels on their respective axes."""
     n_channels = len(signals)
 
-    if channel_names is None:
-        channel_names = [f"CH{i + 1}" for i in range(n_channels)]
-
-    # Configure matplotlib for fast rendering
-    with plt.rc_context(
-        {
-            "path.simplify": True,
-            "path.simplify_threshold": 1.0,
-            "agg.path.chunksize": 1000,
-            "lines.antialiased": False,
-            "patch.antialiased": False,
-            "text.antialiased": False,
-        }
-    ):
-        # Calculate figure size
-        width_inches = size[0] / dpi
-        height_inches = size[1] / dpi
-
-        fig, axes = plt.subplots(
-            n_channels,
-            1,
-            figsize=(width_inches, height_inches),
-            dpi=dpi,
-            sharex=True,
-        )
+    for i, (sig, name, ax) in enumerate(zip(signals, names, axes, strict=False)):
+        if len(sig) == 0:
+            continue
 
-        if n_channels == 1:
-            axes = [axes]
-
-        # Get time unit from first signal
-        if len(signals[0]) > 0:
-            total_time = len(signals[0]) / sample_rate
-            if time_unit == "auto":
-                if total_time < 1e-6:
-                    time_unit = "ns"
-                elif total_time < 1e-3:
-                    time_unit = "us"
-                elif total_time < 1:
-                    time_unit = "ms"
-                else:
-                    time_unit = "s"
-        else:
-            time_unit = "s"
-
-        time_multipliers = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
-        multiplier = time_multipliers.get(time_unit, 1.0)
-
-        # Plot each channel
-        for i, (sig, name, ax) in enumerate(zip(signals, channel_names, axes, strict=False)):
-            if len(sig) == 0:
-                continue
-
-            # Decimate signal
-            decimated = _decimate_uniform(sig, max_samples)
-
-            # Time vector
-            total_time = len(sig) / sample_rate
-            time = np.linspace(0, total_time, len(decimated)) * multiplier
-
-            # Plot
-            ax.plot(time, decimated, "b-", linewidth=0.5, antialiased=False)
-
-            # Channel label
-            ax.set_ylabel(name, fontsize=7, rotation=0, ha="right", va="center")
-            ax.tick_params(labelsize=6)
-
-            # Only x-label on bottom
-            if i == n_channels - 1:
-                ax.set_xlabel(f"Time ({time_unit})", fontsize=8)
+        decimated = _decimate_uniform(sig, max_samples)
+        total_time = len(sig) / sample_rate
+        time = np.linspace(0, total_time, len(decimated)) * multiplier
 
-        fig.tight_layout(pad=0.3)
+        ax.plot(time, decimated, "b-", linewidth=0.5, antialiased=False)
+        ax.set_ylabel(name, fontsize=7, rotation=0, ha="right", va="center")
+        ax.tick_params(labelsize=6)
 
-    return fig
+        if i == n_channels - 1:
+            ax.set_xlabel(f"Time ({time_unit})", fontsize=8)
 
 
 __all__ = [

oscura/visualization/waveform.py

@@ -92,15 +92,58 @@ def plot_waveform(
     if not HAS_MATPLOTLIB:
         raise ImportError("matplotlib is required for visualization")
 
+    # Setup figure and axes
+    fig, ax = _setup_waveform_figure(ax, figsize)
+
+    # Prepare time axis
+    time_unit_final, time_info = _prepare_time_axis(trace, time_unit)
+    time_scaled, _ = time_info
+
+    # Plot waveform
+    _plot_waveform_data(ax, time_scaled, trace.data, color, label)
+
+    # Apply styling and formatting
+    _apply_waveform_formatting(
+        ax,
+        time_range,
+        time_unit_final,
+        time_info,
+        xlabel,
+        ylabel,
+        title,
+        trace.metadata.channel_name,
+        show_grid,
+        label,
+    )
+
+    # Add measurements if provided
+    if show_measurements:
+        _add_measurement_annotations(ax, trace, show_measurements, time_unit_final, time_info[1])
+
+    fig.tight_layout()
+
+    # Save and show
+    _save_and_show_figure(fig, save_path, show)
+
+    return fig
+
+
+def _setup_waveform_figure(ax: Axes | None, figsize: tuple[float, float]) -> tuple[Figure, Axes]:
+    """Setup figure and axes for waveform plot."""
     if ax is None:
         fig, ax = plt.subplots(figsize=figsize)
-    else:
-        fig_temp = ax.get_figure()
-        if fig_temp is None:
-            raise ValueError("Axes must have an associated figure")
-        fig = cast("Figure", fig_temp)
+        return fig, ax
 
-    # Calculate time axis
+    fig_temp = ax.get_figure()
+    if fig_temp is None:
+        raise ValueError("Axes must have an associated figure")
+    return cast("Figure", fig_temp), ax
+
+
+def _prepare_time_axis(
+    trace: WaveformTrace, time_unit: str
+) -> tuple[str, tuple[NDArray[np.float64], float]]:
+    """Prepare time axis with appropriate unit and scaling."""
     time = trace.time_vector
 
     # Auto-select time unit
@@ -119,8 +162,34 @@ def plot_waveform(
     multiplier = time_multipliers.get(time_unit, 1.0)
     time_scaled = time * multiplier
 
-    # Plot waveform
-    ax.plot(time_scaled, trace.data, color=color, label=label, linewidth=0.8)
+    return time_unit, (time_scaled, multiplier)
+
+
+def _plot_waveform_data(
+    ax: Axes,
+    time_scaled: NDArray[np.float64],
+    data: NDArray[np.float64],
+    color: str,
+    label: str | None,
+) -> None:
+    """Plot waveform data on axes."""
+    ax.plot(time_scaled, data, color=color, label=label, linewidth=0.8)
+
+
+def _apply_waveform_formatting(
+    ax: Axes,
+    time_range: tuple[float, float] | None,
+    time_unit: str,
+    time_info: tuple[NDArray[np.float64], float],
+    xlabel: str,
+    ylabel: str,
+    title: str | None,
+    channel_name: str | None,
+    show_grid: bool,
+    label: str | None,
+) -> None:
+    """Apply formatting to waveform plot."""
+    _, multiplier = time_info
 
     # Apply time range if specified
     if time_range is not None:
@@ -130,33 +199,28 @@ def plot_waveform(
     ax.set_xlabel(f"{xlabel} ({time_unit})")
     ax.set_ylabel(ylabel)
 
+    # Title
     if title:
         ax.set_title(title)
-    elif trace.metadata.channel_name:
-        ax.set_title(f"Waveform - {trace.metadata.channel_name}")
+    elif channel_name:
+        ax.set_title(f"Waveform - {channel_name}")
 
+    # Grid and legend
     if show_grid:
         ax.grid(True, alpha=0.3)
 
     if label:
         ax.legend()
 
-    # Add measurement annotations
-    if show_measurements:
-        _add_measurement_annotations(ax, trace, show_measurements, time_unit, multiplier)
 
-    fig.tight_layout()
-
-    # Save if path provided
+def _save_and_show_figure(fig: Figure, save_path: str | None, show: bool) -> None:
+    """Save and/or display the figure."""
     if save_path is not None:
         fig.savefig(save_path, dpi=300, bbox_inches="tight")
 
-    # Show if requested
     if show:
         plt.show()
 
-    return fig
-
 
 def plot_multi_channel(
     traces: list[WaveformTrace | DigitalTrace],
@@ -193,74 +257,97 @@ def plot_multi_channel(
         >>> fig = plot_multi_channel([ch1, ch2, ch3], names=["CLK", "DATA", "CS"])
         >>> plt.show()
     """
-    # Handle share_x alias
-    if share_x is not None:
-        shared_x = share_x
     if not HAS_MATPLOTLIB:
         raise ImportError("matplotlib is required for visualization")
 
+    shared_x = share_x if share_x is not None else shared_x
     n_channels = len(traces)
+    names = names or [f"CH{i + 1}" for i in range(n_channels)]
+    figsize = figsize or (10, 2 * n_channels)
 
-    if names is None:
-        names = [f"CH{i + 1}" for i in range(n_channels)]
+    fig, axes = plt.subplots(n_channels, 1, figsize=figsize, sharex=shared_x)
+    axes = [axes] if n_channels == 1 else axes
 
-    if figsize is None:
-        figsize = (10, 2 * n_channels)
+    time_unit, multiplier = _determine_time_unit_and_multiplier(time_unit, traces)
 
-    fig, axes = plt.subplots(
-        n_channels,
-        1,
-        figsize=figsize,
-        sharex=shared_x,
-    )
+    _plot_channels(traces, names, axes, colors, time_unit, multiplier, show_grid, n_channels)
 
-    if n_channels == 1:
-        axes = [axes]
+    if title:
+        fig.suptitle(title)
+
+    fig.tight_layout()
+    return fig
 
-    # Auto-select time unit from first trace
+
+def _determine_time_unit_and_multiplier(
+    time_unit: str, traces: list[WaveformTrace | DigitalTrace]
+) -> tuple[str, float]:
+    """Determine time unit and multiplier for plotting."""
     if time_unit == "auto" and len(traces) > 0:
         ref_trace = traces[0]
         duration = len(ref_trace.data) * ref_trace.metadata.time_base
-        if duration < 1e-6:
-            time_unit = "ns"
-        elif duration < 1e-3:
-            time_unit = "us"
-        elif duration < 1:
-            time_unit = "ms"
-        else:
-            time_unit = "s"
+        time_unit = _select_time_unit_from_duration(duration)
 
     time_multipliers = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
     multiplier = time_multipliers.get(time_unit, 1.0)
 
-    for i, (trace, name, ax) in enumerate(zip(traces, names, axes, strict=False)):
-        time = trace.time_vector * multiplier
-        color = colors[i] if colors is not None and i < len(colors) else f"C{i}"
+    return time_unit, multiplier
 
-        if isinstance(trace, WaveformTrace):
-            ax.plot(time, trace.data, color=color, linewidth=0.8)
-            ax.set_ylabel("V")
-        else:
-            # Digital trace - step plot
-            ax.step(time, trace.data.astype(int), color=color, where="post", linewidth=1.0)
-            ax.set_ylim(-0.1, 1.1)
-            ax.set_yticks([0, 1])
-            ax.set_yticklabels(["L", "H"])
 
-        ax.set_ylabel(name, rotation=0, ha="right", va="center")
+def _select_time_unit_from_duration(duration: float) -> str:
+    """Select appropriate time unit based on duration."""
+    if duration < 1e-6:
+        return "ns"
+    if duration < 1e-3:
+        return "us"
+    if duration < 1:
+        return "ms"
+    return "s"
 
-        if show_grid:
-            ax.grid(True, alpha=0.3)
 
-        # Only show x-label on bottom plot
+def _plot_channels(
+    traces: list[WaveformTrace | DigitalTrace],
+    names: list[str],
+    axes: list[Any],
+    colors: list[str] | None,
+    time_unit: str,
+    multiplier: float,
+    show_grid: bool,
+    n_channels: int,
+) -> None:
+    """Plot each channel on its subplot."""
+    for i, (trace, name, ax) in enumerate(zip(traces, names, axes, strict=False)):
+        time = trace.time_vector * multiplier
+        color = colors[i] if colors and i < len(colors) else f"C{i}"
+
+        _plot_single_channel(ax, trace, time, color, name, show_grid)
+
         if i == n_channels - 1:
             ax.set_xlabel(f"Time ({time_unit})")
 
-    if title:
-        fig.suptitle(title)
 
-    fig.tight_layout()
-    return fig
+def _plot_single_channel(
+    ax: Any,
+    trace: WaveformTrace | DigitalTrace,
+    time: Any,
+    color: str,
+    name: str,
+    show_grid: bool,
+) -> None:
+    """Plot a single channel (analog or digital)."""
+    if isinstance(trace, WaveformTrace):
+        ax.plot(time, trace.data, color=color, linewidth=0.8)
+        ax.set_ylabel("V")
+    else:
+        ax.step(time, trace.data.astype(int), color=color, where="post", linewidth=1.0)
+        ax.set_ylim(-0.1, 1.1)
+        ax.set_yticks([0, 1])
+        ax.set_yticklabels(["L", "H"])
+
+    ax.set_ylabel(name, rotation=0, ha="right", va="center")
+
+    if show_grid:
+        ax.grid(True, alpha=0.3)
 
 
 def plot_xy(

oscura/workflows/__init__.py

@@ -16,6 +16,7 @@ Example:
     >>> stats = osc.workflows.load_all(["trace1.wfm", "trace2.wfm"])
 """
 
+from oscura.workflows.complete_re import CompleteREResult, full_protocol_re
 from oscura.workflows.compliance import emc_compliance_test
 from oscura.workflows.digital import characterize_buffer
 from oscura.workflows.multi_trace import (
@@ -40,6 +41,7 @@ __all__ = [
     # Multi-trace
     "AlignmentMethod",
     # Reverse engineering
+    "CompleteREResult",
     "FieldSpec",
     "InferredFrame",
     "MultiTraceResults",
@@ -51,6 +53,7 @@ __all__ = [
     "characterize_buffer",
     "debug_protocol",
     "emc_compliance_test",
+    "full_protocol_re",
     "load_all",
     "power_analysis",
     "reverse_engineer_signal",

oscura/{batch → workflows/batch}/__init__.py

@@ -5,23 +5,23 @@ This module enables efficient batch analysis of multiple signal files
 with parallel execution support and comprehensive result aggregation.
 """
 
-from oscura.batch.advanced import (
+from oscura.workflows.batch.advanced import (
     AdvancedBatchProcessor,
     BatchCheckpoint,
     BatchConfig,
     FileResult,
     resume_batch,
 )
-from oscura.batch.aggregate import aggregate_results
-from oscura.batch.analyze import batch_analyze
-from oscura.batch.logging import (
+from oscura.workflows.batch.aggregate import aggregate_results
+from oscura.workflows.batch.analyze import batch_analyze
+from oscura.workflows.batch.logging import (
     BatchLogger,
     BatchSummary,
     FileLogEntry,
     FileLogger,
     aggregate_batch_logs,
 )
-from oscura.batch.metrics import (
+from oscura.workflows.batch.metrics import (
     BatchMetrics,
     BatchMetricsSummary,
     ErrorBreakdown,