Python API Reference

The epc_tofcam_native module provides Python bindings for the libepctofcam library, built with pybind11. All frame data is returned as 2D numpy arrays.

Overview

The API consists of the following main classes:

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

Frame data is provided as numpy arrays and its memory is owned and managed by the underlying C++ frame object.

Quick Start

"""Basic example of using the Python API to capture a frame from the TOF camera."""

from epc_tofcam_native import TOFCam, TOFControl, FrameType

cam = TOFCam()
cam.open()
cam.setControl(TOFControl.MODULATION_FREQUENCY_HZ, 10_000_000)
cam.setControl(TOFControl.EXPOSURE_US, 2000)
cam.startStream()

frame = cam.captureFrame()
distance = frame.get(FrameType.DISTANCE)
amplitude = frame.get(FrameType.AMPLITUDE)

# Your processing code here...

cam.stopStream()
cam.close()

Frame Types

Use the following frame types with TOFFrame.get() to access typed frame data:

Frame type	Data type	Unit	Description
`FrameType.DCS`	uint16	LSB	Raw DCS images
`FrameType.AMPLITUDE`	uint16	LSB	Amplitude image
`FrameType.DISTANCE`	uint16	mm	Computed distance image
`FrameType.PHASE`	float	radian	Phase image

Logging

The module uses Python’s standard logging module under the logger name epc_tofcam_native. All internal C++ log messages are routed through this logger. Configure it as usual:

import logging
logging.getLogger("epc_tofcam_native").setLevel(logging.DEBUG)

API reference:

class epc_tofcam_native.TOFCam

Interface for controlling an EPC TOF camera module.

captureFrame(self: epc_tofcam_native.TOFCam) → epc_tofcam_native.TOFFrame

Capture the next frame.

If streaming is active, retrieves the latest frame from the stream. If streaming is not active, triggers a single-shot capture.

Returns:: TOFFrame instance containing the captured data.

close(self: epc_tofcam_native.TOFCam) → None: Close the connection to the camera and release all resources.

getControl(self: epc_tofcam_native.TOFCam, control: epc_tofcam_native.TOFControl) → int

Get the current value of a camera control parameter.

Parameters:: control – TOFControl identifier.
Returns:: Current integer value of the control.

open(self: epc_tofcam_native.TOFCam) → None: Open the connection to the camera. Must be called before any other method.

setControl(self: epc_tofcam_native.TOFCam, control: epc_tofcam_native.TOFControl, value: object) → None

Set a camera control parameter.

Parameters:

control – TOFControl identifier.
value – Integer value or enum (e.g. AcquisitionMode) to set.

startStream(self: epc_tofcam_native.TOFCam) → None: Start continuous frame acquisition. Enables the maximum frame rate.

stopStream(self: epc_tofcam_native.TOFCam) → None: Stop continuous frame acquisition.

class epc_tofcam_native.TOFFrame

A single captured TOF frame. Holds image data and metadata.

get(self: epc_tofcam_native.TOFFrame, type: epc_tofcam_native.FrameType, index: SupportsInt | SupportsIndex = 0) → numpy.ndarray

Return a 2D numpy array for the requested frame type.

Parameters:

type – FrameType selector (DCS, AMPLITUDE, DISTANCE, PHASE).
index – DCS channel index (only used for FrameType.DCS).

Returns:

numpy.ndarray of shape (height, width). dtype is uint16 for DCS/AMPLITUDE/DISTANCE, float32 for PHASE.

Raises:

RuntimeError – if the requested data is not available in the current acquisition mode.

getMetadata(self: epc_tofcam_native.TOFFrame) → epc_tofcam_native.TOFMetadata: Return the TOFMetadata for this frame.

property height: Image height in pixels.

property width: Image width in pixels.

class epc_tofcam_native.TOFSensor(value): Supported TOF camera sensor models.

class epc_tofcam_native.FrameType(value): Frame data type selector for TOFFrame.get().

class epc_tofcam_native.TOFControl(value): TOFCam Control ID’s.

class epc_tofcam_native.AcquisitionMode(value): Supported acquisition modes.

class epc_tofcam_native.TOFMetadata

Metadata associated with a captured TOF frame.

property frameNumber: Sequential frame number since stream start.

property timestamp: Frame timestamp in microseconds.