Merge branch 'main' of github.com:cellcanvas/surforama

docs/contributing.md

@@ -0,0 +1,14 @@
+# Contributing to Surforama
+## developer installation
+
+If you would like to make changes to the surforama source code, you can install surformama with the developer tools as follows:
+
+```bash
+cd /path/to/your/surforama/source/code/folder
+pip install -e ".[dev]"
+```
+We use pre-commit to keep the code tidy. Install the pre-commit hooks to activate the checks:
+
+```bash
+pre-commit install
+```

docs/getting_started.md

@@ -0,0 +1,29 @@
+# Getting started with surforama
+
+This short tutorial explains how to annotate particles on your first membrane with `Surforama`. If you haven't already installed `Surforama`, please see our [installation instructions](installation.md). First, open your terminal and activate the Python environment with `Surforma` installed. Then launch `Surforama` with the included sample data with the following command
+
+```bash
+surforama --demo
+```
+
+This will launch the napari viewer with the Surforama plugins and sample data open. Note that the first time you launch napari may take a bit of extra time. The sample data is a tomogram and of a Chal chloroplast and a mesh of a segment of membrane. In this demo, we will annotate the photosystem II densities on the surface of this membrane. The tomogram is loaded as an image layer and the mesh of the membrane surface is loaded as a surface layer.
+
+![Surforama opened](./resources/getting_started/open_surforama.png){ align=center }
+
+The tomogram is rendered as a 2D slice. You can move the position of the slice being rendered by first selecting the image layer (named "tomogram") from the layer list and then holding the "shift" key while clicking and dragging on the plane with your left mouse button. You can rotate the view by clicking and dragging in the canvas and zoom by using the scroll wheel on your mouse.
+
+![Tomogram selection](./resources/getting_started/move_render_plane.png){ align=center }
+
+![type:video](https://github.com/user-attachments/assets/d42aa634-6e21-4f62-888a-390617393690)
+
+We can now initialize the picking mode that will allow you to annotate particle locations and orientations on the membrane. First, select the mesh layer from the layer list (named "mesh_data"). Then click the "start picking" button.
+
+![Start annotating](./resources/getting_started/start_picking.png)
+
+With the picking mode activated, we can now annotate particles on the membrane surface. We can select the centroid of a particle by clicking on it. This will place the particle. We can then set the orientation by adjusting the orientation slider underneath the "enable/disable" picking button (denoted in the screenshot above). The orientation of the particle is indicated by orange arrow point away from the centroid marker.
+
+![type:video](https://github.com/user-attachments/assets/8e5ad177-d9af-4c7b-9524-42f0f3f8389d)
+
+Finally, you can output your annotated particles as a Relion-formatted Star file. To do so, enter the file path in the "Save" table of the "Save points" widget and click the "Save to star file" button.
+
+![Save points](./resources/getting_started/save_points.png){ align=center }

docs/index.md

@@ -1,57 +1,12 @@
-# surforama
-a napari-based tool for using surfaces to explore volumetric data in napari
+# Surforama
+a napari-based tool for using surfaces to explore volumetric data. Using `Surforama` you can visualize densities on a membrane surface, annotate particle locations and orientations, and analyze the picked particles.
 
 inspired by [membranorama](https://github.com/dtegunov/membranorama)
 
 ![Screenshot of surforama showing a surface in the slice of a tomogram](./surforama_screenshot.png)
 
 ## installation
-`surforama` requires the napari viewer. If you would like to install napari and surforama together in one line, you can use the following command:
+To install `Surforama`, see our installation guides for [users](installation.md) and [developers](contributing.md).
 
-```bash
-pip install "surforama[napari]"
-```
-
-
-If you already have napari installed, you can directly install surforama in the same environment:
-
-```bash
-pip install surforama
-```
-
-## usage
-### launch with demo data
-If you'd like to test surforama out, you can launch surforama with demo data:
-
-```bash
-surforama --demo
-```
-
-### launch without data
-You can launch surforama using the command line interface. After you have installed surforama, you can launch it with the following command in your terminal:
-
-```bash
-surforama
-```
-After surforama launches, you can load your image and mesh into napari and get surfing!
-
-### launch with data
-If you have an MRC-formatted tomogram and an obj-formatted mesh, you can launch using the following command:
-
-```bash
-surforama --image-path /path/to/image.mrc --mesh-path /path/to/mesh.obj
-```
-
-## developer installation
-
-If you would like to make changes to the surforama source code, you can install surformama with the developer tools as follows:
-
-```bash
-cd /path/to/your/surforama/source/code/folder
-pip install -e ".[dev]"
-```
-We use pre-commit to keep the code tidy. Install the pre-commit hooks to activate the checks:
-
-```bash
-pre-commit install
-```
+## getting started
+If you would like to give `Surforama` a try, check out our [Getting Started](getting_started.md) tutorial.

docs/installation.md

@@ -0,0 +1,20 @@
+# Installing surforama
+
+`Surforama` is a python package that can be installed via PyPI. If you are just getting started, we recommend installing Surforama via an environment manager such as `venv` or `mamba`. We recommend Python 3.9 or greater. Once you have set up your Python environment, you can install `Surforama` with the following commands.
+
+`surforama` requires the napari viewer. If you would like to install napari and surforama together in one line, you can use the following command:
+
+```bash
+pip install "surforama[napari]"
+```
+
+If you already have napari installed, you can directly install surforama in the same environment:
+
+```bash
+pip install surforama
+```
+
+After installation completes, you can test the installation using our [Getting Started](getting_started.md) tutorial. If you have questions you can post on the CellCanvas stream of the [image.sc zulip chat](http://imagesc.zulipchat.com/).
+
+## Developer installation
+If you would like to contribute to `Surforama`, please see our [Contributing Guide](contributing.md).

mkdocs.yml

@@ -83,7 +83,10 @@ extra:
 
 nav:
   - 'Overview': index.md
+  - 'Getting started': getting_started.md
+  - 'Installation': installation.md
   - 'CZ cryoET Data Portal': surforama_for_data_portal.md
+  - 'Contributing': contributing.md
 
 plugins:
   - search

src/surforama/gui/qt_point_io.py

@@ -68,7 +68,8 @@ def _load_star_file(self, file_path: Path):
         )
 
         # add the data to the viewer
-        self.surface_picker.points_layer.data = point_coordinates
+        with self.surface_picker.points_layer.events.data.blocker():
+            self.surface_picker.points_layer.data = point_coordinates
         self.surface_picker.points_layer.features = features_table
 
         self.surface_picker.normal_vectors_layer.data = normal_data