carpentries-incubator / carpentries-incubator/bioimage-analysis-python
Episode 6, Exercise 3 labelling with connected components
- Dominant language
- HTML
- Stars
- 12
- Forks
- 6
- Avg merge
- 1m
- Merged PRs (30d)
- 1
Description
### Brief description
Connected component labelling is a prevalent way to label pixels that could be identified as the same object. To perform such analysis, it is important to define 'connectivity' which pixels are considered direct neighbours of a pixel. I think [neubias's page on connected component](https://neubias.github.io/training-resources/connected_components/index.html) is great to use. It demonstrated 1 and 2 connectivity in both 2D and 3D.
From prior exercises, students now have **binary images** from different thresholding approaches. Briefly, with binary images as input, we use connected components analysis by defining connectivity, producing a label image with separated objects. The exercises use [label function from skimage.measure](https://scikit-image.org/docs/stable/api/skimage.measure.html#skimage.measure.label). `skimage.measure.label(label_image, background=None, return_num=False, connectivity=None)`
Input:
* binary images (typically background and foreground regions)
* We use a small sub-region of a binary image from previous step. (side note: [EPFL course demo-ed the concept with a 6-by-6 made up image](https://biapol.github.io/Image-data-science-with-Python-and-Napari-EPFL2022/day2d_image_segmentation/09_connected_component_labeling.html#connected-component-labeling).
* Students will be able to say how many objects in that region.
2nd step:
* we introduce the concept of connectivity as we need to define which pixels are considered direct neighbours of a pixel. Essentially, do we consider the diagonal pixels as part of the objection x (demo-ed below).
`labels_2D_conn1_image = label(binary_2D_subregion, connectivity=1)`
`labels_2D_conn2_image = label(binary_2D_subregion, connectivity=2)`
* we can use `matplotlib.pyplot.imshow`to visualise them.
* Probably worth mentioning that the label image contain objects (each has its own assigned integer).
```
1-connectivity 2-connectivity
[ ] [ ] [ ] [ ]
| \ | /
[ ]--[x]--[ ] [ ]--[x]--[ ]
| / | \
[ ] [ ] [ ] [ ]
```
We can mention the following equivalent nomenclatures
- 2D: 1 connectivity = 4 connectivity
- 2D: 2 connectivity = 8 connectivity
- 3D: 1 connectivity = 6 connectivity
- 3D: 2 connectivity = 26 connectivity
3rd step:
* to visualise label images by colour coding and overlaying raw data. [skimage.color.label2rgb](Probably worth mentioning that the label image contain objects (each has its own assigned integer).)
`image_label_overlay = label2rgb(labels_2D_conn1_image, image=raw_image, bg_label=0, kind='overlay')`
4th step:
* we can count the number of objects in the label image by len() of the resulting array of `numpy.unique(labels_2D_conn1_image)`
### Learning objective(s)
Covers [Objective Labelling with Connected Components](https://github.com/carpentries-incubator/bioimage-analysis-python/wiki/Learning-Objectives#labeling-with-connected-components).
I think the first two objectives can be achieved by working on (segmented) binary images (2D or 3D) to identify objects by defining connectivity=1 or 2. Less connectivity, one will have more separation; more connectivity will result in more merging of objects.
with label2rgb function, Learners will be able to overlay colour coded labels over desired image (we can define this to be the original image).
### Volunteer(s)
@terezbelinova @marcodallavecchia (Hi again, feel free to add any comments). Thanks
@wangliyuan72
Contributor guide
Research direction
No file path is named in the issue; start with the Episode 6 lesson structure and the preceding thresholding exercises. Use the linked connected-components references to frame the exercise, and consider it complete when learners apply 1- and 2-connectivity to binary images, visualize label overlays, and count the resulting objects.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- matplotlib, numpy, python
- Domain
- computer-vision, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 62/100