# __`SurfaceDefects`__ Python Package
A simple but powerful Python package capable of
1. `detecting pores` in concrete, steel and similar surafaces, or the `fabrication errors` for that matter.
2. determining the `area` of each pore.
3. calculating `equivalent diameter` of each pore. Equivalent diameter is the diameter of a circle whose area equals that of a pore. More on it later...
4. calculating `surface porosity` i.e., the ratio of area covered by pores to the total area.
5. plotting `circles` over pores once the `equivalent diameters` are determined.
6. assigning length `scale` to image.
It works on the spirit of `Computer Vision` and segmentation. The Python package `SurfaceDefects` classifies surfaces based on the difference in their pixel values. It can also generally be used for detecting contours in 2D images of any type provided they are suitable for the intended purpose.
>## Better images lead to better results!
The concept will develop as we go down the documentation.
## 1. Install `SurfaceDefects`
```
~ pip install SurfaceDefects
```
## 2. Import into the project alongwith `matplotlib.pyplot`
```
import SurfaceDefects as sdf
import matplotlib.pyplot as plt
```
## 3. Load image using `LoadImage()` function
```
img = sdf.LoadImage(path, gray=Fasle)
```
`path`: is the complete path to your image
`gray`: whether to load the image as a grayscale image, default is `False`
>## Tip: Load `img` as it is and another `img_gray` as a graysacle image. You will need both of them later.
## 4. Make a `black` replica of `img` (not compulsory)
```
black = sdf.PseudoImage(img)
```
## 5. Detect pores/defects using `ClassifySurface()` function
```
thresh = sdf.ClassifySurface(img_gray, threshold, invert_color=True)
```
```
plt.imshow(thresh, cmap='gray')
```
`thresh`: the resultant image is better known as _thresholded_ image hence `thresh`
`img_gray`: the original _grayscale_ image
`threshold`: verily the most important parameter, `threshold` is what that controls the detection of pores/defects. Ranges between 0 (black) and 255 (white).
`invert_color`: swaps colors i.e., black to white. Default is `True`
___
>plt's `cmap='gray'` for a grayscale image.
## 6. Find boundary of pores/defects using `FindContours()` function
>Contours are lines joining points of same instensity.
Those points in this case are located along the boundaries of pores.
```
contours, _ = sdf.FindContours(classified_img)
```
`contours`: an `array`
`_`: the `hierarchy` and can be ignored in this particular case.
`classified_img` = `thresh`, the _thresholded_ image.
## 7. `SignificatContours()`
Some of the contours found by `FindContours()` might be insignificant in that their areas might be _zero_. `SignificatContours()` will automatically discard contours whose areas are _zero_.
```
sig_contours, _ = sdf.SignificantContours(classified_img)
```
`sig_contours`: an `array`
`_`: the `hierarchy` and can be ignored in this particular case.
`classified_img` = `thresh`, the _thresholded_ image.
## 8. Define a scale using `DefineScale()` function
```
scale_factor = sdf.Scale(height, width)
```
`scale_factor`: a ratio of scale, or better known as a _Referesentative Factor_
`height`, `width`: height and width of real object/surface in units of length
## 9. Calculate area of pores using `ContourArea()`
```
pore_area = sdf.ContourArea(classified_img, sum=False, scale_factor=1)
```
If `sum`=`True`, total pore area will be calculated; otherwise a `list`.
`scale_factor`: a ratio of scale, or better known as a _Referesentative Factor_. Default value is $1$ which means no conversion from units of pixel to units of length.
## 10. `EquivalentDiameter()` calculates diameter of a circle whose area equals that of a pore
```
equ_dia = sdf.EquivalentDiameter(contours, scale_factor=1)
```
## 11. `DrawContours()` draws boundaries of each pore
```
contour_img = sdf.DrawContours(img,contours, index=-1, color = (0,255,0), thickness=1)
```
```
#display
plt.imshow(contour_img)
```
`img`: original or `black` img
`contours`: `array` from `DrawContours()` or `SignificantContours()`
`index`: which contour boundary to plot? $-1$ means all. Similarly $2, 3, 4$ for number $3$<sup>rd</sup>, $4$<sup>th</sup>, $5$<sup>th</sup> respectively, and so on.
`color`: color of boundary line, default is green.
`thickness`: thickness of boundary line, default is 1.
## 12. `DrawCircles()` draws circle aroud the boundary of `equivalent diameter`
```
circle_img = sdf.DrawCircles(img, contours, color=(0,255,0), thickness=1)
```
```
plt.imshow(circle_img)
```
Refer to point number $11$ for parameters/arguments.
## 13. `Denoise()` smoothens/denoises the original image
```
#applies GaussianBlur filter of opencv-python
denoised_img = sdf.Denoise(img, kernel=(3,3), channels=0)
```
`kernel`: default ($3,3$)
`channels`: $3$ for an RGB/BGR image and $0$ for a grayscale image
## 14. `SurfacePorosity()` calculates the ratio in percentage of area covered by pores to the total area
```
porosity = sdf.SurfacePorosity(img, contour_area)
```
`contour_area`: a float or an integer
_______________________
# Acknowledgement | Dependencies
1. `opencv-python`
2. `numpy`
Raw data
{
"_id": null,
"home_page": "",
"name": "SurfaceDefects",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "",
"keywords": "Computer Vision,Contours,Pores Detection in concrete,Pores Detection in Steel",
"author": "",
"author_email": "Amir Hamza <19pwciv5384@uetpeshawar.edu.pk>",
"download_url": "https://files.pythonhosted.org/packages/17/31/f4807c58bfdff927deaea8634cfde7efa038f9c7e2dac3e5a8d88cb00d1b/SurfaceDefects-1.0.0.tar.gz",
"platform": null,
"description": "# __`SurfaceDefects`__ Python Package\r\nA simple but powerful Python package capable of\r\n 1. `detecting pores` in concrete, steel and similar surafaces, or the `fabrication errors` for that matter. \r\n 2. determining the `area` of each pore.\r\n 3. calculating `equivalent diameter` of each pore. Equivalent diameter is the diameter of a circle whose area equals that of a pore. More on it later...\r\n 4. calculating `surface porosity` i.e., the ratio of area covered by pores to the total area.\r\n 5. plotting `circles` over pores once the `equivalent diameters` are determined.\r\n 6. assigning length `scale` to image. \r\n\r\n\r\n It works on the spirit of `Computer Vision` and segmentation. The Python package `SurfaceDefects` classifies surfaces based on the difference in their pixel values. It can also generally be used for detecting contours in 2D images of any type provided they are suitable for the intended purpose. \r\n\r\n>## Better images lead to better results!\r\n\r\n\r\nThe concept will develop as we go down the documentation.\r\n\r\n## 1. Install `SurfaceDefects`\r\n```\r\n~ pip install SurfaceDefects\r\n```\r\n## 2. Import into the project alongwith `matplotlib.pyplot`\r\n```\r\nimport SurfaceDefects as sdf\r\nimport matplotlib.pyplot as plt\r\n```\r\n## 3. Load image using `LoadImage()` function \r\n```\r\nimg = sdf.LoadImage(path, gray=Fasle) \r\n```\r\n`path`: is the complete path to your image\r\n\r\n`gray`: whether to load the image as a grayscale image, default is `False`\r\n\r\n>## Tip: Load `img` as it is and another `img_gray` as a graysacle image. You will need both of them later. \r\n\r\n## 4. Make a `black` replica of `img` (not compulsory)\r\n```\r\nblack = sdf.PseudoImage(img) \r\n```\r\n## 5. Detect pores/defects using `ClassifySurface()` function\r\n```\r\nthresh = sdf.ClassifySurface(img_gray, threshold, invert_color=True)\r\n```\r\n```\r\nplt.imshow(thresh, cmap='gray')\r\n```\r\n`thresh`: the resultant image is better known as _thresholded_ image hence `thresh`\r\n\r\n`img_gray`: the original _grayscale_ image \r\n\r\n`threshold`: verily the most important parameter, `threshold` is what that controls the detection of pores/defects. Ranges between 0 (black) and 255 (white). \r\n\r\n`invert_color`: swaps colors i.e., black to white. Default is `True`\r\n___\r\n>plt's `cmap='gray'` for a grayscale image.\r\n\r\n\r\n\r\n\r\n## 6. Find boundary of pores/defects using `FindContours()` function\r\n>Contours are lines joining points of same instensity. \r\n\r\nThose points in this case are located along the boundaries of pores. \r\n```\r\ncontours, _ = sdf.FindContours(classified_img)\r\n```\r\n`contours`: an `array` \r\n\r\n`_`: the `hierarchy` and can be ignored in this particular case.\r\n\r\n`classified_img` = `thresh`, the _thresholded_ image.\r\n\r\n## 7. `SignificatContours()` \r\nSome of the contours found by `FindContours()` might be insignificant in that their areas might be _zero_. `SignificatContours()` will automatically discard contours whose areas are _zero_.\r\n```\r\nsig_contours, _ = sdf.SignificantContours(classified_img)\r\n```\r\n`sig_contours`: an `array` \r\n\r\n`_`: the `hierarchy` and can be ignored in this particular case.\r\n\r\n`classified_img` = `thresh`, the _thresholded_ image.\r\n\r\n## 8. Define a scale using `DefineScale()` function\r\n```\r\nscale_factor = sdf.Scale(height, width) \r\n```\r\n`scale_factor`: a ratio of scale, or better known as a _Referesentative Factor_\r\n\r\n`height`, `width`: height and width of real object/surface in units of length \r\n\r\n## 9. Calculate area of pores using `ContourArea()`\r\n```\r\npore_area = sdf.ContourArea(classified_img, sum=False, scale_factor=1)\r\n```\r\nIf `sum`=`True`, total pore area will be calculated; otherwise a `list`. \r\n\r\n`scale_factor`: a ratio of scale, or better known as a _Referesentative Factor_. Default value is $1$ which means no conversion from units of pixel to units of length.\r\n\r\n## 10. `EquivalentDiameter()` calculates diameter of a circle whose area equals that of a pore\r\n\r\n```\r\nequ_dia = sdf.EquivalentDiameter(contours, scale_factor=1)\r\n```\r\n## 11. `DrawContours()` draws boundaries of each pore\r\n```\r\ncontour_img = sdf.DrawContours(img,contours, index=-1, color = (0,255,0), thickness=1)\r\n```\r\n```\r\n#display\r\nplt.imshow(contour_img)\r\n```\r\n`img`: original or `black` img\r\n\r\n`contours`: `array` from `DrawContours()` or `SignificantContours()`\r\n\r\n`index`: which contour boundary to plot? $-1$ means all. Similarly $2, 3, 4$ for number $3$<sup>rd</sup>, $4$<sup>th</sup>, $5$<sup>th</sup> respectively, and so on.\r\n\r\n`color`: color of boundary line, default is green.\r\n\r\n`thickness`: thickness of boundary line, default is 1.\r\n\r\n## 12. `DrawCircles()` draws circle aroud the boundary of `equivalent diameter`\r\n\r\n```\r\ncircle_img = sdf.DrawCircles(img, contours, color=(0,255,0), thickness=1)\r\n```\r\n```\r\nplt.imshow(circle_img)\r\n```\r\nRefer to point number $11$ for parameters/arguments.\r\n\r\n\r\n\r\n\r\n\r\n\r\n## 13. `Denoise()` smoothens/denoises the original image\r\n```\r\n#applies GaussianBlur filter of opencv-python\r\n\r\ndenoised_img = sdf.Denoise(img, kernel=(3,3), channels=0)\r\n```\r\n\r\n`kernel`: default ($3,3$)\r\n\r\n`channels`: $3$ for an RGB/BGR image and $0$ for a grayscale image\r\n\r\n## 14. `SurfacePorosity()` calculates the ratio in percentage of area covered by pores to the total area\r\n\r\n```\r\nporosity = sdf.SurfacePorosity(img, contour_area)\r\n```\r\n`contour_area`: a float or an integer\r\n\r\n_______________________\r\n\r\n# Acknowledgement | Dependencies\r\n1. `opencv-python`\r\n2. `numpy`\r\n",
"bugtrack_url": null,
"license": "",
"summary": "A package for detecting and analysing defects/pores in concrete, steel or similar surfaces.",
"version": "1.0.0",
"split_keywords": [
"computer vision",
"contours",
"pores detection in concrete",
"pores detection in steel"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "831c92d7fe33fcf10f5228a38286122d",
"sha256": "634e74daaf9e1d832a4c7d4e7349b5745e93d6ecdfb7c0df0648cee702bef6aa"
},
"downloads": -1,
"filename": "SurfaceDefects-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "831c92d7fe33fcf10f5228a38286122d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 7131,
"upload_time": "2022-12-14T17:30:23",
"upload_time_iso_8601": "2022-12-14T17:30:23.805672Z",
"url": "https://files.pythonhosted.org/packages/5d/52/23ae6f6d76889777c85fabe7276f7cb9e7aa40767d7e3f963001e8f504fd/SurfaceDefects-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "482662443f3237957277cfa9641f64f6",
"sha256": "a8a0a228b357d163a610471655782632012598f388e0a9c11c0e1d222b5d8739"
},
"downloads": -1,
"filename": "SurfaceDefects-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "482662443f3237957277cfa9641f64f6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 5879,
"upload_time": "2022-12-14T17:30:30",
"upload_time_iso_8601": "2022-12-14T17:30:30.515284Z",
"url": "https://files.pythonhosted.org/packages/17/31/f4807c58bfdff927deaea8634cfde7efa038f9c7e2dac3e5a8d88cb00d1b/SurfaceDefects-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-14 17:30:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "surfacedefects"
}
JSON