XCIST is a Python application (the compute-intensive work are written in C/C++) that runs on Linux, Windows, and MacOS. To perform a simulation, users can simply run the executable or install CatSim in their Python environment.

The gecatsim/examples directory contains several sample programs that you can experiment with. You can utilize these scripts as a starting point for your experiments, taking advantage of predefined elements and structures.
You can run a testing simulation with:

python Sim_Recon_Sample.py

Then, using either our GUI or simple configuration files, you will simply need to

1. Select an imaging system configuration from a pre-defined standard system with or without variations based on several available component models (or advanced users can develop their own models).
2. Select a scan protocol from several pre-defined protocols and multiple user-selectable variations such as kVp, mA, rotation time, focal spot, bowtie, etc.
3. Select simulation options from several pre-defined configurations and multiple user-selectable variations including oversampling, with or without quantum and/or electronic noise, etc.
4. Select a subject to be scanned (i.e a numerical phantom) from a rich library of geometric phantoms and virtual patient models with and without tumors (or advanced users can develop their own phantoms).
5. Select a reconstruction algorithm from several pre-defined options (or advanced users can develop their own reconstruction).
6. Launch your simulation.
7. Review the results! (available as simple binary files and/or in DICOM format)

The code repository is here.

CatSim was originally developed to produce sinograms to be used in the process of developing new reconstruction algorithms. Therefore, the focus is on simulation, rather than reconstruction. However, CatSim is also used by non-reconstruction experts, for producing reconstructed images following simulation. Therefore, some basic “prep” and reconstruction functionality is included with CatSim.

In general, these can be invoked after running catsim, and the same configuration file can be used for prep and reconstruction as was used for the simulation itself, provided that the fields required by catprep and catsimrecon are specified in the configuration file.

All results of CatSim and related commands are written to files for which the base name is specified in the cfg structure:

cfg.results_basename = 'Basename';

Basename can (optionally) include a full path. If a Basename is provided without a full path, then the Basename will be interpreted relative to the current Matlab working directory.

CatSim will automatically add an extension to complete the file name:

.scan	regular scan, without prep
.offset	offset scan
.air	air scan
.prep	prepped scan
.recon	reconstructed image or volume

The output/results of CatSim are binary data in float32.
cfg.resultsName defines the basename of the result files, which can be full path and name or just the name.
The result files are:

[basename].air - air scan data, dim: [Ebin, column, row, view_air]
[basename].offset - offset scan data (X-ray off), dim: [Ebin, column, row, view_offset]
[basename].scan - phantom scan data, dim: [Ebin, column, row, view]
[basename].prep - prep data, dim: [Ebin, column, row, view]
[basename]_512x512x4.raw - reconstructed image, dim: [recon.imageSize, recon.imageSize, recon.sliceCount], here is 512x512x4

where

Ebin is the energy bin, for energy integration CT, it's 1.
Column and row are detector pixels in x and z direction.
View is the scan views, view_air and view_offset are 1 by default.
 

The simulation is defined in a Python script, which is the primary input to CatSim, whether running the executable or running from within Python. Sample scripts are included in the release; users can revise to create their own. We recommend to use filename Sim_name.py for all simulation experiments. The script should contain the following elements.

Step 1: Define simulation parameters in configuration files in the cfg folder.

Step 2: Initialize the simulation class and assign it the right configuration names. For example,

ct = xc.CatSim("Phantom_Sample", "Scanner_Samplegeneric", "Protocol_Sampleaxial")

Step 3: Choose a name for the simulation experiment, which will be used to write the results

ct.resultsName = "test"

Step 4: If desired, over-ride selected predefined parameters directly from within the script. For example,

ct.protocol.mA = 200
ct.protocol.enableQuantumNoise = 1

Step 5: Run the desired scans

ct.run_all()

The input phantom images can be viewed using ImageJ, described here.

Simulation results are described on this page.

(Future content)

After downloading the .zip file, un-zip it to a folder of your choice (e.g. I put it directly in C:). Please rename the top-level extracted folder to simply CatSim (it might be named main-master, or main-master (1), or the like).

Browse to that folder, browse to the EXE subdirectory, and double-click on catsim.exe. This should open a command window and run an example simulation. However, if an error occurs, the command window might automatically close. And even when successful, the command window will close when complete.

Therefore, it's preferable to first open a command window, then run the executable.

1. Type "command" into Windows search, then pin "Command prompt" to your Start menu and/or Taskbar, as you prefer.
2. Click the "Command prompt" icon to open a command window.
3. Change directory to the path for the Windows executable (example below).
4. Type "catsim" (the filename of the executable).
5. There will be a pause for several seconds as the code initializes, then the simulation should run (example output below).
6. If you receive a warning message about "The MATPLOTLIBDATA environment variable...", it can safely be ignored.
7. When the simulation is complete, a plot should open.
8. Close the plot, and press a key when prompted. After several seconds (while the executable cleans up and closes), you should get a command prompt.

Example:
Note that your command prompt, to the left of the '>', will be different from mine, shown in this example.
Also, the path to the executable (to the right of the '>' in the first line), depends on where you unzipped the executable code that you downloaded.

C:\Users\user_name>cd C:\Catsim\main-master\EXE
C:\Catsim\main-master\EXE>catsim
Airscan
Loading GEANT4/EDLP97 cross section database...compton..rayleigh..photo..scatter..form..done
Scan sim time: 4.5 s
Offset scan
Scan sim time: 0.3 s
Phantom scan
in C> Preparing to allocate memory for material volume data...
in C> Allocated memory for image volume for material  1
in C> Copying data for material  1 into C memory...in C>  done.
in C> Allocated memory for image volume for material  2
in C> Copying data for material  2 into C memory...in C>  done.
in C> Allocated a total of      2 MB.
Simulated view 80/800, time: 10.8 s
Simulated view 160/800, time: 21.4 s
Simulated view 240/800, time: 32.5 s
Simulated view 320/800, time: 43.1 s
Simulated view 400/800, time: 53.5 s
Simulated view 480/800, time: 64.1 s
Simulated view 560/800, time: 74.6 s
Simulated view 640/800, time: 85.8 s
Simulated view 720/800, time: 96.5 s
Simulated view 800/800, time: 107.0 s
Scan sim time: 107.0 s
Prep view
Simulation is done
    
Press any key to continue . . .
    
C:\Catsim\main-master\EXE>

Once complete, you may ask: What happened? What were the inputs and outputs? How do I know it really worked?
You can find answers to those questions and more here: Viewing XCIST image files using ImageJ.

Back to Main menu

• Viewing XCIST image files using ImageJ: describes how to use the ImageJ application to view simulation results.

Back to Main menu