flimkit 0.12.0__py3-none-any.whl

flimkit/UI/utils.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+import re
+import time
+import threading
+import tkinter as tk
+from tkinter import ttk, filedialog, scrolledtext
+from pathlib import Path
+from typing import Optional
+import numpy as np
+from flimkit.UI.fit_help import help_button
+from flimkit.utils.config_snapshot import _C
+from flimkit.utils.session import (
+    _reconstruct_dict_from_session,
+    _safe_array_from_json,
+    _parse_summary,
+)
+try:
+    from tkinterdnd2 import DND_FILES, DND_TEXT
+    HAS_DND = True
+except ImportError:
+    HAS_DND = False
+
+def _enable_dnd(root):
+    if not HAS_DND:
+        return False
+    try:
+        from tkinterdnd2 import TkinterDnD
+        TkinterDnD._require(root)
+        return True
+    except Exception:
+        return False
+
+class _Redirect:
+
+    def __init__(self, widget: scrolledtext.ScrolledText, buf: list, root=None, is_stderr=False):
+        self.widget = widget
+        self.buf = buf
+        self.root = root
+        self._is_stderr = is_stderr
+        self._batch = []
+        self._batch_size = 5000
+        self._last_flush = time.time()
+        self._flush_interval = 0.5
+
+    def write(self, text: str):
+        if not text:
+            return
+        self.buf.append(text)
+        self._batch.append(text)
+        if self._is_stderr:
+            try:
+                from flimkit.utils.crash_handler import log_event
+                log_event(f'STDERR: {text.rstrip()}', level='warning')
+            except Exception:
+                pass
+        should_flush = False
+        if len(''.join(self._batch)) >= self._batch_size:
+            should_flush = True
+        elif time.time() - self._last_flush >= self._flush_interval:
+            should_flush = True
+        if should_flush:
+            self._flush_batch()
+
+    def _flush_batch(self):
+        if not self._batch:
+            return
+        text = ''.join(self._batch)
+        self._batch.clear()
+        if self.root:
+            self.root.after(0, self._update_widget, text)
+        else:
+            self._update_widget(text)
+
+    def _update_widget(self, text):
+        try:
+            self.widget.configure(state='normal')
+            self.widget.insert(tk.END, text)
+            self.widget.see(tk.END)
+            self.widget.configure(state='disabled')
+            self.widget.update_idletasks()
+        except Exception:
+            pass
+        self._last_flush = time.time()
+
+    def flush(self):
+        self._flush_batch()
+
+class _FileRedirect:
+
+    def __init__(self, filepath: str, buf: list):
+        self.filepath = filepath
+        self.buf = buf
+        self._file = None
+        try:
+            self._file = open(filepath, 'w', buffering=1)
+        except Exception:
+            pass
+
+    def write(self, text: str):
+        if not text:
+            return
+        self.buf.append(text)
+        if self._file:
+            try:
+                self._file.write(text)
+            except Exception:
+                pass
+
+    def flush(self):
+        if self._file:
+            try:
+                self._file.flush()
+            except Exception:
+                pass
+
+    def close(self):
+        if self._file:
+            try:
+                self._file.close()
+            except Exception:
+                pass
+            self._file = None
+
+class _FileTailer:
+
+    def __init__(self, filepath: str, widget: scrolledtext.ScrolledText, update_interval_ms: int = 200):
+        self.filepath = filepath
+        self.widget = widget
+        self.update_interval_ms = update_interval_ms
+        self._file = None
+        self._last_pos = 0
+        self._running = False
+
+    def start(self, root):
+        self._running = True
+        self._poll_file(root)
+
+    def _poll_file(self, root):
+        if not self._running:
+            return
+        try:
+            if not Path(self.filepath).exists():
+                root.after(self.update_interval_ms, lambda: self._poll_file(root))
+                return
+            with open(self.filepath, 'r') as f:
+                f.seek(self._last_pos)
+                new_content = f.read()
+                self._last_pos = f.tell()
+            if new_content:
+                self.widget.configure(state='normal')
+                self.widget.insert(tk.END, new_content)
+                self.widget.see(tk.END)
+                self.widget.configure(state='disabled')
+                self.widget.update_idletasks()
+        except Exception:
+            pass
+        root.after(self.update_interval_ms, lambda: self._poll_file(root))
+
+    def stop(self):
+        self._running = False
+
+PAD = dict(padx=8, pady=4)
+
+from flimkit.formats import file_dialog_filetypes
+FLIM_FILETYPES = file_dialog_filetypes() + [('All', '*.*')]
+
+def _browse_file(var, title='Select file', filetypes=(('All', '*.*'),)):
+    p = filedialog.askopenfilename(title=title, filetypes=filetypes)
+    if p:
+        var.set(p)
+
+def _browse_dir(var, title='Select directory'):
+    p = filedialog.askdirectory(title=title)
+    if p:
+        var.set(p)
+
+def _row(parent, label, var, row, browse_fn, width=45, state='normal'):
+    ttk.Label(parent, text=label).grid(
+        row=row, column=0, sticky='e', padx=6, pady=3)
+    e = ttk.Entry(parent, textvariable=var, width=width, state=state)
+    e.grid(row=row, column=1, sticky='ew', padx=4, pady=3)
+    ttk.Button(parent, text='Browse...', command=browse_fn).grid(
+        row=row, column=2, padx=4, pady=3)
+    if HAS_DND:
+        try:
+            def _drop_handler(event):
+                data = event.data.strip()
+                if data.startswith('{') and data.endswith('}'):
+                    data = data[1:-1]
+                var.set(data)
+            e.drop_target_register(DND_FILES, DND_TEXT)
+            e.dnd_bind('<<Drop>>', _drop_handler)
+        except Exception:
+            pass
+    return e
+
+def _section(parent, text: str, help_topic: Optional[str] = None) -> ttk.LabelFrame:
+    lf = ttk.LabelFrame(parent, text=f'  {text}  ', padding=(10, 6))
+    if help_topic:
+        holder = ttk.Frame(lf)
+        ttk.Label(holder, text=f'  {text} ').pack(side='left')
+        help_button(holder, help_topic).pack(side='left', padx=(0, 6))
+        lf.configure(labelwidget=holder)
+    return lf
+
+def _tog(bvar: tk.BooleanVar, entry: ttk.Entry):
+    entry.configure(state='normal' if bvar.get() else 'disabled')
+
+def _flt(sv: tk.StringVar) -> Optional[float]:
+    v = sv.get().strip()
+    return float(v) if v and v.lower() != 'none' else None
+
+def _thresh(bvar: tk.BooleanVar, sv: tk.StringVar):
+    if not bvar.get():
+        return None
+    v = sv.get().strip()
+    return int(v) if v else None

flimkit/_version.py

@@ -0,0 +1,41 @@
+__version__ = '0.12.0'
+fitter_version = '19'
+
+roadmap = '''Flim program roadmap:
+Version history:
+0.1.0 -> Initial version with basic FLIM fitting functionality
+0.1.1 -> Added command line interface (CLI) for single FOV fitting
+0.1.2 -> Added support for IRF estimation from XLSX files
+0.1.3 -> Added some user prompts and created defaults
+0.1.4 -> Updated interactive prompts and added some error handling
+Will be updated to 0.2.0 when ROI stitching works
+0.3.0 -> ROI stiching + fitting
+0.4.0 -> batch processing of multiple ROIs or FOVs
+0.5.0 -> tbd
+Need to add Phasor once added to the codebase, and update version to 1.0. And added some tests.
+0.8.0 -> added per-tile machine IRF fitting workflow, updated docs and examples
+0.8.1 -> added some error handling and user prompts to per-tile machine IRF workflow
+0.8.2 -> added some more error handling and user prompts to per-tile machine IRF workflow, and updated example notebook
+0.9.0 -> made flim fitted image visible in GUI
+0.9.1 -> added session restoration in the GUI
+0.9.2 -> added some error handling and begin session restoration for roi analysis panel in the GUI
+0.9.3 -> complete session restoration for roi analysis panel
+0.9.5 -> selectable ROIs in FLIM image in GUI and export of region stats
+0.9.7 -> added FRET (using PhasorPy)
+0.9.8 -> added pile-up correction function
+0.9.9 -> UI fixes
+0.9.10 -> fixed GPU tests
+0.9.11 -> updated PhasorPy calls to match latest version (0.10.0) and added phasor filtering options
+0.9.12 -> changed masking to use cellpose-SAM
+0.9.13 -> added Gaussian and Lorentzian lifetime distribution fitting (Lakowicz §4.11.2)
+0.9.14 -> bug fixes galore
+0.9.15 -> new file format support: ISS (TD-FLIM .TAGTIME/.TAGCHANNEL/.TAGDECAY, FD-FLIM phasor .ifli; see issue #19), Becker & Hickl .sdt (SPC TCSPC FLIM, FIFO-image histograms; decoder written from B&H SPCM file-structure docs) and Photonscore .photons (LINCam D7 container; pure-Python, no native dependency, validated bit-exact vs the Photonscore SDK; see issue #20)
+0.9.16 -> fixed pile-up correction: Coates was being fed the photon/record count instead of the excitation-pulse count (N_sync), which destroyed the decay tail and mis-reported pile-up (0.07% read as 97%). N_sync is now taken from the true sync count per format, and Coates refuses any count that cannot be one.
+0.9.17 -> user-settable fit window + exclusion bands (--fit-start-ns/--fit-end-ns/--exclude-ns), so reflection peaks mid-decay can be dropped from the fit; the per-pixel path now honours the window at all (it previously projected over every bin, IRF rise and artefacts included). Pile-up can now go in the forward model (n_sync=) instead of correcting the data, which keeps the fit Poisson.
+0.9.18 -> added the n-exponential tail fit: bare exponentials fitted past the decay peak with no IRF and no reconvolution, y(t) = sum A[i] exp(-(t-t0)/tau[i]) + Bkgr. Reports the Leica quantities (per-component intensities I[k] = A[k]tau[k], I_sum, A_sum, t0) alongside the usual amplitude- and intensity-weighted mean lifetimes. t0 is pinned to the decay peak by default because it is strongly correlated with the amplitudes; free it from expert settings or --fit-t0. Available in FOV, batch and stitch modes, and as --fit-model tail on the CLI.
+0.9.19 -> multidimensional (z-stack and/or timelapse) tile stitching: a fourth Stitch pipeline that walks every (timepoint, z) plane, stitches the overlapping tiles for that plane and fits it, so overlapping positions are no longer treated as separate fields of view. One decay is pooled across the series and the lifetimes held fixed for every plane, so amplitudes stay comparable between timepoints. Tile positions come from the XLIF/LIF when one is given and are then refined against the tile overlap, which matters because the nominal stage coordinates can be out by tens of pixels; without metadata they are recovered from the overlap alone. Results browse with a plane slider in the FOV preview.
+0.10.0 -> add-on system: analysis tools, file formats, format sniffers and phasor filters register themselves through a flimkit.plugins registry instead of being hard-coded, and FLIMKit's own tools go through the same registry a third party would use. Plugins load from ~/.flimkit/plugins (off until you turn it on), from folders named in the config or FLIMKIT_PLUGIN_PATH, and from installed packages that declare a flimkit.plugins entry point. A plugin that raises on import has its registrations rolled back and cannot take the app down; Help > Plugins reports what loaded and what failed, and turns individual plugins off. FLIMKIT_NO_PLUGINS=1 or --no-plugins skips the lot for a reproducible baseline. The v1 hook signatures are frozen and a fixture plugin written against them is loaded by the test suite on every run. Adds pyproject.toml so an installed plugin can announce itself.
+0.10.1 -> the GPU per-pixel path honours a fit window, so dropping a reflection peak out of the fit no longer costs the GPU. Two fitting bugs found and fixed by Zhen Yuan: one-component free-tau gave different answers depending on whether a backend was selected, because the CPU grid-scanned it and the backend used the SciPy solver; and per-pixel distribution fits ignored the fit window that the summed fit honoured, so an excluded artefact stayed in every per-pixel map. Add-ons can now be installed into the compiled app as a wheel, and the GUI explains the fit settings in place.
+0.12.0 -> on PyPI, so pip install flimkit gets the analysis core without the desktop, with gui, torch, mlx, notebook, segmentation and test as extras. Plugins now load when a format is looked up, so a plugin-registered format works from a script or a CLI and not only from the GUI. Per-pixel fitting on the GPU works in pixel blocks, so a field larger than a gigabyte reaches the GPU instead of silently falling back to the CPU; a 1024 square field fits in 7.8s against 25.2s on the CPU. The per-pixel tau grid goes from 200 points to 1600, which cuts the error against known-truth synthetic data from 0.021 ns to 0.008 ns, so per-pixel lifetimes will differ slightly from earlier versions. Cancelling a tile fit is honoured through canvas assembly and saving rather than only during the fitting. Leica .xlef projects are read for tile positions.
+1.0.0 -> release version with all core features implemented and tested
+1.5.0 (or 2.0) -> validation of fitting results with known fluorophores.'''

flimkit/cli.py

@@ -0,0 +1,120 @@
+import argparse
+import os
+
+
+def main(fast=False, cli=False, check_updates=False, no_plugins=False, plugin_path=None):
+    if no_plugins:
+        os.environ['FLIMKIT_NO_PLUGINS'] = '1'
+    if plugin_path:
+        existing = os.environ.get('FLIMKIT_PLUGIN_PATH', '')
+        os.environ['FLIMKIT_PLUGIN_PATH'] = (
+            existing + os.pathsep + os.pathsep.join(plugin_path) if existing
+            else os.pathsep.join(plugin_path))
+    if check_updates:
+        from flimkit.utils.update_check import (
+            check_installation_freshness,
+            format_update_report,
+        )
+        report = format_update_report(
+            check_installation_freshness(timeout=3.0, do_fetch=True)
+        )
+        print(report)
+        return
+    if not cli:
+        from flimkit.UI.gui import launch_gui
+        launch_gui()
+        return
+    from flimkit import plugins
+    plugins.ensure_loaded()
+    from flimkit.interactive import single_FOV_flim_fit, stitch_and_fit, stitch_tiles, timelapse_flim_fit, zstack_flim_fit
+    import inquirer
+    from flimkit._version import __version__, roadmap
+    from flimkit.utils.fancy import display_banner, flim_fitting_banner, banner_goodbye
+    if fast == False:
+        display_banner()
+    print('Welcome to the FLIM data processing tool!')
+    questions = [
+        inquirer.List(
+            'process_option',
+            message='Choose a processing option',
+            choices=[
+                'FLIM FIT a single FOV',
+                'Phasor analysis',
+                'Reconstruct a FOV and FLIM FIT',
+                'Just stitch multiple tiles together',
+                'Timelapse batch fit',
+                'Z-stack batch fit',
+                'About',
+                'Exit'
+            ]
+        )
+    ]
+    answers = inquirer.prompt(questions)
+    if answers['process_option'] == 'FLIM FIT a single FOV':
+        if fast == False:
+            flim_fitting_banner()
+        print('FLIM FITting a single FOV...')
+        single_FOV_flim_fit(interactive=True)
+    elif answers['process_option'] == 'Phasor analysis':
+        from flimkit.phasor_launcher import phasor_inquire
+        phasor_inquire()
+    elif answers['process_option'] == 'Reconstruct a FOV and FLIM FIT':
+        print('Reconstructing a FOV and FLIM FITting...')
+        stitch_and_fit(interactive=True)
+    elif answers['process_option'] == 'Just stitch multiple tiles together':
+        print('Stitching multiple tiles together...')
+        stitch_tiles(interactive=True)
+    elif answers['process_option'] == 'Timelapse batch fit':
+        print('Timelapse batch FLIM fitting...')
+        timelapse_flim_fit(interactive=True)
+    elif answers['process_option'] == 'Z-stack batch fit':
+        print('Z-stack batch FLIM fitting...')
+        zstack_flim_fit(interactive=True)
+    elif answers['process_option'] == 'About':
+        print('Current version: ' + __version__)
+        try:
+            from flimkit.utils.update_check import (
+                check_installation_freshness,
+                format_update_report,
+            )
+            print()
+            print(format_update_report(
+                check_installation_freshness(timeout=2.5, do_fetch=False)
+            ))
+        except Exception as exc:
+            print(f'Update check unavailable: {exc}')
+        print(roadmap)
+        return    
+    else:
+        banner_goodbye()
+        return
+    
+def run(argv=None):
+    import multiprocessing
+    multiprocessing.freeze_support()
+    parser = argparse.ArgumentParser(description='FLIMKit — FLIM data processing toolkit')
+    parser.add_argument('--cli', action='store_true', help='=Run in CLI mode')
+    parser.add_argument('--fast', action='store_true', help='Skip banner display')
+    parser.add_argument(
+        '--check-updates',
+        action='store_true',
+        help='Check whether git checkout and local version are up to date, then exit',
+    )
+    parser.add_argument(
+        '--no-plugins',
+        action='store_true',
+        help='Skip every plugin, built in and user, for a reproducible baseline',
+    )
+    parser.add_argument(
+        '--plugins',
+        action='append',
+        metavar='DIR',
+        help='Extra folder to load plugins from, repeatable',
+    )
+    args = parser.parse_args(argv)
+    main(fast=args.fast, cli=args.cli, check_updates=args.check_updates,
+         no_plugins=args.no_plugins, plugin_path=args.plugins)
+
+
+if __name__ == '__main__':
+    run()

flimkit/configs.py

@@ -0,0 +1,148 @@
+import sys
+from matplotlib.colors import LinearSegmentedColormap
+from pathlib import Path
+
+FLIM_CMAP = LinearSegmentedColormap.from_list(
+    'flim', ['#000080','#0000ff','#00ffff','#00ff00','#ffff00','#ff0000']
+)
+
+MIN_PHOTONS_PERPIX = 10
+
+# Intensity threshold for masking low-signal pixels before fitting.
+# Set to None (disabled) or an integer photon count.
+# Use --intensity-threshold on the CLI, or 'interactive' to pick visually.
+INTENSITY_THRESHOLD = None
+
+
+# General fitting settings:
+Tau_min = 0.145
+Tau_max = 45.0
+
+# Set default fitting mode. Options are "summed", "perPixel", and "both". Override with --mode when running the code.
+D_mode = 'both'
+
+# Default number of exponentials to fit. Options are 1, 2, or 3. Override with --nexp when running the code. 4+ exponentials are not supported as the fitting becomes unstable and unreliable.
+n_exp = 3
+
+# Default binning factor for per-pixel fitting. Set to 1 for no binning. Override with --binning when running the code.
+binning_factor = 1
+# Default optimizer for per-pixel fitting. Options are "lm_multistart" and "de".
+Optimizer = 'de'
+
+# Levenberg-Marquardt settins:
+lm_restarts = 8
+
+# Default settings for DE optimizer:
+de_population = 30
+de_maxiter = 5000
+n_workers = -1
+
+# IRF settings:
+IRF_FWHM = None
+# ns window (centred on the decay peak) the parametric IRF is fit over. Keep it
+# tight: a wide window pulls in the fluorescence falling edge, so the fit traces
+# the decay instead of the instrument pulse and yields an over-broad IRF.
+IRF_FIT_WIDTH = 0.5
+IRF_BINS = 21
+Estimate_IRF = 'none'
+
+# Machine IRF defaults (spreadsheet-free workflow)
+
+# True when launched as a PyInstaller-compiled executable.
+_is_frozen = getattr(sys, 'frozen', False)
+
+# Bundled read-only resources - always accessible via __file__ (even when frozen,
+# PyInstaller extracts them to a temp dir that __file__ still points into).
+_BUNDLED_MACHINE_IRF_DIR = Path(__file__).resolve().parent / 'machine_irf'
+
+# Writable location for user-generated IRF files.
+# When frozen the package dir is inside a read-only bundle, so saves go to
+# ~/.flimkit/machine_irf/ instead.  When running from source the behaviour is
+# unchanged (saves alongside the package).
+USER_MACHINE_IRF_DIR = Path.home() / '.flimkit' / 'machine_irf'
+MACHINE_IRF_DIR = USER_MACHINE_IRF_DIR if _is_frozen else _BUNDLED_MACHINE_IRF_DIR
+
+# Default IRF path used when no explicit path is given.
+# When frozen: prefer a user-saved copy (if it exists), else fall back to the
+# bundled factory default so a fresh install still works out of the box.
+_user_default = USER_MACHINE_IRF_DIR / 'machine_irf_default.npy'
+MACHINE_IRF_DEFAULT_PATH = (
+    (_user_default if _user_default.exists() else _BUNDLED_MACHINE_IRF_DIR / 'machine_irf_default.npy')
+    if _is_frozen
+    else _BUNDLED_MACHINE_IRF_DIR / 'machine_irf_default.npy'
+)
+MACHINE_IRF_ALIGN_ANCHOR = 'peak'
+MACHINE_IRF_REDUCER = 'median'
+MACHINE_IRF_FIT_STRATEGY = 'fixed'
+MACHINE_IRF_FIT_BG = True
+MACHINE_IRF_FIT_SIGMA = False
+MACHINE_IRF_FIT_TAIL = False
+MACHINE_IRF_SIGMA_MAX_FULL = 3.0
+MACHINE_IRF_SIGMA_MAX_HALF = 0.5
+MACHINE_IRF_DE_POPULATION = 30
+MACHINE_IRF_DE_MAXITER = 5000
+
+# Cost function for summed fit. Options are "poisson" (recommended) and "chi2" (legacy).
+# "poisson" uses Poisson deviance (C-statistic) on raw counts - statistically correct.
+# "chi2" normalises by peak and uses Neyman weights - underweights the tail.
+Cost_function = 'poisson'
+
+# Display range for exported tau images (FLIM microscope clipping).
+# Out-of-range pixels are clipped to the nearest boundary, matching FLIM microscope software behaviour.
+# Set to None to keep the full fitted range (no clipping).
+TAU_DISPLAY_MIN = None
+TAU_DISPLAY_MAX = None
+
+# Display range for exported intensity images (same clipping behaviour).
+# Set to None to keep the full range.
+INTENSITY_DISPLAY_MIN = None
+INTENSITY_DISPLAY_MAX = None
+
+# Phasor-domain spatial filtering applied after calibration.
+# Set to None to disable.  Options: None, 'gaussian', 'median', 'wavelet'.
+PHASOR_FILTER = None
+PHASOR_FILTER_SIGMA = 1.0
+PHASOR_FILTER_SIZE = 3
+PHASOR_FILTER_WAVELET = 'db4'
+PHASOR_FILTER_LEVEL = 1
+
+# Other specific settings:
+channels = None
+OUT_NAME = 'flim_out'
+
+
+config_message = f"""Default settings:
+Intensity threshold: {INTENSITY_THRESHOLD} photons (None = disabled)
+Tau_min: {Tau_min} ns
+Tau_max: {Tau_max} ns
+Tau display min: {TAU_DISPLAY_MIN} ns (None = no clip)
+Tau display max: {TAU_DISPLAY_MAX} ns (None = no clip)
+Intensity display min: {INTENSITY_DISPLAY_MIN} (None = no clip)
+Intensity display max: {INTENSITY_DISPLAY_MAX} (None = no clip)
+Fitting mode: {D_mode}  
+Number of exponentials: {n_exp}
+Cost function: {Cost_function}
+Optimizer: {Optimizer}
+Levenberg-Marquardt restarts: {lm_restarts}
+Differential Evolution population size: {de_population}
+Differential Evolution max iterations: {de_maxiter}
+Number of workers for DE optimization: {n_workers}
+IRF FWHM: {IRF_FWHM} ns
+IRF fit width: {IRF_FIT_WIDTH} ns
+IRF bins: {IRF_BINS}
+IRF estimation method: {Estimate_IRF}
+Machine IRF default path: {MACHINE_IRF_DEFAULT_PATH}
+Machine IRF align anchor: {MACHINE_IRF_ALIGN_ANCHOR}
+Machine IRF reducer: {MACHINE_IRF_REDUCER}
+Machine IRF fit strategy: {MACHINE_IRF_FIT_STRATEGY}
+Machine IRF fit bg/sigma/tail: {MACHINE_IRF_FIT_BG}/{MACHINE_IRF_FIT_SIGMA}/{MACHINE_IRF_FIT_TAIL}
+Machine IRF DE population/maxiter: {MACHINE_IRF_DE_POPULATION}/{MACHINE_IRF_DE_MAXITER}
+Channels to fit: {channels}
+Output directory: {OUT_NAME}
+Change any of these defaults by passing the corresponding argument when running the code. 
+Run `python -m flim_fitter --help` for more details on available arguments and their usage. 
+Change defaults in configs.py or override with command line arguments as needed for different datasets and systems.
+"""
+
+if __name__ == '__main__':
+    print(config_message)

flimkit/dialogs.py

@@ -0,0 +1,46 @@
+_provider = None
+
+def set_dialog_provider(fn):
+    global _provider
+    _provider = fn
+
+def get_dialog_provider():
+    return _provider
+
+def _tk_save_path(title, default_name, defaultextension, filetypes):
+    import tkinter as tk
+    from tkinter import filedialog
+    existing = tk._default_root
+    if existing is not None:
+        parent = existing
+        need_destroy = False
+    else:
+        parent = tk.Tk()
+        parent.withdraw()
+        need_destroy = True
+    parent.attributes('-topmost', True)
+    parent.update()
+    path = filedialog.asksaveasfilename(
+        parent=parent,
+        title=title,
+        defaultextension=defaultextension,
+        initialfile=default_name,
+        filetypes=filetypes)
+    if need_destroy:
+        parent.destroy()
+    return path or None
+
+def ask_save_path(title, default_name, defaultextension='', filetypes=None):
+    filetypes = filetypes or [('All files', '*')]
+    if _provider is not None:
+        try:
+            return _provider(title=title, default_name=default_name,
+                             defaultextension=defaultextension,
+                             filetypes=filetypes)
+        except Exception:
+            pass
+    try:
+        return _tk_save_path(title, default_name, defaultextension, filetypes)
+    except Exception:
+        path = input(f'Save path [{default_name}]: ').strip().strip('"')
+        return path or default_name