evutils 0.3.10__cp313-cp313-win_amd64.whl

evutils/__init__.py

@@ -0,0 +1,41 @@
+"""evutils: utilities for event-based data.
+
+Event-based data processing and visualization utilities.
+
+To get started::
+
+    import evutils
+    ...
+
+
+
+Notes
+-----
+Anything worth calling out up front.
+
+
+
+"""
+
+import importlib.metadata
+
+try:
+    __version__ = importlib.metadata.version("evutils")
+except importlib.metadata.PackageNotFoundError:
+    # Fallback if the package is run without being installed
+    __version__ = "dev"
+
+
+__all__ = [
+    'augment', 
+    'chunking', 
+    'dataset', 
+    'io', 
+    'utils', 
+    'vis', 
+    'processing', 
+    'random', 
+    'types', 
+    '__version__'
+]
+

evutils/augment/__init__.py

@@ -0,0 +1,11 @@
+"""Data augmentation transforms for events.
+
+Random and deterministic transformations for augmenting event streams
+during training, such as spatial flips, time reversal, event dropout and
+added noise.
+"""
+
+
+from ._drop import drop_random_events
+
+__all__ = ["drop_random_events"]

evutils/augment/_drop.py

@@ -0,0 +1,32 @@
+
+import numpy as np
+
+
+
+def drop_random_events(events: np.ndarray, drop_rate: float = 0.1):
+    """Drops a percentage of events randomly using slicing.
+    
+    Parameters
+    ----------
+    events : np.ndarray
+        Array of events to drop from.
+    drop_rate : float, optional
+        Percentage of events to drop, by default 0.1 (10%).
+    
+    Returns
+    -------
+    np.ndarray:w
+    
+        Array of events with the specified percentage dropped.
+    """
+    if drop_rate <= 0 or drop_rate >= 1:
+        raise ValueError("drop_rate must be between 0 and 1")
+    
+    n_events = len(events)
+    indices = np.arange(n_events)
+    np.random.shuffle(indices)
+    
+    drop_count = int(n_events * drop_rate)
+    keep_indices = indices[drop_count:]
+    
+    return events[keep_indices]

evutils/chunking.py

@@ -0,0 +1,117 @@
+"""Splitting event streams into chunks.
+
+Slice a continuous event stream into fixed-size windows, either by event
+count or by time interval.
+"""
+
+import numpy as np
+
+
+
+def window_delta_t(events: np.ndarray, delta_t: int = 10_000):
+    '''
+    Returns a generator that chunks the events array into windows of size delta_t
+    
+    Parameters
+    ----------
+    events : np.ndarray
+        Array of events
+    delta_t : int, optional
+        Size of the window in microseconds, by default 10_000'''
+
+
+    if len(events) == 0:
+        return
+
+    index_start = 0
+    
+    ts = events["t"]
+    current_ts = ts[0]
+
+    while index_start < len(events):
+        next_index = np.searchsorted(ts[index_start:], current_ts + delta_t)
+
+        window = events[index_start:index_start + next_index]
+        yield window
+
+        current_ts += delta_t
+        index_start += next_index
+
+def sliding_window(events: np.ndarray, delta_t: int = 10_000, window_size: int = 20_000, full_window: bool = False):
+    '''
+    Returns a generator that chunks the events array into windows of size delta_t
+    
+    Parameters
+    ----------
+    events : np.ndarray
+        Array of events
+    delta_t : int, optional
+        Time delta between frames in microseconds, by default 10_000
+    window_size : int, optional
+        Size of the window in microseconds, by default 20_000
+        can overlap with the next frame
+    full_window : bool, optional
+        If True, the last window will be full, by default False
+        If False, the last window will be the remaining events
+    '''
+
+    if len(events) == 0:
+        return
+
+    index_start = 0
+    
+    ts = events["t"]
+    current_ts = ts[0]
+
+    while index_start < len(events):
+
+
+        next_frame_index = np.searchsorted(ts[index_start:], current_ts + delta_t)
+        next_window_index = np.searchsorted(ts[index_start:], current_ts + window_size)
+        
+       
+
+        window = events[index_start:index_start + next_window_index]
+        yield window
+
+
+        # Exit if the next window index is  not full
+        if full_window and index_start + next_window_index >= len(events):
+            break
+
+        current_ts += delta_t
+        index_start += next_frame_index
+
+
+
+
+def sort_events(events: np.ndarray):
+    '''Sorts the events array by timestamp
+    
+    Parameters
+    ----------
+    events : np.ndarray
+        Array of events
+
+    '''
+    return np.sort(events, order="t")
+
+def get_dt_events(events: np.ndarray, dt: int =10_000):
+    '''
+    Returns the events that are within a time window of dt from the first event's timestamp.
+    Parameters
+    ----------
+    events : np.ndarray
+        Array of events
+    dt : int, optional
+        Time window in microseconds, by default 10_000
+    '''
+    if len(events) == 0:
+        return events
+
+    first_ts = events[0]['t'] 
+    last_ts = first_ts + dt
+
+    next_index = np.searchsorted(events['t'], last_ts)
+    
+    return events[:next_index]

evutils/dataset/__init__.py

@@ -0,0 +1,5 @@
+"""Dataset loading and management.
+
+Dataset classes and helpers for downloading, caching and iterating over
+event-based datasets.
+"""

evutils/io/__init__.py

@@ -0,0 +1,14 @@
+"""Reading and writing events in various file formats.
+
+Format-specific readers and writers (``bin``, ``csv``, ``dat``, ``hdf5``,
+``npz``, ``raw``, ``txt``) built on a shared ``EventReader`` / ``EventWriter``
+interface, plus ``EventReader_Any`` / ``EventWriter_Any`` which pick the
+backend from the file extension. Backends that need optional dependencies
+degrade gracefully and only raise on use.
+"""
+
+from ._event_reader import EventReader
+from ._event_writer import EventWriter
+
+
+__all__ = ["EventReader", "EventWriter"]

evutils/io/_aedat.py

@@ -0,0 +1,33 @@
+
+
+
+import numpy as np
+
+from .common import EventDecoder, EventEncoder
+
+
+class EventDecoder_Aedat(EventDecoder):
+    '''
+    A decoder for reading events from AEDAT files.
+
+    Parameters
+    ----------
+    file
+        Path to the data file
+    '''
+    def __init__(self, file):
+        super().__init__(file)
+
+
+class EventEncoder_Aedat(EventEncoder):
+    '''
+    A encoder for writing events to AEDAT files.
+
+    Parameters
+    ----------
+    file
+        Path to the data file
+    '''
+    def __init__(self, file, width=1280, height=720):
+        super().__init__(file)
+

evutils/io/_aer.py

@@ -0,0 +1,32 @@
+
+
+
+import numpy as np
+
+from .common import EventDecoder, EventEncoder
+
+
+class EventDecoder_AER(EventDecoder):
+    '''
+    A decoder for reading events from AER files.
+
+    Parameters
+    ----------
+    file
+        Path to the data file
+    '''
+    def __init__(self, file):
+        super().__init__(file)
+
+
+class EventEncoder_AER(EventEncoder):
+    '''
+    A encoder for writing events to AER files.
+
+    Parameters
+    ----------
+    file
+        Path to the data file
+    '''
+    def __init__(self, file, width=1280, height=720):
+        super().__init__(file, width, height)

evutils/io/_bin.py

@@ -0,0 +1,31 @@
+
+import numpy as np
+
+from .common import EventDecoder, EventEncoder
+
+
+class EventDecoder_Bin(EventDecoder):
+    '''
+    A decoder for reading events from binary files.
+
+    Parameters
+    ----------
+    file
+        Path to the data file
+    '''
+    def __init__(self, file):
+        super().__init__(file)
+
+
+class EventEncoder_Bin(EventEncoder):
+    '''
+    A encoder for writing events to binary files.
+
+    Parameters
+    ----------
+    file
+        Path to the data file
+    '''
+    def __init__(self, file, width=1280, height=720):
+        super().__init__(file)
+

evutils/io/_csv.py

@@ -0,0 +1,197 @@
+
+
+
+import io
+from io import TextIOWrapper
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import pandas as pd
+from pandas._typing import CSVEngine
+from pandas.io.parsers import TextFileReader
+
+from ..types import Event_dtype, EventArray
+from .common import EventDecoder, EventEncoder
+
+
+class EventDecoder_Csv(EventDecoder):
+    '''
+    A reader for CSV files with events.
+
+    Parameters
+    ----------
+    file
+        Path to the data file
+    order
+        Order of the columns in the CSV file, by default ['t', 'x', 'y', 'p']
+    chunk_size
+        Size of the chunk to read, by default 10_000
+    delimiter
+        Delimiter for the CSV file, by default ","
+    engine
+        Engine to use to read the CSV file, by default 'c'
+
+    Raises
+    ------
+    ValueError
+        If the order is not a list of 4 strings or if the order does not contain 't', 'x', 'y' and 'p'
+
+    '''
+
+    def __init__(self, readable:io.BufferedReader,  order:list|None=None, chunk_size:int=1_000_000, delimiter:str=",", engine:CSVEngine='c'):
+        super().__init__(readable, chunk_size)
+
+
+        if order is None:
+            # we infer the header from the file, or use a default header
+            pass
+        else:
+            # Validate the parameters
+            if len(order) != 4:
+                raise ValueError("Order must be a list of 4 strings")
+            if "t" not in order or "x" not in order or "y" not in order or "p" not in order:
+                raise ValueError("Order must contain 't', 'x', 'y' and 'p'")
+
+        self._order = order
+        self._delimiter = delimiter
+        self._engine = engine
+
+        self._chunk_reader:TextFileReader|None= None
+
+    def _check_header(self):
+        have_header = False
+
+        # Check first line to see if it is a header
+        # TODO: Need to deal with non-seekable files
+        first_line: str = self._fd.readline().decode('utf-8').strip()
+
+        # Check if the first line is a header
+        # If we find a header, it will take precendence over the order parameter
+
+        if "t" in first_line or "x" in first_line or "y" in first_line or "p" in first_line:
+            # Header found
+            have_header = True
+
+        if have_header:
+            # We expect a header:
+            if "t" in first_line and "x" in first_line and "y" in first_line and "p" in first_line:
+                # Header found
+                order = first_line.split(",")
+
+                if self._order is not None and order != self._order:
+                    print(ValueError(f"WARNING: Header order {self._order} does not match order file {order}"))
+                self._order = order
+
+
+            else:
+                raise ValueError(f"Header not found or invalid: {first_line}")
+        else:
+            # No header found, just seek to start of file
+            self._fd.seek(0)
+
+        # If we still don't have a header, we use a default one
+        if self._order is None:
+            self._order = ['t', 'x', 'y', 'p']
+
+
+
+    def init(self):
+
+        self._check_header()
+
+        self._chunk_reader = pd.read_csv(self._fd, iterator=True, header=None, names=self._order, engine=self._engine,
+                                        delimiter=self._delimiter,  dtype={"t":"u8", "p":"u1", "x":"u2","y":"u2"})
+
+        # self.numpy_reader = np.fromtxt(self._fd, delimiter=",", dtype=np.uint64)
+        self._is_initialized = True
+
+
+    def read_chunk(self, delta_t_hint:int | None = None, n_events_hint:int | None = None) -> np.ndarray[Any, np.dtype[Any]]:
+        assert self._is_initialized, "Reader is not initialized"
+        assert self._chunk_reader is not None
+        # We can use the n_events_hint to read exactly n_events
+        #n_events_hint = None
+        #if not n_events_hint is None:
+        #    chunk_size = n_events_hint
+        #else:
+        #    chunk_size = self.chunk_size
+        chunk_size = self._chunk_size
+
+        try:
+            df = self._chunk_reader.get_chunk(chunk_size)
+            events = EventArray(df['t'].to_numpy(), df['x'].to_numpy(),
+                                df['y'].to_numpy(), df['p'].to_numpy())
+        except StopIteration:
+            events = EventArray.empty()
+
+        # Detect end of file
+        if len(events) < chunk_size:
+            self._eof = True
+
+        return events
+
+
+    def reset(self):
+        assert self._fd is not None
+        self._fd.seek(0)
+        self._check_header()
+
+
+
+class EventEncoder_Csv(EventEncoder):
+    '''
+    A writer for CSV files with events.
+
+    Parameters
+    ----------
+    file : str
+        Path to the data file
+    width : int, optional
+        Width of the frame, by default 1280 (not relevant for this formats)
+    height : int, optional
+        Height of the frame, by default 720 (not relevant for this formats)
+    sep : str, optional
+        Separator for the CSV file, by default ","
+    order : list, optional
+        Order of the columns in the CSV file, by default ['t', 'x', 'y', 'p']
+    header : bool, optional
+        If True, a header is written on the first line, by default True
+
+    Raises
+    ------
+    ValueError
+        If the order is not a list of 4 strings or if the order does not contain 't', 'x', 'y' and 'p'
+
+    '''
+
+    def __init__(self, writable: io.BufferedWriter, width:int=1280, height:int=720, sep:str=",", order:list=['t', 'x', 'y', 'p'], header:bool=True):
+        super().__init__(writable)
+
+
+        if len(order) != 4:
+            raise ValueError("Order must be a list of 4 strings")
+        if "t" not in order or "x" not in order or "y" not in order or "p" not in order:
+            raise ValueError("Order must contain 't', 'x', 'y' and 'p'")
+
+        self._order = order
+        self._header = header
+        self._sep = sep
+
+    def init(self):
+
+        if self._header:
+            header = self._sep.join(self._order) + "\n"
+            self._fd.write(header.encode('utf-8'))
+
+        self._is_initialized = True
+
+
+    def write(self, events: np.ndarray[Any, np.dtype[Any]]) -> int:
+        if not self._is_initialized:
+            self.init()
+
+        df = pd.DataFrame(events)
+        df.to_csv(self._fd, header=False, index=False, columns=self._order, sep=self._sep)
+        return len(events)
+

evutils/io/_dat.py

@@ -0,0 +1,30 @@
+
+import numpy as np
+
+from .common import EventDecoder, EventEncoder
+
+
+class EventDecoder_Dat(EventDecoder):
+    '''
+    A decoder for reading events from DAT files.
+
+    Parameters
+    ----------
+    file
+        Path to the data file
+    '''
+    def __init__(self, file):
+        super().__init__(file)
+
+
+class EventEncoder_Dat(EventEncoder):
+    '''
+    A encoder for writing events to DAT files.
+
+    Parameters
+    ----------
+    file
+        Path to the data file
+    '''
+    def __init__(self, file, width=1280, height=720):
+        super().__init__(file)