Skip to content

Color Detection

notes

This project is almost exactly identical to the pipe_angle project (that was not intentional but for multiple of reasons we have decided to separate them instead of making them a single project).

.json file
input_type

type: int or string (only in the *.json file in the settings folder)
possible values (depends on input variable): 1 (or video), 2 (or image), 3 (or camera), 4 (or ip).
default value: camera

Explanation: Determine what kind of input the program will use. There are four possible integer values for this variable. They are:
1 (video), 2 (image), 3 (camera), and 4 (ip). more details are in the input variable documentation.

Notes:
For your convenience it is possible to use string type as an input but only in the *.json file in the settings folder. for example instead of writing 3 you could write camera or Camera in the default.json file. the load_settings function in your main.py file will take care of converting the input_type variable to an integer.

Also note that the input variable depends on the input_type variable. So if you change the input_type variable you should make sure that the input variable will have a correct value. for example if the input_type variable is a camera (or number 3), then the input variable should only be an integer which represent which camera in your device such as 1. Another example if the input_type is video (or number 1) then the input should be a file path such as C:/filename.mp4

input

type: int, string
possible values (depends on input_type variable):
input_type is 1 or 2 (video or image): possible values are file paths (Example: C:/filename.mp4 or C:/filename.png).
input_type is 3 (camera): possible values are integers from 0 or more (Example: 2).
input_type is 4 (ip): possible values are Live stream URLs (Example: https://192.168.100.25:8080/video).

default value: 0 (for camera)

Explanation:
This variable depends on the input_type variable.
Here is a brief description of the variable:

input_type is video or image:
The input will be a path of the image or video you want to use in you program. usually we use the video or image for testing purposes.

input_type is camera:
The input variable will be an integer that will describe what camera you are using (note that the count starts from 0 not 1). So if you have three cameras on your device and write 2 in the *.json file, then you will use the third camera. if you write 3 then you will get an error.

input_type IP:
The live stream ip address (URL) you want to use in your program. you could stream from your phone if you use the IP Webcam App for Android devices. If you install the app, open it and scroll to the bottom and select "Start server". Your live IP server in the local area network will be after "IPv4:" (you could choose the first or second). the URL that you need to past is what is after "IPv4:" plus "/video" (Example: http://192.168.100.25:8080/video) make sure you are at the same local area network. you can test if the stream is available by simply writing the URL in your web browser such as Chrome or Firefox.

Notes:
If you are using Windows and the input is for an image or video use "/" instead of "\" for the path of the video or image or add additional "\" to "\". For example C:\Users\Ibrahim\filename.mp4 should instead be C:/Users/Ibrahim/filename.mp4 or C:\Users\Ibrahim\filename.mp4

Do not forget to add the extension. Example: filename.mp4 not filename

centroid_size

type: float
possible values: from 0 to 1
default value: 0.015

Explanation:
the size of the radius of the circle which is the centroid of the largest continuous white area (the white area is the detected color range)

centroid_color

type: list
possible values: the list has three values each could be from 0 to 255
default value: [0,0,255]

Explanation:
the bgr color (Blue,Green,Red) of the centroid circle

contour_s_color

type: list
possible values: the list has three values each could be from 0 to 255
default value: [0,0,255]

Explanation:
the bgr color (Blue,Green,Red) of the border (or perimeter) of the largest continuous white color (the color that represent the detected range)

contour_s_thickness

type: float
possible values: from 0 to 1
default value: 0.01

Explanation:
the thickness of the border (or perimeter) of the largest continuous white color (the color that represent the detected range). the value is the ratio of the frame hight.

lowerH, upperH, lowerS, upperS, lowerV, and upperV

type: int
possible values: from 0 to 360 for lowerH, and upperH. and from 0 to 256 for lowerS, upperS, lowerV, and upperV

Explanation:
the lower and upper ranges for the HSV color (HSV stands for hue saturation value)

for more information go to:
http://color.lukas-stratmann.com/color-systems/hsv.html
or
https://medium.com/programming-fever/how-to-find-hsv-range-of-an-object-for-computer-vision-applications-254a8eb039fc

additional_lowerH, additional_upperH, additional_lowerS, additional_upperS, additional_lowerV, and additional_upperV

type: list
possible values: from 1 to 360 for lowerH, and upperH. and from 1 to 256 for lowerS, upperS, lowerV, and upperV. all of the list should have the same number of inputs or you will get an error.

Explanation:
an additional HSV color range (HSV stands for hue saturation value). this will be useful if you want to select two more different colors at the same time.

Notes:
please note that the lists should have the same number of values or you will get an error. for example if additional_lowerH = [2,77,300,44] (5 inputs), then the rest should have 5 inputs.

for more information go to:
http://color.lukas-stratmann.com/color-systems/hsv.html
or
https://medium.com/programming-fever/how-to-find-hsv-range-of-an-object-for-computer-vision-applications-254a8eb039fc

blur

type: int
possible values: from 0 and more (preferred less then 20)
default value: 4

Explanation:
This filter the image and makes it blur. this is one of the filters that will help to get ride of the noise

erosion

type: int
possible values: from 0 and more (preferred less then 10)
default value: 5

Explanation:
This filter will decrease all of the white areas which represent the detected color range. this is one of the filters that will help to get ride of the noise.

dilation

type: int
possible values: from 0 and more (preferred less then 10)
default value: 2

Explanation:
This filter will increase all of the white areas which represent the detected color range. this filter will be applied after the erosion filter. it will be useful if for example there are two close parallel objects such as two pips and we want to analyze the two as a one object. also this will solve the issue of having two objects with almost identical areas which will make the program alternate between the two objects.

contourAreaRatio

type: float
possible values: from 0 to 1 (preferred 0.005)
default value: 0.005

Explanation:
if the ratio of the white color pixels (the detected color range) to the frame (hight * width) pixels is greater than this value then it will start recording the detection.

show_frames

type: boolean
possible values: true or false
default value: true

Explanation:
if false the display window will not show. this will be useful if you want to use less processing power.

Notes:
if you want to use the code for a certain project with the Raspberry pi 4 (or any lny linux machine) and would like the code to immediately run once you power the processor, then follow the steps in the readMe.md file which will be generated if you click on the "Generate Code" in the "Control Window" and make sure to make this variable false.

resize

type: boolean
possible values: true or false
default value: true

Explanation:
This variable simply will allow you to scale your frame. if it is false, then the scale variable will not have any effect

scale

type: float
possible values (depends on resize variable): more than 0 and preferred to be less than 1
default value: 1

Explanation:
This variable is the percentage scale of your original frame. if you have a frame of 1000 pixels width and 1000 pixels height and you make scale variable to 0.5 then you will have 500 pixels for height and width. this variable will be useful if you have a frame with very high resolution and you want to make your program run faster.

Notes:
This variable depends on the resize variable. if it is false then its value will have no effect.
It will not make sense if you make this variable more than 1 since it will not increase the resolution but simply will make your program much slower since you have increased the number of pixels.

delay_time

type: int
possible values: 1 and more (preferred 1)
default value: 1

Explanation:
time in milliseconds it waits after each frame.

ASCII_close_window_key

type: int
possible values: 0 to 127 (preferred 27)
default value: 27

Explanation:
the key on your keyboard that will close the program. every key on your keyboard has an ASCII value. the ASCII for the Esc key is 27

location

type: string
possible values: any string
default value: KFUPM

Explanation:
This variable will be one of the results that will be recorded once a detection was found.

Use case:
one of the useful cases is when this software is used in a surveillance application. Say that you decided to use 1000 cameras in a certain area. multiple cameras or each one is connected to a computer that uses the software. you can make the location variable for each camera describes exactly the place it is in such as using the x and y GPS coordinate. Another example is if you have a drone you could update the location variable as the drone moves so that you could know the exact coordinate of each detection you had.

font_TTF_file

type: string
possible values: .ttf file path
default value: resources/fonts/times.ttf (The Times New Roman Font)

Explanation:
the font that will be used in displaying most of the texts in the software.

display_text_sizes

type: python dictionary (or javascript object) with 5 variables each is a float
possible values: every variable in display_text_sizes could be from 0 to 100
default value: {"fps":5,"location":5,"SSD_objects":5,"date_and_time":5,"AI_model": 5}

Explanation:
the 5 variables will be displayed in the frame. their values represent their size percentage relative to the frame hight. so if the frame hight is 1000 pixels and for an example fps is 10 then it will be 10% of the hight of the frame which is 100 pixels height.

Notes:
if you want to remove one of the 5 texts displayed in your frame then make the its variable equals to 0.

display_text_colors

type: python dictionary (or javascript object) with 5 variables each has a list of three integers
possible values: every variable in the font_sizes has a list that has three values each could be from 0 to 255
default value: [255,0,0] for all (blue)

Explanation:
the values in the list inside the variables inside the font_sizes describes the color of the text. the color order is BGR (Blue, green, Red). For example if fps is [0,0,255] then it will be red or if it is [0,255,255] it will be yellow and so on.

display_text_locations

type: python dictionary (or javascript object) with 5 variables each has a list of two floats
possible values: every variable in font_sizes has a list that has two values each could be from 0 to 1

Explanation:
the values in the list inside the variables inside the font_sizes describes the location of the texts.

the first value is the x axis and the second value is the y axis.
the coordinate starts from the upper left.
the x axis increases from left to right and the y axis increases from up to bottom.
the x and y axes is for the location of the upper left of the text.

for example if fps is [0.5, 0.5] then the upper left point of the text will be at the center.

Note:
if you make fps or any variable's x or y axis to 1 then it will disappear because this is the location of the upper left of the text.

save_results

type: boolean
possible values: true or false
default value: true

Explanation:
if there was a detection found then this variable will save the results in the Results folder.

Notes:
a .csv file will always be present if this value is true.
if this value is false then the save_images will not have effect even if it true.

save_images

type: boolean
possible values (depends on save_results): true or false
default value: true

Explanation:
if this variable is true then there will be images saved in the Results folder. make this variable false if you want to save space.

Notes:
if the save_results variable is false then the save_images variable will not save images even if it ia true

add_to_previous_results

type: boolean
possible values: true or false
default value: false

Explanation:
if this value is true and you close and open the program multiple times then the .csv file in the Results folder will not change (the results will be accumulated)

add_header_to_next_results

type: boolean
possible values (depends on add_to_previous_results): true or false.
default value: true

Explanation:
this variable will add a header in the .csv file in the Results folder to the accumulated results (if add_to_previous_results is true and you have open the program more than two times).

image_extension

type: string
possible values: jpg or png
default value: jpg

Explanation:
the formate of the image that will be saved. use .jpg if you want less size.

add_results_on_image

type: boolean
possible values: true or false
default value: true

Explanation:
if false the results images in the Results folder will not display some results such as frames per seconds and date and time, and location etc.

Notes:
only the saved images will not show if this variable is false. the window that will display the

results
results["frame_number"]

type: int

Example: 478

Example Explanation:

the frame number since the beginning of the program.

results["fps"]

type: float

Example: 5.58

Example Explanation:

the frames per second at the time of detection.

results["location"]

type: string

Example: KFUPM

Example Explanation:
This is simply one of the inputs that is also used as an output for getting more information about the results.

results["date_and_time"]

type: string

Example: 2022/08/03, Wed, 04:46:40 PM

Example Explanation:
the date and time there were detection on the frame.
year/month/day, day name, hour:minute:seconds AM or PM

results["x"]

type: float

Example: 0.50

Example Explanation:

the normalized x coordinate of the centroid of the contour area (the white area which represent the color range). the 0.5 means that it is in the middle of the frame. the x axis starts from the left and increase right.

results["y"]

type: float

Example: 0.9

Example Explanation:

the normalized y coordinate of the centroid of the contour area (the white area which represent the color range). the 0.9 means that it is almost at the top. the x axis starts from the bottom and increase upp

results_frames

type: numpy object.

possible values: three or sometimes two dimensional array (hight, width, and sometimes color channels with three values which are usually (b,g,r)). for the three or one channel (two dimensional array) the values are usually from 0 to 255 (uint8 type in the numpy library)

Notes:
1-the "type" and "possible values" are true for all of the BV software.
2-the names of the frames (or one frame) should be self explanatory so we will not go deep in explaining them. Some one with basic knowledge with the numpy library should be able to deal with them without issues.

frames:
results_frames["1_original_with_results"]
results_frames["2_filtered"]
results_frames["3_HSV_range(s)"]
results_frames["4_erosion"]
results_frames["5_dilation"]
results_frames["6_contour(s)_centroid"]