Scanner.h

Go to the documentation of this file.

/*
    Copyright (C) 2000 PARAPET partners
    Copyright (C) 2000-2010, Hammersmith Imanet Ltd
    Copyright (C) 2011-2013, King's College London
    Copyright (C) 2016, University of Hull
    Copyright (C) 2016, 2019, 2021, 2023 UCL
    Copyright 2017 ETH Zurich, Institute of Particle Physics and Astrophysics
    Copyright (C 2017-2018, University of Leeds
    This file is part of STIR.

    SPDX-License-Identifier: Apache-2.0 AND License-ref-PARAPET-license

    See STIR/LICENSE.txt for details
*/

#ifndef __stir_buildblock_SCANNER_H__
#define __stir_buildblock_SCANNER_H__

#include "stir/DetectionPosition.h"
#include "stir/CartesianCoordinate3D.h"
#include "stir/DetectorCoordinateMap.h"
#include "stir/shared_ptr.h"
#include <string>
#include <list>
#include <vector>
#include <cmath>
#include <algorithm>
#include <fstream>
#include <boost/algorithm/string.hpp>
#include <boost/unordered_map.hpp>

START_NAMESPACE_STIR

class Succeeded;
class Scanner
{
  friend class BlocksTests;

public:
  /************* static members*****************************/
  static Scanner* ask_parameters();

  static Scanner* get_scanner_from_name(const std::string& name);
  /* \return a string with one line per predefined scanner, listing the predefined names for
     that scanner (separated by a comma)
  */
  static std::string list_all_names();
  /* \return a list of strings, each element is a name of a predefined scanner.
     If a scanner can have multiple names, only one name is returned, i.e.
     the list has the same length as the number of predefined scanners.
  */
  static std::list<std::string> get_names_of_predefined_scanners();

  // E931 HAS to be first, Unknown_scanner HAS to be last
  // also, the list HAS to be consecutive (so DO NOT assign numbers here)
  // finally, test_Scanner assumes E966 is the last in the list of CTI scanners
  // supported by ecat_model from the LLN matrix library
  // 08-3-2004, zlong, add user defined scanner
  /* \a Userdefined_scanner can be used to set arbitrary scanner geometry info.
     \a Unknown_scanner will be used when parsing (e.g. from an Interfile header)
     to flag up an error and do some guess work in trying to recognise the scanner from
     any given parameters.
  */
  enum Type
  {
    E931,
    E951,
    E953,
    E921,
    E925,
    E961,
    E962,
    E966,
    E1080,
    test_scanner,
    Siemens_mMR,
    Siemens_mCT,
    Siemens_Vision_600,
    RPT,
    HiDAC,
    Advance,
    DiscoveryLS,
    DiscoveryST,
    DiscoverySTE,
    DiscoveryRX,
    Discovery600,
    PETMR_Signa,
    Discovery690,
    DiscoveryMI3ring,
    DiscoveryMI4ring,
    DiscoveryMI5ring,
    HZLR,
    RATPET,
    PANDA,
    HYPERimage,
    nanoPET,
    HRRT,
    Allegro,
    GeminiTF,
    SAFIRDualRingPrototype,
    UPENN_5rings,
    UPENN_5rings_no_gaps,
    UPENN_6rings,
    UPENN_6rings_no_gaps,
    User_defined_scanner,
    Unknown_scanner
  };

  virtual ~Scanner() {}

  Scanner(Type scanner_type);


  Scanner(Type type_v,
          const std::list<std::string>& list_of_names_v,
          int num_detectors_per_ring_v,
          int num_rings_v,
          int max_num_non_arccorrected_bins_v,
          int default_num_arccorrected_bins_v,
          float inner_ring_radius_v,
          float average_depth_of_interaction_v,
          float ring_spacing_v,
          float bin_size_v,
          float intrinsic_tilt_v,
          int num_axial_blocks_per_bucket_v,
          int num_transaxial_blocks_per_bucket_v,
          int num_axial_crystals_per_block_v,
          int num_transaxial_crystals_per_block_v,
          int num_axial_crystals_per_singles_unit_v,
          int num_transaxial_crystals_per_singles_unit_v,
          int num_detector_layers_v,
          float energy_resolution_v = -1.0f,
          float reference_energy_v = -1.0f,
          short int max_num_of_timing_poss = -1,
          float size_timing_pos = -1.0f,
          float timing_resolution = -1.0f,
          const std::string& scanner_geometry_v = "Cylindrical",
          float axial_crystal_spacing_v = -1.0f,
          float transaxial_crystal_spacing_v = -1.0f,
          float axial_block_spacing_v = -1.0f,
          float transaxial_block_spacing_v = -1.0f,
          const std::string& crystal_map_file_name = "");


  Scanner(Type type_v,
          const std::string& name,
          int num_detectors_per_ring_v,
          int num_rings_v,
          int max_num_non_arccorrected_bins_v,
          int default_num_arccorrected_bins_v,
          float inner_ring_radius_v,
          float average_depth_of_interaction_v,
          float ring_spacing_v,
          float bin_size_v,
          float intrinsic_tilt_v,
          int num_axial_blocks_per_bucket_v,
          int num_transaxial_blocks_per_bucket_v,
          int num_axial_crystals_per_block_v,
          int num_transaxial_crystals_per_block_v,
          int num_axial_crystals_per_singles_unit_v,
          int num_transaxial_crystals_per_singles_unit_v,
          int num_detector_layers_v,
          float energy_resolution_v = -1.0f,
          float reference_energy_v = -1.0f,
          short int max_num_of_timing_poss = -1,
          float size_timing_pos = -1.0f,
          float timing_resolution = -1.0f,
          const std::string& scanner_geometry_v = "Cylindrical",
          float axial_crystal_spacing_v = -1.0f,
          float transaxial_crystal_spacing_v = -1.0f,
          float axial_block_spacing_v = -1.0f,
          float transaxial_block_spacing_v = -1.0f,
          const std::string& crystal_map_file_name = "");


  virtual void set_up();

  std::string parameter_info() const;
  const std::string& get_name() const;
  const std::list<std::string>& get_all_names() const;
  std::string list_names() const;

  bool operator==(const Scanner& scanner) const;
  inline bool operator!=(const Scanner& scanner) const;

  inline Type get_type() const;

  Succeeded check_consistency() const;



  inline int get_num_rings() const;
  inline int get_num_detectors_per_ring() const;

  inline int get_max_num_non_arccorrected_bins() const;

  inline int get_default_num_arccorrected_bins() const;

  inline int get_max_num_views() const;
  inline float get_inner_ring_radius() const;
  inline float get_max_FOV_radius() const;
  inline float get_effective_ring_radius() const;
  inline float get_average_depth_of_interaction() const;
  inline float get_ring_spacing() const;
  inline float get_default_bin_size() const;

  inline float get_intrinsic_azimuthal_tilt() const;

  inline int get_num_transaxial_blocks_per_bucket() const;
  inline int get_num_axial_blocks_per_bucket() const;
  inline int get_num_axial_crystals_per_block() const;
  inline int get_num_transaxial_crystals_per_block() const;
  inline int get_num_transaxial_crystals_per_bucket() const;
  inline int get_num_axial_crystals_per_bucket() const;
  inline int get_num_detector_layers() const;
  inline int get_num_axial_blocks() const;
  inline int get_num_transaxial_blocks() const;
  inline int get_num_axial_buckets() const;
  inline int get_num_transaxial_buckets() const;

  inline int get_num_axial_crystals_per_singles_unit() const;
  inline int get_num_transaxial_crystals_per_singles_unit() const;
  // TODO accomodate more complex geometries of singles units.
  /*  inline int get_num_crystal_layers_per_singles_unit() const; */
  inline int get_num_axial_singles_units() const;
  inline int get_num_transaxial_singles_units() const;
  /* inline int get_num_layers_singles_units() const; */
  inline int get_num_singles_units() const;

  inline int get_max_num_timing_poss() const;

  inline float get_size_of_timing_pos() const;

  inline float get_timing_resolution() const;

  float get_coincidence_window_width_in_ps() const;

  float get_coincidence_window_width_in_mm() const;



  int get_num_virtual_axial_crystals_per_block() const;
  int get_num_virtual_transaxial_crystals_per_block() const;
  void set_num_virtual_axial_crystals_per_block(int);
  void set_num_virtual_transaxial_crystals_per_block(int);



  inline std::string get_scanner_geometry() const;
  inline float get_axial_crystal_spacing() const;
  inline float get_transaxial_crystal_spacing() const;
  inline float get_axial_block_spacing() const;
  inline float get_transaxial_block_spacing() const;
  inline float get_axial_length() const;

  inline std::string get_crystal_map_file_name() const;






  inline float get_energy_resolution() const;

  inline float get_reference_energy() const;
  inline bool has_energy_information() const;



  // zlong, 08-04-2004, add set_methods
  inline void set_type(const Type& new_type);
  inline void set_num_rings(const int& new_num);
  inline void set_num_detectors_per_ring(const int& new_num);
  inline void set_max_num_non_arccorrected_bins(const int& new_num);
  inline void set_default_num_arccorrected_bins(const int& new_num);
  inline void set_inner_ring_radius(const float& new_radius);
  inline void set_average_depth_of_interaction(const float& new_depth_of_interaction);
  inline void set_ring_spacing(const float& new_spacing);
  inline void set_default_bin_size(const float& new_size);
  inline void set_intrinsic_azimuthal_tilt(const float new_tilt);

  inline void set_num_transaxial_blocks_per_bucket(const int& new_num);
  inline void set_num_axial_blocks_per_bucket(const int& new_num);
  inline void set_num_axial_crystals_per_block(const int& new_num);
  inline void set_num_transaxial_crystals_per_block(const int& new_num);
  inline void set_num_detector_layers(const int& new_num);
  inline void set_num_axial_crystals_per_singles_unit(const int& new_num);
  inline void set_num_transaxial_crystals_per_singles_unit(const int& new_num);
  // TODO accomodate more complex geometries of singles units.

  void set_scanner_geometry(const std::string& new_scanner_geometry);
  inline void set_axial_crystal_spacing(const float& new_spacing);
  inline void set_transaxial_crystal_spacing(const float& new_spacing);
  inline void set_axial_block_spacing(const float& new_spacing);
  inline void set_transaxial_block_spacing(const float& new_spacing);

  inline void set_crystal_map_file_name(const std::string& new_crystal_map_file_name);


  inline void set_energy_resolution(const float new_num);

  inline void set_reference_energy(const float new_num);
  inline void set_max_num_timing_poss(int new_num);
  inline void set_size_of_timing_poss(float new_num);
  inline void set_timing_resolution(float new_num_in_ps);


  inline int get_singles_bin_index(int axial_index, int transaxial_index) const;

  inline int get_singles_bin_index(const DetectionPosition<>& det_pos) const;

  inline int get_axial_singles_unit(int singles_bin_index) const;

  inline int get_transaxial_singles_unit(int singles_bin_index) const;

  inline bool is_tof_ready() const;

  // used in CListRecordSAFIR.inl for accessing the coordinates
  inline stir::DetectionPosition<> get_det_pos_for_index(const stir::DetectionPosition<>& det_pos) const;
  // used in ProjInfoDataGenericNoArcCorr.cxx for accessing the coordinates
  inline stir::CartesianCoordinate3D<float> get_coordinate_for_det_pos(const stir::DetectionPosition<>& det_pos) const;
  inline stir::CartesianCoordinate3D<float> get_coordinate_for_index(const stir::DetectionPosition<>& det_pos) const;
  // used  in ProjInfoDataGenericNoArcCorr.cxx for accessing the get_bin
  inline Succeeded find_detection_position_given_cartesian_coordinate(DetectionPosition<>& det_pos,
                                                                      const CartesianCoordinate3D<float>& cart_coord) const;

  shared_ptr<const DetectorCoordinateMap> get_detector_map_sptr() const { return detector_map_sptr; }

private:
  bool _already_setup;
  Type type;
  std::list<std::string> list_of_names;
  int num_rings; /* number of direct planes */
  int max_num_non_arccorrected_bins;
  int default_num_arccorrected_bins; /* default number of bins */
  int num_detectors_per_ring;

  float inner_ring_radius;            
  float average_depth_of_interaction; 
  float max_FOV_radius;               
  float ring_spacing;                 
  float bin_size;                     
  float intrinsic_tilt;               
  int num_transaxial_blocks_per_bucket;  /* transaxial blocks per bucket */
  int num_axial_blocks_per_bucket;       /* axial blocks per bucket */
  int num_axial_crystals_per_block;      /* number of crystals in the axial direction */
  int num_transaxial_crystals_per_block; /* number of transaxial crystals */
  int num_detector_layers;

  int num_axial_crystals_per_singles_unit;
  int num_transaxial_crystals_per_singles_unit;

  float energy_resolution;
  float reference_energy;
  float timing_resolution;
  int max_num_of_timing_poss;
  float size_timing_pos;

  std::string scanner_geometry;     
  float axial_crystal_spacing;      
  float transaxial_crystal_spacing; 
  float axial_block_spacing;        
  float transaxial_block_spacing;   
  std::string crystal_map_file_name;
  shared_ptr<DetectorCoordinateMap> detector_map_sptr; 
  void set_detector_map(const DetectorCoordinateMap::det_pos_to_coord_type& coord_map);
  void initialise_max_FOV_radius();

  // function to create the maps
  void read_detectormap_from_file(const std::string& filename);

  // ! set all parameters
  void set_params(Type type_v,
                  const std::list<std::string>& list_of_names_v,
                  int num_rings_v,
                  int max_num_non_arccorrected_bins_v,
                  int default_num_arccorrected_bins_v,
                  int num_detectors_per_ring_v,
                  float inner_ring_radius_v,
                  float average_depth_of_interaction_v,
                  float ring_spacing_v,
                  float bin_size_v,
                  float intrinsic_tilt_v,
                  int num_axial_blocks_per_bucket_v,
                  int num_transaxial_blocks_per_bucket_v,
                  int num_axial_crystals_per_block_v,
                  int num_transaxial_crystals_per_block_v,
                  int num_axial_crystals_per_singles_unit_v,
                  int num_transaxial_crystals_per_singles_unit_v,
                  int num_detector_layers_v,
                  float energy_resolution_v = -1.0f,
                  float reference_energy = -1.0f,
                  short int max_num_of_timing_poss_v = -1.0f,
                  float size_timing_pos_v = -1.0f,
                  float timing_resolution_v = -1.0f,
                  const std::string& scanner_geometry_v = "",
                  float axial_crystal_spacing_v = -1.0f,
                  float transaxial_crystal_spacing_v = -1.0f,
                  float axial_block_spacing_v = -1.0f,
                  float transaxial_block_spacing_v = -1.0f,
                  const std::string& crystal_map_file_name = "");
};

END_NAMESPACE_STIR

#include "stir/Scanner.inl"

#endif