Epicure- version 1.3 - Merge pull request #7 from gletort/epidev

Epicure- version 1.3
Version with TrackMate export
Tests updated, some small bugs corrected
Doc updated
Reading of input images with bioio, compatible with more formats

Author: gletort

.gitignore

@@ -25,6 +25,7 @@ lib64/
 parts/
 src/_tests/files/
 sdist/
+test_data/epics/
 var/
 *.egg-info/
 .installed.cfg

docs/Display.md

@@ -22,3 +22,26 @@ When `Add grid` is clicked, the grid is visible and a layer `EpicGrid` is added
 :round_pushpin: **Press <kbd>g</kbd> to show/hide the grid.**
 
 ![grid](imgs/display.png)
+
+## Visualization shortcuts :eye:
+
+???+ tip "Shortcut/options"
+
+     _**EpiCure shortcuts are only active when `Segmentation` layer is selected**_
+
+	=== "Display :eye:"
+	
+		|   |     |	
+		| ------------ | ------------------------------------ |
+		| <kbd>h</kbd>|Show/hide help message| 
+		| <kbd>a</kbd>|Opens a pop-up window with all the shortcuts| 
+		| <kbd>v</kbd>|Show/hide the raw movie (or click the :eye: icon next to the `Movie` layer in the bottom left panel)| 
+		| <kbd>b</kbd>|Show/hide the segmentation (or click the :eye: icon next to the `Segmentation` layer in the bottom left panel)| 
+		| <kbd>c</kbd>|Show **only** the raw movie. Press again to go back to previous display state| 
+		| <kbd>5</kbd>|Switch between zooming mode and moving mode| 
+		| <kbd>k</kbd>|Show/hide segmentation skeleton (or go to `Display` panel and click `Show segmentation skeleton`)| 
+		| <kbd>g</kbd>|Show/hide a grid (see [grid options above](#grid-options))| 
+		| <kbd>x</kbd>|Show/hide the event points (division, extrusion, suspect)| 
+		| `contour`| Labels (cells) can be displayed as filled areas (put `contour` to 0) or only the contour lines  `contour`>0 | 
+		|<kbd>Ctrl-c</kbd>/<kbd>Ctrl-d</kbd>| Increase/Decrease the `contour` value| 
+		|`show selected`|See only the current label (the pixels which have the value that is currently active in the `label` field)|

docs/Inspect.md

@@ -39,11 +39,18 @@ You can manually add a division event, or remove one.
 * To add a divison, do <kbd>Control+Shift+Left clikc</kbd> from one daughter cell to the other. EpiCure will detect automatically the most likely mother cell.
 If suspect events had been found on the two daughter cells or on the mother cell, they will be automatically removed when manually adding the division.
 
+### Detect divisions
+Divisions can be generated by the tracking algorithm and will be directly added to the list of events in that case.
+It is also possible to find the division by inspecting the track, by looking for disapearing tracks if two appearing tracks could be linked to it as a daughter cells.
+
+For this, in `Inspect>Track options`, select the `Get divisions` option and click `Inspect track` to run the detection. 
 
 ## Extrusion events
 
 Extrusions are indicated by a red cross, placed on the last frame where the cell is still visible.
-
+![extrusion_event](imgs/inspect_extrusion_sequence.png)
+ 
+### Detect extrusions
 Extrusion events are detected with the `Inspect` panel, in the inspect track option.
 It detects track that suddenly disappear (no daughter cell, not on the last frame, and not on the tissue boundary if the option `ignore boundary cells` is checked).
 As a sudden disparition of a track can also be due to a segmentation/tracking error, we added a constraint on the size of the cell to consider the disappearance as an extrusion.

docs/Installation.md

@@ -5,20 +5,34 @@ EpiCure is a Napari plugin, in python.
 You can install it either through an already installed Napari instance by going in Napari to `Plugins>Install/Uninstall`, search for `Epicure` and click `Install`.
 You could have version issues between the different modules installed in your environment and EpiCure dependencies, in this case it is recommended to create a new virtual environnement specific for EpiCure.
 
-## From virtual environnement
+
+## From a virtual environment (recommended)
+
 To install EpiCure in a new environnement, you should create a new virtual environnement or activate an exisiting compatible one.
 
-### Create a new virtual environement
- You can create a virtual environement [with venv](https://www.geeksforgeeks.org/create-virtual-environment-using-venv-python/) or anaconda (you may need to install anaconda, see here: [on windows](https://www.geeksforgeeks.org/how-to-install-anaconda-on-windows/), [on macOS](https://www.geeksforgeeks.org/installation-guide/how-to-install-anaconda-on-macos/?ref=ml_lbp) or [on linux](https://www.geeksforgeeks.org/how-to-install-anaconda-on-linux/) ). 
+### Step 1 : install a Python management package (if you don't have one already). 
+You have different options, but you have to choose one:  
 
-Then use the Anaconda interface to create a new virtual environement with the desired python version, or [through the Terminal](https://www.geeksforgeeks.org/set-up-virtual-environment-for-python-using-anaconda/).
+- Miniforge (**recommended**): fast, free but no interface. Follow the detailled steps here to [install miniforge](https://kirenz.github.io/codelabs/codelabs/miniforge-setup/#0)
+- venv: fast and simple install in general, no interface. See [tutorial here](https://www.geeksforgeeks.org/create-virtual-environment-using-venv-python/)
+- Mamba: fast, free but no interface. See [here](https://informatics.fas.harvard.edu/resources/tutorials/installing-command-line-software-conda-mamba/)
+- Anaconda: a sort of interface, works well on MacOS and Windows but slow and might not stay free to all. See here: [on windows](https://www.geeksforgeeks.org/how-to-install-anaconda-on-windows/), [on macOS](https://www.geeksforgeeks.org/installation-guide/how-to-install-anaconda-on-macos/?ref=ml_lbp) or [on linux](https://www.geeksforgeeks.org/how-to-install-anaconda-on-linux/) ). 
+ 
+### Step 2 : Create a virtual environment with that python management package. 
+Once you have installed such Python management package, they generally create one environment called `base` but you should not install anything in that environment.  
 
-For example, in a terminal, once conda is installed, you can create a new environnement by typing:
-```
-conda create -n epicurenv python=3.10
+- You need to create an environment where you will install EpiCure. To do so you first open the terminal (activated in the `base` environment), and type: 
 ```
+    conda create -n epicurenv python=3.10
+``` 
+It will install python 3.10 and create an environment called `epicurenv`. 
+
 
-### Install EpiCure 
+!!! warning "Python version"
+    If you wish to use the option to segment the movie with Epyseg, you must use a python version until <= 3.10. Indeed, epyseg is not compatible on more recent versions. By default, we recommend 3.10 so that everything is compatible
+
+
+### Step 3: Install EpiCure 
 Once you have created/identified a virtual environnement, type in the terminal:
 ``` 
 conda activate epicurenv
@@ -32,4 +46,10 @@ pip install epicure
 ```
 to install EpiCure with its dependencies.
 
+**Step 4: Open napari and start using EpiCure **
+You can open napari by writing `napari` in the terminal. 
+It is often slow to open the first time but that’s it. 
+
+You can start EpiCure by going in `Plugins>EpiCure>Start Epicure` and follow the [Usage online documentation](./Start-epicure.md) to know how to use it.
+
 ## Compatibility/Dependencies

docs/Output.md

@@ -12,19 +12,26 @@
 ## Define current selection
 
 You can choose which cells to analyse/export with the `Apply on` option in the interface:
+
 * `Only selected cell` will measure/export only the currently selected label/cell. Its value can be seen and modified in the left panel under `label`. You can select `show selected` option in that panel to see only this cell.
 * _`GroupName`_ will measure/export all the cells in the corresponding Group (that have beend defined with the `Edit>Group` options. To see which cells are in the group, you can select the option `see group cells` in the `Edit>Group` panel of Epicure.
 * `All cells` will measure/export all the cells in the `Segmentation` layer.
 
 ---
 
-## Export to other plugins
+## Export to TrackMate
 
-The output of EpiCure are also compatible with other Napari plugins, and this panel allows you to communicate directly with those plugins. It will open a new Napari window, with the corresponding plugin launched, and the necessary layer. You need to have these plugins already installed in Napari, or install them in the `Plugins` panel of Napari.
+The corrected segmentation/tracking can be exported as a [TrackMate](https://imagej.net/plugins/trackmate/) `.xml` file that can be directly loadded into TrackMate in Fiji as for any other TrackMate file.
 
-Currently, we propose direct export to:
-* [Griotte Napari plugin](https://www.napari-hub.org/plugins/napari-griottes) that allows to visualize/export the connectivity graphs between the cells.
-* [Cluster-Plotter Napari plugin](https://github.com/BiAPoL/napari-clusters-plotter) that allows to cluster objects based on their properties and interactive visualisation of the results.
+Select the option `Save as TrackMate XMl` and click on the `Save as TrackMate XML` to create this file. 
+Segmentation, tracking and divisions will be exported in the correct TrackMate format.
+
+You can then load it in `Fiji` with `TrackMate>Load a TrackMate file` and selecting the created `imagename.xml` file in `epics` folder. Don't move it or the input image to be sure that TrackMate will load them correctly.
+
+![trackmate export](./imgs/output_trackmate.png)
+
+!!! warning "Image with swapped Z and T"
+	In some cases, the image dimensions are not correctly set, and the temporal dimension is set as a Z-axis dimension. EpiCure should handle this case and print a warning on opening this image, but if you load the file with TrackMate from the exported `.xml` it's possible that the image dimensions will be uncorrect. In that case, all the segmentations will be overlaid on the first image. Then in Fiji you should swap them to have a temporal axis (`frames`) and not a Z axis (`slices`). 
 
 ---
 
@@ -45,7 +52,7 @@ The button `Save segmentation(s)` allows to save the label image of the segmente
 ### Save skeleton
 
 Allows to save the skeleton: the binary of the junctions, of the current selection (only selected cells, cells of a given group, or all cells). The file will be saved in the output folder.
-The skeleton can also be displayed by pressing <kbd>k>/kdb> when the segmentation layer is active.
+The skeleton can also be displayed by pressing <kbd>k</kdb> when the segmentation layer is active.
 
 ---
 
@@ -59,6 +66,16 @@ Then choose the type of format to export the event.
 Currently, only `Fiji ROI` is proposed. It will save the list of events as `Fiji point ROI` in a `.zip` file which can be open in Fiji through the `ROI Manager`. This export format is also compatible with [`DeXtrusion`](https://gitlab.pasteur.fr/gletort/dextrusion) so that EpiCure can be used to create a training dataset for DeXtrusion.
 
 
+---
+## Export to other plugins
+
+The output of EpiCure are also compatible with other Napari plugins, and this panel allows you to communicate directly with those plugins. It will open a new Napari window, with the corresponding plugin launched, and the necessary layer. You need to have these plugins already installed in Napari, or install them in the `Plugins` panel of Napari.
+
+Currently, we propose direct export to:
+
+* [Griotte Napari plugin](https://www.napari-hub.org/plugins/napari-griottes) that allows to visualize/export the connectivity graphs between the cells.
+* [Cluster-Plotter Napari plugin](https://github.com/BiAPoL/napari-clusters-plotter) that allows to cluster objects based on their properties and interactive visualisation of the results.
+
 ---
 
 ## Measure cell features
@@ -163,3 +180,12 @@ If you need to measure a feature that is not yet present in this list, you can o
 	|Straightness|How straight is the trajectory: NetDisplacement/TotalDisplacement. A value of 1 means the track is linear (totally straight) while close to 0 the motion is very tortuous|
 	|Group|Group in which the cell Label is classified if any|
 
+---
+
+## Save screenshot movie
+
+This allows to save screenshots of the current display/current view (same part of the movie, same zoom...) for several consecutives frames.
+Choose the first and last frame of the screenshot movie and click on `save current view`.
+This will creates a `.tif` file in the `epics` folder containing the screenshots of the current view repeated on the given frames.
+
+![interface of screenshot movies](./imgs/output_screenshot.png)

docs/Start-epicure.md

@@ -5,26 +5,47 @@
 
 In the `Start EpiCure` step, you have a dedicated interface in the right part of the main interface.
 
-The first file to choose is the movie containing the epithelial staining, with th `image file` parameter. 
-It should be _2D(+time), .tif file_. 
+The first file to choose is the movie containing the epithelial staining, with the `image file` parameter. 
+It should be _2D(+time/channels) file_. 3D is not handled. If a file has a Z dimension and no temporal dimension, EpiCure will swap them and use the Z axis as time.  
 
 If the file contains several chanels, the plugin should detect it and show the `junction_chanel` parameter, to choose the chanel that contains the junction staining. The plugin will display only this chanel. If you wish to also see the other chanels, use the option `show other chanels` in the [advanced parameters](#advanced-parameters) panel.
 
-The second file is the segmentation of this movie (also a `.tif` file). It can be a binarized file of the junctions (skeletonized) or a labelled file (each cell is filled by a unique number).
+The second file is the segmentation of this movie (it should only contain the segmentation), to select with the `segmentation file` parameter. It can be a binarized file of the junctions (skeletonized) or a labelled file (each cell is filled by a unique number).
 
-_Note that if you haven't done the segmentation yet, there's an [additional option](#segment-with-epyseg) in EpiCure to directly run [EpySeg](https://github.com/baigouy/EPySeg) on the loaded movie._ 
+_Note that if you haven't done the segmentation yet, there's an [additional option](./Segment-option.md) in EpiCure to directly run [EpySeg](https://github.com/baigouy/EPySeg) on the loaded movie._ 
+
+If the input movie file had already been processed with EpiCure previously (and saved), EpiCure will automatically propose to load the saved file and reload the previous parameters. You can directly click `START CURE` in this case.
 
 ![start interface](./imgs/starting.png)
 
+## Movie metadata
+The information of pixel size in xy dimensions and of temporal resolution can be set with the scaling parameters:
+`scale xy` (the size of one pixel in the corresponding unit), `unit_xy` (which unit, usually `µm`), `timeframe` (the temporal resolution at which the movie is acquired) and `unit_t` (which unit for the temporal resolution).
+
+These scaling information is then used to display the movie with the correct sizes and export the measures in scaled units if the option is selected.
+
+Since version 1.3 of EpiCure, files are loaded with the [bioio](https://github.com/bioio-devs/bioio) python library, to support several formats.
+EpiCure reads the metadata of the input file with this library and fill the value of the scaling parameters of the interface. 
+Depending on python/module versions and the input file itself, all the information might not be correctly extracted, so we recommend to check these values to be sure that the movie will be properly scaled in EpiCure.
+
 ## Advanced parameters
 
 `output dirname` is the name of directory where all files generated by `EpiCure` will be saved. By default, it is placed in the input movie directory and called `epics`.
 
 `show other chanels` will display the other chanels of the original movie.
 
+`show scale bar` will display a scale bar overlaid on the movie. This can also be manually set by going in `Napari>View>Scale Bar>Scale Bar Visible`.
+
+`allow gaps`: allows tracks to have a few gaps (intermediate frames in which one label is not present, but reappear later).
+
 `epithelial cells`: EpiCure has been developed and optimized for epithelia movies, with jointive cells. However, you can still use it for non jointive cells by unselecting this option. Note that some options might not be usable in that case
 
 `process frames parallel`: if this is checked, some operations will be performed in parallel, processing multiple frames at the same time. The number of parallel threads run together is defined by the parameter `nbparallel_threads`, which is by default 75% of the computer's cpu numbers. 
 
 `verbose level` defines the amount of messages that are printed to the user. By default, some information or warning messages are shown. If this parameter is put to 0, very few messages will appear while if it's put to 3, a lot of information useful for debugging will be shown.
 
+## Using EpiCure without interface
+
+While EpiCure is optimized for a graphical usage as its scope relies on easing manual edition of segmentation, there's a possbility to launch it without starting Napari first (or at all).
+This can be useful for automatic testing or batching some process. 
+See our released [notebooks](https://github.com/gletort/Epicure/tree/main/notebooks/) for example of usage or our [test files](https://github.com/gletort/Epicure/tree/main/src/tests/).