API reference

This section documents selected modules that are safe to import in a headless documentation build. GUI modules are intentionally excluded.

Workers

theatrics.workers.export_worker.export_rics_process_main(params, out_q, cancel_event)

params keys:

input_file, channel, crop_factor, window_size, correct_drift

theatrics.workers.fit_worker.fit_rics_one_file(params, out_q=None)

Returns (summary_dict, npz_path).

params keys expected:

rics_file, saving_path, crop_fast, crop_slow, diffusion_model, channel_to_use (for metadata), fit_pixel_size_nm, fit_pixel_dwell_us, fit_line_time_ms (fallback) psf_size_xy_um, psf_aspect_ratio do_fit_1d (bool)

theatrics.workers.fit_worker.fit_rics_process_main(params, out_q, cancel_event)

Worker entry point. Supports single file OR batch (list of rics files).

params keys:

mode: “single” or “batch” rics_file OR rics_files (list) … plus keys required by fit_rics_one_file()

theatrics.workers.sfcs_worker.sfcs_process_main_curvefit(input_file, channel, cpu_n, out_q, cancel_event, bleach_corr, chunk_lines=500, max_workers=None)

Whole SFCS pipeline in a separate process. Gaussian fitting uses curve_fit in parallel via multiprocessing.Pool + chunking.

out_q messages: (“progress”, pct) / (“done”, payload) / (“error”, tb)

theatrics.workers.diffmap_worker.diffusion_map_process_main(params, out_q, cancel_event=None)

params keys:

input_file (czi), channel (int), psf_xy_um, psf_aspect_ratio, window_size, offset, diffusion_model (“2Ddiff” or “3Ddiff”), cpu_n (optional)

Utilities

theatrics.utils.file_utils.get_files_from_folder(folder_path, extension, suffix='')

theatrics.utils.mp_utils.clamp_workers(requested, max_fraction=0.8, min_workers=1, hard_cap=None)

Choose a safe number of workers based on machine capacity and user request.

Parameters:

• requested (int) – User requested workers (e.g. from GUI input).

• max_fraction (float) – Fraction of logical CPUs to allow (0..1).

• min_workers (int) – Minimum workers.

• hard_cap (int or None) – Absolute maximum, useful for e.g. Windows overhead control.

Returns:

Worker count to use.

Return type:

int

theatrics.utils.mp_utils.set_single_threaded_blas()

Prevents OpenBLAS/MKL/NumExpr/OMP from using many threads inside each process. Call this before importing numpy/scipy-heavy modules if possible.

theatrics.utils.mp_utils.setup_multiprocessing(start_method='spawn', force=True)

Call once in main entry point (main.py), inside if __name__ == ‘__main__’. On Windows/macOS ‘spawn’ is the safe default.