Reading/Writing Camera Parameter Files

This example shows how to open a camera, apply a saved parameter set from a json parameter file saved from NxView and modify single parameters thereafter.

Format of JSON parameter files

A parameter file is a text file and contains the complete camera tree structure with all node names and values in JSON format. When saving parameter files from NxView you can choose to save the tree below two different nodes:

• the subtree Parameters of the Camera node (see picture, red frame), or

• the entire Camera node (see picture, blue frame), which includes the Parameters subtree, but additionally all other information like the camera calibration, model name, serial number, etc.

Depending on the content of the parameter file you have different options how to restore the parameters onto an open camera:

• Full Camera node in json file

  • Overwrite the entire Camera node of you opened camera with the JSON content of the parameter file: This will restore all camera settings in the Parameters subnode, but will also apply the calibration data from the Calibration subnode of the parameter file onto the Calibration node of the opened camera. Make sure to not overwrite the calibration with a calibration of a different camera.

  • Extract the Parameters subtree from the file and overwrite only the camera’s Parameters subtree with this. The extraction is easily done by saving the entire JSON content of the file into a temporary NxLib tree item. The camera will then keep its calibration and adopt all other settings from the file.

• Only Parameters subtree in json file

  • Here you can directly overwrite the camera’s Parameters node with the content of the file. The camera will keep its calibration and adopt all other settings from the file.

Parameter Import/Export from NxView

When setting up your camera in NxView you can easily import and export parameters by opening the parameters dialog and pressing either the Load or Save button in the top right corner.

Saving parameter files will always save the complete camera node including calibration, link and parameters. When loading a parameter file NxView will let you select whether you want to load the camera parameters only, or if you want to restore link and/or calibration as well from this file. Note that even after loading calibration and link these values are not stored into the camera eeprom until you manually execute StoreCalibration .

Code Examples

Open camera and read parameter file

C++

Halcon/HDevelop

NxLibItem root; // References the tree's root item at path "/"
// replace "1234" with your camera's serial number:
NxLibItem camera =
    root[itmCameras][itmBySerialNo]["1234"]; // References the camera's item at path "/Cameras/BySerialNo/1234"
// Call the Open command to open the camera (the constant cmdOpen is relevant here.)
NxLibCommand open(cmdOpen);
// specifies the name of the command to be executed when '.execute()' is called
// on the object.
// Set parameters for the command
open.parameters()[itmCameras] =
    "1234"; // Insert the serial number of the camera to be opened into the Cameras parameter of Open
open.execute();
// At this point the parameter tree under /Cameras/BySerialNo/1234/Parameters contains the default values for all
// settings. Assume we saved a file 'params.json' from NxView that we now want to load First we read the json file
// as normal text file into a string variable
std::ifstream file("params.json");
if (file.is_open() && file.rdbuf()) {
	// You can use the std::stringstream class to read a textfile:
	std::stringstream buffer;
	buffer << file.rdbuf();
	std::string const& fileContent = buffer.str();
	// We now have the entire json representation of the parameter set
	// in the string variable 'fileContent'
	// In order to detect if the file contains the parameters only, or the entire camera node we simply write it
	// into a temporary NxLib node "/tmp" and check if it contains a subitem 'Parameters'; if it does, we only use
	// this subitem to rewrite the camera's parameter tree, otherwise we assume that the file contained the
	// parameter subtree only
	NxLibItem tmp("/tmp");
	tmp.setJson(fileContent); // Parse json file content into temporary item
	if (tmp[itmParameters].exists()) {
		// Looks like we had a file containing the full camera node; let's just use the parameters subtree to
		// overwrite the camera's parameter subtree
		camera[itmParameters].setJson(
		    tmp[itmParameters].asJson(), true); // writeableNodesOnly = true silently skips
		                                        // read-only nodes instead of failing when
		                                        // encountering a read-only node
	} else {
		// It seems that our file only contained the parameters node, because we don't have Parameters as a subnode;
		// We then use the entire content of the temporary node to rewrite the camera's parameters node
		camera[itmParameters].setJson(tmp.asJson(), true); // with writebleNodesOnly = true, see comment above
	}
} else {
	// File could not be read
	// ...
}

In Halcon, you can use the special parameter ‘do_set_parameters’ for ‘set_framegrabber_param’. It wraps the logic from the C++ code above and automatically loads the right parameters depending on the content of the settings file. You can either give it a JSON value or specify the path to a JSON file with the file://prefix.

* Open the camera and reference the camera's item at path "/Cameras/BySerialNo/1234"
* replace "1234" with your camera's serial number
open_framegrabber ('Ensenso-NxLib', 0, 0, 0, 0, 0, 0, 'default', 0, 'Raw', -1, 'false', 'Stereo', '1234', 0, 0, CameraHandle)

* Load the parameters from the given JSON file into the camera tree
set_framegrabber_param (CameraHandle, 'do_set_parameters', 'file://C:/MyJsonFiles/params.json')

Write parameter file

As explained above there are two options to write the settings file, one containing the entire camera node, and one containing only the parameters subtree. In the example the constant ‘ StoreEntireCameraNode’ switches between these two options.

C++

Halcon/HDevelop

std::ofstream file("params.json");
if (file.is_open()) {
	if (StoreEntireCameraNode) {
		file << camera.asJson(
		    true); // write entire camera node content as JSON with pretty printing into text file
	} else {
		file << camera[itmParameters].asJson(
		    true); // write parameter subtree as JSON with pretty printing into text file
	}
	file.close();
} else {
	// File could not be opened for writing
	// ...
}

if (StoreEntireCameraNode)
        * write entire camera node content as JSON with pretty printing into text file
        get_framegrabber_param (CameraHandle, '/', Params)
        else
        * write parameter subtree as JSON with pretty printing into text file
        get_framegrabber_param (CameraHandle, 'Parameters', Params)
endif
set_framegrabber_param(RootHandle, 'file://C:/MyJsonFiles/Params.json', Params)