The pre-built executable runs on Windows 7 and Windows 10 64-bit. The pre-built libraries that are called from python run on Windows 7, Windows 10 64-bit, Linux 64-bit, and Mac OS (x86-64). CatSim uses Python3 syntax.

The XCIST GitHub organization includes the following repositories:

• documentation includes:

  • We are currently using the Wiki page of the documentation repository for the XCIST Wiki
  • Images used in the Wiki

• main includes:

  • README file with acknowledgements
  • License files
  • all code and associated files, including: CatSim simulator Python code, configuration, dose estimation, examples,
    C source code and compiled libraries, data, and tests are located within subdirectories in this Git submodule

The following repositories contain phantom files, which can be rather large. We recommend only downloading those that you need.

• phantoms-NURBS
• phantoms-polygonal
• phantoms-voxelized

Files associated with public applications, such as the AAPM Grand Challenge, are located in this repository

• Install VSCode: https://code.visualstudio.com/download
• Open VSCode, install Python Extensions
• When you open your Python file in VSCode, from the bottom right, select your Python interpreter

• Download from https://www.jetbrains.com/pycharm/. After downloading, follow Setting up Pycharm to set up your environment.

Run one or more of the example programs to confirm that you have the python dependencies setup correctly.

• Right click on the examples/Sim_Sample.py file and click Run 'Sim_Sample'.

Output will be written to the Run window. A plot window will be opened. Click to close it after review.

cd examples
python Sim_Sample.py

Sample output (times may vary)

Airscan
Scan sim time: 1.3 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      8 MB.
Simulated view 5/50, time: 8.9 s
Simulated view 10/50, time: 18.0 s
Simulated view 15/50, time: 28.1 s
Simulated view 20/50, time: 37.8 s
Simulated view 25/50, time: 45.9 s
Simulated view 30/50, time: 54.1 s
Simulated view 35/50, time: 63.1 s
Simulated view 40/50, time: 72.8 s
Simulated view 45/50, time: 82.2 s
Simulated view 50/50, time: 90.3 s
Scan sim time: 90.3 s
Prep view
Simulation is done

A plot window will open up. Close it to finish the program.

If you are using PyCharm, you can update the code and then rerun.

If you are using the command-line, rebuild catsim before rerunning. This will update your installed version of catsim-xcist.

pip install . --use-feature=in-tree-build

If you are using the PyPI installation, you can run this command to upgrade:

pip install -U gecatsim

If you have changes to share back to GitHub, create a branch and the submit a GitHub pull request. Please increment the version in setup.py and catsim/init.py.

CatSim will look in the following locations for data files, including config, phantoms, materials, etc.

• A file matching the name as written.
• A file matching the name as written with the default extension for the type of file.
• A list of extra search paths. The paths will be searched recursively.
  • A file that matches the name as written in the search path.
  • A file that matches the name as written in the search path with the default extension for the type of file.
  • A file that matches the name as written in a subdirectory with the file type key (e.g. cfg, phantom, etc.)
  • A file that matches the name as written in a subdirectory with the file type key and the default extension.
• The path to the catsim code directory. This path will be searched recursively.
  • A file that matches the name as written in the default path.
  • A file that matches the name as written in the default path with the default extension for the file type.

The extra search paths can be defined by creating a file called .catsim. This file can be placed in the directory where you are running main catsim file (e.g. examples). The .catsim file can also be placed in the user's home directory.

If you write your own python script, you can also call the add_search_path function with code like:

import gecatsim as xc
##--------- Initialize
my_path = xc.pyfiles.CommonTools.my_path
# add any additional search directories
my_path.add_search_path("my-experiments")

pip install gecatsim

Note: If you are installing this while behind a company firewall, you might need to specify your company proxy information to the pip command using the "--proxy" option, e.g., pip --proxy http://your-company-proxy-info install gecatsim. Ask your IT for your proxy information.

(Supported OS: Windows 7 and Windows 10 64-bit; Linux 64-bit, Mac OS 13.5).

git clone https://github.com/xcist/main.git

Or if you're unfamiliar with git, you might find the GitHub Desktop helpful.

In a Python command window, navigate to the CatSim main directory and type:

pip install . --use-feature=in-tree-build

If you don't have administrator rights on the account, you can try:

pip install . --user --use-feature=in-tree-build

(Supported OS: Windows 7 and Windows 10 64-bit.)

• Download the software from GitHub as a zip file, including an executable file and configuration files.
• After downloading, extract the Zip file to a location of your choice - directly under C:\ might be easiest.
• Please rename the top-level extracted folder to simply CatSim (it might be named main-master, or main-master (1), or the like).
• For information about running the executable, see Tips and tricks: Running the Windows executable

Although there are many ways to set up a Python development environment, here is one way which we believe may be relatively low effort. The CatSim project uses Python 3 syntax. These instructions were written for Python 3.7, but may work for later versions as well.

Follow the instructions for downloading and installing Python. We recommend using Python 3.7 or one of its 3.7.x maintenance releases.

Click the box to "Add Python 3.7 to PATH." Install with the default options rather than the custom installation.

Follow the instructions for downloading and installing PyCharm, getting the free Community Edition. NOTE: We will not use PyCharm for Anaconda for the time being. It seems to have some issues running with corporate firewalls.

We suggest selecting all options:

• Create Desktop Shortcut
• Update context menu
• Create Associations -- unless you also have another Python environment on the same computer
• Update PATH variable

Reboot your computer after installing PyCharm.

Double-click on the PyCharm icon on your desktop. If you are asked about importing settings, choose "Do not import settings" unless you know that you have previous settings that you want to use. You will then be asked for your preferred color scheme.

If you are behind a corporate firewall, PyCharm may fail to get the list of available plugins online. We will fix that later.

Click on "Start using PyCharm."

If you are working behind a corporate proxy server, you may need to update the proxy settings in order to download and install public Python packages.

When the "Welcome to PyCharm" dialog is shown, click on Customize-> All Settings.

• Expand the Appearance & Behavior section
• Expand the System Settings section
• Click on HTTP Proxy.
• Enter the correct settings for your site. Many people find using manual settings easiest. The Automatic settings may be easy to copy from your browser settings.

• Use the Check connection to confirm you can access sites inside your corporate network and on the Internet.

Successful connection:

Failed connection:

• If your internal sites cannot be reached, adjust the items in the in "No proxy for" entry.
• If external sites cannot be reached, contact your IT network team to get the correct settings. You may want to inspect your browser settings.
• Click OK on the Settings dialog.

Users behind corporate firewalls may periodically get (frequent) dialogs about "Untrusted Server's Certificate." Click on "Accept." (A solution to this is being sought.)

Back on the "Welcome to Pycharm" dialog, click on "Create New Project."

Enter the location for your new project by editing the provided path.

Expand the Project Interpreter section. The dialog may be filled out with these defaults:

• Select the radio button for "New environment using" and choose "Virtualenv".

• Location should be filled in automatically.

• Base interpreter should also be filled in automatically for where you have installed python.exe.

  • If you have multiple installations of python, select the desired one (e.g. python 3.7).

• Check the boxes to "Inherit global site-packages" and "Make available to all projects."

  • This will allow you to reuse your installation. However, if you have other work that has different requirements you may leave this unchecked, but then you will have to repeat package installations if you create multiple projects for CatSim work.

• Check the box to add a main.py file to the project. This will create a simple test python file.

• Click "Create."

PyCharm will take a couple of minutes to create the virtual environment, the new directory and files and open your new project.

If you forgot to check the box to add main.py file, then create a new file:

• Under "Project" on the left panel, right-click on your project
• Choose New -> Python File.
• Give the file a name. (You don't need to add .py. This is added automatically.)
• Add some python code to your new file:

print("Hello, python user")

• Right-click on your filename and find the "Run myfile.py" in the menu.

• If the Run item does not exist in the menu, then Python may still be doing some background tasks to initialize the environment - especially the first time you use python or a new python interpreter. Look for background tasks in the lower right status bar.

This should run your python program and show any output in the "Run" window.

Follow the instructions for downloading and installing Anaconda. Follow the instructions and download Anaconda for Python 3.7.

• Make sure you choose your appropriate platform (e.g. Windows, Mac, etc.).
• Select installing for "Just Me."
• To simplify finding specific files later, install in a simple location such as C:\anaconda3 (for Windows) rather than the default longer path. Note the instructions - do not install in a path that includes spaces in the name.
• Accept the installation defaults (not adding Anaconda to your PATH, but registering Anaconda as your default Python).

The installation of Anaconda may take 10-30 minutes depending on the speed of your computer.

GitHub Desktop is a convenient tool for cloning GitHub repositories to your computer.

Instructions for installing the Windows version:

1. If you don't already have one, register for a GitHub.com account.

2. Go to https://desktop.github.com/ and click "Download for Windows". After it downloads, open the executable.

3. When prompted, sign in to GitHub and open GitHubDesktop.exe.

4. Choose "Close a repository from the internet...", enter xcist/CatSim, and click Clone.

5. You should now have a copy of that repository on our computer. You can view that copy by clicking "Show in Explorer".

6. Now, from the GitHub Desktop menu, select "File -> Clone Repository...", enter xcist/phantom, and click Clone.

7. Again, you should now have a copy of that repository on our computer, and you can view that copy by clicking "Show in Explorer".

At a minimum, you will need:

1. The Python language itself.

2. Several python packages:

• numpy
• scipy
• matplotlib

3. (optional but recommended for developers) An integrated development environment (IDE). This is a fancy editor that makes code development more efficient and allows for debugging with breakpoints, stepping through the code and inspecting the value of variables..

Some installation options

There are a multitude of ways to install Python; advanced developers might have their own favorite tools that work fine with XCIST. Here are some options for newbies.

A la carte installation: From Python.org you can download Python itself, and then separately install the packages that you need. This might rersult in the most compact installation, but you might need to download several packages seperately.

Here's what worked for me (Paul FitzGerald). Thanks for advice from Brion Sarachan! I installed for Windows, but Linux installations of the same tools are also available from the links below.

A more comprehensive installation One alternative is to install Anaconda, which includes Python and a large number of common packages and tools. Compared to the al la carte option, Anaconda is easier to set up but takes a while (hands off) and results in a lot of stuff installed (i.e. GB on your disk). For a straightforward installation, installing Anaconda seems like a good choice. I'm not sure of the differences between the 2.7 and 3.7 versions. I installed Anaconda version 3.7 for Windows. Here's Anaconda version 3.7 for Linux.

Even more comprehensive installation (for developers) Anaconda comes with several IDEs. Another IDE, PyCharm, is quite popular. I installed a new version of PyCharm that works specifically with Anaconda; here is the version for Windows and here is the version for Linux.

Then, run Pycharm.

Note: If you're behind a firewall, you might get an error message like this. You might need to change your proxy setting - contact your system administrator for the correct settings. The place to change it (in PyCharm) is File -> Settings... -> Appearance & Behavior -> System Settings -> HTTP Proxy. After changing the settings, you can test using the "Check Connection" button. You might then get an error message like this. I clicked "Accept" and all was good.

I then went to Help -> Getting Started. There are videos and tutorials to help you get started with Python and PyCharm.

Please feel free to add to this page if you have different suggestions!

(not required if you only use the executable version)

Minimum needs: A Python 3 distribution, such as:

• Python standard version: https://www.python.org/downloads/. We recommend using Python 3.7 or later.
• Miniconda, download from https://docs.conda.io/en/latest/miniconda.html.

Recommended: A Python development environment (IDE), e.g., VSCode, PyCharm; Or use an editor that provides python syntax checking, such as Notepad++.  

Back to Main menu