diff --git a/CHANGES.md b/CHANGES.md index 21286f045..7ab1b7dec 100644 --- a/CHANGES.md +++ b/CHANGES.md @@ -1,12 +1,12 @@ # ChangeLog ## v3.4.0 -* added support for spiral trajectories that are pre-computed by the user by exposing a setter. +* MR: + - added support for spiral trajectories that are pre-computed by the user by exposing a setter. + - writing MR images and their attributes to `.dcm` and `.xml` files fixed. + - use C++ 17 if Gadgetron-support is enabled -## v3.X - -* writing MR images and their attributes to `.dcm` and `.xml` files fixed. - -* Use C++ 17 if Gadgetron-support is enabled +* documentation + - revision of READMEs for the examples ## v3.3.0 diff --git a/examples/Matlab/readme.txt b/examples/Matlab/README.md similarity index 57% rename from examples/Matlab/readme.txt rename to examples/Matlab/README.md index fe3ffc20b..dc9d488c5 100644 --- a/examples/Matlab/readme.txt +++ b/examples/Matlab/README.md @@ -1,10 +1,15 @@ This folder's subfolders contain Matlab demo scripts for PET and MR reconstruction. -The folder YOUR_PATH/build/install/bin (see SIRF/INSTALL.txt) must be in Windows path, +Unfortunately, we no longer support Matlab, so have not checked in a while if these +demos work. Apologies. + +See [the main README section](../README.md#environment-variables) for information +on environment variables. + +The folder YOUR_PATH/build/install/bin (see SIRF/INSTALL.txt) must be in the Windows path, and the folder YOUR_PATH/build/install/matlab in Matlab path. To use Matlab doc feature on demo scripts, you also need to add folders YOUR_PATH/SIRF/examples/Matlab/MR and YOUR_PATH/SIRF/examples/Matlab/PET and their -sub-folders to Matlab path. +sub-folders to the Matlab path. -Please also see the Wiki page on Examples (MR). diff --git a/examples/Python/MR/README.md b/examples/Python/MR/README.md index f2935ba94..cd5a37cd2 100644 --- a/examples/Python/MR/README.md +++ b/examples/Python/MR/README.md @@ -2,6 +2,8 @@ This folder contains scripts demonstrating the use of SIRF for MR reconstruction All scripts currently use Gadgetron as the reconstruction engine, however only the demos located in the subfolder named `Gadgetron` employ Gadgetron's gadget chains explicitly. Those outside of this subfolder allow the use of any reconstruction engine that provides the necessary functionality such as `AcquisitionData` object, `preprocess_acquisition_data` function etc. +See the [Python/README](../README.md) for instructions. + \ No newline at end of file diff --git a/examples/Python/PET/README.md b/examples/Python/PET/README.md index 14f1f47df..37e5a7ebb 100644 --- a/examples/Python/PET/README.md +++ b/examples/Python/PET/README.md @@ -2,16 +2,4 @@ This folder contains scripts demonstrating the use of SIRF for PET reconstructio All scripts currently use STIR as the reconstruction engine but actually allow the use of any reconstruction engine that provides the necessary functionality such as `AcquisitionData` object, `make_Poisson_loglikelihood` function etc. - \ No newline at end of file +See the [Python/README](../README.md) for instructions. diff --git a/examples/Python/PETMR/README.md b/examples/Python/PETMR/README.md new file mode 100644 index 000000000..b90699539 --- /dev/null +++ b/examples/Python/PETMR/README.md @@ -0,0 +1,5 @@ +This folder contains simple scripts demonstrating the use of SIRF for +PETMR related tasks. There are examples on synergistic image reconstruction +in our Jupyter notebooks in the [SIRF Exercises](https://github.com/SyneRBI/SIRF-Exercises/#readme). + +See the [Python/README](../README.md) for instructions. diff --git a/examples/Python/README.md b/examples/Python/README.md index 3e95209da..0ae09b9a1 100644 --- a/examples/Python/README.md +++ b/examples/Python/README.md @@ -1,12 +1,22 @@ -This folder's subfolders named PET and MR contain Python demo scripts for PET and MR reconstruction respectively. +This folder's subfolders contains Python demo scripts. For a brief description of each script's purpose and usage type -``` +```sh python .py --help ``` -(on VM use `python3` instead of `python`). +(on the VM use `python3` instead of `python`). Note that the SIRF Python utilities should be in your `PYTHONPATH` (see the installation instructions). -To run the demo scripts, please create an environment variable `SIRF_PATH` whose value is the location of your SIRF source, e.g. `/home/sirfuser/devel/SIRF`. (NOTE: even on Windows, you must use `/` in paths, not `\\`.) If you do not do this, you can still run the demos but you will have to give full path to raw data files via command-line options `-p` or `--path`. +See [the main README section](../README.md#environment-variables) for information +on environment variables. +If you do not set the environment variables that allow SIRF to find the example data, +you can still run most demos but you will have to give full path to raw data files via command-line options `-p` or `--path`. + +## Subfolders: +- [MR](MR#readme) +- [PET](PET#readme) +- [PETMR](PETMR#readme) +- [Registration](Registration#readme) +- [SPECT](SPECT#readme) diff --git a/examples/Python/Registration/README.md b/examples/Python/Registration/README.md new file mode 100644 index 000000000..ae66a76c6 --- /dev/null +++ b/examples/Python/Registration/README.md @@ -0,0 +1,5 @@ +This folder contains scripts demonstrating the use of SIRF for image registration reconstruction and related tasks. + +Scripts currently use NiftyReg or SPM as the registration engine + +See the [Python/README](../README.md) for instructions. diff --git a/examples/Python/SPECT/README.md b/examples/Python/SPECT/README.md new file mode 100644 index 000000000..cdb408c22 --- /dev/null +++ b/examples/Python/SPECT/README.md @@ -0,0 +1,5 @@ +This folder contains scripts demonstrating the use of SIRF for SPECT reconstruction and related tasks. + +All scripts currently use STIR as the reconstruction engine but actually allow the use of any reconstruction engine that provides the necessary functionality such as `AcquisitionData` object, `make_Poisson_loglikelihood` function etc. + +See the [Python/README](../README.md) for instructions. diff --git a/examples/README.md b/examples/README.md index f333830bf..b6907814c 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,7 +1,8 @@ This directory contains examples and demos on how to use SIRF. - + +Please also our Jupyter notebooks in the [SIRF Exercises](https://github.com/SyneRBI/SIRF-Exercises/#readme) +which are more extensive and allow you to learn step-by-step. + Most of the demos use simplistic data for illustration. The images might therefore be not very interesting either. The idea here is to illustrate what you can do with SIRF, @@ -28,21 +29,30 @@ The structure of the examples subfolder is as follows: SPECT interactive -The contents of subfolder named Python are described [here](https://github.com/SyneRBI/SIRF/blob/master/examples/Python/README.md). The contents of subfolder named Matlab are of similar nature but are not documented as we no longer support Matlab. +The contents of subfolder named Python are described [here](Python/README.md). The contents of subfolder named Matlab are of similar nature but are not documented as we no longer support Matlab. ## Environment variables The correct setup of SIRF requires defining the environment variables `SIRF_PATH` and `SIRF_INSTALL_PATH`. -On Unix/Linux, these environment variables are sourced from the [`env_sirf.sh`](https://github.com/SyneRBI/SIRF-SuperBuild/blob/master/env_sirf.sh.in) file. +If you built SIRF with the SIRF-Superbuild, these environment variables can be sourced from the `env_sirf.*` files, e.g. +on Unix/Linux [`env_sirf.sh`](https://github.com/SyneRBI/SIRF-SuperBuild/blob/master/env_sirf.sh.in). -On Windows, the value of `SIRF_PATH` should be set by the user to the full path to the root folder containing SIRF source, and the value of `SIRF_INSTALL_PATH` to the full path to the folder where the user wants SIRF binaries and other files created by the build installed. +Alternatively, `SIRF_PATH` should be set by the user to the full path to the root folder containing the SIRF source, +and `SIRF_INSTALL_PATH` to the full path to the folder where the user installed SIRF binaries and other files (i.e. +set by `CMAKE_INSTALL_PREFIX`). -Additionally, the user may define the variable `SIRF_DATA_PATH` whose value is the path to the data to be processed by SIRF. +Additionally, the user may define the variable `SIRF_DATA_PATH` to point to an alternative location. For instance, when the +installation files are in a write-protected location, the user can make a copy elsewhere and point there. + + ### Examples data path The resolution order for the examples data path is: 1. The directory pointed by `${SIRF_DATA_PATH}` if it is set by the user. -2. The directory `${SIRF_INSTALL_PATH}/share/SIRF-.`. +2. The directory `${SIRF_INSTALL_PATH}/share/SIRF-.` if `SIRF_INSTALL_PATH` is set. +3. The directory `${SIRF_PATH}/data/examples` if `SIRF_PATH` is set.