Merge branch 'main' into 68-create-a-widget-for-vesicle-pool-assignments

Author: constantinpape

.github/workflows/run_tests.yaml

@@ -0,0 +1,40 @@
+name: test
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*" # Push events to matching v*, i.e. v1.0, v20.15.10
+  pull_request:  # run CI on commits to any open PR
+  workflow_dispatch:  # can manually trigger CI from GitHub actions tab
+
+
+jobs:
+  test:
+    name: ${{ matrix.os }} ${{ matrix.python-version }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 60
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.11"]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup micromamba
+        uses: mamba-org/setup-micromamba@v1
+        with:
+          environment-file: environment_cpu.yaml
+          create-args: >-
+            python=${{ matrix.python-version }}
+
+      - name: Install SynapseNet
+        shell: bash -l {0}
+        run: pip install --no-deps -e .
+
+      - name: Run tests
+        shell: bash -l {0}
+        run: python -m unittest discover -s test -v

README.md

@@ -1,21 +1,10 @@
-# Synaptic Reconstruction
+# SynapseNet: Deep Learning for Automatic Synapse Reconstruction
 
-Reconstruction of synaptic structures in electron microscopy.
+SynapseNet is a tool for segmentation and analysis of synapses in electron microscopy.
 
-THIS IS WORK IN PROGRESS!
+To learn how to use SynapseNet, check out [the documentation](https://computational-cell-analytics.github.io/synapse-net/).
+To learn more about how it works, check out [our preprint](TODO).
 
-## Installation
-
-- Make sure conda or mamba is installed.
-    - If you don't have a conda installation yet we recommend [micromamba](https://mamba.readthedocs.io/en/latest/installation/micromamba-installation.html)
-- Create the environment with all required dependencies: `mamba env create -f environment.yaml`
-- Activate the environment: `mamba activate synaptic-reconstruction`
-- Install the package: `pip install -e .`
-
-## Tools
-
-### Segmentation Correction
-
-https://napari.org/stable/howtos/layers/labels.html
-
-### Distance Measurements
+See an example reconstruction of a mossy fibre synapse with SynapseNet.
+Automatic segmentation of synaptic vesicles are rendered in orange, active zones in blue and two mitochondria in red and cyan.
+![Reconstruction of a mossy fiber synapse](doc/images/synapse-reconstruction.png)

doc/images/synapse-reconstruction.png

@@ -1,2 +1,87 @@
-# Synaptic Reconstruction
-lorem ipsum...
+# SynapseNet: Deep Learning for Automatic Synapse Reconstruction
+
+SynapseNet is a tool for automatic segmentation and analysis of synapses in electron micrographs.
+It provides deep neural networks for:
+- Synaptic vesicle segmentation in ssTEM (2d data) and (cryo-)electron tomography (3d data)
+- Active zone membrane segmentation in electron tomography
+- Mitochondrion segmentation in electron tomography
+- Synaptic compartment segmentation in electron tomography
+- Synaptic ribbon and pre-synaptic density segmentation for ribbon synapses in electron tomography
+It also offers functionality for quantifying synaptic ultrastructure based on segmentation results, for example by measuring vesicle or structure morphology, measuring distances between vesicles and structures, or assigning vesicles into different pools.
+SynapseNet mainly targets electron tomography, but can also be appled to other types of electron microscopy,
+especially throught the [domain adaptation](domain-adaptation) functionality.
+
+SynapseNet offers a [napari plugin](napari-plugin), [command line interface](command-line-interface), and [python library](python-library).
+Please cite our [bioRxiv preprint](TODO) if you use it in your research.
+
+
+## Requirements & Installation
+
+SynapseNet was developed and tested on Linux. It should be possible to install and use it on Mac or Windows, but we have not tested this.
+Furthermore, SynapseNet requires a GPU for segmentation of 3D volumes.
+
+You need a [conda](https://docs.conda.io/projects/conda/en/latest/user-guide/install/index.html) or [mamba](https://mamba.readthedocs.io/en/latest/installation/mamba-installation.html) installation. Follow the instruction at the respective links if you have installed neither. We assume you have `conda` for the rest of the instructions. After installing it, you can use the `conda` command.
+
+To install it you should follow these steps:
+- First, download the SynapseNet repository via
+```bash
+git clone https://github.com/computational-cell-analytics/synapse-net
+```
+- Then, enter the `synapse-net` folder:
+```bash
+cd synapse-net
+```
+- Now you can install the environment for SynapseNet with `conda` from the environment file we proved:
+```bash
+conda env create -f environment.yaml
+```
+- You will need to confirm this step. It will take a while. Afterwards you can activate the environment:
+```bash
+conda activate synapse-net
+```
+- Finally, install SynapseNet itself into the environment:
+```bash
+pip install -e .
+```
+
+Now you can use all SynapseNet features. From now on, just activate the environment via
+```
+conda activate synapse-net
+```
+to use them.
+
+> Note: If you use `mamba` instead of conda just replace `conda` in the commands above with `mamba`.
+
+> Note: We also provide an environment for a CPU version of SynapseNet. You can install it by replacing `environment.yaml` with `environment_cpu.yaml` in the respective command above. This version can be used for 2D vesicle segmentation, but it does not work for 3D segmentation.
+
+> Note: If you have issues with the CUDA version then install a PyTorch that matches your nvidia drivers. See [pytorch.org](https://pytorch.org/) for details.
+
+
+## Napari Plugin
+
+**The rest of the documentation will be updated in the next days!**
+
+
+## Command Line Functionality
+
+- segmentation cli
+- export to imod
+    - vesicles / spheres
+    - objects
+
+
+## Python Library
+
+- segmentation functions
+- distance and morphology measurements
+- imod
+
+### Domain Adaptation
+
+- explain domain adaptation
+- link to the example script
+
+### Network Training
+
+- explain / diff to domain adaptation
+- link to the example script

doc/start_page.md

@@ -1,17 +1,22 @@
 channels:
+    - pytorch
+    - nvidia
     - conda-forge
 name:
-    synaptic-reconstruction
+    synapse-net
 dependencies:
-    - python-elf
+    - bioimageio.core
+    - kornia
+    - magicgui
     - napari
     - pip
     - pyqt
-    - magicgui
+    - python-elf
     - pytorch
-    - bioimageio.core
-    - kornia
+    - pytorch-cuda=12.4
     - tensorboard
+    - torch_em
+    - torchvision
     - trimesh
     - pip:
         - napari-skimage-regionprops

environment.yaml

@@ -0,0 +1,18 @@
+channels:
+    - conda-forge
+name:
+    synapse-net
+dependencies:
+    - bioimageio.core
+    - kornia
+    - magicgui
+    - napari
+    - pip
+    - pyqt
+    - python-elf
+    - pytorch
+    - tensorboard
+    - torch_em
+    - trimesh
+    - pip:
+        - napari-skimage-regionprops