add docs

.napari-hub/DESCRIPTION.md

@@ -0,0 +1,94 @@
+# 3D Filament Annotator
+
+## Summary
+
+3D Filament Annotator is a tool for annotating filaments and other curvilinear structures in 3D. 
+The 3D annotation is done by annotating the filament in two different projections, 
+calculating intersection, and refining the filament position with active contours.
+
+![demo](../docs/demo_09.gif)
+
+## Intended Audience & Supported Data
+
+The plugin is intended for annotation of filamentous structures from a 3D view. 
+The main use-case are structures that are not visible in a single-slice image due to being
+too thin or too low intensity. 
+
+No expertise in image analysis is required to use this plugin, though a basic knowledge of 
+active contours would be helpful to set the parameters.
+
+The plugin expects single-channel 3D images as input. Time-series data are not yet supported.
+
+## Quickstart
+
+**1. Open example image**
+
+![Open example image](../docs/demo_01.png)
+
+**2. Start the 3D annotator plugin**
+
+![Start 3D annotator plugin](../docs/demo_02.png)
+
+**3. Adjust image parameters**
+
+Adjust the voxel size of the image and the Gaussian-smoothing sigma that will be used to smooth the image for active
+contour refinement of filament position.
+
+- Voxel size in xy and z
+- Sigma um: smoothing sigma, microns (or the same units as used for the voxel size)
+
+![Adjust image parameters](../docs/demo_03.png)
+
+**4. Add annotation layer**
+
+Click the "Add annotation layer" button to add a new Shapes layer for annotation.
+
+This step might take several seconds, depending on the image size, due to some filtering 
+that is performed behind the scenes.
+
+![Add annotation layer](../docs/demo_05.png)
+
+**5. Annotate filaments**
+
+1. Rotate the image to find a position, where the filament is clearly visible
+2. Draw a line over the filament, by holding "Control" (or "Command" on macOS) and clicking with the mouse:
+   this will draw a polygon with potential filament locations
+3. Rotate the image to view the filament from another angle and repeat step 2
+4. Rotate the image again: this will calculate the filament position from the intersection of the two polygons
+5. Repeat steps 1-4 for other filaments
+
+Hot keys to edit the annotations:
+
+- `p`: delete the last added point (during the polygon drawing)
+- `d`: delete the last added shape (polygon or filament)
+- `f`: delete the first point of the last added filament
+- `l`: delete the last point of the last added filament
+
+![Annotate](../docs/demo_09.gif)
+
+**6. Save annotations**
+
+Save final or intermediate annotations to a csv file.
+
+There is an option to load previously annotated filaments and continue the annotation.
+
+![Save annotations](../docs/demo_10.png)
+
+## Documentation 
+
+For more details on the plugin functionality and tips for adjusting parameters,
+please refer to the [Filamenter Annotator Tutorial](../docs/tutorial.md)
+
+## Getting Help
+
+If you encounter any problems, please 
+[file an issue](https://github.com/amedyukhina/napari-filament-annotator/issues) 
+along with a detailed description.
+
+If you have a question, you can ask it in the 
+[Discussion tab](https://github.com/amedyukhina/napari-filament-annotator/discussions) 
+of the project.
+
+## How to Cite
+
+

README.md

@@ -7,13 +7,9 @@
 [![codecov](https://codecov.io/gh/amedyukhina/napari-filament-annotator/branch/main/graph/badge.svg)](https://codecov.io/gh/amedyukhina/napari-filament-annotator)
 [![napari hub](https://img.shields.io/endpoint?url=https://api.napari-hub.org/shields/napari-filament-annotator)](https://napari-hub.org/plugins/napari-filament-annotator)
 
-Annotation of filaments / curvilinear structures in 3D.
-
-----------------------------------
-
-Annotate the filament in two different projections, calculate intersection, and refine the filament position
-by active contour evolution.
-
+3D Filament Annotator is a tool for annotating filaments and other curvilinear structures in 3D. 
+The 3D annotation is done by annotating the filament in two different projections, 
+calculating intersection, and refining the filament position with active contours.
 
 ![demo](docs/demo_09.gif)
 
@@ -42,7 +38,10 @@ For detailed usage instructions, please refer to the [usage tutorial](docs/tutor
 
 ## Contributing
 
-Contributions are very welcome. Tests can be run with [tox], please ensure
+Contributions are very welcome both with regard to plugin functionality, and
+tips on using it and setting parameters. 
+
+Tests can be run with [tox], please ensure
 the coverage at least stays the same before you submit a pull request.
 
 ## License

docs/tutorial.md

@@ -3,15 +3,15 @@
 The filament position is calculated as intersection between annotations done in two different projections. The filament
 position is then refined by the active contour.
 
-**1. Open example image**
+###1. Open example image
 
 ![Open example image](demo_01.png)
 
-**2. Start the 3D annotator plugin**
+###2. Start the 3D annotator plugin
 
 ![Start 3D annotator plugin](demo_02.png)
 
-**3. Adjust image parameters**
+###3. Adjust image parameters
 
 Adjust the voxel size of the image and the Gaussian-smoothing sigma that will be used to smooth the image for active
 contour refinement of filament position.
@@ -21,7 +21,7 @@ contour refinement of filament position.
 
 ![Adjust image parameters](demo_03.png)
 
-**4. Mask out bright parts of the image**
+###4. Mask out bright parts of the image
 
 If necessary, mask out parts of the image that are brighter than the target filaments by adjusting the slider for the
 maximum image intensity. This is done to avoid the annotation being attracted to these bright parts during the active
@@ -35,7 +35,7 @@ related to macOS with intel built-in GPU)
 
 ![Mask out bright parts](demo_04b.gif)
 
-**5. Add annotation layer**
+###5. Add annotation layer
 
 Click the "Add annotation layer" button to add a new Shapes layer for annotation.
 
@@ -46,13 +46,13 @@ Due to this filtering step, adding an annotation layer might take several second
 
 ![Add annotation layer](demo_05.png)
 
-**6. Adjust display parameters**
+###6. Adjust display parameters
 
 Adjust the line width for the annotations.
 
 ![Adjust line width](demo_06.png)
 
-**7. Adjust parameters for annotation refinement**
+###7. Adjust parameters for annotation refinement
 
 - [Active contour](https://en.wikipedia.org/wiki/Active_contour_model#Energy_formulation) parameters:
     - alpha: active contour weight for the amount of stretch in the contour; large values penalize changes in the
@@ -70,13 +70,13 @@ Adjust the line width for the annotations.
 
 ![Adjust refinement parameters](demo_07.png)
 
-**8. Save parameters for future annotation**
+###8. Save parameters for future annotation
 
 There is an option to save all adjusted parameters to a json file to load for future annotation.
 
 ![Save parameters](demo_08.png)
 
-**9. Annotate filaments**
+###9. Annotate filaments
 
 1. Rotate the image to find a position, where the filament is clearly visible
 2. Draw a line over the filament, by holding "Control" (or "Command" on macOS) and clicking with the mouse:
@@ -94,10 +94,36 @@ Hot keys to edit the annotations:
 
 ![Annotate](demo_09.gif)
 
-**10. Save annotations**
+###10. Save annotations
 
 Save final or intermediate annotations to a csv file.
 
 There is an option to load previously annotated filaments and continue the annotation.
 
 ![Save annotations](demo_10.png)
+
+## A few tips for annotation
+
+1. If your images contain a lot of clutter that hinders visibility, and you only need to 
+annotate a small part of the image, use Fiji or Slicer to mask out irrelevant parts.
+
+2. If your images contain structure that are brighter than the structure that you want to
+annotate, use the slider in the plugin 
+   ([step 4](tutorial.md#4.-Mask-out-bright-parts-of-the-image)) to maks out the bright pixels 
+   and prevent active contour from attracting to these bright pixels
+
+3. After adjusting parameters for one image, 
+   [save](tutotial.md#8.-Save-parameters-for-future-annotation) them to a json file and
+   load for annotating other images from the same batch
+
+4. Adjust the contrast in the image layer, and zoom in and out for better visibility of 
+low-intensity filaments
+
+5. Use hot keys to edit annotations; "d" to delete the last filament; 
+   "f" to delete the first point of the last filament; 
+   "l" to delete the last point of the last filament
+
+6. If a filament "snaps" to the nearest brighter filament, 
+   decrease or disable the "gamma" parameter, decrease the number of active contour iterations, 
+   or disable the active contour by setting the number of iterations to 0.
+