Spectrogram Slicer & Windowizer — Complete Documentation

Index

Overview
Features
Dependencies
Code Architecture
- Functional Flow
- Component Diagram
GUI Layout & Controls
- Control Panel
- Plot Area
Core Functionalities
Helper Functions
Threading & Responsiveness
Diagrams
- Data Processing Pipeline
- Object Structure
Customization & Extension
API Documentation
FAQs & Common Errors
Conclusion

Overview

Spectrogram Slicer & Windowizer is a modern, interactive GUI tool built using CustomTkinter for efficiently handling batches of 2D spectrogram data (stored as .npy NumPy arrays).

✨ Main Goals:

Batch load sets of spectrogram arrays from disk.
(Optional) Average pooling to downsample spectrograms.
Interactive region selection (time/frequency ranges).
Windowize (split into patches) selected regions.
Skip, slice, or save as needed.
Accumulate results and save them to disk incrementally or at the end.

Features

Feature	Description
📂 Batch Load	Load many `.npy` files (with glob pattern) from a folder.
➗ Average Pooling	Optionally pool spectrograms to reduce time/freq resolution.
🖱 Interactive Slicing	Select regions by adjusting sliders for time/frequency.
🔪 Windowizing	Crop regions into windows/patches for ML pipelines.
⏭ Skip	Skip unwanted spectrograms instantly.
💾 Partial Save	Save & clear accumulated windows, freeing RAM.
🚀 Final Export	Export all remaining windows in one go.
🧮 Progress Bar	See batch loading progress.
📊 Live Preview	See the currently loaded or selected spectrogram region.
🌓 Modern UI	Dark mode, responsive layouts via CustomTkinter.

Dependencies

customtkinter
matplotlib
scikit-image
numpy
tkinter (standard library)

Install:
pip install customtkinter matplotlib scikit-image numpy

Code Architecture

This project is a single-file GUI application centered around the SpectGUI class, which encapsulates all business logic, state management, and UI construction.

Functional Flow

flowchart TD
    subgraph User
        A1(Browse Folder)<--Click-->A2(Load Files)<--Progress-->A3(Slice/Skip)<--Slice/Skip-->A4(Partial Save/Finish)
    end

    subgraph App
        B1[Load npy files]<--(Optional) Pool-->B2[Store loaded spectrograms]
        B2--Display-->B3[Interactive Plot & Sliders]
        B3--Select region-->B4[Windowize region]
        B4--Store-->B5[All Windows List]
        B5--Partial Save-->B6[Disk: NPY file]
        B5--Finish & Save-->B7[Disk: NPY file]
    end

    A1-->|Files|B1
    A2-->|Progress|B1
    A3-->|Slice|B4
    A3-->|Skip|B2
    A4-->|Save|B6
    A4-->|Finish|B7

Component Diagram

classDiagram
    class SpectGUI {
        - np.ndarray~spects~
        - int idx
        - list~np.ndarray~ all_windows
        - np.ndarray? all_windows_array
        - int total_saved_windows
        - int partial_save_count
        - int pool_t, pool_f, win_t, win_f, step_t, step_f
        + __init__()
        + _build_controls()
        + _build_plot()
        + _start_loading()
        + _load_and_pool()
        + _reset_sliders()
        + _slider_update()
        + _update_action_buttons()
        + _plot_current(full)
        + _on_slice()
        + _skip_spect()
        + _advance()
        + _on_skip_pool_toggle()
        + _save_and_clear_windows()
        + _finish()
    }
    SpectGUI --|> ctk.CTk : inherits

GUI Layout & Controls

Control Panel

Control	Description
Folder Path Entry	Path to folder containing `.npy` files
Browse Button	Opens folder picker dialog
Glob Pattern Entry	Pattern for file matching (e.g. `27H.npy`)
Pooling Window Entries	Size of pooling window in time/freq
Skip Pooling Checkbox	Use original or pooled inputs
Window & Step Entries	Window and step sizes for slicing
Load Button	Loads and (optionally) pools files
Progress Bar	Loading progress indicator
Time/Freq Sliders	Adjust selected region (sliders appear after loading)
Slice & Next	Slice current region and move to next
Skip Spect	Skip current spectrogram
Save & Clear Windows	Save accumulated windows to disk, clear RAM
Finish & Save	Final save of all remaining windows
Status Label	Displays current processing info

Plot Area

Matplotlib Figure: Displays current full or partial spectrogram (with region preview if slicing).
Navigation Toolbar: Standard Matplotlib controls (zoom, pan, etc.).

Core Functionalities

Loading & Pooling

File Selection: User selects folder and pattern; files are matched using glob.
Average Pooling (optional): If enabled, each spectrogram array is downsampled using a pooling window (time, freq).
- Pooling can be skipped for already pooled arrays.
Progress Bar: Updates as files are loaded and processed.

Average Pooling Implementation

Tries to import a custom util.average_pooling if available.
Fallback: Locally implemented safe_average_pooling() using skimage's view_as_blocks.

Pooling Algorithm

Pads input if needed to ensure divisibility by pooling window.
Computes mean of each block.
Offers normalization (max, l2, or none).

Slicing & Windowizing

Sliders: After loading, sliders for selecting time and frequency indices become active.
Minimum Size Enforcement: Slices must meet minimum width/height in time/freq.
Live Preview: As sliders move, plot updates to show selected region.
Windowizing: Selected region is split into smaller windows (patches) using view_as_windows, with customizable window and step sizes.
Accumulation: Windows are stored in RAM until saved or cleared.

Saving & Exporting

Partial Save: Accumulated windows can be saved and cleared at any time. Useful for large datasets (frees RAM).
Final Export: At the end (or after skipping through all spectrograms), remaining windows can be saved.
NPY Format: All saves use the standard NumPy .npy format for compatibility with ML pipelines.

Helper Functions

Function	Description
`safe_average_pooling()`	Robust average pooling for 2D arrays.
`rescale()`	Rescales spectrogram intensities for display (2-98th percentile stretch).
`windowize()`	Splits a region into windows/patches of fixed size with a given step.

Threading & Responsiveness

Threaded Loading: File loading and pooling is run in a background thread, keeping the UI responsive.
Tkinter Mainloop: All GUI updates (incl. progress) are safely handled.

Diagrams

Data Processing Pipeline

sequenceDiagram
    participant User
    participant GUI as SpectGUI
    participant Disk as NPY Files
    participant RAM as RAM
    participant DiskOut as Output NPY

    User->>GUI: Select folder, pattern, pooling, etc.
    GUI->>Disk: Load .npy files
    Disk-->>GUI: Return array(s)
    GUI->>GUI: (Optional) Average pool each array
    GUI->>RAM: Store loaded/pooled spectrograms

    loop For each spectrogram
        GUI->>User: Show region selection controls
        User->>GUI: Adjust sliders
        GUI->>GUI: Preview selected region
        User->>GUI: Click "Slice & Next" or "Skip"
        alt Slice & Next
            GUI->>GUI: Windowize selected region
            GUI->>RAM: Store windows
        end
    end

    alt Partial Save
        User->>GUI: Click "Save & Clear"
        GUI->>DiskOut: Write accumulated windows (NPY)
        GUI->>RAM: Clear accumulated windows
    end

    User->>GUI: Click "Finish & Save"
    GUI->>DiskOut: Write all windows (NPY)
    GUI->>RAM: Clear all windows

Object Structure

classDiagram
    class SpectGUI {
        - np.ndarray[] spects
        - int idx
        - np.ndarray[] all_windows
        - np.ndarray? all_windows_array
        - int total_saved_windows
        - int partial_save_count
        - int pool_t, pool_f, win_t, win_f, step_t, step_f
        + __init__()
        + _start_loading()
        + _load_and_pool()
        + _reset_sliders()
        + _slider_update()
        + _update_action_buttons()
        + _plot_current()
        + _on_slice()
        + _skip_spect()
        + _advance()
        + _on_skip_pool_toggle()
        + _save_and_clear_windows()
        + _finish()
    }
    SpectGUI --|> ctk.CTk

Customization & Extension

Pooling Method: Extend by supplying your own util.average_pooling in PYTHONPATH.
Spectrogram Shape: Adjust minimum slice sizes by changing MIN_T_DIFF and MIN_F_DIFF.
Window/Step Sizes: Highly customizable via the GUI.

API Documentation

This is a desktop GUI app, not an HTTP API, so API blocks are not relevant.

FAQs & Common Errors

Q: Why does loading fail or files are skipped?

A: File must be NumPy .npy arrays containing 2D arrays (time, freq). Errors are printed and skipped.

Q: Why is "Slice & Next" disabled?

A: The selected region is too small. Enlarge your selection so that (t1-t0) ≥ 24 and (f1-f0) ≥ 96.

Q: Why does saving fail?

A: Check permissions or disk space. Also ensure you have actually accumulated windows to save.

Conclusion

Spectrogram Slicer & Windowizer is a robust, extensible GUI for ML practitioners and researchers working with large batches of 2D spectrogram data. Its interactive, step-by-step workflow and efficient memory management make it a valuable tool for data curation, patch extraction, and dataset preparation.

🛠 Example Usage

Launch the app:
```
python main.py
```
Select folder containing your .npy spectrogram files.
Adjust pooling and windowing parameters as needed.
Load files and interactively select/slice regions of interest.
Save windows incrementally or after finishing all files.

📝 Additional Notes

All data is processed in-memory and export is in NumPy format for easy ML integration.
UI is fully responsive even during heavy operations thanks to background threading.
Uses percentile-based intensity rescaling for clear, consistent visualization.

Happy slicing! 🎶🔬🖥

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
main.py		main.py
readme.md		readme.md
spect_slice.code-workspace		spect_slice.code-workspace

Woffleisme/spect_slice

Folders and files

Latest commit

History

Repository files navigation