{"id":13716873,"url":"https://github.com/tlambert03/LLSpy","last_synced_at":"2025-05-07T06:31:53.819Z","repository":{"id":19040681,"uuid":"96235902","full_name":"tlambert03/LLSpy","owner":"tlambert03","description":"Lattice light-sheet post-processing utility.","archived":false,"fork":false,"pushed_at":"2025-05-05T20:09:32.000Z","size":56805,"stargazers_count":28,"open_issues_count":5,"forks_count":6,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-05-05T21:25:46.426Z","etag":null,"topics":["image-analysis","image-processing","light-sheet","microscopy"],"latest_commit_sha":null,"homepage":"http://llspy.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tlambert03.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.rst","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-07-04T16:20:12.000Z","updated_at":"2025-03-07T07:11:24.000Z","dependencies_parsed_at":"2023-10-03T17:56:32.171Z","dependency_job_id":"a0636232-527b-47bb-b62a-99fdcc55da87","html_url":"https://github.com/tlambert03/LLSpy","commit_stats":{"total_commits":808,"total_committers":8,"mean_commits":101.0,"dds":0.0383663366336634,"last_synced_commit":"0da7546ecf045cc5663c9de6f0bcb517d57e8cc3"},"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2FLLSpy","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2FLLSpy/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2FLLSpy/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tlambert03%2FLLSpy/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tlambert03","download_url":"https://codeload.github.com/tlambert03/LLSpy/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252579425,"owners_count":21771190,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["image-analysis","image-processing","light-sheet","microscopy"],"created_at":"2024-08-03T00:01:15.255Z","updated_at":"2025-05-07T06:31:48.810Z","avatar_url":"https://github.com/tlambert03.png","language":"Python","funding_links":[],"categories":["Image restoration and quality assessment"],"sub_categories":[],"readme":"# LLSpy: Lattice light-sheet post-processing utility\n\n[![license_shield](https://img.shields.io/badge/License-BSD%203--Clause-brightgreen.svg)](https://opensource.org/licenses/BSD-3-Clause)\n![python_shield](https://img.shields.io/badge/Python-2.7%2C%203.5%2C%203.6-brightgreen.svg)\n[![travis_shield](https://img.shields.io/travis/tlambert03/LLSpy/master.svg)](https://travis-ci.org/tlambert03/LLSpy)\n[![Documentation Status](https://readthedocs.org/projects/llspy/badge/?version=latest)](http://llspy.readthedocs.io/en/latest/?badge=latest)\n[![doi_shield](https://zenodo.org/badge/96235902.svg)](https://zenodo.org/badge/latestdoi/96235902)\n\n[![image](https://raw.githubusercontent.com/tlambert03/LLSpy/develop/img/cbmflogo.png)](https://cbmf.hms.harvard.edu/lattice-light-sheet/)\n\nCopyright © 2019 Talley Lambert, Harvard Medical School.\n\nLLSpy is a python library to facilitate lattice light sheet data\nprocessing. It extends the cudaDeconv binary created in the Betzig lab\nat Janelia Research Campus, adding features that auto-detect\nexperimental parameters from the data folder structure and metadata\n(minimizing user input), auto-choose OTFs, perform image corrections and\nmanipulations, and facilitate file handling. Full(er) documentation\navailable at \u003chttp://llspy.readthedocs.io/\u003e\n\n**There are three ways to use LLSpy:**\n\n## 1. Graphical User Interface\n\nThe GUI provides access to the majority of functionality in LLSpy. It includes a\ndrag-and drop queue, visual progress indicator, and the ability to preview data\nprocessed with the current settings using the (awesome) 4D-viewer,\n[Spimagine](https://github.com/maweigert/spimagine),\nand experimental support for napari.\n\n![LLSpy graphical interface](https://raw.githubusercontent.com/tlambert03/LLSpy/master/img/screenshot.png)\n\n## 2. Command Line Interface\n\nThe command line interface can be used to process LLS data in a server\nenvironment (linux compatible).\n\n```sh\n$ lls --help\n\nUsage: lls [OPTIONS] COMMAND [ARGS]...\n\n  LLSpy\n\n  This is the command line interface for the LLSpy library, to facilitate\n  processing of lattice light sheet data using cudaDeconv and other tools.\n\nOptions:\n  --version          Show the version and exit.\n  -c, --config PATH  Config file to use instead of the system config.\n  --debug\n  -h, --help         Show this message and exit.\n\nCommands:\n  camera    Camera correction calibration\n  clean     Delete LLSpy logs and preferences\n  compress  Compression \u0026 decompression of LLSdir\n  config    Manipulate the system configuration for LLSpy\n  decon     Deskew and deconvolve data in LLSDIR.\n  deskew    Deskewing only (no decon) of LLS data\n  gui       Launch LLSpy Graphical User Interface\n  info      Get info on an LLSDIR.\n  install   Install cudaDeconv libraries and binaries\n  reg       Channel registration\n\n# process a dataset\n$ lls decon --iters 8 --correctFlash /path/to/dataset\n\n# change system or user-specific configuration\n$ lls config --set otfDir path/to/PSF_and_OTFs\n\n# or launch the gui\n$ lls gui\n```\n\n## 3. Interactive data processing in a python console\n\n```python\n\u003e\u003e\u003e import llspy\n\n# the LLSdir object contains most of the useful attributes and\n# methods for interacting with a data folder containing LLS tiffs\n\u003e\u003e\u003e E = llspy.LLSdir('path/to/experiment_directory')\n# it parses the settings file into a dict:\n\u003e\u003e\u003e E.settings\n{'acq_mode': 'Z stack',\n 'basename': 'cell1_Settings.txt',\n 'camera': {'cam2name': '\"Disabled\"',\n            'cycle': '0.01130',\n            'cycleHz': '88.47 Hz',\n            'exp': '0.01002',\n    ...\n}\n\n# many important attributes are in the parameters dict\n\u003e\u003e\u003e E.parameters\n{'angle': 31.5,\n 'dx': 0.1019,\n 'dz': 0.5,\n 'nc': 2,\n 'nt': 10,\n 'nz': 65,\n 'samplescan': True,\n  ...\n}\n\n# and provides methods for processing the data\n\u003e\u003e\u003e E.autoprocess()\n\n# the autoprocess method accepts many options as keyword aruguments\n# a full list with descriptions can be seen here:\n\u003e\u003e\u003e llspy.printOptions()\n\n              Name  Default                    Description\n              ----  -------                    -----------\n      correctFlash  False                      do Flash residual correction\nflashCorrectTarget  cpu                        {\"cpu\", \"cuda\", \"parallel\"} for FlashCor\n            nIters  10                         deconvolution iters\n         mergeMIPs  True                       do MIP merge into single file (decon)\n            otfDir  None                       directory to look in for PSFs/OTFs\n            tRange  None                       time range to process (None means all)\n            cRange  None                       channel range to process (None means all)\n               ...  ...                        ...\n\n# as well as file handling routines\n\u003e\u003e\u003e E.compress(compression='lbzip2')  # compress the raw data into .tar.(bz2|gz)\n\u003e\u003e\u003e E.decompress()  # decompress files for re-processing\n\u003e\u003e\u003e E.freeze()  # delete all processed data and compress raw data for long-term storage.\n```\n\n*Note:* The LLSpy API is currently unstable (subject to change). Look at\nthe `llspy.llsdir.LLSdir` class as a starting point for most of the\nuseful methods. Minimal documentation available in the docs. Feel free\nto fork this project on github and suggest changes or additions.\n\n## Requirements\n\n- Compatible with Windows (tested on 7/10), Mac or Linux (tested on\n    Ubuntu 16.04)\n- Python 3.6 (as of version 0.4.0, support for 2.7 and 3.5 ended)\n- Most functionality assumes a data folder structure as generated by\n    the Lattice Scope LabeView acquisition software written by Dan\n    Milkie in the Betzig lab. If you are using different acquisition\n    software (such as 3i software), it is likely that you will need to\n    change the data structure and metadata parsing routines in order to\n    make use of this software.\n- Currently, the core deskew/deconvolution processing is based on\n    cudaDeconv, written by Lin Shao and maintained by Dan Milkie.\n    cudaDeconv is licensed and distributed by HHMI. It was open-sourced\n    in Feb 2019, and is available here:\n    \u003chttps://github.com/dmilkie/cudaDecon\u003e\n- CudaDeconv requires a CUDA-capable GPU\n- The Spimagine viewer requires a working OpenCL environment\n\n## Installation\n\n1. Install [conda/mamba](https://github.com/conda-forge/miniforge)\n\n2. Launch a `terminal` window (Linux), or `Miniforge Prompt` (Windows)\n\n3. Install LLSpy into a new conda environment\n\n    ```sh\n    conda create -n llsenv python=3.11 cudadecon\n    conda activate llsenv\n    pip install llspy\n    ```\n\n    The `create -n llsenv` line creates a virtual environment. This is\n    optional, but recommended as it easier to uninstall cleanly and\n    prevents conflicts with any other python environments. If\n    installing into a virtual environment, you must source the\n    environment before proceeding, and each time before using llspy.\n\nEach time you use the program, you will need to activate the virtual\nenvironment. The main command line interface is `lls`, and the gui can\nbe launched with `lls gui`. You can create a bash script or batch file\nto autoload the environment and launch the program if desired.\n\n```sh\n# Launch Anaconda Prompt and type...\nconda activate llsenv\n\n# show the command line interface help menu\nlls -h\n# process a dataset\nlls decon /path/to/dataset\n# or launch the gui\nlls gui\n```\n\nSee complete usage notes in the\n[documentation](http://llspy.readthedocs.io/).\n\n## Features of LLSpy\n\n- graphical user interface with persistent/saveable processing\n    settings\n- command line interface for remote/server usage (coming)\n- preview processed image to verify settings prior to processing full\n    experiment\n- *Pre-processing corrections*:\n  - correct \\\"residual electron\\\" issue on Flash4.0 when using\n        overlap synchronous mode. Includes CUDA and parallel CPU\n        processing as well as GUI for generation of calibration file.\n  - apply selective median filter to particularly noisy pixels\n  - trim image edges prior to deskewing (helps with CMOS edge row\n        artifacts)\n  - auto-detect background\n- Processing:\n  - select subset of acquired images (C or T) for processing\n  - automatic parameter detection based on auto-parsing of\n        Settings.txt\n  - automatic OTF generation/selection from folder of raw PSF files,\n        based on date of acquisition, mask used (if entered into\n        SPIMProject.ini), and wavelength.\n  - graphical progress bar and time estimation\n- Post-processing:\n  - proper voxel-size metadata embedding (newer version of Cimg)\n  - join MIP files into single hyperstack viewable in ImageJ/Fiji\n  - automatic width/shift selection based on image content (\\\"auto\n        crop to features\\\")\n  - automatic fiducial-based image registration (provided tetraspeck\n        bead stack)\n  - compress raw data after processing\n- Watched-folder autoprocessing (experimental):\n  - Server mode: designate a folder to watch for incoming *finished*\n        LLS folders (with Settings.txt file). When new folders are\n        detected, they are added to the processing queue and the queue\n        is started if not already in progress.\n  - Acquisition mode: designed to be used on the acquisition\n        computer. Designate folder to watch for new LLS folders, and\n        process new files as they arrive. Similar to built in GPU\n        processing tab in Lattice Scope software, but with the addition\n        of all the corrections and parameter selection in the GUI.\n- easily return LLS folder to original (pre-processed) state\n- compress and decompress folders and subfolders with lbzip2 (not\n    working on windows)\n- concatenate two experiments - renaming files with updated relative\n    timestamps and stack numbers\n- rename files acquired in script-editor mode with `Iter_` in the name\n    to match standard naming with positions (work in progress)\n- cross-platform: includes precompiled binaries and shared libraries\n    that should work on all systems.\n\n## Bug Reports, Feature requests, etc\n\nPull requests are welcome!\n\nTo report a bug or request a feature, please [submit an issue on\ngithub](https://github.com/tlambert03/LLSpy/issues)\n\nPlease include the following in any bug reports:\n\n- Operating system version\n- GPU model\n- CUDA version (type `nvcc --version` at command line prompt)\n- Python version (type `python --version` at command line prompt, with\n    `llsenv` conda environment active if applicable)\n\nThe most system-dependent component (and the most likely to fail) is the\nOpenCL dependency for Spimagine. LLSpy will fall back gracefully to the\nbuilt-in Qt-based viewer, but the Spimagine option will be will be\nunavailble and grayed out on the config tab in the GUI. Submit an [issue\non github](https://github.com/tlambert03/LLSpy/issues) for help.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlambert03%2FLLSpy","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftlambert03%2FLLSpy","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftlambert03%2FLLSpy/lists"}