Package: plaque-size-tool
Plaque Size Tool User ManualIntroductionPrerequisites installationPython installationPip3 installationPlaque Size Tool installationGitHub archive downloadInstallation using pipPlaque Size Tool usagePlaque Size Tool usage optionsSingle file processingExamplesBatch files processingExampleOutput filesIntroductionPlaque Size Tool is an open-source application written in Python 3 that
is able to detect and measure bacteriophage plaques on a Petri dish
image.The source files are located athttps://github.com/ellinium/plaque_size_tool.The tool can be installed on any operation system supporting Python.The installation guide is provided for two most frequently used OS –
Windows and MacOS.To execute installation commands on Mac use ‘Terminal’ or any other
command line interpreter (CLI) preferred, on Windows use ‘Command
Prompt’ (or any other CLI preferred).The CLI screenshots taken for this manual were made on macOS High Sierra
and Windows 10.Plaque size tool was tested on the Python versions 3.7, 3.8 and 3.9.4,
and if you are experiencing any problems with the higher versions,
please send an email with the error toellina.trofimova@hdr.mq.edu.auor create an issue athttps://github.com/ellinium/plaque_size_tool/issues(requires
registration on GitHub).Prerequisites installationPython 3.6or higher andpip3should be installed on the system.It is possible to test whether they are installed on your OS by
executing a command in Terminal (macOS) or Command Prompt (Windows):MacOS: executepython3 --versionWindows: executepy --versionpip3should be installed on the system.Pip3 is usually already installed on your system if you are using Python
3.6 or higher.To check whether it is installed or not, execute the command ‘pip3’ in
your CLI (the same command is used both for Windows and MacOS).Python installationIf Python3 is not found in your system, please navigate
tohttps://www.python.org/downloads/.On the main page there is a link to the latest version of Python3
depending on your OS.MacOS:Windows:Install the latest version of Python by clicking ‘Download Python
<latest version>’ and running the downloaded package.The detailed instructions for Python download and installation are also
provided athttps://wiki.python.org/moin/BeginnersGuide/Download.After Python installation, check that Python3 and pip3 were installed
properly by executing the same commands as above:MacOS:python3 –-versionpip3Windows:py –-versionpip3Pip3 installationIf Python3 is installed in your system butpip3is missing, it is
possible to install it separately.For that, navigate tohttps://pip.pypa.io/en/stable/installing/and
the section'Installing with get-pip.py'.Execute the following command to download get-pip.py file:MacOS:python3 get-pip.pyWindows:py get-pip.pyIf pip3 is installed but outdated, please upgrade it by executing the
following command:MacOS:python3 -m pip install --upgrade pipWindows:py -m pip install --upgrade pipPlaque Size Tool installationGitHub archive downloadNavigate tohttps://github.com/ellinium/plaque_size_tool. After that,
click the green button 'Code' in the right corner and select the option
'Download Zip'.The archive called ‘plaque_size_tool-main.zip’ will be downloaded.
Unpack the archive into the directory of your choice.< OPTIONAL >: If you have already installed the program git,
another option to download the files is to use the command:git clone https://github.com/ellinium/plaque_size_tool directory, where directory is a directory for Plaque Size Tool
on a local machine.Installation using pipNext, within Terminal (macOS) or Command Prompt (Windows) navigate to
the directory you unpacked the downloaded zip file into. For example, if
you unpacked ‘plaque_size_tool-main.zip‘ into the
‘/home/plaque_size_tool/ plaque_size_tool-main’ directory, navigate
to this directory. To confirm you are in the directory containing the
plaque size tool files, type ‘ls’ on Terminal (MacOS) or ‘dir’ on
Command Prompt (Windows). You should see the following files listed:Test_plates
LICENSE
plaque_size_tool.py
pyproject.toml
README.md
setup.pyOnce in the directory containing plaque size tool, execute the following
command which installs all required libraries for Plaque Size Tool:pip3 install plaque-size-toolIf the pip3 command worked properly you should see something like this
on your screen:MacOS and Windows use the same command for installation.Plaque Size Tool usagePlaque Size Tool usage optionsThe tool can be run on a single image file (TIF, TIFF, JPG, JPEG, PNG
image formats are supported) or on a directory containing several image
files. The output of Plaque Size Tool will be placed into a
sub-directory called ‘out’ within the /plaque_size_tool-main
directory.You can execute the command to run Plaque Size Tool from the directory
used inInstallation Step 3.1.If your current directory differs,
you need to include a full path to the tool (see below for examples).Input parameters:-i to process a single image file-d to process a directory with image files-p is an optional parameter for the Petri dish size in millimetres-small an optional flag, is recommended to use when the plaques are less
than 2.5 mm or images are of low resolution and sizeSingle File processingMacOS:python3 PATH_TO_PST/plaque_size_tool.py -i PATH_TO_THE_IMAGE_FILE [-p plate_size] [-small]Windows:py PATH_TO_PST/plaque_size_tool.py -i PATH_TO_THE_IMAGE_FILE [-p plate_size] [-small]When the tool is executed from the directory Plaque Size Tool is
installed into, the PATH_TO_PST can be omitted:MacOS:python3 plaque_size_tool.py -i PATH_TO_THE_IMAGE_FILE [-p plate_size] [-small]Windows:py plaque_size_tool.py -i PATH_TO_THE_IMAGE_FILE [-p plate_size] [-small]ExamplesTo use the following examples on Windows‘python3’is required to
be replaced with‘py’.MacOS:python3 plaque_size_tool.py -i Test_plates/large/Plate_4.tif• runs the tool on the file Plate_4.tif located in the sub-directory
Test_plates/large• creates two files within the /out directory called:
‘data-green-Plate_4.csv’ and ‘out_Plate_4.tif’• all results within ‘data-green-Plate_4.csv’ will be shown in pixels
as the plate size is not specified.MacOS:python3 plaque_size_tool.py -i Test_plates/large/Plate_4.tif -p 90• runs the tool on the file Plate_4.tif that has a plate size 90 mm.• the results file ‘data-green-Plate_4.csv’ will contain measurements
in both mm and pixels.MacOS:python3 plaque_size_tool.py -i Test_plates/small/Plate_16.tif -p 90 -small• runs the tool on the file Plate_16.tif that has small plaques. The
results on a plate will be shown in mm.• If executing the tool while the current working directory (which can
be checked with command ‘pwd’ on MacOS, ‘cd’ on Windows) is not
‘/plaque_size_tool-main’ then the full path to the
‘plaque_size_tool.py’ file AND the image file must be specified, or an
error will be shown because python3 cannot find the executable file and
image file.MacOS:python3 /Users/paul/plaque_size_tool-main/plaque_size_tool.py -i /Users/paul/plaque_size_tool-main/Test_plates/large/Plate_4.tifBatch files processingMacOS:python3 PATH_TO_PST/plaque_size_tool.py -d PATH_TO_THE_DIRECTORY [-p plate_size] [-small]Windows:py PATH_TO_PST/plaque_size_tool.py -d PATH_TO_THE_DIRECTORY [-p plate_size] [-small]ExampleMacOS:python3 plaque_size_tool.py -d Test_plates/small -p 90 -smallWindows:Windows: py plaque_size_tool.py -d Test_plates/small -p 90 -small• runs the tool on the directory Test_plates/small that contains plates
with small plaques (<= 2.5 mm). The results on a plate will be shown
in mm.Output filesThe tool produces two output files in the ‘out’ sub-directory that is
created automatically:out_<file_name>- an image with identified non-overlapping
plaques circled with a green line, where <file_name> is the name
of the original file.If -p (plate size) parameter is specified, the results will be shown
in mm. If -p is not specified, then the results are shown in pixels.data-green-<file_name>.csva CSV file with detected plaques
parameters:INDEX_COL - the ID of the plaque that corresponds to the ID on the
output imageAREA_PXL - Area of a plaque in square pixelsAREA_MM2 - Area of a plaque in square millimetres if plate size is
specifiedDIAMETER_PXL - Diameter of a plaque in pixelsDIAMETER_MM - Diameter of a plaque in millimetres if plate size is
specified