Merge branch 'updateModules' into 'master'

Update modules

See merge request !33

1

----
-title:     Image binarization
-layout:    module
-prerequisites:
-  - "[Basic properties of images and pixels](pixels)"
-objectives:
-  - "Describe the relationship between an intensity image and a derived binary image"
-  - "Apply a threshold to distinguish foreground and background pixels"
-motivation: >
-  Very often, one wants to detect objects or specific regions in images. Typically, the first step to achieve this aim is to distinguish so-called background pixels, which do not contain objects or interesting regions, from foreground pixels, which mark the areas of interest. The foreground regions can than be further processed, e.g to detect objects or perform measurements.      
-concept_map: >
-  graph TD
-    PV("Pixel values") --> BA(Binarization algorithm)
-    BA --> BPV("Binarized pixel values")
-    BPV --> BG("Background (0)")
-    BPV --> FG("Foreground (1)")
-
-figure: /figures/binarization.png
-figure_legend: An image before and after applying a threshold. Can you see what the treshold value was?
-
-activity_preface: >
-  Open an image and binarize it by applying a threshold.
-
-activities:
-  "ImageJ GUI": "binarization/activities/binarization_imagejgui.md"
-  "ImageJ Macro": "binarization/activities/binarization_imagejmacro.md"
-  "Jython": "binarization/activities/binarization_jython.md"
-  "MATLAB": "binarization/activities/binarization_matlab.md"
-
-exercises_preface: >
-
-  ### Fill in the blanks
-
-    - Pixels in a binary image can have maximally ___ different values.
-    - If the threshold is larger than the maximal pixel value in the intensity image, all pixels in the binary image have a value of ___.
-
-exercises:
-  "ImageJ GUI": "binarization/exercises/binarization_imagejgui.md"
-  "ImageJ Macro": "binarization/exercises/binarization_imagejmacro.md"
-  "Jython": "binarization/exercises/binarization_jython.md"
-  "MATLAB": "binarization/exercises/binarization_matlab.md"
-
-learn_next:
-  - "[Algorithms to automatically determine a threshold value](auto_threshold)"
-  - "[Finding objects in a binary image](connected_components)"
-
-external_links:
-  - "[Wikipedia: Binary image](https://en.wikipedia.org/wiki/Binary_image)"
----

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/filter_morphological.md

+---
+title:     Morphological filters
+layout:    page
+permalink: /filtermorphological
+---
+
+# Morphological filters
+
+## Requirements
+
+- Neighbourhood filters
+- Rank filters
+
+## Motivation
+
+This module explains how filters can be used to change size and shape of objects in the image.
+
+## Learning objectives
+- Understand how to design morphological filters using rank filters
+- Execute morpholofical filters on binary or grayscale images and explain the output
+
+## Concept map
+```mermaid
+graph TD
+    image --> max1[max]
+    image --> min1[min]
+    image --> max2[max]
+    image --> min2[min]
+    image --> d 
+subgraph rank filter sequence
+    max2 --> min3[min]
+    min2 --> max3[max]
+    max1
+    min1
+    d[max - min]
+    end
+    max1 --> dilation
+    min1 --> erosion
+    max3 --> opening
+    min3 --> closing
+    d --> gradient
+    subgraph morphological filter name
+    dilation
+    erosion
+    opening
+    closing
+    gradient
+    end
+```
+
+[*] Concept map above assumes bright objects on dark background. For dark objects on bright background effect of min and max filters inverses 
+
+### Activity: Explore erosion and dilation on binary images
+
+- Open image: xy_8bit_binary__two_spots_different_size.tif
+- Explore how structures grow and shrink, using erosion and dilation
+
+### Activity: Explore opening and closing on binary images
+
+- Open image: xy_8bit_binary__for_open_and_close.tif
+- Explore effects of morphological closing and opening:
+	- closing can fill holes
+	- closing can connect gaps
+	- opening can remove thin structures
+
+### Formative assessment
+
+Fill in the blanks, using those words: shrinks, increases, decreases, enlarges.
+
+1. An erosion _____ objects in a binary image. 
+2. An erosion in a binary image _____ the number of foreground pixels.
+3. A dilation in a grayscale image _____ the average intensity in the image.
+4. A dilation _____ objects in a binary image.
+
+
+True of false? Discuss with your neighbour!
+
+1. Morphological openings on binary images can decrease the number of foreground pixels.
+2. Morphological closings on binary images never decreases the number of foreground pixels.
+3. Performing a morphological closing a twice in a row does not make sense, because the second closing does not further change the image.
+
+## Learn more
+
+- https://en.wikipedia.org/wiki/Morphological_gradient
+- https://imagej.net/MorphoLibJ#Grayscale_morphological_filters

modules/filter_neighbourhood.md

+---
+title:     Neighbourhood image filters
+layout:    page
+permalink: /filtersneighbourhood
+---
+
+# Neighborhood filters
+
+## Requirements
+
+- Pixel properties
+
+## Motivation
+
+This module explains how image features (objects) can be enhanced using filters
+
+## Learning objectives
+
+- Understand the basic principle of a neighbourhood filter.
+
+## Concept map
+
+```mermaid
+graph TB
+	P(pixel) --> |has| NBH(neighbourhood pixels) 
+	NBH --> |are used in| A(mathematical formula)
+	A --> |compute new| NP(pixel value) 
+```
+
+|   |   |   |   |   |   |   |   |
+|---|---|---|---|---|---|---|---|
+| NC  | NC  | NC  |   |   |   |   |   |
+| NC  | C, NC  | NC  |   |   |   |   |   |
+| NC  | NC  | NC  |   |   |   |   |   |
+|   |   |   |   | NB  | NB  | NB  |   |
+|   |   |   |   |  NB | B, NB| NB  |   |
+|   |   |   |   |  NB |  NB |  NB |   |
+|   |   |   |   |   |   |   |   |
+
+## Example
+
+TODO: Mean filter image
+
+## Activity: Use mean filter to facilitate image binarization
+
+* Open image: xy_8bit__nuclei_noisy_different_intensity.tif
+* Appreciate that you cannot readily apply a threshold to binarize the image into two nuclei and background
+* Apply a mean filter, exploring different neighbourhood sizes
+* Appreciate that the filtered pixel values are slightly wrong due to integer data type
+* Binarize the filtered image by applying a threshold
+

modules/filter_rank.md

-# Neighborhood filters
+---
+title:     Rank filters
+layout:    page
+permalink: /filterrank
+---
 
-<img src='https://g.gravizo.com/svg?
- digraph G {
-    shift [fontcolor=white,color=white];
-	"neighbourhood filter" -> "central neighbourhood pixel" [label="  replaces"]; 
-	"neighbourhood filter" -> "size" [label="  has"];
-	"neighbourhood filter" -> "shape" [label="  has"];
-	"neighbourhood filter" -> "convolution filters";
- 	"neighbourhood filter" -> "rank filters";
-}
-'/>
+# Rank filters
 
+## Basic rank filters
 
-|   |   |   |   |   |   |   |   |
-|---|---|---|---|---|---|---|---|
-| NC  | NC  | NC  |   |   |   |   |   |
-| NC  | C, NC  | NC  |   |   |   |   |   |
-| NC  | NC  | NC  |   |   |   |   |   |
-|   |   |   |   | NB  | NB  | NB  |   |
-|   |   |   |   |  NB | B, NB| NB  |   |
-|   |   |   |   |  NB |  NB |  NB |   |
-|   |   |   |   |   |   |   |   |
+## Requirements
 
+To understand this episode you need to know:
 
+- Pixel properties
+- Neighbourhood filters
 
+## Motivation
 
+In this module one would learn basic principles of rank image filters and understand when using this type filters might be beneficial.
 
-# Rank filters
+## Learning objectives
 
-## Basic rank filters
-<img src='https://g.gravizo.com/svg?
- digraph G {
-    shift [fontcolor=white,color=white];
-	"rank filters" -> "neighbourhood filters" [label="  are"];
-	"rank filters" -> minimum; 
-	minimum -> erosion [label="  aka"];
-	"rank filters" -> maximum; 
-	maximum -> dilation [label="  aka"];
-	"rank filters" -> median;
-	"rank filters" -> "size" [label="  have"];
-  }
-'/>
+- Understand how rank filters function.
+- Execute and compare several rank filters.
+- Compare image smoothing using rank (e.g. median) vs another filter type (e.g. mean).
 
 
+## Concept map
+```mermaid
+graph TB
+	pixel --> values[neighbourhood pixel values] 
+	values --> sorted[sorted pixel values]
+	sorted --> min
+	sorted --> max
+	sorted --> median
+	sorted --> ...
+	subgraph rank value
+	min
+	max
+	median
+	...
+	end
+	min --> fpixel[filtered image pixel]
+	max --> fpixel
+	median --> fpixel
+	... --> fpixel
+```
 
-### Activity: Explore rank filters on binary images
-
-- Open image: xy_8bit_binary__two_spots_different_size.tif
-- Explore how structures grow and shrink, using erosion and dilation
 
 ### Activity: Explore rank filters on grayscale images
 
@@ -66,130 +65,8 @@ True or false? Discuss with your neighbour!
 1. Median filter is just another name for mean filter.
 2. Small structures can completely disappear from an image when applying a median filter.
 
-Fill in the blanks, using those words: shrinks, increases, decreases, enlarges.
-
-1. An erosion _____ objects in a binary image. 
-2. An erosion in a binary image _____ the number of foreground pixels.
-3. A dilation in a grayscale image _____ the average intensity in the image.
-4. A dilation _____ objects in a binary image.
-
-
-## Morphological opening and closing
-
-<img src='https://g.gravizo.com/svg?
- digraph G {
-    shift [fontcolor=white,color=white];
-        "opening" -> "rank filter sequence" [label="  is"];
-        "closing" -> "rank filter sequence" [label="  is"];
-	"opening" -> "removes small structures";
-	"closing" -> "fills small gaps";
-  }
-'/>
-
-```
-opening( image, r ) = dilation( erosion( image, r ), r )
-```
-
-```
-closing( image, r ) = erosion( dilation( image, r ), r )
-```
-
-
-### Activity: Explore opening and closing on binary images
-
-- Open image: xy_8bit_binary__for_open_and_close.tif
-- Explore effects of morphological closing and opening:
-	- closing can fill holes
-	- closing can connect gaps
-	- opening can remove thin structures
-
-
-### Formative assessment
-
-True of false? Discuss with your neighbour!
-
-1. Morphological openings on binary images can decrease the number of foreground pixels.
-2. Morphological closings on binary images never decreases the number of foreground pixels.
-3. Performing a morphological closing a twice in a row does not make sense, because the second closing does not further change the image.   
-
-## Top hat filter for local background subtraction
-
-<img src='https://g.gravizo.com/svg?
- digraph G {
-    shift [fontcolor=white,color=white];
-	"tophat" -> "rank filter sequence"; 
-	"tophat" -> "local background subtraction";
-  }
-'/>
-
-
-```
-tophat( image ) = image - opening( image, r ) =  image - dilation( erosion( image, r), r )
-```
-
-
-### Activity: Explore tophat filter
-
-- Open image: xy_8bit__spots_local_background.tif
-- Use a tophat filter to remove local background
-
-## Activity: Implement a tophat filter
-
-- Devise code implementing a tophat filter, using minimum and maximum filters
-
-## Activity: Explore tophat filter on biological data
-
-- Open image: xy_16bit__autophagosomes.tif 
-- Appreciate that you cannot readliy segment the spots.
-- Use a tophat filter to remove local background.
-- Threshold the spots in the tophat filtered image.
-
-## Activity: Explore tophat filter on noisy data
-
-- Open image: xy_8bit__spots_local_background_with_noise.tif 
-- Use topHat filter to remove local background
-- Appreciate that noise poses a challenge to the tophat filter
-
-## Median filter for local background subtraction
-
-<img src='https://g.gravizo.com/svg?
- digraph G {
-    shift [fontcolor=white,color=white];
-	"median" -> "local background" [label="  approximates"];
-	"median" -> "radius" -> "> object width";
-	"radius" -> "< spatial background frequency";
-  }
-'/>
-
-
-```
-median_based_background_correction = image - median( image, r)
-```
-
-### Activity: Implement median based background subtraction
-
-- Write code to implement a median based background subtraction
-
-
-### Activity: Explore median filter for local background subtraction
-
-- Open images: 
-	- xy_8bit__spots_local_background.tif 
-	- xy_8bit__spots_local_background_with_noise.tif 
-- Use tophat filter to remove local background
-- Devise code to implement a tophat filter using basic functions
-
-### Formative assessment
-
-Answer below questions. Discuss with your neighbour!
-
-1. What could one do to close small gaps in a binary image? 
-2. What could one do to remove small objects in a image?
-3. What could you use for local background subtraction in a very noisy image?
-
-## Learn more
-
-- https://imagej.net/MorphoLibJ#Grayscale_morphological_filters
 
+### Learn next
 
+- median based local background subtraction
 

modules/html/image_pixels.html

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

modules/display.md → modules/image_display.md

@@ -3,6 +3,10 @@ title:     Image display
 layout:    page
 ---
 
+# Prerequisites
+
+- image_pixel_content
+
 # Image display
 
 <img src='https://g.gravizo.com/svg?
@@ -19,6 +23,9 @@ layout:    page
 ```
 brightness = ( value - min ) / ( max - min )
 
+if ( brightness < 0 ) set to zero
+if ( brightness > 1 ) set to one
+
 0 <= brightness <= 1
 
 contrast = max - min
@@ -26,16 +33,26 @@ 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.
+* Open image: xy_16bit__nuclei_high_dynamic_range.tif 
+* Explore different single color LUTs and LUT settings
+* Appreciate that LUT settings do not change the pixel values
+* Explore multi-color LUT for visualisation of high dynamic range images
+	* Add a LUT calibration bar to the image
 
 
 ## Formative Assessment
 
+### Fill in the blanks
+
 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.
+
+### TODO: Comparative image display
+
+Open two images and display with the same LUT settings.
+
+

modules/pixels.md → modules/image_pixels.md

 ---
-title:     Pixels 
+title:     Image pixels 
 layout:    page
 ---
 
@@ -14,6 +14,7 @@ layout:    page
     pixel -> value;
     pixel -> indices;
     pixel -> voxel [label="  3D"];
+    pixel -> size [label="  can have"]
   }
 '/>
 
@@ -24,6 +25,18 @@ layout:    page
 * Check where the lowest pixel indices are in the displayed image:
         * Most commonly: Upper left corner, which is different to conventional coordinate systems.
 
+## Activity: Explore image calibration
+
+* Open image: xyz_8bit_calibrated_anisotropic__mri_head.tif
+* Check the calibration of this image
+* Explore how image calibration affects spatial measurements, e.g.,
+  * Measure the distance between two pixels in the image
+  * Measure the size of an image region
+* Appreciate that image calibration might be neccessary, e.g.
+  * 3D distance measurements
+* Appreciate that image calibration can be confusing, e.g.
+  * not consistently used in image filter parameter specification
+
 ## Formative assessment
 
 True or false?

modules/local_background_subtraction.md

+---
+title:     Local background subtraction
+layout:    page
+permalink: /localbackground
+---
+
+# Local background subtraction
+
+
+## Requirements
+
+- Neighbourhood filters
+- Rank filters
+- Convolutional filters
+- Pixel math
+
+## Motivation
+
+This module explains how to remove background which has different values in different image parts.
+
+## Learning objectives
+
+- Understand how to use filters to create background image
+- Learn differences between different methods/filters for generating background image 
+- Practice background subtraction
+
+
+## Concept map
+
+```mermaid
+graph TD;
+    image --> smooth1[small radius filter]
+    image --> smooth2[big radius filter]
+    smooth1 --> image1[Noise suppressed image]
+    smooth2 --> image2[Background image]
+    image1 --> subtraction["[Noise suppressed image] - [Background image]"]
+    image2 --> subtraction
+    subtraction --> result[Background subtracted image]
+```
+
+## Possible filters for creating bacground image
+
+- Median filter
+- Opening filter: the result of background subtraction operation is called **Top-Hat filter**
+- Gaussian filter
+
+
+## Activity: Implement a tophat filter
+- Devise code implementing a tophat filter, using minimum and maximum filters
+
+
+### Activity: Explore tophat filter
+
+- Open image: xy_8bit__spots_local_background.tif
+- Use a tophat filter to remove local background
+
+## Activity: Explore tophat filter on biological data
+
+- Open image: xy_16bit__autophagosomes.tif 
+- Appreciate that you cannot readliy segment the spots.
+- Use a tophat filter to remove local background.
+- Threshold the spots in the tophat filtered image.
+
+## Activity: Explore tophat filter on noisy data
+
+- Open image: xy_8bit__spots_local_background_with_noise.tif 
+- Use topHat filter to remove local background
+- Appreciate that noise poses a challenge to the tophat filter
+
+
+### Activity: Implement median based background subtraction
+
+- Write code to implement a median based background subtraction
+
+### Activity: Explore median filter for local background subtraction