DOC : Update new ReadTheDocs with content from the old documentation

CodeContribution.md

@@ -0,0 +1,25 @@
+# Code contribution
+
+## Coding style
+
+RTK is based on ITK and aims at following its coding conventions. Any developer should follow these conventions when submitting new code or contributions to the existing one. We strongly recommend you to read thoroughly [ITK's style guide](http://www.itk.org/Wiki/ITK/Coding_Style_Guide).
+
+## Testing
+
+This section describes how to add/edit datasets for testing purposes for RTK. Datasets are not stored in the GIT repository for efficiency and also to avoid having large history due to binary files. Instead the files are stored on a [Girder](http://data.kitware.com) instance. Here's the recipe to add new datasets:
+
+1.  Register/Login to Girder hosted at Kitware: [http://data.kitware.com](http://data.kitware.com)
+2.  Locate the RTK collection: [https://data.kitware.com/#collection/5a7706878d777f0649e04776](https://data.kitware.com/#collection/5a7706878d777f0649e04776)
+3.  Upload the new datasets in the appropriate folder. If you don't have the necessary privileges please email the mailing list
+4.  In the GIT repository, add in testing/Data a file with the exact filename of the original file **but with the .md5 extension**. Inside that file put the md5sum of the file on Girder.
+5.  When adding a test use the new macro 'RTK_ADD_TEST' instead of 'ADD_TEST' and specify the datasets you want CTest to download by appending the data to 'DATA{}'. For example:
+
+```
+RTK_ADD_TEST(NAME rtkimagxtest
+    COMMAND ${EXECUTABLE\_OUTPUT\_PATH}/rtkimagxtest
+    DATA{Data/Input/ImagX/raw.xml,raw.raw}
+    DATA{Data/Baseline/ImagX/attenuation.mha})
+```
+## Dashboard
+
+*   The RTK dashboard is available at [RTK Dashboard](http://my.cdash.org/index.php?project=RTK)

INSTALLATION.md

@@ -38,6 +38,26 @@ We also provide pre-compiled [CUDA](https://developer.nvidia.com/cuda-toolkit) p
 python -m pip install itk-rtk-cuda116
 ```
 
+Docker
+---------------------
+
+Another installation solution is to use the Docker solution provided by Thomas Baudier:
+
+```
+docker pull tbaudier/rtk:v1.3.0
+docker run -ti --rm -e DISPLAY=$DISPLAY -v \[Documents\]:/home tbaudier/rtk:v1.3.0 bash
+```
+Information on what is installed can be reached using the commands:
+```
+docker images
+docker ps -a
+```
+To clean it after use, you can do:
+```
+docker rm -f \[container id\]
+docker rmi -f \[image id\]
+```
+
 Getting started
 ---------------
 See [GettingStarted.md](GettingStarted.md). Your `CMakeLists.txt` can now use RTK when importing ITK as shown in the [FirstReconstruction's CMakeLists.txt](https://github.com/RTKConsortium/RTK/blob/master/examples/FirstReconstruction/CMakeLists.txt#L7).

documentation/docs/CMakeLists.txt

@@ -12,6 +12,7 @@ if(RTK_BUILD_SPHINX)
     COMMAND ${CMAKE_COMMAND} -E copy "${RTK_SOURCE_DIR}/index.md" "${RTK_DOC_OUTPUT_DIR}/index.md"
     COMMAND ${CMAKE_COMMAND} -E copy "${RTK_SOURCE_DIR}/GettingStarted.md" "${RTK_DOC_OUTPUT_DIR}/GettingStarted.md"
     COMMAND ${CMAKE_COMMAND} -E copy "${RTK_SOURCE_DIR}/INSTALLATION.md" "${RTK_DOC_OUTPUT_DIR}/INSTALLATION.md"
+    COMMAND ${CMAKE_COMMAND} -E copy "${RTK_SOURCE_DIR}/CodeContribution.md" "${RTK_DOC_OUTPUT_DIR}/CodeContribution.md"
     COMMENT "Copying documentation sources"
     )
 

documentation/docs/Tutorial.md

@@ -0,0 +1,22 @@
+
+# Tutorials
+-------------------------------------------------------
+## Building a HelloWorld application
+
+RTK is a library, therefore it's meant to be integrated into application. This tutorial shows how to create a simple FirstReconstruction project that links with RTK. The source code for this tutorial is located in [RTK/examples/FirstReconstruction](https://github.com/RTKConsortium/RTK/blob/master/examples/FirstReconstruction).
+
+*   First you need to create a [CMakeLists.txt](https://github.com/RTKConsortium/RTK/blob/master/examples/FirstReconstruction/CMakeLists.txt)
+
+```{literalinclude} ../../examples/FirstReconstruction/CMakeLists.txt
+:language: cmake
+```
+*   Create a [FirstReconstruction.cxx](https://github.com/RTKConsortium/RTK/blob/master/examples/FirstReconstruction/FirstReconstruction.cxx) file
+```{literalinclude} ../../examples/FirstReconstruction/FirstReconstruction.cxx
+```
+*   Run CMake on the FirstReconstruction directory and create a HelloWorld-bin,
+*   Configure and build the project using your favorite compiler,
+*   Run `FirstReconstruction image.mha geometry.xml`. If everything runs correctly, you should see a few messages ending with `Done!` and two new files in the current directory, image.mha and geometry.xml. image.mha is the reconstruction of a sphere from 360 projections and geometry.xml is the geometry file in the [RTK format](./Geometry.md).
+
+## Modifying a basic RTK application
+
+In [applications/rtktutorialapplication/](https://github.com/RTKConsortium/RTK/blob/master/applications/rtktutorialapplication), you will find a very basic RTK application that can be used as a starting point for building more complex applications.

examples/4DRooster/Blurred.jpg.sha512

@@ -0,0 +1 @@
+52a2f4d2559e0a60c5af7c50c5969ea4f9649573492df3f25e7e963b408bc25022ea8aec3a661ae1cf6a82119a249ef4c383d97c483371b0a5fa578314457c2d

examples/4DRooster/MotionMask.jpg.sha512

@@ -0,0 +1 @@
+13b801ac5e9833613e42abb9d9e7628fcde6f4dcf2d7e6c2a501e61a6b335d7b6766c512db547887a367f280943a9715934f6f21918117942e6e3ea99e39865d

examples/4DRooster/README.md

@@ -0,0 +1,225 @@
+# 4DROOSTER: Total variation-regularized 3D + time reconstruction
+
+RTK provides a tool to reconstruct a 3D + time image which does not require explicit motion estimation. Instead, it uses total variation regularization along both space and time. The implementation is based on a paper that we have published ([article](http://www.creatis.insa-lyon.fr/site/fr/publications/MORY-14)). You should read the article to understand the basics of the algorithm before trying to use the software.
+
+The algorithm requires a set of projection images with the associated RTK geometry, the respiratory phase of each projection image and a motion mask in which the region of the space where movement is expected is set to 1 and the rest is set to 0. Each piece of data is described in more details below and can be downloaded using [Girder](https://data.kitware.com/#collection/5a7706878d777f0649e04776). It is assumed that the breathing motion is periodic, which implies that the mechanical state of the chest depends only on the respiratory phase.
+
+## Contents
+--------
+
+*   [1 Projection images](#projection-images)
+*   [2 Motion mask](#motion-mask)
+*   [3 Respiratory signal](#respiratory-signal)
+*   [4 4D ROOSTER for cone-beam CT reconstruction](#rooster-for-conebeam-ct-reconstruction)
+*   [5 Motion-Aware 4D ROOSTER (MA-ROOSTER)](#motion-aware-4d-rooster)
+
+## Projection images
+=================
+
+This example is illustrated with a set of projection images of the [POPI patient](http://www.creatis.insa-lyon.fr/rio/popi-model_original_page). You can [download the projections](https://data.kitware.com/api/v1/item/5be99af88d777f2179a2e144/download) and the required tables of the Elekta database, [FRAME.DBF](https://data.kitware.com/api/v1/item/5be99a068d777f2179a2cf4f/download) and [IMAGE.DBF](https://data.kitware.com/api/v1/item/5be99a078d777f2179a2cf65/download). The dataset is first used to reconstruct a blurry image:
+
+```
+# Convert Elekta database to RTK geometry
+rtkelektasynergygeometry
+  -o geometry.rtk
+  -f FRAME.DBF
+  -i IMAGE.DBF
+  -u 1.3.46.423632.141000.1169042526.68
+
+# Reconstruct a 3D volume from all projection images.
+# We implicitly assume that the patient's chest is static, which is wrong.
+# Therefore the reconstruction will be blurry. This blurry reconstruction is
+# not required for 4D ROOSTER, but there is usually no other way to generate
+# a motion mask, which is required. Additionally, the blurry reconstruction
+# can be used to initialize the 4D ROOSTER reconstruction.
+rtkfdk
+  -p .
+  -r .*.his
+  -o fdk.mha
+  -g geometry.rtk
+  --hann 0.5
+  --pad 1.0
+  --dimension 160
+  --spacing 2
+```
+
+You should obtain something like that with [VV](http://vv.creatis.insa-lyon.fr/):
+
+![Blurred](Blurred.jpg){w=600px alt="Blurred image"}
+
+## Motion mask
+===========
+
+The next piece of data is a 3D motion mask: a volume that contains only zeros, where no movement is expected to occur, and ones, where movement is expected. Typically, during breathing, the whole chest moves, so it is safe to use the [patient mask](https://data.kitware.com/api/v1/item/5be99a418d777f2179a2ddf4/download) (red+green). However, restricting the movement to a smaller region, e.g. the rib cage, can help reconstruct this region more accurately and mitigate artifacts, so we might want to use the [rib cage mask](https://data.kitware.com/api/v1/item/5be99a2c8d777f2179a2dc4f/download) (red):
+
+![Mm](MotionMask.jpg){w=400px alt="Motion mask"}
+
+## Respiratory signal
+==================
+
+The 4D ROOSTER algorithm requires that we associate each projection image with the instant of the respiratory cycle at which it has been acquired. We used the Amsterdam shroud solution of Lambert Zijp (described [here](http://www.creatis.insa-lyon.fr/site/fr/publications/RIT-12a)) which is implemented in RTK
+
+```
+rtkamsterdamshroud --path .
+                   --regexp '.*.his'
+                   --output shroud.mha
+                   --unsharp 650
+rtkextractshroudsignal --input shroud.mha
+                       --output signal.txt
+                       --phase sphase.txt
+```
+
+to get the phase signal. Note that the phase must go from 0 to 1 where 0.3 corresponds to 30% in the respiratory cycle, i.e., frame 3 if you have a 10-frames 4D reconstruction or frame 6 if you have a 20-frames 4D reconstruction. The [resulting phase](https://data.kitware.com/api/v1/item/5be99af98d777f2179a2e160/download) is in green on top of the blue respiratory signal and the detected end-exhale peaks:
+
+![Signal](Signal.jpg){w=800px alt="Phase signal"}
+
+## ROOSTER for conebeam CT reconstruction
+==========================================
+
+We now have all the pieces to perform a 3D + time reconstruction. The algorithm will perform "niter" iterations of the main loop, and run three inner loops at each iteration:
+
+*   conjugate gradient reconstruction with "cgiter" iterations
+*   total-variation regularization in space, with parameter "gamma_space" (the higher, the more regularized) and "tviter" iterations
+*   total-variation regularization in time, with parameter "gamma_time" (the higher, the more regularized) and "tviter" iterations
+
+The number of iterations suggested here should work in most situations. The parameters gamma_space and gamma_time, on the other hand, must be adjusted carefully for each type of datasets (and, unfortunately, for each resolution). Unlike in analytical reconstruction methods like FDK, with 4D ROOSTER it is also very important that the reconstruction volume contains the whole patient's chest. You should therefore adapt the "dimension", "spacing" and "origin" parameters carefully, based on what you have observed on the blurry FDK reconstruction.
+
+```
+# Reconstruct from all projection images with 4D ROOSTER
+rtkfourdrooster
+  -p .
+  -r .*.his
+  -o rooster.mha
+  -g geometry.rtk
+  --signal sphase.txt
+  --motionmask MotionMask.mha
+  --gamma_time 0.0001
+  --gamma_space 0.0001
+  --niter 30
+  --cgiter 4
+  --tviter 10
+  --spacing 2
+  --dimension 160
+  --frames 5
+```
+
+Depending on the resolution you choose, and even on powerful computers, the reconstruction time can range from a few minutes (very low resolution, typically 32³ * 5, only for tests) to many hours (standard resolution, typically 256³ * 10). To speed things up, it is recommended to use the CUDA version of the forward and back projectors by running this command instead:
+
+```
+# Reconstruct from all projection images with 4D ROOSTER, using CUDA forward and back projectors
+rtkfourdrooster
+  -p .
+  -r .*.his
+  -o rooster.mha
+  -g geometry.rtk
+  --signal sphase.txt
+  --motionmask MotionMask.mha
+  --fp CudaRayCast
+  --bp CudaVoxelBased
+  --gamma_time 0.0001
+  --gamma_space 0.0001
+  --niter 30
+  --cgiter 4
+  --tviter 10
+  --spacing 2
+  --dimension 160
+  --frames 5
+```
+
+With a recent GPU, this should allow you to perform a standard resolution reconstruction in less than one hour.
+
+Note that the reconstructed volume in this example does not fully contain the attenuating object, causing hyper-attenuation artifacts on the borders of the result. To avoid these artifacts, reconstruct a larger volume (--dimension 256) should be fine. Note that you will have to resize your motion mask as well, as 3D the motion mask is expected to have the same size, spacing and origin as the first 3 dimensions of the 4D output.
+
+## Motion-Aware 4D Rooster
+==========================
+
+4D ROOSTER doesn't require explicit motion information, but can take advantage of it to guide TV-regularization if motion information is available. Please refer to the tutorial on Motion-Compensated FDK to learn how to obtain a valid 4D Displacement Vector Field (DVF). Once you have it, simply adding the option --dvf "4D_DVF_Filename" to the list of rtkfourdrooster arguments will run MA-ROOSTER instead of 4D ROOSTER.
+
+```
+# Reconstruct from all projection images with MA ROOSTER
+rtkfourdrooster
+  -p .
+  -r .*.his
+  -o rooster.mha
+  -g geometry.rtk
+  --signal sphase.txt
+  --motionmask MotionMask.mha
+  --gamma_time 0.0001
+  --gamma_space 0.0001
+  --niter 30
+  --cgiter 4
+  --tviter 10
+  --spacing 2
+  --dimension 160
+  --frames 5
+  --dvf deformationField_4D.mhd
+```
+
+Making use of the motion information adds to computation time. If you have compiled RTK with RTK_USE_CUDA = ON and have a working and CUDA-enabled nVidia GPU, it will automatically be used to speed up that part of the process.
+
+The article in which the theoretical foundations of MA-ROOSTER are presented (link to be added) contains results obtained on two patients. If you wish to reproduce these results, you can download all the necessary data here:
+
+*   Original projections, log-transformed projections with the table removed, motion mask, respiratory signal, and transform matrices to change from CT to CBCT coordinates and back
+    *   [Patient 1](https://data.kitware.com/api/v1/item/5be97d688d777f2179a28e39/download)
+    *   [Patient 2](https://data.kitware.com/api/v1/item/5be99df68d777f2179a2e904/download)
+*   Inverse-consistent 4D Displacement Vector Fields, to the end-exhale phase and from the end-exhale phase
+    *   [Patient 1](https://data.kitware.com/api/v1/item/5be989e68d777f2179a29e95/download)
+    *   [Patient 2](https://data.kitware.com/api/v1/item/5be9a1388d777f2179a2f44d/download)
+
+Extract the data of each patient in a separate folder. From the folder containing the data of patient 1, run the following command line:
+
+```
+# Reconstruct patient 1 with MA ROOSTER
+rtkfourdrooster
+  -p .
+  -r correctedProjs.mha
+  -o marooster.mha
+  -g geom.xml
+  --signal cphase.txt
+  --motionmask dilated_resampled_mm.mhd
+  --gamma_time 0.0002
+  --gamma_space 0.00005
+  --niter 10
+  --cgiter 4
+  --tviter 10
+  --spacing "1, 1, 1, 1"
+  --dimension "220, 280, 370, 10"
+  --origin "-140, -140, -75, 0"
+  --frames 10
+  --dvf toPhase50_4D.mhd
+  --idvf fromPhase50_4D.mhd
+```
+
+From the folder containing the data of patient 2, run the following command line (only the dimension and origin parameters are different):
+
+```
+# Reconstruct patient 2 with MA ROOSTER
+rtkfourdrooster
+  -p .
+  -r correctedProjs.mha
+  -o marooster.mha
+  -g geom.xml
+  --signal cphase.txt
+  --motionmask dilated_resampled_mm.mhd
+  --gamma_time 0.0002
+  --gamma_space 0.00005
+  --niter 10
+  --cgiter 4
+  --tviter 10
+  --spacing "1, 1, 1, 1"
+  --dimension "285, 270, 307, 10"
+  --origin "-167.5, -135, -205, 0"
+  --frames 10
+  --dvf toPhase50_4D.mhd
+  --idvf fromPhase50_4D.mhd
+```
+
+Note the option "--idvf", which allows to provide the inverse DVF. It is used to inverse warp the 4D reconstruction after the temporal regularization. MA-ROOSTER will work with and without the inverse DVF, and yield almost the same results in both cases. Not using the inverse DVF is approximately two times slower, as it requires MA-ROOSTER to perform the inverse warping by an iterative method.
+
+Again, if you have a CUDA-enabled GPU (in this case with at least 3 GB of VRAM), and have compiled RTK with RTK_USE_CUDA = ON, you can add the "--bp CudaVoxelBased" and "--fp CudaRayCast" to speed up the computation by performing the forward and back projections on the GPU.
+
+You do not need the 4D planning CT data to perform the MA-ROOSTER reconstructions. It is only required to compute the DVFs, which can be downloaded above. We do provide it anyway, in case you want to use your own method, or the one described in Motion-Compensated FDK, to extract a DVF from it:
+
+*   4D planning CT
+    *   [Patient 1](https://data.kitware.com/api/v1/item/5be98bd28d777f2179a2a279/download)
+    *   [Patient 2](https://data.kitware.com/api/v1/item/5be9a1918d777f2179a2f568/download)

examples/4DRooster/Signal.jpg.sha512

@@ -0,0 +1 @@
+7c265ec19e50310585f65ae90147ca1972225f93f35b090e233acfa081b084e329ed5b2d31fad23ec43e64d281937fad213d1229f5b717a98592518f6d56a7c2

examples/AmsterdamShroud/Amsterdam.png.sha512

@@ -0,0 +1 @@
+bf4f5bc8e887d7faf7dc9e835814b123a84dd617ef83343590411651f35a03083cc2d71cff6f7a3d8fd5b4b0fdd517871335650183238814de769f49ca07210e

examples/AmsterdamShroud/Moving-Phantom-Sinogram.png.sha512

@@ -0,0 +1 @@
+b31fe75d2f3ef6289e6dbca4bf7dc2675eebd80bfd25d61b167727587b796cf9b371f05db51949904699ceb3bf5cc681265ac7b4aa9b89ab632a2213e7bcca1d

examples/AmsterdamShroud/README.md

@@ -0,0 +1,13 @@
+# Amsterdam Shroud
+
+![sin](Moving-Phantom-Sinogram.png){w=400px alt="Moving phantom sinogram"}
+![img](Amsterdam.png){w=400px alt="Amsterdam image"}
+
+Picture 1 shows the sinogram of the input and picture 2 the shroud image that was created using the command line below.
+
+The script uses the file [movingPhantom.mha](https://data.kitware.com/api/v1/file/5be99c428d777f2179a2e537/download) as input:
+
+```
+# Creating an Amsterdam Shroud image from a set of projections
+rtkamsterdamshroud -p . -r movingPhantom.mha -o Amsterdam.mha
+ ```

examples/ConjugateGradient/Code3D.sh

@@ -0,0 +1,21 @@
+ # Create a simulated geometry
+ rtksimulatedgeometry -n 180 -o geometry.xml
+ # You may add "--arc 200" to make the scan short or "--proj_iso_x 200" to offset the detector
+
+ # Create projections of the phantom file
+ rtkprojectshepploganphantom -g geometry.xml -o projections.mha --spacing 2 --dimension 256
+
+ # Reconstruct
+ rtkconjugategradient -p . -r projections.mha -o 3dcg.mha -g geometry.xml --spacing 2 --dimension 256 -n 20
+
+ # Create a reference volume for comparison
+ rtkdrawshepploganphantom --spacing 2 --dimension 256 -o ref.mha
+
+  # Perform least squares reconstruction
+ rtkconjugategradient -p . -r noisyLineIntegrals.mha -o LeastSquares.mha -g geom.xml -n 20
+
+#  # Perform weighted least squares reconstruction
+#  rtkconjugategradient -p . -r noisyLineIntegrals.mha -o WeightedLeastSquares.mha -g geom.xml -w weightsmap.mha -n 20
+
+#  # Perform preconditioned conjugate gradient reconstruction with weighted least squares cost function
+#  rtkconjugategradient -p . -r noisyLineIntegrals.mha -o WeightedLeastSquares.mha -g geom.xml -w weightsmap.mha -n 20 --preconditioned

examples/ConjugateGradient/ConjugateGradient-Sinogram.png.sha512

@@ -0,0 +1 @@
+6a1b6bd8a92f84cbd9a7e7385216f15bef58c814e182c3598a0938f2b4d839b23e7237cbd536d5d6902c0720c7694b6b0b47742dae7ed350306b7cc6314b910a

examples/ConjugateGradient/ConjugateGradient.png.sha512

@@ -0,0 +1 @@
+8fa29a5ddbe658203faea0b1b3d48146904f1e2362d44385681cb7a96e2eba5b9d8a99f26a9c73c1a8fb24fe6d19891d1db3c57489c68fecb540f522703cf6fa