Skip to content

Start Cylindra

This section describes how to start cylindra, open images and prepare for the analysis.

Launch the GUI

You can launch the GUI application using cylindra command.

cylindra

Note

The cylindra command is enabled only when you are in the virtual environment. For conda users, you can activate with conda activate my-env

After the startup, the napari viewer will be shown with the cylindra widget added on the right side as a dock widget.

Launch programatically

You can use the start function to launch the GUI. The GUI object is returned.

from cylindra import start

ui = start()

napari has a integrate IPython console for running Python code. You can open it with Ctrl+Shift+C. If you launched the napari viewer from cylindra, following variables are pushed to the console global namespace:

  • ui: The currently opened cylindra main GUI object.
  • viewer: The napari viewer object.
  • np: numpy module.
  • ip: impy module.
  • pl: polars module.
  • plt: matplotlib.pyplot module.
  • Path: pathlib.Path class.

Open an Image

API: open_image.

GUI: File > Open image or Ctrl+K → Ctrl+O.

In GUI, an open-image dialog is shown.

open image dialog

In this dialog, you can configure how to open the image. Note that the image opened in the viewer is NOT the original image. cylindra uses a binned and optionally filtered image for visualization.

Important: Use dark background images

Most of the methods require dark-background images, while most of the raw images of electron microscopy are light-background. You have to manually prepare an inverted image file, or check the "Invert intensity" option in the open-image dialog. The loaded image can also be inverted from the menu (see Invert Images).

  1. Click "Select file" to select the image file to open. tiff and mrc files are supported.
  2. Set the appropriate pixel scale. You can click "Scan header" to automatically detect the pixel scale.
  3. Set the tilt range and the tilt axis used for calculating missing wedges.
  4. Set the bin sizes used during your analysis. For example, setting to [2, 4] will start calculation of 2× and 4× binned images, which will be loaded into the memory, and leave the original image in the memory-mapped state (ready to be read in the future). The 4× binned image will be shown in the viewer as a reference. In the later analysis, you can switch between the original, 2× binned and 4× binned images. See Use Multi-scaled Images for more details.
  5. Set the filter to apply to the image. The filter is applied to the reference image shown in the viewer, not to the original image.
  6. If you want to invert the image, check "Invert intensity".
  7. If you want to load the original image into the memory, check "Load the entire image into memory".
  8. You can preview the selected image by clicking "Preview". A preview window will be shown, which only loads separate image slices to accelerate the image loading.
  9. Click "Open" to calculate the binning/filtering and show the reference image.

After opening an image, you'll find three layers added to the viewer:

  • "Drawing Layer": a Points layer used to manually draw splines.
  • "Splines": a Points layer showing the registered splines.
  • <name of the tomogram>: an Image layer showing the reference image.

The "Drawing Layer" will be selected, with the "add points" mode activated by default.

Use Multi-scaled Images

Tomograms can be loaded as multi-scaled images, which means that you can switch between the original and binned images. Many methods in cylindra have a bin_size argument. All the bin sizes registered as multi-scales are available for this argument. Usually, the bin sizes are set using the bin_size argument of the open-image dialog.

(i) Add a new bin size to the multi-scale list after you opened the image

API: add_multiscale.

GUI: File > Add multi-scale

(ii) Choose which multi-scale image to be shown in the viewer

API: set_multiscale.

GUI: File > Set multi-scale

It is useful when you have a low-resolution image (to see the overall state of your sample) and a high-resolution image (to see the detailed structures of the components) as the multi-scale images.

Invert Images

API: invert_image.

GUI: Image > Invert image

Raw images are usually light-background images, but most of the analysis methods require dark-background images. You can invert all the images (original image, multi- scaled images, and the reference image) using this method.

Note

Since the original image is memory-mapped, the inversion will be done when the image is read from the memory. Therefore, it takes a bit longer in the later analysis compared to using an already-inverted image saved separately. They are, however, not that different in most cases, because the inversion is much faster than most of the image processing methods such as cross-correlation calculation and coordinate transformation.

Note that open_image can also run this method by specifying the invert argument.

Filter the Reference Image

API: filter_reference_image.

GUI: Image > Filter reference image

The reference image shown in the viewer can be filtered for better visualization. Currently, following filters are implemented:

  • method="LowPass": low-pass filter
  • method="Gaussian": Gaussian filter
  • method="DoG": Difference of Gaussian (DoG) filter
  • method="LoG": Laplacian of Gaussian (LoG) filter

Note that open_image can also run this method by specifying the filter argument.

Use Custom Reference

API: open_reference_image.

GUI: Image > Open reference image

There are many softwares that implement powerful denoising and deconvolution methods, such as Topaz and cryoCARE. It is a good idea to use these noise-reduced images as the reference image while using the original image for the analysis. In this case, you can load any image as the reference using open_reference_image.