aviSegment

Interactive segmentation and analysis of laryngoscopic high-speed video: the glottal opening is segmented frame-by-frame and both the Glottal Area Waveform (GAW) and the Phonovibrogram (PVG) are computed from the masks.

This repository contains the released standalone application (aviSegment.exe) plus the full source code in forCompiling/, including the C segmentation and PVG kernels.

About

The app loads an AVI video of the larynx and segments the glottal opening in every frame:

1. Load video - all frames are read into memory.
2. Thresholding - four horizontal bands divide the image; each band has a pixel-value threshold. A pixel is foreground ("open glottis") iff pixel < threshold(row) * smoothing(col).
3. Smoothing fade - a pchip curve (factor 0..1) across the image width scales the threshold to fade out artefacts near the left/right image edges.
4. Keyframes - thresholds can be set per frame and are interpolated across all other frames; keyframes are managed via the frame listbox.
5. Segmentation - user-placed seed crosses restrict the region. A Line-of-Sight (LOS) alpha C kernel fills holes, concavities and gaps between blobs; a pure-MATLAB alpha-shape fallback is used if the MEX is absent.
6. GAW / PVG - the Glottal Area Waveform and the Phonovibrogram are computed from the segmented masks.

Getting started

Option A: Standalone application (no MATLAB licence needed)

1. Install the MATLAB Runtime 2022a (Windows x64) once on the target machine.
2. Download aviSegment.exe and run it.
3. A MATLAB licence is not required.

Option B: Run from source in MATLAB

1. You need a recent MATLAB release (Windows x64) with the Image Processing Toolbox.

2. Open the forCompiling/ folder in MATLAB and run:

   cd forCompiling
   aviSegment

3. About the prebuilt MEX kernels (los_extract_batch.mexw64, pvgextract_batch.mexw64): MEX files are tied to the MATLAB release they were compiled against (the files shipped here match the release build). If a MEX is missing or incompatible, the app automatically falls back to the slower pure-MATLAB pipeline. To rebuild the kernels for a different MATLAB release, use the build scripts documented in seg_extraction/README.md and pvg_extraction/README.md.

Typical workflow

1. Load an AVI (Load file).
2. Place the four threshold lines on the image and set the seed crosses that mark the region to segment.
3. Scroll through the video and adjust thresholds; set threshold keyframes in frames where the illumination changes.
4. Optionally refine the edge fade with smoothing points.
5. Tune the alpha radii and, if desired, switch the LOS distance metric to Euclidean (instead of the default Chebyshev).
6. Use the frame range slider or the start/end frame fields to restrict analysis to a subset of the recording.
7. Compute GAW / PVG and export the results.

Controls overview

• Frame slider - step through the video; the app re-segments the current frame live.
• Range slider + start/end fields - restrict segmentation and GAW/PVG computation to a frame subset.
• Threshold lines / threshold plot / smoothing fade - set the four band thresholds and the edge-fading curve.
• Threshold keyframe listbox (+/-) - add/remove per-frame threshold keyframes; the app interpolates between them.
• Seed crosses (+/-) - place/remove the segmentation seed grid.
• Alpha radii - per-blob and after-blob alpha radius for gap filling.
• "Use Euclidean" checkbox - distance metric for the LOS alpha radius (default off = Chebyshev/block distance).
• Mask overlay transparency + color - visualize the segmentation overlay.
• GAW/PVG window (reached via Preview GAW) - calculate GAW and PVG, set the PVG excerpt, and save results as image or video.

Keyboard & mouse

• Mouse wheel - one frame forward/backward.
• Arrow keys - right/left = ±1 frame, down/up = ±10 frames.

Output formats

• GAW: semicolon-delimited text with columns Sample, Time, GAW, Interior GAW.
• Mask videos: AVI from the segmented masks - black/white, inside black / outside original, or outside white / inside original.
• PVG: PNG image (before saving, the PVG is already visible in the GAW/PVG window).

Repository layout

githubRepo/
├── aviSegment.exe               released standalone application (requires
│                                MATLAB Runtime 2022a)
├── ReleaseNotes.txt             version history (newest first)
├── LICENSE                      MIT license
├── CITATION.cff                 citation metadata (cite this repository)
└── forCompiling/                everything needed to build & run from source
    ├── aviSegment.m             main interactive application
    ├── compileAviSegment.m      build script: assembles the standalone app
    │                            and the forCompiling folder (MATLAB Compiler)
    ├── drawMajorAxis.m          pure-MATLAB PVG reference (fallback)
    ├── distinguishable_colors.m colour helper for the overlay
    ├── los_extract_batch.mexw64 LOS segmentation kernel (fast path)
    ├── pvgextract_batch.mexw64  PVG extraction kernel (fast path)
    ├── seg_extraction/          segmentation kernels (approach + benchmarks +
    │                            build scripts + own README)
    └── pvg_extraction/          PVG kernels (approach + benchmarks +
                                 build scripts + own README)

Building the standalone application

If you want to rebuild the .exe yourself:

1. Install MATLAB R2022a with the MATLAB Compiler and the Image Processing Toolbox.
2. Rebuild the MEX kernels against R2022a (see the two sub-READMEs, the MEX ABI must match the runtime).
3. Run compileAviSegment; it builds the standalone application, copies the .exe to githubRepo/, and refreshes the forCompiling/ folder with all required files.

License & citation

Released under the MIT License - see LICENSE.

If you use this software in your research, please cite it; see CITATION.cff for the citation metadata.