Metadata-Version: 2.4
Name: filark
Version: 0.0.3
Summary: High-performance DAS visualization and analysis tool
Author-email: Jintao Li <lijintaobt@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/JintaoLee-Roger/filark
Project-URL: Documentation, https://filark.readthedocs.io
Keywords: visualization,geophysics,DAS,Fiber
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: matplotlib
Requires-Dist: vispy
Requires-Dist: h5py
Requires-Dist: scipy
Provides-Extra: gui
Requires-Dist: PySide6; extra == "gui"
Provides-Extra: gpu
Requires-Dist: torch; extra == "gpu"
Provides-Extra: all
Requires-Dist: PySide6; extra == "all"
Requires-Dist: torch; extra == "all"
Dynamic: license-file

# FiLark

FiLark is a Python framework for streaming-first visualization, ROI analysis,
and signal processing for distributed acoustic sensing (DAS) data.

The project is built around one practical constraint: DAS recordings are often
too large to treat as ordinary in-memory arrays. FiLark therefore keeps data
access, visualization, ROI inspection, and processing aligned around streaming
windows instead of one-off extracted snippets.

## What FiLark Provides

- A Qt + VisPy desktop viewer for large DAS arrays.
- A fixed-size OpenGL ring-buffer renderer for deterministic navigation through
  long recordings.
- Tape abstractions for H5, NPY, binary files, arrays, and stitched folders.
- ROI analysis windows for PSD, STFT, F-K, tau-p, RMS, SVD, cross-correlation,
  and denoising previews.
- Display-side stream preprocessing and filters for exploratory browsing.
- DSP operators and chunked pipelines that can be used without the GUI.

FiLark is still evolving quickly. This branch intentionally exposes only the
viewer, ROI analysis, and processing workflow.

## Installation

Most users should install the desktop viewer profile:

```bash
pip install "filark[gui]"
```

Install the GUI viewer plus PyTorch-backed operators:

```bash
pip install "filark[all]"
```

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

```bash
pip install filark
```

Development checkout:

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

`JAX` and `CuPy` are not installed automatically because their wheels are
platform-specific.

## Launch The Viewer

From the command line:

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

From Python:

```python
from filark.gui.app import run_app

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

With a configuration object:

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

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

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

If `PySide6` is missing, the GUI entry points raise a clear install message with
the exact `python -m pip install "filark[gui]"` command.

## Open Common DAS Sources

```python
from filark.gui.app import run_app
from filark.io.fileset import TapeFileSet
from filark.io.tapeio import BinTape, H5Tape, NpyTape

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

# NPY file or ndarray.
tape = NpyTape("data/example.npy", dims="nt_nc", fs=1550, dx=5, dx_unit="m")
run_app(source=tape)

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

# Folder stitched as one logical stream.
tape = TapeFileSet("data/DS", suffixes=(".h5", ".hdf5"))
run_app(source=tape)
```

The GUI load panel can also open `.h5`, `.npy`, `.dat`, `.bin`, and folders.
When metadata is not recoverable from the file, the load panel asks for layout,
sample rate, channel spacing, dtype, dimensions, and optional gauge length.

## Configure Display And ROI Processing

Most project-specific behavior should be registered through `GuiConfig` rather
than hard-coded into the application.

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

cfg = GuiConfig(
    loaders=[...],    # custom source loaders
    processors=[...], # ROI processing processors
)

run_app(cfg=cfg)
```

For display-side preprocessing, pass transform objects or factories:

```python
import filark.dsp.transforms as T
from filark.gui.app import run_app
from filark.gui.config import GuiConfig

cfg = GuiConfig(
    stream_preprocess=[
        T.DeMeanTime(),
        T.AGCTime(half_window=50),
    ],
)

run_app(cfg=cfg, source="data/example.h5")
```

## Repository Map

- `filark/io`: Tape interfaces, file readers, folder stitching, streaming
  source adapters.
- `filark/viz`: VisPy canvas, ring-buffer image visual, scheduler, and camera.
- `filark/gui`: Qt application, panels, controllers, and ROI windows.
- `filark/dsp`: Array-first DSP functions, chunk helpers, transform objects,
  and PyTorch-backed GPU variants.
- `filark/pipeline`: Chunked processing execution for large sources.
- `filark/processing`: GUI-facing ROI processor schemas and helpers.
- `filark/utils`: Coordinates, memory, performance, and time helpers.
- `docs`: the Sphinx documentation site.
- `latex`: manuscript material. It explains the research motivation, but the
  user documentation is maintained separately in `docs`.

## Documentation

Build the docs locally:

```bash
pip install -r docs/requirements.txt
sphinx-build -b html docs docs/_build/html
```

Main pages:

- `docs/getting_started.md`
- `docs/basic_usage.md`
- `docs/concepts.md`
- `docs/io_loader_guide.md`
- `docs/visualization.md`
- `docs/dsp_pipeline.md`

## License

FiLark is released under the MIT License.
