irsol::camera::Interface Class Reference

High-level wrapper around the NeoAPI camera for synchronized access. More...

#include <interface.hpp>

Public Types
using	image_t = NeoAPI::Image
	Alias for the image type returned by the NeoAPI.
using	camera_param_t = std::variant< bool, int, int64_t, double, std::string, const char * >
	Union of all supported types for camera parameters.

Public Member Functions
	Interface (NeoAPI::Cam cam=irsol::utils::loadDefaultCamera())
	Constructs the Interface by loading the default camera.
	Interface (Interface &&other)
	Move constructor.
Interface &	operator= (Interface &&other)
	Move assignment operator.
std::string	cameraInfoAsString () const
	Get human-readable camera information.
std::string	cameraStatusAsString () const
	Get current camera status.
NeoAPI::Cam &	getNeoCam ()
	Access the underlying NeoAPI camera instance.
bool	isConnected () const
	Check if the camera is currently connected.
void	resetSensorArea ()
	Reset the sensor area to the full sensor dimensions.
irsol::types::duration_t	getExposure () const
	Get the current exposure time from the camera.
irsol::types::duration_t	setExposure (irsol::types::duration_t exposure)
	Set the exposure time of the camera.
template<typename T , std::enable_if_t< std::is_integral_v< T >||std::is_floating_point_v< T >||std::is_same_v< std::string, T >, int > = 0>
T	getParam (const std::string &param) const
	Retrieve a camera parameter of arbitrary type T.
std::string	getParam (const std::string &param) const
	Retrieve a camera parameter and convert it to string.
template<typename T , std::enable_if_t< std::is_integral_v< std::decay_t< T > >||std::is_floating_point_v< std::decay_t< T > >||std::is_same_v< std::decay_t< T >, std::string >, int > = 0>
T	setParam (const std::string &param, T value)
	Set a camera parameter of arbitrary type T.
template<typename T , std::enable_if_t< std::is_same_v< std::decay_t< T >, const char * >, int > = 0>
std::string	setParam (const std::string &param, T value)
	Specialization for setting const char* values as strings.
void	setMultiParam (const std::unordered_map< std::string, camera_param_t > &params)
	Set multiple parameters in one call.
void	trigger (const std::string &param)
	Trigger a camera feature (e.g., software trigger).
image_t	captureImage (std::optional< irsol::types::duration_t > timeout=std::nullopt)
	Capture a single image from the camera.

Static Public Member Functions
static Interface	FullResolution ()
	Factory method to create a camera interface using full sensor resolution.
static Interface	HalfResolution ()
	Factory method to create a camera interface using half sensor resolution.

Static Public Attributes
static constexpr irsol::types::duration_t	DEFAULT_EXPOSURE_TIME = std::chrono::milliseconds(2)
	Default exposure time (2 milliseconds) used to initialize the camera.

Private Member Functions
template<typename T , std::enable_if_t< std::is_integral_v< std::decay_t< T > >||std::is_floating_point_v< std::decay_t< T > >||std::is_same_v< std::decay_t< T >, std::string >||std::is_same_v< std::decay_t< T >, const char * >, int > = 0>
void	setParamNonThreadSafe (const std::string &param, T value)
	Internal, non-thread-safe parameter setter used by setParam.

Private Attributes
std::mutex	m_camMutex
	Mutex to protect access to camera parameters and image acquisition.
NeoAPI::Cam	m_cam
	Internal camera instance from NeoAPI.
irsol::types::duration_t	m_CachedExposureTime

Detailed Description

High-level wrapper around the NeoAPI camera for synchronized access.

The Interface class provides thread-safe control over camera acquisition and configuration via NeoAPI. It abstracts common camera operations such as setting exposure, retrieving and setting camera parameters, capturing images, and managing sensor state.

Note

The underlying NeoAPI camera must be usable with a pixel format Mono12. Failure to run in this modality will lead to the Interface constructor to raise a fatal assertion.

Definition at line 60 of file interface.hpp.

Member Typedef Documentation

camera_param_t

using irsol::camera::Interface::camera_param_t = std::variant<bool, int, int64_t, double, std::string, const char*>

Union of all supported types for camera parameters.

Definition at line 67 of file interface.hpp.

image_t

using irsol::camera::Interface::image_t = NeoAPI::Image

Alias for the image type returned by the NeoAPI.

Definition at line 64 of file interface.hpp.

Constructor & Destructor Documentation

Interface() [1/2]

irsol::camera::Interface::Interface

(

NeoAPI::Cam

cam = irsol::utils::loadDefaultCamera()

)

Constructs the Interface by loading the default camera.

Initializes the camera by calling irsol::utils::loadDefaultCamera(), which automatically finds and opens the default device based on serial number.

Parameters

cam	Optional camera handle. Defaults to the result of irsol::utils::loadDefaultCamera().

Exceptions

std::runtime_error

if camera initialization fails.

Definition at line 13 of file interface.cpp.

                                 : m_cam(cam)
{
 
  // Here we configure the camera settings so that we can trigger it on-demand via software
  // triggers.
  IRSOL_LOG_INFO("Configuring camera for manual trigger via software events");
  setMultiParam({{"TriggerMode", {"On"}},               // Enable software trigger
                 {"AcquisitionMode", {"SingleFrame"}},  // Take a single frame, only when triggered
                 {"TriggerSource", {"Software"}}});
 
  // Here we set the exposure parameters, so that they can be controlled via software
  IRSOL_LOG_INFO("Configuring camera for manual exposure");
  setMultiParam({
    {"ExposureAuto", {"Off"}},    // Disable automatic exposure
    {"ExposureMode", {"Timed"}},  // Exposure mode: timed
  });
  setExposure(Interface::DEFAULT_EXPOSURE_TIME);  // Default exposure
  // Store the current exposure of the camera
  m_CachedExposureTime = getExposure();
 
  // Here we configure the default bit-depth
  IRSOL_LOG_INFO("Setting bit-depth to 12bits/pixel");
  auto setPixelFormat = setParam("PixelFormat", "Mono12");
  IRSOL_ASSERT_FATAL(
    setPixelFormat == "Mono12", "Pixel format is not 'Mono12', but is %s", setPixelFormat.c_str());
}

Interface() [2/2]

irsol::camera::Interface::Interface

(

Interface &&

other

)

Move constructor.

Definition at line 40 of file interface.cpp.

: m_cam(other.m_cam) {}

Member Function Documentation

cameraInfoAsString()

std::string irsol::camera::Interface::cameraInfoAsString

(

)

const

Get human-readable camera information.

Collects fields from NeoAPI::CamInfo and formats them into a readable tabular string.

Returns

Formatted string with camera model, serial, etc.

Definition at line 79 of file interface.cpp.

{
  auto       info           = m_cam.GetInfo();
  const auto model          = info.GetModelName();
  const auto camId          = info.GetId();
  const auto serial         = info.GetSerialNumber();
  const auto tlType         = info.GetTLType();
  const auto vendor         = info.GetVendorName();
  const auto usb3VisionGuid = info.GetUSB3VisionGUID();
  const auto usbPortId      = info.GetUSBPortID();
  const auto gevIpAddress   = info.GetGevIpAddress();
  const auto gevSubnetMask  = info.GetGevSubnetMask();
  const auto gevGateway     = info.GetGevGateway();
  const auto gevMacAddress  = info.GetGevMACAddress();
 
  tabulate::Table camInfo;
  camInfo.add_row({"Name", "Value"});
  camInfo.add_row({"Camera Model Name", model.c_str()});
  camInfo.add_row({"Camera ID", camId.c_str()});
  camInfo.add_row({"Camera Serial Number", serial.c_str()});
  camInfo.add_row({"Camera Transport Layer Type", tlType.c_str()});
  camInfo.add_row({"Camera Vendor Name", vendor.c_str()});
  camInfo.add_row({"Camera USB3 Vision GUID", usb3VisionGuid.c_str()});
  camInfo.add_row({"Camera USB Port ID", usbPortId.c_str()});
  camInfo.add_row({"Camera GEV IP Address", gevIpAddress.c_str()});
  camInfo.add_row({"Camera GEV Subnet Mask", gevSubnetMask.c_str()});
  camInfo.add_row({"Camera GEV Gateway", gevGateway.c_str()});
  camInfo.add_row({"Camera GEV MAC Address", gevMacAddress.c_str()});
  camInfo.add_row({"Is connectable", info.IsConnectable() ? "true" : "false"});
 
  camInfo.column(0).format().font_align(tabulate::FontAlign::right);
  return camInfo.str();
}

cameraStatusAsString()

std::string irsol::camera::Interface::cameraStatusAsString

(

)

const

Get current camera status.

Reads camera state such as resolution, exposure, and other operational flags and returns a descriptive tabular string.

Returns

Formatted string describing current state of the camera.

Definition at line 114 of file interface.cpp.

{
  static const char* const FEATURE_NAMES[] = {"AcquisitionMode",
                                              "BinningHorizontalMode",
                                              "BinningHorizontal",
                                              "BinningVerticalMode",
                                              "BinningVertical",
                                              "DeviceTemperatureStatus",
                                              "DeviceTemperature",
                                              "ExposureAuto",
                                              "ExposureMode",
                                              "ExposureTime",
                                              "FrameCounter",
                                              "Height",
                                              "HeightMax",
                                              "OffsetX",
                                              "OffsetY",
                                              "PayloadSize",
                                              "PixelFormat",
                                              "ReadOutTime",
                                              "ReverseX",
                                              "ReverseY",
                                              "TriggerMode",
                                              "TriggerOverlap",
                                              "Width",
                                              "WidthMax"};
 
  tabulate::Table featureInfo;
  featureInfo.add_row({"Feature", "Value"});
 
  for(const auto featureName : FEATURE_NAMES) {
    std::string featureValue = getParam(featureName);
    featureInfo.add_row({featureName, featureValue});
  }
  featureInfo.column(0).format().font_align(tabulate::FontAlign::right);
  return featureInfo.str();
}

captureImage()

Interface::image_t irsol::camera::Interface::captureImage

(

std::optional< irsol::types::duration_t >

timeout = std::nullopt

)

Capture a single image from the camera.

Waits up to a specified timeout (or the cached exposure time if not provided as argument). Thread-safe.

Parameters

timeout

Optional duration to wait for a frame.

Returns

Captured image.

Exceptions

std::runtime_error

on timeout or camera error.

Definition at line 232 of file interface.cpp.

{
  std::scoped_lock<std::mutex> lock(m_camMutex);
 
  // Send software trigger to get an image
  trigger("AcquisitionStart");
  trigger("TriggerSoftware");
  // Wait for image, either using the current cached exposure time with a small buffer
  // or using the user-provided timeout
  irsol::types::duration_t actualTimeout = m_CachedExposureTime + std::chrono::milliseconds(200);
  if(timeout.has_value()) {
    IRSOL_LOG_DEBUG(
      "User provided a custom timeout of capturing camera of {}",
      irsol::utils::durationToString(*timeout));
    actualTimeout = *timeout;
  } else {
    IRSOL_LOG_DEBUG(
      "Using exposure from camera {} with buffer", irsol::utils::durationToString(actualTimeout));
  }
 
  uint32_t timeoutMs = static_cast<uint32_t>(
    std::chrono::duration_cast<std::chrono::milliseconds>(actualTimeout).count());
  auto image = m_cam.GetImage(timeoutMs);
  if(image.IsEmpty() || image.GetSize() == 0) {
    IRSOL_LOG_WARN("Timeout or empty image received.");
  }
  trigger("AcquisitionStop");
  return image;
}

FullResolution()

Interface irsol::camera::Interface::FullResolution ( )

static

Factory method to create a camera interface using full sensor resolution.

Returns

Interface instance initialized at full resolution.

Definition at line 49 of file interface.cpp.

{
  auto cam = irsol::utils::loadDefaultCamera();
 
  Interface interface(cam);
  interface.setMultiParam({{"BinningVertical", {1}},
                           {"BinningVerticalMode", {"Sum"}},
                           {"BinningHorizontal", {1}},
                           {"BinningHorizontalMode", {"Sum"}}});
  interface.resetSensorArea();
  return interface;
}

getExposure()

irsol::types::duration_t irsol::camera::Interface::getExposure

(

)

const

Get the current exposure time from the camera.

Returns

Current exposure duration.

Definition at line 170 of file interface.cpp.

{
  auto exposureInMicroSeconds = getParam<int64_t>("ExposureTime");
  return std::chrono::microseconds(exposureInMicroSeconds);
}

getNeoCam()

NeoAPI::Cam & irsol::camera::Interface::getNeoCam

(

)

Access the underlying NeoAPI camera instance.

Returns

Reference to the underlying NeoAPI::Cam object.

Definition at line 153 of file interface.cpp.

{
  return m_cam;
}

getParam() [1/2]

template<typename T , std::enable_if_t< std::is_integral_v< T >||std::is_floating_point_v< T >||std::is_same_v< std::string, T >, int > = 0>

T irsol::camera::Interface::getParam

(

const std::string &

param

)

const

Retrieve a camera parameter of arbitrary type T.

Uses the NeoAPI API to retrieve the value and cast to T. Supported types:

• std::string
• bool
• integral types (e.g., int, int64_t)
• floating-point types (e.g., double)

Thread-safe: locks internal mutex.

Template Parameters

T	Desired return type.

Parameters

param

Name of the camera parameter.

Returns

Value of type T or a default on read error.

getParam() [2/2]

std::string irsol::camera::Interface::getParam

(

const std::string &

param

)

const

Retrieve a camera parameter and convert it to string.

Thread-safe: locks internal mutex.

Parameters

param

Name of the camera parameter.

Returns

Value as string or "Unknown" on error.

Definition at line 189 of file interface.cpp.

{
  IRSOL_LOG_DEBUG("Getting parameter '{}'", param);
  try {
    NeoAPI::NeoString neoParam(param.c_str());
    auto              feature = m_cam.GetFeature(neoParam);
    return NeoAPI::NeoString(feature).c_str();
  } catch(const std::exception& e) {
    IRSOL_LOG_ERROR("Failed to get parameter '{}': {}", param, e.what());
    return "Unknown";
  }
}

HalfResolution()

Interface irsol::camera::Interface::HalfResolution ( )

static

Factory method to create a camera interface using half sensor resolution.

Uses hardware binning to reduce resolution by averaging pixels.

Returns

Interface instance initialized at half resolution.

Definition at line 63 of file interface.cpp.

{
  auto cam = irsol::utils::loadDefaultCamera();
 
  Interface interface(cam);
  // For 'HalfResolution' we bin in both vertical and horizontal direction.
  interface.setMultiParam({{"BinningVertical", {2}},
                           {"BinningVerticalMode", {"Average"}},
                           {"BinningHorizontal", {2}},
                           {"BinningHorizontalMode", {"Average"}}});
  interface.resetSensorArea();
 
  return interface;
}

isConnected()

bool irsol::camera::Interface::isConnected ( ) const

inline

Check if the camera is currently connected.

Uses NeoAPI::Cam::IsConnected() internally.

Returns

true if camera is connected; false otherwise.

Definition at line 137 of file interface.hpp.

  {
    return m_cam.IsConnected();
  }

operator=()

Interface & irsol::camera::Interface::operator=

(

Interface &&

other

)

Move assignment operator.

Definition at line 42 of file interface.cpp.

{
  m_cam = other.m_cam;
  return *this;
}

resetSensorArea()

void irsol::camera::Interface::resetSensorArea

(

)

Reset the sensor area to the full sensor dimensions.

Useful if a previous program limited the sensor region and full dimensions need to be restored.

Definition at line 159 of file interface.cpp.

{
  IRSOL_LOG_INFO("Resetting sensor area");
  int maxWidth  = getParam<int>("WidthMax");
  int maxHeight = getParam<int>("HeightMax");
 
  setMultiParam(
    {{"Width", {maxWidth}}, {"Height", {maxHeight}}, {"OffsetX", {0}}, {"OffsetY", {0}}});
}

setExposure()

irsol::types::duration_t irsol::camera::Interface::setExposure

(

irsol::types::duration_t

exposure

)

Set the exposure time of the camera.

Parameters

exposure

New exposure duration.

Returns

The actual exposure set on the camera (may differ slightly).

Definition at line 177 of file interface.cpp.

{
  IRSOL_ASSERT_ERROR(exposure.count() > 0, "Cannot set non-positive exposure");
  auto exposureInMicroseconds =
    std::chrono::duration_cast<std::chrono::microseconds>(exposure).count();
  auto setExposureInMicroseconds =
    setParam("ExposureTime", static_cast<int64_t>(exposureInMicroseconds));
  m_CachedExposureTime = std::chrono::microseconds(setExposureInMicroseconds);
  return m_CachedExposureTime;
}

setMultiParam()

void irsol::camera::Interface::setMultiParam

(

const std::unordered_map< std::string, camera_param_t > &

params

)

Set multiple parameters in one call.

Iterates through a map of key-value pairs and sets each camera parameter accordingly. Internally dispatches based on type.

Parameters

params

Map of parameter names and values.

See also

Interface::setParam()

Definition at line 203 of file interface.cpp.

{
  IRSOL_LOG_DEBUG("Setting multiple parameters");
  std::scoped_lock<std::mutex> lock(m_camMutex);
  for(const auto& [param, value] : params) {
    std::visit(
      [&param, this](auto&& arg) {
        using U = std::decay_t<decltype(arg)>;
        IRSOL_LOG_TRACE("Setting parameter '{}' to value '{}'", param, arg);
        setParamNonThreadSafe<U>(param, arg);
      },
      value);
  }
}

setParam() [1/2]

template<typename T , std::enable_if_t< std::is_integral_v< std::decay_t< T > >||std::is_floating_point_v< std::decay_t< T > >||std::is_same_v< std::decay_t< T >, std::string >, int > = 0>

T irsol::camera::Interface::setParam	(	const std::string &	param,
		T	value
	)

Set a camera parameter of arbitrary type T.

Thread-safe. Supported types:

• std::string
• const char*
• bool
• integral types (converted to int64_t)
• floating-point types (converted to double)

Template Parameters

T	Value type.

Parameters

param	Parameter name.
value	Value to set.

Returns

The set value (after conversion/rounding, if any).

See also

Interface::setMultiParam()

setParam() [2/2]

template<typename T , std::enable_if_t< std::is_same_v< std::decay_t< T >, const char * >, int > = 0>

std::string irsol::camera::Interface::setParam	(	const std::string &	param,
		T	value
	)

Specialization for setting const char* values as strings.

Parameters

param	Parameter name.
value	C-string value.

Returns

Set value as std::string.

See also

Interface::setMultiParam()

setParamNonThreadSafe()

template<typename T , std::enable_if_t< std::is_integral_v< std::decay_t< T > >||std::is_floating_point_v< std::decay_t< T > >||std::is_same_v< std::decay_t< T >, std::string >||std::is_same_v< std::decay_t< T >, const char * >, int > = 0>

void irsol::camera::Interface::setParamNonThreadSafe ( const std::string &  param, T  value  )

private

Internal, non-thread-safe parameter setter used by setParam.

Template Parameters

T	Parameter value type.

Parameters

param	Name of the parameter.
value	Value to assign.

trigger()

void irsol::camera::Interface::trigger

(

const std::string &

param

)

Trigger a camera feature (e.g., software trigger).

Parameters

param

Name of the triggerable feature.

Definition at line 219 of file interface.cpp.

{
  IRSOL_LOG_TRACE("Triggering camera with parameter '{}'", param);
  try {
    NeoAPI::NeoString neoParam(param.c_str());
    auto              feature = m_cam.GetFeature(neoParam);
    feature.Execute();
  } catch(const std::exception& e) {
    IRSOL_LOG_ERROR("Failed to trigger camera with parameter '{}': {}", param, e.what());
  }
}

Member Data Documentation

DEFAULT_EXPOSURE_TIME

constexpr irsol::types::duration_t irsol::camera::Interface::DEFAULT_EXPOSURE_TIME = std::chrono::milliseconds(2)

staticconstexpr

Default exposure time (2 milliseconds) used to initialize the camera.

Definition at line 70 of file interface.hpp.

m_CachedExposureTime

irsol::types::duration_t irsol::camera::Interface::m_CachedExposureTime

private

Cached exposure value used for implicit timeout behavior in irsol::camera::Interface::captureImage().

Definition at line 270 of file interface.hpp.

m_cam

NeoAPI::Cam irsol::camera::Interface::m_cam

private

Internal camera instance from NeoAPI.

Definition at line 266 of file interface.hpp.

m_camMutex

std::mutex irsol::camera::Interface::m_camMutex

mutableprivate

Mutex to protect access to camera parameters and image acquisition.

Definition at line 263 of file interface.hpp.

---

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

• src/irsol/include/irsol/camera/interface.hpp
• src/irsol/lib/irsol/camera/interface.cpp