Python Bindings

GENERATED BY COPILOT - REVIEW IS NEEDED.

libaditof Python Bindings (aditofpython)

This page documents the Python bindings for the libaditof SDK as implemented in:

• bindings/python/aditofpython.cpp

The bindings use pybind11 to expose the core C++ API from sdk/include/aditof into a Python module called aditofpython.

---

1. Python Module Overview

1.1 Module name and description

PYBIND11_MODULE(aditofpython, m) {
    m.doc() = "ADI Time Of Flight python extensions";
    ...
}

• The Python package you import is:

import aditofpython

• It provides:
  • Enum types (Status, Adsd3500Status, ConnectionType)
  • Data structures (FrameDetails, CameraDetails, Metadata, etc.)
  • Classes mapping to C++ SDK classes (System, Camera, Frame, FrameHandler, DepthSensorInterface)
  • Helper frameData for zero‑copy NumPy access
  • SDK version helper functions

---

2. Enumerations

2.1 Status

C++ enum: aditof::Status
Python enum: aditofpython.Status

Values:

• Status.Ok
• Status.Busy
• Status.Unreachable
• Status.InvalidArgument
• Status.Unavailable
• Status.GenericError

Returned by most API calls to indicate success or failure.

---

2.2 Adsd3500Status

C++ enum: aditof::Adsd3500Status
Python enum: aditofpython.Adsd3500Status

Represents detailed ADSD3500 firmware/hardware statuses and error codes, such as:

• Adsd3500Status.OK
• Adsd3500Status.Invalid_Mode
• Adsd3500Status.Invalid_JBLF_Filter_Size
• Adsd3500Status.Unsupported_Command
• Adsd3500Status.Invalid_Memory_Region
• Adsd3500Status.Invalid_Firmware_Crc
• Adsd3500Status.Invalid_Imager
• Adsd3500Status.Invalid_Ccb
• Adsd3500Status.Flash_Header_Parse_Error
• Adsd3500Status.Flash_File_Parse_Error
• Adsd3500Status.Spim_Error
• Adsd3500Status.Invalid_Chipid
• Adsd3500Status.Imager_Communication_Error
• Adsd3500Status.Imager_Boot_Failure
• Adsd3500Status.Firmware_Update_Complete
• Adsd3500Status.Nvm_Write_Complete
• Adsd3500Status.Imager_Error
• Adsd3500Status.Timeout_Error
• Adsd3500Status.Dynamic_Mode_Switching_Not_Enabled
• Adsd3500Status.Invalid_Dynamic_Mode_Compositions
• Adsd3500Status.Invalid_Phase_Invalid_Value
• Adsd3500Status.CCB_Write_Complete
• Adsd3500Status.Invalid_CCB_Write_CRC
• Adsd3500Status.CFG_Write_Complete
• Adsd3500Status.Invalid_CFG_Write_CRC
• Adsd3500Status.Init_FW_Write_Complete
• Adsd3500Status.Invalid_Init_FW_Write_CRC
• Adsd3500Status.Invalid_Bin_Size
• Adsd3500Status.ACK_Error
• Adsd3500Status.Flash_Status_Chunk_Already_Found
• Adsd3500Status.Invalid_INI_Update_In_PCM_Mode
• Adsd3500Status.Unsupported_Mode_INI_Read
• Adsd3500Status.Imager_Stream_Off
• Adsd3500Status.Unknown_Error_Id

---

2.3 ConnectionType

C++ enum: aditof::ConnectionType
Python enum: aditofpython.ConnectionType

Values:

• ConnectionType.Network
• ConnectionType.OnTarget
• ConnectionType.Offline

Describes how a camera or sensor is connected.

---

3. Data Structures

These are thin Python bindings over the C++ structs defined in the SDK headers.

3.1 FrameDataDetails

Python class: aditofpython.FrameDataDetails
Fields (read/write):

• type
• width
• height
• subelementSize
• subelementsPerElement
• bytesCount

Describes one typed data plane in a Frame (e.g., depth, AB, confidence).

---

3.2 FrameDetails

Python class: aditofpython.FrameDetails
Fields (read/write):

• type
• dataDetails – list of FrameDataDetails
• cameraMode
• width
• height
• totalCaptures
• passiveIRCaptured

Describes the overall layout and properties of a frame.

---

3.3 Metadata

Python class: aditofpython.Metadata
Fields (read/write): (exposed as simple attributes)

• width, height
• outputConfiguration
• bitsInDepth, bitsInAb, bitsInConfidence
• invalidPhaseValue
• frequencyIndex, abFrequencyIndex
• frameNumber
• imagerMode
• numberOfPhases, numberOfFrequencies
• xyzEnabled
• elapsedTimeFractionalValue, elapsedTimeSecondsValue
• sensorTemperature
• laserTemperature

Returned from Frame.getMetadataStruct().

---

3.4 IntrinsicParameters

Python class: aditofpython.IntrinsicParameters
Fields:

• fx, fy, cx, cy
• codx, cody
• k1, k2, k3, k4, k5, k6
• p1, p2

Defines camera intrinsic calibration parameters.

---

3.5 CameraDetails

Python class: aditofpython.CameraDetails
Fields:

• cameraId
• mode
• frameType
• connection (a ConnectionType)
• intrinsics (an IntrinsicParameters)
• minDepth, maxDepth
• bitCount
• uBootVersion
• kernelVersion
• sdCardImageVersion
• serialNumber

Filled via Camera.getDetails(details).

---

3.6 SensorDetails

Python class: aditofpython.SensorDetails

Fields:

• id
• connectionType

---

3.7 DriverConfiguration

Python class: aditofpython.DriverConfiguration

Fields:

• depthBits
• abBits
• confBits
• pixelFormat
• driverWidth
• driverHeigth
• pixelFromatIndex (note: name follows the C++ struct; typo preserved)

---

3.8 DepthSensorModeDetails

Python class: aditofpython.DepthSensorModeDetails

Fields:

• numberOfPhases
• frameContent
• modeNumber
• pixelFormatIndex
• frameWidthInBytes
• frameHeightInBytes
• baseResolutionWidth
• baseResolutionHeight
• metadataSize
• isPCM
• driverConfiguration (a DriverConfiguration)

Used with DepthSensorInterface.getModeDetails and DepthSensorInterface.setMode.

---

4. Helper: frameData (buffer protocol)

Python class: aditofpython.frameData

This is a small helper struct:

struct frameData {
    void *pData;
    aditof::FrameDataDetails details;
};

It implements the buffer protocol so that it can be viewed directly as a NumPy array without copying.

Binding:

• Returned by Frame.getData(dataType) as a frameData instance.
• The __buffer__ implementation (via py::buffer_protocol()) describes:
  • Shape: 2D (height, width) or 3D (height, width, subelementsPerElement).
  • Strides based on subelementSize and subelementsPerElement.
  • Data type:
    • "B" if subelementSize == 1 (uint8)
    • "H" if subelementSize == 2 (uint16)
    • "f" otherwise (float, used for MP confidence frames)

Typical usage in Python:

import numpy as np
import aditofpython as aditof

frame = aditof.Frame()
camera.requestFrame(frame)

depth_fd = frame.getData("depth")       # frameData
depth_np = np.array(depth_fd, copy=False)  # zero-copy NumPy view

print(depth_np.shape)   # (height, width) or (height, width, channels)

---

5. Core Classes

5.1 System

Python class: aditofpython.System

Bindings:

• Constructor:
  • System()
• Methods:
  • getCameraList(cameras, ip)
    • cameras – Python list to be filled with Camera objects.
    • ip – string (URI). Example: "ip:10.43.0.1".
    • Returns: Status.
  • getCameraList(cameras)
    • Same as above, without specifying ip.

Example:

import aditofpython as aditof

system = aditof.System()
cams = []
status = system.getCameraList(cams)

if status == aditof.Status.Ok and cams:
    cam = cams[0]

---

5.2 Camera

Python class: aditofpython.Camera
Backed by std::shared_ptr<aditof::Camera>.

5.2.1 Basic control and streaming

• initialize(configFilepath="")

• start()

• stop()

• setMode(mode) – mode is uint8.

• getAvailableModes(availableModes)

  • availableModes – Python list, populated with integers.
  • Returns: Status.

• getDetails(details)

  • details – CameraDetails instance (filled by the call).

5.2.2 Recording and playback

• startRecording(file_path) – Start recording frames to a file.
• stopRecording() – Stop recording.
• setPlaybackFile(file_path) – Use frames from a recording file instead of live stream.

5.2.3 Frame acquisition

• requestFrame(frame, index=0)
  • frame – Frame instance to fill.
  • index – used for offline playback (frame index).
  • Returns: Status.

5.2.4 Frame processing parameters

• getFrameProcessParams()

  • Returns: (Status, dict) mapping string → string.

• setFrameProcessParams(params, mode)

  • params – Python dict (string → string).
  • mode – int32 mode.
  • Returns: Status.

5.2.5 Controls and metadata

• getAvailableControls(controls)

  • controls – Python list of control names; returns Status.

• setControl(control, value) – both strings.

• getControl(control, value) – returns Status, value will be modified.

5.2.6 Sensor access and configuration

• getSensor() → DepthSensorInterface
• enableXYZframe(enable) – bool.
• saveModuleCFG(filepath)
• saveModuleCCB(filepath)
• enableDepthCompute(enable)
• setSensorConfiguration(sensorConf) – string.

5.2.7 ADSD3500‑specific methods

Many methods are exposed to configure and query the ADSD3500, including:

• Firmware update:

  • adsd3500UpdateFirmware(filePath)

• Thresholds and filters:

  • adsd3500SetABinvalidationThreshold(threshold)
  • adsd3500GetABinvalidationThreshold() → (Status, threshold)
  • adsd3500SetConfidenceThreshold(threshold)
  • adsd3500GetConfidenceThreshold() → (Status, threshold)
  • adsd3500SetJBLFfilterEnableState(enable)
  • adsd3500GetJBLFfilterEnableState() → (Status, enabled)
  • adsd3500SetJBLFfilterSize(size)
  • adsd3500GetJBLFfilterSize() → (Status, size)
  • adsd3500SetRadialThresholdMin(threshold)
  • adsd3500GetRadialThresholdMin() → (Status, threshold)
  • adsd3500SetRadialThresholdMax(threshold)
  • adsd3500GetRadialThresholdMax() → (Status, threshold)
  • adsd3500SetJBLFMaxEdgeThreshold(threshold)
  • adsd3500SetJBLFABThreshold(threshold)
  • adsd3500SetJBLFGaussianSigma(value)
  • adsd3500GetJBLFGaussianSigma() → (Status, value)
  • adsd3500SetJBLFExponentialTerm(value)
  • adsd3500GetJBLFExponentialTerm() → (Status, value)

• Temperatures:

  • adsd3500GetSensorTemperature() → (Status, sensorTemp)
  • adsd3500GetLaserTemperature() → (Status, laserTemp)

• MIPI and deskew:

  • adsd3500SetMIPIOutputSpeed(speed)
  • adsd3500GetMIPIOutputSpeed() → (Status, speed)
  • adsd3500SetEnableDeskewAtStreamOn(deskewEnable)

• Error and status reporting:

  • adsd3500GetImagerErrorCode() → (Status, errcode)
  • adsd3500GetStatus(chipStatus, imagerStatus) → (Status, chipStatus, imagerStatus)
  • adsd3500GetFirmwareVersion(fwVersion, fwHash) → (Status, fwVersion, fwHash)

• VCSEL delay:

  • adsd3500SetVCSELDelay(delay)
  • adsd3500GetVCSELDelay() → (Status, delay)

• Frame rate, confidence and temperature compensation:

  • adsd3500SetFrameRate(value)
  • adsd3500GetFrameRate() → (Status, framerate)
  • adsd3500SetEnableEdgeConfidence(value)
  • adsd3500GetTemperatureCompensationStatus() → (Status, value)
  • adsd3500SetEnablePhaseInvalidation(value)
  • adsd3500SetEnableTemperatureCompensation(value)

• Metadata in AB:

  • adsd3500SetEnableMetadatainAB(value)
  • adsd3500GetEnableMetadatainAB() → (Status, value)

• CCBM:

  • adsd3500DisableCCBM(value)
  • adsd3500IsCCBMsupported() → (Status, supported)

• Dynamic mode switching:

  • adsd3500setEnableDynamicModeSwitching(enable)
  • adsds3500setDynamicModeSwitchingSequence(sequence)
    (sequence is a list of (mode, repeatCount) pairs).

• Generic register access:

  • adsd3500SetGenericTemplate(reg, value)
  • adsd3500GetGenericTemplate(reg) → (Status, value)

• Depth parameters and INI reset:

  • saveDepthParamsToJsonFile(savePathFile)
  • loadDepthParamsFromJsonFile(loadPathFile, mode)
  • adsd3500ResetIniParamsForMode(value)

• Serial number and imager type:

  • readSerialNumber(serialNumber, useCacheValue) → (Status, serialNumber)
  • getImagerType(imagerType) – fills an ImagerType (from C++).

---

5.3 Frame

Python class: aditofpython.Frame

Methods:

• Frame() – constructor.
• setDetails(details, bitsInConf, bitsInAB)
• getDetails(details) – fills FrameDetails.
• getDataDetails(dataType, dataDetails) – fills FrameDataDetails.
• getData(dataType) → frameData (see section 4).
• getMetadataStruct() → (Status, Metadata)

Typical usage:

frame = aditof.Frame()
camera.requestFrame(frame)

status, metadata = frame.getMetadataStruct()
depth_fd = frame.getData("depth")
depth_np = np.array(depth_fd, copy=False)

---

5.4 DepthSensorInterface

Python class: aditofpython.DepthSensorInterface
Shared pointer to low‑level sensor interface.

Key methods (high‑level):

• open(), start(), stop()
• getAvailableModes(modes) – fills Python list; returns Status.
• getModeDetails(mode, details) – details is DepthSensorModeDetails.
• setMode(mode) – overloaded:
  • setMode(DepthSensorModeDetails)
  • setMode(uint8 mode)
• getFrame(buffer) – buffer is numpy.ndarray(dtype=np.uint16).
• getAvailableControls(controls) – list of strings.
• setControl(control, value), getControl(control, value)
• getDetails(details) – SensorDetails
• getName(name) – name of the sensor.
• setHostConnectionType(connectionType)
• getHandle(handle) – returns (Status, handle) where handle is a pointer placeholder.
• initTargetDepthCompute(iniFile, iniFileLength, calData, calDataLength) – uses numpy arrays of uint8.

ADSD3500‑specific methods (low‑level register/payload I/O):

• adsd3500_read_cmd(cmd, data, usDelay) → (Status, dataPtr)
• adsd3500_write_cmd(cmd, data) → Status
• adsd3500_read_payload_cmd(cmd, readback_data, payload_len) → (Status, dataPtr)
• adsd3500_read_payload(payload, payload_len) → (Status, dataPtr)
• adsd3500_write_payload_cmd(cmd, payload, payload_len) → Status
• adsd3500_write_payload(payload, payload_len) → Status
• adsd3500_reset() → Status
• adsd3500_register_interrupt_callback(cb) / adsd3500_unregister_interrupt_callback(cb) – callback‑based interrupt handling.

---

5.5 FrameHandler

Python class: aditofpython.FrameHandler

Bindings:

• FrameHandler()
• setOutputFilePath(filePath)
• setInputFileName(fullFileName)
• saveFrameToFile(frame, fileName="")
• saveFrameToFileMultithread(frame, fileName="")
• readNextFrame(frame, fullFileName) – returns Status
• setCustomFormat(format)
• storeFramesToSingleFile(enable)
• setFrameContent(frameContent)

Usage examples:

fh = aditof.FrameHandler()
fh.setOutputFilePath("recordings")
fh.setFrameContent("depth,ab")

frame = aditof.Frame()
camera.start()
camera.requestFrame(frame)
fh.saveFrameToFile(frame)
camera.stop()

fh = aditof.FrameHandler()
fh.setInputFileName("recordings/session.dat")

frame = aditof.Frame()
while fh.readNextFrame(frame, "") == aditof.Status.Ok:
    depth_fd = frame.getData("depth")
    depth_np = np.array(depth_fd, copy=False)
    # process playback frame

---

6. Version Helpers

The module exposes four free functions based on version-kit.h:

• aditofpython.getKitVersion() → string
• aditofpython.getApiVersion() → string
• aditofpython.getBranchVersion() → string
• aditofpython.getCommitVersion() → string

Example:

import aditofpython as aditof

print("Kit:", aditof.getKitVersion())
print("API:", aditof.getApiVersion())
print("Branch:", aditof.getBranchVersion())
print("Commit:", aditof.getCommitVersion())

---

7. Minimal End‑to‑End Example

import numpy as np
import aditofpython as aditof

# Discover camera
system = aditof.System()
cameras = []
status = system.getCameraList(cameras)
if status != aditof.Status.Ok or not cameras:
    raise RuntimeError("No cameras found")

camera = cameras[0]

# Initialize camera
camera.initialize()
camera.setMode(0)
camera.start()

# Request one frame
frame = aditof.Frame()
camera.requestFrame(frame)

# Access depth as NumPy
depth_fd = frame.getData("depth")
depth_np = np.array(depth_fd, copy=False)
print("Depth shape:", depth_np.shape)

# Get metadata
status, metadata = frame.getMetadataStruct()
print("Frame number:", metadata.frameNumber)

camera.stop()

This summarizes the Python bindings implemented in aditofpython.cpp in a GitHub‑Wiki‑friendly format.