Adapter Implementations

CamCom ships with three adapter implementations. Each is a shared library loaded at runtime via dlopen.

GenICam Adapter

The GenICam adapter (genicam/adapter/, libcamcom_genicam_arv.so) provides communication with real GenICam/GigE Vision cameras using the Aravis library.

Note

This adapter is only built when the Aravis library is found on the system.

Overview

The adapter implements AdapterBase as a thin wrapper around the Aravis C API. It:

Connects to cameras by IP address, serial number, or arv:// URI.
Discovers all GenICam parameters by parsing the camera’s XML description.
Reads and writes parameters using their GenICam SFNC names (e.g., ExposureTime, AcquisitionFrameRate, PixelFormat).
Receives frames via GigE Vision streaming.
Reports the camera’s native GenICam XML via GetNativeParameterDocument().

Protocol identifier: "genicam"

GenICam Core Library

The GenICam core library (genicam/lib/, libcamcom_genicam.so) provides shared infrastructure used by both the adapter and the emulator.

Node Types

The node model mirrors the GenICam SFNC node types:

GenICam Node Types
Node Type	C++ Type	Description
Integer	`IntegerNode`	64-bit integer with min, max, increment, and unit.
Float	`FloatNode`	Double-precision float with min, max, and unit.
Boolean	`BooleanNode`	True/false value.
String	`StringNode`	Text value with maximum length.
Enumeration	`EnumerationNode`	Named choice from a list of allowed entries.
Command	`CommandNode`	Trigger-style node (execute, then poll `is_done`).
Category	`CategoryNode`	Grouping node listing child features.

Each node has common metadata:

Common Node Fields
Field	Type	Description
`name`	`string`	SFNC name (e.g., `"ExposureTime"`).
`display_name`	`string`	Human-readable label (e.g., `"Exposure Time"`).
`description`	`string`	Description text.
`category`	`string`	Parent category path.
`access`	`AccessMode`	`RO` (read-only), `WO` (write-only), `RW` (read-write), or `NA` (not available).

All nodes are stored in a NodeMap (std::map<std::string, GenICamNode>), where GenICamNode is a std::variant of all node types.

XML Parser

The XmlParser class provides bidirectional GenICam XML parsing:

Method	Description
`parse(xml_content)`	Parse GenICam XML from a string into a `NodeMap`.
`parseFile(file_path)`	Parse GenICam XML from a file.
`serialize(nodes)`	Serialize a `NodeMap` back to GenICam XML.

Type Mapping

The type_mapping module converts between GenICam nodes and CamCom Parameter objects:

Function	Description
`nodeToParameter(node)`	Convert a `GenICamNode` to a CamCom `Parameter` with metadata.
`parameterToNode(param, node)`	Apply a `Parameter` value to a `GenICamNode`.
`pixelFormatToDataType(format)`	Convert a GenICam pixel format string (e.g., `"Mono16"`) to a CamCom `DataType`.
`bytesPerPixel(format)`	Get bytes per pixel for a GenICam format string.

RAII Wrappers

The adapter uses RAII wrappers for safe management of Aravis C resources:

GErrorGuard — RAII for GError*. Auto-frees on destruction.
GObjectGuard<T> — Template RAII for GObject-derived types. Calls g_object_unref on destruction.
Type aliases: DeviceGuard, StreamGuard, BufferGuard, InetAddrGuard.

Configuration Example

includes:
  - "config/camcom/common.yaml"

camcom:
  camera_name: 'Mako_G-158B'
  uri: 'tccd004.hq.eso.org'      # Host name, IP address, or GenICam device id
  timeout: 10

adapter:
  library: 'libcamcom_genicam_arv.so'
  factory_symbol: 'CreateAdapter'

set_values:
  AcquisitionMode: 'Continuous'   # GenICam SFNC names
  ExposureTime: 100000            # Microseconds
  AcquisitionFrameRate: 10        # Hz
  Width: 1456
  Height: 1088
  Gain: 20.0

gui:
  primary_parameters:
    - AcquisitionMode
    - ExposureTime
    - AcquisitionFrameRate
    - Width
    - Height
    - Gain

GenICam Emulator Adapter

The emulator adapter (genicam/emulator/, libcamcom_genicam_emu.so) is an in-process fake GenICam camera. It implements AdapterBase and is loaded via dlopen like any other adapter — no external process, no network, no Aravis dependency.

Protocol identifier: "genicam-emulator"

How It Works

On Connect(), the emulator loads a GenICam XML profile that defines which parameters the camera exposes (names, types, constraints).
It maintains a NodeMap in memory, exactly like a real GenICam camera.
Read() and Write() operate on this node map using GenICam SFNC names.
Scan() returns all nodes as CamCom Parameter objects with metadata.
During acquisition, it generates synthetic frames using FrameGenerator at the frame rate specified in the node tree.

The XML profile is loaded from:

The uri (address) field, if it points to a file.
The adapter.profile config field.
Standard resource locations ($INTROOT/resource, $PREFIX/resource).

Configuration Example

includes:
  - "config/camcom/common.yaml"

camcom:
  camera_name: 'GenICam_Emulator'
  uri: 'emulator'
  timeout: 10

adapter:
  library: 'libcamcom_genicam_emu.so'
  factory_symbol: 'CreateAdapter'
  profile: 'config/camcom/genicam/sfnc/default_camera.xml'

Simulation Adapter

The simulation adapter (simadapter/, libcamcom_sim.so) generates synthetic camera frames for testing and development without any camera hardware.

Protocol identifier: "Simulation"

Simulated Parameters

The adapter exposes the following parameters via Scan():

Acquisition Parameters

Parameter	Type	Description
`acquisition_mode`	STRING	`"Continuous"` or `"Finite"`.
`nb_of_exposures`	INT32	Number of frames in Finite mode.
`exposure_time`	DOUBLE	Exposure time in seconds.
`frame_rate`	DOUBLE	Frame rate in Hz.

Geometry Parameters

Parameter	Type	Description
`width`	INT32	Image width in pixels.
`height`	INT32	Image height in pixels.
`offset_x`	INT32	ROI X offset.
`offset_y`	INT32	ROI Y offset.
`binning_horizontal`	INT32	Horizontal binning factor.
`binning_vertical`	INT32	Vertical binning factor.

Image Parameters

Parameter	Type	Description
`gain`	FLOAT	Gain multiplier.
`sim_data_type`	STRING	Pixel data type: `"UInt8"`, `"UInt16"`, `"Int16"`, `"Int32"`, `"Float32"`, etc.
`sim_type`	STRING	Pattern type (see below).
`sim_file`	STRING	Path to FITS file to use as pattern (when `sim_type = "File"`).

Pattern Types

The simulation adapter supports multiple synthetic image patterns:

Pattern	Description
`Gaussian`	Single moving Gaussian spot (star).
`MultiGaussian`	Multiple Gaussian spots with random movement.
`Flat`	Uniform intensity field.
`Grid`	Regular grid of spots.
`Gradient`	Linear intensity gradient (horizontal, vertical, or radial).
`Ring`	Defocused star pattern (Airy disk / ring).
`Checkerboard`	Alternating black and white squares.
`Noise`	Pure noise (Gaussian or Poisson distribution).
`Grating`	Dispersed spectrum pattern.
`File`	Load image data from a FITS file.

../_images/sim_patterns.jpeg — Examples of simulation adapter pattern types.

Pattern-Specific Parameters

Each pattern exposes additional control parameters:

Gaussian / MultiGaussian:

Parameter	Type	Description
`sim_nb_stars`	INT32	Number of stars.
`sim_amplitude`	FLOAT	Peak intensity.
`sim_sigma`	FLOAT	Gaussian width in pixels.
`sim_nb_planes`	INT32	Number of star planes.
`sim_max_shift`	INT32	Maximum position offset between planes.
`sim_max_shift_per_frame`	INT32	Maximum position change per frame.

Flat:

Parameter	Type	Description
`sim_flat_intensity`	FLOAT	Uniform intensity level.

Grid:

Parameter	Type	Description
`sim_grid_spacing`	INT32	Spacing between spots in pixels.
`sim_spot_size`	FLOAT	Spot radius in pixels.

Gradient:

Parameter	Type	Description
`sim_gradient_dir`	STRING	`"Horizontal"`, `"Vertical"`, or `"Radial"`.
`sim_gradient_start`	FLOAT	Start intensity.
`sim_gradient_end`	FLOAT	End intensity.

Ring:

Parameter	Type	Description
`sim_ring_inner_radius`	FLOAT	Inner radius in pixels.
`sim_ring_outer_radius`	FLOAT	Outer radius in pixels.

Checkerboard:

Parameter	Type	Description
`sim_checker_size`	INT32	Square size in pixels.

Noise:

Parameter	Type	Description
`sim_noise_dist`	STRING	`"Gaussian"` or `"Poisson"`.
`sim_noise_mean`	FLOAT	Mean intensity.
`sim_noise_std`	FLOAT	Standard deviation.

Grating:

Parameter	Type	Description
`sim_grating_dispersion`	FLOAT	Wavelength range.
`sim_grating_wavelength_min`	FLOAT	Minimum wavelength (nm).
`sim_grating_wavelength_max`	FLOAT	Maximum wavelength (nm).
`sim_grating_order`	INT32	Diffraction order.

Configuration Example

includes:
  - "config/camcom/common.yaml"

camcom:
  camera_name: 'SimCamera'
  uri: 'sim://localhost'
  timeout: 10

adapter:
  library: 'libcamcom_sim.so'
  factory_symbol: 'CreateAdapter'

set_values:
  acquisition_mode: 'Continuous'
  exposure_time: 0.5            # Seconds
  frame_rate: 2.0               # Hz
  width: 512
  height: 512
  sim_type: 'MultiGaussian'
  sim_data_type: 'UInt16'
  sim_nb_stars: 10
  sim_amplitude: 10000.0
  sim_sigma: 5.0

gui:
  primary_parameters:
    - acquisition_mode
    - nb_of_exposures
    - exposure_time
    - frame_rate
    - width
    - height

Implementing a New Adapter

To implement a new camera adapter:

Create a directory for your adapter (e.g., myadapter/).

Implement camcom::common::AdapterBase:

#include <camcom/common/adapterBase.hpp>

class MyAdapter : public camcom::common::AdapterBase {
public:
    std::map<std::string, Parameter> Connect() override;
    void Disconnect() override;
    CheckResult CheckConnection() const override;
    std::string GetProtocol() const override { return "myprotocol"; }
    BasicParams GetBasicParams() const override;
    void ReceiveFrame(bool& received, uint64_t max_size,
                      std::span<uint8_t>& data, FrameInfo& info) override;
    Parameter Read(const std::string& name) override;
    std::vector<Parameter> Read(const std::vector<std::string>& names) override;
    void Write(const Parameter& param) override;
    void Write(const std::vector<Parameter>& params) override;
    std::vector<Parameter> Scan() override;
    AcquisitionState GetAcquisitionState() const override;
    void StartAcquisition(std::optional<int64_t> frame_count) override;
    void StopAcquisition() override;
};

Export factory functions:

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

Build as a shared library (e.g., libcamcom_myadapter.so).

Create a YAML config that references your library:

adapter:
  library: 'libcamcom_myadapter.so'
  factory_symbol: 'CreateAdapter'

Run the server with your config:

camcomServer -c config/camcom/my_camera.yaml -l DEBUG -v

The adapter depends only on common/ (libcamcom_com). It has no compile-time dependency on the test bench.