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

oscura/visualization/thumbnails.py

@@ -1,340 +0,0 @@
-"""Thumbnail rendering for fast signal previews.
-
-This module provides fast preview rendering with reduced detail
-for gallery and browser contexts.
-
-
-Example:
-    >>> from oscura.visualization.thumbnails import render_thumbnail
-    >>> fig = render_thumbnail(signal, sample_rate, size=(400, 300))
-
-References:
-    Aggressive decimation for performance
-    Simplified rendering without expensive features
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Any
-
-import numpy as np
-
-if TYPE_CHECKING:
-    from matplotlib.figure import Figure
-    from numpy.typing import NDArray
-
-try:
-    import matplotlib  # noqa: F401
-    import matplotlib.pyplot as plt
-
-    HAS_MATPLOTLIB = True
-except ImportError:
-    HAS_MATPLOTLIB = False
-
-
-def render_thumbnail(
-    signal: NDArray[np.float64],
-    sample_rate: float | None = None,
-    *,
-    size: tuple[int, int] = (400, 300),
-    width: int | None = None,
-    height: int | None = None,
-    max_samples: int = 1000,
-    time_unit: str = "auto",
-    title: str | None = None,
-    dpi: int = 72,
-) -> Figure:
-    """Render fast preview thumbnail of signal.
-
-    : Fast preview rendering mode with reduced detail,
-    simplified styles, and lower resolution for quick plot generation.
-
-    Target performance: <100ms for typical signals (goal: 50ms)
-
-    Args:
-        signal: Input signal array
-        sample_rate: Sample rate in Hz. If None, uses 1.0 (sample indices as x-axis).
-        size: Thumbnail size in pixels (width, height), default (400, 300)
-        width: Width in pixels (alternative to size). If specified, height defaults to 3/4 of width.
-        height: Height in pixels (alternative to size).
-        max_samples: Maximum samples to plot (default: 1000, aggressive decimation)
-        time_unit: Time unit for x-axis ("s", "ms", "us", "ns", "auto")
-        title: Optional title
-        dpi: DPI for rendering (default: 72)
-
-    Returns:
-        Matplotlib Figure object configured for fast rendering
-
-    Raises:
-        ValueError: If signal is empty or sample_rate is invalid
-        ImportError: If matplotlib is not available
-
-    Example:
-        >>> signal = np.sin(2*np.pi*1000*np.arange(0, 0.01, 1/1e6))
-        >>> fig = render_thumbnail(signal, 1e6, size=(400, 300))
-        >>> fig.savefig("preview.png")
-        >>> # Without sample rate
-        >>> fig = render_thumbnail(data, width=100, height=50)
-
-    References:
-        VIS-018: Thumbnail Mode
-        Fixed-count decimation for uniform sampling
-    """
-    if not HAS_MATPLOTLIB:
-        raise ImportError("matplotlib is required for visualization")
-
-    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:
-        raise ValueError("Sample rate must be positive")
-    if max_samples < 10:
-        raise ValueError("max_samples must be >= 10")
-
-
-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)
-        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]:
-    """Decimate signal to exactly target_samples using uniform stride.
-
-    Args:
-        signal: Input signal
-        target_samples: Target number of samples
-
-    Returns:
-        Decimated signal with exactly target_samples
-    """
-    if len(signal) <= target_samples:
-        return signal
-
-    # Calculate uniform stride
-    stride = len(signal) // target_samples
-
-    # Sample at uniform intervals
-    indices = np.arange(0, len(signal), stride)[:target_samples]
-
-    decimated: NDArray[np.float64] = signal[indices]
-    return decimated
-
-
-def render_thumbnail_multichannel(
-    signals: list[NDArray[np.float64]],
-    sample_rate: float,
-    *,
-    size: tuple[int, int] = (400, 300),
-    max_samples: int = 1000,
-    time_unit: str = "auto",
-    channel_names: list[str] | None = None,
-    dpi: int = 72,
-) -> Figure:
-    """Render fast preview thumbnail of multiple channels.
-
-    : Fast multi-channel preview rendering.
-
-    Args:
-        signals: List of signal arrays
-        sample_rate: Sample rate in Hz
-        size: Thumbnail size in pixels (width, height)
-        max_samples: Maximum samples per channel
-        time_unit: Time unit for x-axis
-        channel_names: Optional channel names
-        dpi: DPI for rendering
-
-    Returns:
-        Matplotlib Figure object
-
-    Raises:
-        ValueError: If inputs are invalid
-        ImportError: If matplotlib is not available
-
-    Example:
-        >>> signals = [ch1_data, ch2_data, ch3_data]
-        >>> fig = render_thumbnail_multichannel(signals, 1e6)
-
-    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)
-
-    for i, (sig, name, ax) in enumerate(zip(signals, names, axes, strict=False)):
-        if len(sig) == 0:
-            continue
-
-        decimated = _decimate_uniform(sig, max_samples)
-        total_time = len(sig) / sample_rate
-        time = np.linspace(0, total_time, len(decimated)) * multiplier
-
-        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)
-
-        if i == n_channels - 1:
-            ax.set_xlabel(f"Time ({time_unit})", fontsize=8)
-
-
-__all__ = [
-    "render_thumbnail",
-    "render_thumbnail_multichannel",
-]

oscura/visualization/time_axis.py

@@ -1,351 +0,0 @@
-"""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",
-]