small changes to examples/README.md etc

[ci skip]

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
 

examples/Matlab/readme.txt → 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).

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.
+
 <!--
 ### Fully Sampled Data Reconstructions
 
@@ -34,6 +36,4 @@ The demos also have some options. Try
 ```bash
 python acquisition_model.py --help
 ```
-
-Check the `interactive` folder for demos that you run from an IDE.
 -->

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.
 
-<!--
-This folder contains scripts intended to be run from the command line.
-For instance,
-```bash
-python acquisition_model.py 
-```
-The demos also have some options. Try
-```bash
-python acquisition_model.py --help
-```
-
-Check the `interactive` folder for demos that you run from an IDE.
--->
+See the [Python/README](../README.md) for instructions.

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.

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 <script_name>.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)
 

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.

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.

examples/README.md

@@ -1,7 +1,8 @@
 This directory contains examples and demos on how to use SIRF. 
-<!--
-Please also see the [related Wiki page](https://github.com/CCPPETMR/SIRF/wiki/Examples).
--->
+
+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.
+
+<!--
+(NOTE: even on Windows, you must use `/` in paths, not `\\`.)
+-->
 
 ### 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-<version_major>.<version_minor>`.
+2. The directory `${SIRF_INSTALL_PATH}/share/SIRF-<version_major>.<version_minor>` if `SIRF_INSTALL_PATH` is set.
+3. The directory `${SIRF_PATH}/data/examples` if `SIRF_PATH` is set.