Python script to binarize an RGB image and find its mean pixel value.
This script was built for the image processing of the data reported on V. Márquez-Alvarez, J. Amigó-Vega, A. Rivera, A. J. Batista-Leyva, and E. Altshuler, Relative Assessment of Cloth Mask Protection against Ballistic Droplets: A Frugal Approach. PLOS ONE 17, e0275376 (2022). doi: 10.1371/journal.pone.0275376.
Please refer to the article to understand the context, main use case and definition of parameters used in the script.
Sample raw images that can be used to test the script can be found at V. Márquez-Alvarez and E. Altshuler, Raw Images Corresponding to Article “Relative Assessment of Cloth Mask Protection against Ballistic Droplets: A Frugal Approach.” Zenodo (2022). doi: 10.5281/zenodo.6941696".
This script is publicly hosted in this repository to allow the reproduction of the results reported on the article.
Nevertheless, further applications are encouraged.
Here you can find a description of the main files and folders in the repository.
-
main.py Python script that contains the minimum code required to fulfill the script goal.
-
example.ipynb Jupyter Notebook that contains an example using the script. Intermediate plots are included to help understanding each step in the image-preparation and parameter-extraction processes.
-
libs/utils.py Python file containing the utility functions used.
-
requirements.txt Text file containing the version information of the Python libraries used.
-
input Suggested directory to place the image(s) that will be processed by the script.
-
output Directory that contains the binarized image(s) exported by the script.
To use the script you must download the repository files, have Python>=3.9.10 installed as well as the packages included in the 'requirements.txt' file.
If you have Git installed, you can open the terminal, go to the path where you want to download the repository and simply run
git clone https://github.com/vmalv/Binary-Image-Mean-Pixel-Value.git
If you need help installing Git see this link.
If you do not want to install Git, or simply don't want to open a local Git repo, download the repository files using this link
https://github.com/vmalv/Binary-Image-Mean-Pixel-Value/archive/refs/heads/main.zip
and extract the ZIP file in the directory of your preference.
To install Python for the first time, this guide could be useful.
Although we used Python version 3.9.10, the code should run without problems with superior versions.
We recommend using pip to install the required packages --contained in 'requirements.txt'. If you need help installing pip, the official documentation provides a step-by-step guide.
With pip installed, open a terminal in the repository directory and run the following code:
pip install -r requirements.txt
In general terms, the script workflow is as follows:
- Load libraries and image parameters.
- Load raw image.
- Crop raw image.
- Select the RGB component with best stains-background contrast.
- Binarize the RGB component and export it.
- Get the binary image mean pixel value.
It is strongly recommended to see example.ipynb and libs/utils.py for a detailed explanation of each line of the code.
The script itself can be used for any application where it is suited. However, if you are looking to reproduce our results, or make a new research based on ours, further steps are necessary to calculate the BBC parameter for a given blocking material and configuration.
- Run the script for all the raw scanned images corresponding to CONFFREE experiments (experiments made with no cloth at any position). For each one of these experiments you will get a mean pixel value (p). The mean of all p values in CONFFREE corresponds to the parameter <\overline{p_{no}}> (Latex formatting) introduced in the article.
- Suppose you make a set of experiments with a given blocking material in CONF1 (if the experiments were made in CONF2, CONF3 or CONF4 the steps would be identical). Run the script for the set of raw scanned images obtained. You will get the corresponding set of p values. The mean of these p values corresponds to the parameter <\overline{p_{o}}> presented in the article.
- Calculate BBC using the formula (1) from the article.
- For BBC uncertainty, refer to S1 Supporting Information Section C.
In this example you obtain the BBC value of the given blocking material in CONF1. For the rest of configurations and materials, repeat steps from 2 to 4.
If you use this software, please cite both the software and the main article "V. Márquez-Alvarez, J. Amigó-Vega, A. Rivera, A. J. Batista-Leyva, and E. Altshuler, Relative Assessment of Cloth Mask Protection against Ballistic Droplets: A Frugal Approach. PLOS ONE 17, e0275376 (2022). doi: 10.1371/journal.pone.0275376."
All citation metadata can be found at the CITATION file.
Copyright (c) 2022 vmalv, jamigov
The scripts and documentation in this project are released under the MIT License. Please refer to the LICENSE file.