ZebraFishTFM · ziyi-zhang · Jan 2, 2022
diff --git a/docs/cli.md b/docs/cli.md
@@ -1,2 +1,30 @@
 # Command-line Interface
 
+The system supports command line mode (without triggering the GUI) for batch processing. But this should only be used for a batch of images of similar qualities. In general, there is no guarantee of the correctness of the final output without human intervention.
+
+```
+./Cellogram -i {PATH_TO_IMAGE} -c -s {PATH_TO_JSON_SETTINGS}
+```
+
+We also prepared a MATLAB script to invoke this batch mode at `script/batch_cellgram.m`.
+
+Especially, the JSON file can override all the settings used in the GUI analysis. Here are the default values for some of the settings:
+```
+json default_analysis_settings = R”({
+    “scaling”: 0.098,
+    “zscaling”: 0.5,
+    “E”: 13.578,
+    “I”: 0.5,
+    “L”: 3.0,
+    “eps”: 0.32967033982276917,
+    “formulation”: “LinearElasticity”,
+    “image_from_pillars”: false,
+    “nu”: 0.49,
+    “padding_size”: 25.0,
+    “displacement_threshold”: 0.18,
+    “relative_threshold”: true,
+    “mesh_size”: 0.15,
+    “thickness”: 30.0,
+    “mesh_gradation”: 1.2
+    })“_json;
+```
diff --git a/docs/media/depth.png b/docs/media/depth.png
diff --git a/docs/media/depth_fix1.png b/docs/media/depth_fix1.png
diff --git a/docs/media/depth_fix2.png b/docs/media/depth_fix2.png
diff --git a/docs/media/stage_1.png b/docs/media/stage_1.png
diff --git a/docs/media/usage1.png b/docs/media/usage1.png
diff --git a/docs/media/usage2.png b/docs/media/usage2.png
diff --git a/docs/media/usage3.png b/docs/media/usage3.png
diff --git a/docs/media/usage4.png b/docs/media/usage4.png
diff --git a/docs/media/usage5.png b/docs/media/usage5.png
diff --git a/docs/media/usage6.png b/docs/media/usage6.png
diff --git a/docs/stage_1.md b/docs/stage_1.md
@@ -0,0 +1,7 @@
+![](./media/stage_1.png)
+
+- `Sigma`: sigma for Gaussian fitting. Larger markers usually need a larger `Sigma`.
+- `Otsu`: thresholding multiplier used in 2D marker detection algorithm.
+- If the image is too bright or dark due to outlier brightness pixels, use the `min` and `max` slider as cutoff values. This modifies the image data and could facilitate subsequent steps.
+- The `dark` slider has similar effects, but it only has to do with visualization and does not modify the image data.
+- `Advanced vertex options`: manually delete, add or move vertices using your mouse.
diff --git a/docs/stage_2.md b/docs/stage_2.md
@@ -0,0 +1,5 @@
+In this stage, the system has found a valid connectivity of the mesh and cleaned up incorrectly detected markers. Additionally it has added points that were missed during the detection. The underlying algorithm is the same as in the previous Cellogram paper.
+
+In case there were previously undetected points added, the button to move points appears. Move the points to their exact position by clicking and dragging them.
+
+Most likely, it would simply say "Great! No vertex added" meaning your input image is of great quality.
diff --git a/docs/stage_3.md b/docs/stage_3.md
@@ -0,0 +1,33 @@
+![](./media/usage2.png)
+
+###	`Compute Bspline`
+
+This could take a long time if the image is large. The lower-right window (`Image Viewer`) has info about your image stack shape. In this example the image is $451\times 734\times 25$ and will take 1~2 minutes to prepare.
+
+It is highly suggested to crop the image to focus on the area of interest to save time and prevent using up all the memory.
+
+### `Depth Search`
+
+This is the step where we introduce the depth coordinate. Prior to this step the mesh is just a 2D flat thing.
+
+![](./media/depth.png)
+
+Unfortunately, this step does not always succeed. ☹️
+
+The depth search for most markers in the above figure is OK, but 
+
+-  The red markers (index 16, 152, 126) indicate "depth search failure". There could be multiple reasons, but most likely “too close to boundary” which is indeed the case here.
+-  The yellow markers (index 92) indicate "warning". The cause may be blurry images, random noise or “too close to search range”. Here if we take a look at the image, index 92 is best captured in the bottom z-slice out of 25 slices, which is problematic because its correct depth might be out of this image stack.
+
+#### What do we do to fix them?
+-	Change the Camera Type to “Two Axes”. It should give us a good intuition of what’s happening in 3D.
+-	Change the 3D Image Viewer Type to “Z-Slice” and play around the `slice` slider. It is helpful to manually determine one marker’s correct depth.
+
+![](./media/depth_fix1.png)
+
+-	Open `Window-Property Editor` under `View`, we can manually change the depth ($Z$-coordinate).
+
+![](./media/depth_fix2.png)
+
+-	`Depth Search Refine` button under `Advanced Depth` runs depth search again based on the latest coordinates. It is highly suggested to click this button after any manual modification of the markers $XYZR$ information.
+
diff --git a/docs/stage_4.md b/docs/stage_4.md
@@ -0,0 +1,17 @@
+### `Build volumetric mesh`
+This step generates a 3D tetrahedral mesh (interior filled with tetrahedra, not empty)
+-	Make sure the four important parameters are correct
+    - `Z-scaling`: um/pixel in Z
+    - `XY-scaling`: um/pixel in XY
+    - `E`: Young’s modulus in kPa
+    - `Nu`: Poisson’s ratio
+
+> how thick is the material?  
+> We can also set that if needed (advanced mesh options - thickness)
+
+### Click the `>`
+This solves the finite element model. Two results will be automatically saved at the same folder as the input image.
+-	`{FileName}.vtu`
+-	`{FileName}.all.vtu`
+
+They are essentially the same except the “all” one saves the entire box and the other one saves only one surface (the surface with the mesh we care about).
diff --git a/docs/stage_5.md b/docs/stage_5.md
@@ -0,0 +1,18 @@
+This is simply the result preview. Doing anything here does not affect the computed result.
+
+The `displacement`, the 3x3 stress matrix and the computed `traction forces` have already been exported to the `VTU` files. There is no need to click the `Save` button.
+
+***
+
+![](./media/usage6.png)
+
+Here is the detailed steps to visualize the vector field in `Paraview`:
+
+-	Load the vtu file with ParaView.
+-	Click `Apply changes to parameters automatically`. This saves us from clicking `Apply` every time.
+-	Click the loaded vtu in the `Pipeline browser` to focus on it
+-	Change colormap to `displacement` and visualization type to `Surface With Edges`
+    - This controls what the flat mesh is showing
+-	To view the vector field (displacement or traction force), when focused on the vtu file, click `Glyph`
+-	Now click that new "glyph1" to focus on that
+-	Change the `Orientation Array`, `Scale Array` and glyph1's `colormap` to “displacement”.
diff --git a/docs/usage.md b/docs/usage.md
@@ -1 +1,35 @@
 # Usage Instructions
+This section explains the most important steps to calculate the traction forces for an image. For a detailed explanation of all the features, please check the `Interface Description` page.
+
+## Marker Detection
+After loading the image, the first step is 2D marker detection. If there is any mistake made by the auto-detection, it is possible to manually fix them (by mouse click deleting, adding and moving) in the second stage.  
+At the end of marker detection, we only have markers' $XY$ information.
+
+![](./media/usage1.png)
+
+## Depth Search
+This stage computes the $Z$-coordinate of the markers. The user needs to first click the `Compute Bspline` button. This step may take minutes if the image stack is large. Once the B-Spline control points are computed, the `Depth Search` button will pop up. It runs some optimization for each marker to decide an optimal $Z$-coordinate (or depth) for it.  
+The optimization may not always succeed, for example when a marker is too close to the image stack border (in the image below, the depth of marker 87 has touched the bottom of the image stack), or the image itself is too blurry for the system to automatically make a decision. Our GUI can highlight such problematic markers with colors. We also provide multiple tools to fix such problems.
+
+![](./media/usage2.png)
+
+## Volumetric Mesh
+Once we reach the fourth stage, the system will switch to another visualization to highlight the **displacements** of the markers as visualized in orange line segments. After this step, we no longer need to the original image stack any more.
+
+![](./media/usage3.png)
+
+By clicking `Build Volumetric Mesh`, the system will construct a tetrahedral mesh based on the old mesh. This volumetric mesh is not only a surface: it has its interior filled with tetrahedra. Padding is adopted by default so the volume may look larger.
+
+![](./media/usage4.png)
+
+## Results
+The system will solve the underlying finite element model when reaching this stage. The user can preview the final results of either displacements or traction forces with interpolation.  
+The result will automatically be exported to `{FileName}.vtu` at the same folder as the input image. It contains the `displacement`, the 3x3 stress matrix and the computed `traction forces`. There is no need to manually click the `save` button.
+
+![](./media/usage5.png)
+
+## Visualization
+The final results are stored in a `VTU` file. One can read it with python for customized visualization or post data processing.  
+Here we showcase one possible way to visualize the `displacement` in 3D vector fields with `Paraview`, a commercial visualization software.
+
+![](./media/usage6.png)
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -47,3 +47,14 @@ nav:
   - Home: index.md
   - Documentation: usage.md
   - Command-Line: cli.md
+nav:
+  - Home: index.md
+  - Documentation:
+    - Usage: usage.md
+    - Command-Line: cli.md
+    - Interface Description:
+      - Stage 1 - Detection: stage_1.md
+      - Stage 2 - Meshing: stage_2.md
+      - Stage 3 - Depth: stage_3.md
+      - Stage 4 - Analysis: stage_4.md
+      - Stage 5 - Results: stage_5.md