HandWashing/COVID-19 PoC used to detect when people are washing their hands correctly. More...

#include <HW.hpp>

Collaboration diagram for CCR::HW:

Public Member Functions
	HW ()
	Empty (default) constructor. Caller must use init() if this constructor is used. More...

	HW (const std::string &filename)
	Constructor. The specified input video file or device must exist. More...

virtual	~HW ()
	Destructor. More...

virtual HW &	false_start_timer_reset ()
	Classes that inherit from `HW` can override this method to be told when the timer has been reset due to too many frames since the last time "wash" was detected. More...

virtual HW &	hand_washing_completed ()
	Classes that inherit from `HW` can override this method to be told when handwashing has reached the desired number of seconds. More...

virtual HW &	hand_washing_ended_too_early ()
	Classes that inherit from `HW` can override this method to be told when handwashing has finished prior to the full number of seconds. More...

virtual HW &	hand_washing_finished ()
	Classes that inherit from `HW` can override this method to be told when handwashing has finished, meaning the hands are now completely out of view or the video stream has ended. More...

virtual HW &	hand_washing_started ()
	Classes that inherit from `HW` can override this method to be told when handwashing is first detected. More...

virtual HW &	init (const std::string &filename)
	Initialize (or re-initialize) the `HW` object using the specified video file. More...

virtual HW &	init (const int idx, const int request_width=1024, const int request_height=768, const int request_fps=30)
	Initialize (or re-initialize) the HW object using the specified web cam. More...

virtual HW &	load_neural_network ()
	Load the neural network files from disk. More...

virtual HW &	process_stream ()
	Process the specified video stream. You must call init() (or use the constructor with the filename) prior to this call. More...

virtual HW &	reset ()
	Reset the HW object. More...

virtual HW &	stream_has_ended ()
	Classes that inherit from `HW` can override this method to be told when the video stream has ended. More...

virtual std::string	to_string ()
	Format information on the HW object as a multi-line text string. More...

std::string	version () const
	Get the HW library version number. E.g., `"1.0.0-2956"`. More...

Public Attributes
std::string	base_filename
	The base filename. This is the input_filename without any path and with no extension. More...

double	blend_ratio
	The amount of blending between the counter circle's black background and the original frame image. More...

cv::VideoCapture	cap
	OpenCV video capturing device. More...

size_t	current_frame_index
	Starts at zero and increments up for every frame processed in the video stream. More...

size_t	current_session_index
	Starts at zero and increments up for every hand washing session that is started. More...

cv::Mat	current_video_frame_annotated
	The most recent video frame. This is after all annotations have been applied. More...

cv::Mat	current_video_frame_original
	The most recent video frame. This is the original image, prior to resizing and annotations. More...

cv::Mat	current_video_frame_resized
	The most recent video frame. This is after it has been resized. More...

double	current_wash_session_length
	In seconds the length of time the current (or most recent) hand washing session has lasted. More...

DarkHelp	darkhelp
	Neural network library. More...

int	desired_fps
	If a video capture device is used (e.g., "webcam") versus a recorded video stream, then the desired FPS, width, and height can be specified. More...

int	desired_frame_height
	Video frame will be resized to this height before processing by the neural network. More...

int	desired_frame_width
	Video frame will be resized to this width before processing by the neural network. More...

bool	display_frame_information
	Display some frame details at the bottom left corner, including FPS, frame index, and timestamp. More...

double	duration_of_frame
	The length (in seconds) of a single video stream based on the fps. More...

double	fps
	The number of frames-per-second in the video stream. More...

const int	HAND = 1
	Class used by the neural network to indicate detection of a hand. More...

bool	in_handwashing_session
	Is set to `true` when a handwashing session has started. More...

std::string	input_filename
	The name of the input file or input device which was originally opened. More...

size_t	last_empty_frame
	The frame index of the last time we saw a frame that was empty (no hands). More...

size_t	last_hand_frame
	The frame index of the last time we saw a frame with a single hand. More...

size_t	last_session_frame
	The frame index of the most recent frame that was part of a session. More...

size_t	last_washing_frame
	The frame index of the last time we saw a frame with washing hands. More...

double	length_of_time_users_must_wash_hands
	In seconds, the length of time users must wash hands. More...

DarkHelp::PredictionResults	predictions
	Predictions returned by the neural network. More...

bool	save_output_video
	When set to `true`, the processed video stream will be saved as a .mp4 output video. More...

const int	WASHING = 0
	Class used by the neural network to indicate detection of handwashing. More...

const int	WATER = 2
	Class used by the neural network to indicate detection of water from a faucet. More...

Detailed Description

HandWashing/COVID-19 PoC used to detect when people are washing their hands correctly.

This class will inspect the given video stream and determine if users are washing their hands with the help of the trained neural network.

There are two ways to use this class:

You can directly instantiate an object of this type and call the existing methods, such as HW::init() and HW::process_stream().
You can create your own class which inherits from HW and override the methods such as hand_washing_started() and hand_washing_completed() prior to calling the usual methods HW::init() and HW::process_stream().

If using a class that derives from HW, these are some of the methods you may want to override:

Constructor & Destructor Documentation

◆ ~HW()

CCR::HW::~HW ( )

virtual

Destructor.

◆ HW() [1/2]

CCR::HW::HW ( )

Empty (default) constructor. Caller must use init() if this constructor is used.

Here is the call graph for this function:

◆ HW() [2/2]

CCR::HW::HW ( const std::string & filename )

Constructor. The specified input video file or device must exist.

Here is the call graph for this function:

Member Function Documentation

◆ false_start_timer_reset()

CCR::HW & CCR::HW::false_start_timer_reset ( )

virtual

Classes that inherit from HW can override this method to be told when the timer has been reset due to too many frames since the last time "wash" was detected.

This is only called at the start of the session when there is barely any time logged on the timer.

Here is the caller graph for this function:

◆ hand_washing_completed()

CCR::HW & CCR::HW::hand_washing_completed ( )

virtual

Classes that inherit from HW can override this method to be told when handwashing has reached the desired number of seconds.

See also: hand_washing_finished(); hand_washing_ended_too_early(); length_of_time_users_must_wash_hands (defaults to 20.0 seconds)

Here is the caller graph for this function:

◆ hand_washing_ended_too_early()

CCR::HW & CCR::HW::hand_washing_ended_too_early ( )

virtual

Classes that inherit from HW can override this method to be told when handwashing has finished prior to the full number of seconds.

See also: hand_washing_completed();

Here is the caller graph for this function:

◆ hand_washing_finished()

CCR::HW & CCR::HW::hand_washing_finished ( )

virtual

Classes that inherit from HW can override this method to be told when handwashing has finished, meaning the hands are now completely out of view or the video stream has ended.

This is only called once per session.

See also: hand_washing_completed()

Here is the caller graph for this function:

◆ hand_washing_started()

CCR::HW & CCR::HW::hand_washing_started ( )

virtual

Classes that inherit from HW can override this method to be told when handwashing is first detected.

This is only called once per session.

Here is the caller graph for this function:

◆ init() [1/2]

CCR::HW & CCR::HW::init ( const std::string & filename )

virtual

Initialize (or re-initialize) the HW object using the specified video file.

This automatically calls reset().

If you want to customize the look-and-feel of either the neural network annotations or how CCR::HW behaves, the right place to make those changes is immediately after the call to init(). For example:

CCR::HW hw;
hw.init(video_stream_filename);
hw.desired_frame_width                   = 640;  // in pixels
hw.desired_frame_height                  = 480;  // in pixels
hw.length_of_time_users_must_wash_hands  = 15.0; // in seconds
hw.darkhelp.names_include_percentage     = true;

To get further insight into what can be customized, see the members defined in CCR::HW, look at the code in CCR::HW::reset(), or in CCR::HW::load_neural_network().

Exceptions

std::invalid_argument if the specified file cannot be opened

Here is the call graph for this function:

Here is the caller graph for this function:

◆ init() [2/2]

CCR::HW & CCR::HW::init	(	const int	idx,
		const int	request_width = `1024`,
		const int	request_height = `768`,
		const int	request_fps = `30`
	)

virtual

Initialize (or re-initialize) the HW object using the specified web cam.

The first camera is index zero, the next camera is index one, etc. These correspond to /dev/video0, /dev/video1, ... This automatically calls reset().

Exceptions

std::invalid_argument if the specified camera index cannot be opened

Here is the call graph for this function:

◆ load_neural_network()

CCR::HW & CCR::HW::load_neural_network ( )

virtual

Load the neural network files from disk.

The neural network files are automatically installed during installation. This is automatically called by init().

Here is the caller graph for this function:

◆ process_stream()

CCR::HW & CCR::HW::process_stream ( )

virtual

Process the specified video stream. You must call init() (or use the constructor with the filename) prior to this call.

Exceptions

std::runtime_error if the output video cannot be created

Here is the call graph for this function:

◆ reset()

CCR::HW & CCR::HW::reset ( )

virtual

Reset the HW object.

This may be called to re-use the HW object. This is automatically called by both versions of init().

Here is the caller graph for this function:

◆ stream_has_ended()

CCR::HW & CCR::HW::stream_has_ended ( )

virtual

Classes that inherit from HW can override this method to be told when the video stream has ended.

Here is the caller graph for this function:

◆ to_string()

std::string CCR::HW::to_string ( )

virtual

Format information on the HW object as a multi-line text string.

Mostly for debugging purposes.

For example:

- filename ................................. set_02/Handwash_microdia_webcam/Film_le_20-04-15_23.04.mov
- base filename ............................ Film_le_20-04-15_23.04
- is open ............................. TRUE
- version (HW) .................. 1.0.0-2956
- version (OpenCV) ................... 3.2.0
- version (DarkHelp) ............ 1.0.0-2952
- property #00 (POS_MSEC) ............ 41023.33 Current position of the video file in milliseconds
- property #01 (POS_FRAMES) ............ 686    0-based index of the frame to be decoded/captured next
- property #02 (POS_AVI_RATIO) ........... 0    Relative position of the video file: 0=start of the film, 1=end of the film
- property #03 (FRAME_WIDTH) ........... 640    Width of the frames in the video stream
- property #04 (FRAME_HEIGHT) .......... 426    Height of the frames in the video stream
- property #05 (FPS) .................... 16.72 Frame rate
- property #06 (FOURCC) .......... 828601953    4-character code of codec
- property #07 (FRAME_COUNT) ........... 686    Number of frames in the video file

◆ version()

std::string CCR::HW::version ( ) const

Get the HW library version number. E.g., "1.0.0-2956".

Member Data Documentation

◆ base_filename

std::string CCR::HW::base_filename

The base filename. This is the input_filename without any path and with no extension.

◆ blend_ratio

double CCR::HW::blend_ratio

The amount of blending between the counter circle's black background and the original frame image.

Range is 0.0 to 1.0. At zero, the overlay is fully transparent and the background image is copied through. At 1.0 the overlay is opaque and the background image is hidden.

Default value is 0.75, which means the black background is 3/4 opaque and only 25% of the background image frame is shown.

◆ cap

cv::VideoCapture CCR::HW::cap

OpenCV video capturing device.

◆ current_frame_index

size_t CCR::HW::current_frame_index

Starts at zero and increments up for every frame processed in the video stream.

◆ current_session_index

size_t CCR::HW::current_session_index

Starts at zero and increments up for every hand washing session that is started.

◆ current_video_frame_annotated

cv::Mat CCR::HW::current_video_frame_annotated

The most recent video frame. This is after all annotations have been applied.

See also: current_video_frame_original; current_video_frame_resized

◆ current_video_frame_original

cv::Mat CCR::HW::current_video_frame_original

The most recent video frame. This is the original image, prior to resizing and annotations.

See also: current_video_frame_resized; current_video_frame_annotated

◆ current_video_frame_resized

cv::Mat CCR::HW::current_video_frame_resized

The most recent video frame. This is after it has been resized.

See also: desired_frame_width; desired_frame_height; current_video_frame_original; current_video_frame_annotated

◆ current_wash_session_length

double CCR::HW::current_wash_session_length

In seconds the length of time the current (or most recent) hand washing session has lasted.

◆ darkhelp

DarkHelp CCR::HW::darkhelp

Neural network library.

See also: https://www.ccoderun.ca/DarkHelp/api/

◆ desired_fps

int CCR::HW::desired_fps

If a video capture device is used (e.g., "webcam") versus a recorded video stream, then the desired FPS, width, and height can be specified.

This does not guarantee these values will be used, as not all combinations of width, height, and FPS are valid. Default is 1024x768 @ 30 FPS.

See also: desired_frame_width; desired_frame_height

◆ desired_frame_height

int CCR::HW::desired_frame_height

Video frame will be resized to this height before processing by the neural network.

Note that image resizing retains the aspect ratio of the original frame size, so the final dimensions used may not be exactly the size specified using desired_frame_width and desired_frame_height. Default for height is 768.

◆ desired_frame_width

int CCR::HW::desired_frame_width

Video frame will be resized to this width before processing by the neural network.

Note that image resizing retains the aspect ratio of the original frame size, so the final dimensions used may not be exactly the size specified using desired_frame_width and desired_frame_height. Default for width is 1024.

◆ display_frame_information

bool CCR::HW::display_frame_information

Display some frame details at the bottom left corner, including FPS, frame index, and timestamp.

◆ duration_of_frame

double CCR::HW::duration_of_frame

The length (in seconds) of a single video stream based on the fps.

◆ fps

double CCR::HW::fps

The number of frames-per-second in the video stream.

◆ HAND

const int CCR::HW::HAND = 1

Class used by the neural network to indicate detection of a hand.

This is defined at the time the neural network was trained and cannot be changed.

◆ in_handwashing_session

bool CCR::HW::in_handwashing_session

Is set to true when a handwashing session has started.

◆ input_filename

std::string CCR::HW::input_filename

The name of the input file or input device which was originally opened.

For example, could be "myvideo.mp4" or "/dev/video0". The name provided by the user may be relative or absolute.

See also: init()

◆ last_empty_frame

size_t CCR::HW::last_empty_frame

The frame index of the last time we saw a frame that was empty (no hands).

◆ last_hand_frame

size_t CCR::HW::last_hand_frame

The frame index of the last time we saw a frame with a single hand.

◆ last_session_frame

size_t CCR::HW::last_session_frame

The frame index of the most recent frame that was part of a session.

◆ last_washing_frame

size_t CCR::HW::last_washing_frame

The frame index of the last time we saw a frame with washing hands.

◆ length_of_time_users_must_wash_hands

double CCR::HW::length_of_time_users_must_wash_hands

In seconds, the length of time users must wash hands.

Default is 20 seconds. If the neural network reaches this length in time, then a green checkmark is shown. Otherwise, a red X is shown.

◆ predictions

DarkHelp::PredictionResults CCR::HW::predictions

Predictions returned by the neural network.

◆ save_output_video

bool CCR::HW::save_output_video

When set to true, the processed video stream will be saved as a .mp4 output video.

◆ WASHING

const int CCR::HW::WASHING = 0

Class used by the neural network to indicate detection of handwashing.

This is defined at the time the neural network was trained and cannot be changed.

◆ WATER

const int CCR::HW::WATER = 2

Class used by the neural network to indicate detection of water from a faucet.

This is defined at the time the neural network was trained and cannot be changed.

The documentation for this class was generated from the following files:

HW.hpp
HW.cpp
Initializing.cpp
Overrides.cpp
Properties.cpp

Public Member Functions

Public Attributes

Detailed Description

Constructor & Destructor Documentation

◆ ~HW()

◆ HW() [1/2]

◆ HW() [2/2]

Member Function Documentation

◆ false_start_timer_reset()

◆ hand_washing_completed()

◆ hand_washing_ended_too_early()

◆ hand_washing_finished()

◆ hand_washing_started()

◆ init() [1/2]

◆ init() [2/2]

◆ load_neural_network()

◆ process_stream()

◆ reset()

◆ stream_has_ended()

◆ to_string()

◆ version()

Member Data Documentation

◆ base_filename

◆ blend_ratio

◆ cap

◆ current_frame_index

◆ current_session_index

◆ current_video_frame_annotated

◆ current_video_frame_original

◆ current_video_frame_resized

◆ current_wash_session_length

◆ darkhelp

◆ desired_fps

◆ desired_frame_height

◆ desired_frame_width

◆ display_frame_information

◆ duration_of_frame

◆ fps

◆ HAND

◆ in_handwashing_session

◆ input_filename

◆ last_empty_frame

◆ last_hand_frame

◆ last_session_frame

◆ last_washing_frame

◆ length_of_time_users_must_wash_hands

◆ predictions

◆ save_output_video

◆ WASHING

◆ WATER