doc version 0.4

docs/_toc.yml

@@ -12,7 +12,7 @@ parts:
   - file: user_guide/installation
   - file: user_guide/configuration
   - file: user_guide/hardware_support
-  - file: user_guide/external_hw
+  - file: user_guide/GUI
   - file: user_guide/calibration
   - file: user_guide/planar_mode
   - file: user_guide/volume_mode

docs/developer_guide/code_architecture.md

@@ -5,4 +5,10 @@ In a simplified schematic we can see how the `State` file is the core of the pro
 It communicates with GUI and updates values for the GUI to read, it creates and overlooks processes that then are responsible for directly controlling the hardware through custom interfaces.
 Moreover, the State controls the _Global State_ variable of the program which defines the mode in which the program is.  This is used by the GUI to change the interface and settings accordingly and by the different processes to control the hardware.
 
-![Sashimi Structure](../images/sashimi_structure.drawio.png)
+```{figure} ../images/sashmi_struct.png
+---
+height: 500px
+name: sashimi-struct
+---
+Sashimi simplified code structure
+```

docs/hardware/hardware.md

@@ -6,11 +6,23 @@ Sashimi was built for a two-beam digitally-scanning lightsheet microscope used f
 
 ### Top view
 
-![topview](../images/hw_top-Page-2.drawio.png)
+```{figure} ../images/hw_top.png
+---
+height: 500px
+name: sashimi-hw_top
+---
+Sashimi excitation paths
+```
 
 ### Side view
 
-![sideview](../images/hw_top-Page-3.drawio.png)
+```{figure} ../images/hw_side.png
+---
+height: 500px
+name: sashimi-hw_side
+---
+Sashimi excitation path and imaging path
+```
 
 ## Digitally Scanned Lightsheet Microscopy (DLSM)
 
@@ -40,7 +52,6 @@ Therefore, there are 4 galvanometric mirrors, two of which are bigger in size an
 
 ### Laser
 
-
 ````{warning}
  UNDER CONSTRUCTION
  ```
@@ -86,7 +97,6 @@ It is used to control the galvanometric mirrors, the piezo-objective positioner,
 
 ## Parts list
 
-
 ````{warning}
  UNDER CONSTRUCTION
  ```

docs/overview/structure.md

@@ -5,4 +5,10 @@ As shown in the figure below, the GUI is composed of multiple widgets which take
 Each of them communicates with the state to get and send information to the hardware.
 The state communicates with all the subprocesses which in turn control the hardware components through an interface.
 
-![Sashimi Structure](../images/sashimi_structure.drawio.png)
+```{figure} ../images/sashmi_struct.png
+---
+height: 500px
+name: sashimi-struct
+---
+Sashimi simplified code structure
+```

docs/user_guide/external_hw.md → docs/user_guide/GUI.md

@@ -1,4 +1,4 @@
-# external communication
+# GUI
 
 ````{warning}
  UNDER CONSTRUCTION

docs/user_guide/calibration.md

@@ -1,15 +1,51 @@
 # Calibration
 
-````{warning}
- UNDER CONSTRUCTION
- ```
-                                ___
-                        /======/   
-                ____    //      \___
-                | \\  //           
-        |_______|__|_//            
-        _L_____________\o           
-      __(CCCCCCCCCCCCCC)____________
+The calibration mode is divided into two sections, at the top, there are
+three sliders that allow the user to manually set the vertical frontal galvo, the vertical lateral galvo, and
+the piezo. Below there are two buttons to add or remove a calibration point. And at the bottom, there is
+another section for activating the noise subtraction function (see the [fig](sashimi-mode_calib)).
 
+```{figure} ../images/mode_calib.png
+---
+width: 300px
+name: sashimi-mode_calib
+---
+Sashimi calibration mode GUI
+```
+
+The calibration routine works as follows  (see also the [schematic](sashimi-calib-flow)):
+
+- Firstly, you cover one laser beam (either the frontal or lateral).
+- Move the piezo into a position.
+- Adjust the non-covered laser beam with the corresponding vertical galvo slider until the image in the viewer is sharp enough.
+- Cover the other laser and adjust the non-covered laser beam with the corresponding vertical galvo slider until the image in the viewer is sharp enough.
+- Add the calibration point with the button.
+- Repeat for multiple piezo positions.
+
+```{figure} ../images/calib-flow.png
+---
+width: 400px
+name: sashimi-calib-flow
+---
+Sashimi calibration workflow
+```
+
+To choose the piezo position two things are important:
+
+- it is best if the piezo position used for the calibration includes the vertical scanning range that will be set in the volumetric mode
+- the minimum number of calibration points is three, but the more are present the more accurate the calibration
+will be. The software will try to fit a linear function to the points, so the more points the more accurate the
+estimate will be.
+
+The second section of the calibration mode allows the user to activate a noise subtraction filter. Once
+it is activated a pop-up will ask the user to turn off all the lights and the software will take an n number of
+images to compute the average sensor noise. This is then saved and subtracted
+to all the following acquired frames (see the [figure](sashimi-mode_calib_zoom)).
+
+```{figure} ../images/mode_calib_zoom.png
+---
+width: 300px
+name: sashimi-mode_calib_zoom
+---
+Sashimi lower part of the calibration GUI
 ```
-````

docs/user_guide/planar_mode.md

@@ -1,15 +1,14 @@
 # Planar mode
 
-````{warning}
- UNDER CONSTRUCTION
- ```
-                                ___
-                        /======/   
-                ____    //      \___
-                | \\  //           
-        |_______|__|_//            
-        _L_____________\o           
-      __(CCCCCCCCCCCCCC)____________
+The planar mode is quite simple and has only two modifiable inputs (see the [fig](sashimi-mode_planar)):
 
+- A slider to adjust the piezo position (here the galvos will be moved off an amount which is computed using the calibration points).
+- A frequency selector, that allows us to set the frequency at which we desire to acquire images.
+
+```{figure} ../images/mode_planar.png
+---
+height: 400px
+name: sashimi-mode_planar
+---
+Sashimi planar mode GUI
 ```
-````

docs/user_guide/volume_mode.md

@@ -1,15 +1,31 @@
 # Volume mode
 
-````{warning}
- UNDER CONSTRUCTION
- ```
-                                ___
-                        /======/   
-                ____    //      \___
-                | \\  //           
-        |_______|__|_//            
-        _L_____________\o           
-      __(CCCCCCCCCCCCCC)____________
+The volumetric mode (see the [fig](sashimi-mode_vol)) is the core function of the software since it allowsfor fast volume acquisition. It can be divided into two sections, the first one allows for the input of varioussettings, while the second one displays the waveform of the piezo vs lateral galvo with the camera triggers overlaid on top. The setting that can be input into the software are the following:
 
+- A scanning range from ventral to rostral piezo position.
+- A volume rate per second.
+- The number of planes to acquire for each volume.
+- The number of planes to skip at the beginning of each volume.
+- The number of planes to skip at the end of each volume.
+- A button to select whether to pause the live view after the experiment.
+
+```{figure} ../images/mode_vol.png
+---
+width: 350px
+name: sashimi-mode_vol
+---
+Sashimi volume mode GUI
+```
+
+To understand why it may be necessary to drop some planes at the beginning and end of the volume acquisition is important to understand how the volumetric scanner works. During the volumetric scanning the piezo keeps moving following a waveform (see the white line in the [fig](sashimi-mode_vol)), and the galvos follow it based on the calibration. During the acquisition of each frame, the piezo will not be stopping, hence it will keep moving following the waveform. During the constant incline, except for long exposures, the effects of the movement are outweighed by the increased performance.
+However, in some sections of the waveform, this will generate noise and unwanted artifacts which can be avoided by dropping any frame that does not line up with the linear part of the piezo waveform. This can be easily seen in the second section of the volumetric widget, where the waveform and camera frames are plotted.
+
+The camera impulses are also stretched to match the length of   the exposure time, this allows the user to intuitively see      whether there may be overlapping frames when volume rate and exposure time are not matched correctly (see the shaded regions in the [fig](sashimi-mode_vol2)). Moreover, in the status bar, at the bottom of the GUI, the software will automatically print the current frame-rate and highlight it in red if the current frame-rate isn’t high enough. Disregarding these warnings may impair the quality of the experiment.
+
+```{figure} ../images/volum2.png
+---
+width: 250px
+name: sashimi-mode_vol2
+---
+Sashimi frames overlapping
 ```
-````