This class implements a manager for camera calibrations using a modern JSON-based format. More...

#include <CameraCalibrationManager.h>

Inheritance diagram for Ocean::IO::CameraCalibrationManager:

Data Structures
class	CalibrationGroup
	This class stores multiple camera calibrations with the same priority. More...

Public Types
enum	DeviceContextLevel : uint32_t { DCL_NONE = 0u , DCL_PRODUCT , DCL_VERSION , DCL_SERIAL }
	Definition of different device context levels. More...

enum	CalibrationQuality : uint32_t { CQ_UNKNOWN = 0u , CQ_INTERPOLATED , CQ_EXACT }
	Definition of different calibration qualities indicating how the calibration was obtained. More...

using	FactoryFunction = std::function< SharedAnyCamera(const JSONParser::JSONValue &modelObject)>
	Definition of a factory function that creates a SharedAnyCamera from a JSON model object.

Public Member Functions
SharedAnyCamera	camera (const std::string &cameraName, unsigned int width, unsigned int height, CalibrationQuality *calibrationQuality=nullptr) const
	Returns a camera for a given camera name and resolution.

bool	setDeviceProduct (const std::string &product)
	Sets the device context to a specific product name.

bool	setDeviceVersion (const std::string &version)
	Sets the device context to a specific hardware version/variant.

bool	setDeviceSerial (const std::string &serial)
	Sets the device context to a specific device serial number.

void	clearDeviceContext ()
	Clears the device context.

bool	registerCalibrations (const std::string &url)
	Registers calibrations from a JSON file.

bool	registerCalibrations (const void *buffer, const size_t size)
	Registers calibrations from a memory buffer containing JSON data.

bool	registerCalibrations (const JSONParser::JSONValue &jsonValue)
	Registers calibrations from a parsed JSON value.

bool	registerCamera (const std::string &cameraName, SharedAnyCamera &&camera, const int32_t priority)
	Registers a single camera calibration with a specific priority.

bool	registerFactoryFunction (const std::string &modelName, FactoryFunction &&factoryFunction)
	Registers a new camera factory for a specific camera type.

SharedAnyCamera	parseCamera (const std::string &jsonCameraCalibrationFile, std::string &&jsonCameraCalibration=std::string()) const
	Parses one camera calibration from a file or a string/buffer containing the JSON calibration object for only one camera model.

void	clear ()
	Clears all registered calibrations and aliases.

Static Public Member Functions
static bool	parseResolution (const JSONParser::JSONValue &calibrationObject, unsigned int &width, unsigned int &height)
	Parses the resolution of a camera from a JSON calibration object.

Static Public Member Functions inherited from Ocean::Singleton< CameraCalibrationManager >
static CameraCalibrationManager &	get ()
	Returns a reference to the unique object.

Protected Types
using	CalibrationGroups = std::vector< CalibrationGroup >
	Definition of a vector holding calibration groups.

using	FactoryFunctionMap = std::unordered_map< std::string, FactoryFunction >
	Definition of a map mapping camera model names to factory functions.

using	CameraMap = std::unordered_map< std::string, CalibrationGroups >
	Definition of a map mapping camera names to calibration groups.

using	AliasMap = std::unordered_map< std::string, std::string >
	Definition of a map mapping camera aliases to their actual camera names.

Protected Member Functions
	CameraCalibrationManager ()
	Protected default constructor.

bool	registerCameras (const JSONParser::JSONValue::Array &camerasArray, const std::string &deviceProduct=std::string(), const std::string &deviceVersion=std::string(), const std::string &deviceSerial=std::string())
	Registers cameras from a JSON cameras array with optional device context.

Protected Member Functions inherited from Ocean::Singleton< CameraCalibrationManager >
	Singleton ()=default
	Default constructor.

Static Protected Member Functions
static SharedAnyCamera	createOceanPinhole (const JSONParser::JSONValue &modelObject)
	Factory function able to create the "Ocean Pinhole" camera model from a JSON configuration.

static SharedAnyCamera	createOceanFisheye (const JSONParser::JSONValue &modelObject)
	Factory function able to create the "Ocean Fisheye" camera model from a JSON configuration.

Protected Attributes
FactoryFunctionMap	factoryFunctionMap_
	The map mapping camera model names to factory functions.

CameraMap	cameraMap_
	The map mapping camera names to calibration groups.

AliasMap	aliasMap_
	The map mapping camera aliases to their actual camera names.

DeviceContextLevel	deviceContextLevel_ = DCL_NONE
	The current device context level.

std::string	deviceContextValue_
	The current device context value (product, version, or serial depending on deviceContextLevel_).

Lock	lock_
	The lock for thread-safe access to all manager data.

Friends
class	Singleton< CameraCalibrationManager >

Detailed Description

This class implements a manager for camera calibrations using a modern JSON-based format.

The manager supports multiple camera types through a factory pattern and can be extended with custom camera types.

The manager supports device-specific calibrations through a device context system. Device context can be set at three specificity levels: product, version, or serial number. This allows users to specify simple camera names (e.g., "Back-facing Camera 0") and the manager automatically matches the appropriate calibration based on the current device context.

Device Context Levels (from least to most specific):

Product: Broad product category (e.g., "Samsung S21 5G", "iPhone 13 Pro")
Version: Specific hardware variant (e.g., "SM-G991U", "A2483")
Serial: Individual device serial number (e.g., "ABC123456")

By default, the manager supports "Ocean Pinhole" and "Ocean Fisheye" camera models, an example JSON file is:

{
  "devices": [
    {
      "product": "Samsung S21 5G",
      "version": "SM-G991U",
      "serial": "ABC123456",
      "cameras": [
        {
          "name": "Back-facing Camera 0",
          "priority": 10,
          "calibrations": [...]
        }
      ]
    },
    {
      "product": "Samsung S21 5G",
      "version": "SM-G991U",
      "cameras": [...]
    }
  ],
  "cameras": [
    {
      "name": "Generic Camera",
      "aliases": ["Optional Alias 1", "Optional Alias 2"],
      "priority": 10,
      "calibrations": [
        {
          "resolution": {"width": 1920, "height": 1080},
          "model": "Ocean Pinhole",
          "configuration": "8_PARAMETERS",
          "parameters": [fx, fy, mx, my, k1, k2, p1, p2]
          "comment": "fully calibrated camera"
        },
        {
          "resolution": {"width": 640, "height": 480},
          "model": "Ocean Pinhole",
          "fovx": "1.05",
          "comment": "manually calibrate camera with approx. 60 degree of horizontal field of view"
        }
      ]
    }
  ]
}

Member Typedef Documentation

◆ AliasMap

using Ocean::IO::CameraCalibrationManager::AliasMap = std::unordered_map<std::string, std::string>

protected

Definition of a map mapping camera aliases to their actual camera names.

◆ CalibrationGroups

using Ocean::IO::CameraCalibrationManager::CalibrationGroups = std::vector<CalibrationGroup>

protected

Definition of a vector holding calibration groups.

◆ CameraMap

using Ocean::IO::CameraCalibrationManager::CameraMap = std::unordered_map<std::string, CalibrationGroups>

protected

Definition of a map mapping camera names to calibration groups.

◆ FactoryFunction

using Ocean::IO::CameraCalibrationManager::FactoryFunction = std::function<SharedAnyCamera(const JSONParser::JSONValue& modelObject)>

Definition of a factory function that creates a SharedAnyCamera from a JSON model object.

Parameters

modelObject The JSON object containing the camera model calibration, must be valid

Returns: The created camera object, nullptr if creation failed

◆ FactoryFunctionMap

using Ocean::IO::CameraCalibrationManager::FactoryFunctionMap = std::unordered_map<std::string, FactoryFunction>

protected

Definition of a map mapping camera model names to factory functions.

Member Enumeration Documentation

◆ CalibrationQuality

enum Ocean::IO::CameraCalibrationManager::CalibrationQuality : uint32_t

Definition of different calibration qualities indicating how the calibration was obtained.

Enumerator
CQ_UNKNOWN	Unknown or invalid calibration quality.
CQ_INTERPOLATED	The calibration was interpolated from a calibration with a different resolution but the same aspect ratio.
CQ_EXACT	The calibration exactly matches the requested resolution.

◆ DeviceContextLevel

enum Ocean::IO::CameraCalibrationManager::DeviceContextLevel : uint32_t

Definition of different device context levels.

The device context determines which cameras are visible during lookup operations.

Enumerator
DCL_NONE	No device context is set, only global cameras (without device context) are visible.
DCL_PRODUCT	Device context is set to a product name (least specific).
DCL_VERSION	Device context is set to a hardware version/variant.
DCL_SERIAL	Device context is set to a device serial number (most specific).

Constructor & Destructor Documentation

◆ CameraCalibrationManager()

Ocean::IO::CameraCalibrationManager::CameraCalibrationManager ( )

protected

Protected default constructor.

Automatically registers the built-in factory functions for "Ocean Pinhole" and "Ocean Fisheye" camera models.

Member Function Documentation

◆ camera()

SharedAnyCamera Ocean::IO::CameraCalibrationManager::camera	(	const std::string &	cameraName,
		unsigned int	width,
		unsigned int	height,
		CalibrationQuality *	calibrationQuality = `nullptr`
	)		const

Returns a camera for a given camera name and resolution.

The function will find the best matching calibration for the given resolution.
First, it searches for exact resolution matches. If none are found, it attempts to interpolate from calibrations with the same aspect ratio.
When multiple calibrations are available, the one with the highest priority and best quality is selected. The camera lookup is filtered based on the current device context (if set).

Parameters

cameraName	The name of the camera (or alias), must be valid
width	The width of the camera image in pixels, with range [1, infinity)
height	The height of the camera image in pixels, with range [1, infinity)
calibrationQuality	Optional resulting calibration quality, nullptr if not of interest

Returns: The camera model, nullptr if no matching calibration was found

See also: setDeviceProduct(), setDeviceVersion(), setDeviceSerial()

◆ clear()

void Ocean::IO::CameraCalibrationManager::clear ( )

Clears all registered calibrations and aliases.

This function does not remove registered factory functions.

◆ clearDeviceContext()

void Ocean::IO::CameraCalibrationManager::clearDeviceContext ( )

Clears the device context.

After clearing, only global cameras (without device context) will be visible during lookup.

◆ createOceanFisheye()

static SharedAnyCamera Ocean::IO::CameraCalibrationManager::createOceanFisheye ( const JSONParser::JSONValue & modelObject )

staticprotected

Factory function able to create the "Ocean Fisheye" camera model from a JSON configuration.

Parameters

modelObject The JSON object containing the camera model configuration, must be valid

Returns: The created camera object, nullptr if creation failed

◆ createOceanPinhole()

static SharedAnyCamera Ocean::IO::CameraCalibrationManager::createOceanPinhole ( const JSONParser::JSONValue & modelObject )

staticprotected

Factory function able to create the "Ocean Pinhole" camera model from a JSON configuration.

Parameters

modelObject The JSON object containing the camera model configuration, must be valid

Returns: The created camera object, nullptr if creation failed

◆ parseCamera()

SharedAnyCamera Ocean::IO::CameraCalibrationManager::parseCamera	(	const std::string &	jsonCameraCalibrationFile,
		std::string &&	jsonCameraCalibration = `std::string()`
	)		const

Parses one camera calibration from a file or a string/buffer containing the JSON calibration object for only one camera model.

The provided JSON object must have the following structure:

{
   "resolution": {"width": <WIDTH_IN_PIXELS>, "height": <HEIGHT_IN_PIXELS>},
   "model": "<MODEL_NAME>",
   "configuration": "<PARAMETER_CONFIGURATION>",
   "parameters": [<PARAMETER_1>, <PARAMETER_2>, ...],
}

Parameters

jsonCameraCalibrationFile	The file path of the JSON calibration file, empty in case a buffer is provided via 'jsonCameraCalibrationBuffer'
jsonCameraCalibrationBuffer	The JSON string/buffer containing the camera calibration, empty in case a file is provided via 'jsonCameraCalibrationFile'

Returns: The parsed camera object, nullptr in case of an error

◆ parseResolution()

static bool Ocean::IO::CameraCalibrationManager::parseResolution	(	const JSONParser::JSONValue &	calibrationObject,
		unsigned int &	width,
		unsigned int &	height
	)

static

Parses the resolution of a camera from a JSON calibration object.

Parameters

calibrationObject	The JSON calibration object, must be valid
width	The resulting width in pixels
height	The resulting height in pixels

Returns: True if the resolution was parsed successfully

◆ registerCalibrations() [1/3]

bool Ocean::IO::CameraCalibrationManager::registerCalibrations ( const JSONParser::JSONValue & jsonValue )

Registers calibrations from a parsed JSON value.

Parameters

jsonValue The parsed JSON value, must be a valid object holding the calibration

Returns: True if the calibrations were registered successfully, false otherwise

◆ registerCalibrations() [2/3]

bool Ocean::IO::CameraCalibrationManager::registerCalibrations ( const std::string & url )

Registers calibrations from a JSON file.

Parameters

url	The URL or file path of the JSON calibration file, must be valid

Returns: True if the calibrations were registered successfully, false otherwise

◆ registerCalibrations() [3/3]

bool Ocean::IO::CameraCalibrationManager::registerCalibrations	(	const void *	buffer,
		const size_t	size
	)

Registers calibrations from a memory buffer containing JSON data.

Parameters

buffer	The memory buffer containing the JSON calibration data, must be valid
size	The size of the buffer in bytes, with range [1, infinity)

Returns: True if the calibrations were registered successfully, false otherwise

◆ registerCamera()

bool Ocean::IO::CameraCalibrationManager::registerCamera	(	const std::string &	cameraName,
		SharedAnyCamera &&	camera,
		const int32_t	priority
	)

Registers a single camera calibration with a specific priority.

Parameters

cameraName	The name of the camera, must be valid
camera	The camera model to register, must be valid
priority	The priority of this calibration, higher values indicate higher priority, with range (-infinity, infinity)

Returns: True if the camera was registered successfully

See also: registerCalibrations()

◆ registerCameras()

bool Ocean::IO::CameraCalibrationManager::registerCameras	(	const JSONParser::JSONValue::Array &	camerasArray,
		const std::string &	deviceProduct = `std::string()`,
		const std::string &	deviceVersion = `std::string()`,
		const std::string &	deviceSerial = `std::string()`
	)

protected

Registers cameras from a JSON cameras array with optional device context.

Parameters

camerasArray	The JSON array containing camera definitions, must be valid
deviceProduct	Optional device product name, empty for global cameras
deviceVersion	Optional device version, empty for global cameras
deviceSerial	Optional device serial number, empty for global cameras

Returns: True if at least one camera was registered successfully

◆ registerFactoryFunction()

bool Ocean::IO::CameraCalibrationManager::registerFactoryFunction	(	const std::string &	modelName,
		FactoryFunction &&	factoryFunction
	)

Registers a new camera factory for a specific camera type.

Factory functions are used to create camera objects from JSON model configurations.

Parameters

modelName	The name of the camera model, e.g., "Custom Camera", must be valid
factoryFunction	The factory function to create cameras of the specified model, nullptr to unregister a factory

Returns: True if the factory was registered successfully, false if a factory for the same model name already exists

◆ setDeviceProduct()

bool Ocean::IO::CameraCalibrationManager::setDeviceProduct ( const std::string & product )

Sets the device context to a specific product name.

When set, only cameras associated with this product (and no version/serial constraints) will be visible during lookup.

Parameters

product The product name (e.g., "Samsung S21 5G", "iPhone 13 Pro"), must be valid

Returns: True if the device context was set successfully

See also: clearDeviceContext()

◆ setDeviceSerial()

bool Ocean::IO::CameraCalibrationManager::setDeviceSerial ( const std::string & serial )

Sets the device context to a specific device serial number.

When set, only cameras associated with this exact serial number will be visible during lookup.

Parameters

serial The device serial number (e.g., "ABC123456"), must be valid

Returns: True if the device context was set successfully

See also: clearDeviceContext()

◆ setDeviceVersion()

bool Ocean::IO::CameraCalibrationManager::setDeviceVersion ( const std::string & version )

Sets the device context to a specific hardware version/variant.

When set, only cameras associated with this version will be visible during lookup.

Parameters

version The hardware version/variant identifier (e.g., "SM-G991U", "A2483"), must be valid

Returns: True if the device context was set successfully

See also: clearDeviceContext()

Friends And Related Symbol Documentation

◆ Singleton< CameraCalibrationManager >

friend class Singleton< CameraCalibrationManager >

friend

Field Documentation

◆ aliasMap_

AliasMap Ocean::IO::CameraCalibrationManager::aliasMap_

protected

The map mapping camera aliases to their actual camera names.

◆ cameraMap_

CameraMap Ocean::IO::CameraCalibrationManager::cameraMap_

protected

The map mapping camera names to calibration groups.

◆ deviceContextLevel_

DeviceContextLevel Ocean::IO::CameraCalibrationManager::deviceContextLevel_ = DCL_NONE

protected

The current device context level.

◆ deviceContextValue_

std::string Ocean::IO::CameraCalibrationManager::deviceContextValue_

protected

The current device context value (product, version, or serial depending on deviceContextLevel_).

◆ factoryFunctionMap_

FactoryFunctionMap Ocean::IO::CameraCalibrationManager::factoryFunctionMap_

protected

The map mapping camera model names to factory functions.

◆ lock_

Lock Ocean::IO::CameraCalibrationManager::lock_

mutableprotected

The lock for thread-safe access to all manager data.

The documentation for this class was generated from the following file:

CameraCalibrationManager.h

Data Structures

Public Types

Public Member Functions

Static Public Member Functions

Protected Types

Protected Member Functions

Static Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Typedef Documentation

◆ AliasMap

◆ CalibrationGroups

◆ CameraMap

◆ FactoryFunction

◆ FactoryFunctionMap

Member Enumeration Documentation

◆ CalibrationQuality

◆ DeviceContextLevel

Constructor & Destructor Documentation

◆ CameraCalibrationManager()

Member Function Documentation

◆ camera()

◆ clear()

◆ clearDeviceContext()

◆ createOceanFisheye()

◆ createOceanPinhole()

◆ parseCamera()

◆ parseResolution()

◆ registerCalibrations() [1/3]

◆ registerCalibrations() [2/3]

◆ registerCalibrations() [3/3]

◆ registerCamera()

◆ registerCameras()

◆ registerFactoryFunction()

◆ setDeviceProduct()

◆ setDeviceSerial()

◆ setDeviceVersion()

Friends And Related Symbol Documentation

◆ Singleton< CameraCalibrationManager >

Field Documentation

◆ aliasMap_

◆ cameraMap_

◆ deviceContextLevel_

◆ deviceContextValue_

◆ factoryFunctionMap_

◆ lock_