Skip to content

Add privacy-conscious waveform fixture extractor#29

Draft
sslnevefocusrite wants to merge 2 commits into
DigitalHolography:mainfrom
sslnevefocusrite:codex/extract-waveform-fixtures
Draft

Add privacy-conscious waveform fixture extractor#29
sslnevefocusrite wants to merge 2 commits into
DigitalHolography:mainfrom
sslnevefocusrite:codex/extract-waveform-fixtures

Conversation

@sslnevefocusrite

@sslnevefocusrite sslnevefocusrite commented Jul 18, 2026

Copy link
Copy Markdown

Summary

Adds a standalone extraction utility and a double-click Windows application for
creating compact waveform-only HDF5 fixtures from EyeFlow outputs. This enables
beat-detection and waveform-metric robustness testing without transferring
complete acquisition files.

Windows release:
EyeFlow Waveform Fixture Extractor 0.1.0

What changed

  • Added tools/extract_waveform_fixture.py with file, folder, recursive,
    dry-run, overwrite, and size-limit modes.
  • Added a Tkinter interface with separate Validate inputs and
    Extract fixtures actions.
  • Added a reproducible PyInstaller build script for a single-file Windows app.
  • Supports both legacy full-output and current slim-output dataset paths.
  • Copies only an explicit allow-list of numeric artery/vein waveforms, beat
    timing, and optional per-beat signals.
  • Derives and records the sample interval from beat periods and boundary
    indexes.
  • Uses content-derived output names to avoid carrying source filenames into
    fixtures and to reuse duplicates safely.
  • Strips source HDF5 attributes and excludes images, masks, velocity volumes,
    maps, filenames, and acquisition metadata.
  • Marks every output as patient-derived and includes an explicit privacy
    warning.
  • Added command-line, graphical-app, build, checksum, and governance guidance
    to the README.
  • Added eight tests covering allow-listing, metadata removal, schema aliases,
    duplicate reuse, malformed inputs, recursive discovery, GUI validation, and
    GUI extraction.

Why

Full EyeFlow outputs can be hundreds of megabytes and may contain patient or
acquisition metadata that is unnecessary for beat-detection and waveform-metric
robustness testing. This utility produces small, purpose-limited fixtures while
making clear that metadata removal does not make clinical waveforms
non-sensitive.

Validation

  • Eight focused extraction and GUI-job tests pass.
  • All 67 repository tests pass.
  • Ruff reports no issues in the extractor source and tests.
  • A packaged executable self-test completed successfully on a full EyeFlow H5.
  • A 516.85 MB EyeFlow output produced a 539.3 KiB fixture containing 15
    allow-listed datasets.
  • Verified that the fixture did not contain the source filename, identifying
    attributes, or the full retinal velocity volume.
  • The release checksum matches the executable.
  • Microsoft Defender found no threats in the release executable.

Privacy and signing

Extracted waveforms remain patient-derived and potentially sensitive. They
should not be uploaded to a public repository without explicit approval.

The downloadable executable is not code-signed. Windows SmartScreen may show an
unrecognized-app warning; the release includes a SHA-256 checksum for
verification.

This remains a draft so the fixture contract and privacy boundary can be
reviewed before merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant