TomoStream

Content

About

tomostream is Python module for supporting streaming analysis of tomographic data where all pre-processing and reconstruction procedures are performed in real time while images are collected and the rotary stage is moving. tomostream provides this main functionality:

• Streaming reconstruction of 3 X-Y-Z ortho-slices through the sample

  The streaming reconstruction engine generates 3 selectable X-Y-Z orthogonal planes and makes them available as an EPICS PV viewable in ImageJ using the EPICS_NTNDA_Viewer plug-in. Projection, dark and flat images used for the reconstruction are taken in real time from a set of PV access variables (pvapy) and stored in a synchronized queue. On each reconstruction call new data are taken from the queue, copied to a circular GPU buffer containing projections for a 180 degrees interval, and then reconstructed.

All tomostream functionalies can be controlled from the tomoStream user interface:

tomostream relies on tomoscan_stream_2bm (part of tomoScan) for:

• Tomography instrument control

• Projection, dark and flat image broadcast as PV access variables

• On-demand retake of dark-flat field images

• On-demand data capturing with saving in a standard hdf5 DXfile file

• Set a number of projectons (“Pre count”) collected before a triggered data capturing event to be also saved in the same hdf5 file

All tomoscan_stream_2bm functionalies supporting tomostream can be controlled from the tomoScanStream user interface marked in yellow:

The output of tomostream is a live reconstruction diplaying in ImageJ using the EPICS_NTNDA_Viewer plug-in:

While the sample is rotating is possible to optimize instrument (alignment, focus, sample to detector distance etc.) and beamline (energy etc.) conditions and monitor the effect live on the 3 orthogonal slices. It is also possible to automatically trigger data capturing based on events occurring in the sample and its environment as a result of segmentation or machine learning.

Install directions

The computer performing the tomographic reconstruction must have CUDA/GPU installed. tomostream consists of two modules TomoScanApp and tomostream tools.

TomoScanApp

Provides all the EPICS PVs needed by tomostream. To install TomoScanApp follow these steps:

Build a minimal synApps

To build a minimal synApp:

$ mkdir ~/epics
$ cd epics

• Download in ~/epics assemble_synApps.sh

• Edit the assemble_synApps.sh script as follows:

  • Set FULL_CLONE=True

  • Set EPICS_BASE to point to the location of EPICS base. This could be on APSshare (the default), or a local version you built.

  • For tomostream you only need BUSY and AUTOSAVE. You can comment out all of the other modules (ALLENBRADLEY, ALIVE, etc.)

• Run:

  $ assemble_synApps.sh
  

• This will create a synApps/ directory:

  $ cd synApps/support/
  

• Edit busy-R1-7-2/configure/RELEASE to comment out this line:

  ASYN=$(SUPPORT)/asyn-4-32).
  

• Clone the tomostream module into synApps/support:

  $ git clone https://github.com/tomography/tomostream.git
  

• Edit tomostream/configure/RELEASE to comment out this line:

  ASYN=$(SUPPORT)/asyn-4-38
  

• Edit tomostream/tomoStreamApp/src/Makefile to comment out this line:

  tomoStreamApp_LIBS += asyn
  

• Edit configure/RELEASE add this line to the end:

  TOMOSTREAM=$(SUPPORT)/tomostream
  

• Edit Makefile add this line to the end of the MODULE_LIST:

  MODULE_LIST += TOMOSTREAM
  

• Run the following commands:

  $ make release
  $ make -sj
  

Testing the installation

• Edit /epics/synApps/support/tomostream/configure

  • Set EPICS_BASE to point to the location of EPICS base:

  • EPICS_BASE=/APSshare/epics/base-3.15.6

• Start the epics ioc and associated medm screen with:

  $ cd ~/epics/synApps/support/tomostream/iocBoot/iocTomoStream
  $ start_IOC
  $ start_medm
  

tomostream python tools

$ cd ~/epics/synApps/support/tomostream/
$ python setup.py install

Testing the installation

$ cd ~/epics/synApps/support/tomostream/iocBoot/iocTomoStream
$ python -i start_tomostream.py

Usage

Using the tomoStream

Pre-requisites

Before running tomostream you need to install and run tomoscan_stream_2bm (see tomoScan for details) to provide:

• Tomography instrument control

• Projection, dark and flat image broadcast as PV access variables

• On-demand retake of dark-flat field images

• On-demand data capturing

Once tomoScan is installed on the computer connected to the detector:

• start area detector, e.g.:

  user2bmb@lyra$  2bmbPG1 start
  

• start tomoScan IOC, e.g.:

  user2bmb@lyra$  cd /local/user2bmb/epics/synApps/support/tomoscan/iocBoot/iocTomoScan_2BM/
  user2bmb@lyra$  ./start_IOC
  

• start the instance of tomoscan.py supporting tomostream tasks at your beamline, e.g.:

  user2bmb@lyra$  cd /local/user2bmb/epics/synApps/support/tomoscan/iocBoot/iocTomoScan_2BM/
  user2bmb@lyra$  python -i start_tomoscan_stream.py
  

• start tomoScan user interface, e.g.:

  user2bmb@lyra$  cd /local/tomo/epics/synApps/support/tomostream/iocBoot/iocTomoStream/
  user2bmb@lyra$  ./start_medm
  

All tomoscan_stream_2bm functionalies supporting tomostream can be controlled from the tomoScanStream user interface marked in yellow.

Run tomoStream

• start tomoStream IOC, e.g.:

  tomo@handyn$  cd /local/tomo/epics/synApps/support/tomostream/iocBoot/iocTomoStream/
  tomo@handyn$  ./start_IOC
  

• start the tomostream.py supporting streaming reconstruction, e.g.:

  tomo@handyn$ cd /local/tomo/epics/synApps/support/tomostream/iocBoot/iocTomoStream/
  tomo@handyn$ python -i start_tomostream.py
  

• start tomoStream user interface, e.g.:

  tomo@handyn$ cd /local/tomo/epics/synApps/support/tomostream/iocBoot/iocTomoStream/
  tomo@handyn$ ./start_medm
  

Open the EPICS PV names configuration screen:

to set the TomoScan prefix and the PVAccess names provided by tomoScan for projection (Image), dark and flat image broadcast. Here also set the Recon PVAccess name where the streaming reconstruction will served. Use the Recon PVAccess name to view the live reconstriction using the EPICS_NTNDA_Viewer ImageJ plug-in:

Finally press “Start Scan” in the tomoScan control screen and reconstructions will diplay live in ImageJ:

tomoStreamApp EPICS application

tomostream includes a complete example EPICS application, including:

• A database file and corresponding autosave request file that contain only the PVs required by the tomoscan.py base class.

• Database files and corresponding autosave request files that contain PVs used by the derived classes.

• An example IOC application that can be used to run the above databases. The databases are loaded in the IOC with the example substitutions file, tomoStream.substitutions.

Base class files

The following tables list all of the records in the tomoScan.template file. These records are used by the tomoscan base class and so are required.

tomoStream.template

This is the database file that contains only the PVs required by the tomoscan.py base class tomoStream.template.

tomoStream PV Prefixes

Record name	Record type	Description
$(P)$(R)TomoScanPVPrefix	stringout	Contains the prefix for the tomoscan controlling the data collection, e.g. 2bma:TomoScan

tomoStream PVA Names

Record name	Record type	Description
$(P)$(R)ImagePVAPName	stringout	Contains the name of the TomoScan PV storing the PV prefix of the images streamed by the detector
$(P)$(R)DarkPVAName	stringout	Contains the name of the TomoScan PVA where the dark images are stored
$(P)$(R)FlatPVAName	stringout	Contains the name of the TomoScan PVA where the flat images are stored
$(P)$(R)ThetaPVAName	stringout	Contains the name of the TomoScan PVA where the rotation angle positions are stored
$(P)$(R)ReconPVAName	stringout	Contains the name of the TomoStream PVA where the the selected 3 orthogonal slices are stored

Streaming analysis control

Record name	Record type	Description
$(P)$(R)CameraPVPrefix	stringout	Contains the prefix for the camera, e.g. 13BMDPG1:
$(P)$(R)Status	bo	Flag storing the streaming status. Choices are ‘Off’ and ‘On’. When ‘On’ the streaming reconstruction is enabled
$(P)$(R)BufferSize	longout	Stream buffer size
$(P)$(R)Center	ao	Rotation center for streaming reconstruction
$(P)$(R)FilterType	mbbo	Filter type for streaming reconstruction, ‘Parzen’, ‘Shepp-logan’, ‘Ramp’, ‘Butterworth’
$(P)$(R)OrthoX	longout	Ortho slice in the X direction for streaming reconstruction
$(P)$(R)OrthoY	longout	Ortho slice in the Y direction for streaming reconstruction
$(P)$(R)OrthoZ	longout	Ortho slice in the Z direction for streaming reconstruction

Stream status via Channel Access

Record name	Record type	Description
$(P)$(R)ReconStatus	waveform	This record will be updated with the stream reconstruction status while scanning.
$(P)$(R)ReconTime	ao	This record will update with the time to reconstruct the selected 3 orthogonal slices.
$(P)$(R)ServerRunning	bi	This record will be Running if the Python server is running and Stopped if not. It is controlled by a watchdog timer, and will change from Running to Stopped within 5 seconds if the Python server exits.

tomoStream_settings.req

This is the autosave request file for tomoStream.template tomoStream_settings.req.

It has the same usage and type of content as tomoStream_settings.req described above, except that it contains the PVs for the derived class TomoStream.

medm files

To start the tomostream medm screen:

$ cd /local/USERNAME/epics/synApps/support/tomostream/iocBoot/iocTomoStream
$ start_medm

where USERNAME is the username under which the tomoStreamApp is installed.

tomoStream.adl

The following is the MEDM screen tomoStream.adl. This screen contains the PVs to control tomoStream.

tomoStreamEPICS_PVs.adl

The EPICS PV names screen is below:

API reference

tomostream Modules:

tomostream.kernels

tomostream.tomostream

tomostream.solver

Credits

Citations

A1

Viktor Nikitin, Aniket Tekawade, Anton Duchkov, Pavel Shevchenko, and Francesco De Carlo. Real-time streaming tomographic reconstruction with on-demand data capturing and 3D zooming to regions of interest. Journal of Synchrotron Radiation, 29(3):, May 2022. URL: https://doi.org/10.1107/S1600577522003095, doi:10.1107/S1600577522003095.

References

B1

Viktor Nikitin. Tomocupy: efficient gpu-based tomographic reconstruction with conveyor data processing. 2022. URL: https://arxiv.org/abs/2209.08450, doi:10.48550/ARXIV.2209.08450.