Merge pull request #857 from fractal-analytics-platform/update_readme

jluethi · web-flow · commit 9b854c186ad1 · 2024-10-30T14:40:05.000+01:00
Update README &amp; doc page
diff --git a/README.md b/README.md
@@ -1,66 +1,83 @@
-# Fractal Core Tasks
+# Fractal Tasks Core
+
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/0a4d8d81-3ca8-4e5e-9c99-9a593e4c132c" alt="Fractal tasks core logo" width="400">
+</p>
 
 [![PyPI version](https://img.shields.io/pypi/v/fractal-tasks-core?color=gree)](https://pypi.org/project/fractal-tasks-core/)
+[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 [![CI Status](https://github.com/fractal-analytics-platform/fractal-tasks-core/actions/workflows/ci_pip.yml/badge.svg)](https://github.com/fractal-analytics-platform/fractal-tasks-core/actions/workflows/ci_pip.yml)
 [![Coverage](https://raw.githubusercontent.com/fractal-analytics-platform/fractal-tasks-core/python-coverage-comment-action-data/badge.svg)](https://htmlpreview.github.io/?https://github.com/fractal-analytics-platform/fractal-tasks-core/blob/python-coverage-comment-action-data/htmlcov/index.html)
 [![Documentation Status](https://github.com/fractal-analytics-platform/fractal-tasks-core/actions/workflows/documentation.yaml/badge.svg)](https://fractal-analytics-platform.github.io/fractal-tasks-core)
-[![License](https://img.shields.io/badge/License-BSD_3--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
 
-[Fractal](https://fractal-analytics-platform.github.io/) is a framework developed at the [BioVisionCenter](https://www.biovisioncenter.uzh.ch/en.html) to process bioimaging data at scale in the OME-Zarr format and prepare the images for interactive visualization.
+Fractal tasks core is the official task package for the [Fractal](https://fractal-analytics-platform.github.io/) framework. It provides essential tools for building Fractal tasks, helpful utility functions, and a collection of ready-to-use tasks for processing bioimaging data. These tasks include OME-Zarr conversion, image registration, segmentation, and measurements.
+
+![Fractal_overview_small](https://github.com/user-attachments/assets/666c8797-2594-4b8e-b1d2-b43fca66d1df)
 
-![Fractal_overview](https://github.com/user-attachments/assets/24d24905-ae43-4249-a6de-6ed4853b0e59)
+[Fractal](https://fractal-analytics-platform.github.io/) is a framework developed at the [BioVisionCenter](https://www.biovisioncenter.uzh.ch/en.html) to process bioimaging data at scale in the OME-Zarr format and prepare the images for interactive visualization.
 
-This is the **core-tasks repository**, containing the python tasks that converts Cellvoyager CV7000 & CV8000 images into OME-Zarr and process OME-Zarr files. Find more information about Fractal in general and the other repositories at the [Fractal home page](https://fractal-analytics-platform.github.io).
+## Core Library Components
+This repository includes several core sub-packages:
+- **NGFF Sub-package**: Validates OME-Zarr metadata and provides utilities for reading and writing it.
+- **Tables Sub-package**: Handles AnnData tables for ROIs and features, including reading and writing operations. (See the [Fractal table specification](https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/)).
+- **ROI Sub-package**: Manages ROI-related table processing.
+- **Dev Sub-package**: Handles Fractal manifest creation and task validation for the Fractal server.
 
-Besides tasks, this repository contains library functions for processing OME-Zarr images. The core library parts are:
-- an NGFF sub-package to validate OME-Zarr metadata and provide convenience functions to read & write it
-- a tables sub-package to handle reading and writing of AnnData tables for ROI tables & feature tables (see [fractal table specification](https://fractal-analytics-platform.github.io/fractal-tasks-core/tables/))
-- a roi sub-package to handle ROI table related processing
-- a dev subpackage that handles Fractal manifest creation & other validation of tasks for Fractal server
+The NGFF, Tables & ROI Sub-package functionality will get replaced by functionality in [ngio](https://github.com/fractal-analytics-platform/ngio) over the coming months.
 
 
 ## Documentation
 
 See https://fractal-analytics-platform.github.io/fractal-tasks-core
 
+## Available Tasks
+
+This package includes the following tasks:
+
+- **Image Conversion**:
+  - *Convert Cellvoyager to OME-Zarr*: Converts CV7000/CV8000 images to OME-Zarr format.
+  - *Convert Cellvoyager Multiplexing to OME-Zarr*: Converts multiplexed images from CV7000/CV8000 to OME-Zarr.
+
+- **Image Processing**:
+  - *Project Image (HCS Plate)*: Generates intensity projections (e.g., maximum intensity projection) for images in an HCS plate.
+  - *Illumination Correction*: Applies flatfield correction and background subtraction using pre-calculated illumination profiles.
+
+- **Segmentation**:
+  - *Cellpose Segmentation*: Segments images using custom or pre-trained Cellpose models, with user-tunable options.
+
+- **Registration**:
+  - *Calculate Registration*: Computes translations for aligning images in multiplexed image analysis.
+  - *Find Registration Consensus*: Generates consensus transformations for aligning multiple acquisitions, updating ROI tables as necessary.
+  - *Apply Registration to Image*: Applies registration to images based on existing or newly created ROI tables.
 
-## Available tasks
+- **Measurements**:
+  - *Napari Workflows Wrapper*: Task to run existing napari workflows through Fractal to process images and labels and to generate new labels or measurement tables. Takes an arbitrary napari workflow yaml file to run.
 
-Currently, the following tasks are available:
-- Convert Cellvoyager to OME-Zarr: Task to convert Cellvoyager CV7000 & CV8000 images into OME-Zarr.
-- Convert Cellvoyager Multiplexing to OME-Zarr: Task to convert multiplexed images from Cellvoyager CV7000 & CV8000 images into OME-Zarr.
-- Project Image (HCS Plate): This task creates a new OME-Zarr HCS plate and calculates an intensity projection along the Z axis for all images (e.g. maximum intensity projection).
-- Illumination Correction: Task to apply flatfield correction & background subtraction based on pre-calculated illumination profiles.
-- Cellpose Segmentation: This task performs image segmentation using custom or pre-trained Cellpose models and exposes many model options to be tuned by the user.
-- Napari Workflows Wrapper: Task to run existing napari workflows through Fractal to process images and labels and to generate new labels or measurement tables. Takes an arbitrary napari workflow yaml file to run.
-- Calculate Registration (image-based): Registration task for multiplexed image analysis. This task calculated the translation needed to align images between multiple acquisitions.
-- Find Registration Consensus: Registration task for multiplexed image analysis. This task calculates the consensus transformation across all acquisitions to get aligned images. It creates new ROI tables for them.
-- Apply Registration to Image: Registration task for multiplexed image analysis. This task applies registration based on the ROI tables generated in `Find Registration Consensus` to existing images or it creates new, registered images.
-- Import OME-Zarr: Helper task to validate existing OME-Zarr files, handle the addition of ROI tables to existing Zarrs & to create the necessary metadata for Fractal server about an existing OME-Zarr image to allow further processing.
+- **Other Utilities**:
+  - *Import OME-Zarr*: Validates and processes existing OME-Zarr files, adding ROI tables and metadata for further processing in Fractal.
 
 
 ## Installation
-See [details on installation in the documentation](https://fractal-analytics-platform.github.io/fractal-tasks-core/install/). This package can be installed in 2 main ways:
 
-To use the library, just install the core package:
+To install and use the library components, run:
 
 ```
 pip install fractal-tasks-core
 ```
 
-This installs the core library and allows you to use all the sub-packages for ngff metadata, tables, rois etc.
+This will install the core library, including all sub-packages for working with NGFF metadata, tables, ROIs, and more.
 
-If you want to run the actual Fractal tasks, you need to install the task extra:
+If you intend to run Fractal tasks (such as segmentation or registration), install with the additional task dependencies:
 ```
 pip install "fractal-tasks-core[fractal-tasks]"
 ```
 
-This installs the heavier dependencies like torch for Cellpose & napari for napari workflows.
+This includes larger dependencies such as Torch (for Cellpose) and Napari (for Napari workflows).
 
 If you collect this package on Fractal server to run the task, make sure to add the fractal-tasks extra in the corresponding field for extras.
 
-# Contributors and license
+## Contributors and license
 
-Unless otherwise stated in each individual module, all Fractal components are released according to a BSD 3-Clause License, and Copyright is with the BioVisionCenter at the University of Zurich.
+Fractal was conceived in the Liberali Lab at the Friedrich Miescher Institute for Biomedical Research and in the Pelkmans Lab at the University of Zurich by [@jluethi](https://github.com/jluethi) and [@gusqgm](https://github.com/gusqgm). The Fractal project is now developed at the [BioVisionCenter](https://www.biovisioncenter.uzh.ch/en.html) at the University of Zurich and the project lead is with [@jluethi](https://github.com/jluethi). The core development is done under contract by [eXact lab S.r.l.](https://www.exact-lab.it).
 
-Fractal was conceived in the Liberali Lab at the Friedrich Miescher Institute for Biomedical Research and in the Pelkmans Lab at the University of Zurich by [@jluethi](https://github.com/jluethi) and [@gusqgm](https://github.com/gusqgm). The Fractal project is now developed at the BioVisionCenter at the University of Zurich and the project lead is with [@jluethi](https://github.com/jluethi). The core development is done under contract by [eXact lab S.r.l.](https://www.exact-lab.it).
+Unless otherwise specified, Fractal components are released under the BSD 3-Clause License, and copyright is with the BioVisionCenter at the University of Zurich.
diff --git a/docs/assets/fractal_logo.png b/docs/assets/fractal_logo.png
diff --git a/docs/index.md b/docs/index.md
@@ -5,42 +5,51 @@ hide:
 
 # Welcome to Fractal Tasks Core's documentation!
 
-Fractal is a framework to process high content imaging data at scale and prepare it for interactive visualization.
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/0a4d8d81-3ca8-4e5e-9c99-9a593e4c132c" alt="Fractal tasks core logo" width="400">
+</p>
+
+Fractal tasks core is the official task package for the [Fractal](https://fractal-analytics-platform.github.io/) framework. It provides essential tools for building Fractal tasks, helpful utility functions, and a collection of ready-to-use tasks for processing bioimaging data. These tasks include OME-Zarr conversion, image registration, segmentation, and measurements.
 
 > This project is under active development 🔨. If you need help or found a bug, **open an issue [here](https://github.com/fractal-analytics-platform/fractal-tasks-core/issues/new)**.
 
-Fractal provides distributed workflows that convert TBs of image data into [OME-Zar](https://ngff.openmicroscopy.org) files.
-The platform then processes the 3D image data by applying tasks like illumination correction, maximum intensity projection, 3D segmentation using [cellpose](https://cellpose.readthedocs.io) and measurements using [napari workflows](https://github.com/haesleinhuepf/napari-workflows).
-The pyramidal OME-Zarr files enable interactive visualization in the napari viewer.
+![Fractal overview](https://github.com/user-attachments/assets/666c8797-2594-4b8e-b1d2-b43fca66d1df)
+Fractal is a framework developed at the [BioVisionCenter](https://www.biovisioncenter.uzh.ch/en.html) to process bioimaging data at scale in the OME-Zarr format and prepare the images for interactive visualization.
+
+## Available Tasks
+
+This package includes the following tasks. For all available Fractal tasks, check the [task list page](all_tasks).
+
+**Image Conversion**:
 
-![Fractal overview](https://user-images.githubusercontent.com/18033446/190978261-2e7b57e9-72c7-443e-9202-15d233f8416d.jpg)
+  - *Convert Cellvoyager to OME-Zarr*: Converts CV7000/CV8000 images to OME-Zarr format.
+  - *Convert Cellvoyager Multiplexing to OME-Zarr*: Converts multiplexed images from CV7000/CV8000 to OME-Zarr.
 
+**Image Processing**:
 
-The **fractal-tasks-core** package contains the python tasks that parse Yokogawa CV7000 images into OME-Zarr and process OME-Zarr files. Find more information about Fractal in general and the other repositories at [this link](https://fractal-analytics-platform.github.io/). All tasks are written as Python functions and are optimized for usage in Fractal workflows, but they can also be used as standalone functions to parse data or process OME-Zarr files. We heavily use regions of interest (ROIs) in our OME-Zarr files to store the positions of field of views. ROIs are saved as AnnData tables following [this spec proposal](https://github.com/ome/ngff/pull/64). We save wells as large Zarr arrays instead of a collection of arrays for each field of view (see details [here](https://github.com/ome/ngff/pull/137)).
+  - *Project Image (HCS Plate)*: Generates intensity projections (e.g., maximum intensity projection) for images in an HCS plate.
+  - *Illumination Correction*: Applies flatfield correction and background subtraction using pre-calculated illumination profiles.
 
-Here is an example of the interactive visualization in napari using the newly-proposed async loading in [NAP4](https://github.com/napari/napari/pull/4905) and the [napari-ome-zarr plugin](https://github.com/ome/napari-ome-zarr):
+**Segmentation**:
 
-![Napari plate overview](https://user-images.githubusercontent.com/18033446/190983839-afb9743f-530c-4b00-bde7-23ad62404ee8.gif)
+  - *Cellpose Segmentation*: Segments images using custom or pre-trained Cellpose models, with user-tunable options.
 
+**Registration**:
 
-## Available tasks
+  - *Calculate Registration*: Computes translations for aligning images in multiplexed image analysis.
+  - *Find Registration Consensus*: Generates consensus transformations for aligning multiple acquisitions, updating ROI tables as necessary.
+  - *Apply Registration to Image*: Applies registration to images based on existing or newly created ROI tables.
 
-Currently, the following tasks are available:
+**Measurements**:
 
-* <u>Create Zarr Structure</u>: Task to generate the zarr structure based on Yokogawa metadata files
-* <u>Yokogawa to Zarr</u>: Parses the Yokogawa CV7000 image data and saves it to the Zarr file
-* <u>Illumination Correction</u>: Applies an illumination correction based on a flatfield image & subtracts a background from the image.
-* <u>Image Labeling</u> (& <u>Image Labeling Whole Well</u>): Applies a cellpose network to the image of a single ROI or the whole well. cellpose parameters can be tuned for optimal performance.
-* <u>Maximum Intensity Projection</u>: Creates a maximum intensity projection of the whole plate.
-* <u>Measurement</u>: Make some standard measurements (intensity & morphology) using napari workflows, saving results to AnnData tables.
+  - *Napari Workflows Wrapper*: Task to run existing napari workflows through Fractal to process images and labels and to generate new labels or measurement tables. Takes an arbitrary napari workflow yaml file to run.
 
-Some additional tasks are currently being worked on and some older tasks are still present in the `fractal_tasks_core` folder. See [the package page](https://fractal-analytics-platform.github.io/fractal-tasks-core/api_files/fractal_tasks_core.html) for the detailed description of all tasks.
+**Other Utilities**:
 
-## Contributors
+  - *Import OME-Zarr*: Validates and processes existing OME-Zarr files, adding ROI tables and metadata for further processing in Fractal.
 
-Fractal was conceived in the Liberali Lab at the Friedrich Miescher Institute for Biomedical Research and in the Pelkmans Lab at the University of Zurich by [@jluethi](https://github.com/jluethi) and [@gusqgm](https://github.com/gusqgm). The Fractal project is now developed at the [BioVisionCenter](https://www.biovisioncenter.uzh.ch/en.html) at the University of Zurich and the project lead is with [@jluethi](https://github.com/jluethi). The core development is done under contract by [eXact lab S.r.l.](https://www.exact-lab.it/).
+## Contributors and license
 
-## License
+Fractal was conceived in the Liberali Lab at the Friedrich Miescher Institute for Biomedical Research and in the Pelkmans Lab at the University of Zurich by [@jluethi](https://github.com/jluethi) and [@gusqgm](https://github.com/gusqgm). The Fractal project is now developed at the [BioVisionCenter](https://www.biovisioncenter.uzh.ch/en.html) at the University of Zurich and the project lead is with [@jluethi](https://github.com/jluethi). The core development is done under contract by [eXact lab S.r.l.](https://www.exact-lab.it).
 
-Fractal is released according to a BSD 3-Clause License, see [LICENSE](https://github.com/fractal-analytics-platform/fractal-tasks-core/blob/
-main/LICENSE).
+Unless otherwise specified, Fractal components are released under the BSD 3-Clause License, and copyright is with the BioVisionCenter at the University of Zurich.
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -29,6 +29,7 @@ extra_javascript:
 
 theme:
   name: "material"
+  logo: 'assets/fractal_logo.png'
   custom_dir: "docs/overrides"
   features:
     - content.code.annotate
@@ -100,8 +101,7 @@ extra_css:
   - extra.css
 
 copyright: |
-  © Copyright 2022
-  Friedrich Miescher Institute for Biomedical Research and
+  © Copyright 2024
   University of Zurich
   (see <u><a href="https://github.com/fractal-analytics-platform/fractal-tasks-core/blob/main/LICENSE">
   LICENSE
