Getting Started

This page takes you from installation to a first viewer session.

Installation Profiles

Most users should install the desktop viewer profile:

pip install "filark[gui]"

Install the GUI viewer plus PyTorch-backed operators:

pip install "filark[all]"

Install only the core package for server-side I/O, DSP, pipelines, and headless scripting:

pip install filark

Development checkout:

git clone https://github.com/JintaoLee-Roger/filark.git
cd filark
pip install -e ".[all]"

The GUI requires PySide6. GPU operators use PyTorch when available. JAX and CuPy are left as manual installs because their wheels depend on platform and accelerator setup.

Note

FiLark keeps GUI dependencies optional at the package level, but the documentation recommends filark[gui] because the desktop viewer is the main workflow for most users. Python packaging supports positive extras such as filark[gui], but it does not provide a clean cross-tooling way to install a package with default GUI dependencies and then subtract them with something like filark[no-gui].

Launch The GUI

Command line:

filark
filark --theme light
filark --f path/to/data.h5

Python:

from filark.gui.app import run_app

run_app()
run_app(theme="light")
run_app(source="path/to/data.h5")

Configuration object:

from filark.gui.app import run_app
from filark.gui.config import GuiConfig

cfg = GuiConfig(
    theme="dark",
    async_io=True,
    default_buffer_h=2048,
)

run_app(cfg=cfg, source="path/to/data.h5")

Open A Source

FiLark can start from paths, arrays, or Tape objects.

from filark.gui.app import run_app
from filark.io.tapeio import H5Tape, NpyTape, BinTape

h5 = H5Tape("data/example.h5")
run_app(source=h5)

npy = NpyTape("data/example.npy", dims="nt_nc", fs=1550, dx=5, dx_unit="m")
run_app(source=npy)

bin_tape = BinTape(
    "data/example.dat",
    nt=93000,
    nc=6455,
    dtype="float32",
    dims="nt_nc",
    fs=1550,
    dx=5,
    dx_unit="m",
)
run_app(source=bin_tape)

For a folder of compatible files:

from filark.io.fileset import TapeFileSet

source = TapeFileSet("data/DS", suffixes=(".h5", ".hdf5"))
run_app(source=source)

The Load Data panel can also open a file or folder interactively. For raw formats where metadata is not discoverable, the panel asks for layout, dimensions, sample rate, spacing, dtype, and optional gauge length.

First GUI Session

  1. Open a source from the Load Data tab or pass it to run_app.

  2. Use the arrow keys to pan time and channels.

  3. Press F to fit the visible channel range.

  4. Press X or Y to adjust display downsampling.

  5. Open the Annotation tab, choose a mode, and draw with Ctrl held.

  6. Open the Algorithms tab to create an ROI or run monitor plugins.

For keyboard details, see Keyboard Shortcuts.

Example Demos

The repository includes scripts that launch configured GUI sessions:

python scripts/realtime_monitor_demo.py
python scripts/realtime_monitor_demo.py --quiet-monitor
python scripts/active_source_monitor_demo.py

The realtime demo registers a fake monitor plugin that emits bbox, polyline, and mask events. The active-source demo is model-specific and expects the data/DAS_inference assets to be present.