Deployment & Examples

This chapter covers building, installing, configuring, and running CamCom.

Building

Prerequisites

• C++20 compiler (GCC 10+, Clang 12+)

• CMake 3.10+

• Required libraries: yaml-cpp, fmt, cfitsio, httplib

• Optional: Aravis (for GenICam adapter), GTest (for tests)

• Python 3 with PyQt6, NumPy (for GUI)

Build Systems

CamCom supports two build systems that coexist in the repository:

• cmake/make — the primary build system, used for VLT and standalone builds.

• waf/wtools — the ELT standard build system, used for ELT IFW integration.

Both produce the same installed layout. Use whichever matches your environment.

cmake/make (VLT and standalone)

CamCom uses CMake, wrapped by a convenience make script:

cd camcom
make build install    # Build and install to $PREFIX

cmake/make Targets

Target	Description
make configure	Prepare CMake build environment.
make build	Build all libraries and executables.
make debug	Build with debug symbols.
make install	Install to $PREFIX (or $INTROOT).
make uninstall	Remove installed files.
make test	Run unit tests.
make itest	Run integration tests.
make coverage	Run all tests with code coverage.
make doc	Build documentation (Sphinx user manual).
make clean	Clean build artifacts (keeps CMake cache).
make distclean	Remove entire build directory.

Verbosity levels: -v (basic), -vv (CMake verbose), -vvv (Make verbose), -vvvv (full verbose).

waf/wtools (ELT integration)

For ELT environments where waf and wtools are available:

cd camcom
waf configure build install    # Build and install
waf test --alltests            # Run unit tests

The waf build uses wscript files at each module level, following the ELT wtools conventions (declare_project, declare_cshlib, declare_cprogram, declare_pyprogram, declare_sphinx).

waf/wtools wscript files

Location	Function
wscript	Top-level project: declare_project, configure()
common/wscript	declare_cshlib(target='camcom_com')
simadapter/wscript	declare_cshlib(target='camcom_sim')
genicam/wscript	declare_package(recurse='lib emulator adapter')
genicam/lib/wscript	declare_cshlib(target='camcom_genicam')
genicam/emulator/wscript	declare_cshlib(target='camcom_genicam_emu')
genicam/adapter/wscript	declare_cshlib(target='camcom_genicam_arv')
testbench/wscript	declare_package(recurse='lib app gui')
testbench/lib/wscript	declare_cshlib(target='camcom_testbench_lib')
testbench/app/wscript	declare_cprogram(target='camcomServer')
testbench/gui/wscript	declare_pyprogram(target='camcomGui')
tools/wscript	declare_package(recurse='demo')
tools/demo/wscript	Installs camcomDemoStart / camcomDemoStop to $PREFIX/bin via declare_custom().
doc/manual/wscript	declare_sphinx(...) (HTML + PDF)

Installed Layout

After installation (via either build system), the following is deployed under $PREFIX:

Path	Contents
bin/camcomServer	Server executable.
bin/camcomGui	PyQt6 GUI client.
bin/camcomDemoStart	Convenience script: start the simulated demo environment.
bin/camcomDemoStop	Convenience script: stop the simulated demo environment.
lib64/libcamcom_com.so	Common library (core interfaces).
lib64/libcamcom_sim.so	Simulation adapter.
lib64/libcamcom_genicam.so	GenICam core library (node model, parser).
lib64/libcamcom_genicam_emu.so	GenICam emulator adapter.
lib64/libcamcom_genicam_arv.so	GenICam production adapter (if Aravis found).
share/camcom/	camcomGui Python package.
resource/config/camcom/	YAML configuration files.
include/camcom/	C++ header files.

Configuration Reference

CamCom is entirely config-driven. All configuration is in YAML files.

Config File Resolution

Config files support includes for layering. A typical pattern:

includes:
  - "config/camcom/common.yaml"    # Shared defaults

camcom:
  camera_name: 'MyCamera'          # Camera-specific overrides
  ...

Included files are resolved using the FindFile algorithm (see API). Values in the main file override those from includes.

Configuration Sections

CamCom Section

Key	Type	Description
camera_name	string	Display name for the camera.
uri	string	Camera address: IP address, serial number, or protocol URI.
timeout	int	Connection timeout in seconds (default: 10).

Adapter Section

Key	Type	Description
library	string	Adapter shared library filename (e.g., libcamcom_sim.so).
factory_symbol	string	Factory function name (default: CreateAdapter).
auto_connect	bool	Auto-connect on server start (default: false).
profile	string	GenICam XML profile path (for emulator).

HTTP Server Section

Key	Type	Description
host	string	Listen address (default: 0.0.0.0).
port	int	Listen port (default: 8080).

Setup Section

Key	Type	Description
auto_adjust_expo_time_rate	bool	Auto-adjust when exposure time and frame rate conflict.
auto_stop_acq_on_par_write	bool	Stop acquisition during parameter writes, restart after.
ignore_write_protected_pars	bool	Skip write-protected parameters with a warning.

Acquisition Section

Key	Type	Description
frame_queue_size	int	Capture-to-publisher queue size (default: 10).
skip_silently	bool	Drop frames silently vs. log warnings (default: true).

Web Interface Section

Key	Type	Description
enabled	bool	Enable web interface (default: true).
max_image_width	int	Maximum display image width in pixels (default: 640).
max_image_height	int	Maximum display image height in pixels (default: 480).
max_fps	int	Server-side display rate limit (default: 5).
compression	string	"raw" (native) or "jpeg" (8-bit). Default: "raw".
quality	int	JPEG quality 1-100 (default: 85).

Streaming Section

Key	Type	Description
enabled	bool	Enable real-time streaming (default: false).
protocol	string	"websocket" or "http_polling" (default: "websocket").

Recording Section

Key	Type	Description
directory	string	Output directory (supports $DATAROOT).
format	string	"fits", "fits:cube", or "fits:mef" (default: "fits").
compression	string	"none", "rice", "gzip", "hcompress", "plio".
file_id	string	Identifier prefix in filenames.
filename_pattern	string	Filename pattern with variables: ${file_id}, ${camera_name}, ${timestamp}, ${frame_id}.
nb_of_frames	int	Stop after N frames (0 = unlimited).
period	double	Maximum recording duration in seconds (0 = unlimited).
max_size	int	Maximum file size in MB (0 = unlimited).
max_frames_buffer	int	Recording queue size (default: 100).
overwrite_policy	string	"overwrite" or "increment" (default: "increment").
cube_timestamp_table	bool	Write per-frame timestamps in cube mode (default: false).
trigger	string	"immediate", "delay", or "absolute".
delay	int	Delay in seconds (when trigger is "delay").
start_time	string	ISO8601 timestamp (when trigger is "absolute").

Telemetry Section

Key	Type	Description
enabled	bool	Enable telemetry sampling (default: true).
sampling_period	double	Seconds between samples (default: 2.0).
disable_during_acquisition	bool	Pause sampling during acquisition.
disable_during_recording	bool	Pause sampling during recording.
sample_read_only_pars	bool	Auto-sample read-only parameters.
parameters	list	Extra parameter names to sample.
history_depth	int	Samples to keep per parameter (default: 100).

Statistics Section

Key	Type	Description
enabled	bool	Enable statistics collection (default: true).
window_size	int	Sliding window size in samples (default: 100).

Logging Section

Key	Type	Description
level	string	Log level: ERROR, WARNING, INFO, DEBUG, TRACE.
file	string	Log file path (supports $HOME).
rotation	string	"daily", "weekly", or "size".
max_files	int	Maximum rotated log files to keep (default: 7).

GUI Section

Key	Type	Description
start_srv	bool	Auto-start server from GUI (default: false).
auto_restart	bool	Auto-restart server on crash (default: false).
restart_timeout	int	Seconds before restart attempt (default: 5).
log_level	string	GUI log level.
log_file	string	GUI log file path.
statistics_poll_period	double	Statistics poll interval in seconds (default: 2.0).
primary_parameters	list	Parameter names to show first in the Set Values tab, in order.

Set Values Section

The set_values section is a flat map of parameter names to values. These are applied to the camera after connection, using camera-native names:

set_values:
  ExposureTime: 100000          # Microseconds (GenICam)
  AcquisitionFrameRate: 10      # Hz
  Width: 1024
  Height: 768

Parameter Registry

The adapter.parameter_registry section defines metadata for parameters the server manages:

adapter:
  parameter_registry:
    ExposureTime:
      type: Float
      unit: microseconds
      min: 10.0
      max: 10000000.0
      write_access: true
    mode:
      type: Int32
      allowed: [0, 1]
      internal: true           # CamCom-internal, not on camera

Fields:

Field	Description
type	Data type: Int32, Float, String, Bool, etc.
min, max	Numeric constraints.
allowed	List of valid values (for enumerations).
unit	Physical unit description.
write_access	Whether writable (default: true).
internal	If true, managed by CamCom, not read from/written to camera.

Usage Examples

Example 1: Simulated Camera

The simplest way to try CamCom — no hardware needed:

# Start server with simulation adapter
camcomServer -c config/camcom/example_sim.yaml -l DEBUG -v

# In another terminal, start GUI
camcomGui -c config/camcom/example_sim.yaml -l INFO -v

Or use the convenience scripts:

camcomDemoStart            # Starts server + GUI
camcomDemoStop             # Stops both

Example 2: GenICam Emulator

Test GenICam parameter handling without real hardware:

# Start server with emulator adapter (loads XML profile)
camcomServer -c config/camcom/example_genicam_emulator.yaml -l DEBUG -v

# Start GUI
camcomGui -c config/camcom/example_genicam_emulator.yaml -l INFO -v

The emulator exposes all parameters from the XML profile with GenICam SFNC names (ExposureTime, Width, PixelFormat, etc.).

Example 3: Real GenICam Camera

For a real GigE Vision camera (requires Aravis):

# Start server (connects to camera at tccd004.hq.eso.org)
camcomServer -c config/camcom/example_avt_mako_g_158b.yaml -l DEBUG -v

# Start GUI
camcomGui -c config/camcom/example_avt_mako_g_158b.yaml -l INFO -v

Example 4: Remote GUI

Connect a GUI to a server running on another host:

# On the server machine
camcomServer -c config/camcom/example_sim.yaml -l INFO -v

# On the client machine (any network-accessible host)
camcomGui -u http://server-host:8080 -l INFO -v

Example 5: Web Dashboard

Open a browser and navigate to the server URL:

http://localhost:8080/

The web dashboard provides status monitoring, acquisition control, and live image display without installing any client software.

Example 6: Recording FITS Files

Configure recording in YAML:

recording:
  directory: '/tmp/camcom/data'
  format: 'fits:cube'         # 3D cube (all frames in one file)
  compression: 'rice'         # FITS tile compression
  nb_of_frames: 100           # Stop after 100 frames
  cube_timestamp_table: true  # Include per-frame timestamps

Then start recording via the GUI’s Recording tab, or via the HTTP API:

curl -X POST http://localhost:8080/recording/start
# ... wait ...
curl -X POST http://localhost:8080/recording/stop

Environment Variables

Variable	Description
PREFIX	Installation prefix (used by build and FindFile).
INTROOT	Alternative installation prefix (fallback for PREFIX).
CFGPATH	Colon-separated list of directories for config file search.
DATAROOT	Default data output directory (used in recording config).
HOME	User home directory (used for log files, preferences).

Helper Scripts

Two convenience wrappers are installed under $PREFIX/bin to spin up the simulated-camera demo environment without having to remember the right config path or argument order. Source lives in camcom/tools/demo/src/; the build system (waf and CMake both) installs them as executables.

camcomDemoStart

Starts the demo environment (server + GUI):

camcomDemoStart            # Start server and GUI
camcomDemoStart --no-gui   # Start server only

The script:

1. Stops any existing CamCom demo environment.

2. Starts camcomServer with the sim adapter config (example_sim.yaml).

3. Starts camcomGui (unless --no-gui).

4. Saves process IDs to /tmp/camcom_demo.pids.

camcomDemoStop

Stops the demo environment:

camcomDemoStop

Gracefully stops the GUI and server processes tracked in the PID file.