API

This chapter documents the core C++ API provided by the common/ library (libcamcom_com). This is the foundation that all adapters and the test bench build upon.

AdapterBase

camcom::common::AdapterBase (camcom/common/adapterBase.hpp) is the central abstract interface. Every camera adapter implements this class.

Connection Management

Method	Description
`Connect() -> map<string, Parameter>`	Connect to the camera and return the initial parameter set read from the device (camera-native names). Throws on failure.
`Disconnect()`	Disconnect from the camera.
`CheckConnection() const -> CheckResult`	Check connection health. Returns `CheckResult{ok, diagnostics}`; `diagnostics` carries human-readable reasons when `ok==false`.
`IsConnected()`	Returns `true` if currently connected.
`SetAddress(const string& address)`	Set the camera address/URI before connecting.
`SetTimeout(double seconds)`	Set the connection timeout in seconds.
`Initialise(const ReceiveCfg& cfg)`	Optional initialization with custom configuration (address, timeout, properties).
`GetProtocol()`	Returns a protocol identifier string (e.g., `"genicam"`, `"Simulation"`).

Parameter Access

All parameter names across the AdapterBase boundary are camera-native. The adapter does no name mapping.

Method	Description
`Read(const string& name)`	Read a single parameter by its camera-native name. Returns a `Parameter` object with the current value.
`Read(const vector<string>& names)`	Batch read multiple parameters. Returns a vector of `Parameter` objects.
`Write(const Parameter& param)`	Write a single parameter to the camera.
`Write(const vector<Parameter>& params)`	Batch write multiple parameters.
`Scan()`	Discover all available parameters from the camera. Returns a vector of `Parameter` objects with metadata (name, type, value, min/max, unit, etc.).
`GetBasicParams()`	Returns a `BasicParams` struct with standardized timing and geometry values (exposure time in seconds, frame rate in Hz, width, height, etc.).
`GetNativeParameterDocument()`	Returns the camera’s native parameter document (e.g., GenICam XML).

Acquisition Control

Method	Description
`StartAcquisition(optional<int64_t> frame_count)`	Start frame acquisition. Pass `nullopt` for continuous mode, or a frame count for finite mode.
`StopAcquisition()`	Stop frame acquisition.
`ReceiveFrame(bool& received, uint64_t max_size, span<uint8_t>& data, FrameInfo& info)`	Receive a single frame. Sets `received` to `true` if a frame was available. Frame data is written into `data`, metadata into `info`.
`GetAcquisitionState()`	Returns the current acquisition state (mode, remaining frames, measured FPS).

Acquisition State

enum class AcqMode {
    Inactive,    // No acquisition
    Continuous,  // Stream until stopped
    Finite       // Acquire N frames then stop
};

struct AcquisitionState {
    AcqMode mode{AcqMode::Inactive};
    std::optional<int64_t> remaining_frames;  // Only if Finite
    double current_fps{0.0};                  // Measured frame rate
};

Factory Functions

Each adapter shared library must export these C functions for dlopen loading:

extern "C" {
    camcom::common::AdapterBase* CreateAdapter();
    void destroyAdapter(camcom::common::AdapterBase* adapter);
}

Parameter

camcom::common::Parameter (camcom/common/parameter.hpp) is a type-safe container for camera parameters.

Construction

// Explicit construction
Parameter(const std::string& name, const Value& value, const DataType& type);

// Template construction (type deduced)
Parameter("ExposureTime", 10000.0);     // DOUBLE
Parameter("Width", int32_t(1024));       // INT32
Parameter("Enabled", true);              // BOOL
Parameter("PixelFormat", "Mono16"s);     // STRING

Methods

Method	Description
`GetName()`	Returns the parameter name.
`GetValue<T>()`	Returns the value cast to type `T`. Throws on type mismatch.
`GetValueAsString()`	Returns the value formatted as a string.
`GetType()`	Returns the `DataType` enum.
`GetTypeAsString()`	Returns the type as a human-readable string.
`Store(name, value, type)`	Replace the stored name, value, and type.
`HasMetadata()`	Returns `true` if metadata is attached.
`GetMetadata()`	Returns a const reference to the `ParameterMetadata`.
`SetMetadata(metadata)`	Attach metadata to this parameter.

DataType

CamCom does not define its own data-type enum. camcom::common::DataType (camcom/common/datatype.hpp) is an alias for the ELT IFW data type ifw::fnd::datatype::DataType (based on the CPL definition), so there is a single source of truth across IFW. The supported values used for parameters and pixel data are:

Supported Data Types
Enum Value	Bit Value	Description
`BYTE`	64	Unsigned 8-bit byte
`BOOL`	128	Boolean
`INT16`	256	Signed 16-bit integer
`UINT16`	512	Unsigned 16-bit integer
`INT32`	1024	Signed 32-bit integer
`UINT32`	2048	Unsigned 32-bit integer
`INT64`	4096	Signed 64-bit integer
`UINT64`	8192	Unsigned 64-bit integer
`FLOAT`	65536	32-bit floating point
`DOUBLE`	131072	64-bit floating point
`STRING`	33	Character array (CHAR \| ARRAY)
`CHAR`	32	Single character
`UNSPECIFIED`	1048576	Unknown / not set
`INVALID`	16	Invalid type

ParameterMetadata

camcom::common::ParameterMetadata (camcom/common/parameterMetadata.hpp) carries optional constraints and descriptive information for a parameter.

ParameterMetadata Fields
Field	Type	Description
`camera_name`	`string`	Native parameter name (before any mapping).
`min`	`optional<double>`	Minimum allowed value (numeric types).
`max`	`optional<double>`	Maximum allowed value (numeric types).
`increment`	`optional<double>`	Step size (used for UI slider/spinbox).
`allowed`	`vector<string>`	List of valid values (for enumerations).
`unit`	`string`	Physical unit (e.g., `"microseconds"`, `"Hz"`).
`description`	`string`	Human-readable description.
`readable`	`bool`	Whether the parameter can be read (default: `true`).
`writable`	`bool`	Whether the parameter can be written (default: `true`).
`default_value`	`optional<Value>`	Default value, if known.

The server’s /parameters/scan endpoint returns parameters with their metadata, enabling the GUI to render appropriate controls (spinboxes with limits, comboboxes for enums, read-only labels, etc.).

FrameInfo

camcom::common::FrameInfo (camcom/common/frameInfo.hpp) carries metadata for a single image frame.

FrameInfo Fields
Field	Type	Description
`start_x`	`int16_t`	ROI X offset in pixels.
`start_y`	`int16_t`	ROI Y offset in pixels.
`width`	`int16_t`	Image width in pixels.
`height`	`int16_t`	Image height in pixels.
`frame_id`	`int64_t`	Frame sequence number.
`timestamp`	`uint64_t`	Camera timestamp in nanoseconds.
`exposure_time_us`	`double`	Exposure time in microseconds.
`data_type`	`DataType`	Pixel data type (e.g., `UINT16`).
`size`	`size_t`	Frame buffer size in bytes.
`meta_data`	`map<string, Value>`	Extensible key-value metadata.

BasicParams

camcom::common::BasicParams (camcom/common/basicParams.hpp) provides a standardized view of camera parameters in common units, independent of the adapter’s native units.

BasicParams Fields
Field	Type	Description
`expo_time_sec`	`double`	Exposure time in seconds.
`frame_rate_hz`	`double`	Frame rate in Hz.
`width`	`uint32_t`	Current image width in pixels.
`height`	`uint32_t`	Current image height in pixels.
`offset_x`	`uint32_t`	ROI X offset.
`offset_y`	`uint32_t`	ROI Y offset.
`bin_x`	`uint32_t`	Horizontal binning factor.
`bin_y`	`uint32_t`	Vertical binning factor.
`sensor_width`	`uint32_t`	Full sensor width in pixels.
`sensor_height`	`uint32_t`	Full sensor height in pixels.
`bytes_per_pixel`	`uint8_t`	Bytes per pixel (1, 2, 4, etc.).
`max_frame_size`	`uint64_t`	Maximum frame buffer size in bytes.

FindFile

camcom::common::FindFile (camcom/common/find_file.hpp) provides centralized file resolution used by both C++ and Python components.

Functions

Function	Description
`ExpandPath(const string& path)`	Expand environment variables (`$VAR`, `${VAR}`) and `~` in a path.
`FindFile(const string& path, const string& referrer)`	Resolve a file path using the CamCom search algorithm. Returns the resolved absolute path, or empty string if not found.

Resolution Algorithm

Expand $VAR, ${VAR}, and ~ in the path.
If the result is an absolute path and exists, use it directly.
If relative, search each directory in CFGPATH (colon-separated environment variable).
Fall back to $INTROOT/resource and $PREFIX/resource.
If a referrer is provided, try the referrer’s directory.
Try the current working directory.
Return empty string if not found.

All resolutions are logged at INFO level.

Note

The Python implementation in testbench/gui/src/camcom/gui/find_file.py follows the same algorithm, ensuring consistent file resolution between the C++ server and the Python GUI.

Logger

CamCom uses the ifw-fnd logging abstraction (ifw/fnd/defs/base.hpp). An application installs a concrete ifw::fnd::Logger (stdout, null, or backend-specific such as log4cplus) once at startup via ifw::fnd::InstallLogger(...); call sites then use the FND* macros below. There is no camcom-specific logger to bootstrap.

Log Levels

Level	Description
ERROR	Errors that may require attention.
WARNING	Unexpected conditions that are handled.
INFO	Informational messages about normal operation.
DEBUG	Diagnostic information for troubleshooting.
TRACE	Detailed tracing of function entry/exit with timing.

Log Macros

The preferred way to log is via the macros, which automatically include source location:

FNDDEBUG("Exposure time set to {:.3f} ms", expo_ms);
FNDINFO("Connected to camera at {}", address);
FNDWARNING("Frame dropped, queue full (size={})", queue_size);
FNDERROR("Failed to open library: {}", dlerror());
FNDTHROW("Invalid data type: {}", type_str);  // Logs and throws

FNDTRACE();                        // Trace function entry/exit with timing
FNDTRACE("acquisition");          // Scope name appears on both ENTERING/LEAVING lines

Note

When adding diagnostic logs, use DEBUG level, not INFO. Leave DEBUG logs in the code for future troubleshooting.

Queue

camcom::common::Queue<T> (camcom/common/queue.hpp) is a thread-safe bounded queue used in the frame pipeline.

Method	Description
`Queue(max_size, id)`	Construct with maximum size and identifier for logging.
`Push(value)`	Add an element. If full, drops the oldest element and logs a warning (throttled to once per 10 seconds).
`Pop(value)`	Remove and return the front element. Returns `false` if empty.
`GetSize()`	Current number of elements in the queue.
`Clear()`	Remove all elements.

ReceiveCfg

camcom::common::ReceiveCfg (camcom/common/receiveCfg.hpp) encapsulates adapter initialization parameters.

Method	Description
`ReceiveCfg(address, timeout)`	Construct with camera address and optional timeout (default: 10s).
`ReceiveCfg(address, properties, timeout)`	Construct with additional key-value properties.
`GetAddress()`	Returns the camera address string.
`GetTimeout()`	Returns the connection timeout duration.
`SetProperty(name, value)`	Set a custom property.
`HasProperty(name)`	Check if a property exists.
`GetPropertyValue(name)`	Get the value of a property.