From 738c4377009deb52aaf77d8831bcc9de62393aba Mon Sep 17 00:00:00 2001 From: Kevin Dean <42547789+AdvancedImagingUTSW@users.noreply.github.com> Date: Fri, 10 May 2024 13:02:40 -0500 Subject: [PATCH] Getting closer --- docs/source/api.rst | 2 +- .../implementations/implementations.rst | 2 +- docs/source/index.rst | 53 ++++++++++++------- docs/source/software_installation.rst | 24 +++++---- docs/source/user_guide/file_formats.rst | 40 ++++++++------ docs/source/user_guide/hardware_overview.rst | 50 +++++++++++++++-- docs/source/user_guide/restapi.rst | 2 + 7 files changed, 124 insertions(+), 49 deletions(-) diff --git a/docs/source/api.rst b/docs/source/api.rst index 4f9d40a1d..bd5563494 100644 --- a/docs/source/api.rst +++ b/docs/source/api.rst @@ -1,4 +1,4 @@ -API +Software API ============= .. autosummary:: diff --git a/docs/source/implementations/implementations.rst b/docs/source/implementations/implementations.rst index a91f147ee..26812201d 100644 --- a/docs/source/implementations/implementations.rst +++ b/docs/source/implementations/implementations.rst @@ -1,5 +1,5 @@ =========================================== -Example Microscopes +Implemented Microscopes =========================================== As an example of the flexibility of the **navigate** software, we describe several diff --git a/docs/source/index.rst b/docs/source/index.rst index c8f54f63b..e6a0a4d13 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -6,10 +6,11 @@ ############ -**navigate** is an open-source Python software for general microscope control. It focuses -on smart microscopy applications by providing reusable acquisition and analysis routines, -termed :ref:`features `, that can be chained -in arbitrary orders to create custom acquisition protocols. **navigate** is designed to accommodate the needs of +**navigate** is an open-source Python software for light-sheet microscope control. It +focuses on smart microscopy applications by providing reusable acquisition and +analysis routines, termed :ref:`features `, that can be chained +in arbitrary orders to create custom acquisition protocols. +**navigate** is designed to accommodate the needs of a diverse user base, from biologists with no programming experience to advanced technology developers. @@ -17,12 +18,14 @@ technology developers. ========================= * Prioritize standard library imports for maximum stability, and minimize external -dependencies. + dependencies. * Abstraction layer to drive different camera types, etc. * Plugin architecture for extensibility. -* Maximize productivity for biological users through robust graphical user interface-based workflows. +* Maximize productivity for biological users through robust graphical user + interface-based workflows. * Performant and responsive. -* Brutally obvious, well-documented, clean code organized in an industry standard Model-View-Controller architecture. +* Brutally obvious, well-documented, clean code organized in an industry standard + Model-View-Controller architecture. .. note:: @@ -43,16 +46,16 @@ dependencies. .. toctree:: :caption: Getting Started - :maxdepth: 2 + :maxdepth: 1 quick_start - implementations/implementations software_installation i_want_to + .. toctree:: :caption: User Guide - :maxdepth: 2 + :maxdepth: 1 user_guide/hardware_overview user_guide/file_formats @@ -63,7 +66,7 @@ dependencies. .. toctree:: :caption: Development - :maxdepth: 2 + :maxdepth: 1 contributing/software_architecture contributing/contributing_guidelines @@ -71,23 +74,35 @@ dependencies. user_guide/restapi plugin/plugin_home +.. toctree:: + :caption: Plugins + :maxdepth: 1 + + navigate Plugin Template + navigate Confocal Projection Plugin + navigate at Scale + navigate MMCore Plugin + navigate ilastik Server + .. toctree:: :caption: Reference - :maxdepth: 2 + :maxdepth: 1 + implementations/implementations api **Authors** ============ -**Navigate** includes key contributions from numerous individuals, both past and present, -in `The Dean Lab `_. Please see the accompanying manuscript for a full list of contributors. +**navigate** includes key contributions from numerous individuals, both past and +present, in `The Dean Lab `_. Please see the accompanying manuscript +for a full list of contributors. :ref:`Outside contributors ` are welcome. **Funding** ============ **navigate** is supported by the -`UT Southwestern and University of North Carolina Center for Cell Signaling -`_, a Biomedical Technology Development and Dissemination (BTDD) -Center funded by the NIH National Institute of General Medical Science (RM1GM145399), and -the `Center for Metastatic Tumor Imaging `_ program, a -Cellular Cancer Biology Imaging Research (CCBIR) program funded by the NIH National Cancer Institute (U54CA268072). + +- NIH National Institute of General Medical Science (RM1GM145399). +- NIH National Cancer Institute (1U54CA268072). +- `Simmons Comprehensive Cancer Center `_ Translational Seed Grant. +- `UTSW President's Research Council `_ diff --git a/docs/source/software_installation.rst b/docs/source/software_installation.rst index 85f336927..1aff3cd5d 100644 --- a/docs/source/software_installation.rst +++ b/docs/source/software_installation.rst @@ -12,7 +12,8 @@ Operating System Compatibility .. important:: **navigate** is developed for use on Windows-based systems. This is due to the - compatibility of device drivers for various microscope hardware components, such as + compatibility of :ref:`device drivers ` for various microscope + hardware components, such as cameras, stages, and data acquisition cards, which are predominantly designed for the Windows environment. @@ -21,8 +22,8 @@ Operating System Compatibility include improper positioning of widgets and problems with resizing the GUI window. As such, the use of **navigate** on MacOS is not recommended. - The software is untested on Linux systems.Users considering the use of **navigate** - software on Linux should proceed with caution and be prepared for potential + The software is untested on Linux systems. Users considering the use of **navigate** + software on Linux should proceed with caution and be prepared for potential compatibility issues, especially with respect to device drivers. .. note:: @@ -33,16 +34,16 @@ Hardware Considerations ----------------------- **navigate** will run on a mid-range laptop with at least 8 GB of RAM and a processor -with two cores. Most of its operations are undemanding. Saving data at a reasonable -rate, however, will require an SSD. The hardware configuration for an example +with two cores. Most of its operations are undemanding. Saving data at a reasonable +rate, however, will require an SSD. The hardware configuration for an example microscope control machine is shown below. .. important:: Scientific cameras are capable of rapidly generating large amounts of high-resolution data. - As such, the read/write speed of the data storage device is a critical for smooth operation + As such, the read/write speed of the data storage device is a critical for smooth operation of the software. For example, for a standard Hamamatsu camera with a 2048 x 2048 sensor, operating at 16-bit depth and 20 frames per second, the data save rate is approximately ~167 MB/s. - While such capabilities are well within the capabilities of modern SSDs, they are beyond the + While such capabilities are well within the capabilities of modern SSDs, they are beyond the capabilities of most HDDs. Therefore, it is recommended to use a fast SSD data saving operations. @@ -97,7 +98,7 @@ microscope control machine is shown below. - **Interface**: PCI-E x 8 .. note:: - The specifications listed are based on an example system configuration and can + The specifications listed are based on an example system configuration and can be adjusted based on specific needs and availability. --------------------- @@ -157,7 +158,7 @@ To install the bleeding edge version of **navigate**, run the following command: .. note:: - If you are running the software on a computer that is not connected to microscope + If you are running the software on a computer that is not connected to microscope hardware, you can add the flag ``-sh`` (``--synthetic-hardware``) to launch the program: @@ -175,13 +176,16 @@ Open an ``Anaconda Prompt (Miniconda3)`` and enter the following. (base) conda activate navigate (navigate) navigate -.. note:: +.. tip:: If you are running Windows, you can create a desktop shortcut to **navigate** by right-clicking the Desktop, navigating to New and then Shortcut and entering ``%windir%\system32\cmd.exe "/c" C:\path\to\miniconda\Scripts\activate.bat navigate && navigate`` into the location text box. + This provides a convenient executable shortcut to launch the software, which is + advantageous for users who are not comfortable with the command line. + Developer install ================= diff --git a/docs/source/user_guide/file_formats.rst b/docs/source/user_guide/file_formats.rst index d39be952f..26f4447c0 100644 --- a/docs/source/user_guide/file_formats.rst +++ b/docs/source/user_guide/file_formats.rst @@ -50,34 +50,28 @@ Image Writing Benchmarks ------------------------ To evaluate the performance of saving imaging data in different formats, we conducted -benchmarks on a Linux-based system. We assessed the average disk write time for TIFF, +benchmarks on a Linux-based system. We assessed the median disk write time for TIFF, OME-TIFF, H5, N5, and OME-Zarr formats across image resolutions of 512x512, 1024x1024, and 2048x2048 under two conditions: (A) capturing 1000 single-plane images and (B) acquiring a single z-stack composed of 1000 planes. All times -are measured in milliseconds. Bottom panel for both A and B has a reduced y-axis to -highlight the differences in write times between the formats. Results are also -presented in a table format below. - -The initial setup for writing H5/N5 files introduces -significant overhead, and to a lesser extent for TIFF and OME-TIFF files, which -elevates the average write time. However, the median write time remains consistently -low and stable across most of the acquisition. For z-stack imaging, TIFF and OME-TIFF -formats achieved write speeds of up to approximately 400 Hz for a 2048x2048 camera +are measured in milliseconds. Results are presented below. For z-stack imaging, TIFF +and OME-TIFF formats achieved write speeds of up to approximately 400 Hz for a 2048x2048 camera resolution, surpassing the operational speeds of most contemporary sCMOS cameras. The Big-TIFF variant was used for both TIFF and OME-TIFF formats to accommodate the large file sizes. +Timelapse Imaging +~~~~~~~~~~~~~~~~~ -.. image:: images/benchmarks.png - :width: 50% - :align: center +1000 images acquired, with a single Z plane. Median write time reported in +milliseconds. .. table:: :widths: auto :align: center +-------------+---------+----------+-------+-------+---------+ - | Z=1, T=1000 | TIFF | OME-TIFF | H5 | N5 | OME-Zarr| + | | TIFF | OME-TIFF | H5 | N5 | OME-Zarr| +=============+=========+==========+=======+=======+=========+ | 512x512 | 4.06 | 15.26 | 2.79 | 12.09 | 1.35 | +-------------+---------+----------+-------+-------+---------+ @@ -86,12 +80,17 @@ large file sizes. | 2048x2048 | 22.25 | 38.57 | 34.71 | 29.56 | 11.85 | +-------------+---------+----------+-------+-------+---------+ +Z-Stack Imaging +~~~~~~~~~~~~~~~ + +1 image acquired, with 1000 Z planes. Median write speed time in milliseconds. + .. table:: :widths: auto :align: center +--------------+---------+----------+-------+-------+---------+ - | Z=1000, T=1 | TIFF | OME-TIFF | H5 | N5 | OME-Zarr| + | | TIFF | OME-TIFF | H5 | N5 | OME-Zarr| +==============+=========+==========+=======+=======+=========+ | 512x512 | 0.21 | 0.17 | 4.76 | 1.80 | 1.30 | +--------------+---------+----------+-------+-------+---------+ @@ -100,6 +99,17 @@ large file sizes. | 2048x2048 | 2.35 | 2.14 | 75.56 | 14.08 | 8.60 | +--------------+---------+----------+-------+-------+---------+ +Additional Sources of Overhead +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The initial setup for writing H5/N5 files introduces +significant overhead, and to a lesser extent for TIFF and OME-TIFF files, which +elevates the average write time. However, the median write time remains consistently +low and stable across most of the acquisition. + +Computer Specifications for Benchmarks +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + The computer specifications that the benchmarks were performed on are as follows: - Architecture: x86_64 diff --git a/docs/source/user_guide/hardware_overview.rst b/docs/source/user_guide/hardware_overview.rst index a8ce4bea2..d9aa4d011 100644 --- a/docs/source/user_guide/hardware_overview.rst +++ b/docs/source/user_guide/hardware_overview.rst @@ -28,7 +28,7 @@ configure each of these devices is provided :doc:`here `. +The navigate ilastik Server plugin can be found `here `_.