Starting the Application
When a user first opens the app, they are greeted with the following dialog:
When the user has entered the team names, the main window of the program appears, as shown below. A number of controls are visible which will become useful when an input has been selected and the table setup process completed.
Selecting Video Input
Clicking the Settings dropdown provides the user with options to select an input source, or exit the application. The Local Cameras option can be used to select from any available cameras which are directly connected to the computer.
Clicking the Web Feed option opens the dialog shown below. The user can then enter the web address (beginning with http:// ) of a video feed which they would like to stream as the input source.
Clicking the Video File option opens a file selection dialog shown below. The user can navigate to, and then select, a video file to use as input.
Setting up the Table
Once an input has been selected, the video feed will automatically begin. At this point, the user can press the "p" key on the keyboard to pause the video and begin selecting pockets (note: the user can also select the pockets while the video is still playing if they wish).
Pocket selection is accomplished by clicking on the pockets as prompted by the text displayed on the video. Left-clicking will add a point to designate a pocket, and right-clicking will remove the most recently placed pocket.
When all 6 pockets have been selected, the playing surface becomes outlined as shown below. This shows the user what area will be transformed and used to display the video feed. The user is prompted to press "p" again to un-pause and proceed to the next step.
The ordering in which a user selects the pockets is important; pockets must be selected by beginning in a corner, then selecting the middle pocket on the same side as the first corner, then selecting the other corner on that same side of the table, then the moving back to the other side of the table to select the corner directly adjacent to the first pocket, and proceeding to select the other two pockets on that side of the table.
The prompts "top left", "middle left", "bottom left", "top right", "middle right", "bottom right" are relative; they are just suggestions to help the user select pockets in the correct order, but need not be followed exactly. Examples of valid and invalid orderings of pockets are shown below.
Warping the Frame
Once the user has completed pocket selection, they will be shown a preview of the warped table as shown below. They will be prompted to type "y" if the pockets are properly aligned with the programs understanding of where the pockets are (designated by the blue circles). If not, they user should type "n" to begin the pocket selection process again. In the image below, the top pockets are not aligned with the edges of the blue circles, so it would be recommended that the user restarts pocket selection in this case.
Adjusting Image and Ball Recognition Parameters
The section below the team scores provides controls to improve the applications ability to detect and classify the balls on the table. In the image below, the Hue Adjustment, Saturation Adjustment, and Value Adjustment sliders control those respective values on the image. These changes take effect prior to ball recognition, so these sliders can be used to tweak the whiteness values of the balls, changing what they are classified as.
Below those sliders the three threshold values for determining the ball types can be manually changed.
Stripe/Solid sets the whiteness value that marks the threshold between striped and solid balls; anything below this value will be counted as a solid, and anything above it will be counted as a striped ball.
Cue/Stripe sets the whiteness value that marks the threshold between striped balls and the cue ball; anything below this value and above Stripe/Solid will be counted as a striped ball, and anything above this value will be counted as a cue ball.
8ball sets the blackness value that marks the threshold between an 8-ball and the other types of balls; anything above this value will be counted as an 8-ball, and anything below this value will be counted as one of the other balls.
Show Mask displays the mask used to detect the balls as an overlay on top of the video feed.