Automatic Plumbline Detection

VidSync can automatically detect the "plumblines" for distortion correction, the straight lines made up of chess-board corners from which VidSync calculates the distortion coefficients. However, different visual conditions and hardware configurations require different settings for the automatic detection algorithm. Sometimes the default values will work fine for you. When you find values that work for one of your videos, they're reasonably likely to work for others shot under similar conditions. However, minor trial-and-error adjustments are sometimes required, and it's helpful to guide that process with knowledge of what the parameters mean and how the automatic detection process works.

There are two main stages:

First, VidSync converts the video frame to a still image and runs it through OpenCV's functions cvGoodFeaturesToTrack and cvFindCornerSubPix. With the right settings (the defaults in this program seem to work well), this will detect all the chessboard corners, and a few stray spots (like where a chessboard square intersects the edge of the image). The next part of the algorithm basically filters out some of the stray spots, but a few others may slip through and show up in your detected plumblines. You can delete those points or move them into a better position manually, by right-clicking nearby to select them and using the arrow keys to move them around.

Once VidSync gets the disorganized collection of detected chessboard corner positions from OpenCV, it has to arrange them into straight plumblines. To do this automatically, it finds the point closest to the center of all the points, and then finds the closest point to that one, which is guaranteed to be along one of the chessboard axes (because the diagonal points are farther away) unless there are stray points. VidSync then projects a line from one point to the other one, and doubles it to go past the second point and end in a location very near where a third point should be. The detected point closest to this "candidate" third point position is added to the line as the third point. The process is repeated, projecting from the 2nd point to the 3rd point and beyond to find the 4th point, then from the 3rd past the 4th in order to find the 5th, and so on until the line ends when no point is found close enough to the candidate position. (It can even skip one bad corner and keep looking.) This same process is just reversed in direction and then rotated 90 degrees to fill out the rest of the grid.

One of the most common failures of this fully automatic algorithm happens when the center starting point or the next point (the nearest one to it) are not on the actual chessboard corners because OpenCV was too sensitive, or not sensitive enough. You can begin to diagnose this problem because VidSync will overlay yellow dots on all the detected chessboard corners; these dots will be hidden by any plumblines it successfully detects, but stray or unused dots will still be visible. Ideally you want to make sure you've detected points at most of the real corners and not too many false ones.

If this all looks fine, you can try manually seeding the line arrangement algorithm by manually creating exactly one plumbline with exactly two points on adjacent chessboard corners somewhere near the center of the screen, and then running the autodetect algorithm from that starting point.

Parameters for OpenCV corner detection:

  • Max # of corners to detect - (default 2000): This is the initial value of the cornerCount parameter to OpenCV's cvGoodFeaturesToTrack function. It can be set comfortably larger than the number of corners you expect to detect, but should not be superfluously huge.
  • Min pixel distance between detected corners - (default 10): This is the minDistance parameter to OpenCV's cvGoodFeaturesToTrack function. It determines how close two corners can be and still be considered separate corners.
  • Minimum quality threshold for detection - (default 0.05): This is the qualityLevel parameter to OpenCV's cvGoodFeaturesToTrack function. Every detected potential corner gets a quality score (using an eigenvalue method). The threshold is set as a portion of the highest score below which features are not returned as detected corners. Set this too high, and the algorithm will miss some corners. Set it too low, and the algorithm will pick up some false corners.
  • Window size for corner subpixel refinement - (default 15): This is the win parameter to OpenCV's cvFindCornerSubPix function. That function takes the integer pixel coordinates of a detected corner and refines the position to subpixel precision within an area defined by a search window. This function also helps correct the positions of some corners that are flat-out mislocated by cvGoodFeaturesToTrack. This parameter is half the size of that search window, in pixels.

Parameters for VidSync's algorithm arranging corners into plumblines:

  • Candidate point distance tolerance - (default 0.2): This is the maximum distance between a "candidate" point and a real detected point, expressed as a portion of the distance between the previous two points. For example, at the default value of 0.2, if corners are spaced 10 pixels apart, VidSync would assume a line has ended when it does not find a detected point within 0.2*10 = 2 pixels of the candidate position.
  • Minimum plumbline length - default 4: The fewest points allowed in a plumbline. Must be at least 3.