oscura 0.0.1__py3-none-any.whl → 0.1.0__py3-none-any.whl

oscura/visualization/time_axis.py

@@ -0,0 +1,351 @@
+"""Time-aware X-axis formatting and optimization.
+
+This module provides intelligent time axis formatting with automatic unit
+selection, relative time offsets, and cursor readout with full precision.
+
+
+Example:
+    >>> from oscura.visualization.time_axis import format_time_axis
+    >>> labels = format_time_axis(time_values, unit="auto")
+
+References:
+    - SI prefixes for time units
+    - IEEE publication time axis standards
+    - Matplotlib formatter customization
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from numpy.typing import NDArray
+
+TimeUnit = Literal["s", "ms", "us", "ns", "ps", "auto"]
+
+
+def select_time_unit(
+    time_range: float,
+    *,
+    prefer_larger: bool = False,
+) -> TimeUnit:
+    """Automatically select appropriate time unit based on range.
+
+    Args:
+        time_range: Time range in seconds.
+        prefer_larger: Prefer larger units when ambiguous.
+
+    Returns:
+        Selected time unit ("s", "ms", "us", "ns", "ps").
+
+    Example:
+        >>> select_time_unit(0.001)  # 1 ms
+        'ms'
+        >>> select_time_unit(1e-6)  # 1 us
+        'us'
+
+    References:
+        VIS-014: Adaptive X-Axis Time Window
+    """
+    if time_range >= 1.0:
+        return "s"
+    elif time_range >= 1e-3:
+        return "ms" if not prefer_larger else "s"
+    elif time_range >= 1e-6:
+        return "us" if not prefer_larger else "ms"
+    elif time_range >= 1e-9:
+        return "ns" if not prefer_larger else "us"
+    else:
+        return "ps" if not prefer_larger else "ns"
+
+
+def convert_time_values(
+    time: NDArray[np.float64],
+    unit: TimeUnit,
+) -> NDArray[np.float64]:
+    """Convert time values to specified unit.
+
+    Args:
+        time: Time array in seconds.
+        unit: Target time unit.
+
+    Returns:
+        Time array in target unit.
+
+    Raises:
+        ValueError: If unit is invalid.
+
+    Example:
+        >>> time_s = np.array([0.001, 0.002, 0.003])
+        >>> time_ms = convert_time_values(time_s, "ms")
+        >>> # Returns [1.0, 2.0, 3.0]
+
+    References:
+        VIS-014: Adaptive X-Axis Time Window
+    """
+    multipliers = {
+        "s": 1.0,
+        "ms": 1e3,
+        "us": 1e6,
+        "ns": 1e9,
+        "ps": 1e12,
+    }
+
+    if unit == "auto":
+        time_range = float(np.ptp(time))
+        unit = select_time_unit(time_range)
+
+    if unit not in multipliers:
+        raise ValueError(f"Invalid time unit: {unit}")
+
+    return time * multipliers[unit]
+
+
+def format_time_labels(
+    time: NDArray[np.float64],
+    unit: TimeUnit = "auto",
+    *,
+    precision: int | None = None,
+    scientific_threshold: float = 1e6,
+) -> list[str]:
+    """Format time values as labels with appropriate precision.
+
+    Args:
+        time: Time array in seconds.
+        unit: Time unit ("s", "ms", "us", "ns", "ps", "auto").
+        precision: Number of decimal places (auto if None).
+        scientific_threshold: Use scientific notation above this value.
+
+    Returns:
+        List of formatted time labels.
+
+    Example:
+        >>> time = np.array([0.0, 0.001, 0.002])
+        >>> labels = format_time_labels(time, unit="ms")
+        >>> # Returns ['0', '1', '2']
+
+    References:
+        VIS-014: Adaptive X-Axis Time Window
+    """
+    # Convert to target unit
+    time_converted = convert_time_values(time, unit)
+
+    # Auto-select precision based on value range
+    if precision is None:
+        value_range = np.ptp(time_converted)
+        if value_range == 0:
+            precision = 1
+        else:
+            # Use enough precision to show differences
+            magnitude = np.log10(value_range)
+            precision = max(0, int(np.ceil(2 - magnitude)))
+
+    # Format labels
+    labels = []
+    for val in time_converted:
+        if abs(val) >= scientific_threshold:
+            # Scientific notation
+            labels.append(f"{val:.{precision}e}")
+        else:
+            # Fixed point
+            labels.append(f"{val:.{precision}f}".rstrip("0").rstrip("."))
+
+    return labels
+
+
+def create_relative_time(
+    time: NDArray[np.float64],
+    *,
+    start_at_zero: bool = True,
+    reference_time: float | None = None,
+) -> NDArray[np.float64]:
+    """Create relative time axis starting at zero or reference.
+
+    Args:
+        time: Absolute time array in seconds.
+        start_at_zero: Start time axis at t=0.
+        reference_time: Reference time (uses first sample if None).
+
+    Returns:
+        Relative time array.
+
+    Example:
+        >>> time_abs = np.array([1000.5, 1000.6, 1000.7])
+        >>> time_rel = create_relative_time(time_abs)
+        >>> # Returns [0.0, 0.1, 0.2]
+
+    References:
+        VIS-014: Adaptive X-Axis Time Window
+    """
+    if len(time) == 0:
+        return time
+
+    if reference_time is None:
+        reference_time = time[0] if start_at_zero else 0.0
+
+    return time - reference_time
+
+
+def calculate_major_ticks(
+    time_min: float,
+    time_max: float,
+    *,
+    target_count: int = 7,
+    unit: TimeUnit = "auto",
+) -> NDArray[np.float64]:
+    """Calculate major tick positions for time axis.
+
+    Args:
+        time_min: Minimum time value in seconds.
+        time_max: Maximum time value in seconds.
+        target_count: Target number of major ticks.
+        unit: Time unit for tick alignment.
+
+    Returns:
+        Array of major tick positions in seconds.
+
+    Example:
+        >>> ticks = calculate_major_ticks(0, 0.01, target_count=5, unit="ms")
+
+    References:
+        VIS-014: Adaptive X-Axis Time Window
+        VIS-019: Grid Auto-Spacing
+    """
+    time_range = time_max - time_min
+
+    if time_range <= 0:
+        return np.array([time_min])
+
+    # Select unit if auto
+    if unit == "auto":
+        unit = select_time_unit(time_range)
+
+    # Convert to selected unit
+    multipliers = {
+        "s": 1.0,
+        "ms": 1e3,
+        "us": 1e6,
+        "ns": 1e9,
+        "ps": 1e12,
+    }
+    multiplier = multipliers[unit]
+
+    time_min_unit = time_min * multiplier
+    time_max_unit = time_max * multiplier
+    range_unit = time_max_unit - time_min_unit
+
+    # Calculate rough spacing
+    rough_spacing = range_unit / target_count
+
+    # Round to nice number
+    nice_spacing = _round_to_nice_time(rough_spacing)
+
+    # Generate ticks
+    first_tick = np.ceil(time_min_unit / nice_spacing) * nice_spacing
+    n_ticks = int((time_max_unit - first_tick) / nice_spacing) + 1
+
+    ticks_unit = first_tick + np.arange(n_ticks) * nice_spacing
+
+    # Convert back to seconds
+    ticks = ticks_unit / multiplier
+
+    # Filter to range
+    filtered_ticks: NDArray[np.float64] = ticks[(ticks >= time_min) & (ticks <= time_max)]
+
+    return filtered_ticks
+
+
+def _round_to_nice_time(value: float) -> float:
+    """Round to nice time value (1, 2, 5, 10, 20, 50 × 10^n).  # noqa: RUF002
+
+    Args:
+        value: Value to round.
+
+    Returns:
+        Nice rounded value.
+    """
+    if value <= 0:
+        return 1.0
+
+    exponent = np.floor(np.log10(value))
+    mantissa = value / (10**exponent)
+
+    # Nice fractions for time
+    nice_fractions = [1.0, 2.0, 5.0, 10.0]
+
+    # Find closest
+    distances = [abs(f - mantissa) for f in nice_fractions]
+    min_idx = np.argmin(distances)
+    nice_mantissa = nice_fractions[min_idx]
+
+    # Handle overflow
+    if nice_mantissa >= 10.0:
+        nice_mantissa = 1.0
+        exponent += 1
+
+    return nice_mantissa * (10**exponent)  # type: ignore[no-any-return]
+
+
+def format_cursor_readout(
+    time_value: float,
+    *,
+    unit: TimeUnit = "auto",
+    full_precision: bool = True,
+) -> str:
+    """Format time value for cursor readout with full precision.
+
+    Args:
+        time_value: Time value in seconds.
+        unit: Display unit.
+        full_precision: Show full floating-point precision.
+
+    Returns:
+        Formatted time string.
+
+    Example:
+        >>> readout = format_cursor_readout(1.23456789e-6, unit="us")
+        >>> # Returns "1.23456789 μs"
+
+    References:
+        VIS-014: Adaptive X-Axis Time Window (cursor readout)
+    """
+    # Select unit if auto
+    if unit == "auto":
+        unit = select_time_unit(abs(time_value))
+
+    # Convert to unit
+    time_converted = convert_time_values(np.array([time_value]), unit)[0]
+
+    # Unit symbols
+    unit_symbols = {
+        "s": "s",
+        "ms": "ms",
+        "us": "μs",
+        "ns": "ns",
+        "ps": "ps",
+    }
+
+    symbol = unit_symbols.get(unit, unit)
+
+    # Format with appropriate precision
+    if full_precision:
+        # Maximum useful precision (avoid floating point noise)
+        formatted = f"{time_converted:.12g}"
+    else:
+        # Standard precision
+        formatted = f"{time_converted:.6g}"
+
+    return f"{formatted} {symbol}"
+
+
+__all__ = [
+    "TimeUnit",
+    "calculate_major_ticks",
+    "convert_time_values",
+    "create_relative_time",
+    "format_cursor_readout",
+    "format_time_labels",
+    "select_time_unit",
+]

oscura/visualization/waveform.py

@@ -0,0 +1,367 @@
+"""Waveform visualization functions.
+
+This module provides time-domain waveform and multi-channel plots
+with measurement annotations.
+
+
+Example:
+    >>> from oscura.visualization.waveform import plot_waveform, plot_multi_channel
+    >>> plot_waveform(trace)
+    >>> plot_multi_channel([ch1, ch2, ch3])
+
+References:
+    matplotlib best practices for scientific visualization
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+import numpy as np
+
+try:
+    import matplotlib.pyplot as plt
+
+    HAS_MATPLOTLIB = True
+except ImportError:
+    HAS_MATPLOTLIB = False
+
+from oscura.core.types import DigitalTrace, WaveformTrace
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+    from numpy.typing import NDArray
+
+
+def plot_waveform(
+    trace: WaveformTrace,
+    *,
+    ax: Axes | None = None,
+    time_unit: str = "auto",
+    time_range: tuple[float, float] | None = None,
+    show_grid: bool = True,
+    color: str = "C0",
+    label: str | None = None,
+    show_measurements: dict[str, Any] | None = None,
+    title: str | None = None,
+    xlabel: str = "Time",
+    ylabel: str = "Amplitude",
+    show: bool = True,
+    save_path: str | None = None,
+    figsize: tuple[float, float] = (10, 6),
+) -> Figure:
+    """Plot time-domain waveform.
+
+    Args:
+        trace: Waveform trace to plot.
+        ax: Matplotlib axes. If None, creates new figure.
+        time_unit: Time unit ("s", "ms", "us", "ns", "auto").
+        time_range: Optional (start, end) time range in seconds to display.
+        show_grid: Show grid lines.
+        color: Line color.
+        label: Legend label.
+        show_measurements: Dictionary of measurements to annotate.
+        title: Plot title.
+        xlabel: X-axis label (appended with time unit).
+        ylabel: Y-axis label.
+        show: If True, call plt.show() to display the plot.
+        save_path: Path to save the figure. If None, figure is not saved.
+        figsize: Figure size (width, height) in inches. Only used if ax is None.
+
+    Returns:
+        Matplotlib Figure object.
+
+    Raises:
+        ImportError: If matplotlib is not installed.
+        ValueError: If axes has no associated figure.
+
+    Example:
+        >>> import oscura as tk
+        >>> trace = tk.load("signal.wfm")
+        >>> fig = tk.plot_waveform(trace, time_unit="us", show=False)
+        >>> fig.savefig("waveform.png")
+
+        >>> # With custom styling
+        >>> fig = tk.plot_waveform(trace,
+        ...                        title="Captured Signal",
+        ...                        xlabel="Time",
+        ...                        ylabel="Voltage",
+        ...                        color="blue")
+    """
+    if not HAS_MATPLOTLIB:
+        raise ImportError("matplotlib is required for visualization")
+
+    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)
+
+    # Calculate time axis
+    time = trace.time_vector
+
+    # Auto-select time unit
+    if time_unit == "auto":
+        duration = time[-1] if len(time) > 0 else 0
+        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)
+    time_scaled = time * multiplier
+
+    # Plot waveform
+    ax.plot(time_scaled, trace.data, color=color, label=label, linewidth=0.8)
+
+    # Apply time range if specified
+    if time_range is not None:
+        ax.set_xlim(time_range[0] * multiplier, time_range[1] * multiplier)
+
+    # Labels
+    ax.set_xlabel(f"{xlabel} ({time_unit})")
+    ax.set_ylabel(ylabel)
+
+    if title:
+        ax.set_title(title)
+    elif trace.metadata.channel_name:
+        ax.set_title(f"Waveform - {trace.metadata.channel_name}")
+
+    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
+    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],
+    *,
+    names: list[str] | None = None,
+    shared_x: bool = True,
+    share_x: bool | None = None,
+    colors: list[str] | None = None,
+    time_unit: str = "auto",
+    show_grid: bool = True,
+    figsize: tuple[float, float] | None = None,
+    title: str | None = None,
+) -> Figure:
+    """Plot multiple channels in stacked subplots.
+
+    Args:
+        traces: List of traces to plot.
+        names: Channel names for labels.
+        shared_x: Share x-axis across subplots.
+        share_x: Alias for shared_x (for compatibility).
+        colors: List of colors for each trace. If None, uses default cycle.
+        time_unit: Time unit ("s", "ms", "us", "ns", "auto").
+        show_grid: Show grid lines.
+        figsize: Figure size (width, height) in inches.
+        title: Overall figure title.
+
+    Returns:
+        Matplotlib Figure object.
+
+    Raises:
+        ImportError: If matplotlib is not available.
+
+    Example:
+        >>> 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")
+
+    n_channels = len(traces)
+
+    if names is None:
+        names = [f"CH{i + 1}" for i in range(n_channels)]
+
+    if figsize is None:
+        figsize = (10, 2 * n_channels)
+
+    fig, axes = plt.subplots(
+        n_channels,
+        1,
+        figsize=figsize,
+        sharex=shared_x,
+    )
+
+    if n_channels == 1:
+        axes = [axes]
+
+    # Auto-select time unit from first trace
+    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_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}"
+
+        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")
+
+        if show_grid:
+            ax.grid(True, alpha=0.3)
+
+        # Only show x-label on bottom plot
+        if i == n_channels - 1:
+            ax.set_xlabel(f"Time ({time_unit})")
+
+    if title:
+        fig.suptitle(title)
+
+    fig.tight_layout()
+    return fig
+
+
+def plot_xy(
+    x_trace: WaveformTrace | NDArray[np.float64],
+    y_trace: WaveformTrace | NDArray[np.float64],
+    *,
+    ax: Axes | None = None,
+    color: str = "C0",
+    marker: str = "",
+    alpha: float = 0.7,
+    title: str | None = None,
+) -> Figure:
+    """Plot X-Y (Lissajous) diagram.
+
+    Args:
+        x_trace: X-axis waveform.
+        y_trace: Y-axis waveform.
+        ax: Matplotlib axes.
+        color: Line/marker color.
+        marker: Marker style.
+        alpha: Transparency.
+        title: Plot title.
+
+    Returns:
+        Matplotlib Figure object.
+
+    Raises:
+        ImportError: If matplotlib is not available.
+        ValueError: If axes has no associated figure.
+
+    Example:
+        >>> fig = plot_xy(ch1, ch2)  # Phase relationship
+    """
+    if not HAS_MATPLOTLIB:
+        raise ImportError("matplotlib is required for visualization")
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(6, 6))
+    else:
+        fig_temp = ax.get_figure()
+        if fig_temp is None:
+            raise ValueError("Axes must have an associated figure")
+        fig = cast("Figure", fig_temp)
+
+    x_data = x_trace.data if isinstance(x_trace, WaveformTrace) else x_trace
+    y_data = y_trace.data if isinstance(y_trace, WaveformTrace) else y_trace
+
+    # Ensure same length
+    min_len = min(len(x_data), len(y_data))
+    x_data = x_data[:min_len]
+    y_data = y_data[:min_len]
+
+    ax.plot(x_data, y_data, color=color, marker=marker, alpha=alpha, linewidth=0.5)
+
+    ax.set_xlabel("X (V)")
+    ax.set_ylabel("Y (V)")
+    ax.set_aspect("equal")
+    ax.grid(True, alpha=0.3)
+
+    if title:
+        ax.set_title(title)
+
+    fig.tight_layout()
+    return fig
+
+
+def _add_measurement_annotations(
+    ax: Axes,
+    trace: WaveformTrace,
+    measurements: dict[str, Any],
+    time_unit: str,
+    multiplier: float,
+) -> None:
+    """Add measurement annotations to plot."""
+    # Create annotation text
+    text_lines = []
+
+    for name, value in measurements.items():
+        if isinstance(value, dict):
+            val = value.get("value", value)
+            unit = value.get("unit", "")
+            if isinstance(val, float) and not np.isnan(val):
+                text_lines.append(f"{name}: {val:.4g} {unit}")
+        elif isinstance(value, float) and not np.isnan(value):
+            text_lines.append(f"{name}: {value:.4g}")
+
+    if text_lines:
+        text = "\n".join(text_lines)
+        ax.annotate(
+            text,
+            xy=(0.02, 0.98),
+            xycoords="axes fraction",
+            verticalalignment="top",
+            fontfamily="monospace",
+            fontsize=8,
+            bbox={"boxstyle": "round", "facecolor": "wheat", "alpha": 0.8},
+        )
+
+
+__all__ = [
+    "plot_multi_channel",
+    "plot_waveform",
+    "plot_xy",
+]