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

oscura/search/context.py

@@ -0,0 +1,149 @@
+"""Context extraction around points of interest.
+
+
+This module provides efficient extraction of signal context around
+events, maintaining original time references for debugging workflows.
+"""
+
+from typing import Any
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def extract_context(
+    trace: NDArray[np.float64],
+    index: int | list[int] | NDArray[np.int_],
+    *,
+    before: int = 100,
+    after: int = 100,
+    sample_rate: float | None = None,
+    include_metadata: bool = True,
+) -> dict[str, Any] | list[dict[str, Any]]:
+    """Extract signal context around a point of interest.
+
+    : Context extraction with time reference preservation.
+    Supports batch extraction for multiple indices and optional protocol data.
+
+    Args:
+        trace: Input signal trace
+        index: Sample index or list of indices to extract context around.
+            Can be int, list of ints, or numpy array.
+        before: Number of samples to include before index (default: 100)
+        after: Number of samples to include after index (default: 100)
+        sample_rate: Optional sample rate in Hz for time calculations
+        include_metadata: Include metadata dict with context info (default: True)
+
+    Returns:
+        If index is scalar: Single context dictionary
+        If index is list/array: List of context dictionaries
+
+        Each context dictionary contains:
+        - data: Extracted sub-trace array
+        - start_index: Starting index in original trace
+        - end_index: Ending index in original trace
+        - center_index: Center index (original query index)
+        - time_reference: Time offset if sample_rate provided
+        - length: Number of samples in context
+
+    Raises:
+        ValueError: If index is out of bounds
+        ValueError: If before or after are negative
+
+    Examples:
+        >>> # Extract context around a glitch
+        >>> trace = np.random.randn(1000)
+        >>> glitch_index = 500
+        >>> context = extract_context(
+        ...     trace,
+        ...     glitch_index,
+        ...     before=50,
+        ...     after=50,
+        ...     sample_rate=1e6
+        ... )
+        >>> print(f"Context length: {len(context['data'])}")
+        >>> print(f"Time reference: {context['time_reference']*1e6:.2f} µs")
+
+        >>> # Batch extraction for multiple events
+        >>> event_indices = [100, 200, 300]
+        >>> contexts = extract_context(
+        ...     trace,
+        ...     event_indices,
+        ...     before=25,
+        ...     after=25
+        ... )
+        >>> print(f"Extracted {len(contexts)} contexts")
+
+    Notes:
+        - Handles edge cases at trace boundaries automatically
+        - Context may be shorter than before+after at boundaries
+        - Time reference is relative to start of extracted context
+        - Original trace is not modified
+
+    References:
+        SRCH-003: Context Extraction
+    """
+    if before < 0 or after < 0:
+        raise ValueError("before and after must be non-negative")
+
+    if trace.size == 0:
+        raise ValueError("Trace cannot be empty")
+
+    # Handle single index vs multiple indices
+    if isinstance(index, int | np.integer):
+        indices = [int(index)]
+        return_single = True
+    else:
+        indices = [int(i) for i in index]
+        return_single = False
+
+    # Validate indices
+    for idx in indices:
+        if idx < 0 or idx >= len(trace):
+            raise ValueError(f"Index {idx} out of bounds for trace of length {len(trace)}")
+
+    # Extract contexts
+    contexts = []
+
+    for idx in indices:
+        # Calculate window bounds with boundary handling
+        start_idx = max(0, idx - before)
+        end_idx = min(len(trace), idx + after + 1)
+
+        # Extract data
+        data = trace[start_idx:end_idx].copy()
+
+        # Build context dictionary
+        context: dict[str, Any] = {
+            "data": data,
+            "start_index": start_idx,
+            "end_index": end_idx,
+            "center_index": idx,
+            "length": len(data),
+        }
+
+        # Add time reference if sample rate provided
+        if sample_rate is not None:
+            time_offset = start_idx / sample_rate
+            context["time_reference"] = time_offset
+            context["sample_rate"] = sample_rate
+
+            # Time array for the context
+            dt = 1.0 / sample_rate
+            context["time_array"] = np.arange(len(data)) * dt + time_offset
+
+        if include_metadata:
+            context["metadata"] = {
+                "samples_before": idx - start_idx,
+                "samples_after": end_idx - idx - 1,
+                "at_start_boundary": start_idx == 0,
+                "at_end_boundary": end_idx == len(trace),
+            }
+
+        contexts.append(context)
+
+    # Return single context or list
+    if return_single:
+        return contexts[0]
+    else:
+        return contexts

oscura/search/pattern.py

@@ -0,0 +1,160 @@
+"""Pattern search in digital traces.
+
+
+This module provides efficient bit pattern matching in digital signals
+with wildcard support via mask parameter.
+"""
+
+from typing import cast
+
+import numpy as np
+from numpy.typing import NDArray
+
+
+def find_pattern(
+    trace: NDArray[np.float64] | NDArray[np.uint8],
+    pattern: int | NDArray[np.uint8],
+    mask: int | NDArray[np.uint8] | None = None,
+    *,
+    threshold: float | None = None,
+    min_spacing: int = 1,
+) -> list[tuple[int, NDArray[np.uint8]]]:
+    """Find occurrences of bit patterns in digital traces.
+
+    : Pattern search with wildcard support via mask.
+    Works on both raw analog traces (with threshold) and decoded digital data.
+
+    Args:
+        trace: Input trace array. If analog (float), threshold is required.
+            If already digital (uint8), threshold is ignored.
+        pattern: Bit pattern to search for. Can be:
+            - Integer: e.g., 0b10101010 (8-bit pattern)
+            - Array: sequence of bytes to match
+        mask: Optional mask for wildcard matching. Bits set to 0 in mask
+            are "don't care" positions. Can be:
+            - Integer: e.g., 0xFF (all bits matter)
+            - Array: per-byte masks
+            If None, all bits must match (equivalent to all 1s).
+        threshold: Threshold for converting analog to digital (required if
+            trace is analog). Typically mid-level of logic family.
+        min_spacing: Minimum samples between detected patterns to avoid
+            overlapping matches (default: 1)
+
+    Returns:
+        List of (index, match) tuples where:
+        - index: Starting sample index of the pattern
+        - match: The actual matched bit sequence as uint8 array
+
+    Raises:
+        ValueError: If analog trace provided without threshold
+        ValueError: If pattern is empty
+
+    Examples:
+        >>> # Find 0xAA pattern in analog trace
+        >>> import numpy as np
+        >>> trace = np.array([0, 1, 0, 1, 0, 1, 0, 1, 0, 0])
+        >>> matches = find_pattern(trace, 0b10101010, threshold=0.5)
+        >>> print(f"Found {len(matches)} matches")
+
+        >>> # Wildcard search: find 0b1010xxxx (x = don't care)
+        >>> pattern = 0b10100000
+        >>> mask = 0b11110000  # Only upper 4 bits matter
+        >>> matches = find_pattern(trace, pattern, mask, threshold=0.5)
+
+        >>> # Search in already-decoded digital data
+        >>> digital = np.array([0xAA, 0x55, 0xAA, 0x00], dtype=np.uint8)
+        >>> matches = find_pattern(digital, 0xAA)
+
+    Notes:
+        - For analog traces, values >= threshold are interpreted as '1'
+        - Mask bits: 1 = must match, 0 = don't care
+        - Overlapping patterns can be filtered with min_spacing > 1
+        - Returns empty list if no matches found
+
+    References:
+        SRCH-001: Pattern Search
+    """
+    if trace.size == 0:
+        return []
+
+    # Convert pattern to array if integer
+    if isinstance(pattern, int):
+        if pattern < 0:
+            raise ValueError("Pattern must be non-negative")
+        # Convert to byte array (variable length based on value)
+        pattern_bytes = []
+        if pattern == 0:
+            pattern_bytes = [0]
+        else:
+            temp = pattern
+            while temp > 0:
+                pattern_bytes.insert(0, temp & 0xFF)
+                temp >>= 8
+        pattern_arr = np.array(pattern_bytes, dtype=np.uint8)
+    else:
+        pattern_arr = np.asarray(pattern, dtype=np.uint8)
+
+    if pattern_arr.size == 0:
+        raise ValueError("Pattern cannot be empty")
+
+    # Convert mask to array if integer
+    if mask is not None:
+        if isinstance(mask, int):
+            mask_bytes: list[int] = []
+            temp = mask
+            # Match pattern length
+            for _ in range(len(pattern_arr)):
+                mask_bytes.insert(0, temp & 0xFF)
+                temp >>= 8
+            mask_arr = np.array(mask_bytes, dtype=np.uint8)
+        else:
+            mask_arr = np.asarray(mask, dtype=np.uint8)
+
+        # Ensure mask and pattern have same length
+        if mask_arr.size != pattern_arr.size:
+            raise ValueError("Mask and pattern must have same length")
+    else:
+        # Default: all bits matter
+        mask_arr = np.full(pattern_arr.size, 0xFF, dtype=np.uint8)
+
+    # Convert analog trace to digital if needed
+    if trace.dtype != np.uint8:
+        if threshold is None:
+            raise ValueError(
+                "Threshold required for analog trace conversion. "
+                "Provide threshold parameter or pre-convert to digital."
+            )
+        # Simple threshold conversion: >= threshold is 1
+        digital = (trace >= threshold).astype(np.uint8)
+        # Pack bits into bytes (8 samples per byte)
+        # Pad to multiple of 8
+        n_pad = (8 - len(digital) % 8) % 8
+        if n_pad:
+            digital = np.pad(digital, (0, n_pad), constant_values=0)
+        # Pack bits
+        digital_packed: NDArray[np.uint8] = np.packbits(digital, bitorder="big")
+    else:
+        digital_packed = cast("NDArray[np.uint8]", trace)
+
+    if digital_packed.size < pattern_arr.size:
+        return []
+
+    # Sliding window pattern matching with mask
+    matches: list[tuple[int, NDArray[np.uint8]]] = []
+    i = 0
+
+    while i <= len(digital_packed) - len(pattern_arr):
+        window = digital_packed[i : i + len(pattern_arr)]
+
+        # Apply mask and compare
+        masked_window = window & mask_arr
+        masked_pattern = pattern_arr & mask_arr
+
+        if np.array_equal(masked_window, masked_pattern):
+            matches.append((i, window.copy()))
+            # Skip ahead by min_spacing to avoid overlapping matches
+            i += max(1, min_spacing)
+        else:
+            i += 1
+
+    return matches

oscura/session/__init__.py

@@ -0,0 +1,34 @@
+"""Session management for TraceKit analysis sessions.
+
+This module provides session save/restore, trace annotations, and
+operation history tracking.
+
+
+Example:
+    >>> import oscura as tk
+    >>> session = tk.Session()
+    >>> session.load_trace('capture.wfm')
+    >>> session.annotate(time=1.5e-6, text='Glitch here')
+    >>> session.save('debug_session.tks')
+    >>>
+    >>> # Later...
+    >>> session = tk.load_session('debug_session.tks')
+    >>> print(session.annotations)
+"""
+
+from oscura.session.annotations import Annotation, AnnotationLayer, AnnotationType
+from oscura.session.history import HistoryEntry, OperationHistory
+from oscura.session.session import Session, load_session
+
+__all__ = [
+    # Annotations (SESS-002)
+    "Annotation",
+    "AnnotationLayer",
+    "AnnotationType",
+    # History (SESS-003)
+    "HistoryEntry",
+    "OperationHistory",
+    # Session (SESS-001)
+    "Session",
+    "load_session",
+]

oscura/session/annotations.py

@@ -0,0 +1,289 @@
+"""Trace annotation support.
+
+This module provides annotation capabilities for marking points of interest
+in signal traces.
+
+
+Example:
+    >>> layer = AnnotationLayer("Debug Markers")
+    >>> layer.add(Annotation(time=1.5e-6, text="Glitch detected"))
+    >>> layer.add(Annotation(time_range=(2e-6, 3e-6), text="Data packet"))
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+
+class AnnotationType(Enum):
+    """Types of annotations."""
+
+    POINT = "point"  # Single time point
+    RANGE = "range"  # Time range
+    VERTICAL = "vertical"  # Vertical line
+    HORIZONTAL = "horizontal"  # Horizontal line
+    REGION = "region"  # 2D region (time + amplitude)
+    TEXT = "text"  # Free-floating text
+
+
+@dataclass
+class Annotation:
+    """Single annotation on a trace.
+
+    Attributes:
+        text: Annotation text/label
+        time: Time point (for point annotations)
+        time_range: (start, end) time range
+        amplitude: Amplitude value (for horizontal lines)
+        amplitude_range: (min, max) amplitude range
+        annotation_type: Type of annotation
+        color: Display color (hex or name)
+        style: Line style ('solid', 'dashed', 'dotted')
+        visible: Whether annotation is visible
+        created_at: Creation timestamp
+        metadata: Additional metadata
+    """
+
+    text: str
+    time: float | None = None
+    time_range: tuple[float, float] | None = None
+    amplitude: float | None = None
+    amplitude_range: tuple[float, float] | None = None
+    annotation_type: AnnotationType = AnnotationType.POINT
+    color: str = "#FF6B6B"
+    style: str = "solid"
+    visible: bool = True
+    created_at: datetime = field(default_factory=datetime.now)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        """Infer annotation type from provided parameters."""
+        if self.annotation_type == AnnotationType.POINT:
+            if self.time_range is not None:
+                self.annotation_type = AnnotationType.RANGE
+            elif self.amplitude is not None and self.time is None:
+                self.annotation_type = AnnotationType.HORIZONTAL
+            elif self.amplitude_range is not None and self.time_range is not None:
+                self.annotation_type = AnnotationType.REGION  # type: ignore[unreachable]
+
+    @property
+    def start_time(self) -> float | None:
+        """Get start time for range annotations."""
+        if self.time_range:
+            return self.time_range[0]
+        return self.time
+
+    @property
+    def end_time(self) -> float | None:
+        """Get end time for range annotations."""
+        if self.time_range:
+            return self.time_range[1]
+        return self.time
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "text": self.text,
+            "time": self.time,
+            "time_range": self.time_range,
+            "amplitude": self.amplitude,
+            "amplitude_range": self.amplitude_range,
+            "annotation_type": self.annotation_type.value,
+            "color": self.color,
+            "style": self.style,
+            "visible": self.visible,
+            "created_at": self.created_at.isoformat(),
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Annotation:
+        """Create from dictionary."""
+        data = data.copy()
+        data["annotation_type"] = AnnotationType(data.get("annotation_type", "point"))
+        if "created_at" in data and isinstance(data["created_at"], str):
+            data["created_at"] = datetime.fromisoformat(data["created_at"])
+        return cls(**data)
+
+
+@dataclass
+class AnnotationLayer:
+    """Collection of related annotations.
+
+    Attributes:
+        name: Layer name
+        annotations: List of annotations
+        visible: Whether layer is visible
+        locked: Whether layer is locked (read-only)
+        color: Default color for new annotations
+        description: Layer description
+    """
+
+    name: str
+    annotations: list[Annotation] = field(default_factory=list)
+    visible: bool = True
+    locked: bool = False
+    color: str = "#FF6B6B"
+    description: str = ""
+
+    def add(
+        self,
+        annotation: Annotation | None = None,
+        *,
+        text: str = "",
+        time: float | None = None,
+        time_range: tuple[float, float] | None = None,
+        **kwargs: Any,
+    ) -> Annotation:
+        """Add annotation to layer.
+
+        Args:
+            annotation: Pre-built Annotation object.
+            text: Annotation text (if not using pre-built).
+            time: Time point.
+            time_range: Time range.
+            **kwargs: Additional Annotation parameters.
+
+        Returns:
+            Added annotation.
+
+        Raises:
+            ValueError: If layer is locked.
+        """
+        if self.locked:
+            raise ValueError(f"Layer '{self.name}' is locked")
+
+        if annotation is None:
+            annotation = Annotation(
+                text=text,
+                time=time,
+                time_range=time_range,
+                color=kwargs.pop("color", self.color),
+                **kwargs,
+            )
+
+        self.annotations.append(annotation)
+        return annotation
+
+    def remove(self, annotation: Annotation) -> bool:
+        """Remove annotation from layer.
+
+        Args:
+            annotation: Annotation to remove.
+
+        Returns:
+            True if removed, False if not found.
+
+        Raises:
+            ValueError: If layer is locked.
+        """
+        if self.locked:
+            raise ValueError(f"Layer '{self.name}' is locked")
+
+        try:
+            self.annotations.remove(annotation)
+            return True
+        except ValueError:
+            return False
+
+    def find_at_time(
+        self,
+        time: float,
+        tolerance: float = 0.0,
+    ) -> list[Annotation]:
+        """Find annotations at or near a specific time.
+
+        Args:
+            time: Time to search.
+            tolerance: Time tolerance for matching.
+
+        Returns:
+            List of matching annotations.
+        """
+        matches = []
+        for ann in self.annotations:
+            if ann.time is not None:
+                if abs(ann.time - time) <= tolerance:
+                    matches.append(ann)
+            elif ann.time_range is not None and (
+                ann.time_range[0] - tolerance <= time <= ann.time_range[1] + tolerance
+            ):
+                matches.append(ann)
+        return matches
+
+    def find_in_range(
+        self,
+        start_time: float,
+        end_time: float,
+    ) -> list[Annotation]:
+        """Find annotations within a time range.
+
+        Args:
+            start_time: Range start.
+            end_time: Range end.
+
+        Returns:
+            List of annotations within range.
+        """
+        matches = []
+        for ann in self.annotations:
+            ann_start = ann.start_time
+            ann_end = ann.end_time
+
+            if ann_start is not None and (
+                start_time <= ann_start <= end_time
+                or (ann_end is not None and ann_start <= end_time and ann_end >= start_time)
+            ):
+                matches.append(ann)
+
+        return matches
+
+    def clear(self) -> int:
+        """Remove all annotations.
+
+        Returns:
+            Number of annotations removed.
+
+        Raises:
+            ValueError: If layer is locked.
+        """
+        if self.locked:
+            raise ValueError(f"Layer '{self.name}' is locked")
+
+        count = len(self.annotations)
+        self.annotations.clear()
+        return count
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dictionary for serialization."""
+        return {
+            "name": self.name,
+            "annotations": [a.to_dict() for a in self.annotations],
+            "visible": self.visible,
+            "locked": self.locked,
+            "color": self.color,
+            "description": self.description,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> AnnotationLayer:
+        """Create from dictionary."""
+        annotations = [Annotation.from_dict(a) for a in data.get("annotations", [])]
+        return cls(
+            name=data["name"],
+            annotations=annotations,
+            visible=data.get("visible", True),
+            locked=data.get("locked", False),
+            color=data.get("color", "#FF6B6B"),
+            description=data.get("description", ""),
+        )
+
+
+__all__ = [
+    "Annotation",
+    "AnnotationLayer",
+    "AnnotationType",
+]