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

oscura/visualization/render.py

@@ -1,223 +0,0 @@
-"""Visualization rendering functions for DPI-aware output.
-
-This module provides DPI-aware rendering configuration for adapting
-plot quality and parameters based on target output device (screen vs print).
-
-
-Example:
-    >>> from oscura.visualization.render import configure_dpi_rendering
-    >>> config = configure_dpi_rendering("publication")
-    >>> fig = plt.figure(dpi=config['dpi'], figsize=config['figsize'])
-
-References:
-    - matplotlib DPI scaling best practices
-    - Print quality standards (300-600 DPI)
-"""
-
-from __future__ import annotations
-
-from typing import Any, Literal
-
-RenderPreset = Literal["screen", "print", "publication"]
-
-
-def configure_dpi_rendering(
-    preset: RenderPreset = "screen",
-    *,
-    custom_dpi: int | None = None,
-    dpi: int | None = None,
-    figsize: tuple[float, float] = (10, 6),
-    baseline_dpi: float = 96.0,
-) -> dict[str, Any]:
-    """Configure DPI-aware rendering parameters.
-
-    Adapts plot rendering quality and parameters based on target DPI
-    for print (300-600 DPI) versus screen (72-96 DPI) with export presets.
-
-    Args:
-        preset: Rendering preset ("screen", "print", "publication").
-        custom_dpi: Custom DPI override (ignores preset).
-        dpi: Alias for custom_dpi.
-        figsize: Figure size in inches (width, height).
-        baseline_dpi: Baseline DPI for scaling calculations (default 96).
-
-    Returns:
-        Dictionary with rendering configuration:
-            - dpi: Target DPI
-            - figsize: Figure size
-            - font_scale: Font size scale factor
-            - line_scale: Line width scale factor
-            - marker_scale: Marker size scale factor
-            - antialias: Whether to enable anti-aliasing
-            - format: Recommended file format
-            - style_params: Additional matplotlib rcParams
-
-    Raises:
-        ValueError: If preset is invalid.
-
-    Example:
-        >>> config = configure_dpi_rendering("print")
-        >>> plt.rcParams.update(config['style_params'])
-        >>> fig = plt.figure(dpi=config['dpi'], figsize=config['figsize'])
-
-    References:
-        VIS-017: DPI-Aware Rendering
-    """
-    presets = _get_dpi_presets()
-
-    # Handle dpi alias and resolve preset
-    if dpi is not None and custom_dpi is None:
-        custom_dpi = dpi
-
-    if preset not in presets and custom_dpi is None:
-        raise ValueError(f"Invalid preset: {preset}. Must be one of {list(presets.keys())}")
-
-    # Get configuration and DPI
-    target_dpi, preset_config = _resolve_dpi_config(preset, custom_dpi, presets)
-
-    # Calculate scale factors
-    scale = target_dpi / baseline_dpi
-    font_scale = scale
-    line_scale = scale
-    marker_scale = scale
-
-    # Build style parameters
-    style_params = _build_style_params(
-        target_dpi, font_scale, line_scale, marker_scale, preset_config
-    )
-
-    _apply_antialias_settings(style_params, preset_config)
-
-    if preset == "publication":
-        _apply_publication_settings(style_params)
-
-    return {
-        "dpi": target_dpi,
-        "figsize": figsize,
-        "font_scale": font_scale,
-        "line_scale": line_scale,
-        "marker_scale": marker_scale,
-        "antialias": preset_config["antialias"],
-        "format": preset_config["format"],
-        "style_params": style_params,
-        "description": preset_config["description"],
-        "preset": preset if custom_dpi is None else "custom",
-    }
-
-
-def _get_dpi_presets() -> dict[str, dict[str, Any]]:
-    """Get DPI preset configurations."""
-    return {
-        "screen": {
-            "dpi": 96,
-            "font_family": "sans-serif",
-            "antialias": True,
-            "format": "png",
-            "description": "Screen display (96 DPI)",
-        },
-        "print": {
-            "dpi": 300,
-            "font_family": "sans-serif",
-            "antialias": False,
-            "format": "pdf",
-            "description": "Print output (300 DPI)",
-        },
-        "publication": {
-            "dpi": 600,
-            "font_family": "serif",
-            "antialias": False,
-            "format": "pdf",
-            "description": "Publication quality (600 DPI)",
-        },
-    }
-
-
-def _resolve_dpi_config(
-    preset: str, custom_dpi: int | None, presets: dict[str, dict[str, Any]]
-) -> tuple[int, dict[str, Any]]:
-    """Resolve target DPI and configuration from preset or custom value."""
-    if custom_dpi is not None:
-        return custom_dpi, {
-            "font_family": "sans-serif",
-            "antialias": True,
-            "format": "png" if custom_dpi <= 150 else "pdf",
-            "description": f"Custom ({custom_dpi} DPI)",
-        }
-
-    preset_config = presets[preset]
-    return preset_config["dpi"], preset_config
-
-
-def _build_style_params(
-    target_dpi: int,
-    font_scale: float,
-    line_scale: float,
-    marker_scale: float,
-    preset_config: dict[str, Any],
-) -> dict[str, Any]:
-    """Build matplotlib rcParams dictionary."""
-    return {
-        "figure.dpi": target_dpi,
-        "savefig.dpi": target_dpi,
-        "font.family": preset_config["font_family"],
-        "font.size": 10 * font_scale,
-        "axes.titlesize": 12 * font_scale,
-        "axes.labelsize": 10 * font_scale,
-        "xtick.labelsize": 9 * font_scale,
-        "ytick.labelsize": 9 * font_scale,
-        "legend.fontsize": 9 * font_scale,
-        "lines.linewidth": 1.0 * line_scale,
-        "lines.markersize": 6.0 * marker_scale,
-        "patch.linewidth": 1.0 * line_scale,
-        "grid.linewidth": 0.5 * line_scale,
-        "axes.linewidth": 0.8 * line_scale,
-        "xtick.major.width": 0.8 * line_scale,
-        "ytick.major.width": 0.8 * line_scale,
-        "xtick.minor.width": 0.6 * line_scale,
-        "ytick.minor.width": 0.6 * line_scale,
-    }
-
-
-def _apply_antialias_settings(style_params: dict[str, Any], preset_config: dict[str, Any]) -> None:
-    """Apply anti-aliasing settings to style params (modifies in-place)."""
-    antialias = preset_config["antialias"]
-    style_params["lines.antialiased"] = antialias
-    style_params["patch.antialiased"] = antialias
-    style_params["text.antialiased"] = antialias
-
-
-def _apply_publication_settings(style_params: dict[str, Any]) -> None:
-    """Apply publication-specific settings to style params (modifies in-place)."""
-    style_params["font.family"] = "serif"
-    style_params["mathtext.fontset"] = "cm"  # Computer Modern for LaTeX
-    style_params["axes.grid"] = True
-    style_params["grid.alpha"] = 0.3
-    style_params["axes.axisbelow"] = True
-
-
-def apply_rendering_config(config: dict[str, Any]) -> None:
-    """Apply rendering configuration to matplotlib rcParams.
-
-    Args:
-        config: Configuration dictionary from configure_dpi_rendering().
-
-    Raises:
-        ImportError: If matplotlib is not available.
-
-    Example:
-        >>> config = configure_dpi_rendering("print")
-        >>> apply_rendering_config(config)
-    """
-    try:
-        import matplotlib.pyplot as plt
-
-        plt.rcParams.update(config["style_params"])
-    except ImportError:
-        raise ImportError("matplotlib is required for rendering configuration")
-
-
-__all__ = [
-    "RenderPreset",
-    "apply_rendering_config",
-    "configure_dpi_rendering",
-]

oscura/visualization/rendering.py

@@ -1,444 +0,0 @@
-"""Rendering optimization for large datasets and streaming updates.
-
-This module provides level-of-detail rendering, progressive rendering,
-and memory-efficient plot updates for high-performance visualization.
-
-
-Example:
-    >>> from oscura.visualization.rendering import render_with_lod
-    >>> time_lod, data_lod = render_with_lod(time, data, screen_width=1920)
-
-References:
-    - Level-of-detail (LOD) rendering techniques
-    - Min-max envelope for waveform rendering
-    - Progressive rendering algorithms
-    - Streaming data visualization
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING, Literal
-
-import numpy as np
-
-if TYPE_CHECKING:
-    from numpy.typing import NDArray
-
-
-def render_with_lod(
-    time: NDArray[np.float64],
-    data: NDArray[np.float64],
-    *,
-    screen_width: int = 1920,
-    samples_per_pixel: float = 2.0,
-    max_points: int = 100_000,
-    method: Literal["minmax", "lttb", "uniform"] = "minmax",
-) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
-    """Render signal with level-of-detail decimation./VIS-019.
-
-    Reduces number of points while preserving visual appearance using
-    intelligent downsampling. Target: <100k points at any zoom level.
-
-    Args:
-        time: Time array.
-        data: Signal data array.
-        screen_width: Screen width in pixels.
-        samples_per_pixel: Target samples per pixel (2.0 recommended).
-        max_points: Maximum points to render (default: 100k).
-        method: Decimation method ("minmax", "lttb", "uniform").
-
-    Returns:
-        Tuple of (decimated_time, decimated_data).
-
-    Raises:
-        ValueError: If arrays are invalid or method unknown.
-
-    Example:
-        >>> # 1M sample signal decimated for 1920px display
-        >>> time_lod, data_lod = render_with_lod(time, data, screen_width=1920)
-        >>> print(len(data_lod))  # ~3840 samples (2 per pixel)
-
-    References:
-        VIS-017: Performance - LOD Rendering
-        VIS-019: Memory-Efficient Plot Rendering
-    """
-    if len(time) == 0 or len(data) == 0:
-        raise ValueError("Time or data array is empty")
-
-    if len(time) != len(data):
-        raise ValueError(f"Time and data length mismatch: {len(time)} vs {len(data)}")
-
-    # Calculate target point count
-    target_points = min(
-        int(screen_width * samples_per_pixel),
-        max_points,
-    )
-
-    # Skip decimation if already below target
-    if len(data) <= target_points:
-        return (time, data)
-
-    # Apply decimation
-    if method == "uniform":
-        return _decimate_uniform(time, data, target_points)
-    elif method == "minmax":
-        return _decimate_minmax_envelope(time, data, target_points)
-    elif method == "lttb":
-        return _decimate_lttb(time, data, target_points)
-    else:
-        raise ValueError(f"Unknown decimation method: {method}")
-
-
-def _decimate_uniform(
-    time: NDArray[np.float64],
-    data: NDArray[np.float64],
-    target_points: int,
-) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
-    """Uniform stride decimation (simple but loses peaks).
-
-    Args:
-        time: Time array.
-        data: Signal data array.
-        target_points: Target number of points after decimation.
-
-    Returns:
-        Tuple of (decimated_time, decimated_data).
-    """
-    stride = len(data) // target_points
-    stride = max(stride, 1)
-
-    indices = np.arange(0, len(data), stride)[:target_points]
-    return (time[indices], data[indices])
-
-
-def _decimate_minmax_envelope(
-    time: NDArray[np.float64],
-    data: NDArray[np.float64],
-    target_points: int,
-) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
-    """Min-max envelope decimation - preserves peaks and valleys.
-
-    This method ensures all signal extrema are preserved in the decimated view.
-
-    Args:
-        time: Time array.
-        data: Signal data array.
-        target_points: Target number of points after decimation.
-
-    Returns:
-        Tuple of (decimated_time, decimated_data).
-    """
-    # Calculate bucket size (each bucket contributes 2 points: min and max)
-    bucket_size = len(data) // (target_points // 2)
-
-    if bucket_size < 1:
-        return (time, data)
-
-    decimated_time = []
-    decimated_data = []
-
-    for i in range(0, len(data), bucket_size):
-        bucket_data = data[i : i + bucket_size]
-        bucket_time = time[i : i + bucket_size]
-
-        if len(bucket_data) == 0:
-            continue
-
-        # Find min and max in bucket
-        min_idx = np.argmin(bucket_data)
-        max_idx = np.argmax(bucket_data)
-
-        # Add in chronological order
-        if min_idx < max_idx:
-            decimated_time.extend([bucket_time[min_idx], bucket_time[max_idx]])
-            decimated_data.extend([bucket_data[min_idx], bucket_data[max_idx]])
-        else:
-            decimated_time.extend([bucket_time[max_idx], bucket_time[min_idx]])
-            decimated_data.extend([bucket_data[max_idx], bucket_data[min_idx]])
-
-    return (np.array(decimated_time), np.array(decimated_data))
-
-
-def _decimate_lttb(
-    time: NDArray[np.float64],
-    data: NDArray[np.float64],
-    target_points: int,
-) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
-    """Largest Triangle Three Buckets decimation.
-
-    Preserves visual shape by maximizing triangle areas.
-
-    Args:
-        time: Time array.
-        data: Signal data array.
-        target_points: Target number of points after decimation.
-
-    Returns:
-        Tuple of (decimated_time, decimated_data).
-    """
-    if len(data) <= target_points:
-        return (time, data)
-
-    # Always include first and last points
-    sampled_time = [time[0]]
-    sampled_data = [data[0]]
-
-    bucket_size = (len(data) - 2) / (target_points - 2)
-
-    prev_idx = 0
-
-    for i in range(target_points - 2):
-        # Average point of next bucket
-        avg_range_start = int((i + 1) * bucket_size) + 1
-        avg_range_end = int((i + 2) * bucket_size) + 1
-        avg_range_end = min(avg_range_end, len(data))
-
-        if avg_range_start < avg_range_end:
-            avg_time = np.mean(time[avg_range_start:avg_range_end])
-            avg_data = np.mean(data[avg_range_start:avg_range_end])
-        else:
-            avg_time = time[-1]
-            avg_data = data[-1]
-
-        # Current bucket range
-        range_start = int(i * bucket_size) + 1
-        range_end = int((i + 1) * bucket_size) + 1
-        range_end = min(range_end, len(data) - 1)
-
-        # Find point in bucket that forms largest triangle
-        max_area = -1.0
-        max_idx = range_start
-
-        for idx in range(range_start, range_end):
-            # Calculate triangle area
-            area = abs(
-                (time[prev_idx] - avg_time) * (data[idx] - data[prev_idx])
-                - (time[prev_idx] - time[idx]) * (avg_data - data[prev_idx])
-            )
-
-            if area > max_area:
-                max_area = area
-                max_idx = idx
-
-        sampled_time.append(time[max_idx])
-        sampled_data.append(data[max_idx])
-        prev_idx = max_idx
-
-    # Always include last point
-    sampled_time.append(time[-1])
-    sampled_data.append(data[-1])
-
-    return (np.array(sampled_time), np.array(sampled_data))
-
-
-def progressive_render(
-    time: NDArray[np.float64],
-    data: NDArray[np.float64],
-    *,
-    viewport: tuple[float, float] | None = None,
-    priority: Literal["viewport", "full"] = "viewport",
-) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
-    """Progressive rendering - render visible viewport first.
-
-    Args:
-        time: Time array.
-        data: Signal data array.
-        viewport: Visible viewport (t_min, t_max). None = full range.
-        priority: Rendering priority ("viewport" = visible first, "full" = all data).
-
-    Returns:
-        Tuple of (time, data) for priority rendering.
-
-    Example:
-        >>> # Render only visible portion for fast initial display
-        >>> time_vis, data_vis = progressive_render(
-        ...     time, data, viewport=(0, 0.001), priority="viewport"
-        ... )
-
-    References:
-        VIS-019: Memory-Efficient Plot Rendering (progressive rendering)
-    """
-    if viewport is None or priority == "full":
-        return (time, data)
-
-    t_min, t_max = viewport
-
-    # Find indices within viewport
-    mask = (time >= t_min) & (time <= t_max)
-    indices = np.where(mask)[0]
-
-    if len(indices) == 0:
-        # Viewport is outside data range
-        return (time, data)
-
-    # Return viewport data first
-    viewport_time = time[indices]
-    viewport_data = data[indices]
-
-    return (viewport_time, viewport_data)
-
-
-def estimate_memory_usage(
-    n_samples: int,
-    n_channels: int = 1,
-    dtype: type = np.float64,
-) -> float:
-    """Estimate memory usage for plot rendering.
-
-    Args:
-        n_samples: Number of samples per channel.
-        n_channels: Number of channels.
-        dtype: Data type for arrays.
-
-    Returns:
-        Estimated memory usage in MB.
-
-    Example:
-        >>> mem_mb = estimate_memory_usage(1_000_000, n_channels=4)
-        >>> print(f"Memory: {mem_mb:.1f} MB")
-
-    References:
-        VIS-019: Memory-Efficient Plot Rendering
-    """
-    # Bytes per sample
-    if dtype == np.float64:
-        bytes_per_sample = 8
-    elif dtype == np.float32 or dtype == np.int32:
-        bytes_per_sample = 4
-    elif dtype == np.int16:
-        bytes_per_sample = 2
-    else:
-        bytes_per_sample = 8  # Default
-
-    # Total memory: time + data arrays per channel
-    # Time array: n_samples * bytes_per_sample
-    # Data arrays: n_channels * n_samples * bytes_per_sample
-    total_bytes = (1 + n_channels) * n_samples * bytes_per_sample
-
-    # Convert to MB
-    return total_bytes / (1024 * 1024)
-
-
-def downsample_for_memory(
-    time: NDArray[np.float64],
-    data: NDArray[np.float64],
-    *,
-    target_memory_mb: float = 50.0,
-) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
-    """Downsample signal to meet memory target.
-
-    Args:
-        time: Time array.
-        data: Signal data array.
-        target_memory_mb: Target memory usage in MB.
-
-    Returns:
-        Tuple of (decimated_time, decimated_data).
-
-    Example:
-        >>> # Reduce 100MB dataset to 50MB
-        >>> time_ds, data_ds = downsample_for_memory(time, data, target_memory_mb=50.0)
-
-    References:
-        VIS-019: Memory-Efficient Plot Rendering (memory target <50MB per subplot)
-    """
-    current_memory = estimate_memory_usage(len(data), n_channels=1)
-
-    if current_memory <= target_memory_mb:
-        # Already within target
-        return (time, data)
-
-    # Calculate required decimation factor
-    decimation_factor = current_memory / target_memory_mb
-    target_samples = int(len(data) / decimation_factor)
-
-    # Use min-max to preserve features
-    return _decimate_minmax_envelope(time, data, target_samples)
-
-
-class StreamingRenderer:
-    """Streaming plot renderer for real-time data updates.
-
-    Handles incremental data updates without full redraws for performance.
-
-    Example:
-        >>> renderer = StreamingRenderer(max_samples=10000)
-        >>> renderer.append(new_time, new_data)
-        >>> time, data = renderer.get_render_data()
-
-    References:
-        VIS-018: Streaming Plot Updates
-    """
-
-    def __init__(
-        self,
-        *,
-        max_samples: int = 10_000,
-        decimation_method: Literal["minmax", "lttb", "uniform"] = "minmax",
-    ):
-        """Initialize streaming renderer.
-
-        Args:
-            max_samples: Maximum samples to keep in buffer.
-            decimation_method: Decimation method for buffer management.
-        """
-        self.max_samples = max_samples
-        self.decimation_method = decimation_method
-
-        self._time: list[float] = []
-        self._data: list[float] = []
-
-    def append(
-        self,
-        time: NDArray[np.float64],
-        data: NDArray[np.float64],
-    ) -> None:
-        """Append new data to streaming buffer.
-
-        Args:
-            time: New time samples.
-            data: New data samples.
-        """
-        self._time.extend(time.tolist())
-        self._data.extend(data.tolist())
-
-        # Decimate if buffer exceeds limit
-        if len(self._data) > self.max_samples:
-            self._decimate_buffer()
-
-    def _decimate_buffer(self) -> None:
-        """Decimate internal buffer to max_samples."""
-        time_arr = np.array(self._time)
-        data_arr = np.array(self._data)
-
-        time_dec, data_dec = render_with_lod(
-            time_arr,
-            data_arr,
-            max_points=self.max_samples,
-            method=self.decimation_method,
-        )
-
-        self._time = time_dec.tolist()
-        self._data = data_dec.tolist()
-
-    def get_render_data(self) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
-        """Get current data for rendering.
-
-        Returns:
-            Tuple of (time, data) arrays.
-        """
-        return (np.array(self._time), np.array(self._data))
-
-    def clear(self) -> None:
-        """Clear streaming buffer."""
-        self._time.clear()
-        self._data.clear()
-
-
-__all__ = [
-    "StreamingRenderer",
-    "downsample_for_memory",
-    "estimate_memory_usage",
-    "progressive_render",
-    "render_with_lod",
-]