From e8fe61d7c5803a09930c1cb3cb1114d0b49b58e1 Mon Sep 17 00:00:00 2001 From: Marco Dalla Vecchia Date: Sun, 29 Mar 2026 17:24:17 +0200 Subject: [PATCH 1/4] formatted edge-detection lesson --- learners/edge-detection.md | 290 +++++++------------------------------ 1 file changed, 53 insertions(+), 237 deletions(-) diff --git a/learners/edge-detection.md b/learners/edge-detection.md index b0cf3f7..1e9bf17 100644 --- a/learners/edge-detection.md +++ b/learners/edge-detection.md @@ -13,138 +13,54 @@ exercises: 0 :::::::::::::::::::::::::::::: objectives - Apply Canny edge detection to an image. -- Explain how we can use sliders to expedite finding appropriate parameter values - for our scikit-image function calls. +- Explain how we can use sliders to expedite finding appropriate parameter values for our scikit-image function calls. - Create scikit-image windows with sliders and associated callback functions. ::::::::::::::::::::::::::::::::::::::::: -In this episode, we will learn how to use scikit-image functions to apply *edge -detection* to an image. -In edge detection, we find the boundaries or edges of objects in an image, -by determining where the brightness of the image changes dramatically. -Edge detection can be used to extract the structure of objects in an image. -If we are interested in the number, -size, -shape, -or relative location of objects in an image, -edge detection allows us to focus on the parts of the image most helpful, -while ignoring parts of the image that will not help us. - -For example, once we have found the edges of the objects in the image -(or once we have converted the image to binary using thresholding), -we can use that information to find the image *contours*, -which we will learn about in -[the *Connected Component Analysis* episode](../episodes/06-processing-segmentation.md). -With the contours, -we can do things like counting the number of objects in the image, -measure the size of the objects, classify the shapes of the objects, and so on. - -As was the case for blurring and thresholding, -there are several different methods in scikit-image that can be used for edge detection, -so we will examine only one in detail. +In this episode, we will learn how to use scikit-image functions to apply *edge detection* to an image. In edge detection, we find the boundaries or edges of objects in an image, by determining where the brightness of the image changes dramatically. Edge detection can be used to extract the structure of objects in an image. If we are interested in the number, size, shape, or relative location of objects in an image, edge detection allows us to focus on the parts of the image most helpful, while ignoring parts of the image that will not help us. + +For example, once we have found the edges of the objects in the image (or once we have converted the image to binary using thresholding), we can use that information to find the image *contours*, which we will learn about in [the *Connected Component Analysis* episode](../episodes/06-processing-segmentation.md). With the contours, we can do things like counting the number of objects in the image, measure the size of the objects, classify the shapes of the objects, and so on. + +As was the case for blurring and thresholding, there are several different methods in scikit-image that can be used for edge detection, so we will examine only one in detail. ## Introduction to edge detection -To begin our introduction to edge detection, -let us look at an image with a very simple edge - -this grayscale image of two overlapped pieces of paper, -one black and and one white: +To begin our introduction to edge detection, let us look at an image with a very simple edge - this grayscale image of two overlapped pieces of paper, one black and and one white: ![](fig/black-and-white.jpg){alt='Black and white image'} -The obvious edge in the image is the vertical line -between the black paper and the white paper. -To our eyes, -there is a quite sudden change between the black pixels and the white pixels. -But, at a pixel-by-pixel level, is the transition really that sudden? +The obvious edge in the image is the vertical line between the black paper and the white paper. To our eyes, there is a quite sudden change between the black pixels and the white pixels. But, at a pixel-by-pixel level, is the transition really that sudden? -If we zoom in on the edge more closely, as in this image, we can see -that the edge between the black and white areas of the image is not a clear-cut line. +If we zoom in on the edge more closely, as in this image, we can see that the edge between the black and white areas of the image is not a clear-cut line. ![](fig/black-and-white-edge-pixels.jpg){alt='Black and white edge pixels'} -We can learn more about the edge by examining the colour values of some of the pixels. -Imagine a short line segment, -halfway down the image and straddling the edge between the black and white paper. -This plot shows the pixel values -(between 0 and 255, since this is a grayscale image) -for forty pixels spanning the transition from black to white. +We can learn more about the edge by examining the colour values of some of the pixels. Imagine a short line segment, halfway down the image and straddling the edge between the black and white paper. This plot shows the pixel values (between 0 and 255, since this is a grayscale image) for forty pixels spanning the transition from black to white. ![](fig/black-and-white-gradient.png){alt='Gradient near transition'} -It is obvious that the "edge" here is not so sudden! -So, any scikit-image method to detect edges in an image must be able to -decide where the edge is, and place appropriately-coloured pixels in that location. +It is obvious that the "edge" here is not so sudden! So, any scikit-image method to detect edges in an image must be able to decide where the edge is, and place appropriately-coloured pixels in that location. ## Canny edge detection -Our edge detection method in this workshop is *Canny edge detection*, -created by John Canny in 1986. -This method uses a series of steps, some incorporating other types of edge detection. -The `skimage.feature.canny()` function performs the following steps: - -1. A Gaussian blur - (that is characterised by the `sigma` parameter, - see [*Blurring Images*](../episodes/06-blurring.md) - is applied to remove noise from the image. - (So if we are doing edge detection via this function, - we should not perform our own blurring step.) -2. Sobel edge detection is performed on both the cx and ry dimensions, - to find the intensity gradients of the edges in the image. - Sobel edge detection computes - the derivative of a curve fitting the gradient between light and dark areas - in an image, and then finds the peak of the derivative, - which is interpreted as the location of an edge pixel. -3. Pixels that would be highlighted, but seem too far from any edge, - are removed. - This is called *non-maximum suppression*, and - the result is edge lines that are thinner than those produced by other methods. -4. A double threshold is applied to determine potential edges. - Here extraneous pixels caused by noise or milder colour variation than desired - are eliminated. - If a pixel's gradient value - based on the Sobel differential - - is above the high threshold value, - it is considered a strong candidate for an edge. - If the gradient is below the low threshold value, it is turned off. - If the gradient is in between, - the pixel is considered a weak candidate for an edge pixel. -5. Final detection of edges is performed using *hysteresis*. - Here, weak candidate pixels are examined, and - if they are connected to strong candidate pixels, - they are considered to be edge pixels; - the remaining, non-connected weak candidates are turned off. - -For a user of the `skimage.feature.canny()` edge detection function, -there are three important parameters to pass in: -`sigma` for the Gaussian filter in step one and -the low and high threshold values used in step four of the process. -These values generally are determined empirically, -based on the contents of the image(s) to be processed. - -The following program illustrates how the `skimage.feature.canny()` method -can be used to detect the edges in an image. -We will execute the program on the `data/shapes-01.jpg` image, -which we used before in -[the *Thresholding* episode](../episodes/06-processing-segmentation.md): +Our edge detection method in this workshop is *Canny edge detection*, created by John Canny in 1986. This method uses a series of steps, some incorporating other types of edge detection. The `skimage.feature.canny()` function performs the following steps: + +1. A Gaussian blur (that is characterised by the `sigma` parameter, see [*Blurring Images*](../episodes/06-blurring.md) is applied to remove noise from the image. (So if we are doing edge detection via this function, we should not perform our own blurring step.) +2. Sobel edge detection is performed on both the cx and ry dimensions, to find the intensity gradients of the edges in the image. Sobel edge detection computes the derivative of a curve fitting the gradient between light and dark areas in an image, and then finds the peak of the derivative, which is interpreted as the location of an edge pixel. +3. Pixels that would be highlighted, but seem too far from any edge, are removed. This is called *non-maximum suppression*, and the result is edge lines that are thinner than those produced by other methods. +4. A double threshold is applied to determine potential edges. Here extraneous pixels caused by noise or milder colour variation than desired are eliminated. If a pixel's gradient value - based on the Sobel differential - is above the high threshold value, it is considered a strong candidate for an edge. If the gradient is below the low threshold value, it is turned off. If the gradient is in between, the pixel is considered a weak candidate for an edge pixel. +5. Final detection of edges is performed using *hysteresis*. Here, weak candidate pixels are examined, and if they are connected to strong candidate pixels, they are considered to be edge pixels; the remaining, non-connected weak candidates are turned off. + +For a user of the `skimage.feature.canny()` edge detection function, there are three important parameters to pass in: `sigma` for the Gaussian filter in step one and the low and high threshold values used in step four of the process. These values generally are determined empirically, based on the contents of the image(s) to be processed. + +The following program illustrates how the `skimage.feature.canny()` method can be used to detect the edges in an image. We will execute the program on the `data/shapes-01.jpg` image, which we used before in [the *Thresholding* episode](../episodes/06-processing-segmentation.md): ![](fig/shapes-01.jpg){alt='coloured shapes'} -We are interested in finding the edges of the shapes in the image, -and so the colours are not important. -Our strategy will be to read the image as grayscale, -and then apply Canny edge detection. -Note that when reading the image with `iio.imread(..., mode="L")` -the image is converted to a grayscale image of same dtype. - -This program takes three command-line arguments: -the filename of the image to process, -and then two arguments related to the double thresholding -in step four of the Canny edge detection process. -These are the low and high threshold values for that step. -After the required libraries are imported, -the program reads the command-line arguments and -saves them in their respective variables. +We are interested in finding the edges of the shapes in the image, and so the colours are not important. Our strategy will be to read the image as grayscale, and then apply Canny edge detection. Note that when reading the image with `iio.imread(..., mode="L")` the image is converted to a grayscale image of same dtype. + +This program takes three command-line arguments: the filename of the image to process, and then two arguments related to the double thresholding in step four of the Canny edge detection process. These are the low and high threshold values for that step. After the required libraries are imported, the program reads the command-line arguments and saves them in their respective variables. ```python """Python script to demonstrate Canny edge detection. @@ -182,91 +98,49 @@ edges = skimage.feature.canny( ) ``` -As we are using it here, the `skimage.feature.canny()` function takes four parameters. -The first parameter is the input image. -The `sigma` parameter determines -the amount of Gaussian smoothing that is applied to the image. -The next two parameters are the low and high threshold values -for the fourth step of the process. +As we are using it here, the `skimage.feature.canny()` function takes four parameters. The first parameter is the input image. The `sigma` parameter determines the amount of Gaussian smoothing that is applied to the image. The next two parameters are the low and high threshold values for the fourth step of the process. -The result of this call is a binary image. -In the image, the edges detected by the process are white, -while everything else is black. +The result of this call is a binary image. In the image, the edges detected by the process are white, while everything else is black. -Finally, the program displays the `edges` image, -showing the edges that were found in the original. +Finally, the program displays the `edges` image, showing the edges that were found in the original. ```python # display edges skimage.io.imshow(edges) ``` -Here is the result, for the coloured shape image above, -with sigma value 2.0, low threshold value 0.1 and high threshold value 0.3: +Here is the result, for the coloured shape image above, with sigma value 2.0, low threshold value 0.1 and high threshold value 0.3: ![](fig/shapes-01-canny-edges.png){alt='Output file of Canny edge detection'} -Note that the edge output shown in a scikit-image window may look significantly -worse than the image would look -if it were saved to a file due to resampling artefacts in the interactive image viewer. -The image above is the edges of the junk image, saved in a PNG file. -Here is how the same image looks when displayed in a scikit-image output window: +Note that the edge output shown in a scikit-image window may look significantly worse than the image would look if it were saved to a file due to resampling artefacts in the interactive image viewer. The image above is the edges of the junk image, saved in a PNG file. Here is how the same image looks when displayed in a scikit-image output window: ![](fig/shapes-01-canny-edge-output.png){alt='Output window of Canny edge detection'} ## Interacting with the image viewer using viewer plugins -As we have seen, for a user of the `skimage.feature.canny()` edge detection function, -three important parameters to pass in are sigma, -and the low and high threshold values used in step four of the process. -These values generally are determined empirically, -based on the contents of the image(s) to be processed. +As we have seen, for a user of the `skimage.feature.canny()` edge detection function, three important parameters to pass in are sigma, and the low and high threshold values used in step four of the process. These values generally are determined empirically, based on the contents of the image(s) to be processed. -Here is an image of some glass beads that we can use as -input into a Canny edge detection program: +Here is an image of some glass beads that we can use as input into a Canny edge detection program: ![](fig/beads.jpg){alt='Beads image'} -We could use the `code/edge-detection/CannyEdge.py` program above -to find edges in this image. -To find acceptable values for the thresholds, -we would have to run the program over and over again, -trying different threshold values and examining the resulting image, -until we find a combination of parameters that works best for the image. +We could use the `code/edge-detection/CannyEdge.py` program above to find edges in this image. To find acceptable values for the thresholds, we would have to run the program over and over again, trying different threshold values and examining the resulting image, until we find a combination of parameters that works best for the image. -*Or*, we can write a Python program and -create a viewer plugin that uses scikit-image *sliders*, -that allow us to vary the function parameters while the program is running. -In other words, we can write a program that presents us with a window like this: +*Or*, we can write a Python program and create a viewer plugin that uses scikit-image *sliders*, that allow us to vary the function parameters while the program is running. In other words, we can write a program that presents us with a window like this: ![](fig/beads-canny-ui.png){alt='Canny UI'} -Then, when we run the program, we can use the sliders to -vary the values of the sigma and threshold parameters -until we are satisfied with the results. -After we have determined suitable values, -we can use the simpler program to utilise the parameters without -bothering with the user interface and sliders. - -Here is a Python program that shows how to apply Canny edge detection, -and how to add sliders to the user interface. -There are four parts to this program, -making it a bit (but only a *bit*) -more complicated than the programs we have looked at so far. -The added complexity comes from setting up the sliders for the parameters -that were previously read from the command line: -In particular, we have added +Then, when we run the program, we can use the sliders to vary the values of the sigma and threshold parameters until we are satisfied with the results. After we have determined suitable values, we can use the simpler program to utilise the parameters without bothering with the user interface and sliders. + +Here is a Python program that shows how to apply Canny edge detection, and how to add sliders to the user interface. There are four parts to this program, making it a bit (but only a *bit*) more complicated than the programs we have looked at so far. The added complexity comes from setting up the sliders for the parameters that were previously read from the command line: In particular, we have added - The `canny()` filter function that returns an edge image, - The `cannyPlugin` plugin object, to which we add - The sliders for *sigma*, and *low* and *high threshold* values, and - The main program, i.e., the code that is executed when the program runs. -We will look at the main program part first, and then return to writing the plugin. -The first several lines of the main program are easily recognizable at this point: -saving the command-line argument, -reading the image in grayscale, -and creating a window. +We will look at the main program part first, and then return to writing the plugin. The first several lines of the main program are easily recognizable at this point: saving the command-line argument, reading the image in grayscale, and creating a window. ```python """Python script to demonstrate Canny edge detection with sliders to adjust the thresholds. @@ -285,11 +159,7 @@ image = iio.imread(uri=filename, mode="L") viewer = plt.imshow(image) ``` -The `skimage.viewer.plugins.Plugin` class is designed to manipulate images. -It takes an `image_filter` argument in the constructor that should be a function. -This function should produce a new image as an output, -given an image as the first argument, -which then will be automatically displayed in the image viewer. +The `skimage.viewer.plugins.Plugin` class is designed to manipulate images. It takes an `image_filter` argument in the constructor that should be a function. This function should produce a new image as an output, given an image as the first argument, which then will be automatically displayed in the image viewer. ```python # Create the plugin and give it a name @@ -297,15 +167,7 @@ canny_plugin = skimage.viewer.plugins.Plugin(image_filter=skimage.feature.canny) canny_plugin.name = "Canny Filter Plugin" ``` -We want to interactively modify the parameters of the filter function interactively. -scikit-image allows us to further enrich the plugin by adding widgets, like -`skimage.viewer.widgets.Slider`, -`skimage.viewer.widgets.CheckBox`, -`skimage.viewer.widgets.ComboBox`. -Whenever a widget belonging to the plugin is updated, -the filter function is called with the updated parameters. -This function is also called a callback function. -The following code adds sliders for `sigma`, `low_threshold` and `high_thresholds`. +We want to interactively modify the parameters of the filter function interactively. scikit-image allows us to further enrich the plugin by adding widgets, like `skimage.viewer.widgets.Slider`, `skimage.viewer.widgets.CheckBox`, `skimage.viewer.widgets.ComboBox`. Whenever a widget belonging to the plugin is updated, the filter function is called with the updated parameters. This function is also called a callback function. The following code adds sliders for `sigma`, `low_threshold` and `high_thresholds`. ```python # Add sliders for the parameters @@ -320,26 +182,13 @@ canny_plugin += skimage.viewer.widgets.Slider( ) ``` -A slider is a widget that lets you choose a number by dragging a handle along a line. -On the left side of the line, we have the lowest value, -on the right side the highest value that can be chosen. -The range of values in between is distributed equally along this line. -All three sliders are constructed in the same way: -The first argument is the name of the parameter that is tweaked by the slider. -With the arguments `low`, and `high`, -we supply the limits for the range of numbers that is represented by the slider. -The `value` argument specifies the initial value of that parameter, -so where the handle is located when the plugin is started. -Adding the slider to the plugin makes the values available as -parameters to the `filter_function`. +A slider is a widget that lets you choose a number by dragging a handle along a line. On the left side of the line, we have the lowest value, on the right side the highest value that can be chosen. The range of values in between is distributed equally along this line. All three sliders are constructed in the same way: The first argument is the name of the parameter that is tweaked by the slider. With the arguments `low`, and `high`, we supply the limits for the range of numbers that is represented by the slider. The `value` argument specifies the initial value of that parameter, so where the handle is located when the plugin is started. Adding the slider to the plugin makes the values available as parameters to the `filter_function`. ::::::::::::::::::::::::::::::::::::::::: callout ## How does the plugin know how to call the filter function with the parameters? -The filter function will be called with the slider parameters -according to their *names* as *keyword* arguments. -So it is very important to name the sliders appropriately. +The filter function will be called with the slider parameters according to their *names* as *keyword* arguments. So it is very important to name the sliders appropriately. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -351,10 +200,7 @@ viewer += canny_plugin viewer.show() ``` -Here is the result of running the preceding program on the beads image, -with a sigma value 1.0, -low threshold value 0.1 and high threshold value 0.3. -The image shows the edges in an output file. +Here is the result of running the preceding program on the beads image, with a sigma value 1.0, low threshold value 0.1 and high threshold value 0.3. The image shows the edges in an output file. ![](fig/beads-out.png){alt='Beads edges (file)'} @@ -362,23 +208,17 @@ The image shows the edges in an output file. ## Applying Canny edge detection to another image (5 min) -Now, run the program above on the image of coloured shapes, -`data/shapes-01.jpg`. -Use a sigma of 1.0 and adjust low and high threshold sliders -to produce an edge image that looks like this: +Now, run the program above on the image of coloured shapes, `data/shapes-01.jpg`. Use a sigma of 1.0 and adjust low and high threshold sliders to produce an edge image that looks like this: ![](fig/shapes-01-canny-track-edges.png){alt='coloured shape edges'} -What values for the low and high threshold values did you use to -produce an image similar to the one above? +What values for the low and high threshold values did you use to produce an image similar to the one above? ::::::::::::::: solution ## Solution -The coloured shape edge image above was produced with a low threshold -value of 0.05 and a high threshold value of 0.07. -You may be able to achieve similar results with other threshold values. +The coloured shape edge image above was produced with a low threshold value of 0.05 and a high threshold value of 0.07. You may be able to achieve similar results with other threshold values. ::::::::::::::::::::::::: @@ -388,28 +228,17 @@ You may be able to achieve similar results with other threshold values. ## Using sliders for thresholding (30 min) -Now, let us apply what we know about creating sliders to another, -similar situation. -Consider this image of a collection of maize seedlings, -and suppose we wish to use simple fixed-level thresholding to -mask out everything that is not part of one of the plants. +Now, let us apply what we know about creating sliders to another, similar situation. Consider this image of a collection of maize seedlings, and suppose we wish to use simple fixed-level thresholding to mask out everything that is not part of one of the plants. ![](fig/maize-roots-grayscale.jpg){alt='Maize roots image'} - -To perform the thresholding, we could first create a histogram, -then examine it, and select an appropriate threshold value. -Here, however, let us create an application with a slider to set the threshold value. -Create a program that reads in the image, -displays it in a window with a slider, -and allows the slider value to vary the threshold value used. -You will find the image at `data/maize-roots-grayscale.jpg`. + +To perform the thresholding, we could first create a histogram, then examine it, and select an appropriate threshold value. Here, however, let us create an application with a slider to set the threshold value. Create a program that reads in the image, displays it in a window with a slider, and allows the slider value to vary the threshold value used. You will find the image at `data/maize-roots-grayscale.jpg`. ::::::::::::::: solution ## Solution -Here is a program that uses a slider to vary the threshold value used in -a simple, fixed-level thresholding process. +Here is a program that uses a slider to vary the threshold value used in a simple, fixed-level thresholding process. ```python """Python program to use a slider to control fixed-level thresholding value. @@ -451,8 +280,7 @@ viewer += smooth_threshold_plugin viewer.show() ``` -Here is the output of the program, -blurring with a sigma of 1.5 and a threshold value of 0.45: +Here is the output of the program, blurring with a sigma of 1.5 and a threshold value of 0.45: ![](fig/maize-roots-threshold.png){alt='Thresholded maize roots'} @@ -460,23 +288,11 @@ blurring with a sigma of 1.5 and a threshold value of 0.45: :::::::::::::::::::::::::::::::::::::::::::::::::: -Keep this plugin technique in your image processing "toolbox." -You can use sliders (or other interactive elements, -see [the scikit-image documentation](https://scikit-image.org/docs/dev/api/skimage.viewer.widgets.html)) -to vary other kinds of parameters, such as sigma for blurring, -binary thresholding values, and so on. -A few minutes developing a program to tweak parameters like this can -save you the hassle of repeatedly running a program from the command line -with different parameter values. -Furthermore, scikit-image already comes with a few viewer plugins that you can -check out in [the documentation](https://scikit-image.org/docs/dev/api/skimage.viewer.plugins.html). +Keep this plugin technique in your image processing "toolbox." You can use sliders (or other interactive elements, see [the scikit-image documentation](https://scikit-image.org/docs/dev/api/skimage.viewer.widgets.html)) to vary other kinds of parameters, such as sigma for blurring, binary thresholding values, and so on. A few minutes developing a program to tweak parameters like this can save you the hassle of repeatedly running a program from the command line with different parameter values. Furthermore, scikit-image already comes with a few viewer plugins that you can check out in [the documentation](https://scikit-image.org/docs/dev/api/skimage.viewer.plugins.html). ## Other edge detection functions -As with blurring, there are other options for finding edges in skimage. -These include `skimage.filters.sobel()`, -which you will recognise as part of the Canny method. -Another choice is `skimage.filters.laplace()`. +As with blurring, there are other options for finding edges in skimage. These include `skimage.filters.sobel()`, which you will recognise as part of the Canny method. Another choice is `skimage.filters.laplace()`. :::::::::::::::::::::::::::::: keypoints From 0aed5813256e5ef6c68aa0913a4da6324f3ff56e Mon Sep 17 00:00:00 2001 From: Marco Dalla Vecchia Date: Sun, 29 Mar 2026 17:47:53 +0200 Subject: [PATCH 2/4] more formatting --- episodes/01-introduction.md | 78 +--- episodes/02-image-basics.md | 694 ++++++------------------------------ 2 files changed, 132 insertions(+), 640 deletions(-) diff --git a/episodes/01-introduction.md b/episodes/01-introduction.md index 5851794..12de0fa 100644 --- a/episodes/01-introduction.md +++ b/episodes/01-introduction.md @@ -18,31 +18,13 @@ exercises: 0 :::::::::::::::::::::::::::::::::::::::::::::::::: -As computer systems have become faster and more powerful, -and cameras and other imaging systems have become commonplace -in many other areas of life, -the need has grown for researchers to be able to -process and analyse image data. -Considering the large volumes of data that can be involved - -high-resolution images that take up a lot of disk space/virtual memory, -and/or collections of many images that must be processed together - -and the time-consuming and error-prone nature of manual processing, -it can be advantageous or even necessary for this processing and analysis -to be automated as a computer program. - -This lesson introduces an open source toolkit for processing image data: -the Python programming language -and [the *scikit-image* (`skimage`) library](https://scikit-image.org/). -With careful experimental design, -Python code can be a powerful instrument in answering many different kinds of questions. +As computer systems have become faster and more powerful, and cameras and other imaging systems have become commonplace in many other areas of life, the need has grown for researchers to be able to process and analyse image data. Considering the large volumes of data that can be involved - high-resolution images that take up a lot of disk space/virtual memory, and/or collections of many images that must be processed together - and the time-consuming and error-prone nature of manual processing, it can be advantageous or even necessary for this processing and analysis to be automated as a computer program. + +This lesson introduces an open source toolkit for processing image data: the Python programming language and [the *scikit-image* (`skimage`) library](https://scikit-image.org/). With careful experimental design, Python code can be a powerful instrument in answering many different kinds of questions. ## Uses of Image Processing in Research -Automated processing can be used to analyse many different properties of an image, -including the distribution and change in colours in the image, -the number, size, position, orientation, and shape of objects in the image, -and even - when combined with machine learning techniques for object recognition - -the type of objects in the image. +Automated processing can be used to analyse many different properties of an image, including the distribution and change in colours in the image, the number, size, position, orientation, and shape of objects in the image, and even - when combined with machine learning techniques for object recognition - the type of objects in the image. Some examples of image processing methods applied in research include: @@ -52,27 +34,15 @@ Some examples of image processing methods applied in research include: - [Estimating the population of emperor penguins](https://www.ncbi.nlm.nih.gov/pmc/articles/PMC3325796/) - [Global-scale analysis of marine plankton diversity](https://www.cell.com/cell/fulltext/S0092-8674\(19\)31124-9) -With this lesson, -we aim to provide a thorough grounding in the fundamental concepts and skills -of working with image data in Python. -Most of the examples used in this lesson focus on -one particular class of image processing technique, *morphometrics*, -but what you will learn can be used to solve a much wider range of problems. +With this lesson, we aim to provide a thorough grounding in the fundamental concepts and skills of working with image data in Python. Most of the examples used in this lesson focus on one particular class of image processing technique, *morphometrics*, but what you will learn can be used to solve a much wider range of problems. ## Morphometrics -Morphometrics involves counting the number of objects in an image, -analyzing the size of the objects, -or analyzing the shape of the objects. -For example, we might be interested in automatically counting -the number of bacterial colonies growing in a Petri dish, -as shown in this image: +Morphometrics involves counting the number of objects in an image, analyzing the size of the objects, or analyzing the shape of the objects. For example, we might be interested in automatically counting the number of bacterial colonies growing in a Petri dish, as shown in this image: ![](fig/colonies-01.jpg){alt='Bacteria colony'} -We could use image processing to find the colonies, count them, -and then highlight their locations on the original image, -resulting in an image like this: +We could use image processing to find the colonies, count them, and then highlight their locations on the original image, resulting in an image like this: ![](fig/colony-mask.png){alt='Colonies counted'} @@ -80,44 +50,24 @@ resulting in an image like this: ## Why write a program to do that? -Note that you can easily manually count the number of bacteria colonies -shown in the morphometric example above. -Why should we learn how to write a Python program to do a task -we could easily perform with our own eyes? -There are at least two reasons to learn how to perform tasks like these -with Python and scikit-image: +Note that you can easily manually count the number of bacteria colonies shown in the morphometric example above. Why should we learn how to write a Python program to do a task we could easily perform with our own eyes? There are at least two reasons to learn how to perform tasks like these with Python and scikit-image: -1. What if there are many more bacteria colonies in the Petri dish? - For example, suppose the image looked like this: +1. What if there are many more bacteria colonies in the Petri dish? For example, suppose the image looked like this: ![](fig/colonies-03.jpg){alt='Bacteria colony'} -Manually counting the colonies in that image would present more of a challenge. -A Python program using scikit-image could count the number of colonies more accurately, -and much more quickly, than a human could. +Manually counting the colonies in that image would present more of a challenge. A Python program using scikit-image could count the number of colonies more accurately, and much more quickly, than a human could. -2. What if you have hundreds, or thousands, of images to consider? - Imagine having to manually count colonies on several thousand images - like those above. - A Python program using scikit-image could move through all of the images in seconds; - how long would a graduate student require to do the task? - Which process would be more accurate and repeatable? +2. What if you have hundreds, or thousands, of images to consider? Imagine having to manually count colonies on several thousand images like those above. A Python program using scikit-image could move through all of the images in seconds; how long would a graduate student require to do the task? Which process would be more accurate and repeatable? -As you can see, the simple image processing / computer vision techniques you -will learn during this workshop can be very valuable tools for scientific -research. +As you can see, the simple image processing / computer vision techniques you will learn during this workshop can be very valuable tools for scientific research. :::::::::::::::::::::::::::::::::::::::::::::::::: -As we move through this workshop, -we will learn image analysis methods useful for many different scientific problems. -These will be linked together -and applied to a real problem in the final end-of-workshop -[capstone challenge](10-challenges.md). +As we move through this workshop, we will learn image analysis methods useful for many different scientific problems. These will be linked together and applied to a real problem in the final end-of-workshop [capstone challenge](10-challenges.md). -Let's get started, -by learning some basics about how images are represented and stored digitally. +Let's get started, by learning some basics about how images are represented and stored digitally. :::::::::::::::::::::::::::::::::::::::: keypoints diff --git a/episodes/02-image-basics.md b/episodes/02-image-basics.md index fa651a6..7e2467b 100644 --- a/episodes/02-image-basics.md +++ b/episodes/02-image-basics.md @@ -6,8 +6,7 @@ exercises: 5 ::::::::::::::::::::::::::::::::::::::: objectives -- Describe the main differences between typical fluorescence bioimages and scientific (like histological staining) and non-scientific (like camera pictures) RGB images. -- Explain how some aspects of image origin and formation can influence downstream analysis. +- Describe the main differences between typical fluorescence bioimages and scientific (like histological staining) and non-scientific (like camera pictures) RGB images. - Explain how some aspects of image origin and formation can influence downstream analysis. - Load images into Python represented as n-dimensional arrays via BioIO - Display pixel values from a NumPy array @@ -29,11 +28,7 @@ exercises: 5 :::::::::::::::::::::::::::::::::::::::::::::::::: -The images we see on hard copy, view with our electronic devices, -or process with our programs are represented and stored in the computer -as numeric abstractions, approximations of what we see with our eyes in the real world. -Before we begin to learn how to process images with Python programs, -we need to spend some time understanding how these abstractions work. +The images we see on hard copy, view with our electronic devices, or process with our programs are represented and stored in the computer as numeric abstractions, approximations of what we see with our eyes in the real world. Before we begin to learn how to process images with Python programs, we need to spend some time understanding how these abstractions work. ::::::::::::::::::::::::::::::::::::::::: callout @@ -43,55 +38,31 @@ Feel free to make use of the [available cheat-sheet](./files/cheatsheet.html) as ## Pixels -It is important to realise that images are stored as rectangular arrays -of hundreds, thousands, or millions of discrete "picture elements," -otherwise known as *pixels*. -Each pixel can be thought of as a single square point of coloured light. +It is important to realise that images are stored as rectangular arrays of hundreds, thousands, or millions of discrete "picture elements," otherwise known as *pixels*. Each pixel can be thought of as a single square point of coloured light. -For example, consider this image of a maize seedling, -with a square area designated by a red box: +For example, consider this image of a maize seedling, with a square area designated by a red box: ![](fig/maize-seedling-original.jpg){alt='Original size image'} -Now, if we zoomed in close enough to see the pixels in the red box, -we would see something like this: +Now, if we zoomed in close enough to see the pixels in the red box, we would see something like this: ![](fig/maize-seedling-enlarged.jpg){alt='Enlarged image area'} -Note that each square in the enlarged image area - each pixel - -is all one colour, -but that each pixel can have a different colour from its neighbors. -Viewed from a distance, -these pixels seem to blend together to form the image we see. +Note that each square in the enlarged image area - each pixel - is all one colour, but that each pixel can have a different colour from its neighbors. Viewed from a distance, these pixels seem to blend together to form the image we see. -Real-world images are typically made up of a vast number of pixels, -and each of these pixels is one of potentially millions of colours. -While we will deal with pictures of such complexity in this lesson, -let's start our exploration with just 15 pixels in a 5 x 3 matrix with 2 colours, -and work our way up to that complexity. +Real-world images are typically made up of a vast number of pixels, and each of these pixels is one of potentially millions of colours. While we will deal with pictures of such complexity in this lesson, let's start our exploration with just 15 pixels in a 5 x 3 matrix with 2 colours, and work our way up to that complexity. ::::::::::::::::::::::::::::::::::::::::: callout ## Matrices, arrays, images and pixels -A **matrix** is a mathematical concept - numbers evenly arranged in a rectangle. This can be a two-dimensional rectangle, -like the shape of the screen you're looking at now. Or it could be a three-dimensional equivalent, a cuboid, or have -even more dimensions, but always keeping the evenly spaced arrangement of numbers. In computing, an **array** refers -to a structure in the computer's memory where data is stored in evenly spaced **elements**. This is strongly analogous -to a matrix. A NumPy array is a **type** of variable (a simpler example of a type is an integer). For our purposes, -the distinction between matrices and arrays is not important, we don't really care how the computer arranges our data -in its memory. The important thing is that the computer stores values describing the pixels in images, as arrays. And -the terms matrix and array will be used interchangeably. +A **matrix** is a mathematical concept - numbers evenly arranged in a rectangle. This can be a two-dimensional rectangle, like the shape of the screen you're looking at now. Or it could be a three-dimensional equivalent, a cuboid, or have even more dimensions, but always keeping the evenly spaced arrangement of numbers. In computing, an **array** refers to a structure in the computer's memory where data is stored in evenly spaced **elements**. This is strongly analogous to a matrix. A NumPy array is a **type** of variable (a simpler example of a type is an integer). For our purposes, the distinction between matrices and arrays is not important, we don't really care how the computer arranges our data in its memory. The important thing is that the computer stores values describing the pixels in images, as arrays. And the terms matrix and array will be used interchangeably. :::::::::::::::::::::::::::::::::::::::::::::::::: ## Loading images -As noted, images we want to analyze (process) with Python are loaded into arrays. -There are multiple ways to load images. In this lesson, we use imageio, a Python -library for reading (loading) and writing (saving) image data, and more specifically -its version 3. But, really, we could use any image loader which would return a -NumPy array. +As noted, images we want to analyze (process) with Python are loaded into arrays. There are multiple ways to load images. In this lesson, we use imageio, a Python library for reading (loading) and writing (saving) image data, and more specifically its version 3. But, really, we could use any image loader which would return a NumPy array. ```python """Python library for reading and writing images.""" @@ -99,13 +70,9 @@ NumPy array. import imageio.v3 as iio ``` -The `v3` module of imageio (`imageio.v3`) is imported as `iio` (see note in -the next section). -Version 3 of imageio has the benefit of supporting nD (multidimensional) image data -natively (think of volumes, movies). +The `v3` module of imageio (`imageio.v3`) is imported as `iio` (see note in the next section). Version 3 of imageio has the benefit of supporting nD (multidimensional) image data natively (think of volumes, movies). -Let us load our image data from disk using -the `imread` function from the `imageio.v3` module. +Let us load our image data from disk using the `imread` function from the `imageio.v3` module. ```python eight = iio.imread(uri="data/eight.tif") @@ -116,21 +83,13 @@ print(type(eight)) ``` -Note that, using the same image loader or a different one, we could also read in -remotely hosted data. +Note that, using the same image loader or a different one, we could also read in remotely hosted data. ::::::::::::::::::::::::::::::::::::::::: callout ## Why not use `skimage.io.imread()`? -The scikit-image library has its own function to read an image, -so you might be asking why we don't use it here. -Actually, `skimage.io.imread()` uses `iio.imread()` internally when loading an image into Python. -It is certainly something you may use as you see fit in your own code. -In this lesson, we use the imageio library to read or write images, -while scikit-image is dedicated to performing operations on the images. -Using imageio gives us more flexibility, especially when it comes to -handling metadata. +The scikit-image library has its own function to read an image, so you might be asking why we don't use it here. Actually, `skimage.io.imread()` uses `iio.imread()` internally when loading an image into Python. It is certainly something you may use as you see fit in your own code. In this lesson, we use the imageio library to read or write images, while scikit-image is dedicated to performing operations on the images. Using imageio gives us more flexibility, especially when it comes to handling metadata. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -138,17 +97,7 @@ handling metadata. ## Beyond NumPy arrays -Beyond NumPy arrays, there exist other types of variables which are array-like. Notably, -[pandas.DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) -and [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) -can hold labeled, tabular data. -These are not natively supported in scikit-image, the scientific toolkit we use -in this lesson for processing image data. However, data stored in these types can -be converted to `numpy.ndarray` with certain assumptions -(see `pandas.DataFrame.to_numpy()` and `xarray.DataArray.data`). Particularly, -these conversions ignore the sampling coordinates (`DataFrame.index`, -`DataFrame.columns`, or `DataArray.coords`), which may result in misrepresented data, -for instance, when the original data points are irregularly spaced. +Beyond NumPy arrays, there exist other types of variables which are array-like. Notably, [pandas.DataFrame](https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.html) and [xarray.DataArray](https://docs.xarray.dev/en/stable/generated/xarray.DataArray.html) can hold labeled, tabular data. These are not natively supported in scikit-image, the scientific toolkit we use in this lesson for processing image data. However, data stored in these types can be converted to `numpy.ndarray` with certain assumptions (see `pandas.DataFrame.to_numpy()` and `xarray.DataArray.data`). Particularly, these conversions ignore the sampling coordinates (`DataFrame.index`, `DataFrame.columns`, or `DataArray.coords`), which may result in misrepresented data, for instance, when the original data points are irregularly spaced. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -169,15 +118,9 @@ import skimage as ski ## Import statements in Python -In Python, the `import` statement is used to -load additional functionality into a program. -This is necessary when we want our code to do something more specialised, -which cannot easily be achieved with the limited set of basic tools and -data structures available in the default Python environment. +In Python, the `import` statement is used to load additional functionality into a program. This is necessary when we want our code to do something more specialised, which cannot easily be achieved with the limited set of basic tools and data structures available in the default Python environment. -Additional functionality can be loaded as a single function or object, -a module defining several of these, or a library containing many modules. -You will encounter several different forms of `import` statement. +Additional functionality can be loaded as a single function or object, a module defining several of these, or a library containing many modules. You will encounter several different forms of `import` statement. ```python import skimage # form 1, load whole skimage library @@ -190,51 +133,27 @@ import skimage as ski # form 4, load all of skimage into an object call ## Further explanation -In the example above, form 1 loads the entire scikit-image library into the -program as an object. -Individual modules of the library are then available within that object, -e.g., to access the `disk` function used in [the drawing episode](04-drawing.md), -you would write `skimage.draw.disk()`. - -Form 2 loads only the `draw` module of `skimage` into the program. -The syntax needed to use the module remains unchanged: -to access the `disk` function, -we would use the same function call as given for form 1. - -Form 3 can be used to import only a specific function/class from a library/module. -Unlike the other forms, when this approach is used, -the imported function or class can be called by its name only, -without prefixing it with the name of the library/module from which it was loaded, -i.e., `disk()` instead of `skimage.draw.disk()` using the example above. -One hazard of this form is that importing like this will overwrite any -object with the same name that was defined/imported earlier in the program, -i.e., the example above would replace any existing object called `disk` -with the `disk` function from `skimage.draw`. - -Finally, the `as` keyword can be used when importing, -to define a name to be used as shorthand for the library/module being imported. -This name is referred to as an alias. Typically, using an alias (such as -`np` for the NumPy library) saves us a little typing. -You may see `as` combined with any of the other first three forms of `import` statements. - -Which form is used often depends on -the size and number of additional tools being loaded into the program. +In the example above, form 1 loads the entire scikit-image library into the program as an object. Individual modules of the library are then available within that object, e.g., to access the `disk` function used in [the drawing episode](04-drawing.md), you would write `skimage.draw.disk()`. + +Form 2 loads only the `draw` module of `skimage` into the program. The syntax needed to use the module remains unchanged: to access the `disk` function, we would use the same function call as given for form 1. + +Form 3 can be used to import only a specific function/class from a library/module. Unlike the other forms, when this approach is used, the imported function or class can be called by its name only, without prefixing it with the name of the library/module from which it was loaded, i.e., `disk()` instead of `skimage.draw.disk()` using the example above. One hazard of this form is that importing like this will overwrite any object with the same name that was defined/imported earlier in the program, i.e., the example above would replace any existing object called `disk` with the `disk` function from `skimage.draw`. + +Finally, the `as` keyword can be used when importing, to define a name to be used as shorthand for the library/module being imported. This name is referred to as an alias. Typically, using an alias (such as `np` for the NumPy library) saves us a little typing. You may see `as` combined with any of the other first three forms of `import` statements. + +Which form is used often depends on the size and number of additional tools being loaded into the program. ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: -Now that we have our libraries loaded, -we will run a Jupyter Magic Command that will ensure our images display -in our Jupyter document with pixel information that will help us -more efficiently run commands later in the session. +Now that we have our libraries loaded, we will run a Jupyter Magic Command that will ensure our images display in our Jupyter document with pixel information that will help us more efficiently run commands later in the session. ```python %matplotlib widget ``` -With that taken care of, let us display the image we have loaded, using -the `imshow` function from the `matplotlib.pyplot` module. +With that taken care of, let us display the image we have loaded, using the `imshow` function from the `matplotlib.pyplot` module. ```python fig, ax = plt.subplots() @@ -243,26 +162,9 @@ ax.imshow(eight) ![](fig/eight.png){alt='Image of 8'} -You might be thinking, -"That does look vaguely like an eight, -and I see two colours but how can that be only 15 pixels". -The display of the eight you see does use a lot more screen pixels to -display our eight so large, but that does not mean there is information -for all those screen pixels in the file. -All those extra pixels are a consequence of our viewer creating -additional pixels through interpolation. -It could have just displayed it as a tiny image using only 15 screen pixels if -the viewer was designed differently. - -While many image file formats contain descriptive metadata that can be essential, -the bulk of a picture file is just arrays of numeric information that, -when interpreted according to a certain rule set, -become recognizable as an image to us. -Our image of an eight is no exception, -and `imageio.v3` stored that image data in an array of arrays making -a 5 x 3 matrix of 15 pixels. -We can demonstrate that by calling on the shape property of our image variable -and see the matrix by printing our image variable to the screen. +You might be thinking, "That does look vaguely like an eight, and I see two colours but how can that be only 15 pixels". The display of the eight you see does use a lot more screen pixels to display our eight so large, but that does not mean there is information for all those screen pixels in the file. All those extra pixels are a consequence of our viewer creating additional pixels through interpolation. It could have just displayed it as a tiny image using only 15 screen pixels if the viewer was designed differently. + +While many image file formats contain descriptive metadata that can be essential, the bulk of a picture file is just arrays of numeric information that, when interpreted according to a certain rule set, become recognizable as an image to us. Our image of an eight is no exception, and `imageio.v3` stored that image data in an array of arrays making a 5 x 3 matrix of 15 pixels. We can demonstrate that by calling on the shape property of our image variable and see the matrix by printing our image variable to the screen. ```python print(eight.shape) @@ -278,21 +180,9 @@ print(eight) [0. 0. 0.]] ``` -Thus if we have tools that will allow us to manipulate these arrays of numbers, -we can manipulate the image. -The NumPy library can be particularly useful here, -so let's try that out using NumPy array slicing. -Notice that the default behavior of the `imshow` function appended row and -column numbers that will be helpful to us as we try to address individual or -groups of pixels. -First let's load another copy of our eight, and then make it look like a zero. - -To make it look like a zero, -we need to change the number underlying the centremost pixel to be 1. -With the help of those row and column headers, -at this small scale we can determine the centre pixel is in row labeled 2 and -column labeled 1. -Using array slicing, we can then address and assign a new value to that position. +Thus if we have tools that will allow us to manipulate these arrays of numbers, we can manipulate the image. The NumPy library can be particularly useful here, so let's try that out using NumPy array slicing. Notice that the default behavior of the `imshow` function appended row and column numbers that will be helpful to us as we try to address individual or groups of pixels. First let's load another copy of our eight, and then make it look like a zero. + +To make it look like a zero, we need to change the number underlying the centremost pixel to be 1. With the help of those row and column headers, at this small scale we can determine the centre pixel is in row labeled 2 and column labeled 1. Using array slicing, we can then address and assign a new value to that position. ```python zero = iio.imread(uri="data/eight.tif") @@ -318,40 +208,20 @@ print(zero) ## Coordinate system -When we process images, we can access, examine, and / or change -the colour of any pixel we wish. -To do this, we need some convention on how to access pixels -individually; a way to give each one a name, or an address of a sort. +When we process images, we can access, examine, and / or change the colour of any pixel we wish. To do this, we need some convention on how to access pixels individually; a way to give each one a name, or an address of a sort. -The most common manner to do this, and the one we will use in our programs, -is to assign a modified Cartesian coordinate system to the image. -The coordinate system we usually see in mathematics has -a horizontal x-axis and a vertical y-axis, like this: +The most common manner to do this, and the one we will use in our programs, is to assign a modified Cartesian coordinate system to the image. The coordinate system we usually see in mathematics has a horizontal x-axis and a vertical y-axis, like this: ![](fig/cartesian-coordinates.png){alt='Cartesian coordinate system'} -The modified coordinate system used for our images will have only positive -coordinates, the origin will be in the upper left corner instead of the -centre, and y coordinate values will get larger as they go down instead of up, -like this: +The modified coordinate system used for our images will have only positive coordinates, the origin will be in the upper left corner instead of the centre, and y coordinate values will get larger as they go down instead of up, like this: ![](fig/image-coordinates.png){alt='Image coordinate system'} - -This is called a *left-hand coordinate system*. -If you hold your left hand in front of your face and point your thumb at the floor, -your extended index finger will correspond to the x-axis -while your thumb represents the y-axis. + This is called a *left-hand coordinate system*. If you hold your left hand in front of your face and point your thumb at the floor, your extended index finger will correspond to the x-axis while your thumb represents the y-axis. ![](fig/left-hand-coordinates.png){alt='Left-hand coordinate system'} -Until you have worked with images for a while, -the most common mistake that you will make with coordinates is to forget -that y coordinates get larger as they go down instead of up -as in a normal Cartesian coordinate system. Consequently, it may be helpful to think -in terms of counting down rows (r) for the y-axis and across columns (c) for the x-axis. This -can be especially helpful in cases where you need to transpose image viewer data -provided in *x,y* format to *y,x* format. Thus, we will use *cx* and *ry* where appropriate -to help bridge these two approaches. +Until you have worked with images for a while, the most common mistake that you will make with coordinates is to forget that y coordinates get larger as they go down instead of up as in a normal Cartesian coordinate system. Consequently, it may be helpful to think in terms of counting down rows (r) for the y-axis and across columns (c) for the x-axis. This can be especially helpful in cases where you need to transpose image viewer data provided in *x,y* format to *y,x* format. Thus, we will use *cx* and *ry* where appropriate to help bridge these two approaches. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -359,9 +229,7 @@ to help bridge these two approaches. ## Changing Pixel Values (5 min) -Load another copy of eight named five, -and then change the value of pixels so you have what looks like a 5 instead of an 8. -Display the image and print out the matrix as well. +Load another copy of eight named five, and then change the value of pixels so you have what looks like a 5 instead of an 8. Display the image and print out the matrix as well. ::::::::::::::: solution @@ -394,11 +262,7 @@ print(five) ## More colours -Up to now, we only had a 2 colour matrix, -but we can have more if we use other numbers or fractions. -One common way is to use the numbers between 0 and 255 to allow for -256 different colours or 256 different levels of grey. -Let's try that out. +Up to now, we only had a 2 colour matrix, but we can have more if we use other numbers or fractions. One common way is to use the numbers between 0 and 255 to allow for 256 different colours or 256 different levels of grey. Let's try that out. ```python # make a copy of eight @@ -417,31 +281,7 @@ print(three_colours) ![](fig/three-colours.png){alt='Image of three colours'} -We now have 3 colours, but are they the three colours you expected? -They all appear to be on a continuum of dark purple on the low end and -yellow on the high end. -This is a consequence of the default colour map (cmap) in this library. -You can think of a colour map as an association or mapping of numbers -to a specific colour. -However, the goal here is not to have one number for every possible colour, -but rather to have a continuum of colours that demonstrate relative intensity. -In our specific case here for example, -255 or the highest intensity is mapped to yellow, -and 0 or the lowest intensity is mapped to a dark purple. -The best colour map for your data will vary and there are many options built in, -but this default selection was not arbitrary. -A lot of science went into making this the default due to its robustness -when it comes to how the human mind interprets relative colour values, -grey-scale printability, -and colour-blind friendliness -(You can read more about this default colour map in -[a Matplotlib tutorial](https://matplotlib.org/stable/tutorials/colors/colormaps.html) -and [an explanatory article by the authors](https://bids.github.io/colormap/)). -Thus it is a good place to start, -and you should change it only with purpose and forethought. -For now, let's see how you can do that using an alternative map -you have likely seen before where it will be even easier to see it as -a mapped continuum of intensities: greyscale. +We now have 3 colours, but are they the three colours you expected? They all appear to be on a continuum of dark purple on the low end and yellow on the high end. This is a consequence of the default colour map (cmap) in this library. You can think of a colour map as an association or mapping of numbers to a specific colour. However, the goal here is not to have one number for every possible colour, but rather to have a continuum of colours that demonstrate relative intensity. In our specific case here for example, 255 or the highest intensity is mapped to yellow, and 0 or the lowest intensity is mapped to a dark purple. The best colour map for your data will vary and there are many options built in, but this default selection was not arbitrary. A lot of science went into making this the default due to its robustness when it comes to how the human mind interprets relative colour values, grey-scale printability, and colour-blind friendliness (You can read more about this default colour map in [a Matplotlib tutorial](https://matplotlib.org/stable/tutorials/colors/colormaps.html) and [an explanatory article by the authors](https://bids.github.io/colormap/)). Thus it is a good place to start, and you should change it only with purpose and forethought. For now, let's see how you can do that using an alternative map you have likely seen before where it will be even easier to see it as a mapped continuum of intensities: greyscale. ```python fig, ax = plt.subplots() @@ -450,29 +290,11 @@ ax.imshow(three_colours, cmap="gray") ![](fig/grayscale.png){alt='Image in greyscale'} -Above we have exactly the same underlying data matrix, but in greyscale. -Zero maps to black, 255 maps to white, and 128 maps to medium grey. -Here we only have a single channel in the data and utilize a grayscale color map -to represent the luminance, or intensity of the data and correspondingly -this channel is referred to as the luminance channel. +Above we have exactly the same underlying data matrix, but in greyscale. Zero maps to black, 255 maps to white, and 128 maps to medium grey. Here we only have a single channel in the data and utilize a grayscale color map to represent the luminance, or intensity of the data and correspondingly this channel is referred to as the luminance channel. ## Even more colours -This is all well and good at this scale, -but what happens when we instead have a picture of a natural landscape that -contains millions of colours. -Having a one to one mapping of number to colour like this would be inefficient -and make adjustments and building tools to do so very difficult. -Rather than larger numbers, the solution is to have more numbers in more dimensions. -Storing the numbers in a multi-dimensional matrix where each colour or -property like transparency is associated with its own dimension allows -for individual contributions to a pixel to be adjusted independently. -This ability to manipulate properties of groups of pixels separately will be -key to certain techniques explored in later chapters of this lesson. -To get started let's see an example of how different dimensions of information -combine to produce a set of pixels using a 4 x 4 matrix with 3 dimensions -for the colours red, green, and blue. -Rather than loading it from a file, we will generate this example using NumPy. +This is all well and good at this scale, but what happens when we instead have a picture of a natural landscape that contains millions of colours. Having a one to one mapping of number to colour like this would be inefficient and make adjustments and building tools to do so very difficult. Rather than larger numbers, the solution is to have more numbers in more dimensions. Storing the numbers in a multi-dimensional matrix where each colour or property like transparency is associated with its own dimension allows for individual contributions to a pixel to be adjusted independently. This ability to manipulate properties of groups of pixels separately will be key to certain techniques explored in later chapters of this lesson. To get started let's see an example of how different dimensions of information combine to produce a set of pixels using a 4 x 4 matrix with 3 dimensions for the colours red, green, and blue. Rather than loading it from a file, we will generate this example using NumPy. ```python # set the random seed so we all get the same matrix @@ -510,10 +332,7 @@ print(checkerboard) ![](fig/checkerboard.png){alt='Image of checkerboard'} -Previously we had one number being mapped to one colour or intensity. -Now we are combining the effect of 3 numbers to arrive at a single colour value. -Let's see an example of that using the blue square at the end of the second row, -which has the index [1, 3]. +Previously we had one number being mapped to one colour or intensity. Now we are combining the effect of 3 numbers to arrive at a single colour value. Let's see an example of that using the blue square at the end of the second row, which has the index [1, 3]. ```python # extract all the colour information for the blue square @@ -521,25 +340,9 @@ upper_right_square = checkerboard[1, 3, :] upper_right_square ``` -This outputs: array([ 7, 1, 110]) -The integers in order represent Red, Green, and Blue. -Looking at the 3 values and knowing how they map, -can help us understand why it is blue. -If we divide each value by 255, which is the maximum, -we can determine how much it is contributing relative to its maximum potential. -Effectively, the red is at 7/255 or 2.8 percent of its potential, -the green is at 1/255 or 0.4 percent, -and blue is 110/255 or 43.1 percent of its potential. -So when you mix those three intensities of colour, -blue is winning by a wide margin, -but the red and green still contribute to make it a slightly different -shade of blue than 0,0,110 would be on its own. - -These colours mapped to dimensions of the matrix may be referred to as channels. -It may be helpful to display each of these channels independently, -to help us understand what is happening. -We can do that by multiplying our image array representation with -a 1d matrix that has a one for the channel we want to keep and zeros for the rest. +This outputs: array([ 7, 1, 110]) The integers in order represent Red, Green, and Blue. Looking at the 3 values and knowing how they map, can help us understand why it is blue. If we divide each value by 255, which is the maximum, we can determine how much it is contributing relative to its maximum potential. Effectively, the red is at 7/255 or 2.8 percent of its potential, the green is at 1/255 or 0.4 percent, and blue is 110/255 or 43.1 percent of its potential. So when you mix those three intensities of colour, blue is winning by a wide margin, but the red and green still contribute to make it a slightly different shade of blue than 0,0,110 would be on its own. + +These colours mapped to dimensions of the matrix may be referred to as channels. It may be helpful to display each of these channels independently, to help us understand what is happening. We can do that by multiplying our image array representation with a 1d matrix that has a one for the channel we want to keep and zeros for the rest. ```python red_channel = checkerboard * [1, 0, 0] @@ -565,43 +368,21 @@ ax.imshow(blue_channel) ![](fig/checkerboard-blue-channel.png){alt='Image of blue channel'} -If we look at the upper [1, 3] square in all three figures, -we can see each of those colour contributions in action. -Notice that there are several squares in the blue figure that look -even more intensely blue than square [1, 3]. -When all three channels are combined though, -the blue light of those squares is being diluted by the relative strength -of red and green being mixed in with them. +If we look at the upper [1, 3] square in all three figures, we can see each of those colour contributions in action. Notice that there are several squares in the blue figure that look even more intensely blue than square [1, 3]. When all three channels are combined though, the blue light of those squares is being diluted by the relative strength of red and green being mixed in with them. ## 24-bit RGB colour -This last colour model we used, -known as the *RGB (Red, Green, Blue)* model, is the most common. - -As we saw, the RGB model is an *additive* colour model, which means that the primary -colours are mixed together to form other colours. -Most frequently, the amount of the primary colour added is represented as -an integer in the closed range [0, 255] as seen in the example. -Therefore, there are 256 discrete amounts of each primary colour that can be -added to produce another colour. -The number of discrete amounts of each colour, 256, corresponds to the number of -bits used to hold the colour channel value, which is eight (28\=256). -Since we have three channels with 8 bits for each (8+8+8=24), -this is called 24-bit colour depth. - -Any particular colour in the RGB model can be expressed by a triplet of -integers in [0, 255], representing the red, green, and blue channels, -respectively. -A larger number in a channel means that more of that primary colour is present. +This last colour model we used, known as the *RGB (Red, Green, Blue)* model, is the most common. + +As we saw, the RGB model is an *additive* colour model, which means that the primary colours are mixed together to form other colours. Most frequently, the amount of the primary colour added is represented as an integer in the closed range [0, 255] as seen in the example. Therefore, there are 256 discrete amounts of each primary colour that can be added to produce another colour. The number of discrete amounts of each colour, 256, corresponds to the number of bits used to hold the colour channel value, which is eight (28\=256). Since we have three channels with 8 bits for each (8+8+8=24), this is called 24-bit colour depth. + +Any particular colour in the RGB model can be expressed by a triplet of integers in [0, 255], representing the red, green, and blue channels, respectively. A larger number in a channel means that more of that primary colour is present. ::::::::::::::::::::::::::::::::::::::: challenge ## Thinking about RGB colours (5 min) -Suppose that we represent colours as triples (r, g, b), where each of r, g, -and b is an integer in [0, 255]. -What colours are represented by each of these triples? -(Try to answer these questions without reading further.) +Suppose that we represent colours as triples (r, g, b), where each of r, g, and b is an integer in [0, 255]. What colours are represented by each of these triples? (Try to answer these questions without reading further.) 1. (255, 0, 0) 2. (0, 255, 0) @@ -614,32 +395,20 @@ What colours are represented by each of these triples? ## Solution -1. (255, 0, 0) represents red, because the red channel is maximised, while - the other two channels have the minimum values. +1. (255, 0, 0) represents red, because the red channel is maximised, while the other two channels have the minimum values. 2. (0, 255, 0) represents green. 3. (0, 0, 255) represents blue. -4. (255, 255, 255) is a little harder. When we mix the maximum value of all - three colour channels, we see the colour white. +4. (255, 255, 255) is a little harder. When we mix the maximum value of all three colour channels, we see the colour white. 5. (0, 0, 0) represents the absence of all colour, or black. -6. (128, 128, 128) represents a medium shade of gray. - Note that the 24-bit RGB colour model provides at least 254 shades of gray, - rather than only fifty. +6. (128, 128, 128) represents a medium shade of gray. Note that the 24-bit RGB colour model provides at least 254 shades of gray, rather than only fifty. -Note that the RGB colour model may run contrary to your experience, -especially if you have mixed primary colours of paint to create new colours. -In the RGB model, the *lack of* any colour is black, -while the *maximum amount* of each of the primary colours is white. -With physical paint, we might start with a white base, -and then add differing amounts of other paints to produce a darker shade. +Note that the RGB colour model may run contrary to your experience, especially if you have mixed primary colours of paint to create new colours. In the RGB model, the *lack of* any colour is black, while the *maximum amount* of each of the primary colours is white. With physical paint, we might start with a white base, and then add differing amounts of other paints to produce a darker shade. ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: -After completing the previous challenge, -we can look at some further examples of 24-bit RGB colours, in a visual way. -The image in the next challenge shows some colour names, -their 24-bit RGB triplet values, and the colour itself. +After completing the previous challenge, we can look at some further examples of 24-bit RGB colours, in a visual way. The image in the next challenge shows some colour names, their 24-bit RGB triplet values, and the colour itself. ::::::::::::::::::::::::::::::::::::::: challenge @@ -647,55 +416,27 @@ their 24-bit RGB triplet values, and the colour itself. ![](fig/colour-table.png){alt='RGB colour table'} -We cannot really provide a complete table. -To see why, answer this question: -How many possible colours can be represented with the 24-bit RGB model? +We cannot really provide a complete table. To see why, answer this question: How many possible colours can be represented with the 24-bit RGB model? ::::::::::::::: solution ## Solution -There are 24 total bits in an RGB colour of this type, -and each bit can be on or off, -and so there are 224 = 16,777,216 -possible colours with our additive, 24-bit RGB colour model. +There are 24 total bits in an RGB colour of this type, and each bit can be on or off, and so there are 224 = 16,777,216 possible colours with our additive, 24-bit RGB colour model. ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: -Although 24-bit colour depth is common, there are other options. -For example, we might have 8-bit colour -(3 bits for red and green, but only 2 for blue, providing 8 × 8 × 4 = 256 colours) -or 16-bit colour -(4 bits for red, green, and blue, plus 4 more for transparency, -providing 16 × 16 × 16 = 4096 colours, with 16 transparency levels each). -There are colour depths with more than eight bits per channel, -but as the human eye can only discern approximately 10 million different colours, -these are not often used. - -If you are using an older or inexpensive laptop screen or LCD monitor to view images, -it may only support 18-bit colour, capable of displaying -64 × 64 × 64 = 262,144 colours. -24-bit colour images will be converted in some manner to 18-bit, -and thus the colour quality you see will not match what is actually in the image. - -We can combine our coordinate system with the 24-bit RGB colour model to gain a -conceptual understanding of the images we will be working with. -An image is a rectangular array of pixels, -each with its own coordinate. -Each pixel in the image is a square point of coloured light, -where the colour is specified by a 24-bit RGB triplet. -Such an image is an example of *raster graphics*. +Although 24-bit colour depth is common, there are other options. For example, we might have 8-bit colour (3 bits for red and green, but only 2 for blue, providing 8 × 8 × 4 = 256 colours) or 16-bit colour (4 bits for red, green, and blue, plus 4 more for transparency, providing 16 × 16 × 16 = 4096 colours, with 16 transparency levels each). There are colour depths with more than eight bits per channel, but as the human eye can only discern approximately 10 million different colours, these are not often used. + +If you are using an older or inexpensive laptop screen or LCD monitor to view images, it may only support 18-bit colour, capable of displaying 64 × 64 × 64 = 262,144 colours. 24-bit colour images will be converted in some manner to 18-bit, and thus the colour quality you see will not match what is actually in the image. + +We can combine our coordinate system with the 24-bit RGB colour model to gain a conceptual understanding of the images we will be working with. An image is a rectangular array of pixels, each with its own coordinate. Each pixel in the image is a square point of coloured light, where the colour is specified by a 24-bit RGB triplet. Such an image is an example of *raster graphics*. ## Image formats -Although the images we will manipulate in our programs are conceptualised as -rectangular arrays of RGB triplets, -they are not necessarily created, stored, or transmitted in that format. -There are several image formats we might encounter, -and we should know the basics of at least of few of them. -Some formats we might encounter, and their file extensions, are shown in this table: +Although the images we will manipulate in our programs are conceptualised as rectangular arrays of RGB triplets, they are not necessarily created, stored, or transmitted in that format. There are several image formats we might encounter, and we should know the basics of at least of few of them. Some formats we might encounter, and their file extensions, are shown in this table: | Format | Extension | | :-------------------------------------- | :------------ | @@ -705,81 +446,27 @@ Some formats we might encounter, and their file extensions, are shown in this ta ## BMP -The file format that comes closest to our preceding conceptualisation of images -is the Device-Independent Bitmap, or BMP, file format. -BMP files store raster graphics images as long sequences of binary-encoded numbers -that specify the colour of each pixel in the image. -Since computer files are one-dimensional structures, -the pixel colours are stored one row at a time. -That is, the first row of pixels (those with y-coordinate 0) are stored first, -followed by the second row (those with y-coordinate 1), and so on. -Depending on how it was created, -a BMP image might have 8-bit, 16-bit, or 24-bit colour depth. - -24-bit BMP images have a relatively simple file format, -can be viewed and loaded across a wide variety of operating systems, -and have high quality. -However, BMP images are not *compressed*, -resulting in very large file sizes for any useful image resolutions. - -The idea of image compression is important to us for two reasons: -first, compressed images have smaller file sizes, -and are therefore easier to store and transmit; -and second, -compressed images may not have as much detail as their uncompressed counterparts, -and so our programs may not be able to detect some important aspect -if we are working with compressed images. -Since compression is important to us, -we should take a brief detour and discuss the concept. +The file format that comes closest to our preceding conceptualisation of images is the Device-Independent Bitmap, or BMP, file format. BMP files store raster graphics images as long sequences of binary-encoded numbers that specify the colour of each pixel in the image. Since computer files are one-dimensional structures, the pixel colours are stored one row at a time. That is, the first row of pixels (those with y-coordinate 0) are stored first, followed by the second row (those with y-coordinate 1), and so on. Depending on how it was created, a BMP image might have 8-bit, 16-bit, or 24-bit colour depth. + +24-bit BMP images have a relatively simple file format, can be viewed and loaded across a wide variety of operating systems, and have high quality. However, BMP images are not *compressed*, resulting in very large file sizes for any useful image resolutions. + +The idea of image compression is important to us for two reasons: first, compressed images have smaller file sizes, and are therefore easier to store and transmit; and second, compressed images may not have as much detail as their uncompressed counterparts, and so our programs may not be able to detect some important aspect if we are working with compressed images. Since compression is important to us, we should take a brief detour and discuss the concept. ## Image compression -Before discussing additional formats, -familiarity with image compression will be helpful. -Let's delve into that subject with a challenge. -For this challenge, -you will need to know about bits / bytes and -how those are used to express computer storage capacities. -If you already know, you can skip to the challenge below. +Before discussing additional formats, familiarity with image compression will be helpful. Let's delve into that subject with a challenge. For this challenge, you will need to know about bits / bytes and how those are used to express computer storage capacities. If you already know, you can skip to the challenge below. :::::::::::::::::::::::::::::::::::::::: callout ## Bits and bytes -Before we talk specifically about images, -we first need to understand how numbers are stored in a modern digital computer. -When we think of a number, -we do so using a *decimal*, or *base-10* place-value number system. -For example, a number like 659 is -6 × 102 + 5 × 101 + 9 × 100. -Each digit in the number is multiplied by a power of 10, -based on where it occurs, -and there are 10 digits that can occur in each position -(0, 1, 2, 3, 4, 5, 6, 7, 8, 9). - -In principle, -computers could be constructed to represent numbers in exactly the same way. -But, the electronic circuits inside a computer are much easier to construct -if we restrict the numeric base to only two, instead of 10. -(It is easier for circuitry to tell the difference between -two voltage levels than it is to differentiate among 10 levels.) -So, values in a computer are stored using a *binary*, -or *base-2* place-value number system. - -In this system, each symbol in a number is called a *bit* instead of a digit, -and there are only two values for each bit (0 and 1). -We might imagine a four-bit binary number, 1101. -Using the same kind of place-value expansion as we did above for 659, -we see that -1101 = 1 × 23 + 1 × 22 + 0 × 21 + 1 × 20, -which if we do the math is 8 + 4 + 0 + 1, or 13 in decimal. - -Internally, -computers have a minimum number of bits that they work with at a given time: eight. -A group of eight bits is called a *byte*. -The amount of memory (RAM) and drive space our computers have is quantified -by terms like Megabytes (MB), Gigabytes (GB), and Terabytes (TB). -The following table provides more formal definitions for these terms. +Before we talk specifically about images, we first need to understand how numbers are stored in a modern digital computer. When we think of a number, we do so using a *decimal*, or *base-10* place-value number system. For example, a number like 659 is 6 × 102 + 5 × 101 + 9 × 100. Each digit in the number is multiplied by a power of 10, based on where it occurs, and there are 10 digits that can occur in each position (0, 1, 2, 3, 4, 5, 6, 7, 8, 9). + +In principle, computers could be constructed to represent numbers in exactly the same way. But, the electronic circuits inside a computer are much easier to construct if we restrict the numeric base to only two, instead of 10. (It is easier for circuitry to tell the difference between two voltage levels than it is to differentiate among 10 levels.) So, values in a computer are stored using a *binary*, or *base-2* place-value number system. + +In this system, each symbol in a number is called a *bit* instead of a digit, and there are only two values for each bit (0 and 1). We might imagine a four-bit binary number, 1101. Using the same kind of place-value expansion as we did above for 659, we see that 1101 = 1 × 23 + 1 × 22 + 0 × 21 + 1 × 20, which if we do the math is 8 + 4 + 0 + 1, or 13 in decimal. + +Internally, computers have a minimum number of bits that they work with at a given time: eight. A group of eight bits is called a *byte*. The amount of memory (RAM) and drive space our computers have is quantified by terms like Megabytes (MB), Gigabytes (GB), and Terabytes (TB). The following table provides more formal definitions for these terms. | Unit | Abbreviation | Size | | :-------------------------------------- | ------------- | :--------- | @@ -794,109 +481,47 @@ The following table provides more formal definitions for these terms. ## BMP image size (optional, not included in timing) -Imagine that we have a fairly large, but very boring image: -a 5,000 × 5,000 pixel image composed of nothing but white pixels. -If we used an uncompressed image format such as BMP, -with the 24-bit RGB colour model, -how much storage would be required for the file? +Imagine that we have a fairly large, but very boring image: a 5,000 × 5,000 pixel image composed of nothing but white pixels. If we used an uncompressed image format such as BMP, with the 24-bit RGB colour model, how much storage would be required for the file? ::::::::::::::: solution ## Solution -In such an image, there are 5,000 × 5,000 = 25,000,000 pixels, -and 24 bits for each pixel, -leading to 25,000,000 × 24 = 600,000,000 bits, -or 75,000,000 bytes (71.5MB). -That is quite a lot of space for a very uninteresting image! +In such an image, there are 5,000 × 5,000 = 25,000,000 pixels, and 24 bits for each pixel, leading to 25,000,000 × 24 = 600,000,000 bits, or 75,000,000 bytes (71.5MB). That is quite a lot of space for a very uninteresting image! ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: -Since image files can be very large, -various *compression* schemes exist for saving -(approximately) the same information while using less space. -These compression techniques can be categorised as *lossless* or *lossy*. +Since image files can be very large, various *compression* schemes exist for saving (approximately) the same information while using less space. These compression techniques can be categorised as *lossless* or *lossy*. ### Lossless compression -In lossless image compression, -we apply some algorithm (i.e., a computerised procedure) to the image, -resulting in a file that is significantly smaller than -the uncompressed BMP file equivalent would be. -Then, when we wish to load and view or process the image, -our program reads the compressed file, and reverses the compression process, -resulting in an image that is *identical* to the original. -Nothing is lost in the process -- hence the term "lossless." - -The general idea of lossless compression is to somehow detect -long patterns of bytes in a file that are repeated over and over, -and then assign a smaller bit pattern to represent the longer sample. -Then, the compressed file is made up of the smaller patterns, -rather than the larger ones, -thus reducing the number of bytes required to save the file. -The compressed file also contains -a table of the substituted patterns and the originals, -so when the file is decompressed it can be -made identical to the original before compression. - -To provide you with a concrete example, -consider the 71.5 MB white BMP image discussed above. -When put through the zip compression utility on Microsoft Windows, -the resulting .zip file is only 72 KB in size! -That is, the .zip version of the image is -three orders of magnitude smaller than the original, -and it can be decompressed into a file that is -byte-for-byte the same as the original. -Since the original is so repetitious - -simply the same colour triplet repeated 25,000,000 times - -the compression algorithm can dramatically reduce the size of the file. - -If you work with .zip or .gz archives, you are dealing with lossless -compression. +In lossless image compression, we apply some algorithm (i.e., a computerised procedure) to the image, resulting in a file that is significantly smaller than the uncompressed BMP file equivalent would be. Then, when we wish to load and view or process the image, our program reads the compressed file, and reverses the compression process, resulting in an image that is *identical* to the original. Nothing is lost in the process -- hence the term "lossless." + +The general idea of lossless compression is to somehow detect long patterns of bytes in a file that are repeated over and over, and then assign a smaller bit pattern to represent the longer sample. Then, the compressed file is made up of the smaller patterns, rather than the larger ones, thus reducing the number of bytes required to save the file. The compressed file also contains a table of the substituted patterns and the originals, so when the file is decompressed it can be made identical to the original before compression. + +To provide you with a concrete example, consider the 71.5 MB white BMP image discussed above. When put through the zip compression utility on Microsoft Windows, the resulting .zip file is only 72 KB in size! That is, the .zip version of the image is three orders of magnitude smaller than the original, and it can be decompressed into a file that is byte-for-byte the same as the original. Since the original is so repetitious - simply the same colour triplet repeated 25,000,000 times - the compression algorithm can dramatically reduce the size of the file. + +If you work with .zip or .gz archives, you are dealing with lossless compression. ### Lossy compression -Lossy compression takes the original image and discards some of the detail in it, -resulting in a smaller file format. -The goal is to only throw away detail that someone viewing the image would not notice. -Many lossy compression schemes have adjustable levels of compression, -so that the image creator can choose the amount of detail that is lost. -The more detail that is sacrificed, -the smaller the image files will be - -but of course, the detail and richness of the image will be lower as well. - -This is probably fine for images that are shown on Web pages -or printed off on 4 × 6 photo paper, -but may or may not be fine for scientific work. -You will have to decide whether the loss of image quality and detail are -important to your work, -versus the space savings afforded by a lossy compression format. - -It is important to understand that -once an image is saved in a lossy compression format, -the lost detail is just that - lost. -I.e., unlike lossless formats, -given an image saved in a lossy format, -there is no way to reconstruct the original image in a byte-by-byte manner. +Lossy compression takes the original image and discards some of the detail in it, resulting in a smaller file format. The goal is to only throw away detail that someone viewing the image would not notice. Many lossy compression schemes have adjustable levels of compression, so that the image creator can choose the amount of detail that is lost. The more detail that is sacrificed, the smaller the image files will be - but of course, the detail and richness of the image will be lower as well. + +This is probably fine for images that are shown on Web pages or printed off on 4 × 6 photo paper, but may or may not be fine for scientific work. You will have to decide whether the loss of image quality and detail are important to your work, versus the space savings afforded by a lossy compression format. + +It is important to understand that once an image is saved in a lossy compression format, the lost detail is just that - lost. I.e., unlike lossless formats, given an image saved in a lossy format, there is no way to reconstruct the original image in a byte-by-byte manner. ## JPEG -JPEG images are perhaps the most commonly encountered digital images today. -JPEG uses lossy compression, -and the degree of compression can be tuned to your liking. -It supports 24-bit colour depth, -and since the format is so widely used, -JPEG images can be viewed and manipulated easily on all computing platforms. +JPEG images are perhaps the most commonly encountered digital images today. JPEG uses lossy compression, and the degree of compression can be tuned to your liking. It supports 24-bit colour depth, and since the format is so widely used, JPEG images can be viewed and manipulated easily on all computing platforms. ::::::::::::::::::::::::::::::::::::::: challenge ## Examining actual image sizes (optional, not included in timing) -Let us see the effects of image compression on image size with actual images. -The following script creates a square white image 5000 x 5000 pixels, -and then saves it as a BMP and as a JPEG image. +Let us see the effects of image compression on image size with actual images. The following script creates a square white image 5000 x 5000 pixels, and then saves it as a BMP and as a JPEG image. ```python dim = 5000 @@ -908,18 +533,13 @@ iio.imwrite(uri="data/ws.bmp", image=img) iio.imwrite(uri="data/ws.jpg", image=img) ``` -Examine the file sizes of the two output files, `ws.bmp` and `ws.jpg`. -Does the BMP image size match our previous prediction? -How about the JPEG? +Examine the file sizes of the two output files, `ws.bmp` and `ws.jpg`. Does the BMP image size match our previous prediction? How about the JPEG? ::::::::::::::: solution ## Solution -The BMP file, `ws.bmp`, is 75,000,054 bytes, -which matches our prediction very nicely. -The JPEG file, `ws.jpg`, is 392,503 bytes, -two orders of magnitude smaller than the bitmap version. +The BMP file, `ws.bmp`, is 75,000,054 bytes, which matches our prediction very nicely. The JPEG file, `ws.jpg`, is 392,503 bytes, two orders of magnitude smaller than the bitmap version. ::::::::::::::::::::::::: @@ -929,26 +549,11 @@ two orders of magnitude smaller than the bitmap version. ## Comparing lossless versus lossy compression (optional, not included in timing) -Let us see a hands-on example of lossless versus lossy compression. -Open a terminal (or Windows PowerShell) and navigate to the `data/` directory. -The two output images, `ws.bmp` and `ws.jpg`, should still be in the directory, -along with another image, `tree.jpg`. - -We can apply lossless compression to any file by using the `zip` command. -Recall that the `ws.bmp` file contains 75,000,054 bytes. -Apply lossless compression to this image by executing the following command: -`zip ws.zip ws.bmp` -(`Compress-Archive ws.bmp ws.zip` with PowerShell). -This command tells the computer to create a new compressed file, -`ws.zip`, from the original bitmap image. -Execute a similar command on the tree JPEG file: `zip tree.zip tree.jpg` -(`Compress-Archive tree.jpg tree.zip` with PowerShell). - -Having created the compressed file, -use the `ls -l` command (`dir` with PowerShell) to display the contents of the directory. -How big are the compressed files? -How do those compare to the size of `ws.bmp` and `tree.jpg`? -What can you conclude from the relative sizes? +Let us see a hands-on example of lossless versus lossy compression. Open a terminal (or Windows PowerShell) and navigate to the `data/` directory. The two output images, `ws.bmp` and `ws.jpg`, should still be in the directory, along with another image, `tree.jpg`. + +We can apply lossless compression to any file by using the `zip` command. Recall that the `ws.bmp` file contains 75,000,054 bytes. Apply lossless compression to this image by executing the following command: `zip ws.zip ws.bmp` (`Compress-Archive ws.bmp ws.zip` with PowerShell). This command tells the computer to create a new compressed file, `ws.zip`, from the original bitmap image. Execute a similar command on the tree JPEG file: `zip tree.zip tree.jpg` (`Compress-Archive tree.jpg tree.zip` with PowerShell). + +Having created the compressed file, use the `ls -l` command (`dir` with PowerShell) to display the contents of the directory. How big are the compressed files? How do those compare to the size of `ws.bmp` and `tree.jpg`? What can you conclude from the relative sizes? ::::::::::::::: solution @@ -963,101 +568,49 @@ Here is a partial directory listing, showing the sizes of the relevant files the -rw-rw-r-- 1 diva diva 72986 Jun 18 08:53 ws.zip ``` -We can see that the regularity of the bitmap image -(remember, it is a 5,000 x 5,000 pixel image containing only white pixels) -allows the lossless compression scheme to compress the file quite effectively. -On the other hand, compressing `tree.jpg` does not create a much smaller file; -this is because the JPEG image was already in a compressed format. +We can see that the regularity of the bitmap image (remember, it is a 5,000 x 5,000 pixel image containing only white pixels) allows the lossless compression scheme to compress the file quite effectively. On the other hand, compressing `tree.jpg` does not create a much smaller file; this is because the JPEG image was already in a compressed format. ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: -Here is an example showing how JPEG compression might impact image quality. -Consider this image of several maize seedlings -(scaled down here from 11,339 × 11,336 pixels in order to fit the display). +Here is an example showing how JPEG compression might impact image quality. Consider this image of several maize seedlings (scaled down here from 11,339 × 11,336 pixels in order to fit the display). ![](fig/quality-original.jpg){alt='Original image'} -Now, let us zoom in and look at a small section of the label in the original, -first in the uncompressed format: +Now, let us zoom in and look at a small section of the label in the original, first in the uncompressed format: ![](fig/quality-tif.jpg){alt='Enlarged, uncompressed'} -Here is the same area of the image, but in JPEG format. -We used a fairly aggressive compression parameter to make the JPEG, -in order to illustrate the problems you might encounter with the format. +Here is the same area of the image, but in JPEG format. We used a fairly aggressive compression parameter to make the JPEG, in order to illustrate the problems you might encounter with the format. ![](fig/quality-jpg.jpg){alt='Enlarged, compressed'} -The JPEG image is of clearly inferior quality. -It has less colour variation and noticeable pixelation. -Quality differences become even more marked when one examines -the colour histograms for each image. -A histogram shows how often each colour value appears in an image. -The histograms for the uncompressed (left) and compressed (right) images -are shown below: +The JPEG image is of clearly inferior quality. It has less colour variation and noticeable pixelation. Quality differences become even more marked when one examines the colour histograms for each image. A histogram shows how often each colour value appears in an image. The histograms for the uncompressed (left) and compressed (right) images are shown below: ![](fig/quality-histogram.jpg){alt='Uncompressed histogram'} -We learn how to make histograms such as these later on in the workshop. -The differences in the colour histograms are even more apparent than in the -images themselves; -clearly the colours in the JPEG image are different from the uncompressed version. - -If the quality settings for your JPEG images are high -(and the compression rate therefore relatively low), -the images may be of sufficient quality for your work. -It all depends on how much quality you need, -and what restrictions you have on image storage space. -Another consideration may be *where* the images are stored. -For example, if your images are stored in the cloud and therefore -must be downloaded to your system before you use them, -you may wish to use a compressed image format to speed up file transfer time. +We learn how to make histograms such as these later on in the workshop. The differences in the colour histograms are even more apparent than in the images themselves; clearly the colours in the JPEG image are different from the uncompressed version. + +If the quality settings for your JPEG images are high (and the compression rate therefore relatively low), the images may be of sufficient quality for your work. It all depends on how much quality you need, and what restrictions you have on image storage space. Another consideration may be *where* the images are stored. For example, if your images are stored in the cloud and therefore must be downloaded to your system before you use them, you may wish to use a compressed image format to speed up file transfer time. ## PNG -PNG images are well suited for storing diagrams. It uses a lossless compression and is hence often used -in web applications for non-photographic images. The format is able to store RGB and plain luminance (single channel, without an associated color) data, among others. Image data is stored row-wise and then, per row, a simple filter, like taking the difference of adjacent pixels, can be applied to -increase the compressability of the data. The filtered data is then compressed in the next step and written out to the disk. +PNG images are well suited for storing diagrams. It uses a lossless compression and is hence often used in web applications for non-photographic images. The format is able to store RGB and plain luminance (single channel, without an associated color) data, among others. Image data is stored row-wise and then, per row, a simple filter, like taking the difference of adjacent pixels, can be applied to increase the compressability of the data. The filtered data is then compressed in the next step and written out to the disk. ## TIFF -TIFF images are popular with publishers, graphics designers, and photographers. -TIFF images can be uncompressed, -or compressed using either lossless or lossy compression schemes, -depending on the settings used, -and so TIFF images seem to have the benefits of both the BMP and JPEG formats. -The main disadvantage of TIFF images -(other than the size of images in the uncompressed version of the format) -is that they are not universally readable by image viewing and manipulation software. +TIFF images are popular with publishers, graphics designers, and photographers. TIFF images can be uncompressed, or compressed using either lossless or lossy compression schemes, depending on the settings used, and so TIFF images seem to have the benefits of both the BMP and JPEG formats. The main disadvantage of TIFF images (other than the size of images in the uncompressed version of the format) is that they are not universally readable by image viewing and manipulation software. ## Metadata -JPEG and TIFF images support the inclusion of *metadata* in images. -Metadata is textual information that is contained within an image file. -Metadata holds information about the image itself, -such as when the image was captured, -where it was captured, -what type of camera was used and with what settings, etc. -We normally don't see this metadata when we view an image, -but we can view it independently if we wish to -(see [*Accessing Metadata*](#accessing-metadata), below). -The important thing to be aware of at this stage is that -you cannot rely on the metadata of an image being fully preserved -when you use software to process that image. -The image reader/writer library that we use throughout this lesson, -`imageio.v3`, includes metadata when saving new images but may fail to keep -certain metadata fields. -In any case, remember: **if metadata is important to you, -take precautions to always preserve the original files**. +JPEG and TIFF images support the inclusion of *metadata* in images. Metadata is textual information that is contained within an image file. Metadata holds information about the image itself, such as when the image was captured, where it was captured, what type of camera was used and with what settings, etc. We normally don't see this metadata when we view an image, but we can view it independently if we wish to (see [*Accessing Metadata*](#accessing-metadata), below). The important thing to be aware of at this stage is that you cannot rely on the metadata of an image being fully preserved when you use software to process that image. The image reader/writer library that we use throughout this lesson, `imageio.v3`, includes metadata when saving new images but may fail to keep certain metadata fields. In any case, remember: **if metadata is important to you, take precautions to always preserve the original files**. :::::::::::::::::::::::::::::::::::::::: callout ## Accessing Metadata -`imageio.v3` provides a way to display or explore the metadata -associated with an image. Metadata is served independently from pixel data: +`imageio.v3` provides a way to display or explore the metadata associated with an image. Metadata is served independently from pixel data: ```python # read metadata @@ -1088,24 +641,13 @@ metadata 'resolution': (1.0, 1.0, 'NONE')} ``` -Many popular image editing programs have built-in metadata viewing -capabilities. A platform-independent open-source tool that allows -users to read, write, and edit metadata is -[ExifTool](https://exiftool.org/). It can handle a wide range of file -types and metadata formats but requires some technical knowledge to be -used effectively. -Other software exists that can help you handle metadata, -e.g., [Fiji](https://imagej.net/Fiji) -and [ImageMagick](https://imagemagick.org/index.php). -You may want to explore these options if you need to work with -the metadata of your images. +Many popular image editing programs have built-in metadata viewing capabilities. A platform-independent open-source tool that allows users to read, write, and edit metadata is [ExifTool](https://exiftool.org/). It can handle a wide range of file types and metadata formats but requires some technical knowledge to be used effectively. Other software exists that can help you handle metadata, e.g., [Fiji](https://imagej.net/Fiji) and [ImageMagick](https://imagemagick.org/index.php). You may want to explore these options if you need to work with the metadata of your images. :::::::::::::::::::::::::::::::::::::::::::::::::: ## Summary of image formats used in this lesson -The following table summarises the characteristics of the BMP, JPEG, and TIFF -image formats: +The following table summarises the characteristics of the BMP, JPEG, and TIFF image formats: | Format | Compression | Metadata | Advantages | Disadvantages | | :--------------- | :------------ | :--------- | :--------------------- | :--------------------- | From 98f534dd5500dd1b81f627b61b8193412b27c644 Mon Sep 17 00:00:00 2001 From: Marco Dalla Vecchia Date: Sun, 29 Mar 2026 18:06:18 +0200 Subject: [PATCH 3/4] formatted all episodes --- episodes/03-reading-images.md | 264 ++++------------------- episodes/04-drawing.md | 199 +++--------------- episodes/05-preprocessing.md | 1 - episodes/06-blurring.md | 279 +++++-------------------- episodes/07-postprocessing.md | 383 +++++----------------------------- episodes/10-challenges.md | 66 ++---- 6 files changed, 194 insertions(+), 998 deletions(-) diff --git a/episodes/03-reading-images.md b/episodes/03-reading-images.md index be73be2..aef8a05 100644 --- a/episodes/03-reading-images.md +++ b/episodes/03-reading-images.md @@ -20,8 +20,7 @@ exercises: 50 :::::::::::::::::::::::::::::::::::::::::::::::::: -We have covered much of how images are represented in computer software. In this episode we will learn some more methods -for accessing and changing digital images. +We have covered much of how images are represented in computer software. In this episode we will learn some more methods for accessing and changing digital images. ## First, import the packages needed for this episode @@ -37,16 +36,9 @@ import skimage as ski ## Reading, displaying, and saving images -Imageio provides intuitive functions for reading and writing (saving) images. -All of the popular image formats, such as BMP, PNG, JPEG, and TIFF are supported, -along with several more esoteric formats. Check the -[Supported Formats docs](https://imageio.readthedocs.io/en/stable/formats/index.html) -for a list of all formats. -Matplotlib provides a large collection of plotting utilities. +Imageio provides intuitive functions for reading and writing (saving) images. All of the popular image formats, such as BMP, PNG, JPEG, and TIFF are supported, along with several more esoteric formats. Check the [Supported Formats docs](https://imageio.readthedocs.io/en/stable/formats/index.html) for a list of all formats. Matplotlib provides a large collection of plotting utilities. -Let us examine a simple Python program to load, display, -and save an image to a different format. -Here are the first few lines: +Let us examine a simple Python program to load, display, and save an image to a different format. Here are the first few lines: ```python """Python program to open, display, and save an image.""" @@ -54,9 +46,7 @@ Here are the first few lines: chair = iio.imread(uri="data/chair.jpg") ``` -We use the `iio.imread()` function to read a JPEG image entitled **chair.jpg**. -Imageio reads the image, converts it from JPEG into a NumPy array, -and returns the array; we save the array in a variable named `chair`. +We use the `iio.imread()` function to read a JPEG image entitled **chair.jpg**. Imageio reads the image, converts it from JPEG into a NumPy array, and returns the array; we save the array in a variable named `chair`. Next, we will do something with the image: @@ -65,10 +55,7 @@ fig, ax = plt.subplots() ax.imshow(chair) ``` -Once we have the image in the program, -we first call `fig, ax = plt.subplots()` so that we will have -a fresh figure with a set of axes independent from our previous calls. -Next we call `ax.imshow()` in order to display the image. +Once we have the image in the program, we first call `fig, ax = plt.subplots()` so that we will have a fresh figure with a set of axes independent from our previous calls. Next we call `ax.imshow()` in order to display the image. Now, we will save the image in another format: @@ -77,21 +64,13 @@ Now, we will save the image in another format: iio.imwrite(uri="data/chair.tif", image=chair) ``` -The final statement in the program, `iio.imwrite(uri="data/chair.tif", image=chair)`, -writes the image to a file named `chair.tif` in the `data/` directory. -The `imwrite()` function automatically determines the type of the file, -based on the file extension we provide. -In this case, the `.tif` extension causes the image to be saved as a TIFF. +The final statement in the program, `iio.imwrite(uri="data/chair.tif", image=chair)`, writes the image to a file named `chair.tif` in the `data/` directory. The `imwrite()` function automatically determines the type of the file, based on the file extension we provide. In this case, the `.tif` extension causes the image to be saved as a TIFF. :::::::::::::::::::::::::::::::::::::::: callout ## Metadata, revisited -Remember, as mentioned in the previous section, *images saved with `imwrite()` -will not retain all metadata associated with the original image -that was loaded into Python!* -If the image metadata is important to you, be sure to **always keep an unchanged -copy of the original image!** +Remember, as mentioned in the previous section, *images saved with `imwrite()` will not retain all metadata associated with the original image that was loaded into Python!* If the image metadata is important to you, be sure to **always keep an unchanged copy of the original image!** :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -99,12 +78,7 @@ copy of the original image!** ## Extensions do not always dictate file type -The `iio.imwrite()` function automatically uses the file type we specify in -the file name parameter's extension. -Note that this is not always the case. -For example, if we are editing a document in Microsoft Word, -and we save the document as `paper.pdf` instead of `paper.docx`, -the file *is not* saved as a PDF document. +The `iio.imwrite()` function automatically uses the file type we specify in the file name parameter's extension. Note that this is not always the case. For example, if we are editing a document in Microsoft Word, and we save the document as `paper.pdf` instead of `paper.docx`, the file *is not* saved as a PDF document. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -112,32 +86,19 @@ the file *is not* saved as a PDF document. ## Named versus positional arguments -When we call functions in Python, -there are two ways we can specify the necessary arguments. -We can specify the arguments *positionally*, i.e., -in the order the parameters appear in the function definition, -or we can use *named arguments*. +When we call functions in Python, there are two ways we can specify the necessary arguments. We can specify the arguments *positionally*, i.e., in the order the parameters appear in the function definition, or we can use *named arguments*. -For example, the `iio.imwrite()` -[function definition](https://imageio.readthedocs.io/en/stable/_autosummary/imageio.v3.imwrite.html) -specifies two parameters, -the resource to save the image to (e.g., a file name, an http address) and -the image to write to disk. -So, we could save the chair image in the sample code above -using positional arguments like this: +For example, the `iio.imwrite()` [function definition](https://imageio.readthedocs.io/en/stable/_autosummary/imageio.v3.imwrite.html) specifies two parameters, the resource to save the image to (e.g., a file name, an http address) and the image to write to disk. So, we could save the chair image in the sample code above using positional arguments like this: `iio.imwrite("data/chair.tif", image)` -Since the function expects the first argument to be the file name, -there is no confusion about what `"data/chair.jpg"` means. The same goes -for the second argument. +Since the function expects the first argument to be the file name, there is no confusion about what `"data/chair.jpg"` means. The same goes for the second argument. The style we will use in this workshop is to name each argument, like this: `iio.imwrite(uri="data/chair.tif", image=image)` -This style will make it easier for you to learn how to use the variety of -functions we will cover in this workshop. +This style will make it easier for you to learn how to use the variety of functions we will cover in this workshop. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -145,9 +106,7 @@ functions we will cover in this workshop. ## Resizing an image (10 min) -Using the `chair.jpg` image located in the data folder, -write a Python script to read your image into a variable named `chair`. -Then, resize the image to 10 percent of its current size using these lines of code: +Using the `chair.jpg` image located in the data folder, write a Python script to read your image into a variable named `chair`. Then, resize the image to 10 percent of its current size using these lines of code: ```python new_shape = (chair.shape[0] // 10, chair.shape[1] // 10, chair.shape[2]) @@ -155,44 +114,17 @@ resized_chair = ski.transform.resize(image=chair, output_shape=new_shape) resized_chair = ski.util.img_as_ubyte(resized_chair) ``` -As it is used here, -the parameters to the `ski.transform.resize()` function are -the image to transform, `chair`, -the dimensions we want the new image to have, `new_shape`. +As it is used here, the parameters to the `ski.transform.resize()` function are the image to transform, `chair`, the dimensions we want the new image to have, `new_shape`. ::::::::::::::::::::::::::::::::::::::::: callout -Note that the pixel values in the new image are an approximation of -the original values and should not be confused with actual, observed -data. This is because scikit-image interpolates the pixel values when -reducing or increasing the size of an -image. `ski.transform.resize` has a number of optional -parameters that allow the user to control this interpolation. You -can find more details in the [scikit-image -documentation](https://scikit-image.org/docs/stable/api/skimage.transform.html#skimage.transform.resize). +Note that the pixel values in the new image are an approximation of the original values and should not be confused with actual, observed data. This is because scikit-image interpolates the pixel values when reducing or increasing the size of an image. `ski.transform.resize` has a number of optional parameters that allow the user to control this interpolation. You can find more details in the [scikit-image documentation](https://scikit-image.org/docs/stable/api/skimage.transform.html#skimage.transform.resize). :::::::::::::::::::::::::::::::::::::::::::::::::: -Image files on disk are normally stored as whole numbers for space efficiency, -but transformations and other math operations often result in -conversion to floating point numbers. -Using the `ski.util.img_as_ubyte()` method converts it back to whole numbers -before we save it back to disk. -If we don't convert it before saving, -`iio.imwrite()` may not recognise it as image data. - -Next, write the resized image out to a new file named `resized.jpg` -in your data directory. -Finally, use `ax.imshow()` with each of your image variables to display -both images in your notebook. -Don't forget to use `fig, ax = plt.subplots()` so you don't overwrite -the first image with the second. -Images may appear the same size in jupyter, -but you can see the size difference by comparing the scales for each. -You can also see the difference in file storage size on disk by -hovering your mouse cursor over the original -and the new files in the Jupyter file browser, using `ls -l` in your shell -(`dir` with Windows PowerShell), or viewing file sizes in the OS file browser if it is configured so. +Image files on disk are normally stored as whole numbers for space efficiency, but transformations and other math operations often result in conversion to floating point numbers. Using the `ski.util.img_as_ubyte()` method converts it back to whole numbers before we save it back to disk. If we don't convert it before saving, `iio.imwrite()` may not recognise it as image data. + +Next, write the resized image out to a new file named `resized.jpg` in your data directory. Finally, use `ax.imshow()` with each of your image variables to display both images in your notebook. Don't forget to use `fig, ax = plt.subplots()` so you don't overwrite the first image with the second. Images may appear the same size in jupyter, but you can see the size difference by comparing the scales for each. You can also see the difference in file storage size on disk by hovering your mouse cursor over the original and the new files in the Jupyter file browser, using `ls -l` in your shell (`dir` with Windows PowerShell), or viewing file sizes in the OS file browser if it is configured so. ::::::::::::::: solution @@ -221,9 +153,7 @@ fig, ax = plt.subplots() ax.imshow(resized_chair) ``` -The script resizes the `data/chair.jpg` image by a factor of 10 in both dimensions, -saves the result to the `data/resized_chair.jpg` file, -and displays original and resized for comparision. +The script resizes the `data/chair.jpg` image by a factor of 10 in both dimensions, saves the result to the `data/resized_chair.jpg` file, and displays original and resized for comparision. ::::::::::::::::::::::::: @@ -231,28 +161,13 @@ and displays original and resized for comparision. ## Manipulating pixels -In [the *Image Basics* episode](02-image-basics.md), -we individually manipulated the colours of pixels by changing the numbers stored -in the image's NumPy array. Let's apply the principles learned there -along with some new principles to a real world example. +In [the *Image Basics* episode](02-image-basics.md), we individually manipulated the colours of pixels by changing the numbers stored in the image's NumPy array. Let's apply the principles learned there along with some new principles to a real world example. -Suppose we are interested in this maize root cluster image. -We want to be able to focus our program's attention on the roots themselves, -while ignoring the black background. +Suppose we are interested in this maize root cluster image. We want to be able to focus our program's attention on the roots themselves, while ignoring the black background. ![](fig/maize-root-cluster.jpg){alt='Root cluster image'} -Since the image is stored as an array of numbers, -we can simply look through the array for pixel colour values that are -less than some threshold value. -This process is called *thresholding*, -and we will see more powerful methods to perform the thresholding task in -[the *Thresholding* episode](06-processing-segmentation.md). -Here, though, we will look at a simple and elegant NumPy method for thresholding. -Let us develop a program that keeps only the pixel colour values in an image -that have value greater than or equal to 128. -This will keep the pixels that are brighter than half of "full brightness", -i.e., pixels that do not belong to the black background. +Since the image is stored as an array of numbers, we can simply look through the array for pixel colour values that are less than some threshold value. This process is called *thresholding*, and we will see more powerful methods to perform the thresholding task in [the *Thresholding* episode](06-processing-segmentation.md). Here, though, we will look at a simple and elegant NumPy method for thresholding. Let us develop a program that keeps only the pixel colour values in an image that have value greater than or equal to 128. This will keep the pixels that are brighter than half of "full brightness", i.e., pixels that do not belong to the black background. We will start by reading the image and displaying it. @@ -287,41 +202,19 @@ fig, ax = plt.subplots() ax.imshow(maize_roots) ``` -The NumPy command to ignore all low-intensity pixels is `roots[roots < 128] = 0`. -Every pixel colour value in the whole 3-dimensional array with a value less -that 128 is set to zero. -In this case, -the result is an image in which the extraneous background detail has been removed. +The NumPy command to ignore all low-intensity pixels is `roots[roots < 128] = 0`. Every pixel colour value in the whole 3-dimensional array with a value less that 128 is set to zero. In this case, the result is an image in which the extraneous background detail has been removed. ![](fig/maize-root-cluster-threshold.jpg){alt='Thresholded root image'} ## Converting colour images to grayscale -It is often easier to work with grayscale images, which have a single channel, -instead of colour images, which have three channels. -scikit-image offers the function `ski.color.rgb2gray()` to achieve this. -This function adds up the three colour channels in a way that matches -human colour perception, -see [the scikit-image documentation for details](https://scikit-image.org/docs/dev/api/skimage.color.html#skimage.color.rgb2gray). -It returns a grayscale image with floating point values in the range from 0 to 1. -We can use the function `ski.util.img_as_ubyte()` in order to convert it back to the -original data type and the data range back 0 to 255. -Note that it is often better to use image values represented by floating point values, -because using floating point numbers is numerically more stable. +It is often easier to work with grayscale images, which have a single channel, instead of colour images, which have three channels. scikit-image offers the function `ski.color.rgb2gray()` to achieve this. This function adds up the three colour channels in a way that matches human colour perception, see [the scikit-image documentation for details](https://scikit-image.org/docs/dev/api/skimage.color.html#skimage.color.rgb2gray). It returns a grayscale image with floating point values in the range from 0 to 1. We can use the function `ski.util.img_as_ubyte()` in order to convert it back to the original data type and the data range back 0 to 255. Note that it is often better to use image values represented by floating point values, because using floating point numbers is numerically more stable. :::::::::::::::::::::::::::::::::::::::: callout ## Colour and `color` -The Carpentries generally prefers UK English spelling, -which is why we use "colour" in the explanatory text of this lesson. -However, scikit-image contains many modules and functions that include -the US English spelling, `color`. -The exact spelling matters here, -e.g. you will encounter an error if you try to run `ski.colour.rgb2gray()`. -To account for this, we will use the US English spelling, `color`, -in example Python code throughout the lesson. -You will encounter a similar approach with "centre" and `center`. +The Carpentries generally prefers UK English spelling, which is why we use "colour" in the explanatory text of this lesson. However, scikit-image contains many modules and functions that include the US English spelling, `color`. The exact spelling matters here, e.g. you will encounter an error if you try to run `ski.colour.rgb2gray()`. To account for this, we will use the US English spelling, `color`, in example Python code throughout the lesson. You will encounter a similar approach with "centre" and `center`. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -341,8 +234,7 @@ fig, ax = plt.subplots() ax.imshow(gray_chair, cmap="gray") ``` -We can also load colour images as grayscale directly by -passing the argument `mode="L"` to `iio.imread()`. +We can also load colour images as grayscale directly by passing the argument `mode="L"` to `iio.imread()`. ```python """Python script to load a color image as grayscale.""" @@ -355,9 +247,7 @@ fig, ax = plt.subplots() ax.imshow(gray_chair, cmap="gray") ``` -The first argument to `iio.imread()` is the filename of the image. -The second argument `mode="L"` determines the type and range of the pixel values in the image (e.g., an 8-bit pixel has a range of 0-255). This argument is forwarded to the `pillow` backend, a Python imaging library for which mode "L" means 8-bit pixels and single-channel (i.e., grayscale). The backend used by `iio.imread()` may be specified as an optional argument: to use `pillow`, you would -pass `plugin="pillow"`. If the backend is not specified explicitly, `iio.imread()` determines the backend to use based on the image type. +The first argument to `iio.imread()` is the filename of the image. The second argument `mode="L"` determines the type and range of the pixel values in the image (e.g., an 8-bit pixel has a range of 0-255). This argument is forwarded to the `pillow` backend, a Python imaging library for which mode "L" means 8-bit pixels and single-channel (i.e., grayscale). The backend used by `iio.imread()` may be specified as an optional argument: to use `pillow`, you would pass `plugin="pillow"`. If the backend is not specified explicitly, `iio.imread()` determines the backend to use based on the image type. ::::::::::::::::::::::::::::::::::::::::: callout @@ -371,37 +261,23 @@ When loading an image with `mode="L"`, the pixel values are stored as 8-bit inte ## Keeping only low intensity pixels (10 min) -A little earlier, we showed how we could use Python and scikit-image to turn -on only the high intensity pixels from an image, while turning all the low -intensity pixels off. -Now, you can practice doing the opposite - keeping all -the low intensity pixels while changing the high intensity ones. +A little earlier, we showed how we could use Python and scikit-image to turn on only the high intensity pixels from an image, while turning all the low intensity pixels off. Now, you can practice doing the opposite - keeping all the low intensity pixels while changing the high intensity ones. The file `data/sudoku.png` is an RGB image of a sudoku puzzle: ![](fig/sudoku.png){alt='Su-Do-Ku puzzle'} -Your task is to load the image in grayscale format and turn all of -the bright pixels in the image to a -light gray colour. In other words, mask the bright pixels that have -a pixel value greater than, say, 192 and set their value to 192 (the -value 192 is chosen here because it corresponds to 75% of the -range 0-255 of an 8-bit pixel). The results should look like this: +Your task is to load the image in grayscale format and turn all of the bright pixels in the image to a light gray colour. In other words, mask the bright pixels that have a pixel value greater than, say, 192 and set their value to 192 (the value 192 is chosen here because it corresponds to 75% of the range 0-255 of an 8-bit pixel). The results should look like this: ![](fig/sudoku-gray.png){alt='Modified Su-Do-Ku puzzle'} -*Hint: the `cmap`, `vmin`, and `vmax` parameters of `matplotlib.pyplot.imshow` -will be needed to display the modified image as desired. See the [Matplotlib -documentation](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.imshow.html) -for more details on `cmap`, `vmin`, and `vmax`.* +*Hint: the `cmap`, `vmin`, and `vmax` parameters of `matplotlib.pyplot.imshow` will be needed to display the modified image as desired. See the [Matplotlib documentation](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.imshow.html) for more details on `cmap`, `vmin`, and `vmax`.* ::::::::::::::: solution ## Solution -First, load the image file `data/sudoku.png` as a grayscale image. -Note we may want to create a copy of the image array to avoid modifying our original variable and -also because `imageio.v3.imread` sometimes returns a non-writeable image. +First, load the image file `data/sudoku.png` as a grayscale image. Note we may want to create a copy of the image array to avoid modifying our original variable and also because `imageio.v3.imread` sometimes returns a non-writeable image. ```python sudoku = iio.imread(uri="data/sudoku.png", mode="L") @@ -430,66 +306,31 @@ ax[1].imshow(sudoku_gray_background, cmap="gray", vmin=0, vmax=255) ## Plotting single channel images (cmap, vmin, vmax) -Compared to a colour image, a grayscale image contains only a single -intensity value per pixel. When we plot such an image with `ax.imshow`, -Matplotlib uses a colour map, to assign each intensity value a colour. -The default colour map is called "viridis" and maps low values to purple -and high values to yellow. We can instruct Matplotlib to map low values -to black and high values to white instead, by calling `ax.imshow` with -`cmap="gray"`. -[The documentation contains an overview of pre-defined colour maps](https://matplotlib.org/stable/gallery/color/colormap_reference.html). - -Furthermore, Matplotlib determines the minimum and maximum values of -the colour map dynamically from the image, by default. That means that in -an image where the minimum is 64 and the maximum is 192, those values -will be mapped to black and white respectively (and not dark gray and light -gray as you might expect). If there are defined minimum and maximum vales, -you can specify them via `vmin` and `vmax` to get the desired output. - -If you forget about this, it can lead to unexpected results. Try removing -the `vmax` parameter from the sudoku challenge solution and see what happens. +Compared to a colour image, a grayscale image contains only a single intensity value per pixel. When we plot such an image with `ax.imshow`, Matplotlib uses a colour map, to assign each intensity value a colour. The default colour map is called "viridis" and maps low values to purple and high values to yellow. We can instruct Matplotlib to map low values to black and high values to white instead, by calling `ax.imshow` with `cmap="gray"`. [The documentation contains an overview of pre-defined colour maps](https://matplotlib.org/stable/gallery/color/colormap_reference.html). + +Furthermore, Matplotlib determines the minimum and maximum values of the colour map dynamically from the image, by default. That means that in an image where the minimum is 64 and the maximum is 192, those values will be mapped to black and white respectively (and not dark gray and light gray as you might expect). If there are defined minimum and maximum vales, you can specify them via `vmin` and `vmax` to get the desired output. + +If you forget about this, it can lead to unexpected results. Try removing the `vmax` parameter from the sudoku challenge solution and see what happens. :::::::::::::::::::::::::::::::::::::::::::::::::: ## Access via slicing -As noted in the previous lesson scikit-image images are stored as NumPy arrays, -so we can use array slicing to select rectangular areas of an image. -Then, we can save the selection as a new image, change the pixels in the image, -and so on. -It is important to -remember that coordinates are specified in *(ry, cx)* order and that colour values -are specified in *(r, g, b)* order when doing these manipulations. +As noted in the previous lesson scikit-image images are stored as NumPy arrays, so we can use array slicing to select rectangular areas of an image. Then, we can save the selection as a new image, change the pixels in the image, and so on. It is important to remember that coordinates are specified in *(ry, cx)* order and that colour values are specified in *(r, g, b)* order when doing these manipulations. -Consider this image of a whiteboard, and suppose that we want to create a -sub-image with just the portion that says "odd + even = odd," along with the -red box that is drawn around the words. +Consider this image of a whiteboard, and suppose that we want to create a sub-image with just the portion that says "odd + even = odd," along with the red box that is drawn around the words. ![](fig/board.jpg){alt='Whiteboard image'} -Using `matplotlib.pyplot.imshow` -we can determine the coordinates of the corners of the area we wish to extract -by hovering the mouse near the points of interest and noting the coordinates -(remember to run `%matplotlib widget` first if you haven't already). -If we do that, we might settle on a rectangular -area with an upper-left coordinate of *(135, 60)* -and a lower-right coordinate of *(480, 150)*, -as shown in this version of the whiteboard picture: +Using `matplotlib.pyplot.imshow` we can determine the coordinates of the corners of the area we wish to extract by hovering the mouse near the points of interest and noting the coordinates (remember to run `%matplotlib widget` first if you haven't already). If we do that, we might settle on a rectangular area with an upper-left coordinate of *(135, 60)* and a lower-right coordinate of *(480, 150)*, as shown in this version of the whiteboard picture: ![](fig/board-coordinates.jpg){alt='Whiteboard coordinates'} -Note that the coordinates in the preceding image are specified in *(cx, ry)* order. -Now if our entire whiteboard image is stored as a NumPy array named `image`, -we can create a new image of the selected region with a statement like this: +Note that the coordinates in the preceding image are specified in *(cx, ry)* order. Now if our entire whiteboard image is stored as a NumPy array named `image`, we can create a new image of the selected region with a statement like this: `clip = image[60:151, 135:481, :]` -Our array slicing specifies the range of y-coordinates or rows first, `60:151`, -and then the range of x-coordinates or columns, `135:481`. -Note we go one beyond the maximum value in each dimension, -so that the entire desired area is selected. -The third part of the slice, `:`, -indicates that we want all three colour channels in our new image. +Our array slicing specifies the range of y-coordinates or rows first, `60:151`, and then the range of x-coordinates or columns, `135:481`. Note we go one beyond the maximum value in each dimension, so that the entire desired area is selected. The third part of the slice, `:`, indicates that we want all three colour channels in our new image. A script to create the subimage would start by loading the image: @@ -503,8 +344,7 @@ fig, ax = plt.subplots() ax.imshow(board) ``` -Then we use array slicing to -create a new image with our selected area and then display the new image. +Then we use array slicing to create a new image with our selected area and then display the new image. ```python # extract, display, and save sub-image @@ -524,18 +364,7 @@ fig, ax = plt.subplots() ax.imshow(board) ``` -First, we sample a single pixel's colour at a particular location of the -image, saving it in a variable named `color`, -which creates a 1 × 1 × 3 NumPy array with the blue, green, and red colour values -for the pixel located at *(ry = 330, cx = 90)*. -Then, with the `img[60:151, 135:481] = color` command, -we modify the image in the specified area. -From a NumPy perspective, -this changes all the pixel values within that range to array saved in -the `color` variable. -In this case, the command "erases" that area of the whiteboard, -replacing the words with a beige colour, -as shown in the final image produced by the program: +First, we sample a single pixel's colour at a particular location of the image, saving it in a variable named `color`, which creates a 1 × 1 × 3 NumPy array with the blue, green, and red colour values for the pixel located at *(ry = 330, cx = 90)*. Then, with the `img[60:151, 135:481] = color` command, we modify the image in the specified area. From a NumPy perspective, this changes all the pixel values within that range to array saved in the `color` variable. In this case, the command "erases" that area of the whiteboard, replacing the words with a beige colour, as shown in the final image produced by the program: ![](fig/board-final.jpg){alt='"Erased" whiteboard'} @@ -543,16 +372,13 @@ as shown in the final image produced by the program: ## Practicing with slices (10 min - optional, not included in timing) -Using the techniques you just learned, write a script that -creates, displays, and saves a sub-image containing -only the plant and its roots from "data/maize-root-cluster.jpg" +Using the techniques you just learned, write a script that creates, displays, and saves a sub-image containing only the plant and its roots from "data/maize-root-cluster.jpg" ::::::::::::::: solution ## Solution -Here is the completed Python program to select only the plant and roots -in the image. +Here is the completed Python program to select only the plant and roots in the image. ```python """Python script to extract a sub-image containing only the plant and roots in an existing image.""" diff --git a/episodes/04-drawing.md b/episodes/04-drawing.md index ae1c444..e84dec3 100644 --- a/episodes/04-drawing.md +++ b/episodes/04-drawing.md @@ -19,10 +19,7 @@ exercises: 45 :::::::::::::::::::::::::::::::::::::::::::::::::: -The next series of episodes covers a basic toolkit of scikit-image operators. -With these tools, -we will be able to create programs to perform simple analyses of images -based on changes in colour or shape. +The next series of episodes covers a basic toolkit of scikit-image operators. With these tools, we will be able to create programs to perform simple analyses of images based on changes in colour or shape. ## First, import the packages needed for this episode @@ -40,37 +37,15 @@ Here, we import the same packages as earlier in the lesson. ## Drawing on images -Often we wish to select only a portion of an image to analyze, -and ignore the rest. -Creating a rectangular sub-image with slicing, -as we did in [the *Working with scikit-image* episode](03-skimage-images.md) -is one option for simple cases. -Another option is to create another special image, -of the same size as the original, -with white pixels indicating the region to save and black pixels everywhere else. -Such an image is called a *mask*. -In preparing a mask, we sometimes need to be able to draw a shape - -a circle or a rectangle, say - -on a black image. -scikit-image provides tools to do that. +Often we wish to select only a portion of an image to analyze, and ignore the rest. Creating a rectangular sub-image with slicing, as we did in [the *Working with scikit-image* episode](03-skimage-images.md) is one option for simple cases. Another option is to create another special image, of the same size as the original, with white pixels indicating the region to save and black pixels everywhere else. Such an image is called a *mask*. In preparing a mask, we sometimes need to be able to draw a shape - a circle or a rectangle, say - on a black image. scikit-image provides tools to do that. Consider this image of maize seedlings: ![](fig/maize-seedlings.jpg){alt='Maize seedlings'} -Now, suppose we want to analyze only the area of the image containing the roots -themselves; -we do not care to look at the kernels, -or anything else about the plants. -Further, we wish to exclude the frame of the container holding the seedlings as well. -Hovering over the image with our mouse, could tell us that -the upper-left coordinate of the sub-area we are interested in is *(44, 357)*, -while the lower-right coordinate is *(720, 740)*. -These coordinates are shown in *(x, y)* order. +Now, suppose we want to analyze only the area of the image containing the roots themselves; we do not care to look at the kernels, or anything else about the plants. Further, we wish to exclude the frame of the container holding the seedlings as well. Hovering over the image with our mouse, could tell us that the upper-left coordinate of the sub-area we are interested in is *(44, 357)*, while the lower-right coordinate is *(720, 740)*. These coordinates are shown in *(x, y)* order. -A Python program to create a mask to select only that area of the image would -start with a now-familiar section of code to open and display the original -image: +A Python program to create a mask to select only that area of the image would start with a now-familiar section of code to open and display the original image: ```python # Load and display the original image @@ -82,31 +57,14 @@ ax.imshow(maize_seedlings) We load and display the initial image in the same way we have done before. -NumPy allows indexing of images/arrays with "boolean" arrays of the same size. -Indexing with a boolean array is also called mask indexing. -The "pixels" in such a mask array can only take two values: `True` or `False`. -When indexing an image with such a mask, -only pixel values at positions where the mask is `True` are accessed. -But first, we need to generate a mask array of the same size as the image. -Luckily, the NumPy library provides a function to create just such an array. -The next section of code shows how: +NumPy allows indexing of images/arrays with "boolean" arrays of the same size. Indexing with a boolean array is also called mask indexing. The "pixels" in such a mask array can only take two values: `True` or `False`. When indexing an image with such a mask, only pixel values at positions where the mask is `True` are accessed. But first, we need to generate a mask array of the same size as the image. Luckily, the NumPy library provides a function to create just such an array. The next section of code shows how: ```python # Create the basic mask mask = np.ones(shape=maize_seedlings.shape[0:2], dtype="bool") ``` -The first argument to the `ones()` function is the shape of the original image, -so that our mask will be exactly the same size as the original. -Notice, that we have only used the first two indices of our shape. -We omitted the channel dimension. -Indexing with such a mask will change all channel values simultaneously. -The second argument, `dtype = "bool"`, -indicates that the elements in the array should be booleans - -i.e., values are either `True` or `False`. -Thus, even though we use `np.ones()` to create the mask, -its pixel values are in fact not `1` but `True`. -You could check this, e.g., by `print(mask[0, 0])`. +The first argument to the `ones()` function is the shape of the original image, so that our mask will be exactly the same size as the original. Notice, that we have only used the first two indices of our shape. We omitted the channel dimension. Indexing with such a mask will change all channel values simultaneously. The second argument, `dtype = "bool"`, indicates that the elements in the array should be booleans - i.e., values are either `True` or `False`. Thus, even though we use `np.ones()` to create the mask, its pixel values are in fact not `1` but `True`. You could check this, e.g., by `print(mask[0, 0])`. Next, we draw a filled, rectangle on the mask: @@ -120,28 +78,15 @@ fig, ax = plt.subplots() ax.imshow(mask, cmap="gray") ``` -Here is what our constructed mask looks like: -![](fig/maize-seedlings-mask.png){alt='Maize image mask' .image-with-shadow} +Here is what our constructed mask looks like: ![](fig/maize-seedlings-mask.png){alt='Maize image mask' .image-with-shadow} -The parameters of the `rectangle()` function `(357, 44)` and `(740, 720)`, -are the coordinates of the upper-left (`start`) and lower-right (`end`) corners -of a rectangle in *(ry, cx)* order. -The function returns the rectangle as row (`rr`) and column (`cc`) coordinate arrays. +The parameters of the `rectangle()` function `(357, 44)` and `(740, 720)`, are the coordinates of the upper-left (`start`) and lower-right (`end`) corners of a rectangle in *(ry, cx)* order. The function returns the rectangle as row (`rr`) and column (`cc`) coordinate arrays. ::::::::::::::::::::::::::::::::::::::::: callout ## Check the documentation! -When using an scikit-image function for the first time - or the fifth time - -it is wise to check how the function is used, via -[the scikit-image documentation](https://scikit-image.org/docs/dev/user_guide) -or other usage examples on programming-related sites such as -[Stack Overflow](https://stackoverflow.com/). -Basic information about scikit-image functions can be found interactively in Python, -via commands like `help(ski)` or `help(ski.draw.rectangle)`. -Take notes in your lab notebook. -And, it is always wise to run some test code to verify -that the functions your program uses are behaving in the manner you intend. +When using an scikit-image function for the first time - or the fifth time - it is wise to check how the function is used, via [the scikit-image documentation](https://scikit-image.org/docs/dev/user_guide) or other usage examples on programming-related sites such as [Stack Overflow](https://stackoverflow.com/). Basic information about scikit-image functions can be found interactively in Python, via commands like `help(ski)` or `help(ski.draw.rectangle)`. Take notes in your lab notebook. And, it is always wise to run some test code to verify that the functions your program uses are behaving in the manner you intend. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -150,16 +95,7 @@ that the functions your program uses are behaving in the manner you intend. ## Variable naming conventions! -You may have wondered why we called the return values of the rectangle function -`rr` and `cc`?! -You may have guessed that `r` is short for `row` and `c` is short for `column`. -However, the rectangle function returns mutiple rows and columns; -thus we used a convention of doubling the letter `r` to `rr` (and `c` to `cc`) -to indicate that those are multiple values. -In fact it may have even been clearer to name those variables `rows` and `columns`; -however this would have been also much longer. -Whatever you decide to do, try to stick to some already existing conventions, -such that it is easier for other people to understand your code. +You may have wondered why we called the return values of the rectangle function `rr` and `cc`?! You may have guessed that `r` is short for `row` and `c` is short for `column`. However, the rectangle function returns mutiple rows and columns; thus we used a convention of doubling the letter `r` to `rr` (and `c` to `cc`) to indicate that those are multiple values. In fact it may have even been clearer to name those variables `rows` and `columns`; however this would have been also much longer. Whatever you decide to do, try to stick to some already existing conventions, such that it is easier for other people to understand your code. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -168,41 +104,22 @@ such that it is easier for other people to understand your code. ## Other drawing operations (15 min) -There are other functions for drawing on images, -in addition to the `ski.draw.rectangle()` function. -We can draw circles, lines, text, and other shapes as well. -These drawing functions may be useful later on, to help annotate images -that our programs produce. -Practice some of these functions here. - -Circles can be drawn with the `ski.draw.disk()` function, -which takes two parameters: -the (ry, cx) point of the centre of the circle, -and the radius of the circle. -There is an optional `shape` parameter that can be supplied to this function. -It will limit the output coordinates for cases where the circle -dimensions exceed the ones of the image. - -Lines can be drawn with the `ski.draw.line()` function, -which takes four parameters: -the (ry, cx) coordinate of one end of the line, -and the (ry, cx) coordinate of the other end of the line. - -Other drawing functions supported by scikit-image can be found in -[the scikit-image reference pages](https://scikit-image.org/docs/dev/api/skimage.draw.html?highlight=draw#module-skimage.draw). - -First let's make an empty, black image with a size of 800x600 pixels. -Recall that a colour image has three channels for the colours red, green, and blue -(RGB, cf. [Image Basics](03-skimage-images.md)). -Hence we need to create a 3D array of shape `(600, 800, 3)` where the last dimension represents the RGB colour channels. +There are other functions for drawing on images, in addition to the `ski.draw.rectangle()` function. We can draw circles, lines, text, and other shapes as well. These drawing functions may be useful later on, to help annotate images that our programs produce. Practice some of these functions here. + +Circles can be drawn with the `ski.draw.disk()` function, which takes two parameters: the (ry, cx) point of the centre of the circle, and the radius of the circle. There is an optional `shape` parameter that can be supplied to this function. It will limit the output coordinates for cases where the circle dimensions exceed the ones of the image. + +Lines can be drawn with the `ski.draw.line()` function, which takes four parameters: the (ry, cx) coordinate of one end of the line, and the (ry, cx) coordinate of the other end of the line. + +Other drawing functions supported by scikit-image can be found in [the scikit-image reference pages](https://scikit-image.org/docs/dev/api/skimage.draw.html?highlight=draw#module-skimage.draw). + +First let's make an empty, black image with a size of 800x600 pixels. Recall that a colour image has three channels for the colours red, green, and blue (RGB, cf. [Image Basics](03-skimage-images.md)). Hence we need to create a 3D array of shape `(600, 800, 3)` where the last dimension represents the RGB colour channels. ```python # create the black canvas canvas = np.zeros(shape=(600, 800, 3), dtype="uint8") ``` -Now your task is to draw some other coloured shapes and lines on the image, -perhaps something like this: +Now your task is to draw some other coloured shapes and lines on the image, perhaps something like this: ![](fig/drawing-practice.jpg){alt='Sample shapes'} @@ -232,11 +149,7 @@ fig, ax = plt.subplots() ax.imshow(canvas) ``` -We could expand this solution, if we wanted, -to draw rectangles, circles and lines at random positions within our black canvas. -To do this, we could use the `random` python module, -and the function `random.randrange`, -which can produce random numbers within a certain range. +We could expand this solution, if we wanted, to draw rectangles, circles and lines at random positions within our black canvas. To do this, we could use the `random` python module, and the function `random.randrange`, which can produce random numbers within a certain range. Let's draw 15 randomly placed circles: @@ -261,11 +174,7 @@ fig, ax = plt.subplots() ax.imshow(canvas) ``` -We could expand this even further to also -randomly choose whether to plot a rectangle, a circle, or a square. -Again, we do this with the `random` module, -now using the function `random.random` -that returns a random number between 0.0 and 1.0. +We could expand this even further to also randomly choose whether to plot a rectangle, a circle, or a square. Again, we do this with the `random` module, now using the function `random.random` that returns a random number between 0.0 and 1.0. ```python import random @@ -315,19 +224,13 @@ ax.imshow(canvas) ## Image modification -All that remains is the task of modifying the image using our mask in such a -way that the areas with `True` pixels in the mask are not shown in the image -any more. +All that remains is the task of modifying the image using our mask in such a way that the areas with `True` pixels in the mask are not shown in the image any more. ::::::::::::::::::::::::::::::::::::::: challenge ## How does a mask work? (optional, not included in timing) -Now, consider the mask image we created above. -The values of the mask that corresponds to the portion of the image -we are interested in are all `False`, -while the values of the mask that corresponds to the portion of the image we -want to remove are all `True`. +Now, consider the mask image we created above. The values of the mask that corresponds to the portion of the image we are interested in are all `False`, while the values of the mask that corresponds to the portion of the image we want to remove are all `True`. How do we change the original image using the mask? @@ -335,10 +238,7 @@ How do we change the original image using the mask? ## Solution -When indexing the image using the mask, we access only those pixels at -positions where the mask is `True`. -So, when indexing with the mask, -one can set those values to 0, and effectively remove them from the image. +When indexing the image using the mask, we access only those pixels at positions where the mask is `True`. So, when indexing with the mask, one can set those values to 0, and effectively remove them from the image. @@ -346,9 +246,7 @@ one can set those values to 0, and effectively remove them from the image. :::::::::::::::::::::::::::::::::::::::::::::::::: -Now we can write a Python program to use a mask to retain only the portions -of our maize roots image that actually contains the seedling roots. -We load the original image and create the mask in the same way as before: +Now we can write a Python program to use a mask to retain only the portions of our maize roots image that actually contains the seedling roots. We load the original image and create the mask in the same way as before: ```python # Load the original image @@ -362,8 +260,7 @@ rr, cc = ski.draw.rectangle(start=(357, 44), end=(740, 720)) mask[rr, cc] = False ``` -Then, we use NumPy indexing to remove the portions of the image, -where the mask is `True`: +Then, we use NumPy indexing to remove the portions of the image, where the mask is `True`: ```python # Apply the mask @@ -385,13 +282,7 @@ The resulting masked image should look like this: ## Masking an image of your own (optional, not included in timing) -Now, it is your turn to practice. -Using your mobile phone, tablet, webcam, or digital camera, -take an image of an object with a simple overall geometric shape -(think rectangular or circular). -Copy that image to your computer, write some code to make a mask, -and apply it to select the part of the image containing your object. -For example, here is an image of a remote control: +Now, it is your turn to practice. Using your mobile phone, tablet, webcam, or digital camera, take an image of an object with a simple overall geometric shape (think rectangular or circular). Copy that image to your computer, write some code to make a mask, and apply it to select the part of the image containing your object. For example, here is an image of a remote control: ![](fig/remote-control.jpg){alt='Remote control image'} @@ -403,8 +294,7 @@ And, here is the end result of a program masking out everything but the remote: ## Solution -Here is a Python program to produce the cropped remote control image shown above. -Of course, your program should be tailored to your image. +Here is a Python program to produce the cropped remote control image shown above. Of course, your program should be tailored to your image. ```python # Load the image @@ -448,15 +338,9 @@ ax.imshow(wellplate) ![](fig/wellplate-01.jpg){alt='96-well plate'} -Suppose that we are interested in the colours of the solutions in each of the wells. -We *do not* care about the colour of the rest of the image, -i.e., the plastic that makes up the well plate itself. +Suppose that we are interested in the colours of the solutions in each of the wells. We *do not* care about the colour of the rest of the image, i.e., the plastic that makes up the well plate itself. -Your task is to write some code that will produce a mask that will -mask out everything except for the wells. -To help with this, you should use the text file `data/centers.txt` that contains -the (cx, ry) coordinates of the centre of each of the 96 wells in this image. -You may assume that each of the wells has a radius of 16 pixels. +Your task is to write some code that will produce a mask that will mask out everything except for the wells. To help with this, you should use the text file `data/centers.txt` that contains the (cx, ry) coordinates of the centre of each of the 96 wells in this image. You may assume that each of the wells has a radius of 16 pixels. Your program should produce output that looks like this: @@ -506,30 +390,13 @@ ax.imshow(wellplate) ## Masking a 96-well plate image, take two (optional, not included in timing) -If you spent some time looking at the contents of -the `data/centers.txt` file from the previous challenge, -you may have noticed that the centres of each well in the image are very regular. -*Assuming* that the images are scanned in such a way that -the wells are always in the same place, -and that the image is perfectly oriented -(i.e., it does not slant one way or another), -we could produce our well plate mask without having to -read in the coordinates of the centres of each well. -Assume that the centre of the upper left well in the image is at -location cx = 91 and ry = 108, and that there are -70 pixels between each centre in the cx dimension and -72 pixels between each centre in the ry dimension. -Each well still has a radius of 16 pixels. -Write a Python program that produces the same output image as in the previous challenge, -but *without* having to read in the `centers.txt` file. -*Hint: use nested for loops.* +If you spent some time looking at the contents of the `data/centers.txt` file from the previous challenge, you may have noticed that the centres of each well in the image are very regular. *Assuming* that the images are scanned in such a way that the wells are always in the same place, and that the image is perfectly oriented (i.e., it does not slant one way or another), we could produce our well plate mask without having to read in the coordinates of the centres of each well. Assume that the centre of the upper left well in the image is at location cx = 91 and ry = 108, and that there are 70 pixels between each centre in the cx dimension and 72 pixels between each centre in the ry dimension. Each well still has a radius of 16 pixels. Write a Python program that produces the same output image as in the previous challenge, but *without* having to read in the `centers.txt` file. *Hint: use nested for loops.* ::::::::::::::: solution ## Solution -Here is a Python program that is able to create the masked image without -having to read in the `centers.txt` file. +Here is a Python program that is able to create the masked image without having to read in the `centers.txt` file. ```python # read in original image diff --git a/episodes/05-preprocessing.md b/episodes/05-preprocessing.md index cdea1e9..63abb3d 100644 --- a/episodes/05-preprocessing.md +++ b/episodes/05-preprocessing.md @@ -8,7 +8,6 @@ exercises: 50 - Apply histogram normalization and equalization to facilitate downstream image segmentation - Choose when normalization and equalization is appropriate (batch normalization of intensities) - - Explain the concept of a filter and its effects on the image data (theoretical explanation of kernels) - Define the concept of noise and background in images - Apply techniques like gaussian, mean or median filtering to remove noise from an image diff --git a/episodes/06-blurring.md b/episodes/06-blurring.md index 6aec081..fd8f367 100644 --- a/episodes/06-blurring.md +++ b/episodes/06-blurring.md @@ -19,44 +19,15 @@ exercises: 25 In this episode, we will learn how to use scikit-image functions to blur images. -When processing an image, we are often interested in identifying objects -represented within it so that we can perform some further analysis of these -objects, e.g., by counting them, measuring their sizes, etc. -An important concept associated with the identification of objects in an image -is that of *edges*: the lines that represent a transition from one group of -similar pixels in the image to another different group. -One example of an edge is the pixels that represent -the boundaries of an object in an image, -where the background of the image ends and the object begins. - -When we blur an image, -we make the colour transition from one side of an edge in the image to another -smooth rather than sudden. -The effect is to average out rapid changes in pixel intensity. -Blurring is a very common operation we need to perform before other tasks such as -[thresholding](07-thresholding.md). -There are several different blurring functions in the `ski.filters` module, -so we will focus on just one here, the *Gaussian blur*. +When processing an image, we are often interested in identifying objects represented within it so that we can perform some further analysis of these objects, e.g., by counting them, measuring their sizes, etc. An important concept associated with the identification of objects in an image is that of *edges*: the lines that represent a transition from one group of similar pixels in the image to another different group. One example of an edge is the pixels that represent the boundaries of an object in an image, where the background of the image ends and the object begins. + +When we blur an image, we make the colour transition from one side of an edge in the image to another smooth rather than sudden. The effect is to average out rapid changes in pixel intensity. Blurring is a very common operation we need to perform before other tasks such as [thresholding](07-thresholding.md). There are several different blurring functions in the `ski.filters` module, so we will focus on just one here, the *Gaussian blur*. ::::::::::::::::::::::::::::::::::::::::: callout ## Filters -In the day-to-day, macroscopic world, -we have physical filters which separate out objects by size. -A filter with small holes allows only small objects through, -leaving larger objects behind. -This is a good analogy for image filters. -A high-pass filter will retain the smaller details in an image, -filtering out the larger ones. -A low-pass filter retains the larger features, -analogous to what's left behind by a physical filter mesh. -*High-* and *low*-pass, here, -refer to high and low *spatial frequencies* in the image. -Details associated with high spatial frequencies are small, -a lot of these features would fit across an image. -Features associated with low spatial frequencies are large - -maybe a couple of big features per image. +In the day-to-day, macroscopic world, we have physical filters which separate out objects by size. A filter with small holes allows only small objects through, leaving larger objects behind. This is a good analogy for image filters. A high-pass filter will retain the smaller details in an image, filtering out the larger ones. A low-pass filter retains the larger features, analogous to what's left behind by a physical filter mesh. *High-* and *low*-pass, here, refer to high and low *spatial frequencies* in the image. Details associated with high spatial frequencies are small, a lot of these features would fit across an image. Features associated with low spatial frequencies are large - maybe a couple of big features per image. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -64,12 +35,7 @@ maybe a couple of big features per image. ## Blurring -To blur is to make something less clear or distinct. -This could be interpreted quite broadly in the context of image analysis - -anything that reduces or distorts the detail of an image might apply. -Applying a low-pass filter, which removes detail occurring at high spatial frequencies, -is perceived as a blurring effect. -A Gaussian blur is a filter that makes use of a Gaussian kernel. +To blur is to make something less clear or distinct. This could be interpreted quite broadly in the context of image analysis - anything that reduces or distorts the detail of an image might apply. Applying a low-pass filter, which removes detail occurring at high spatial frequencies, is perceived as a blurring effect. A Gaussian blur is a filter that makes use of a Gaussian kernel. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -77,50 +43,26 @@ A Gaussian blur is a filter that makes use of a Gaussian kernel. ## Kernels -A kernel can be used to implement a filter on an image. -A kernel, in this context, -is a small matrix which is combined with the image using -a mathematical technique: *convolution*. -Different sizes, shapes and contents of kernel produce different effects. -The kernel can be thought of as a little image in itself, -and will favour features of similar size and shape in the main image. -On convolution with an image, a big, blobby kernel will retain -big, blobby, low spatial frequency features. +A kernel can be used to implement a filter on an image. A kernel, in this context, is a small matrix which is combined with the image using a mathematical technique: *convolution*. Different sizes, shapes and contents of kernel produce different effects. The kernel can be thought of as a little image in itself, and will favour features of similar size and shape in the main image. On convolution with an image, a big, blobby kernel will retain big, blobby, low spatial frequency features. :::::::::::::::::::::::::::::::::::::::::::::::::: ## Gaussian blur -Consider this image of a cat, -in particular the area of the image outlined by the white square. +Consider this image of a cat, in particular the area of the image outlined by the white square. ![](fig/cat.jpg){alt='Cat image'} -Now, zoom in on the area of the cat's eye, as shown in the left-hand image below. -When we apply a filter, we consider each pixel in the image, one at a time. -In this example, the pixel we are currently working on is highlighted in red, -as shown in the right-hand image. +Now, zoom in on the area of the cat's eye, as shown in the left-hand image below. When we apply a filter, we consider each pixel in the image, one at a time. In this example, the pixel we are currently working on is highlighted in red, as shown in the right-hand image. ![](fig/cat-eye-pixels.jpg){alt='Cat eye pixels'} -When we apply a filter, we consider rectangular groups of pixels surrounding -each pixel in the image, in turn. -The *kernel* is another group of pixels (a separate matrix / small image), -of the same dimensions as the rectangular group of pixels in the image, -that moves along with the pixel being worked on by the filter. -The width and height of the kernel must be an odd number, -so that the pixel being worked on is always in its centre. -In the example shown above, the kernel is square, with a dimension of seven pixels. - -To apply the kernel to the current pixel, -an average of the colour values of the pixels surrounding it is calculated, -weighted by the values in the kernel. -In a Gaussian blur, the pixels nearest the centre of the kernel are -given more weight than those far away from the centre. -The rate at which this weight diminishes is determined by a Gaussian function, hence the name -Gaussian blur. +When we apply a filter, we consider rectangular groups of pixels surrounding each pixel in the image, in turn. The *kernel* is another group of pixels (a separate matrix / small image), of the same dimensions as the rectangular group of pixels in the image, that moves along with the pixel being worked on by the filter. The width and height of the kernel must be an odd number, so that the pixel being worked on is always in its centre. In the example shown above, the kernel is square, with a dimension of seven pixels. + +To apply the kernel to the current pixel, an average of the colour values of the pixels surrounding it is calculated, weighted by the values in the kernel. In a Gaussian blur, the pixels nearest the centre of the kernel are given more weight than those far away from the centre. The rate at which this weight diminishes is determined by a Gaussian function, hence the name Gaussian blur. A Gaussian function maps random variables into a normal distribution or "Bell Curve". + ![](fig/Normal_Distribution_PDF.svg){alt='Gaussian function'} | *[https://en.wikipedia.org/wiki/Gaussian\_function#/media/File:Normal\_Distribution\_PDF.svg](https://en.wikipedia.org/wiki/Gaussian_function#/media/File:Normal_Distribution_PDF.svg)* | @@ -133,56 +75,29 @@ In fact, when using Gaussian functions in Gaussian blurring, we use a 2D Gaussia | *[https://commons.wikimedia.org/wiki/File:Gaussian\_2D.png](https://commons.wikimedia.org/wiki/File:Gaussian_2D.png)* | -The averaging is done on a channel-by-channel basis, -and the average channel values become the new value for the pixel in -the filtered image. -Larger kernels have more values factored into the average, and this implies -that a larger kernel will blur the image more than a smaller kernel. +The averaging is done on a channel-by-channel basis, and the average channel values become the new value for the pixel in the filtered image. Larger kernels have more values factored into the average, and this implies that a larger kernel will blur the image more than a smaller kernel. -To get an idea of how this works, -consider this plot of the two-dimensional Gaussian function: +To get an idea of how this works, consider this plot of the two-dimensional Gaussian function: ![](fig/gaussian-kernel.png){alt='2D Gaussian function'} -Imagine that plot laid over the kernel for the Gaussian blur filter. -The height of the plot corresponds to the weight given to the underlying pixel -in the kernel. -I.e., the pixels close to the centre become more important to -the filtered pixel colour than the pixels close to the outer limits of the kernel. -The shape of the Gaussian function is controlled via its standard deviation, -or sigma. -A large sigma value results in a flatter shape, -while a smaller sigma value results in a more pronounced peak. -The mathematics involved in the Gaussian blur filter are not quite that simple, -but this explanation gives you the basic idea. - -To illustrate the blurring process, -consider the blue channel colour values from the seven-by-seven region -of the cat image above: +Imagine that plot laid over the kernel for the Gaussian blur filter. The height of the plot corresponds to the weight given to the underlying pixel in the kernel. I.e., the pixels close to the centre become more important to the filtered pixel colour than the pixels close to the outer limits of the kernel. The shape of the Gaussian function is controlled via its standard deviation, or sigma. A large sigma value results in a flatter shape, while a smaller sigma value results in a more pronounced peak. The mathematics involved in the Gaussian blur filter are not quite that simple, but this explanation gives you the basic idea. + +To illustrate the blurring process, consider the blue channel colour values from the seven-by-seven region of the cat image above: ![](fig/cat-corner-blue.png){alt='Image corner pixels'} -The filter is going to determine the new blue channel value for the centre -pixel -- the one that currently has the value 86. The filter calculates a -weighted average of all the blue channel values in the kernel -giving higher weight to the pixels near the centre of the -kernel. +The filter is going to determine the new blue channel value for the centre pixel -- the one that currently has the value 86. The filter calculates a weighted average of all the blue channel values in the kernel giving higher weight to the pixels near the centre of the kernel. ![](fig/combination.png){alt='Image multiplication'} -This weighted average, the sum of the multiplications, -becomes the new value for the centre pixel (3, 3). -The same process would be used to determine the green and red channel values, -and then the kernel would be moved over to apply the filter to the -next pixel in the image. +This weighted average, the sum of the multiplications, becomes the new value for the centre pixel (3, 3). The same process would be used to determine the green and red channel values, and then the kernel would be moved over to apply the filter to the next pixel in the image. :::::::::::::::::::::::::::::::::::::::: instructor ## Terminology about image boundaries -Take care to avoid mixing up the term "edge" to describe the edges of objects -*within* an image and the outer boundaries of the images themselves. -Lack of a clear distinction here may be confusing for learners. +Take care to avoid mixing up the term "edge" to describe the edges of objects *within* an image and the outer boundaries of the images themselves. Lack of a clear distinction here may be confusing for learners. ::::::::::::::::::::::::::::::::::::::::::::::::::: @@ -190,12 +105,7 @@ Lack of a clear distinction here may be confusing for learners. ## Image edges -Something different needs to happen for pixels near the outer limits of the image, -since the kernel for the filter may be partially off the image. -For example, what happens when the filter is applied to -the upper-left pixel of the image? -Here are the blue channel pixel values for the upper-left pixel of the cat image, -again assuming a seven-by-seven kernel: +Something different needs to happen for pixels near the outer limits of the image, since the kernel for the filter may be partially off the image. For example, what happens when the filter is applied to the upper-left pixel of the image? Here are the blue channel pixel values for the upper-left pixel of the cat image, again assuming a seven-by-seven kernel: ```output x x x x x x x @@ -207,15 +117,9 @@ again assuming a seven-by-seven kernel: x x x 5 4 5 3 ``` -The upper-left pixel is the one with value 4. -Since the pixel is at the upper-left corner, -there are no pixels underneath much of the kernel; -here, this is represented by x's. -So, what does the filter do in that situation? +The upper-left pixel is the one with value 4. Since the pixel is at the upper-left corner, there are no pixels underneath much of the kernel; here, this is represented by x's. So, what does the filter do in that situation? -The default mode is to fill in the *nearest* pixel value from the image. -For each of the missing x's the image value closest to the x is used. -If we fill in a few of the missing pixels, you will see how this works: +The default mode is to fill in the *nearest* pixel value from the image. For each of the missing x's the image value closest to the x is used. If we fill in a few of the missing pixels, you will see how this works: ```output x x x 4 x x x @@ -227,9 +131,7 @@ If we fill in a few of the missing pixels, you will see how this works: x x x 5 4 5 3 ``` -Another strategy to fill those missing values is -to *reflect* the pixels that are in the image to fill in for the pixels that -are missing from the kernel. +Another strategy to fill those missing values is to *reflect* the pixels that are in the image to fill in for the pixels that are missing from the kernel. ```output x x x 5 x x x @@ -241,9 +143,7 @@ are missing from the kernel. x x x 5 4 5 3 ``` -A similar process would be used to fill in all of the other missing pixels from -the kernel. Other *border modes* are available; you can learn more about them -in [the scikit-image documentation](https://scikit-image.org/docs/dev/user_guide). +A similar process would be used to fill in all of the other missing pixels from the kernel. Other *border modes* are available; you can learn more about them in [the scikit-image documentation](https://scikit-image.org/docs/dev/user_guide). :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -251,9 +151,7 @@ Let's consider a very simple image to see blurring in action. The animation belo ![](fig/blur-demo.gif){alt='Blur demo animation'} -scikit-image has built-in functions to perform blurring for us, so we do not have to -perform all of these mathematical operations ourselves. Let's work through -an example of blurring an image with the scikit-image Gaussian blur function. +scikit-image has built-in functions to perform blurring for us, so we do not have to perform all of these mathematical operations ourselves. Let's work through an example of blurring an image with the scikit-image Gaussian blur function. First, import the packages needed for this episode: @@ -288,27 +186,9 @@ blurred = ski.filters.gaussian( image, sigma=(sigma, sigma), truncate=3.5, channel_axis=-1) ``` -The first two arguments to `ski.filters.gaussian()` are the image to blur, -`image`, and a tuple defining the sigma to use in ry- and cx-direction, -`(sigma, sigma)`. -The third parameter `truncate` is meant to pass the radius of the kernel in -number of sigmas. -A Gaussian function is defined from -infinity to +infinity, but our kernel -(which must have a finite, smaller size) can only approximate the real function. -Therefore, we must choose a certain distance from the centre of the function -where we stop this approximation, and set the final size of our kernel. -In the above example, we set `truncate` to 3.5, -which means the kernel size will be 2 \* sigma \* 3.5. -For example, for a `sigma` of 1.0 the resulting kernel size would be 7, -while for a `sigma` of 2.0 the kernel size would be 14. -The default value for `truncate` in scikit-image is 4.0. - -The last argument we passed to `ski.filters.gaussian()` is used to -specify the dimension which contains the (colour) channels. -Here, it is the last dimension; -recall that, in Python, the `-1` index refers to the last position. -In this case, the last dimension is the third dimension (index `2`), since our -image has three dimensions: +The first two arguments to `ski.filters.gaussian()` are the image to blur, `image`, and a tuple defining the sigma to use in ry- and cx-direction, `(sigma, sigma)`. The third parameter `truncate` is meant to pass the radius of the kernel in number of sigmas. A Gaussian function is defined from -infinity to +infinity, but our kernel (which must have a finite, smaller size) can only approximate the real function. Therefore, we must choose a certain distance from the centre of the function where we stop this approximation, and set the final size of our kernel. In the above example, we set `truncate` to 3.5, which means the kernel size will be 2 \* sigma \* 3.5. For example, for a `sigma` of 1.0 the resulting kernel size would be 7, while for a `sigma` of 2.0 the kernel size would be 14. The default value for `truncate` in scikit-image is 4.0. + +The last argument we passed to `ski.filters.gaussian()` is used to specify the dimension which contains the (colour) channels. Here, it is the last dimension; recall that, in Python, the `-1` index refers to the last position. In this case, the last dimension is the third dimension (index `2`), since our image has three dimensions: ```python print(image.ndim) @@ -331,21 +211,13 @@ ax.imshow(blurred) ## Visualising Blurring -Somebody said once "an image is worth a thousand words". -What is actually happening to the image pixels when we apply blurring may be -difficult to grasp. Let's now visualise the effects of blurring from a different -perspective. +Somebody said once "an image is worth a thousand words". What is actually happening to the image pixels when we apply blurring may be difficult to grasp. Let's now visualise the effects of blurring from a different perspective. Let's use the petri-dish image from previous episodes: -![ -Graysacle version of the Petri dish image -](fig/petri-dish.png){alt='Bacteria colony'} +![ Graysacle version of the Petri dish image ](fig/petri-dish.png){alt='Bacteria colony'} -What we want to see here is the pixel intensities from a lateral perspective: -we want to see the profile of intensities. -For instance, let's look for the intensities of the pixels along the horizontal -line at `Y=150`: +What we want to see here is the pixel intensities from a lateral perspective: we want to see the profile of intensities. For instance, let's look for the intensities of the pixels along the horizontal line at `Y=150`: ```python # read colonies color image and convert to grayscale @@ -362,11 +234,7 @@ ax.imshow(image_gray, cmap='gray') ax.plot([xmin, xmax], [ymin, ymax], color='red') ``` -![ -Grayscale Petri dish image marking selected pixels for profiling -](fig/petri-selected-pixels-marker.png){ -alt='Bacteria colony image with selected pixels marker' -} +![ Grayscale Petri dish image marking selected pixels for profiling ](fig/petri-selected-pixels-marker.png){ alt='Bacteria colony image with selected pixels marker' } The intensity of those pixels we can see with a simple line plot: @@ -384,11 +252,7 @@ ax.set_ylabel('L') ax.set_xlabel('X') ``` -![ -Intensities profile line plot of pixels along Y=150 in original image -](fig/petri-original-intensities-plot.png){ -alt='Pixel intensities profile in original image' -} +![ Intensities profile line plot of pixels along Y=150 in original image ](fig/petri-original-intensities-plot.png){ alt='Pixel intensities profile in original image' } And now, how does the same set of pixels look in the corresponding *blurred* image: @@ -407,45 +271,24 @@ ax.set_ylabel('L') ax.set_xlabel('X') ``` -![ -Intensities profile of pixels along Y=150 in *blurred* image -](fig/petri-blurred-intensities-plot.png){ -alt='Pixel intensities profile in blurred image' -} +![ Intensities profile of pixels along Y=150 in *blurred* image ](fig/petri-blurred-intensities-plot.png){ alt='Pixel intensities profile in blurred image' } -And that is why *blurring* is also called *smoothing*. -This is how low-pass filters affect neighbouring pixels. +And that is why *blurring* is also called *smoothing*. This is how low-pass filters affect neighbouring pixels. -Now that we have seen the effects of blurring an image from -two different perspectives, front and lateral, let's take -yet another look using a 3D visualisation. +Now that we have seen the effects of blurring an image from two different perspectives, front and lateral, let's take yet another look using a 3D visualisation. :::::::::::::::::::::::::::::::::::::::::: callout ### 3D Plots with matplotlib -The code to generate these 3D plots is outside the scope of this lesson -but can be viewed by following the links in the captions. + +The code to generate these 3D plots is outside the scope of this lesson but can be viewed by following the links in the captions. :::::::::::::::::::::::::::::::::::::::::::::::::: -![ -A 3D plot of pixel intensities across the whole Petri dish image before blurring. -[Explore how this plot was created with matplotlib](https://gist.github.com/chbrandt/63ba38142630a0586ba2a13eabedf94b). -Image credit: [Carlos H Brandt](https://github.com/chbrandt/). -](fig/3D_petri_before_blurring.png){ -alt='3D surface plot showing pixel intensities across the whole example Petri dish image before blurring' -} +![ A 3D plot of pixel intensities across the whole Petri dish image before blurring. [Explore how this plot was created with matplotlib](https://gist.github.com/chbrandt/63ba38142630a0586ba2a13eabedf94b). Image credit: [Carlos H Brandt](https://github.com/chbrandt/). ](fig/3D_petri_before_blurring.png){ alt='3D surface plot showing pixel intensities across the whole example Petri dish image before blurring' } -![ -A 3D plot of pixel intensities after Gaussian blurring of the Petri dish image. -Note the 'smoothing' effect on the pixel intensities of the colonies in the image, -and the 'flattening' of the background noise at relatively low pixel intensities throughout the image. -[Explore how this plot was created with matplotlib](https://gist.github.com/chbrandt/63ba38142630a0586ba2a13eabedf94b). -Image credit: [Carlos H Brandt](https://github.com/chbrandt/). -](fig/3D_petri_after_blurring.png){ -alt='3D surface plot illustrating the smoothing effect on pixel intensities across the whole example Petri dish image after blurring' -} +![ A 3D plot of pixel intensities after Gaussian blurring of the Petri dish image. Note the 'smoothing' effect on the pixel intensities of the colonies in the image, and the 'flattening' of the background noise at relatively low pixel intensities throughout the image. [Explore how this plot was created with matplotlib](https://gist.github.com/chbrandt/63ba38142630a0586ba2a13eabedf94b). Image credit: [Carlos H Brandt](https://github.com/chbrandt/). ](fig/3D_petri_after_blurring.png){ alt='3D surface plot illustrating the smoothing effect on pixel intensities across the whole example Petri dish image after blurring' } @@ -453,27 +296,15 @@ alt='3D surface plot illustrating the smoothing effect on pixel intensities acro ## Experimenting with sigma values (10 min) -The size and shape of the kernel used to blur an image can have a -significant effect on the result of the blurring and any downstream analysis -carried out on the blurred image. -The next two exercises ask you to experiment with the sigma values of the kernel, -which is a good way to develop your understanding of how the choice of kernel -can influence the result of blurring. +The size and shape of the kernel used to blur an image can have a significant effect on the result of the blurring and any downstream analysis carried out on the blurred image. The next two exercises ask you to experiment with the sigma values of the kernel, which is a good way to develop your understanding of how the choice of kernel can influence the result of blurring. -First, try running the code above with a range of smaller and larger sigma values. -Generally speaking, what effect does the sigma value have on the -blurred image? +First, try running the code above with a range of smaller and larger sigma values. Generally speaking, what effect does the sigma value have on the blurred image? ::::::::::::::: solution ## Solution -Generally speaking, the larger the sigma value, the more blurry the result. -A larger sigma will tend to get rid of more noise in the image, which will -help for other operations we will cover soon, such as thresholding. -However, a larger sigma also tends to eliminate some of the detail from -the image. So, we must strike a balance with the sigma value used for -blur filters. +Generally speaking, the larger the sigma value, the more blurry the result. A larger sigma will tend to get rid of more noise in the image, which will help for other operations we will cover soon, such as thresholding. However, a larger sigma also tends to eliminate some of the detail from the image. So, we must strike a balance with the sigma value used for blur filters. @@ -485,9 +316,7 @@ blur filters. ## Experimenting with kernel shape (10 min - optional, not included in timing) -Now, what is the effect of applying an asymmetric kernel to blurring an image? -Try running the code above with different sigmas in the ry and cx direction. -For example, a sigma of 1.0 in the ry direction, and 6.0 in the cx direction. +Now, what is the effect of applying an asymmetric kernel to blurring an image? Try running the code above with different sigmas in the ry and cx direction. For example, a sigma of 1.0 in the ry direction, and 6.0 in the cx direction. ::::::::::::::: solution @@ -506,28 +335,14 @@ ax.imshow(blurred) ![](fig/rectangle-gaussian-blurred.png){alt='Rectangular kernel blurred image'} -These unequal sigma values produce a kernel that is rectangular instead of square. -The result is an image that is much more blurred in the X direction than in the -Y direction. -For most use cases, a uniform blurring effect is desirable and -this kind of asymmetric blurring should be avoided. -However, it can be helpful in specific circumstances, e.g., when noise is present in -your image in a particular pattern or orientation, such as vertical lines, -or when you want to -[remove uniform noise without blurring edges present in the image in a particular orientation](https://www.researchgate.net/publication/228567435_An_edge_detection_algorithm_based_on_rectangular_Gaussian_kernels_for_machine_vision_applications). - +These unequal sigma values produce a kernel that is rectangular instead of square. The result is an image that is much more blurred in the X direction than in the Y direction. For most use cases, a uniform blurring effect is desirable and this kind of asymmetric blurring should be avoided. However, it can be helpful in specific circumstances, e.g., when noise is present in your image in a particular pattern or orientation, such as vertical lines, or when you want to [remove uniform noise without blurring edges present in the image in a particular orientation](https://www.researchgate.net/publication/228567435_An_edge_detection_algorithm_based_on_rectangular_Gaussian_kernels_for_machine_vision_applications). ::::::::::::::::::::::::: :::::::::::::::::::::::::::::::::::::::::::::::::: ## Other methods of blurring -The Gaussian blur is a way to apply a low-pass filter in scikit-image. -It is often used to remove Gaussian (i.e., random) noise in an image. -For other kinds of noise, e.g., "salt and pepper", a -median filter is typically used. -See [the `skimage.filters` documentation](https://scikit-image.org/docs/dev/api/skimage.filters.html#module-skimage.filters) -for a list of available filters. +The Gaussian blur is a way to apply a low-pass filter in scikit-image. It is often used to remove Gaussian (i.e., random) noise in an image. For other kinds of noise, e.g., "salt and pepper", a median filter is typically used. See [the `skimage.filters` documentation](https://scikit-image.org/docs/dev/api/skimage.filters.html#module-skimage.filters) for a list of available filters. :::::::::::::::::::::::::::::::::::::::: keypoints diff --git a/episodes/07-postprocessing.md b/episodes/07-postprocessing.md index 0c05b26..9684bfc 100644 --- a/episodes/07-postprocessing.md +++ b/episodes/07-postprocessing.md @@ -18,10 +18,7 @@ exercises: 55 ## Objects -In [the *Thresholding* episode](06-processing-segmentation.md) -we have covered dividing an image into foreground and background pixels. -In the shapes example image, -we considered the coloured shapes as foreground *objects* on a white background. +In [the *Thresholding* episode](06-processing-segmentation.md) we have covered dividing an image into foreground and background pixels. In the shapes example image, we considered the coloured shapes as foreground *objects* on a white background. ![](fig/shapes-01.jpg){alt='Original shapes image' .image-with-shadow} @@ -29,14 +26,9 @@ In thresholding we went from the original image to this version: ![](fig/shapes-01-mask.png){alt='Mask created by thresholding'} -Here, we created a mask that only highlights the parts of the image -that we find interesting, the *objects*. -All objects have pixel value of `True` while the background pixels are `False`. +Here, we created a mask that only highlights the parts of the image that we find interesting, the *objects*. All objects have pixel value of `True` while the background pixels are `False`. -By looking at the mask image, -one can count the objects that are present in the image (7). -But how did we actually do that, -how did we decide which lump of pixels constitutes a single object? +By looking at the mask image, one can count the objects that are present in the image (7). But how did we actually do that, how did we decide which lump of pixels constitutes a single object? ## Pixel Neighborhoods -In order to decide which pixels belong to the same object, -one can exploit their neighborhood: -pixels that are directly next to each other -and belong to the foreground class can be considered to belong to the same object. +In order to decide which pixels belong to the same object, one can exploit their neighborhood: pixels that are directly next to each other and belong to the foreground class can be considered to belong to the same object. -Let's discuss the concept of pixel neighborhoods in more detail. -Consider the following mask "image" with 8 rows, and 8 columns. -For the purpose of illustration, the digit `0` is used to represent -background pixels, and the letter `X` is used to represent -object pixels foreground). +Let's discuss the concept of pixel neighborhoods in more detail. Consider the following mask "image" with 8 rows, and 8 columns. For the purpose of illustration, the digit `0` is used to represent background pixels, and the letter `X` is used to represent object pixels foreground). ```output 0 0 0 0 0 0 0 0 @@ -64,14 +49,7 @@ object pixels foreground). 0 0 0 0 0 0 0 0 ``` -The pixels are organised in a rectangular grid. -In order to understand pixel neighborhoods -we will introduce the concept of "jumps" between pixels. -The jumps follow two rules: -First rule is that one jump is only allowed along the column, or the row. -Diagonal jumps are not allowed. -So, from a centre pixel, denoted with `o`, -only the pixels indicated with a `1` are reachable: +The pixels are organised in a rectangular grid. In order to understand pixel neighborhoods we will introduce the concept of "jumps" between pixels. The jumps follow two rules: First rule is that one jump is only allowed along the column, or the row. Diagonal jumps are not allowed. So, from a centre pixel, denoted with `o`, only the pixels indicated with a `1` are reachable: ```output - 1 - @@ -79,18 +57,9 @@ only the pixels indicated with a `1` are reachable: - 1 - ``` -The pixels on the diagonal (from `o`) are not reachable with a single jump, -which is denoted by the `-`. -The pixels reachable with a single jump form the **1-jump** neighborhood. +The pixels on the diagonal (from `o`) are not reachable with a single jump, which is denoted by the `-`. The pixels reachable with a single jump form the **1-jump** neighborhood. -The second rule states that in a sequence of jumps, -one may only jump in row and column direction once -> they have to be *orthogonal*. -An example of a sequence of orthogonal jumps is shown below. -Starting from `o` the first jump goes along the row to the right. -The second jump then goes along the column direction up. -After this, -the sequence cannot be continued as a jump has already been made -in both row and column direction. +The second rule states that in a sequence of jumps, one may only jump in row and column direction once -> they have to be *orthogonal*. An example of a sequence of orthogonal jumps is shown below. Starting from `o` the first jump goes along the row to the right. The second jump then goes along the column direction up. After this, the sequence cannot be continued as a jump has already been made in both row and column direction. ```output - - 2 @@ -98,10 +67,7 @@ in both row and column direction. - - - ``` -All pixels reachable with one, or two jumps form the **2-jump** neighborhood. -The grid below illustrates the pixels reachable from -the centre pixel `o` with a single jump, highlighted with a `1`, -and the pixels reachable with 2 jumps with a `2`. +All pixels reachable with one, or two jumps form the **2-jump** neighborhood. The grid below illustrates the pixels reachable from the centre pixel `o` with a single jump, highlighted with a `1`, and the pixels reachable with 2 jumps with a `2`. ```output 2 1 2 @@ -109,10 +75,7 @@ and the pixels reachable with 2 jumps with a `2`. 2 1 2 ``` -We want to revisit our example image mask from above and apply -the two different neighborhood rules. -With a single jump connectivity for each pixel, we get two resulting objects, -highlighted in the image with `A`'s and `B`'s. +We want to revisit our example image mask from above and apply the two different neighborhood rules. With a single jump connectivity for each pixel, we get two resulting objects, highlighted in the image with `A`'s and `B`'s. ```output 0 0 0 0 0 0 0 0 @@ -123,11 +86,7 @@ highlighted in the image with `A`'s and `B`'s. 0 0 0 0 0 0 0 0 ``` -In the 1-jump version, -only pixels that have direct neighbors along rows or columns are considered connected. -Diagonal connections are not included in the 1-jump neighborhood. -With two jumps, however, we only get a single object `A` because pixels are also -considered connected along the diagonals. +In the 1-jump version, only pixels that have direct neighbors along rows or columns are considered connected. Diagonal connections are not included in the 1-jump neighborhood. With two jumps, however, we only get a single object `A` because pixels are also considered connected along the diagonals. ```output 0 0 0 0 0 0 0 0 @@ -190,32 +149,14 @@ a) 2 ## Jumps and neighborhoods -We have just introduced how you can reach different neighboring -pixels by performing one or more orthogonal jumps. We have used the -terms 1-jump and 2-jump neighborhood. There is also a different way -of referring to these neighborhoods: the 4- and 8-neighborhood. -With a single jump you can reach four pixels from a given starting -pixel. Hence, the 1-jump neighborhood corresponds to the -4-neighborhood. When two orthogonal jumps are allowed, eight pixels -can be reached, so the 2-jump neighborhood corresponds to the -8-neighborhood. +We have just introduced how you can reach different neighboring pixels by performing one or more orthogonal jumps. We have used the terms 1-jump and 2-jump neighborhood. There is also a different way of referring to these neighborhoods: the 4- and 8-neighborhood. With a single jump you can reach four pixels from a given starting pixel. Hence, the 1-jump neighborhood corresponds to the 4-neighborhood. When two orthogonal jumps are allowed, eight pixels can be reached, so the 2-jump neighborhood corresponds to the 8-neighborhood. :::::::::::::::::::::::::::::::::::::::::::::::::: ## Connected Component Analysis -In order to find the objects in an image, we want to employ an -operation that is called Connected Component Analysis (CCA). -This operation takes a binary image as an input. -Usually, the `False` value in this image is associated with background pixels, -and the `True` value indicates foreground, or object pixels. -Such an image can be produced, e.g., with thresholding. -Given a thresholded image, -the connected component analysis produces a new *labeled* image with integer pixel values. -Pixels with the same value, belong to the same object. -scikit-image provides connected component analysis in the function `ski.measure.label()`. -Let us add this function to the already familiar steps of thresholding an image. +In order to find the objects in an image, we want to employ an operation that is called Connected Component Analysis (CCA). This operation takes a binary image as an input. Usually, the `False` value in this image is associated with background pixels, and the `True` value indicates foreground, or object pixels. Such an image can be produced, e.g., with thresholding. Given a thresholded image, the connected component analysis produces a new *labeled* image with integer pixel values. Pixels with the same value, belong to the same object. scikit-image provides connected component analysis in the function `ski.measure.label()`. Let us add this function to the already familiar steps of thresholding an image. First, import the packages needed for this episode: @@ -249,63 +190,34 @@ def connected_components(filename, sigma=1.0, t=0.5, connectivity=2): return labeled_image, count ``` -The first four lines of code are familiar from -[the *Thresholding* episode](06-processing-segmentation.md). +The first four lines of code are familiar from [the *Thresholding* episode](06-processing-segmentation.md). -Then we call the `ski.measure.label` function. -This function has one positional argument where we pass the `binary_mask`, -i.e., the binary image to work on. -With the optional argument `connectivity`, -we specify the neighborhood in units of orthogonal jumps. -For example, -by setting `connectivity=2` we will consider the 2-jump neighborhood introduced above. -The function returns a `labeled_image` where each pixel has -a unique value corresponding to the object it belongs to. -In addition, we pass the optional parameter `return_num=True` to return -the maximum label index as `count`. +Then we call the `ski.measure.label` function. This function has one positional argument where we pass the `binary_mask`, i.e., the binary image to work on. With the optional argument `connectivity`, we specify the neighborhood in units of orthogonal jumps. For example, by setting `connectivity=2` we will consider the 2-jump neighborhood introduced above. The function returns a `labeled_image` where each pixel has a unique value corresponding to the object it belongs to. In addition, we pass the optional parameter `return_num=True` to return the maximum label index as `count`. ::::::::::::::::::::::::::::::::::::::::: callout ## Optional parameters and return values -The optional parameter `return_num` changes the data type that is -returned by the function `ski.measure.label`. -The number of labels is only returned if `return_num` is *True*. -Otherwise, the function only returns the labeled image. -This means that we have to pay attention when assigning -the return value to a variable. -If we omit the optional parameter `return_num` or pass `return_num=False`, -we can call the function as +The optional parameter `return_num` changes the data type that is returned by the function `ski.measure.label`. The number of labels is only returned if `return_num` is *True*. Otherwise, the function only returns the labeled image. This means that we have to pay attention when assigning the return value to a variable. If we omit the optional parameter `return_num` or pass `return_num=False`, we can call the function as ```python labeled_image = ski.measure.label(binary_mask) ``` -If we pass `return_num=True`, the function returns a tuple and we -can assign it as +If we pass `return_num=True`, the function returns a tuple and we can assign it as ```python labeled_image, count = ski.measure.label(binary_mask, return_num=True) ``` -If we used the same assignment as in the first case, -the variable `labeled_image` would become a tuple, -in which `labeled_image[0]` is the image -and `labeled_image[1]` is the number of labels. -This could cause confusion if we assume that `labeled_image` -only contains the image and pass it to other functions. -If you get an -`AttributeError: 'tuple' object has no attribute 'shape'` -or similar, check if you have assigned the return values consistently -with the optional parameters. +If we used the same assignment as in the first case, the variable `labeled_image` would become a tuple, in which `labeled_image[0]` is the image and `labeled_image[1]` is the number of labels. This could cause confusion if we assume that `labeled_image` only contains the image and pass it to other functions. If you get an `AttributeError: 'tuple' object has no attribute 'shape'` or similar, check if you have assigned the return values consistently with the optional parameters. :::::::::::::::::::::::::::::::::::::::::::::::::: -We can call the above function `connected_components` and -display the labeled image like so: +We can call the above function `connected_components` and display the labeled image like so: ```python labeled_image, count = connected_components(filename="data/shapes-01.jpg", sigma=2.0, t=0.9, connectivity=2) @@ -319,19 +231,9 @@ ax.set_axis_off(); ## Do you see an empty image? -If you are using an older version of Matplotlib you might get a warning -`UserWarning: Low image data range; displaying image with stretched contrast.` -or just see a visually empty image. +If you are using an older version of Matplotlib you might get a warning `UserWarning: Low image data range; displaying image with stretched contrast.` or just see a visually empty image. -What went wrong? -When you hover over the image, -the pixel values are shown as numbers in the lower corner of the viewer. -You can see that some pixels have values different from `0`, -so they are not actually all the same value. -Let's find out more by examining `labeled_image`. -Properties that might be interesting in this context are `dtype`, -the minimum and maximum value. -We can print them with the following lines: +What went wrong? When you hover over the image, the pixel values are shown as numbers in the lower corner of the viewer. You can see that some pixels have values different from `0`, so they are not actually all the same value. Let's find out more by examining `labeled_image`. Properties that might be interesting in this context are `dtype`, the minimum and maximum value. We can print them with the following lines: ```python print("dtype:", labeled_image.dtype) @@ -347,22 +249,14 @@ min: 0 max: 11 ``` -The `dtype` of `labeled_image` is `int32`. -This means that values in this image range from `-2 ** 31` to `2 ** 31 - 1`. -Those are really big numbers. -From this available space we only use the range from `0` to `11`. -When showing this image in the viewer, -it may squeeze the complete range into 256 gray values. -Therefore, the range of our numbers does not produce any visible variation. One way to rectify this -is to explicitly specify the data range we want the colormap to cover: +The `dtype` of `labeled_image` is `int32`. This means that values in this image range from `-2 ** 31` to `2 ** 31 - 1`. Those are really big numbers. From this available space we only use the range from `0` to `11`. When showing this image in the viewer, it may squeeze the complete range into 256 gray values. Therefore, the range of our numbers does not produce any visible variation. One way to rectify this is to explicitly specify the data range we want the colormap to cover: ```python fig, ax = plt.subplots() ax.imshow(labeled_image, vmin=np.min(labeled_image), vmax=np.max(labeled_image)) ``` -Note this is the default behaviour for newer versions of `matplotlib.pyplot.imshow`. -Alternatively we could convert the image to RGB and then display it. +Note this is the default behaviour for newer versions of `matplotlib.pyplot.imshow`. Alternatively we could convert the image to RGB and then display it. ::::::::::::::::::::::::: @@ -371,19 +265,11 @@ Alternatively we could convert the image to RGB and then display it. ## Suppressing outputs in Jupyter Notebooks -We just used `ax.set_axis_off();` to hide the axis from the image for a visually cleaner figure. The -semicolon is added to supress the output(s) of the statement, in this [case](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.axis.html) -the axis limits. This is specific to Jupyter Notebooks. +We just used `ax.set_axis_off();` to hide the axis from the image for a visually cleaner figure. The semicolon is added to supress the output(s) of the statement, in this [case](https://matplotlib.org/stable/api/_as_gen/matplotlib.pyplot.axis.html) the axis limits. This is specific to Jupyter Notebooks. :::::::::::::::::::::::::::::::::::::::::::::::::: -We can use the function `ski.color.label2rgb()` -to convert the 32-bit grayscale labeled image to standard RGB colour -(recall that we already used the `ski.color.rgb2gray()` function -to convert to grayscale). -With `ski.color.label2rgb()`, -all objects are coloured according to a list of colours that can be customised. -We can use the following commands to convert and show the image: +We can use the function `ski.color.label2rgb()` to convert the 32-bit grayscale labeled image to standard RGB colour (recall that we already used the `ski.color.rgb2gray()` function to convert to grayscale). With `ski.color.label2rgb()`, all objects are coloured according to a list of colours that can be customised. We can use the following commands to convert and show the image: ```python # convert the label image to color image @@ -400,9 +286,7 @@ ax.set_axis_off(); ## How many objects are in that image (15 min) -Now, it is your turn to practice. -Using the function `connected_components`, -find two ways of printing out the number of objects found in the image. +Now, it is your turn to practice. Using the function `connected_components`, find two ways of printing out the number of objects found in the image. What number of objects would you expect to get? @@ -412,26 +296,13 @@ How does changing the `sigma` and `threshold` values influence the result? ## Solution -As you might have guessed, the return value `count` already -contains the number of objects found in the image. So it can simply be printed -with +As you might have guessed, the return value `count` already contains the number of objects found in the image. So it can simply be printed with ```python print("Found", count, "objects in the image.") ``` -But there is also a way to obtain the number of found objects from -the labeled image itself. -Recall that all pixels that belong to a single object -are assigned the same integer value. -The connected component algorithm produces consecutive numbers. -The background gets the value `0`, -the first object gets the value `1`, -the second object the value `2`, and so on. -This means that by finding the object with the maximum value, -we also know how many objects there are in the image. -We can thus use the `np.max` function from NumPy to -find the maximum value that equals the number of found objects: +But there is also a way to obtain the number of found objects from the labeled image itself. Recall that all pixels that belong to a single object are assigned the same integer value. The connected component algorithm produces consecutive numbers. The background gets the value `0`, the first object gets the value `1`, the second object the value `2`, and so on. This means that by finding the object with the maximum value, we also know how many objects there are in the image. We can thus use the `np.max` function from NumPy to find the maximum value that equals the number of found objects: ```python num_objects = np.max(labeled_image) @@ -445,12 +316,7 @@ both methods will print Found 11 objects in the image. ``` -Lowering the threshold will result in fewer objects. -The higher the threshold is set, the more objects are found. -More and more background noise gets picked up as objects. -Larger sigmas produce binary masks with less noise and hence -a smaller number of objects. -Setting sigma too high bears the danger of merging objects. +Lowering the threshold will result in fewer objects. The higher the threshold is set, the more objects are found. More and more background noise gets picked up as objects. Larger sigmas produce binary masks with less noise and hence a smaller number of objects. Setting sigma too high bears the danger of merging objects. @@ -458,46 +324,15 @@ Setting sigma too high bears the danger of merging objects. :::::::::::::::::::::::::::::::::::::::::::::::::: -You might wonder why the connected component analysis with `sigma=2.0`, -and `threshold=0.9` finds 11 objects, whereas we would expect only 7 objects. -Where are the four additional objects? -With a bit of detective work, we can spot some small objects in the image, -for example, near the left border. +You might wonder why the connected component analysis with `sigma=2.0`, and `threshold=0.9` finds 11 objects, whereas we would expect only 7 objects. Where are the four additional objects? With a bit of detective work, we can spot some small objects in the image, for example, near the left border. ![](fig/shapes-01-cca-detail.png){alt='shapes-01.jpg mask detail'} -For us it is clear that these small spots are artifacts and -not objects we are interested in. -But how can we tell the computer? -One way to calibrate the algorithm is to adjust the parameters for -blurring (`sigma`) and thresholding (`t`), -but you may have noticed during the above exercise that -it is quite hard to find a combination that produces the right output number. -In some cases, background noise gets picked up as an object. -And with other parameters, -some of the foreground objects get broken up or disappear completely. -Therefore, we need other criteria to describe desired properties of the objects -that are found. +For us it is clear that these small spots are artifacts and not objects we are interested in. But how can we tell the computer? One way to calibrate the algorithm is to adjust the parameters for blurring (`sigma`) and thresholding (`t`), but you may have noticed during the above exercise that it is quite hard to find a combination that produces the right output number. In some cases, background noise gets picked up as an object. And with other parameters, some of the foreground objects get broken up or disappear completely. Therefore, we need other criteria to describe desired properties of the objects that are found. ## Morphometrics - Describe object features with numbers -Morphometrics is concerned with the quantitative analysis of objects and -considers properties such as size and shape. -For the example of the images with the shapes, -our intuition tells us that the objects should be of a certain size or area. -So we could use a minimum area as a criterion for when an object should be detected. -To apply such a criterion, -we need a way to calculate the area of objects found by connected components. -Recall how we determined the root mass in -[the *Thresholding* episode](06-processing-segmentation.md) -by counting the pixels in the binary mask. -But here we want to calculate the area of several objects in the labeled image. -The scikit-image library provides the function `ski.measure.regionprops` -to measure the properties of labeled regions. -It returns a list of `RegionProperties` that describe each connected region in the images. -The properties can be accessed using the attributes of the `RegionProperties` data type. -Here we will use the properties `"area"` and `"label"`. -You can explore the scikit-image documentation to learn about other properties available. +Morphometrics is concerned with the quantitative analysis of objects and considers properties such as size and shape. For the example of the images with the shapes, our intuition tells us that the objects should be of a certain size or area. So we could use a minimum area as a criterion for when an object should be detected. To apply such a criterion, we need a way to calculate the area of objects found by connected components. Recall how we determined the root mass in [the *Thresholding* episode](06-processing-segmentation.md) by counting the pixels in the binary mask. But here we want to calculate the area of several objects in the labeled image. The scikit-image library provides the function `ski.measure.regionprops` to measure the properties of labeled regions. It returns a list of `RegionProperties` that describe each connected region in the images. The properties can be accessed using the attributes of the `RegionProperties` data type. Here we will use the properties `"area"` and `"label"`. You can explore the scikit-image documentation to learn about other properties available. We can get a list of areas of the labeled objects as follows: @@ -518,13 +353,9 @@ This will produce the output ## Plot a histogram of the object area distribution (10 min) -Similar to how we determined a "good" threshold in -[the *Thresholding* episode](06-processing-segmentation.md), -it is often helpful to inspect the histogram of an object property. -For example, we want to look at the distribution of the object areas. +Similar to how we determined a "good" threshold in [the *Thresholding* episode](06-processing-segmentation.md), it is often helpful to inspect the histogram of an object property. For example, we want to look at the distribution of the object areas. -1. Create and examine a [histogram](05-creating-histograms.md) - of the object areas obtained with `ski.measure.regionprops`. +1. Create and examine a [histogram](05-creating-histograms.md) of the object areas obtained with `ski.measure.regionprops`. 2. What does the histogram tell you about the objects? ::::::::::::::: solution @@ -542,31 +373,9 @@ ax.set_ylabel("Number of objects"); ![](fig/shapes-01-areas-histogram.png){alt='Histogram of object areas'} -The histogram shows the number of objects (vertical axis) -whose area is within a certain range (horizontal axis). -The height of the bars in the histogram indicates -the prevalence of objects with a certain area. -The whole histogram tells us about the distribution of object sizes in the image. -It is often possible to identify gaps between groups of bars -(or peaks if we draw the histogram as a continuous curve) -that tell us about certain groups in the image. - -In this example, we can see that there are four small objects that -contain less than 50000 pixels. -Then there is a group of four (1+1+2) objects in -the range between 200000 and 400000, -and three objects with a size around 500000. -For our object count, we might want to disregard the small objects as artifacts, -i.e, we want to ignore the leftmost bar of the histogram. -We could use a threshold of 50000 as the minimum area to count. -In fact, the `object_areas` list already tells us that -there are fewer than 200 pixels in these objects. -Therefore, it is reasonable to require a minimum area of at least 200 pixels -for a detected object. -In practice, finding the "right" threshold can be tricky and -usually involves an educated guess based on domain knowledge. - +The histogram shows the number of objects (vertical axis) whose area is within a certain range (horizontal axis). The height of the bars in the histogram indicates the prevalence of objects with a certain area. The whole histogram tells us about the distribution of object sizes in the image. It is often possible to identify gaps between groups of bars (or peaks if we draw the histogram as a continuous curve) that tell us about certain groups in the image. +In this example, we can see that there are four small objects that contain less than 50000 pixels. Then there is a group of four (1+1+2) objects in the range between 200000 and 400000, and three objects with a size around 500000. For our object count, we might want to disregard the small objects as artifacts, i.e, we want to ignore the leftmost bar of the histogram. We could use a threshold of 50000 as the minimum area to count. In fact, the `object_areas` list already tells us that there are fewer than 200 pixels in these objects. Therefore, it is reasonable to require a minimum area of at least 200 pixels for a detected object. In practice, finding the "right" threshold can be tricky and usually involves an educated guess based on domain knowledge. ::::::::::::::::::::::::: @@ -576,19 +385,15 @@ usually involves an educated guess based on domain knowledge. ## Filter objects by area (10 min) -Now we would like to use a minimum area criterion to obtain a more -accurate count of the objects in the image. +Now we would like to use a minimum area criterion to obtain a more accurate count of the objects in the image. -1. Find a way to calculate the number of objects by only counting - objects above a certain area. +1. Find a way to calculate the number of objects by only counting objects above a certain area. ::::::::::::::: solution ## Solution -One way to count only objects above a certain area is to first -create a list of those objects, and then take the length of that -list as the object count. This can be done as follows: +One way to count only objects above a certain area is to first create a list of those objects, and then take the length of that list as the object count. This can be done as follows: ```python min_area = 200 @@ -599,15 +404,7 @@ for objf in object_features: print("Found", len(large_objects), "objects!") ``` -Another option is to use NumPy arrays to create the list of large objects. -We first create an array `object_areas` containing the object areas, -and an array `object_labels` containing the object labels. -The labels of the objects are also returned by `ski.measure.regionprops`. -We have already seen that we can create boolean arrays using comparison operators. -Here we can use `object_areas > min_area` -to produce an array that has the same dimension as `object_labels`. -It can then be used to select the labels of objects whose area is -greater than `min_area` by indexing: +Another option is to use NumPy arrays to create the list of large objects. We first create an array `object_areas` containing the object areas, and an array `object_labels` containing the object labels. The labels of the objects are also returned by `ski.measure.regionprops`. We have already seen that we can create boolean arrays using comparison operators. Here we can use `object_areas > min_area` to produce an array that has the same dimension as `object_labels`. It can then be used to select the labels of objects whose area is greater than `min_area` by indexing: ```python object_areas = np.array([objf["area"] for objf in object_features]) @@ -616,26 +413,16 @@ large_objects = object_labels[object_areas > min_area] print("Found", len(large_objects), "objects!") ``` -The advantage of using NumPy arrays is that -`for` loops and `if` statements in Python can be slow, -and in practice the first approach may not be feasible -if the image contains a large number of objects. -In that case, NumPy array functions turn out to be very useful because -they are much faster. +The advantage of using NumPy arrays is that `for` loops and `if` statements in Python can be slow, and in practice the first approach may not be feasible if the image contains a large number of objects. In that case, NumPy array functions turn out to be very useful because they are much faster. -In this example, we can also use the `np.count_nonzero` function -that we have seen earlier together with the `>` operator to count -the objects whose area is above `min_area`. +In this example, we can also use the `np.count_nonzero` function that we have seen earlier together with the `>` operator to count the objects whose area is above `min_area`. ```python n = np.count_nonzero(object_areas > min_area) print("Found", n, "objects!") ``` -For all three alternatives, the output is the same and gives the -expected count of 7 objects. - - +For all three alternatives, the output is the same and gives the expected count of 7 objects. ::::::::::::::::::::::::: @@ -645,11 +432,7 @@ expected count of 7 objects. ## Using functions from NumPy and other Python packages -Functions from Python packages such as NumPy are often more efficient and -require less code to write. -It is a good idea to browse the reference pages of `numpy` and `skimage` to -look for an availabe function that can solve a given task. - +Functions from Python packages such as NumPy are often more efficient and require less code to write. It is a good idea to browse the reference pages of `numpy` and `skimage` to look for an availabe function that can solve a given task. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -657,22 +440,15 @@ look for an availabe function that can solve a given task. ## Remove small objects (20 min) -We might also want to exclude (mask) the small objects when plotting -the labeled image. +We might also want to exclude (mask) the small objects when plotting the labeled image. -2. Enhance the `connected_components` function such that - it automatically removes objects that are below a certain area that is - passed to the function as an optional parameter. +2. Enhance the `connected_components` function such that it automatically removes objects that are below a certain area that is passed to the function as an optional parameter. ::::::::::::::: solution ## Solution -To remove the small objects from the labeled image, -we change the value of all pixels that belong to the small objects to -the background label 0. -One way to do this is to loop over all objects and -set the pixels that match the label of the object to 0. +To remove the small objects from the labeled image, we change the value of all pixels that belong to the small objects to the background label 0. One way to do this is to loop over all objects and set the pixels that match the label of the object to 0. ```python for object_id, objf in enumerate(object_features, start=1): @@ -680,17 +456,7 @@ for object_id, objf in enumerate(object_features, start=1): labeled_image[labeled_image == objf["label"]] = 0 ``` -Here NumPy functions can also be used to eliminate -`for` loops and `if` statements. -Like above, we can create an array of the small object labels with -the comparison `object_areas < min_area`. -We can use another NumPy function, `np.isin`, -to set the pixels of all small objects to 0. -`np.isin` takes two arrays and returns a boolean array with values -`True` if the entry of the first array is found in the second array, -and `False` otherwise. -This array can then be used to index the `labeled_image` and -set the entries that belong to small objects to `0`. +Here NumPy functions can also be used to eliminate `for` loops and `if` statements. Like above, we can create an array of the small object labels with the comparison `object_areas < min_area`. We can use another NumPy function, `np.isin`, to set the pixels of all small objects to 0. `np.isin` takes two arrays and returns a boolean array with values `True` if the entry of the first array is found in the second array, and `False` otherwise. This array can then be used to index the `labeled_image` and set the entries that belong to small objects to `0`. ```python object_areas = np.array([objf["area"] for objf in object_features]) @@ -699,14 +465,7 @@ small_objects = object_labels[object_areas < min_area] labeled_image[np.isin(labeled_image, small_objects)] = 0 ``` -An even more elegant way to remove small objects from the image is -to leverage the `ski.morphology` module. -It provides a function `ski.morphology.remove_small_objects` that -does exactly what we are looking for. -It can be applied to a binary image and -returns a mask in which all objects smaller than `min_area` are excluded, -i.e, their pixel values are set to `False`. -We can then apply `ski.measure.label` to the masked image: +An even more elegant way to remove small objects from the image is to leverage the `ski.morphology` module. It provides a function `ski.morphology.remove_small_objects` that does exactly what we are looking for. It can be applied to a binary image and returns a mask in which all objects smaller than `min_area` are excluded, i.e, their pixel values are set to `False`. We can then apply `ski.measure.label` to the masked image: ```python object_mask = ski.morphology.remove_small_objects(binary_mask, min_size=min_area) @@ -714,8 +473,7 @@ labeled_image, n = ski.measure.label(object_mask, connectivity=connectivity, return_num=True) ``` -Using the scikit-image features, we can implement -the `enhanced_connected_component` as follows: +Using the scikit-image features, we can implement the `enhanced_connected_component` as follows: ```python def enhanced_connected_components(filename, sigma=1.0, t=0.5, connectivity=2, min_area=0): @@ -729,8 +487,7 @@ def enhanced_connected_components(filename, sigma=1.0, t=0.5, connectivity=2, mi return labeled_image, count ``` -We can now call the function with a chosen `min_area` and -display the resulting labeled image: +We can now call the function with a chosen `min_area` and display the resulting labeled image: ```python labeled_image, count = enhanced_connected_components(filename="data/shapes-01.jpg", sigma=2.0, t=0.9, @@ -750,10 +507,7 @@ print("Found", count, "objects in the image.") Found 7 objects in the image. ``` -Note that the small objects are "gone" and we obtain the correct -number of 7 objects in the image. - - +Note that the small objects are "gone" and we obtain the correct number of 7 objects in the image. ::::::::::::::::::::::::: @@ -763,23 +517,13 @@ number of 7 objects in the image. ## Colour objects by area (optional, not included in timing) -Finally, we would like to display the image with the objects coloured -according to the magnitude of their area. -In practice, this can be used with other properties to give -visual cues of the object properties. +Finally, we would like to display the image with the objects coloured according to the magnitude of their area. In practice, this can be used with other properties to give visual cues of the object properties. ::::::::::::::: solution ## Solution -We already know how to get the areas of the objects from the `regionprops`. -We just need to insert a zero area value for the background -(to colour it like a zero size object). -The background is also labeled `0` in the `labeled_image`, -so we insert the zero area value in front of the first element of -`object_areas` with `np.insert`. -Then we can create a `colored_area_image` where we assign each pixel value -the area by indexing the `object_areas` with the label values in `labeled_image`. +We already know how to get the areas of the objects from the `regionprops`. We just need to insert a zero area value for the background (to colour it like a zero size object). The background is also labeled `0` in the `labeled_image`, so we insert the zero area value in front of the first element of `object_areas` with `np.insert`. Then we can create a `colored_area_image` where we assign each pixel value the area by indexing the `object_areas` with the label values in `labeled_image`. ```python object_areas = np.array([objf["area"] for objf in ski.measure.regionprops(labeled_image)]) @@ -799,24 +543,7 @@ ax.set_axis_off(); ::::::::::::::::::::::::::::::::::::::::: callout -You may have noticed that in the solution, we have used the -`labeled_image` to index the array `object_areas`. This is an -example of [advanced indexing in -NumPy](https://numpy.org/doc/stable/user/basics.indexing.html#advanced-indexing) -The result is an array of the same shape as the `labeled_image` -whose pixel values are selected from `object_areas` according to -the object label. Hence the objects will be colored by area when -the result is displayed. Note that advanced indexing with an -integer array works slightly different than the indexing with a -Boolean array that we have used for masking. While Boolean array -indexing returns only the entries corresponding to the `True` -values of the index, integer array indexing returns an array -with the same shape as the index. You can read more about advanced -indexing in the [NumPy -documentation](https://numpy.org/doc/stable/user/basics.indexing.html#advanced-indexing). - - - +You may have noticed that in the solution, we have used the `labeled_image` to index the array `object_areas`. This is an example of [advanced indexing in NumPy](https://numpy.org/doc/stable/user/basics.indexing.html#advanced-indexing) The result is an array of the same shape as the `labeled_image` whose pixel values are selected from `object_areas` according to the object label. Hence the objects will be colored by area when the result is displayed. Note that advanced indexing with an integer array works slightly different than the indexing with a Boolean array that we have used for masking. While Boolean array indexing returns only the entries corresponding to the `True` values of the index, integer array indexing returns an array with the same shape as the index. You can read more about advanced indexing in the [NumPy documentation](https://numpy.org/doc/stable/user/basics.indexing.html#advanced-indexing). :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/episodes/10-challenges.md b/episodes/10-challenges.md index d8cd366..36e5234 100644 --- a/episodes/10-challenges.md +++ b/episodes/10-challenges.md @@ -17,15 +17,11 @@ exercises: 40 :::::::::::::::::::::::::::::::::::::::::::::::::: -In this episode, we will provide a final challenge for you to attempt, -based on all the skills you have acquired so far. -This challenge will be related to the shape of objects in images (*morphometrics*). +In this episode, we will provide a final challenge for you to attempt, based on all the skills you have acquired so far. This challenge will be related to the shape of objects in images (*morphometrics*). ## Morphometrics: Bacteria Colony Counting -As mentioned in [the workshop introduction](01-introduction.md), -your morphometric challenge is to determine how many bacteria colonies are in -each of these images: +As mentioned in [the workshop introduction](01-introduction.md), your morphometric challenge is to determine how many bacteria colonies are in each of these images: ![](fig/colonies-01.jpg){alt='Colony image 1'} @@ -33,28 +29,19 @@ each of these images: ![](fig/colonies-03.jpg){alt='Colony image 3'} -The image files can be found at -`data/colonies-01.tif`, -`data/colonies-02.tif`, -and `data/colonies-03.tif`. +The image files can be found at `data/colonies-01.tif`, `data/colonies-02.tif`, and `data/colonies-03.tif`. ::::::::::::::::::::::::::::::::::::::: challenge ## Morphometrics for bacterial colonies -Write a Python program that uses scikit-image to -count the number of bacteria colonies in each image, -and for each, produce a new image that highlights the colonies. -The image should look similar to this one: +Write a Python program that uses scikit-image to count the number of bacteria colonies in each image, and for each, produce a new image that highlights the colonies. The image should look similar to this one: ![](fig/colonies-01-summary.png){alt='Sample morphometric output'} Additionally, print out the number of colonies for each image. -Use what you have learnt about [histograms](05-creating-histograms.md), -[thresholding and connected component analysis](06-processing-segmentation.md). -Try to put your code into a re-usable function, -so that it can be applied conveniently to any image file. +Use what you have learnt about [histograms](05-creating-histograms.md), [thresholding and connected component analysis](06-processing-segmentation.md). Try to put your code into a re-usable function, so that it can be applied conveniently to any image file. ::::::::::::::: solution @@ -80,9 +67,7 @@ ax.imshow(bacteria_image) ![](fig/colonies-01.jpg){alt='Colony image 1'} -Next, we need to threshold the image to create a mask that covers only -the dark bacterial colonies. -This is easier using a grayscale image, so we convert it here: +Next, we need to threshold the image to create a mask that covers only the dark bacterial colonies. This is easier using a grayscale image, so we convert it here: ```python gray_bacteria = ski.color.rgb2gray(bacteria_image) @@ -109,11 +94,7 @@ ax.set_xlim(0, 1.0) ![](fig/colonies-01-histogram.png){alt='Histogram image'} -In this histogram, we see three peaks - -the left one (i.e. the darkest pixels) is our colonies, -the central peak is the yellow/brown culture medium in the dish, -and the right one (i.e. the brightest pixels) is the white image background. -Therefore, we choose a threshold that selects the small left peak: +In this histogram, we see three peaks - the left one (i.e. the darkest pixels) is our colonies, the central peak is the yellow/brown culture medium in the dish, and the right one (i.e. the brightest pixels) is the white image background. Therefore, we choose a threshold that selects the small left peak: ```python mask = blurred_image < 0.2 @@ -123,17 +104,14 @@ ax.imshow(mask, cmap="gray") ![](fig/colonies-01-mask.png){alt='Colony mask image'} -This mask shows us where the colonies are in the image - -but how can we count how many there are? -This requires connected component analysis: +This mask shows us where the colonies are in the image - but how can we count how many there are? This requires connected component analysis: ```python labeled_image, count = ski.measure.label(mask, return_num=True) print(count) ``` -Finally, we create the summary image of the coloured colonies on top of -the grayscale image: +Finally, we create the summary image of the coloured colonies on top of the grayscale image: ```python # color each of the colonies a different color @@ -149,9 +127,7 @@ ax.imshow(summary_image) ![](fig/colonies-01-summary.png){alt='Sample morphometric output'} -Now that we've completed the task for one image, -we need to repeat this for the remaining two images. -This is a good point to collect the lines above into a re-usable function: +Now that we've completed the task for one image, we need to repeat this for the remaining two images. This is a good point to collect the lines above into a re-usable function: ```python def count_colonies(image_filename): @@ -180,18 +156,7 @@ for image_filename in ["data/colonies-01.tif", "data/colonies-02.tif", "data/col ![](fig/colonies-02-summary.png){alt='Colony 2 output'} ![](fig/colonies-03-summary.png){alt='Colony 3 output'} -You'll notice that for the images with more colonies, the results aren't perfect. -For example, some small colonies are missing, -and there are likely some small black spots being labelled incorrectly as colonies. -You could expand this solution to, for example, -use an automatically determined threshold for each image, -which may fit each better. -Also, you could filter out colonies below a certain size -(as we did in [the *Connected Component Analysis* episode](06-processing-segmentation.md)). -You'll also see that some touching colonies are merged into one big colony. -This could be fixed with more complicated segmentation methods -(outside of the scope of this lesson) like -[watershed](https://scikit-image.org/docs/dev/auto_examples/segmentation/plot_watershed.html). +You'll notice that for the images with more colonies, the results aren't perfect. For example, some small colonies are missing, and there are likely some small black spots being labelled incorrectly as colonies. You could expand this solution to, for example, use an automatically determined threshold for each image, which may fit each better. Also, you could filter out colonies below a certain size (as we did in [the *Connected Component Analysis* episode](06-processing-segmentation.md)). You'll also see that some touching colonies are merged into one big colony. This could be fixed with more complicated segmentation methods (outside of the scope of this lesson) like [watershed](https://scikit-image.org/docs/dev/auto_examples/segmentation/plot_watershed.html). ::::::::::::::::::::::::: @@ -201,14 +166,11 @@ This could be fixed with more complicated segmentation methods ## Colony counting with minimum size and automated threshold (optional, not included in timing) -Modify your function from the previous exercise for colony counting to (i) exclude objects smaller -than a specified size and (ii) use an automated thresholding approach, e.g. Otsu, to mask the -colonies. +Modify your function from the previous exercise for colony counting to (i) exclude objects smaller than a specified size and (ii) use an automated thresholding approach, e.g. Otsu, to mask the colonies. ::::::::::::::::::::::::::::::::::::::: solution -Here is a modified function with the requested features. Note when calculating the Otsu threshold we -don't include the very bright pixels outside the dish. +Here is a modified function with the requested features. Note when calculating the Otsu threshold we don't include the very bright pixels outside the dish. ```python def count_colonies_enhanced(image_filename, sigma=1.0, min_colony_size=10, connectivity=2): @@ -254,4 +216,4 @@ def count_colonies_enhanced(image_filename, sigma=1.0, min_colony_size=10, conne Take a look at our [curated list of resources](further-reading.md) for further publicly available courses, resources and scientific literature around image processing and more. -:::::::::::::::::::::::::::::::::::::::::::::::::: \ No newline at end of file +:::::::::::::::::::::::::::::::::::::::::::::::::: From 6b2a9b5a3bf7ca94d9659937e9f6111301831f66 Mon Sep 17 00:00:00 2001 From: Marco Dalla Vecchia Date: Sun, 29 Mar 2026 18:12:36 +0200 Subject: [PATCH 4/4] formatted rest of markdown files --- CONTRIBUTING.md | 107 +++++++------------------------- README.md | 5 +- index.md | 7 +-- instructors/instructor-notes.md | 15 +---- learners/discuss.md | 33 ++-------- learners/prereqs.md | 11 +--- learners/setup.md | 46 +++----------- 7 files changed, 48 insertions(+), 176 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 188063f..b756849 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,18 +1,10 @@ ## Contributing -[The Carpentries][cp-site] ([Software Carpentry][swc-site], [Data -Carpentry][dc-site], and [Library Carpentry][lc-site]) are open source -projects, and we welcome contributions of all kinds: new lessons, fixes to -existing material, bug reports, and reviews of proposed changes are all -welcome. +[The Carpentries][cp-site] ([Software Carpentry][swc-site], [Data Carpentry][dc-site], and [Library Carpentry][lc-site]) are open source projects, and we welcome contributions of all kinds: new lessons, fixes to existing material, bug reports, and reviews of proposed changes are all welcome. ### Contributor Agreement -By contributing, you agree that we may redistribute your work under [our -license](LICENSE.md). In exchange, we will address your issues and/or assess -your change proposal as promptly as we can, and help you become a member of our -community. Everyone involved in [The Carpentries][cp-site] agrees to abide by -our [code of conduct](CODE_OF_CONDUCT.md). +By contributing, you agree that we may redistribute your work under [our license](LICENSE.md). In exchange, we will address your issues and/or assess your change proposal as promptly as we can, and help you become a member of our community. Everyone involved in [The Carpentries][cp-site] agrees to abide by our [code of conduct](CODE_OF_CONDUCT.md). ### Who Should Contribute? @@ -20,56 +12,34 @@ Contributions to this lesson are welcome from anyone with an interest in the pro ### How to Contribute -The easiest way to get started is to file an issue to tell us about a spelling -mistake, some awkward wording, or a factual error. This is a good way to -introduce yourself and to meet some of our community members. +The easiest way to get started is to file an issue to tell us about a spelling mistake, some awkward wording, or a factual error. This is a good way to introduce yourself and to meet some of our community members. -1. If you have a [GitHub][github] account, or are willing to [create - one][github-join], but do not know how to use Git, you can report problems - or suggest improvements by [creating an issue][issues]. This allows us to - assign the item to someone and to respond to it in a threaded discussion. +1. If you have a [GitHub][github] account, or are willing to [create one][github-join], but do not know how to use Git, you can report problems or suggest improvements by [creating an issue][issues]. This allows us to assign the item to someone and to respond to it in a threaded discussion. -2. If you are comfortable with Git, and would like to add or change material, - you can submit a pull request (PR). Instructions for doing this are - [included below](#using-github). +2. If you are comfortable with Git, and would like to add or change material, you can submit a pull request (PR). Instructions for doing this are [included below](#using-github). -3. If you do not have a [GitHub][github] account, you can [send us comments by - email][contact]. However, we will be able to respond more quickly if you use - one of the other methods described below. +3. If you do not have a [GitHub][github] account, you can [send us comments by email][contact]. However, we will be able to respond more quickly if you use one of the other methods described below. -Note: if you want to build the website locally, please refer to [The Workbench -documentation][template-doc]. +Note: if you want to build the website locally, please refer to [The Workbench documentation][template-doc]. ### Where to Contribute 1. If you wish to change this lesson, add issues and pull requests in this repository. -2. If you wish to change the template used for workshop websites, please refer - to [The Workbench documentation][template-doc]. +2. If you wish to change the template used for workshop websites, please refer to [The Workbench documentation][template-doc]. ### What to Contribute (General) -There are many ways to contribute, from writing new exercises and improving -existing ones to updating or filling in the documentation and submitting [bug -reports][issues] about things that do not work, are not clear, or are missing. -If you are looking for ideas, please see [the list of issues for this -repository][repo], or the issues for [Data Carpentry][dc-issues], [Library -Carpentry][lc-issues], and [Software Carpentry][swc-issues] projects. +There are many ways to contribute, from writing new exercises and improving existing ones to updating or filling in the documentation and submitting [bug reports][issues] about things that do not work, are not clear, or are missing. If you are looking for ideas, please see [the list of issues for this repository][repo], or the issues for [Data Carpentry][dc-issues], [Library Carpentry][lc-issues], and [Software Carpentry][swc-issues] projects. -Comments on issues and reviews of pull requests are just as welcome: we are -smarter together than we are on our own. **Reviews from novices and newcomers -are particularly valuable**: it's easy for people who have been using these -lessons for a while to forget how impenetrable some of this material can be, so -fresh eyes are always welcome. +Comments on issues and reviews of pull requests are just as welcome: we are smarter together than we are on our own. **Reviews from novices and newcomers are particularly valuable**: it's easy for people who have been using these lessons for a while to forget how impenetrable some of this material can be, so fresh eyes are always welcome. ### What to Contribute (This Lesson) Any contributions are welcome, however major contributions should focus on the current development stage. -If you plan to submit a pull request, please open an issue -(or comment on an existing thread) first to ensure that effort is not duplicated -or spent making a change that will not be accepted by the Maintainers. +If you plan to submit a pull request, please open an issue (or comment on an existing thread) first to ensure that effort is not duplicated or spent making a change that will not be accepted by the Maintainers. #### Excercise contribution @@ -85,15 +55,10 @@ If you want to contribute with an excercise content: #### Content / style guidelines -- If you add an image / figure that was generated from Python code, please include this - code in your PR under `episodes/fig/source`. +- If you add an image / figure that was generated from Python code, please include this code in your PR under `episodes/fig/source`. - If you add a new image or figure, verify that it displays correctly in the lesson’s dark mode. A color-inversion filter is applied [by Varnish to all images by default in dark mode](https://github.com/carpentries/varnish/issues/181), which may cause some images to appear incorrectly or become unreadable. If your image is affected, include an additional version of the same image with a `-dark` suffix in its filename. - -- Use the terms in the table below, when referring to Python libraries within the lesson. - The table gives two terms for each library: `Term for descriptive text` which should be - used when discussing the library in plain English / full sentences and `Term for code` - which should be used when referring to code (and within code). +- Use the terms in the table below, when referring to Python libraries within the lesson. The table gives two terms for each library: `Term for descriptive text` which should be used when discussing the library in plain English / full sentences and `Term for code` which should be used when referring to code (and within code). | Python library | Term for descriptive text | Term for code | | :------------- | :------------- | :------------- | @@ -115,8 +80,7 @@ If you want to contribute with an excercise content: rr, cc = ski.draw.rectangle(start=(357, 44), end=(740, 720)) ``` -- For reading and writing images, use the [BioIO](https://github.com/bioio-devs/bioio) - library and avoid use of other libraries. For example: +- For reading and writing images, use the [BioIO](https://github.com/bioio-devs/bioio) library and avoid use of other libraries. For example: ```python from bioio import BioImage @@ -136,61 +100,38 @@ If you want to contribute with an excercise content: We are not looking for contributions falling outside of the defined [Learning Objectives](https://github.com/carpentries-incubator/bioimage-analysis-python/wiki/Learning-Objectives). -We are also not looking for material that only runs on one -platform. Our workshops typically contain a mixture of Windows, macOS, and -Linux users; in order to be usable, our lessons must run equally well on all -three. +We are also not looking for material that only runs on one platform. Our workshops typically contain a mixture of Windows, macOS, and Linux users; in order to be usable, our lessons must run equally well on all three. ### What *Not* to Contribute (This Lesson) -If you want to suggest the addition of new content, especially whole new sections or episodes, -please open an issue to discuss this with the Maintainers first and provide the following -information alongside a summary of the content to be added: +If you want to suggest the addition of new content, especially whole new sections or episodes, please open an issue to discuss this with the Maintainers first and provide the following information alongside a summary of the content to be added: 1. A suggested location for the new content. -2. An estimate of how much time you estimate the new content would require in training - (teaching + exercises). +2. An estimate of how much time you estimate the new content would require in training (teaching + exercises). 3. The [learning objective(s)][cldt-lo] of this new content. -4. (optional, but strongly preferred) - A suggestion of which of the currently-used learning objectives could be - removed from the curriculum to make space for the new content. +4. (optional, but strongly preferred) A suggestion of which of the currently-used learning objectives could be removed from the curriculum to make space for the new content. ### Using GitHub -If you choose to contribute via GitHub, you may want to look at [How to -Contribute to an Open Source Project on GitHub][how-contribute]. In brief, we -use [GitHub flow][github-flow] to manage changes: +If you choose to contribute via GitHub, you may want to look at [How to Contribute to an Open Source Project on GitHub][how-contribute]. In brief, we use [GitHub flow][github-flow] to manage changes: -1. Create a new branch in your desktop copy of this repository for each - significant change. +1. Create a new branch in your desktop copy of this repository for each significant change. 2. Commit the change in that branch. 3. Push that branch to your fork of this repository on GitHub. 4. Submit a pull request from that branch to the [upstream repository][repo]. -5. If you receive feedback, make changes on your desktop and push to your - branch on GitHub: the pull request will update automatically. +5. If you receive feedback, make changes on your desktop and push to your branch on GitHub: the pull request will update automatically. NB: The published copy of the lesson is usually in the `main` branch. -Each lesson has a team of maintainers who review issues and pull requests or -encourage others to do so. The maintainers are community volunteers, and have -final say over what gets merged into the lesson. +Each lesson has a team of maintainers who review issues and pull requests or encourage others to do so. The maintainers are community volunteers, and have final say over what gets merged into the lesson. #### Merging Policy -Pull requests made to the default branch of this repository -(from which the lesson site is built) -can only be merged after at least one approving review from a Maintainer. -Any Maintainer can merge a pull request that has received at least one approval, -but they may prefer to wait for further input from other curriculum developers before merging. +Pull requests made to the default branch of this repository (from which the lesson site is built) can only be merged after at least one approving review from a Maintainer. Any Maintainer can merge a pull request that has received at least one approval, but they may prefer to wait for further input from other curriculum developers before merging. ### Other Resources -The Carpentries is a global organisation with volunteers and learners all over -the world. We share values of inclusivity and a passion for sharing knowledge, -teaching and learning. There are several ways to connect with The Carpentries -community listed at including via social -media, slack, newsletters, and email lists. You can also [reach us by -email][contact]. +The Carpentries is a global organisation with volunteers and learners all over the world. We share values of inclusivity and a passion for sharing knowledge, teaching and learning. There are several ways to connect with The Carpentries community listed at including via social media, slack, newsletters, and email lists. You can also [reach us by email][contact]. [repo]: https://github.com/carpentries-incubator/bioimage-analysis-python [cldt-lo]: https://carpentries.github.io/lesson-development-training/05-objectives.html#learning-objectives diff --git a/README.md b/README.md index f1406fa..ee374cb 100644 --- a/README.md +++ b/README.md @@ -16,9 +16,7 @@ Make a suggestion or correct an error by [raising an Issue](https://github.com/c We are currently in the pre-alpha phase and are actively developing [the learning outcomes assessment](https://carpentries.github.io/lesson-development-training/fig/cldt-design-process.svg). Although all suggestions are welcome, major contributions should be focused on the current development phase. -Please see the [CONTRIBUTING.md file](CONTRIBUTING.md) for contributing guidelines and details on how to get involved with -this project. Some specific guidelines for content / style are provided in the -['What to Contribute (This Lesson)' section](CONTRIBUTING.md#what-to-contribute-this-lesson). +Please see the [CONTRIBUTING.md file](CONTRIBUTING.md) for contributing guidelines and details on how to get involved with this project. Some specific guidelines for content / style are provided in the ['What to Contribute (This Lesson)' section](CONTRIBUTING.md#what-to-contribute-this-lesson). ## Code of Conduct @@ -34,6 +32,7 @@ The Bio-Image Analysis with Python lesson is currently being maintained by: The lesson is built on the original [Image Processing with Python](https://github.com/datacarpentry/image-processing) lesson content originally developed by [Mark Meysenburg](https://github.com/mmeysenburg), [Tessa Durham Brooks](https://github.com/tessalea), [Dominik Kutra](https://github.com/k-dominik), [Constantin Pape](https://github.com/constantinpape), and [Erin Becker](https://github.com/ebecker). ## Acknowledgements + ![](https://avatars.githubusercontent.com/u/165169315?s=200&v=4) This lesson became a reality thanks to the many priceless contributions of the [GloBIAS expert community](https://www.globias.org/home). Learn [here](https://www.globias.org/activities/update-the-data-carpentries-bioimage-analysis-with-python-curriculum) how the whole initative started. diff --git a/index.md b/index.md index d4bcd4e..dca4dcb 100644 --- a/index.md +++ b/index.md @@ -18,15 +18,12 @@ This lesson became a reality thanks to the many priceless contributions of the [ ## Prerequisites -This lesson assumes you have a working knowledge of Python and some previous exposure to the Bash shell. -These requirements can be fulfilled by: +This lesson assumes you have a working knowledge of Python and some previous exposure to the Bash shell. These requirements can be fulfilled by: a) completing a Software Carpentry Python workshop **or** b) completing a Data Carpentry Ecology workshop (with Python) **and** a Data Carpentry Genomics workshop **or** c) independent exposure to both Python and the Bash shell. -If you're unsure whether you have enough experience to participate in this workshop, please read over -[this detailed list](learners/prereqs.md), which gives all of the functions, operators, and other concepts you will need -to be familiar with. +If you're unsure whether you have enough experience to participate in this workshop, please read over [this detailed list](learners/prereqs.md), which gives all of the functions, operators, and other concepts you will need to be familiar with. :::::::::::::::::::::::::::::::::::::::::::::::::: diff --git a/instructors/instructor-notes.md b/instructors/instructor-notes.md index c7884b3..03978b9 100644 --- a/instructors/instructor-notes.md +++ b/instructors/instructor-notes.md @@ -4,16 +4,9 @@ title: Instructor Notes ## Estimated Timings -This is a relatively new curriculum. -The estimated timings for each episode are based on limited experience -and should be taken as a rough guide only. -If you teach the curriculum, -the Maintainers would be delighted to receive feedback with -information about the time that was required -for teaching and exercises in each episode of your workshop. +This is a relatively new curriculum. The estimated timings for each episode are based on limited experience and should be taken as a rough guide only. If you teach the curriculum, the Maintainers would be delighted to receive feedback with information about the time that was required for teaching and exercises in each episode of your workshop. -Please [open an issue on the repository](https://github.com/datacarpentry/image-processing/issues/new/choose) -to share your experience with the lesson Maintainers. +Please [open an issue on the repository](https://github.com/datacarpentry/image-processing/issues/new/choose) to share your experience with the lesson Maintainers. ## Working with Jupyter notebooks @@ -42,7 +35,6 @@ to share your experience with the lesson Maintainers. - [Cheat-sheet HTML for viewing in browser](../episodes/files/cheatsheet.html). - [PDF version for printing](../episodes/files/cheatsheet.pdf). - ## Questions from Learners ### Q: Where would I find out that coordinates are `x,y` not `r,c`? @@ -55,8 +47,7 @@ A: It is a large image. ### Q: Are the coordinates represented `x,y` or `r,c` in the code (e.g. in `array.shape`)? -A: Always `r,c` with numpy arrays, unless clearly specified otherwise - only represented `x,y` when image is displayed by a viewer. -Take home is don't rely on it - always check! +A: Always `r,c` with numpy arrays, unless clearly specified otherwise - only represented `x,y` when image is displayed by a viewer. Take home is don't rely on it - always check! ### Q: What if I want to increase size? How does `skimage` upsample? (image resizing) diff --git a/learners/discuss.md b/learners/discuss.md index e42fbaf..44aecd9 100644 --- a/learners/discuss.md +++ b/learners/discuss.md @@ -4,37 +4,14 @@ title: Discussion ## Choice of Image Processing Library -This lesson was originally designed to use [OpenCV](https://opencv.org/) -and the [`opencv-python`](https://pypi.org/project/opencv-python/) -library ([see the last version of the lesson repository to use -OpenCV](https://github.com/datacarpentry/image-processing/tree/770a2416fb5c6bd5a4b8e728b3e338667e47b0ed)). +This lesson was originally designed to use [OpenCV](https://opencv.org/) and the [`opencv-python`](https://pypi.org/project/opencv-python/) library ([see the last version of the lesson repository to use OpenCV](https://github.com/datacarpentry/image-processing/tree/770a2416fb5c6bd5a4b8e728b3e338667e47b0ed)). -In 2019-2020 the lesson was adapted to use -[scikit-image](https://scikit-image.org/), as this library has proven -easier to install and enjoys more extensive documentation and support. +In 2019-2020 the lesson was adapted to use [scikit-image](https://scikit-image.org/), as this library has proven easier to install and enjoys more extensive documentation and support. ## Choice of Image Viewer -When the lesson was first adapted to use sckikit-image (see above), -`skimage.viewer.ImageViewer` was used to inspect images. [This viewer -is deprecated](https://scikit-image.org/docs/stable/user_guide/visualization.html) -and the lesson maintainers chose to leverage `matplotlib.pyplot.imshow` -with the pan/zoom and mouse-location tools built into the [Matplotlib -GUI](https://matplotlib.org/stable/users/interactive.html). The -[`ipympl` package](https://github.com/matplotlib/ipympl) is required -to enable the interactive features of Matplotlib in Jupyter notebooks -and in Jupyter Lab. This package is included in the setup -instructions, and the backend can be enabled using the `%matplotlib widget` magic. +When the lesson was first adapted to use sckikit-image (see above), `skimage.viewer.ImageViewer` was used to inspect images. [This viewer is deprecated](https://scikit-image.org/docs/stable/user_guide/visualization.html) and the lesson maintainers chose to leverage `matplotlib.pyplot.imshow` with the pan/zoom and mouse-location tools built into the [Matplotlib GUI](https://matplotlib.org/stable/users/interactive.html). The [`ipympl` package](https://github.com/matplotlib/ipympl) is required to enable the interactive features of Matplotlib in Jupyter notebooks and in Jupyter Lab. This package is included in the setup instructions, and the backend can be enabled using the `%matplotlib widget` magic. -The maintainers discussed the possibility of using [napari](https://napari.org/) -as an image viewer in the lesson, acknowledging its growing popularity -and some of the advantages it holds over the Matplotlib-based -approach, especially for working with image data in more than two -dimensions. However, at the time of discussion, napari was still in -an alpha state of development, and could not be relied on for easy and -error-free installation on all operating systems, which makes it less -well-suited to use in an official Data Carpentry curriculum. +The maintainers discussed the possibility of using [napari](https://napari.org/) as an image viewer in the lesson, acknowledging its growing popularity and some of the advantages it holds over the Matplotlib-based approach, especially for working with image data in more than two dimensions. However, at the time of discussion, napari was still in an alpha state of development, and could not be relied on for easy and error-free installation on all operating systems, which makes it less well-suited to use in an official Data Carpentry curriculum. -The lesson Maintainers and/or Curriculum Advisory Committee (when it -exists) will monitor the progress of napari and other image viewers, -and may opt to adopt a new platform in future. +The lesson Maintainers and/or Curriculum Advisory Committee (when it exists) will monitor the progress of napari and other image viewers, and may opt to adopt a new platform in future. diff --git a/learners/prereqs.md b/learners/prereqs.md index 1a5043d..25790c4 100644 --- a/learners/prereqs.md +++ b/learners/prereqs.md @@ -12,9 +12,7 @@ These requirements can be fulfilled by: ### Bash shell skills -The skill set listed below is covered in any Software Carpentry workshop, as well -as in Data Carpentry's Genomics workshop. These skills can also be learned -through coursework or independent learning. +The skill set listed below is covered in any Software Carpentry workshop, as well as in Data Carpentry's Genomics workshop. These skills can also be learned through coursework or independent learning. Be able to: @@ -25,9 +23,7 @@ Be able to: ### Python skills -This skill set listed below is covered in both Software Carpentry's Python workshop and -in Data Carpentry's Ecology workshop with Python. These skills can also be learned -through coursework or independent learning. +This skill set listed below is covered in both Software Carpentry's Python workshop and in Data Carpentry's Ecology workshop with Python. These skills can also be learned through coursework or independent learning. Be able to: @@ -49,5 +45,4 @@ The following skills are useful, but not required: - Apply a function to an entire NumPy array or to a single array axis. - Write a user-defined function. -If you are signed up, or considering signing up for a workshop, and aren't sure whether you meet these reqirements, please -get in touch with the workshop instructors or host. +If you are signed up, or considering signing up for a workshop, and aren't sure whether you meet these reqirements, please get in touch with the workshop instructors or host. diff --git a/learners/setup.md b/learners/setup.md index 43f49f2..232e790 100644 --- a/learners/setup.md +++ b/learners/setup.md @@ -7,21 +7,12 @@ Before joining the workshop or following the lesson, please complete the data an ## Data -The example images and a description of the Python environment used in this lesson are available on [FigShare](https://figshare.com/). -To download the data, please visit [the dataset page for this workshop][figshare-data] -and click the "Download all" button. -Unzip the downloaded file, and save the contents as a folder called `data` somewhere you will easily find it again, -e.g. your Desktop or a folder you have created for using in this workshop. -(The name `data` is optional but recommended, as this is the name we will use to refer to the folder throughout the lesson.) +The example images and a description of the Python environment used in this lesson are available on [FigShare](https://figshare.com/). To download the data, please visit [the dataset page for this workshop][figshare-data] and click the "Download all" button. Unzip the downloaded file, and save the contents as a folder called `data` somewhere you will easily find it again, e.g. your Desktop or a folder you have created for using in this workshop. (The name `data` is optional but recommended, as this is the name we will use to refer to the folder throughout the lesson.) ## Software -1. Download and install the latest [Miniforge distribution of Python](https://conda-forge.org/download/) for your operating system. - ([See more detailed instructions from The Carpentries](https://carpentries.github.io/workshop-template/#python-1).) - If you already have a Python 3 setup that you are happy with, you can continue to use that (we recommend that you make sure your Python version is current). - The next step assumes that `conda` is available to manage your Python environment. -2. Set up an environment to work in during the lesson. - In a terminal (Linux/Mac) or the MiniForge Prompt application (Windows), navigate to the location where you saved the unzipped data for the lesson and run the following command: +1. Download and install the latest [Miniforge distribution of Python](https://conda-forge.org/download/) for your operating system. ([See more detailed instructions from The Carpentries](https://carpentries.github.io/workshop-template/#python-1).) If you already have a Python 3 setup that you are happy with, you can continue to use that (we recommend that you make sure your Python version is current). The next step assumes that `conda` is available to manage your Python environment. +2. Set up an environment to work in during the lesson. In a terminal (Linux/Mac) or the MiniForge Prompt application (Windows), navigate to the location where you saved the unzipped data for the lesson and run the following command: ```bash conda env create -f environment.yml @@ -38,9 +29,7 @@ e.g. your Desktop or a folder you have created for using in this workshop. ## Enabling the `ipympl` backend in Jupyter notebooks - The `ipympl` backend can be enabled with the `%matplotlib` Jupyter - magic. Put the following command in a cell in your notebooks - (e.g., at the top) and execute the cell before any plotting commands. + The `ipympl` backend can be enabled with the `%matplotlib` Jupyter magic. Put the following command in a cell in your notebooks (e.g., at the top) and execute the cell before any plotting commands. ```python %matplotlib widget @@ -52,11 +41,7 @@ e.g. your Desktop or a folder you have created for using in this workshop. ## Older JupyterLab versions - If you are using an older version of JupyterLab, you may also need - to install the labextensions manually, as explained in the [README - file](https://github.com/matplotlib/ipympl#readme) for the `ipympl` - package. - + If you are using an older version of JupyterLab, you may also need to install the labextensions manually, as explained in the [README file](https://github.com/matplotlib/ipympl#readme) for the `ipympl` package. :::::::::::::::::::::::::::::::::::::::::::::::::: @@ -75,15 +60,12 @@ e.g. your Desktop or a folder you have created for using in this workshop. ## Instructions for Windows - Launch the Miniforge Prompt program and type `jupyter lab`. - (Running this command on the standard Command Prompt will return an error: - `'jupyter' is not recognized as an internal or external command, operable program or batch file.`) + Launch the Miniforge Prompt program and type `jupyter lab`. (Running this command on the standard Command Prompt will return an error: `'jupyter' is not recognized as an internal or external command, operable program or batch file.`) ::::::::::::::::::::::::: - After Jupyter Lab has launched, click the "Python 3" button under "Notebook" in the launcher window, - or use the "File" menu, to open a new Python 3 notebook. + After Jupyter Lab has launched, click the "Python 3" button under "Notebook" in the launcher window, or use the "File" menu, to open a new Python 3 notebook. 4. To test your environment, run the following lines in a cell of the notebook: @@ -112,20 +94,10 @@ e.g. your Desktop or a folder you have created for using in this workshop. ## Running Cells in a Notebook - ![](fig/jupyter_overview.png){alt='Overview of the Jupyter Notebook graphical user interface'} - To run Python code in a Jupyter notebook cell, click on a cell in the notebook - (or add a new one by clicking the `+` button in the toolbar), - make sure that the cell type is set to "Code" (check the dropdown in the toolbar), - and add the Python code in that cell. - After you have added the code, - you can run the cell by selecting "Run" -> "Run selected cell" in the top menu, - or pressing Shift\+Enter. - + ![](fig/jupyter_overview.png){alt='Overview of the Jupyter Notebook graphical user interface'} To run Python code in a Jupyter notebook cell, click on a cell in the notebook (or add a new one by clicking the `+` button in the toolbar), make sure that the cell type is set to "Code" (check the dropdown in the toolbar), and add the Python code in that cell. After you have added the code, you can run the cell by selecting "Run" -> "Run selected cell" in the top menu, or pressing Shift\+Enter. ::::::::::::::::::::::::: -5. A small number of exercises will require you to run commands in a terminal. Windows users should -use PowerShell for this. PowerShell is probably installed by default but if not you should -[download and install](https://apps.microsoft.com/detail/9MZ1SNWT0N5D?hl=en-eg&gl=EG) it. +5. A small number of exercises will require you to run commands in a terminal. Windows users should use PowerShell for this. PowerShell is probably installed by default but if not you should [download and install](https://apps.microsoft.com/detail/9MZ1SNWT0N5D?hl=en-eg&gl=EG) it. [figshare-data]: https://figshare.com/articles/dataset/Data_Carpentry_Image_Processing_Data_beta_/19260677