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

oscura/{testing → validation/testing}/__init__.py

@@ -14,12 +14,12 @@ These functions return WaveformTrace objects ready for use:
 - generate_pulse: Single pulse with configurable rise/fall times
 
 Example:
-    >>> from oscura.testing import generate_sine_wave, generate_square_wave
+    >>> from oscura.validation.testing import generate_sine_wave, generate_square_wave
     >>> sine = generate_sine_wave(frequency=1e6, amplitude=1.0)
     >>> square = generate_square_wave(frequency=500e3, duty_cycle=0.3)
 """
 
-from oscura.testing.synthetic import (
+from oscura.validation.testing.synthetic import (
     GroundTruth,
     SyntheticDataGenerator,
     SyntheticMessageConfig,

oscura/{testing → validation/testing}/synthetic.py

@@ -443,7 +443,7 @@ def generate_sine_wave(
         WaveformTrace containing the sine wave.
 
     Example:
-        >>> from oscura.testing import generate_sine_wave
+        >>> from oscura.validation.testing import generate_sine_wave
         >>> trace = generate_sine_wave(frequency=1e6, amplitude=1.0)
         >>> print(f"Samples: {len(trace.data)}")
     """
@@ -483,7 +483,7 @@ def generate_square_wave(
         WaveformTrace containing the square wave.
 
     Example:
-        >>> from oscura.testing import generate_square_wave
+        >>> from oscura.validation.testing import generate_square_wave
         >>> trace = generate_square_wave(frequency=500e3, duty_cycle=0.3)
     """
     num_samples = int(sample_rate * duration)
@@ -520,7 +520,7 @@ def generate_dc(
         WaveformTrace containing the DC signal.
 
     Example:
-        >>> from oscura.testing import generate_dc
+        >>> from oscura.validation.testing import generate_dc
         >>> trace = generate_dc(level=1.5, duration=10e-6)
     """
     num_samples = int(sample_rate * duration)
@@ -559,7 +559,7 @@ def generate_multi_tone(
         ValueError: If frequencies, amplitudes, and phases have different lengths.
 
     Example:
-        >>> from oscura.testing import generate_multi_tone
+        >>> from oscura.validation.testing import generate_multi_tone
         >>> trace = generate_multi_tone(
         ...     frequencies=[1e6, 2.5e6, 4e6],
         ...     amplitudes=[1.0, 0.5, 0.25]
@@ -616,7 +616,7 @@ def generate_pulse(
         WaveformTrace containing the pulse.
 
     Example:
-        >>> from oscura.testing import generate_pulse
+        >>> from oscura.validation.testing import generate_pulse
         >>> trace = generate_pulse(width=1e-6, rise_time=10e-9)
     """
     num_samples = int(sample_rate * duration)

oscura/visualization/__init__.py

@@ -3,6 +3,11 @@
 Provides plotting functions for waveforms, spectra, and other signal data,
 plus optimization utilities, style presets, and intelligent rendering.
 
+**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
 
 Example:
     >>> from oscura.visualization import plot_waveform, plot_spectrum
@@ -15,6 +20,10 @@ Example:
     ...     plt.savefig("figure.pdf")
 """
 
+# 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 (

oscura/visualization/accessibility.py

@@ -111,7 +111,7 @@ def get_multi_line_styles(n_lines: int) -> list[tuple[tuple[float, float, float,
     for i in range(n_lines):
         linestyle = LINE_STYLES[i % len(LINE_STYLES)]
         # Colors from colormap are RGBA tuples
-        rgba_color = tuple(colors[i])  # type: ignore[arg-type]
+        rgba_color = tuple(colors[i])
         styles.append((rgba_color, linestyle))  # type: ignore[arg-type]
 
     return styles

oscura/visualization/annotations.py

@@ -20,6 +20,8 @@ from dataclasses import dataclass
 
 import numpy as np
 
+from oscura.utils.geometry import generate_leader_line
+
 
 @dataclass
 class Annotation:
@@ -106,57 +108,84 @@ def place_annotations(
     if len(annotations) == 0:
         return []
 
-    # Filter by viewport if specified
-    if viewport is not None:
-        x_min, x_max = viewport
-        visible_annots = [a for a in annotations if x_min <= a.x <= x_max]
-    else:
-        visible_annots = annotations
-
-    # Apply density limiting - keep only top priority annotations
-    if len(visible_annots) > density_limit:
-        # Sort by priority (descending)
-        sorted_annots = sorted(
-            visible_annots,
-            key=lambda a: a.priority,
-            reverse=True,
-        )
-        visible_annots = sorted_annots[:density_limit]
-
-    # Initialize placed annotations at anchor points
-    placed = []
-    for annot in visible_annots:
-        placed.append(
-            PlacedAnnotation(
-                annotation=annot,
-                display_x=annot.x,
-                display_y=annot.y,
-                visible=True,
-                needs_leader=False,
-            )
+    # Filter and limit annotations
+    visible_annots = _filter_by_viewport(annotations, viewport)
+    visible_annots = _apply_density_limit(visible_annots, density_limit)
+
+    # Initialize placement
+    placed = _initialize_placements(visible_annots)
+
+    # Resolve collisions
+    _resolve_collisions(placed, collision_threshold, max_iterations)
+
+    # Add leader lines where needed
+    _add_leader_lines(placed, leader_threshold=30.0)
+
+    return placed
+
+
+def _filter_by_viewport(
+    annotations: list[Annotation],
+    viewport: tuple[float, float] | None,
+) -> list[Annotation]:
+    """Filter annotations by viewport range."""
+    if viewport is None:
+        return annotations
+
+    x_min, x_max = viewport
+    return [a for a in annotations if x_min <= a.x <= x_max]
+
+
+def _apply_density_limit(
+    annotations: list[Annotation],
+    density_limit: int,
+) -> list[Annotation]:
+    """Apply density limiting by keeping top priority annotations."""
+    if len(annotations) <= density_limit:
+        return annotations
+
+    sorted_annots = sorted(annotations, key=lambda a: a.priority, reverse=True)
+    return sorted_annots[:density_limit]
+
+
+def _initialize_placements(annotations: list[Annotation]) -> list[PlacedAnnotation]:
+    """Initialize placed annotations at anchor points."""
+    return [
+        PlacedAnnotation(
+            annotation=annot,
+            display_x=annot.x,
+            display_y=annot.y,
+            visible=True,
+            needs_leader=False,
         )
+        for annot in annotations
+    ]
 
-    # Resolve collisions using iterative adjustment
+
+def _resolve_collisions(
+    placed: list[PlacedAnnotation],
+    collision_threshold: float,
+    max_iterations: int,
+) -> None:
+    """Resolve collisions using iterative adjustment."""
     for _iteration in range(max_iterations):
         moved = False
 
-        # Check all pairs for collisions
         for i in range(len(placed)):
             for j in range(i + 1, len(placed)):
                 if _check_collision(placed[i], placed[j], collision_threshold):
-                    # Resolve collision by moving lower-priority annotation
+                    # Move lower-priority annotation
                     if placed[i].annotation.priority >= placed[j].annotation.priority:
                         moved = _move_annotation(placed[j], placed[i], collision_threshold) or moved
                     else:
                         moved = _move_annotation(placed[i], placed[j], collision_threshold) or moved
 
-        # Converged if nothing moved
         if not moved:
             break
 
-    # Determine which annotations need leader lines
-    leader_threshold = 30.0  # pixels
 
+def _add_leader_lines(placed: list[PlacedAnnotation], leader_threshold: float) -> None:
+    """Add leader lines for displaced annotations."""
     for p in placed:
         dx = abs(p.display_x - p.annotation.x)
         dy = abs(p.display_y - p.annotation.y)
@@ -164,13 +193,11 @@ def place_annotations(
 
         if displacement > leader_threshold:
             p.needs_leader = True
-            p.leader_points = _generate_leader_line(
+            p.leader_points = generate_leader_line(
                 (p.annotation.x, p.annotation.y),
                 (p.display_x, p.display_y),
             )
 
-    return placed
-
 
 def _check_collision(
     p1: PlacedAnnotation,
@@ -246,36 +273,6 @@ def _move_annotation(
     return False
 
 
-def _generate_leader_line(
-    anchor: tuple[float, float],
-    label: tuple[float, float],
-) -> list[tuple[float, float]]:
-    """Generate orthogonal leader line from anchor to label.
-
-    Args:
-        anchor: Anchor point (x, y)
-        label: Label position (x, y)
-
-    Returns:
-        List of points for leader line
-    """
-    ax, ay = anchor
-    lx, ly = label
-
-    # L-shaped leader line
-    dx = abs(lx - ax)
-    dy = abs(ly - ay)
-
-    if dx > dy:
-        # Horizontal-first
-        mid = (lx, ay)
-    else:
-        # Vertical-first
-        mid = (ax, ly)
-
-    return [anchor, mid, label]
-
-
 def filter_by_zoom_level(
     placed: list[PlacedAnnotation],
     zoom_range: tuple[float, float],

oscura/visualization/colors.py

@@ -256,7 +256,7 @@ def _adjust_for_contrast(
     b = int(color_val[4:6], 16)
 
     # Convert to HSL for easier lightness adjustment
-    h, s, l = _rgb_to_hsl(r, g, b)  # noqa: E741
+    h, s, l = _rgb_to_hsl(r, g, b)
 
     bg_lum = _relative_luminance(background)
 
@@ -280,18 +280,18 @@ def _adjust_for_contrast(
             if bg_lum > 0.5:
                 # Dark background - make lighter
                 l_min = l
-                l = (l + l_max) / 2  # noqa: E741
+                l = (l + l_max) / 2
             else:
                 # Light background - make darker
                 l_max = l
-                l = (l_min + l) / 2  # noqa: E741
+                l = (l_min + l) / 2
         # Too much contrast - move back
         elif bg_lum > 0.5:
             l_max = l
-            l = (l_min + l) / 2  # noqa: E741
+            l = (l_min + l) / 2
         else:
             l_min = l
-            l = (l + l_max) / 2  # noqa: E741
+            l = (l + l_max) / 2
 
         iterations += 1
 
@@ -319,7 +319,7 @@ def _rgb_to_hsl(r: int, g: int, b: int) -> tuple[float, float, float]:
     delta = max_c - min_c
 
     # Lightness
-    l = (max_c + min_c) / 2.0  # noqa: E741
+    l = (max_c + min_c) / 2.0
 
     if delta == 0:
         # Achromatic
@@ -341,7 +341,7 @@ def _rgb_to_hsl(r: int, g: int, b: int) -> tuple[float, float, float]:
     return (h, s, l)
 
 
-def _hsl_to_rgb(h: float, s: float, l: float) -> tuple[int, int, int]:  # noqa: E741
+def _hsl_to_rgb(h: float, s: float, l: float) -> tuple[int, int, int]:
     """Convert HSL to RGB color space.
 
     Args:

oscura/visualization/digital.py

@@ -38,6 +38,172 @@ if TYPE_CHECKING:
     from oscura.analyzers.protocols.base import Annotation
 
 
+def _validate_timing_inputs(
+    traces: Sequence[WaveformTrace | DigitalTrace],
+    names: list[str] | None,
+) -> tuple[int, list[str]]:
+    """Validate plot_timing inputs and generate default names.
+
+    Args:
+        traces: List of traces to validate.
+        names: Channel names or None for defaults.
+
+    Returns:
+        Tuple of (n_channels, validated_names).
+
+    Raises:
+        ValueError: If traces empty or names length mismatch.
+    """
+    if len(traces) == 0:
+        raise ValueError("traces list cannot be empty")
+
+    n_channels = len(traces)
+
+    if names is None:
+        names = [f"CH{i + 1}" for i in range(n_channels)]
+
+    if len(names) != n_channels:
+        raise ValueError(f"names length ({len(names)}) must match traces ({n_channels})")
+
+    return n_channels, names
+
+
+def _convert_to_digital_traces(
+    traces: Sequence[WaveformTrace | DigitalTrace],
+    threshold: float | str,
+) -> list[DigitalTrace]:
+    """Convert analog traces to digital using threshold.
+
+    Args:
+        traces: List of analog or digital traces.
+        threshold: Threshold for analog-to-digital conversion.
+
+    Returns:
+        List of digital traces.
+    """
+    from oscura.analyzers.digital.extraction import to_digital
+
+    digital_traces: list[DigitalTrace] = []
+    for trace in traces:
+        if isinstance(trace, WaveformTrace):
+            digital_traces.append(to_digital(trace, threshold=threshold))  # type: ignore[arg-type]
+        else:
+            digital_traces.append(trace)
+
+    return digital_traces
+
+
+def _select_time_unit_and_multiplier(
+    digital_traces: list[DigitalTrace],
+    time_unit: str,
+) -> tuple[str, float]:
+    """Select appropriate time unit based on signal duration.
+
+    Args:
+        digital_traces: List of digital traces.
+        time_unit: Time unit ("auto" or specific unit).
+
+    Returns:
+        Tuple of (time_unit, multiplier).
+    """
+    if time_unit == "auto" and len(digital_traces) > 0:
+        ref_trace = digital_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_multipliers = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
+    multiplier = time_multipliers.get(time_unit, 1.0)
+
+    return time_unit, multiplier
+
+
+def _determine_plot_time_range(
+    digital_traces: list[DigitalTrace],
+    time_range: tuple[float, float] | None,
+) -> tuple[float, float]:
+    """Determine start and end times for plot.
+
+    Args:
+        digital_traces: List of digital traces.
+        time_range: User-specified time range or None for auto.
+
+    Returns:
+        Tuple of (start_time, end_time) in seconds.
+    """
+    if time_range is not None:
+        return time_range
+
+    start_time = 0.0
+    end_time = max(trace.duration for trace in digital_traces if len(trace.data) > 0)
+    return start_time, end_time
+
+
+def _plot_timing_channel(
+    ax: Axes,
+    trace: DigitalTrace,
+    name: str,
+    channel_index: int,
+    multiplier: float,
+    time_range: tuple[float, float] | None,
+    show_grid: bool,
+    annotations: list[Annotation] | None,
+    time_unit: str,
+) -> None:
+    """Plot a single channel in the timing diagram.
+
+    Args:
+        ax: Matplotlib axes to plot on.
+        trace: Digital trace to plot.
+        name: Channel name for label.
+        channel_index: Index for color selection.
+        multiplier: Time unit multiplier.
+        time_range: Optional time range to display.
+        show_grid: Show vertical grid lines.
+        annotations: Optional protocol annotations.
+        time_unit: Time unit string.
+    """
+    time = trace.time_vector * multiplier
+
+    # Filter to time range
+    if time_range is not None:
+        start_time, end_time = time_range
+        start_idx = int(np.searchsorted(trace.time_vector, start_time))
+        end_idx = int(np.searchsorted(trace.time_vector, end_time))
+        time = time[start_idx:end_idx]
+        data_slice = trace.data[start_idx:end_idx]
+    else:
+        data_slice = trace.data
+
+    # Plot digital waveform as step function
+    ax.step(
+        time,
+        data_slice.astype(int),
+        where="post",
+        color=f"C{channel_index}",
+        linewidth=1.5,
+    )
+
+    # Set up digital signal display
+    ax.set_ylim(-0.2, 1.2)
+    ax.set_yticks([0, 1])
+    ax.set_yticklabels(["0", "1"])
+    ax.set_ylabel(name, rotation=0, ha="right", va="center", fontweight="bold")
+
+    if show_grid:
+        ax.grid(True, alpha=0.2, axis="x")
+
+    # Add protocol annotations if provided
+    if annotations:
+        _add_protocol_annotations(ax, annotations, multiplier, time_unit)
+
+
 def plot_timing(
     traces: Sequence[WaveformTrace | DigitalTrace],
     *,
@@ -87,108 +253,41 @@ def plot_timing(
     if not HAS_MATPLOTLIB:
         raise ImportError("matplotlib is required for visualization")
 
-    if len(traces) == 0:
-        raise ValueError("traces list cannot be empty")
-
-    n_channels = len(traces)
-
-    if names is None:
-        names = [f"CH{i + 1}" for i in range(n_channels)]
+    # Data preparation/validation
+    n_channels, names = _validate_timing_inputs(traces, names)
+    digital_traces = _convert_to_digital_traces(traces, threshold)
 
-    if len(names) != n_channels:
-        raise ValueError(f"names length ({len(names)}) must match traces ({n_channels})")
+    # Unit/scale selection
+    time_unit, multiplier = _select_time_unit_and_multiplier(digital_traces, time_unit)
+    start_time, end_time = _determine_plot_time_range(digital_traces, time_range)
 
+    # Figure/axes creation
     if figsize is None:
         figsize = (12, 1.5 * n_channels)
 
-    # Convert analog traces to digital
-    from oscura.analyzers.digital.extraction import to_digital
-
-    digital_traces: list[DigitalTrace] = []
-    for trace in traces:
-        if isinstance(trace, WaveformTrace):
-            digital_traces.append(to_digital(trace, threshold=threshold))  # type: ignore[arg-type]
-        else:
-            digital_traces.append(trace)
-
-    # Auto-select time unit from first trace
-    if time_unit == "auto" and len(digital_traces) > 0:
-        ref_trace = digital_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_multipliers = {"s": 1.0, "ms": 1e3, "us": 1e6, "ns": 1e9}
-    multiplier = time_multipliers.get(time_unit, 1.0)
-
-    # Create figure
-    fig, axes = plt.subplots(
-        n_channels,
-        1,
-        figsize=figsize,
-        sharex=True,
-    )
+    fig, axes = plt.subplots(n_channels, 1, figsize=figsize, sharex=True)
 
     if n_channels == 1:
         axes = [axes]
 
-    # Determine time range
-    if time_range is not None:
-        start_time, end_time = time_range
-    else:
-        start_time = 0.0
-        end_time = max(trace.duration for trace in digital_traces if len(trace.data) > 0)
-
+    # Plotting/rendering
     for i, (trace, name, ax) in enumerate(zip(digital_traces, names, axes, strict=False)):
-        time = trace.time_vector * multiplier
-
-        # Filter to time range
-        if time_range is not None:
-            start_idx = int(np.searchsorted(trace.time_vector, start_time))
-            end_idx = int(np.searchsorted(trace.time_vector, end_time))
-            time = time[start_idx:end_idx]
-            data_slice = trace.data[start_idx:end_idx]
-        else:
-            data_slice = trace.data
-
-        # Plot digital waveform as step function
-        ax.step(
-            time,
-            data_slice.astype(int),
-            where="post",
-            color=f"C{i}",
-            linewidth=1.5,
+        channel_annotations = annotations[i] if annotations and i < len(annotations) else None
+        _plot_timing_channel(
+            ax, trace, name, i, multiplier, time_range, show_grid, channel_annotations, time_unit
         )
 
-        # Set up digital signal display
-        ax.set_ylim(-0.2, 1.2)
-        ax.set_yticks([0, 1])
-        ax.set_yticklabels(["0", "1"])
-        ax.set_ylabel(name, rotation=0, ha="right", va="center", fontweight="bold")
-
-        if show_grid:
-            ax.grid(True, alpha=0.2, axis="x")
-
-        # Add protocol annotations if provided
-        if annotations is not None and i < len(annotations) and annotations[i]:
-            _add_protocol_annotations(ax, annotations[i], multiplier, time_unit)
-
         # Remove x-axis labels except for bottom plot
         if i < n_channels - 1:
             ax.set_xticklabels([])
 
-    # Set x-label on bottom plot
+    # Annotation/labeling
     axes[-1].set_xlabel(f"Time ({time_unit})")
 
     if title:
         fig.suptitle(title, fontsize=14, fontweight="bold")
 
+    # Layout/formatting
     fig.tight_layout()
     return fig