Merge branch 'moduleRefactoring' into 'master'

Module refactoring

See merge request grp-bio-it/image-analysis-training-resources!16

modules/basic_image_analysis_workflow.md

+---
+title:     Basic image analysis workflow
+layout:    page
+---
+
+## Typical image analysis workflow
+
+![image](/uploads/b4bdce17515908f40d858b35d5e9256e/image.png)
+

modules/calibration.md

+---
+title:     Image calibration
+layout:    page
+---
+
+## Image calibration
+
+<img src='https://g.gravizo.com/svg?
+ digraph G {
+    shift [fontcolor=white,color=white];
+    pixel -> indices;
+    pixel -> coordinates;
+    indices -> calibration;
+    calibration -> coordinates;
+    calibration -> anisotropic [label="  can be"];
+    image -> calibration [label="  can have"];
+  }
+'/>
+
+
+### Activity: Explore image calibration
+
+* Open image: xy_8bit__nuclei_noisy_different_intensity.tif
+* Add image calibration
+* Explore whether and how this affects image display and measurements (e.g. distance between two points)
+
+
+### Activity: Explore anisotropic 3D image data
+
+* Open image: xy_8bit_calibrated_anisotropic__mri_stack.tif
+        * Appreciate that the pixels are anisotropic
+
+
+### Formative assessment
+
+True or false?
+
+* Changing the image calibration changes the pixel values.
+* Pixel coordinates depend on image calibration.
+
+

modules/connected_components.md

+---
+title:     Connected components 
+layout:    page
+---
+
+## Connected components analysis
+
+<img src='https://g.gravizo.com/svg?
+ digraph G {
+    shift [fontcolor=white,color=white];
+    "intensity image" -> "connected component analysis" -> "label image";
+    connectivity -> "connected component analysis";
+  }
+'/>
+
+
+### Activity: 2D connected components analysis
+
+* Open image: xy_8bit_binary__nuclei.tif
+* Perform connected components analysis
+* Explore multi-color LUTs for object labelling
+* Explore removing and joining labels
+
+
+### Activity: 3D connected components analysis
+
+Repeat above activity but use a 3D image:
+
+* Open image: xyz_8bit_binary__spots.tif
+
+### Formative assessment
+
+Fill in the blanks, using these words: less, more, 8, 255, 4, more.
+
+1. In 3D, pixels have _____ neighbors than in 2D.
+2. 8-connected connectivity results in _____ objects than 4-connected connectivity.
+3. In 3D, pixels have ____ non-diagonal neighbors.
+4. In 2D, pixels have ____ non-diagonal neighbors.
+5. A 8-bit label image can maximally have _____ objects.
+6. The maximum value in a label image is equal to or _____ than the number of objects.
+
+## Learn next
+
+- shape_measurements.md

modules/course-preamble.md

-# Course preamble
-
-<img src='https://g.gravizo.com/svg?
- digraph G {
-        shift [fontcolor=white,color=white];
-        "learn" -> "concepts";
-	"concepts" -> "software independent" [label="  are"];
-}
-'/>
-
-
-The focus of this course it **not** to learn a specific image analysis software.
-
-In fact, one could probably teach most concepts without a computer. 
-

modules/display.md

+---
+title:     Image display
+layout:    page
+---
+
+# Image display
+
+<img src='https://g.gravizo.com/svg?
+ digraph G {
+    shift [fontcolor=white,color=white];
+    LUT -> color;
+    LUT -> brightness;
+    min -> LUT;
+    max -> LUT;
+    value -> LUT;
+  }
+'/>
+
+```
+brightness = ( value - min ) / ( max - min )
+
+0 <= brightness <= 1
+
+contrast = max - min
+```
+
+## Activity
+
+* Open image: xy_8bit__nuclei_noisy_different_intensity.tif
+* Explore different LUTs and LUT settings
+        * Appreciate that LUT settings do not affect image content.
+
+
+## Formative Assessment
+
+Fill in the blanks, using those words: decrease, larger than, increase, smaller than
+
+1. Pixels with values _____ `max` will appear saturated.
+2. Decreasing `max` while keeping `min` constant will _____ the contrast.
+3. Decreasing both `max` and `min` will _____ the overall brightness.
+4. Pixels with values _____ the `min` will appear black, when using a grayscale LUT.

modules/enhance_image_features.md

+# Image feature enhancement
+
+<img src='https://g.gravizo.com/svg?
+digraph G {
+    shift [fontcolor=white,color=white];
+    image -> filter -> "enhanced image";
+    node [shape=box, color=grey, fontcolor=grey];
+    "enhanced image" -> "feature" [label=" aka", style=dashed, color=grey, fontcolor=grey, fontsize=10];
+    "feature enhancement" [shape=box, color=grey, fontcolor=grey, margin=0.05];
+    filter -> "feature enhancement" [label=" aka", style=dashed, color=grey, fontcolor=grey, fontsize=10];   
+}
+'/>
+
+## Examples
+
+- Difference of Gaussian filter enhances spots
+- ...
+
+## Learn next
+
+- filter_difference_of_gaussian.md

modules/filter_convolution.md

+---
+title:     Image math
+layout:    page
+---
+
+## Convolution filters
+
+<img src='https://g.gravizo.com/svg?
+ digraph G {
+    shift [fontcolor=white,color=white];
+    "intensity image" -> "convolution" -> "filtered image";
+    "small image" -> size;
+    "small image" -> "pixel values";
+    "kernel" -> "small image" [label="  is"];
+    "kernel" -> "convolution";
+}
+'/>
+
+### Activity: Explore convolution filters
+
+* Open image: xy_8bit__nuclei_noisy_different_intensity.tif
+* Try the result of different convolution filters, e.g.
+        * https://en.wikipedia.org/wiki/Kernel_(image_processing)
+        * Mean filter
+        * Gaussian blur
+        * Edge detection
+* Appreciate that the results are (slightly) wrong within the 8-bit range of the input image.
+
+### Activity: Use mean filter to facilitate image segmentation
+
+* Open image: xy_8bit__nuclei_noisy_different_intensity.tif
+* Appreciate that you cannot readily threshold the image
+* Apply a mean filter
+* Threshold the filtered image
+
+### Formative assessment
+
+* Draw the kernel of a 3x3 mean filter.
+* Draw three different kernels that enhance edges.
+
+### Learn more
+
+* https://en.wikipedia.org/wiki/Kernel_(image_processing)

modules/image-feature-enhancement.md → modules/filter_difference_of_gaussian.md

-# Image feature enhancement
+---
+title:     Difference of Gaussian
+layout:    page
+---
 
-
-<img src='https://g.gravizo.com/svg?
-digraph G {
-    shift [fontcolor=white,color=white];
-    image -> filter -> "enhanced image";
-    node [shape=box, color=grey, fontcolor=grey];
-    "enhanced image" -> "feature" [label=" aka", style=dashed, color=grey, fontcolor=grey, fontsize=10];
-    "feature enhancement" [shape=box, color=grey, fontcolor=grey, margin=0.05];
-    filter -> "feature enhancement" [label=" aka", style=dashed, color=grey, fontcolor=grey, fontsize=10];   
-}
-'/>
-
-
-## Difference of Gaussian (DoG) for spot enhancement
+## Difference of Gaussian (DoG)
 
 <img src='https://g.gravizo.com/svg?
  digraph G {
-	shift [fontcolor=white,color=white];
-	image -> "small blur";
-	image -> "large blur";
-	"small blur" -> "noise filtered";
-	"large blur" -> "local background";
-	"small blur" -> "small blur - large blur" -> "DoG";
-	"large blur" -> "small blur - large blur" -> "DoG";
-	"DoG" -> "Laplacian of Gaussian (LoG)" [label="  is related"];	
+        shift [fontcolor=white,color=white];
+        image -> "small blur";
+        image -> "large blur";
+        "small blur" -> "noise filtered";
+        "large blur" -> "local background";
+        "small blur" -> "small blur - large blur" -> "DoG";
+        "large blur" -> "small blur - large blur" -> "DoG";
+        "DoG" -> "Laplacian of Gaussian (LoG)" [label="  is related"];
 }
 '/>
 
@@ -33,12 +23,12 @@ digraph G {
 - Open image: xy_8bit__two_spots_noisy_uneven_background.tif
 - Appreciate that you cannot readily threshold the spots
 - Compute DoG:
-	- Copy image and blur with a Gaussian of small sigma -> Gs
-	- Copy image and blur with a Gaussian of bigger sigma -> Gb
-		- For the official DoG: `rb = sqrt(2) * rs`
-	- Create `DoG = Gs - Gb`
+        - Copy image and blur with a Gaussian of small sigma -> Gs
+        - Copy image and blur with a Gaussian of bigger sigma -> Gb
+                - For the official DoG: `rb = sqrt(2) * rs`
+        - Create `DoG = Gs - Gb`
 - Appreciate that now it is possible to threshold the spots in the DoG image
- 
+
 ### Learn more
 
 - https://imagescience.org/meijering/software/featurej/
@@ -46,8 +36,3 @@ digraph G {
 - https://github.com/CellProfiler/CellProfiler/blob/master/cellprofiler/modules/enhanceorsuppressfeatures.py#L4
 
 
-### Formative Assessment
-
-TODO
-
-

modules/image-binariztion.md

-# Image binarization
- 
-<img src='https://g.gravizo.com/svg?
- digraph G {
-    shift [fontcolor=white,color=white];
-    intenstiy_image -> threshold;
-    threshold -> background [label="  <threshold"];
-    threshold -> foreground [label="  >=threshold"];
-    background -> binaryimage;
-	foreground -> binaryimage;
-	binaryimage -> 0 [label="  background"];
-	binaryimage -> 1 [label="  foreground"];   
-  }
-'/>

modules/measure_intensities.md

+---
+title:     Intensity measurements 
+layout:    page
+---
+
+## Intensity measurements
+
+### Activity: Measure intensities in image regions
+
+* Open image: xy_float__h2b_bg_corr.tif
+* Measure for both nuclei:
+        * Maximum intensity
+        * Average intensity
+        * Median intensity
+        * Sum intensity
+* Discuss the interpretation!
+* Discuss where to measure!
+
+
+### Activity: Intensity measurements without pixel based background correction
+
+#### Motivation
+
+There are several good reasons not to subtract the background from each pixel in an image:
+
+* It is a bit tricky to do it right, because one has to convert to float to accomodate floting point and negative values.
+* If one has really big image data (TB) one would need (at least) another TB storage for the background corrected version of the image.
+
+#### Workflow
+
+* Open image: xy_calibrated_8bit__two_nuclei_high_background.tif
+* Measure for both nuclei and a background region:
+        * Maximum intensity
+        * Average intensity
+        * Median intensity
+        * Sum intensity
+* Discuss how to correct the intensities for the background
+        * Appreciate that you also need the region areas for this task
+        * Measure the region areas
+                * Watch out: the image is calibrated!
+                * Use the area for the correction.
+
+### Formative assessment: Intensity measurements
+
+Fill in the blanks, using these words: integrated, mean, number_of_pixels, decrease, increase, sum
+
+1. Average intensity is just another word for _____ intensity.
+2. The _____ intensity is equal to the mean intensity times the _____ in the measured region.
+3. In an 8-bit image, increasing the size of the measurement region can only _____ the sum intensity.
+4. In a float image, increasing the size of the measurement region can _____ the sum intensity.
+

modules/measure_shapes.md

+---
+title:     Object shape measurements 
+layout:    page
+---
+
+## Shape measurements
+
+<img src='https://g.gravizo.com/svg?
+ digraph G {
+        shift [fontcolor=white,color=white];
+        "label image" -> shape_analysis -> table;
+        table -> object_rows;
+        table -> feature_columns;
+        table -> visualisation;
+}
+'/>
+
+
+### Activity: Measure object shape parameters
+
+* Open image: xy_8bit_labels__four_objects.tif
+* Perform shape measurements and discuss their meanings.
+* Explore results visualisation
+        * Color objects by their measurement values.
+* Add a calibration to the image and check which shape measurements are affected.
+* Draw a test image to understand the shape measurements even better.
+
+### Activity: Explore sampling limits
+
+* Draw a square (=circle) of 2x2 pixels (paper, whiteboard, ...)
+        * Measure area, perimeter and circularity
+        * Discuss the results
+* Discuss the England's coastline paradox
+
+
+### Formative assessment
+
+True or false? Discuss with your neighbour!
+
+* Circularity is independent of image calibration.
+* Area is independent of image calibration.
+* Perimeter can strongly depend on spatial sampling.
+* Volume can strongly depend on spatial sampling.
+* Drawing test images to check how certain shape parameters behave is a good idea.
+
+### Learn more
+
+* Especially surface and perimeter measurements are affected by sampling and resolution, see for example:
+        * https://en.wikipedia.org/wiki/Coastline_paradox).
+* Results visualisation:
+        * https://imagej.net/MorphoLibJ#Grayscale_morphological_filters: **Label visualization in 3D viewer**
+
+## Learn next
+
+- object_shape_measurement_workflow.md
+- intensity_measurements.md

modules/object-splitting.md → modules/object_splitting.md

+---
+title:     Object splitting
+layout:    page
+---
+
 # Object splitting
 
+## Requirements
+
+- binarisation.md
+- distance_transform.md
+
 ## "Intensity based" watershed
 
 <img src='https://g.gravizo.com/svg?
@@ -10,7 +20,6 @@
 }
 '/>
 
-
 ### Activity: Explore intensity based watershed 
 
 - Open image: xy_8bit__touching_objects.tif

modules/pixel_data_types.md

+---
+title:     Pixel data types
+layout:    page
+---
+
+## Pixel data types
+
+<img src='https://g.gravizo.com/svg?
+ digraph G {
+    shift [fontcolor=white,color=white];
+    "data type" -> "pixel values" [label="  restricts"];
+    "N-bit unsigned integer" -> "0, 1, ..., 2^N-1";
+    "data type" -> float -> "..., -1031.0, ..., 10.5, ...";
+    "data type" -> "...";
+    "data type" -> "N-bit unsigned integer";
+  }
+'/>
+
+## Pixel data type conversions
+
+<img src='https://g.gravizo.com/svg?
+ digraph G {
+    shift [fontcolor=white,color=white];
+    "data type conversion" -> "values" [label="  can change"];
+    "data type conversion" -> "value range" [label="  changes"];
+  }
+'/>
+
+### Activity: 16-bit to 8-bit conversion
+
+* Open image: xy_16bit__two_values.tif
+* Convert to 8-bit
+* Understand the mathematics underlying the conversion from 16-bit to 8-bit.
+
+### Activity: 16-bit to float conversion
+
+* Open image: xy_16bit__two_values.tif
+* Convert to float
+
+### Formative Assessment
+
+True or false? Discuss with your neighbor!
+
+1. Changing pixel data type never changes pixel values.
+2. Converting from 16-bit unsigned integer to float never changes the pixel values.
+3. Changing from float to 16-bit unsigned integer never changes the pixel values.
+4. There is only one correct way to convert from 16-bit to 8-bit.
+

modules/pixel_math.md

+---
+title:     Image math
+layout:    page
+---
+
+## Image math 
+
+<img src='https://g.gravizo.com/svg?
+ digraph G {
+    shift [fontcolor=white,color=white];
+    "data type" -> "pixel values" [label="  restricts"];
+    "image math" -> "pixel values" [label="  changes"];
+    "N-bit unsigned integer" -> "0, 1, ..., 2^N-1";
+    "data type" -> float -> "..., -1031.0, ..., 10.5, ...";
+    "data type" -> "...";
+    "data type" -> "N-bit unsigned integer";
+  }
+'/>
+
+### Activity: Pixel based background subtraction
+
+* Open image: xy_8bit__nuclei_noisy_different_intensity.tif
+* Appreciate the significant background intensity
+* Measure pixel values at `[ 28, 35 ]` and `[ 28, 39 ]`
+* Measure the image background intensity in this region:
+    * upper left corner at `[ 20, 35 ]`
+    * width = 10
+    * height = 10
+* Subtract the measured background intensity from each pixel.
+* Measure the pixel values again.
+* Observe that the resuls are incorrect.
+
+Repeat above activity, but:
+
+* After opening the image, convert its data type to floating point.
+
+### Activity: Explore the limitations of `float` data type
+
+* Create an empty image
+* Set all pixel values to 1000000000.0
+* Add 1.0 to all pixel values
+* Be shocked...
+
+...it turns out that from 16777216 on you cannot represent all integers anymore within a float.
+
+### Formative Assessment
+
+True or false?
+
+* Subtracting 100 from 50 in a 8-bit image will result in -50.
+* Adding 1 to 255 in a 8-bit image will result in 256.
+* Subtracting 10.1 from 10.0 in a float image will result in -0.1
+* Adding 1.0 to 255.0 in a float image will result in 256.0
+* Adding 1000.0 to 1000000000.0 in a float image will result in 1000001000.0
+
+### Learn more
+
+* [Limitations of float](https://randomascii.wordpress.com/2012/02/13/dont-store-that-in-a-float/)
+

modules/pixels.md

+---
+title:     Pixels 
+layout:    page
+---
+
+# Pixels
+
+## Concept map
+
+<img src='https://g.gravizo.com/svg?
+ digraph G {
+    shift [fontcolor=white,color=white];
+    image -> pixel [label="  has many"];
+    pixel -> value;
+    pixel -> indices;
+    pixel -> voxel [label="  3D"];
+  }
+'/>
+
+## Activity: Explore pixel values and indices
+
+* Open image: xy_8bit__nuclei_noisy_different_intensity.tif
+* Explore different ways to inspect pixel values and indices
+* Check where the lowest pixel indices are in the displayed image:
+        * Most commonly: Upper left corner, which is different to conventional coordinate systems.
+
+## Formative assessment
+
+True or false?
+
+* The lowest pixel index of a 2D image always is `[1,1]`.
+* When looking at a 2D image, the lowest pixel indices are always in the lower left corner.
+
+## Learn next
+
+- display.md

modules/teaching-tips.md

-# Teaching tips
-
-## White-boards
-
-- Try to frequently use white-board, because:
-	- It makes teaching more interactive.
-	- It slows down teaching, because you have to draw.
-- Make sure you have good pens with high contrast.
-- Have two white-boards:
-	- One for tidy concept maps.
-	- One for messy notes.
-
-## Stand
-
-- Try not to sit, because:
-	- Teaching will be more dynamic.
-	- People can see and hear you better.
-- Construct something to have your computer up, such that you can stand in front of it.
-