C++ API Reference

The epc::TOFCam API provides a high-level interface for controlling the EPC670 Time-of-Flight camera module and accessing captured frames.

Overview

The API is split into two main classes:

epc::TOFCam — camera control: open/close, stream management, control parameters
epc::TOFFrame — frame data access: DCS, amplitude, distance, phase and metadata

A frame is always owned by a std::unique_ptr<TOFFrame> and is valid until the pointer goes out of scope.

Quick Start

#include <epc/tofcam.hpp>

int main() {
	epc::TOFCam cam(epc::TOFSensor::epc670);
	cam.open();
	cam.setControl(epc::ControlID::MODULATION_FREQ_HZ, 10000000);
	cam.setControl(epc::ControlID::EXPOSURE_US, 2000);
	cam.startStream();

	std::unique_ptr<epc::TOFFrame> frame;
	cam.captureFrame(frame);

	const uint16_t *distance = frame->get<epc::DistanceFrame>();
	const uint16_t *amplitude = frame->get<epc::AmplitudeFrame>();
	const uint16_t *dcs0 = frame->get<epc::DCSFrame>(0);

	// Your processing code here...

	cam.stopStream();
	cam.close();
}

Frame Types

Use the following structs with TOFFrame::get<T>() to access typed frame data:

Tag struct	Data type	Unit	Description
`epc::DCSFrame`	uint16_t	LSB	Raw DCS images
`epc::AmplitudeFrame`	uint16_t	LSB	Amplitude image
`epc::DistanceFrame`	uint16_t	mm	Computed distance image
`epc::PhaseFrame`	float	radian	Phase image

API Documentation

class TOFCam

Interface for controlling a Time-of-Flight camera.

Public Functions

TOFCam(TOFSensor sensor = TOFSensor::autodetect)

Constructor for TOFCam.

Parameters:: sensor – The specific TOF sensor model to interface with. If the sensor is set to TOFSensor::autodetect, the TOFCam will attempt to auto-detect the sensor model.

TOFCam(const TOFCam&) = delete: Non-copyable, move-only

TOFCam &operator=(const TOFCam&) = delete

TOFCam &operator=(TOFCam&&) = default

TOFCam(TOFCam&&) = default

~TOFCam()

int open()

Open the connection to the camera.

Returns:: int 0 on success, non-zero error code on failure.

int close()

Close the connection to the camera.

Returns:: int 0 on success, non-zero error code on failure.

int startStream(): Start the video stream.

int stopStream(): Stop the video stream.

int captureFrame(std::unique_ptr<TOFFrame> &frame)

Capture next frame. If streaming is active, this function retrieves the latest frame from the stream. If streaming is not active, it triggers a single frame capture.

Parameters:: frame – Reference to a unique_ptr where the captured frame will be stored.
Returns:: int 0 on success, non-zero error code on failure.

int setControl(ControlID control, int value)

Set a control parameter for the camera.

Parameters:

control – The control parameter identifier.
value – The value to set.

Returns:

int 0 on success, non-zero error code on failure.

inline int setControl(ControlID control, AcquisitionMode mode)

int getControl(ControlID control, int &value)

Get the current value of a control parameter.

Parameters:

control – The control parameter identifier.
value – Reference to an integer where the value will be stored.

Returns:

int 0 on success, non-zero error code on failure.

bool isStreaming()

Check if the camera is currently streaming.

Returns:: bool True if streaming is active, false otherwise.

class TOFFrame

Represents a single Time-of-Flight frame.

This class encapsulates the data captured by the TOF camera for a single frame, providing accessors for different data types like DCS, Amplitude, and Distance.

Public Functions

TOFFrame(const TOFFrame&) = delete: Non-copyable, move-only

TOFFrame &operator=(const TOFFrame&) = delete

TOFFrame &operator=(TOFFrame&&) = default

TOFFrame(TOFFrame&&) = default

~TOFFrame()

template<typename T> inline const T::Type *get(uint8_t index = 0) const

Get a pointer to the data of a specific frame type.

Template Parameters:: T – The frame identifier [DCSFrame, AmplitudeFrame, DistanceFrame, PhaseFrame, GrayscaleFrame].
Parameters:: index – Index of the DCS frame to retrieve (only applicable for DCSFrame, ignored for others).
Returns:: const typename T::Type* Pointer to the frame data.

TOFMetadata getMetadata() const

Get the metadata for this frame.

Returns:: TOFMetadata The metadata structure.

inline uint16_t getWidth() const: Get the width of the frame.

inline uint16_t getHeight() const: Get the height of the frame.

struct TOFMetadata

Metadata associated with a TOF frame.

Public Members

uint32_t frameNumber: The frame sequence number.

uint64_t timestamp: Timestamp in microseconds.

enum class epc::FrameType : uint8_t

Frame data type selector. Used to request specific image buffers from a epc::TOFFrame object.

Values:

enumerator DCS: DCS frames (raw sensor captures)

enumerator AMPLITUDE: Amplitude image.

enumerator DISTANCE: Distance image.

enumerator PHASE: Phase image.

enumerator GRAYSCALE: Grayscale image.

enum class epc::TOFSensor : uint8_t

Supported TOF camera models.

Values:

enumerator autodetect: Automatically detect the sensor model.

enumerator epc670: epc670 sensor model

enumerator epc660: epc660 sensor model

Control Parameters

The following control parameters can be passed to setControl() and getControl() as the first argument:

enum class epc::ControlID : uint8_t

Camera control parameter identifiers used with TOFCam::setControl() and TOFCam::getControl().

Note

Sensor-level controls (gain, exposure, modulation frequency) persist across acquisition mode changes because they are maintained by the sensor hardware. All other controls reset to defaults when switching acquisition modes. Controls marked with “@note Persistent” explicitly retain their values.

Values:

enumerator GAIN: Analog gain setting in %

Note

Persistent across acquisition mode changes

enumerator ACQUISITION_MODE

Acquisition mode,

Acquisition Modes

enum class epc::AcquisitionMode : uint8_t

Acquisition mode selection for TOFCam::setControl(ControlID::ACQUISITION_MODE, …).

Values:

enumerator DIST_AMP: Standard mode: computes distance and amplitude from 4 DCS frames.

enumerator GRAYSCALE: Grayscale mode: outputs a single grayscale image.

enumerator DIST_AMP_HDR

HDR mode: uses multiple integration times .