Collecting Calibration Patterns¶

The Global Pattern Buffer¶

Most commands that work with calibration patterns (e.g. EstimatePatternPose, Calibrate, CalibrateHandEye ) use the pattern observations that were previously put into the global pattern buffer. You can fill this buffer in two ways.

Collect a new observation from camera images with the CollectPattern command. By default, the command will add all collected observations to the buffer, but you can control this with the Buffer and Filter parameters.
Import previously collected patterns with the SetPatternBuffer command. You can export this data with the GetPatternBuffer command.

The commands that use patterns from the pattern buffer can be instructed to use only a part of the collected patterns with a Filter parameter. To avoid repeating the filter for every command, you can also set up a view with the AddPatternBufferView command and reference this view by its name.

The FilterPatternBuffer command can discard all patterns in the buffer that don’t match a given filter.

Collecting Patterns¶

Note

Before you start to collect patterns, you should always clear the pattern buffer with DiscardPatterns. Otherwise the pattern buffer might still contain old observations that are inconsistent with the new ones. This can cause invalid calibration results.

To collect a pattern, capture an image and call the CollectPattern command. By default, this command will add any patterns it finds to the pattern buffer as well as return them in its result node.

Note

Some types of calibration patterns need additional data to the point locations in the images. In most cases, it is encoded directly in the pattern and can be decoded by enabling the DecodeData parameter. You can also specify the information manually in the global pattern data node. See the how-to on calibration patterns for more information on the different types of calibration patterns and the information that is encoded in them. For most situations and pattern types, it is recommended to decode the pattern data once and using the global pattern data afterwards.

Make sure that the projector is turned off on any images that you want to use to collect patterns. Collecting patterns with the projector is possible with the Projector parameter, but should only be used in special situations, as it requires prior knowledge on the size of the pattern in the image.

Code Example¶

// We assume that the camera with serial "1234" is already open.

// Turn off the camera's projector. It is not possible to collect patterns while the projector is
// enabled.
NxLibItem()[itmCameras]["1234"][itmParameters][itmCapture][itmProjector] = false;
NxLibItem()[itmCameras]["1234"][itmParameters][itmCapture][itmFrontLight] = true;

// Clear the pattern buffer in case there are any old observations in it.
NxLibCommand(cmdDiscardPatterns).execute();

// Collect 10 pattern observations into the pattern buffer.
bool decodedData = false;
while (NxLibItem()[itmCalibration][itmPattern][itmPatternBuffer][itmAll][itmPatternCount].asInt() < 10) {
	NxLibCommand capture(cmdCapture);
	capture.parameters()[itmCameras] = "1234";
	capture.execute();

	try {
		NxLibCommand collectPattern(cmdCollectPattern);
		collectPattern.parameters()[itmCameras] = "1234";
		if (!decodedData) {
			// For our first pattern, try to decode the pattern data from the observation.
			// The collection will fail when decoding is not possible.
			collectPattern.parameters()[itmDecodeData] = true;
			// Put the decoded data into the global pattern data node so that we can use it for all
			// further patterns (this is already the default).
			collectPattern.parameters()[itmUpdateGlobalPatternData] = true;
		}
		collectPattern.execute();
		decodedData = true;
	} catch (NxLibException&) {
		// Could not find any calibration patterns or could not decode it...
	}
}

// Do something with the collected patterns...
// See the corresponding how-tos for more information on how to perform calibrations.