Finalise quick-start.

#69

docs_source/source/quick_start.rst

@@ -45,16 +45,16 @@ every patient. These can combined into a single ``pandas.DataFrame`` as follows:
 
     feature_data = pd.concat(feature_data)
 
-Computing quantitative features from filtered images
-----------------------------------------------------
+Visualising filtered images
+---------------------------
 Image filters enhance aspects such as edges, blobs and directional structures. MIRP supports several filters (see
 :ref:`quantitative_image_analysis`). Suppose you want to use a Laplacian-of-Gaussian filter, with the width of the
 Gaussian equal to 2.0 mm.
 
 We can first inspect the images visually using ``extract_images``. By default, ``export_images`` exports images and
-masks as dictionary with ``numpy`` data and metadata (or as NIfTI files, in case ``write_dir`` is provided). However,
-MIRP has a simple viewer for its own internal format. To use this viewer, you can set ``image_export_format =
-"native"``.
+masks as dictionary with ``numpy`` data and metadata (or as NIfTI files, in case ``write_dir`` is provided). These
+can be used with external viewers, or your own scripts. MIRP also has a simple viewer for its internal native
+image objects. To use this viewer, you can set ``image_export_format = "native"``.
 
 .. code-block:: python
 
@@ -89,14 +89,14 @@ using the ``show`` method:
     # View the Laplacian-of-Gaussian filtered image
     patient_1_log_image.show()
 
-Of course, features can also be computed from filtered images (also called response maps). By default, only
+Computing quantitative features from filtered images
+----------------------------------------------------
+
+Of course, features can also be computed from filtered images (also known as response maps). By default, only
 statistical features [Zwanenburg2016]_ are computed from filtered images.
 
 .. code-block:: python
 
-    import pandas as pd
-    from mirp import extract_features
-
     feature_data = extract_features(
         image="path/to/data",
         mask="path/to/data",
@@ -113,8 +113,58 @@ statistical features [Zwanenburg2016]_ are computed from filtered images.
 
     feature_data = pd.concat(feature_data)
 
+``feature_data`` is a ``pandas.DataFrame`` similar to the first example, but with features computed from the
+Laplacian-of-Gaussian image appended as new columns.
+
+Processing images
+-----------------
+
+Computing quantitative features is nice, but what if you use deep learning instead? Suppose you just want to process
+images as input for a VGG16 network [Simonyan2015]_. These networks have a default input size of 224 by 224 pixels.
+For many deep learning applications, images should be provided 1-by-1, and we therefore will use a generator. By
+providing the name of the region of interest, images will be cropped based on the center of the mask:
+
+.. code-block:: python
+
+    from mirp import deep_learning_preprocessing_generator
+
+    image_generator = deep_learning_preprocessing_generator(
+        image="path/to/data",
+        mask="path/to/data",
+        image_sub_folder="image",
+        mask_sub_folder="mask",
+        roi_name="GTV",
+        new_spacing=1.0,
+        crop_size=[224, 224],
+        output_slices=True
+    )
+
+    image_slices, mask_slices = next(image_generator)
+
+The generator yields a set of image slices (each 224 by 224 pixels) with corresponding masks. ``output_slices=False``
+can be used to generate 3D volumes.
+
+Extracting metadata
+-------------------
+
+DICOM files contains metadata that are relevant to report in studies. MIRP can extract and collect such metadata:
+
+.. code-block:: python
+
+    from mirp import extract_image_parameters
+
+    image_parameters = extract_image_parameters(
+        image="path/to/data",
+        image_sub_folder="image"
+    )
+
+``image_parameters`` is a ``pandas.DataFrame`` that contains relevant parameters extracted from DICOM metadata, such
+as image resolution, scanner type and vendor as well as modality-specific attributes such as tube voltage for CT.
+Note that metadata for other file types (e.g. NIfTI) are considerably more limited.
 
 References
 ----------
-.. [Zwanenburg2016] Zwanenburg A, Leger S, Vallieres M, Loeck S. Image biomarker standardisation initiative. arXiv
-  [cs.CV] 2016. doi:10.48550/arXiv.1612.070035
+.. [Zwanenburg2016] Zwanenburg A, Leger S, Vallieres M, Loeck S. Image Biomarker Standardisation Initiative. arXiv
+  [cs.CV] 2016. doi:10.48550/arXiv.1612.070035
+.. [Simonyan2015] Simonyan K, Zisserman A. Very Deep Convolutional Networks for Large-Scale Image Recognition. arXiv
+  [cs.CV] 2014. doi:10.48550/arXiv.1409.1556

test/documentation_example_test.py

@@ -72,6 +72,34 @@ def test_quick_start():
 
     assert len(feature_data) == 3
 
+    # Quick-start example 4 (processing images)
+    from mirp import deep_learning_preprocessing_generator
+
+    image_generator = deep_learning_preprocessing_generator(
+        image=os.path.join(CURRENT_DIR, "data", "sts_images"),
+        mask=os.path.join(CURRENT_DIR, "data", "sts_images"),
+        image_sub_folder=os.path.join("CT", "dicom", "image"),
+        mask_sub_folder=os.path.join("CT", "dicom", "mask"),
+        roi_name="GTV_Mass_CT",
+        new_spacing=1.0,
+        crop_size=[224, 224],
+        output_slices=True
+    )
+
+    image_slices, mask_slices = next(image_generator)
+    assert len(image_slices) > 1
+    assert len(mask_slices) > 1
+
+    # Quick-start example 5 (extract metadata)
+    from mirp import extract_image_parameters
+
+    image_parameters = extract_image_parameters(
+        image=os.path.join(CURRENT_DIR, "data", "sts_images"),
+        image_sub_folder=os.path.join("CT", "dicom", "image")
+    )
+
+    assert len(image_parameters) == 3
+
 
 def test_extract_features_examples():
     from mirp import extract_features