docs: write morphology methods of image class

EscapedGibbon · stropitek · commit beebf623785a · 2023-10-13T09:19:25.000+02:00
diff --git a/docs/API reference/Image/Morphology/Dilate.md b/docs/API reference/Image/Morphology/Dilate.md
@@ -2,7 +2,7 @@ import DilateDemo from './dilate.demo.tsx'
 
 [Check options and parameters of dilate method](https://image-js.github.io/image-js-typescript/classes/Image.html#resize 'github.io link')
 
-[Dilation](<https://en.wikipedia.org/wiki/Dilation_(morphology)> 'wikipedia link on dilation') is a fundamental morphological operation in image processing that is used to expand the size of foreground objects (regions of interest) within an image while preserving their shape and structure. It involves moving a structuring element (also known as a kernel) over the image and replacing each pixel with the maximum value of the pixels covered by the structuring element. Dilation is commonly used for tasks like noise reduction, object enlargement, and feature enhancement.
+[Dilation](<https://en.wikipedia.org/wiki/Dilation_(morphology)> 'wikipedia link on dilation') is a fundamental morphological operation in image processing that is used to expand the size of foreground objects ([regions of interest](../../../Glossary.md#roiregion-of-interest 'internal link on region of interest')) within an image while preserving their shape and structure. It involves moving a structuring element (also known as a [kernel](../../../Glossary.md#kernel 'internal link on kernel')) over the image and replacing each pixel with the **maximum** value of the pixels covered by the structuring element. Dilation is commonly used for tasks like noise reduction, object enlargement, and feature enhancement.
 
 <DilateDemo />
 
diff --git a/docs/API reference/Image/Morphology/Erode.md b/docs/API reference/Image/Morphology/Erode.md
@@ -2,7 +2,7 @@ import ErodeDemo from './erode.demo.tsx'
 
 [Check options and parameters of erode method](https://image-js.github.io/image-js-typescript/classes/Image.html#erode 'github.io link')
 
-[Erosion](https://en.wikipedia.org/wiki/Erosion 'wikipedia link on erosion') is a fundamental morphological operation in image processing that is used to reduce the size of foreground objects ([regions of interest](../../../Glossary.md#roiregion-of-interest 'internal link on region of interest')) within an image while preserving their shape and structure. It works by moving a structuring element (also known as a [kernel](../../../Glossary.md#kernel 'internal link on kernel')) over the image and replacing each pixel with the minimum value of the pixels covered by the structuring element. Erosion is particularly useful for tasks like noise reduction, edge detection, and object separation.
+[Erosion](https://en.wikipedia.org/wiki/Erosion 'wikipedia link on erosion') is a fundamental morphological operation in image processing that is used to reduce the size of foreground objects ([regions of interest](../../../Glossary.md#roiregion-of-interest 'internal link on region of interest')) within an image while preserving their shape and structure. It works by moving a structuring element (also known as a [kernel](../../../Glossary.md#kernel 'internal link on kernel')) over the image and replacing each pixel with the **minimum** value of the pixels covered by the structuring element. Erosion is particularly useful for tasks like noise reduction, edge detection, and object separation.
 
 <ErodeDemo />
 
diff --git a/docs/API reference/Image/Morphology/Morphology.md b/docs/API reference/Image/Morphology/Morphology.md
@@ -8,6 +8,10 @@ Morphological operations are simple yet powerful tools that play a significant r
 
 ## Core concepts
 
+There are two main processes in morphology:
+
 - [Erode](Erode.md 'internal link on erode')
 
 - [Dilate](Dilate.md 'internal link on dilate')
+
+These two operations are the foundation of most of the morphological operation that ImageJs possesses.
diff --git a/docs/API reference/Image/Morphology/bottomHat.demo.tsx b/docs/API reference/Image/Morphology/bottomHat.demo.tsx
@@ -0,0 +1,14 @@
+import { Image } from 'image-js';
+
+export default function bottomHat(image: Image) {
+  image = image.grey();
+  return image.bottomHat({
+    kernel: [
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+    ],
+  });
+}
diff --git a/docs/API reference/Image/Morphology/bottomHat.md b/docs/API reference/Image/Morphology/bottomHat.md
@@ -0,0 +1,17 @@
+import BottomHatDemo from './bottomHat.demo.tsx'
+
+Similarly to [topHat](./topHat.md 'internal link to top hat'), [bottom hat](https://en.wikipedia.org/wiki/Top-hat_transform 'wikipedia link to top hat') operation computes the difference between two images. However, if top hat was using [opening method](./open.md 'internal link on open method'), bottom hat is using [closing method](./close.md 'internal link on close method').
+The purpose of bottom hat(or, as it is also called, _black-hat_) is to enhance and extract **darker** regions of the image.
+
+<BottomHatDemo />
+
+### Parameters and default values
+
+- `options`
+
+#### Options
+
+| Property                                                                                                   | Required | Default value                     |
+| ---------------------------------------------------------------------------------------------------------- | -------- | --------------------------------- |
+| [`iterations`](https://image-js.github.io/image-js-typescript/interfaces/BottomHatOptions.html#iterations) | no       | `1`                               |
+| [`kernel`](https://image-js.github.io/image-js-typescript/interfaces/BottomHatOptions.html#kernel)         | no       | `[[1, 1, 1],[1, 1, 1],[1, 1, 1]]` |
diff --git a/docs/API reference/Image/Morphology/cannyEdgeDetector.demo.tsx b/docs/API reference/Image/Morphology/cannyEdgeDetector.demo.tsx
@@ -0,0 +1,6 @@
+import { Image } from 'image-js';
+
+export default function cannyEdgeDetector(image: Image) {
+  image = image.grey();
+  return image.cannyEdgeDetector();
+}
diff --git a/docs/API reference/Image/Morphology/cannyEdgeDetector.md b/docs/API reference/Image/Morphology/cannyEdgeDetector.md
@@ -0,0 +1,54 @@
+import CannyEdgeDemo from './cannyEdgeDetector.demo.tsx'
+
+[Check options and parameters of cannyEdgeDetector method](https://image-js.github.io/image-js-typescript/classes/Image.html#cannyEdgeDetector 'github.io link')
+
+The Canny edge detector is a popular and widely used image processing technique for detecting edges in images. It is widely used in computer vision, image processing, and various applications such as object recognition, image segmentation, and feature extraction due to its ability to accurately detect edges and suppress noise.
+
+The Canny edge detector is known for its ability to:
+
+- Detect edges with good localization (i.e., edges are thin and located precisely).
+- Suppress noise due to the Gaussian smoothing.
+- Handle edges with varying levels of intensity (gradient).
+- Allow for customization through the selection of appropriate threshold values.
+
+<CannyEdgeDemo />
+
+### Parameters and default values
+
+- `options`
+
+#### Options
+
+| Property                                                                                                                     | Required | Default value |
+| ---------------------------------------------------------------------------------------------------------------------------- | -------- | ------------- |
+| [`gaussianBlurOptions`](https://image-js.github.io/image-js-typescript/interfaces/CannyEdgeOptions.html#gaussianBlurOptions) | no       | `1`           |
+| [`highThreshold`](https://image-js.github.io/image-js-typescript/interfaces/CannyEdgeOptions.html#highThreshold)             | no       | `0.1`         |
+| [`lowThreshold`](https://image-js.github.io/image-js-typescript/interfaces/CannyEdgeOptions.html#hysteresis)                 | no       | `0.04`        |
+| [`hysteresis`](https://image-js.github.io/image-js-typescript/interfaces/CannyEdgeOptions.html#hysteresis)                   | no       | `true`        |
+| [`out`](https://image-js.github.io/image-js-typescript/interfaces/CannyEdgeOptions.html#hysteresis)                          | no       | -             |
+
+<details>
+<summary>
+<b>Implementation</b>
+ </summary>
+The Canny edge detector consists of several stages:
+
+_Smoothing_: The first step involves applying a Gaussian filter to the input image. This helps reduce noise and smooth out small variations in pixel values.
+
+_Gradient Calculation_: After smoothing, the gradient of the image is calculated using convolution with Sobel masks in both the horizontal and vertical directions. This step highlights regions of rapid intensity change in the image.
+
+_Non-maximum Suppression_: In this step, the gradient magnitude is examined at each pixel location, and non-maximum values are suppressed. This means that only the local maxima in gradient magnitude are retained, which helps thinning the edges and keeping only the most prominent ones.
+
+**(optional)**
+
+_Edge Tracking by [Hysteresis](../../../Glossary.md#hysteresis "internal link on hysteresis)_: This step involves tracking edges by applying two thresholds: a high threshold and a low threshold. Pixels with gradient magnitude values above the high threshold are considered strong edges, while those between the low and high thresholds are considered potential edges. The algorithm then connects potential edges to strong edges, forming continuous edge contours.
+
+Finally, edge tracking by hysteresis is performed to link weak edges to strong edges. This helps in forming continuous edges and eliminating isolated weak edges caused by noise.
+
+The output of the Canny edge detector is a binary image(mask) where edges are represented as white lines.
+
+</details>
+
+:::info
+The choice of threshold values for the high and low thresholds can affect the performance of the Canny edge detector and may need to be adjusted depending on the specific application and the characteristics of the input image.
+:::
diff --git a/docs/API reference/Image/Morphology/close.demo.tsx b/docs/API reference/Image/Morphology/close.demo.tsx
@@ -0,0 +1,14 @@
+import { Image } from 'image-js';
+
+export default function close(image: Image) {
+  image = image.grey();
+  return image.close({
+    kernel: [
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+    ],
+  });
+}
diff --git a/docs/API reference/Image/Morphology/close.md b/docs/API reference/Image/Morphology/close.md
@@ -0,0 +1,17 @@
+import CloseDemo from './close.demo.tsx'
+
+Opposed to [opening](./open.md 'internal link to open method'), [closing process](<https://en.wikipedia.org/wiki/Closing_(morphology)> 'wikipedia link on closing') first [erodes](./Erode.md 'internal link to erode method') an image and only then [dilates](./Dilate.md 'internal link to dilate method') it.
+It is a useful process for filling small holes in the image, while preserving the shape and size of large holes and objects.
+
+<CloseDemo />
+
+### Parameters and default values
+
+- `options`
+
+#### Options
+
+| Property                                                                                               | Required | Default value                     |
+| ------------------------------------------------------------------------------------------------------ | -------- | --------------------------------- |
+| [`iterations`](https://image-js.github.io/image-js-typescript/interfaces/CloseOptions.html#iterations) | no       | `1`                               |
+| [`kernel`](https://image-js.github.io/image-js-typescript/interfaces/CloseOptions.html#kernel)         | no       | `[[1, 1, 1],[1, 1, 1],[1, 1, 1]]` |
diff --git a/docs/API reference/Image/Morphology/morphologicalGradient.demo.tsx b/docs/API reference/Image/Morphology/morphologicalGradient.demo.tsx
@@ -0,0 +1,6 @@
+import { Image } from 'image-js';
+
+export default function morphologicalGradient(image: Image) {
+  image = image.grey();
+  return image.morphologicalGradient();
+}
diff --git a/docs/API reference/Image/Morphology/morphologicalGradient.md b/docs/API reference/Image/Morphology/morphologicalGradient.md
@@ -0,0 +1,20 @@
+import MorphGradientDemo from './morphologicalGradient.demo.tsx'
+
+[Check options and parameters of morphologicalGradient method](https://image-js.github.io/image-js-typescript/classes/Image.html#morphologicalGradient 'github.io link')
+
+[The morphological gradient](https://en.wikipedia.org/wiki/Morphological_gradient 'wikipedia link on morphological gradient') is a mathematical operation used in image processing and mathematical morphology to highlight the boundaries of objects or regions within an image.
+It is a fundamental concept in morphological image analysis and is often used for tasks such as edge detection and image segmentation.
+The morphological gradient is based on the difference between an image after [dilation](./Dilate.md 'internal link on dilation') and the same image after [erosion](./Erode.md 'intenal link on erosion').
+
+<MorphGradientDemo />
+
+### Parameters and default values
+
+- `options`
+
+#### Options
+
+| Property                                                                                                               | Required | Default value                     |
+| ---------------------------------------------------------------------------------------------------------------------- | -------- | --------------------------------- |
+| [`iterations`](https://image-js.github.io/image-js-typescript/interfaces/MorphologicalGradientOptions.html#iterations) | no       | `1`                               |
+| [`kernel`](https://image-js.github.io/image-js-typescript/interfaces/MorphologicalGradientOptions.html#kernel)         | no       | `[[1, 1, 1],[1, 1, 1],[1, 1, 1]]` |
diff --git a/docs/API reference/Image/Morphology/open.md b/docs/API reference/Image/Morphology/open.md
@@ -1,3 +1,17 @@
 import OpenDemo from './open.demo.tsx'
 
+[Opening](<https://en.wikipedia.org/wiki/Opening_(morphology)#:~:text=In%20mathematical%20morphology%2C%20opening%20is,blue%20square%20with%20round%20corners.&text=denote%20erosion%20and%20dilation%2C%20respectively>) process in morphology involves a dilation of an image, followed by its erosion.
+This process allows removing small objects and thin lines while preserving the shape and size of larger objects.
+
 <OpenDemo />
+
+### Parameters and default values
+
+- `options`
+
+#### Options
+
+| Property                                                                                              | Required | Default value                     |
+| ----------------------------------------------------------------------------------------------------- | -------- | --------------------------------- |
+| [`iterations`](https://image-js.github.io/image-js-typescript/interfaces/OpenOptions.html#iterations) | no       | `1`                               |
+| [`kernel`](https://image-js.github.io/image-js-typescript/interfaces/OpenOptions.html#kernel)         | no       | `[[1, 1, 1],[1, 1, 1],[1, 1, 1]]` |
diff --git a/docs/API reference/Image/Morphology/topHat.demo.tsx b/docs/API reference/Image/Morphology/topHat.demo.tsx
@@ -0,0 +1,14 @@
+import { Image } from 'image-js';
+
+export default function topHat(image: Image) {
+  image = image.grey();
+  return image.topHat({
+    kernel: [
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+      [1, 1, 1, 1, 1],
+    ],
+  });
+}
diff --git a/docs/API reference/Image/Morphology/topHat.md b/docs/API reference/Image/Morphology/topHat.md
@@ -0,0 +1,17 @@
+import TopHatDemo from './topHat.demo.tsx'
+
+In morphology and image processing, [top hat](https://en.wikipedia.org/wiki/Top-hat_transform 'wikipedia link on top hat') is an operation used to enhance or extract small bright regions or details from an image while suppressing the larger surrounding structures.
+It is the result of subtraction between the result of input image [opening](./open.md 'internal link on open method') and the input image itself.
+The purpose of bottom hat(or as it is also called _black-hat_) is to enhance and extract **brighter** regions of the image.
+<TopHatDemo />
+
+### Parameters and default values
+
+- `options`
+
+#### Options
+
+| Property                                                                                                | Required | Default value                     |
+| ------------------------------------------------------------------------------------------------------- | -------- | --------------------------------- |
+| [`iterations`](https://image-js.github.io/image-js-typescript/interfaces/TopHatOptions.html#iterations) | no       | `1`                               |
+| [`kernel`](https://image-js.github.io/image-js-typescript/interfaces/TopHatOptions.html#kernel)         | no       | `[[1, 1, 1],[1, 1, 1],[1, 1, 1]]` |
diff --git a/docs/API reference/Image/dilate.md b/docs/API reference/Image/dilate.md
diff --git a/docs/API reference/Image/erode.md b/docs/API reference/Image/erode.md
diff --git a/docs/Glossary.md b/docs/Glossary.md
@@ -23,6 +23,13 @@ A grey image has 1 component. An RGB image has 3 components.
 
 [Convolution](https://en.wikipedia.org/wiki/Convolution 'wikipedia link on convolution') is a mathematical operation that is widely used in various fields, including image processing, signal processing, and mathematics itself. In the context of image processing, convolution involves sliding a small matrix (filter, kernel, or mask) over an input image and calculating a new value for each pixel by performing a mathematical operation between the values in the filter and the corresponding pixel neighborhood in the image. It is used for tasks such as blurring, sharpening, edge detection, and more.
 
+### Hysteresis
+
+Hysteresis thresholding is a technique used in image processing, particularly in the context of edge detection, to distinguish between strong and weak edges in an image. It is commonly used in edge detection algorithms like the Canny edge detector to improve the detection of continuous edges in noisy images.
+The function takes two binary images that have been thresholded at different levels. The higher threshold has a smaller population of white pixels. The values in the higher threshold are
+more likely to be real edges. In hysteresis, if a value in the larger population is connected to a point in the smaller population, we can assume it is a real edge and add it to
+hysteresis image.
+
 ### Image noise
 
 [Image noise](https://en.wikipedia.org/wiki/Image_noise 'wikipedia link on image noise') refers to random variations in pixel values within an image, which can lead to unwanted visual artifacts and reduced image quality. It is often caused by various factors during image acquisition, transmission, or processing. Image noise can obscure details, reduce contrast, and make it harder to extract meaningful information from an image.
diff --git a/project-words.txt b/project-words.txt
@@ -14,4 +14,5 @@ otsu
 intermodes
 isodata
 renyi
-shanbhag
+shanbhag
+thresholded
