update docs

cylindra/widgets/subwidgets/menus.py

@@ -692,7 +692,7 @@ class Radius(ChildWidget):
     load_project_for_reanalysis = abstractapi()
     sep2 = field(Separator)
 
-    @set_design(text="Open spectra inspector")
+    @set_design(text=capitalize)
     @do_not_record
     def open_spectra_inspector(self):
         """Open the spectra measurer widget to determine cylindric parameters."""

cylindra/widgets/subwidgets/runner.py

@@ -47,13 +47,10 @@ class runner_params2:
     depth: nm
         Longitudinal length of local discrete Fourier transformation used
         for structural analysis.
-    paint : bool
-        Check if paint the tomogram with the local properties.
     """
 
     interval = vfield(50.0, label="Interval (nm)").with_options(min=1.0, max=200.0)
     depth = vfield(50.0, label="FT window size (nm)").with_options(min=1.0, max=200.0)
-    paint = vfield(False)
 
 
 @magicclass(name="_Run cylindrical fitting", record=False)
@@ -138,7 +135,6 @@ def run(
         interval: Annotated[nm, {"bind": params2.interval}] = 50.0,
         depth: Annotated[nm, {"bind": params2.depth}] = 50.0,
         global_props: Annotated[bool, {"bind": global_props}] = True,
-        paint: Annotated[bool, {"bind": params2.paint}] = False,
         infer_polarity: Annotated[bool, {"bind": infer_polarity}] = True,
         map_monomers: Annotated[bool, {"bind": map_monomers}] = False,
     ):

cylindra/widgets/subwidgets/spline_clipper.py

@@ -1,11 +1,13 @@
 from typing import Annotated
-from magicclass import magicclass, field, vfield, do_not_record
+from magicclass import magicclass, field, set_design, vfield, do_not_record
 from magicclass.ext.pyqtgraph import QtMultiImageCanvas
 from cylindra.components import CylSpline
 from cylindra.const import Mode, nm
 from cylindra.utils import map_coordinates
 import numpy as np
 import impy as ip
+
+from cylindra.widget_utils import capitalize
 from ._child_widget import ChildWidget
 
 
@@ -68,7 +70,9 @@ def current_clip_length(self) -> tuple[nm, nm]:
         return (clim0 - lim0) * length, (lim1 - clim1) * length
 
     @do_not_record
+    @set_design(text=capitalize)
     def load_spline(self, spline: Annotated[int, {"bind": _get_spline_id}]):
+        """Load the current spline selected in the main widget."""
         parent = self._get_main()
         spl = parent.tomogram.splines[spline]
         self._spline = self._original_spline = spl
@@ -77,13 +81,17 @@ def load_spline(self, spline: Annotated[int, {"bind": _get_spline_id}]):
         self._update_canvas()
 
     @do_not_record
+    @set_design(text=capitalize)
     def the_other_side(self):
+        """See the other side of the spline."""
         self._clip_at_start = not self._clip_at_start
         self.clip_length = self.current_clip_length[1 - int(self._clip_at_start)]
         self._update_canvas()
 
     @do_not_record(recursive=False)
+    @set_design(text=capitalize)
     def clip_here(self):
+        """Clip the spline at the current position."""
         parent = self._get_main()
         try:
             idx = parent.tomogram.splines.index(self._original_spline)

docs/basics.md

@@ -77,3 +77,12 @@ combine many softwares together. Currently, `cylindra` provides functions to rea
 supported, please open an issue or submit a pull request to the [repository](https://github.com/hanjinliu/cylindra).
 
 Next step: [Start `cylindra`](open_image.md)
+
+## Configure Global Variables
+
+:material-arrow-right-thin-circle-outline: GUI: `Others > Configure cylindra`
+
+![Configure cylindra](images/configure_cylindra.png)
+
+Parameters in this dialog will be used across different sessions, but does not affect
+the calculation results.

docs/fit_splines.md

@@ -18,21 +18,26 @@ the points with a spline.
 
 ![draw_splines](images/draw_splines.gif){ loading=lazy, width=400px }
 
+To delete the last spline, click ![](images/toolbutton_clear_current.png){ width=28px }.
+
 !!! note
 
     You can view the image from the different direction using the `napari` [viewer
     buttons](https://napari.org/stable/tutorials/fundamentals/viewer.html#viewer-buttons).
 
 ??? info "Auto-picking tool"
 
-    The `cylindra` toolbar has an auto-picking tool. If you placed >1 points, you can
-    extend it with a fast auto-centering function (![](images/toolbutton_pick_next.png){ width=28px } or ++f3++).
+    The `cylindra` toolbar has an auto-picking tool. If you have placed two or more
+    points, you can extend it with a fast auto-centering function (![](images/toolbutton_pick_next.png){ width=28px } or ++f3++).
+
+    In the future version, other auto-picking tools (AI-powered, fully automated, etc)
+    may be added.
 
 ??? info "Configure splines"
 
     Each spline is tagged with a `SplineConfig` object, which describes the average
     feature of the cylindric structure it represents. Default values are optimized for
-    microtubules. If you want to analyze other structures, see [here](configure.md).
+    microtubules. If you want to analyze other structures, see [here](spline/config.md).
 
 ## Fit Automatically
 

docs/index.md

@@ -15,8 +15,11 @@ Cylindra is a Python module for image analysis of cylindric structures cryo-ET.
 - [Measure lattice parameters](lattice_params.md)
 - [Load & Save Projects](project_io.md)
 - [Custom Workflows](workflows.md)
+- [Spline](spline/index.md)
+- [Molecules](molecules/index.md)
 - [Subtomogram Alignment](alignment/index.md)
 - [Tomogram Simulation](simulate.md)
+- [Microtubule Seam Search](seam_search.md)
 
 
 ### Major Dependencies

docs/project_io.md

@@ -12,7 +12,7 @@ If you want to save the current session as a project, you can use this method to
 the current state.
 
 - `project.json` ... The main project file, which has the description of this project.
-- `default_spline_config.json` ... The default `SplineConfig`. See [here](configure.md)
+- `default_spline_config.json` ... The default `SplineConfig`. See [here](spline/config.md)
   for the details.
 - `globalprops.csv` ... The global properties of the splines.
 - `localprops.csv` ... The local properties of the splines.

docs/scripts/_screenshots.py

@@ -65,6 +65,8 @@ def main():
         ui.measure_local_radius,
         ui.local_cft_analysis,
         ui.global_cft_analysis,
+        # spline
+        ui.clip_spline,
         # spline -> molecules
         ui.map_monomers,
         ui.map_centers,
@@ -74,6 +76,9 @@ def main():
         ui.paint_molecules,
         ui.split_molecules,
         ui.concatenate_molecules,
+        # others
+        ui.SplinesMenu.Config.update_default_config,
+        ui.OthersMenu.configure_cylindra,
     ]:
         get_button(meth).changed.emit()
         gui = get_function_gui(meth)
@@ -140,7 +145,12 @@ def _workflow_gui(path: Path, tilt_range: tuple[float, float] = (-60, 60)):
     _imsave(ui.SplineControl.native, "spline_control")
     # Local props
     _imsave(ui.LocalProperties.native, "local_props_gui")
-
+    # Clipper
+    ui.SplinesMenu.open_spline_clipper()
+    _imsave(ui.spline_clipper.native, "spline_clipper")
+    # Spectra inspector
+    ui.AnalysisMenu.open_spectra_inspector()
+    _imsave(ui.spectra_inspector.native, "spectra_inspector")
     QtW.QApplication.processEvents()
 
 

docs/spline/clip.md

@@ -0,0 +1,47 @@
+# Clip and Invert Splines
+
+The "clip" operation of a spline is **not** removing the points defining the spline.
+Instead, it is equivalent to defining a linear transformation on the spline coordinate
+$u$ as follows:
+
+$\boldsymbol{C}_{clipped}(u) = \boldsymbol{C}(\alpha _{0} (1 - u) + \alpha _{1} u)$
+
+$\boldsymbol{C}_{clipped}(0) = \boldsymbol{C}(\alpha _{0})$ and
+$\boldsymbol{C}_{clipped}(1) = \boldsymbol{C}(\alpha _{1})$ indicate that the new spline
+is defined by the $\alpha _{0} \le u \le \alpha _{1}$ region of the original spline.
+
+As it is simply a linear transformation, spline inversion can also be defined the same
+way:
+
+$\boldsymbol{C}_{inv}(u) = \boldsymbol{C}(1 - u)$
+
+## Clip by Length
+
+:material-arrow-right-thin-circle-outline: API: [`clip_spline`][cylindra.widgets.main.CylindraMainWidget.clip_spline]
+
+:material-arrow-right-thin-circle-outline: GUI: `Splines > Clip spline` or ++ctrl+k++ → ++ctrl+x++
+
+This method clips the selected spline at both ends by the given lengths. Local
+properties of the clipped spline will be discarded, while global properties will not.
+
+![clip_spline](../images/clip_spline.png)
+
+## Spline Clipper
+
+:material-arrow-right-thin-circle-outline: GUI: `Splines > Open spline clipper`
+
+![Spline Clipper](../images/spline_clipper.png)
+
+For precise clipping, you can use the spline clipper widget. This widget synchronizes
+the clipping lengths and the projections of the spline edges. "Clip here" will call
+[`clip_spline`][cylindra.widgets.main.CylindraMainWidget.clip_spline] internally.
+
+
+## Invert Splines
+
+:material-arrow-right-thin-circle-outline: API: [`invert_spline`][cylindra.widgets.main.CylindraMainWidget.invert_spline]
+
+:material-arrow-right-thin-circle-outline: GUI: `Splines > Orientation > Invert spline`
+
+This method inverts the selected spline. This operation does not discard the local
+properties. They will be inverted as well.

docs/spline/config.md

@@ -0,0 +1,93 @@
+# Spline Configurations
+
+A spline is tagged with a [SplineConfig][cylindra.components.SplineConfig] object. This
+object is practically used to annotate the spline with structural features. For example,
+if a spline represent a microtubule, it is tagged with a `SplineConfig` object with
+parameters appropriate for microtubules. These parameters are used in spline fitting,
+CFT analysis, and so on.
+
+Every time a new spline is created, it is initialized with the default `SplineConfig`.
+Make sure the correct configuration is used before adding splines.
+
+## List of Parameters
+
+- Parameters used during CFT analysis
+  - `npf_range` ... an (`int`, `int`) tuple indicating the minimum/maximum of the
+    number of protofilaments.
+  - `spacing_range` ... an (`float`, `float`) tuple indicating the minimum/maximum of
+    longitudinal spacing between monomers (in nanometer).
+  - `twist_range` ... an (`float`, `float`) tuple indicating the minimum/maximum of
+    twist angle (in degree).
+  - `rise_range` ... an (`float`, `float`) tuple indicating the minimum/maximum of
+    rise angle (in degree).
+  - `rise_sign` ... the sign of the rise angle. This parameter is redundant for the
+    mathematically. It was introduced only to make the rise angle and the start number positive, like "13_3" instead of "13_-3".
+
+- Other parameters
+  - `clockwise` ... `"PlusToMinus"` or `"MinusToPlus"`. This parameter is used for
+    automatic polarity determination. If the cross-sectional view of the cylindric
+    structure in the plus-to-minus orientation has clockwise chirality, set this
+    parameter to `"PlusToMinus"`.
+  - `thickness_inner` ... distance between the inner surface and the peak of the radial
+    profileradius (in nanometer). This parameter is used for construction of cylindric
+    coordinate system.
+  - `thickness_inner` ... distance between the outer surface and the peak of the radial
+    profileradius (in nanometer). This parameter is used for construction of cylindric
+    coordinate system.
+  - `fit_depth` ... the depth of sub-volumes used for spline fitting region (in
+    nanometer).
+  - `fit_width` ... the width of sub-volumes used for spline fitting region (in
+    nanometer).
+
+## Change the Default Configuration
+
+The configuration is optimized for microtubules by default. To analyze other structures,
+you need to change the default configuration.
+
+The default configuration is stored in the `default_config` property.
+
+``` python
+ui.default_config
+```
+
+``` title="Output"
+SplineConfig(
+	npf_range=Range(min=11, max=17),
+	spacing_range=Range(min=3.9, max=4.3),
+	twist_range=Range(min=-0.65, max=0.65),
+	rise_range=Range(min=5.0, max=13.0),
+	rise_sign=-1,
+	clockwise='MinusToPlus',
+	thickness_inner=2.8,
+	thickness_outer=2.8,
+	fit_depth=49.0,
+	fit_width=40.0
+)
+```
+
+### Manually set the parameters
+
+:material-arrow-right-thin-circle-outline: GUI: `Splines > Config > Update default config`
+
+![update_default_config](../images/update_default_config.png)
+
+### Measuring the approximate parameters of unknown structures
+
+:material-arrow-right-thin-circle-outline: GUI: `Analysis > Open spectra inspector`
+
+![spectra_inspector](../images/spectra_inspector.png)
+
+This widget is used to measure lattice parameters by clicking the peak positions on the
+power spectrum.
+
+### Load presets
+
+:material-arrow-right-thin-circle-outline: GUI: `Splines > Config > Load default config`
+
+Presets are stored in the user directory. You can load the presets from the menu.
+
+## Save the Configuration
+
+:material-arrow-right-thin-circle-outline: GUI: `Splines > Config > Save default config`
+
+You can save current default configuration as a preset with arbitrary name.

docs/spline/index.md

@@ -0,0 +1,12 @@
+# Spline
+
+A 3D spline is a mapping from a 1D parameter to 3D points $(z, y, x)$:
+
+$$
+\boldsymbol{C}(u) \in \mathbb{R}^3 \quad (0\le u \le 1)
+$$
+
+In `cylindra`, several useful methods are provided to make the most of splines.
+
+- [Clip and Invert Splines](clip.md)
+- [Spline Configurations](config.md)

mkdocs.yml

@@ -40,6 +40,10 @@ nav:
     - lattice_params.md
     - project_io.md
     - workflows.md
+    - Spline:
+      - Overview: spline/index.md
+      - spline/clip.md
+      - spline/config.md
     - Molecules:
       - Overview: molecules/index.md
       - molecules/spline_to_molecules.md
@@ -53,7 +57,6 @@ nav:
       - alignment/landscape.md
       - alignment/viterbi.md
       - alignment/rma.md
-    - configure.md
     - simulate.md
     - seam_search.md
     - cli.md