phonoscape 0.1.0__py3-none-any.whl

phonoscape/__init__.py

@@ -0,0 +1,74 @@
+import sys
+from pathlib import Path
+from typing import Unpack
+from PySide6.QtWidgets import QApplication
+import matplotlib.pyplot as plt
+
+from .data.parse import load_variables, normalize_args, import_proc_ctor, CmdArgs
+from .window import VarWindow, WindowManager
+from .lproc.protocol import LabelProcedure
+
+
+def phonoscape(file: str, variables: str = "*", **kwargs: Unpack[CmdArgs]) -> None:
+    plt.style.use("dark_background")
+
+    path = Path(file)
+    data, other_data, dimensions = load_variables(
+        path, variables, comps=kwargs.get("comps")
+    )
+
+    if not data:
+        raise ValueError(f"No matching variables found for pattern {variables!r}")
+
+    app_config, temporal_disp_specs, colors = normalize_args(
+        path, kwargs, data, other_data, dimensions
+    )
+
+    selected_variable = next(iter(data.keys()))
+
+    head_s = (kwargs.get("head") or 0) / 1000
+    tail_s = (kwargs.get("tail") or data[selected_variable].duration_s * 1000) / 1000
+    tail_s = min(tail_s, data[selected_variable].duration_s)
+    if head_s < 0:
+        raise ValueError(
+            f"--head must be a non-negative number of milliseconds, but got {head_s * 1000}"
+        )
+    if tail_s < 0:
+        raise ValueError(
+            f"--tail must be a non-negative number of milliseconds, but got {tail_s * 1000}"
+        )
+    if head_s >= tail_s:
+        raise ValueError(
+            f"--head must be less than --tail, but got head={head_s * 1000} and tail={tail_s * 1000}"
+        )
+    elif tail_s - head_s < 0.025:
+        raise ValueError(
+            f"The duration of the selection (tail - head) must be at least 25 milliseconds, but got head={head_s * 1000} and tail={tail_s * 1000} ({(tail_s - head_s) * 1000:.1f} ms)"
+        )
+
+    lproc_ctor_path = kwargs.get("lproc") or "phonoscape.lproc.lp_default"
+    lproc_ctor: type[LabelProcedure] = import_proc_ctor(lproc_ctor_path, "lp")
+
+    app = QApplication.instance()
+    owns_app = app is None
+
+    if app is None:
+        app = QApplication(sys.argv)
+
+    window_manager = WindowManager(lproc_ctor=lproc_ctor)
+    window = VarWindow(
+        window_manager=window_manager,
+        selected_variable=selected_variable,
+        temporal_disp_specs=temporal_disp_specs,
+        lproc_ctor=lproc_ctor,
+        colors=colors,
+        app_config=app_config,
+        view=kwargs.get("view") or (0, -90, 0),
+        head_s=head_s,
+        tail_s=tail_s,
+        custom={},
+    )
+    window.show()
+
+    if owns_app:
+        sys.exit(app.exec())

phonoscape/__main__.py

@@ -0,0 +1,157 @@
+from typing import cast
+from . import phonoscape
+
+if __name__ == "__main__":
+    import argparse
+
+    # [ ] CONFIG
+    # [ ] DPROC
+    # [x] FTRAJ
+    # [x] HEAD
+    # [ ] LABELS
+    # [ ] LPROC
+    # [x] IS3D
+    # [x] MAP / TEMPMAP
+    # [x] PALATE
+    # [x] PHARYNX
+    # [ ] PPROC
+    # [x] SEX
+    # [x] SPLINE
+    # [ ] SPREAD
+    # [x] TAIL
+    # [x] SPATEX
+    # [x] VIEW
+    # [x] NAME
+    # [x] VLIST
+    # [x] VLSEL
+    # [x] SPECLIM
+
+    parser = argparse.ArgumentParser(
+        description="PhonoScape: Visualize acoustics & articulatory data."
+    )
+    parser.add_argument("file", type=str, help="Path to the .mat file to visualize.")
+    parser.add_argument(
+        "variables",
+        type=str,
+        nargs="?",
+        default="*",
+        help="Glob pattern to filter variables (default: '*').",
+    )
+    parser.add_argument(
+        "--palate",
+        type=str,
+        metavar="VAR",
+        help="Variable name for palate trace (optional).",
+    )
+    parser.add_argument(
+        "--pharynx",
+        type=str,
+        metavar="VAR",
+        help="Variable name for pharynx trace (optional).",
+    )
+    parser.add_argument(
+        "--spline",
+        type=str,
+        nargs="+",
+        metavar="TRAJ",
+        help="List of trajectory names to apply spline interpolation (default: all spatial trajectories starting with 'T').",
+    )
+    parser.add_argument(
+        "--polyline-spline",
+        action="store_true",
+        help="Connect the --spline points with a polyline instead of a smooth spline.",
+    )
+    parser.add_argument(
+        "--audio",
+        type=str,
+        metavar="TRAJ",
+        help="Variable name for audio trajectory - for spectrogram plotting and playback (default: first scalar trajectory with sampling rate > 1000 Hz).",
+    )
+    parser.add_argument(
+        "--framing",
+        type=str,
+        metavar="TRAJ",
+        help="Variable name for framing trajectory (default: --audio, or first trajectory if no audio found).",
+    )
+    parser.add_argument(
+        "--temporal-display",
+        type=str,
+        metavar="SPEC",
+        nargs="+",
+        help="List of variable names to include in temporal display (default: all plus {--audio}_SPECT).",
+    )
+    parser.add_argument(
+        "--spatial-exclude",
+        type=str,
+        nargs="+",
+        metavar="TRAJ",
+        help="List of trajectory names to exclude from the spatial view (default: none).",
+    )
+    parser.add_argument(
+        "--comps",
+        type=int,
+        nargs="+",
+        metavar=("N|COL", "COL"),
+        help="Number of dimensions for spatial trajectories, or list of column indices to use for each dimension (default: all dimensions, up to 3, are used for spatial view in x,y,z order).",
+    )
+    parser.add_argument(
+        "--view",
+        type=float,
+        nargs=3,
+        metavar=("ELEV", "AZIM", "ROLL"),
+        help="Initial view angles (degrees) for the 3D spatial display: azimuth, elevation and roll. Only has an effect when the data is 3D. Only has an effect on the first opened window; subsequent windows inherit the opening window's view (default: 0, -90, 0).",
+    )
+    parser.add_argument(
+        "--head",
+        type=float,
+        metavar="MS",
+        help="Start of selection (ms) for the temporal view (default: 0).",
+    )
+    parser.add_argument(
+        "--tail",
+        type=float,
+        metavar="MS",
+        help="End of selection (ms) for the temporal view (default: duration of the current trajectory).",
+    )
+    parser.add_argument(
+        "--sex",
+        choices=["M", "F"],
+        help="Pass 'F' for female, 'M' for male. This can be later customized in the 'Configure spectral analysis' dialog, but it affects the default LPC degree (default: M).",
+    )
+    parser.add_argument(
+        "--spect-lim",
+        type=float,
+        metavar="HZ",
+        help="Frequency upper limit (Hz) for spectrogram display (default: Nyquist frequency).",
+    )
+    parser.add_argument(
+        "--lproc",
+        type=str,
+        metavar="PROC",
+        help="Label procedure to use for labeling (default: none).",
+    )
+    args = parser.parse_args()
+
+    phonoscape(
+        args.file,
+        args.variables,
+        palate=args.palate,
+        pharynx=args.pharynx,
+        spline=args.spline,
+        polyline_spline=args.polyline_spline,
+        audio=args.audio,
+        framing=args.framing,
+        temporal_display=args.temporal_display,
+        spatial_exclude=args.spatial_exclude,
+        comps=(
+            None
+            if not args.comps
+            else args.comps[0] if len(args.comps) == 1 else args.comps
+        ),
+        view=cast(tuple[float, float, float], tuple(args.view)) if args.view else None,
+        head=args.head,
+        tail=args.tail,
+        sex=args.sex,
+        spect_lim=args.spect_lim,
+        lproc=args.lproc,
+    )