Calibrating Robots: OLD - northern-bites/nbites GitHub Wiki
Intro
There are currently three types of parameters in our vision system:
- Color Parameters: the 18 parameters defining what is white, green, and orange in the system (6 each).
- Camera Parameters: functionality of the camera e.g. exposure time
- Calibration Parameters: The offset of the camera in its casing embedded in the robot's face.
This section is about the the process of obtaining the third type, which might be more accurately described as "camera angle offset calibration," but it shortened to "calibration." Note that it has little to do with the first two types of parameters.
Calibrating a robot provides the roll and pitch offsets (IN RADIANS) of the top and bottom cameras, so a total of four values for each robot. Calibration values are stored in src/man/config/calibrationParams.txt.
How to Calibrate
To calibrate a robot, install pCalibrate with USE_LOGGING on, take valid logs of BlackStar, and retrieve calibration values from the C++ side using the Camera Calibrate Utility 2.
BlackStar
"BlackStar" is the 1.3 meters squared poster of 4 black lines at 45 degree angles. BlackStar should be as flat as physically possible. Position the robot about 1.2 meters from the center of the star, aligned with one of the black lines.
NOTE: In order for the black lines to show up as green (which is required for the system to recognize them as hough and then field lines), the color parameters should be adjusted. Just go to the front end view in the tool and drag the green sliders until it looks like a white star on black, and press save. Ideally, you are working out a calibration branch that has working color params so you don't have to do this more than once.
pCalibrate
pCalibrate is a player state written specifically for calibrating from BlackStar. In Game Playing, the robot will tilt its head so the top camera can see the whole mat (if setup correctly). The robot pans very slightly and slowly, moving two degrees and then stopping for one second. After seven of these, it starts again. In Penalized, the robot tilts way back and does the same for the bottom camera.
Every second, the robot logs one image (one top per second if in playing, one bottom if in penalized). Take at least 7 logs of each top and bottom.
Valid Logs
A valid log is one were there are exactly three valid field lines. A valid field line is a field line (comprising of two hough lines) that are not horizontal (or very close to horizontal) in the image and are sufficiently long. These three lines are intended to be the BlackStar line pointing directly at the robot, and the two next to it.
The Camera Calibration Utility 2
The utility used to generate and save calibration params is located in the tool in the misc tab, under utilities. Select the folder of the calibration logs and click the button in this pane or just type "c" or "cc" in the tool. It will display the selected session, which is the tool word for "folder of logs." Ensure that the correct folder is selected and that the it has seven top logs if you are trying to calibrate the top camera, seven bottoms if bottom, and seven of each if you want both. It is okay to have more than seven.
Press "get calibration params" to send seven logs from the session over to the c++ code. I'm not sure if they are the first seven or seven according to some other metric. While the c++ code parses the images it prints whether or not each line in each image is valid. If the offsets are returned as NaN, check these print statements in the terminal logging nbcross.
If there are enough images with three valid field lines, the utility will display the calculated offsets. Press SAVE to save them to src/man/config/calibrationParams.txt. It reads the robot name from the first log and rewrites that robot's line in calibrationParams.txt with the new offsets.
The code needs to be reinstalled for the scrimmage or game or whomever wants a calibrated robot. In short, when the Vision Module is constructed the robot looks up its params in that text file, and uses them until man stop. Getting calibration values, and even saving them to the text file, DOES NOT mean the robot is actually calibrated. Have the installer cherry-pick the commit and reinstall.
Potential Errors
Sounds pretty simple. But..
Vertical Hough Lines
The hough line finder has a bug that causes it to miss lines that are nearly vertical in the image. This means that in calibration only two lines will be detected sometimes. A short term solution is to calibrate from just off of center so there are no truly vertical lines. A better solution would be to work with Bill Silver to find that damn bug!
False Valid Line
When you are calibrating for the first time or in a new place, look through all the logs with LineView open and nbcross running. (It is recommended that as you stream them you look at this view as well to ensure good logs.) Make sure there are no field lines not on BlackStarr. They will wreck calibration. Make sure all three lines that we want are detected.
Other Bugs
Sometimes the VisionModule, probably because of errors in the way the tool or nbcross is written, will act strangely, not pairing field lines or not finding hough lines. There is a lot of work to be done. Because calibration needs to happen, work hard to squash those bugs.
Future Work
- Find bugs mentioned above
- SEND calibrationParams.txt over network to robot. Work with @PhilKoch
- Change players on the fly (send the python file require to switch to pCalibrate over the network) If you can get the two things above working, calibrating will be super fast and super easy.
- Send a variable amount of images to nbcross, and have it keep checking them until it finds seven valid images.
How it Works
The c++ code found in man/vision/Homography.cpp takes tries to find three valid field lines according to the standards discussed above. For each field line, it finds the intersection point of the hough lines that compose it. Because these lines should be parallel, the intersection point in image coordinates should be on the camera horizon. With three lines, it finds three points on the camera horizon. It then fits a line to the three points to calculate roll offset (angle of the line) and tilt offset (height of the line).
The tool passes logs internally between nbcross and nbtool. Logs that have three valid lines are sent back with calibration params in the description (S-Expression form).
The internal flag to take a log for a single frame (so that it doesn't stream tripoints like in other states) are set in the pCalibrate player code in behaviors. It is a sole environment variable which is inspected in the logImage() method in the Vision Module. Logs with with this flag have a "Black Star" tuple, which is used within the Vision Module during calibration to know to look for lines of reversed polarity (because these "field lines" go from light to dark to light, instead of dark light dark like a soccer field.
[email protected] with any questions!