Skip to content

Adding a New Algorithm

Jump to bottom
Travis Stewart edited this page Aug 30, 2018 · 3 revisions

This page will help walk you through adding your own algorithm to the CVER Toolkit. This page assumes you are in the installation directory \AppData\Roaming\Computer Vision Emergency Response Toolkit. All references to folders will be relative to this directory.
All algorithms should be defined as a function in their own Python script file.

Here is an example:

def NewAlgorithm( image, Params )
    ...
    return result_image, time, percentage

Language Used for Algorithms

Python 3.6.4 was used for implementing the algorithms. Using Python allowed for an easy way of adding new algorithms, thanks to the massive collection of scientific libraries already developed in Python.

Importing New Python Packages

We use a batch script file to check for and install all of the required Python packages used by the software. This batch file can be located in \lib\Setup\installPythonPackages.bat. To add new packages, just append pip3 install <Package_Name> in the file. The file contains simple instructions on where to add this line.

Algorithm Input Arguments

Each algorithm takes in 2 arguments, the image and the parameters list Params for the algorithm.
image is an OpenCV image object.
Params is a Python dictionary of all parameters used by each algorithm.
These parameters are those that have been provided to the user as an option to change. While Params is always passed to the algorithm functions, it is optional to add your algorithm's parameters to this dictionary. However, it is highly recommended to add it.

Adding to Params

Params is a standard Python dictionary. Each element is made up of a key:value pair. The key is the name of the variable used in the algorithm. The value is the value of that variable in the algorithm. The element format is "VariableName":variable_value Each element in the dictionary is separated by a comma.

Params = {
    "RxThreshold":90.0,
    "RxChiThreshold":0.999,
    "LineGaussianIter":0, 
    "LineDilationIter":1, 
    "LineBilatBlurColor":75,
    "LineBilatBlurSpace":75, 
    "LineCannyEdgeLowerBound":100,
    "LineCannyEdgeThreshold":140, 
    "CornerGaussianIter":0,
    "CornerErosionIter":1,
    "CornerBilateralColor":200,
    "CornerBilateralSpace":500, 
    "CornerMaxDistance":75, 
    "CornerNumPoints":3
}

Using Params

To access the value of an element use Params["VariableName"]

def RXD( image_file, Params):
    chi_threshold = Params["RxChiThreshold"]
    anomaly_threshold = Params["RxThreshold"]

Making the parameters visible to the user

All user changes to parameter values are stored in the file \lib\parameters.ini If you would like some algorithm variables to be visible to the user, the name(s) of these variables will need to be added to this file. Format: VariableName=UseDefaultBoolean=DefaultValue=UserChangedValue

VariableName is the name of the variable as it is in Params
UseDefaultBoolean is a boolean used to determine whether to use the default value or user changed value. This I managed by the front-end. Use 1 as the default value.
DefaultValue is the default value of the variable
UserChangedValue is the user chosen value

RxThreshold=1=90=90
RxChiThreshold=1=0.999=0.999
LineGaussianIter=1=0=0
LineDilationIter=1=1=1
LineBilatBlurColor=1=75=75
LineBilatBlurSpace=1=75=75
LineCannyEdgeLowerBound=1=100=100
LineCannyEdgeThreshold=1=140=140
CornerGaussianIter=1=0=0
CornerErosionIter=1=1=1
CornerBilateralColor=1=200=200
CornerBilateralSpace=1=500=500
CornerMaxDistance=1=75=75
CornerNumPoints=1=3=3

Algorithm Output

The standard output required by each algorithm is a tuple of 3 elements.

return image, time, percentage
  1. The first element is the resulting image or matrix of values the size of the original image. The image format is defined by OpenCV's image format.
  2. The second element is the time it took for the algorithm to run. There is a provided timer class in the \lib\Algorithms folder that can be used. If you do not want to time your algorithm, just return a 0
  3. The third element is the percentage of anomalous values in the image. There is not strict definition of this value. If you do not want to provide an anomaly percentage, just return 0

Adding the New Algorithm

Add your algorithm Python script to the folder \lib\Algorithms

Setup Algorithms Section

Next, import your algorithm function into \lib\algorithms.py under the Setup Algorithms section. This section starts near the top of algorithms.py around line 15.

Use the format: from Algorithms.FileName import FunctionName

#========================================================================================================
#---------------------------------------------Setup Algorithms-------------------------------------------
#========================================================================================================

# Import algorithm libraries
from Algorithms.RXDetector import RXD
from Algorithms.DXDetector import DebrisDetect
...New Algorithm Import Goes Here...

Next, add any variables to the Params dictionary that you want the user to be able to change. Params can be found under the Setup Algorithms section. This section starts near the top of algorithms.py around line 15.

Each element in the dictionary is separated by a comma.

Params = {
    "RxThreshold":90.0,
    "RxChiThreshold":0.999,
    "LineGaussianIter":0, 
    "LineDilationIter":1, 
    "LineBilatBlurColor":75,
    "LineBilatBlurSpace":75, 
    "LineCannyEdgeLowerBound":100,
    "LineCannyEdgeThreshold":140, 
    "CornerGaussianIter":0,
    "CornerErosionIter":1,
    "CornerBilateralColor":200,
    "CornerBilateralSpace":500, 
    "CornerMaxDistance":75, 
    "CornerNumPoints":3
}

Next, add your function to the Alg_List dictionary. Alg_List can be found under the Setup Algorithms section. This section starts near the top of algorithms.py around line 15.

Use the format: 'FunctionName':FunctionName
Note: The order of functions declared in Alg_List is the order in which each function will be called.

Each element in the dictionary is separated by a comma.

Alg_List = { 
    'RXD':RXD, 
    'DebrisDetect':DebrisDetect
}

Finally, add any new Python packages to the \lib\Setup\installPythonPackages.bat batch file. This will make sure the program checks for and installs the required Python packages for each algorithm.

Clone this wiki locally