.. Doppio Tomography Tutorial documentation master file, created by
   sphinx-quickstart on Tue Feb 18 13:09:38 2025.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Picking in tomograms
=======================

Doppio supports the Napari picker implemented in RELION. This picker
has individual particle picking, sphere annotation and filament picking modes.
Since Napari is graphics intensive and does not scale for port forwarding, we
strongly recommend to use Napari picker locally than remotely. 

How to run Napari picker locally?
----------------------------------
For this, you'll need to install the Napari picker in your local system (aka laptop).
As far as our experience goes, local installation of RELON will bring all the
necessary tools into your local system. 

Local installation of Napari
-----------------------------
We'll install Napari in a new conda environmenet in the local system.

.. code-block:: bash

   git clone https://github.com/3dem/relion.git  # Clone RELION repository
   git checkout ver5.0                           # Checkout to ver5.0 branch

   conda create -n relion-picker python=3.10     # Create relion-picker conda env
   conda activate relion-picker                  # activate the conda env

   pip install '.[.vis]'                         # Install python modules listed in pyproject.toml
                                                 # including Napari components
   conda deactivate
   conda activate relion-picker

Running Napari locally
-----------------------
Navigate to the project folder where you have copied the ``Tomograms`` folder. Then

.. code-block:: bash

   mkdir -p Picks/job007                         # Make Picks/job007 dir for picking
   relion_tomo_pick spheres --tilt-series-star-file Tomograms/job006/tomograms.star --output-directory Picks/job007

This will open Napari picker in your local system. Do the sphare annotation as explained
in the Relion tutorial [link below]. Once you've annotated all the spheres in one tomograms
click ``Save spheres`` button on the lower left and move on to next tomograms. At the end
of annotation of all tomograms, close Napari-picker window. If everything is successful 
you'll see ``TS_01_spheres.star TS_03_spheres.star`` files in the ``Picks/job007/annotations`` folder.

Once you have annotations, the next step is to do the sampling on the spheres to generate particle coordinates.
To do that, 

.. code-block:: bash

   mkdir -p Picks/job008                         # Make Picks/job008 dir for particles
   relion_tomo_get_particle_poses spheres --tilt-series-star-file Tomograms/job006/tomograms.star --annotations-directory Picks/job007/annotations --output-directory Picks/job008/ --spacing-angstroms 60

This will generate and write out particles into ``Picks/job008/particles.star``.
This is the ``particle.star`` file you'll use for next steps.

In this exaple, we use sphere annotation of the locally installed Napari-picker, but you'll
be able to use its other picking modes as explained in the Relion tutorial below:

`Relion Particle Picking job documentation <https://relion.readthedocs.io/en/release-5.0/STA_tutorial/ParticlePicking.html>`_.

EulerMate Particle Picking
----------------------------
TODO