Skip to content

Using the SDK: Python Bindings

Jump to bottom
andrestraker edited this page Feb 27, 2026 · 2 revisions

ADI Time-of-Flight Python Bindings API Documentation

The aditofpython module provides Python bindings for the ADI Time-of-Flight (ToF) SDK, enabling developers to access the ADCAM Camera Kit functionality from Python applications.

Table of Contents

  1. Enumerations
  2. Data Structures
  3. Core Classes
  4. Utility Functions

Enumerations

Status

Represents the result status of SDK operations.

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

Adsd3500Status

ADSD3500-specific error codes for detailed error diagnosis.

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

ConnectionType

Specifies the connection method to the camera.

ConnectionType.Network    # Remote camera via network (e.g., Jetson over LAN)
ConnectionType.OnTarget   # Direct on-target connection (embedded Jetson)
ConnectionType.Offline    # Offline playback mode

ImagerType

Identifies the type of depth imager hardware.

ImagerType.UNSET        # Imager type not set
ImagerType.ADSD3100     # ADSD3100 imager
ImagerType.ADSD3030     # ADSD3030 imager
ImagerType.ADTF3080     # ADTF3080 imager

Data Structures

FrameDataDetails

Describes properties of a specific data type within a frame.

Attributes:

  • type (str): Type of frame data (e.g., "depth", "ab", "xyz", "conf")
  • width (int): Width in pixels
  • height (int): Height in pixels
  • subelementSize (int): Size in bytes of each sub-element
  • subelementsPerElement (int): Number of sub-elements per pixel
  • bytesCount (int): Total size in bytes

Example:

import aditofpython as aditof
details = aditof.FrameDataDetails()
print(f"Width: {details.width}, Height: {details.height}")

FrameDetails

Describes properties of an entire frame.

Attributes:

  • type (str): Frame type description
  • dataDetails (list[FrameDataDetails]): Available data types in the frame
  • cameraMode (str): Camera mode when frame was captured
  • width (int): Frame width in pixels
  • height (int): Frame height in pixels
  • totalCaptures (int): Number of sub-frames
  • passiveIRCaptured (bool): Whether passive IR data is included

Metadata

Contains frame metadata information including timestamps, configuration, and sensor data.

Attributes:

  • width, height (int): Frame dimensions
  • outputConfiguration (int): Output format configuration
  • bitsInDepth, bitsInAb, bitsInConfidence (int): Bit depth for each data type
  • invalidPhaseValue (int): Invalid phase marker
  • frequencyIndex, abFrequencyIndex (int): Modulation frequency indices
  • frameNumber (int): Sequential frame counter
  • imagerMode (int): Active imager mode
  • numberOfPhases, numberOfFrequencies (int): Capture parameters
  • xyzEnabled (bool): Whether XYZ frame is enabled
  • elapsedTimeFractionalValue, elapsedTimeSecondsValue (int): Capture timestamps
  • sensorTemperature, laserTemperature (int): Temperature values in Celsius

IntrinsicParameters

Camera intrinsic calibration parameters (lens distortion model).

Attributes:

  • fx, fy (float): Focal lengths
  • cx, cy (float): Principal point
  • codx, cody (float): Code center
  • k1...k6 (float): Radial distortion coefficients
  • p1, p2 (float): Tangential distortion coefficients

CameraDetails

Complete camera configuration and capabilities.

Attributes:

  • cameraId (str): Camera identifier
  • mode (int): Current operating mode
  • frameType (FrameDetails): Frame structure description
  • connection (ConnectionType): Connection type
  • intrinsics (IntrinsicParameters): Calibration parameters
  • minDepth, maxDepth (int): Depth range in millimeters
  • bitCount (int): Bits per pixel
  • uBootVersion, kernelVersion (str): Firmware versions
  • sdCardImageVersion (str): SD card image version
  • serialNumber (str): Camera serial number

SensorDetails

Low-level sensor information.

Attributes:

  • id (str): Sensor identifier
  • connectionType (ConnectionType): Connection method

DriverConfiguration

V4L2 driver configuration parameters.

Attributes:

  • depthBits, abBits, confBits (str): Bit depth per data type
  • pixelFormat (str): Pixel format string
  • driverWidth, driverHeigth (int): Driver resolution
  • pixelFormatIndex (int): Format index (8-bit, 12/16-bit)

DepthSensorModeDetails

Describes a specific sensor capture mode.

Attributes:

  • modeNumber (int): Mode identifier
  • frameContent (list[str]): Data types in this mode
  • numberOfPhases (int): Phase captures per frame
  • pixelFormatIndex (int): Bit depth format
  • frameWidthInBytes, frameHeightInBytes (int): Payload dimensions
  • baseResolutionWidth, baseResolutionHeight (int): Resolution
  • metadataSize (int): Metadata payload size
  • isPCM (bool): Whether this is PCM mode
  • driverConfiguration (DriverConfiguration): Driver settings

frameData

Numpy-compatible frame data wrapper with buffer protocol support.

Attributes:

  • pData (buffer): Raw frame data accessible as numpy array
  • details (FrameDataDetails): Metadata about the data

Usage:

frame_data = frame.getData("depth")
# Access as numpy array
depth_array = np.asarray(frame_data)

Core Classes

System

Entry point for camera discovery and system management.

Methods:

getCameraList(cameras, ip="")

Discovers available cameras.

Parameters:

  • cameras (list): Will be populated with Camera objects
  • ip (str, optional): IP address for network discovery. If omitted, discovers local cameras

Returns: Status

Example:

import aditofpython as aditof

system = aditof.System()
cameras = []
status = system.getCameraList(cameras)
if status == aditof.Status.Ok:
    print(f"Found {len(cameras)} cameras")

Camera

Main interface for camera control and frame acquisition.

Methods:

initialize(configFilepath="")

Initialize camera with optional configuration file.

Parameters:

  • configFilepath (str): Path to JSON config file (optional)

Returns: Status

start()

Start camera streaming.

Returns: Status

stop()

Stop camera streaming.

Returns: Status

setMode(mode)

Set camera operating mode.

Parameters:

  • mode (int): Mode number (0-6)

Returns: Status

getAvailableModes(availableModes)

Get list of supported modes.

Parameters:

  • availableModes (list): Will be populated with mode numbers

Returns: Status

requestFrame(frame, index=0)

Capture a frame from the camera.

Parameters:

  • frame (Frame): Frame object to populate
  • index (int): Frame index for playback mode

Returns: Status

getDetails(details)

Get camera configuration details.

Parameters:

  • details (CameraDetails): Will be populated with camera info

Returns: Status

getAvailableControls(controls)

Get list of available control names.

Parameters:

  • controls (list): Will be populated with control names

Returns: Status

setControl(control, value) / getControl(control, value)

Set or get camera control parameters.

Parameters:

  • control (str): Control name
  • value (str): Control value

Returns: Status

getSensor()

Get direct access to the depth sensor.

Returns: DepthSensorInterface

enableXYZframe(enable)

Enable/disable XYZ point cloud generation.

Parameters:

  • enable (bool): True to enable, False to disable

Returns: Status

setMode(mode) / getAvailableModes(modes)

Mode management functions.

Returns: Status

saveModuleCFG(filepath) / saveModuleCCB(filepath)

Save module CFG and CCB content to files.

Parameters:

  • filepath (str): Output file path

Returns: Status

enableDepthCompute(enable)

Enable/disable depth computation on frames.

Parameters:

  • enable (bool): Computation enabled state

Returns: Status

adsd3500UpdateFirmware(filePath)

Update ADSD3500 firmware.

Parameters:

  • filePath (str): Path to firmware file

Returns: Status

saveDepthParamsToJsonFile(savePathFile) / loadDepthParamsFromJsonFile(loadPathFile, mode)

Save/load depth processing parameters.

Parameters:

  • savePathFile (str): Output JSON file path
  • loadPathFile (str): Input JSON file path
  • mode (int): Camera mode

Returns: Status

getFrameProcessParams() / setFrameProcessParams(params, mode)

Get/set depth compute library parameters.

Parameters:

  • params (dict): Parameter dictionary

Returns: (Status, dict) for get / Status for set

setSensorConfiguration(sensorConf)

Set sensor configuration table.

Parameters:

  • sensorConf (str): Config name (e.g., "standard", "standardraw")

Returns: Status

adsd3500SetToggleMode(mode) / adsd3500ToggleFsync()

ADSD3500 FSYNC control.

Parameters:

  • mode (int): 0=manual, 1=auto framerate, 2=HiZ

Returns: Status

ADSD3500 Threshold Controls

Methods:

  • adsd3500SetABinvalidationThreshold(threshold) / adsd3500GetABinvalidationThreshold()
  • adsd3500SetConfidenceThreshold(threshold) / adsd3500GetConfidenceThreshold()
  • adsd3500SetRadialThresholdMin(threshold) / adsd3500GetRadialThresholdMin()
  • adsd3500SetRadialThresholdMax(threshold) / adsd3500GetRadialThresholdMax()

Returns: Status for set / (Status, value) for get

JBLF Filter Controls

Methods:

  • adsd3500SetJBLFfilterEnableState(enable) / adsd3500GetJBLFfilterEnableState()
  • adsd3500SetJBLFfilterSize(size) / adsd3500GetJBLFfilterSize()
  • adsd3500SetJBLFMaxEdgeThreshold(threshold)
  • adsd3500SetJBLFABThreshold(threshold)
  • adsd3500SetJBLFGaussianSigma(value) / adsd3500GetJBLFGaussianSigma()
  • adsd3500SetJBLFExponentialTerm(value) / adsd3500GetJBLFExponentialTerm()

Returns: Status for set / (Status, value) for get

Temperature and Sensor Monitoring

Methods:

  • adsd3500GetSensorTemperature() / adsd3500GetLaserTemperature()
  • adsd3500GetFirmwareVersion() / adsd3500GetImagerErrorCode()
  • adsd3500GetVCSELDelay() / adsd3500SetVCSELDelay(delay)

Returns: (Status, value) / (Status, version, hash)

MIPI and Configuration

Methods:

  • adsd3500SetMIPIOutputSpeed(speed) / adsd3500GetMIPIOutputSpeed()
  • adsd3500SetEnableDeskewAtStreamOn(value)

Returns: Status / (Status, speed)

Frame Rate Control

Methods:

  • adsd3500SetFrameRate(fps) / adsd3500GetFrameRate()

Returns: Status / (Status, fps)

Edge and Confidence

Methods:

  • adsd3500SetEnableEdgeConfidence(value)
  • adsd3500GetTemperatureCompensationStatus()

Returns: Status / (Status, value)

Phase and Temperature Compensation

Methods:

  • adsd3500SetEnablePhaseInvalidation(value)
  • adsd3500SetEnableTemperatureCompensation(value)

Returns: Status

Metadata Control

Methods:

  • adsd3500SetEnableMetadatainAB(value) / adsd3500GetEnableMetadatainAB()

Returns: Status / (Status, value)

Advanced Configuration

Methods:

  • adsd3500SetGenericTemplate(reg, value) / adsd3500GetGenericTemplate(reg)
  • adsd3500GetStatus()
  • adsd3500DisableCCBM(disable) / adsd3500IsCCBMsupported()
  • adsd3500ResetIniParamsForMode(mode)

Returns: Status / (Status, value) / (Status, chipStatus, imagerStatus) / (Status, supported)

Dynamic Mode Switching

Methods:

  • adsd3500setEnableDynamicModeSwitching(enable)
  • adsds3500setDynamicModeSwitchingSequence(sequence)

Parameters:

  • enable (bool): Enable dynamic mode switching
  • sequence (list[tuple(mode, count)]): Mode pairs (max 8 pairs)

Returns: Status

Recording and Playback

Methods:

  • startRecording(file_path) / stopRecording()
  • setPlaybackFile(file_path)

Parameters:

  • file_path (str): File path for recording/playback

Returns: Status

Serial Number and Device Info

Methods:

  • readSerialNumber(useCacheValue=False)
  • getImagerType()

Returns: (Status, serialNumber) / (Status, ImagerType)

Additional Device Controls

Methods:

  • dropFirstFrame(dropFrame)
  • getDepthParamtersMap(mode)
  • resetDepthProcessParams()

Parameters:

  • dropFrame (bool): Enable first frame drop
  • mode (int): Camera mode

Returns: Status / (Status, params_dict)

Frame

Container for sensor frame data including depth, AB, confidence, and metadata.

Methods:

setDetails(details, bitsInConf, bitsInAB)

Configure frame structure.

Parameters:

  • details (FrameDetails): Frame configuration
  • bitsInConf (int): Confidence bits
  • bitsInAB (int): AB data bits

Returns: Status

getDetails(details)

Get frame configuration.

Parameters:

  • details (FrameDetails): Will be populated

Returns: Status

getDataDetails(dataType, dataDetails)

Get details of specific data type.

Parameters:

  • dataType (str): Data type ("depth", "ab", "xyz", "conf")
  • dataDetails (FrameDataDetails): Will be populated

Returns: Status

getData(dataType)

Extract frame data as numpy array.

Parameters:

  • dataType (str): Data type to extract

Returns: frameData (numpy-compatible buffer)

Example:

import numpy as np

depth_data = frame.getData("depth")
depth_array = np.asarray(depth_data)
print(depth_array.shape)  # (height, width)

confidence_data = frame.getData("conf")
conf_array = np.asarray(confidence_data)

getMetadataStruct()

Extract frame metadata.

Returns: (Status, Metadata)

haveDataType(dataType)

Check if frame contains specific data type.

Parameters:

  • dataType (str): Data type to check

Returns: bool

Example:

if frame.haveDataType("xyz"):
    xyz_data = frame.getData("xyz")

DepthSensorInterface

Low-level sensor interface for direct hardware control.

Methods:

open() / start() / stop()

Sensor lifecycle management.

Returns: Status

getAvailableModes(modes)

Get list of available sensor modes.

Parameters:

  • modes (list): Will be populated with mode numbers

Returns: Status

getModeDetails(mode, details)

Get configuration for a specific mode.

Parameters:

  • mode (int): Mode number
  • details (DepthSensorModeDetails): Will be populated

Returns: Status

setMode(mode) / setMode(details)

Set sensor mode by number or by DepthSensorModeDetails.

Parameters:

  • mode (int or DepthSensorModeDetails)

Returns: Status

getFrame(buffer, index=0)

Raw sensor frame capture.

Parameters:

  • buffer (numpy array): uint16 array to store frame
  • index (int): Frame index for playback

Returns: Status

getDetails(details)

Get sensor configuration.

Parameters:

  • details (SensorDetails): Will be populated

Returns: Status

getName(name)

Get sensor name.

Parameters:

  • name (str): Will be populated

Returns: Status

Direct Register Access

Methods:

  • adsd3500_read_cmd(cmd, data, usDelay=0)
  • adsd3500_write_cmd(cmd, data, usDelay=0)

Parameters:

  • cmd (int): Device command
  • data (int): Value to write
  • usDelay (int): Microsecond delay

Returns: Status / (Status, dataPtr)

Payload Operations

Methods:

  • adsd3500_read_payload_cmd(cmd, readback_data, payload_len)
  • adsd3500_read_payload(payload, payload_len)
  • adsd3500_write_payload_cmd(cmd, payload, payload_len)
  • adsd3500_write_payload(payload, payload_len)

Parameters:

  • cmd (int): Device command
  • payload (numpy array): uint8 data buffer
  • payload_len (int): Payload size

Returns: Status / (Status, dataPtr)

Hardware Control

Methods:

  • adsd3500_reset()
  • adsd3500_getInterruptandReset()

Returns: Status

Interrupt Handling

Methods:

  • adsd3500_register_interrupt_callback(callback)
  • adsd3500_unregister_interrupt_callback(callback)

Parameters:

  • callback (callable): Function to call on interrupt

Returns: Status

Control Interface

Methods:

  • getAvailableControls(controls)
  • setControl(control, value) / getControl(control, value)

Parameters:

  • controls (list): Will be populated with control names
  • control (str): Control name
  • value (str): Control value

Returns: Status

Depth Compute Library

Methods:

  • initTargetDepthCompute(iniFile, iniFileLength, calData, calDataLength)

Parameters:

  • iniFile (numpy array): uint8 INI file content
  • iniFileLength (int): INI file size
  • calData (numpy array): uint8 calibration data
  • calDataLength (int): Calibration data size

Returns: (Status, iniFilePtr, calDataPtr)

Depth Parameters

Methods:

  • getDepthComputeParams() / setDepthComputeParams(params)

Parameters:

  • params (dict): Parameter dictionary

Returns: (Status, dict) / Status

Sensor Configuration

Methods:

  • setSensorConfiguration(sensorConf)

Parameters:

  • sensorConf (str): Configuration name

Returns: Status

INI Parameters

Methods:

  • getIniParamsArrayForMode(mode)

Parameters:

  • mode (int): Camera mode

Returns: (Status, iniStr)

Recording and Playback

Methods:

  • startRecording(fileName, parameters)
  • stopRecording()
  • setPlaybackFile(filePath)
  • stopPlayback()

Parameters:

  • fileName (str): Recording file name
  • parameters (numpy array): uint8 recording parameters
  • filePath (str): Playback file path

Returns: Status

File Information

Methods:

  • getHeader(buffer)
  • getFrameCount()

Parameters:

  • buffer (numpy array): uint8 buffer for header data

Returns: Status / (Status, frameCount)

FrameHandler

Utilities for frame file I/O operations.

Methods:

setOutputFilePath(filePath) / setInputFileName(fullFileName)

Configure file paths.

Parameters:

  • filePath (str): Output directory path
  • fullFileName (str): Input file path

Returns: Status

saveFrameToFile(frame, fileName="") / saveFrameToFileMultithread(frame, fileName="")

Save frame to file.

Parameters:

  • frame (Frame): Frame to save
  • fileName (str): Output filename (auto-generated if empty)

Returns: Status

readNextFrame(frame, fullFileName="")

Read next frame from file.

Parameters:

  • frame (Frame): Frame object to populate
  • fullFileName (str): File path

Returns: Status

setCustomFormat(format) / setFrameContent(frameContent)

Configure frame format.

Parameters:

  • format (str): Custom format name
  • frameContent (str): Content to store (depth/ab/conf)

Returns: Status

storeFramesToSingleFile(enable)

Enable single file mode.

Parameters:

  • enable (bool): True for single file, False for multiple files

Returns: Status

SnapShotFrames(baseFileName, frame, ab, depth)

Save frame data to snapshot files.

Parameters:

  • baseFileName (str): Output filename base (no extension)
  • frame (Frame): Frame object
  • ab (numpy array): uint8 AB data
  • depth (numpy array): uint8 depth data

Returns: Status

Utility Functions

Version Information

version = aditof.getKitVersion()             # Get kit version string
api_version = aditof.getApiVersion()         # Get API version string
branch = aditof.getBranchVersion()           # Get branch name
commit = aditof.getCommitVersion()           # Get commit hash

Example Usage

Basic Frame Capture

import aditofpython as aditof
import numpy as np

# Initialize system and get camera
system = aditof.System()
cameras = []
status = system.getCameraList(cameras)

if status == aditof.Status.Ok and cameras:
    camera = cameras[0]
    
    # Initialize and start camera
    camera.initialize()
    camera.start()
    
    # Set mode
    camera.setMode(0)
    
    # Capture frame
    frame = aditof.Frame()
    camera.requestFrame(frame)
    
    # Extract data
    depth_data = frame.getData("depth")
    depth_array = np.asarray(depth_data)
    
    # Get metadata
    status, metadata = frame.getMetadataStruct()
    print(f"Frame: {metadata.frameNumber}, Size: {metadata.width}x{metadata.height}")
    
    camera.stop()

Configuration and Parameter Setting

# Get available modes
modes = []
camera.getAvailableModes(modes)
print(f"Available modes: {modes}")

# Set confidence threshold
camera.adsd3500SetConfidenceThreshold(64)
status, threshold = camera.adsd3500GetConfidenceThreshold()

# Enable XYZ frame
camera.enableXYZframe(True)

# Set frame processing parameters
params = {"param1": "value1", "param2": "value2"}
camera.setFrameProcessParams(params, mode=0)

Direct Sensor Access

sensor = camera.getSensor()

# Get sensor details
details = aditof.SensorDetails()
sensor.getDetails(details)
print(f"Sensor: {details.id}")

# Direct register access
status, data = sensor.adsd3500_read_cmd(0x0004)

# Set sensor control
sensor.setControl("gain", "10")

File Operations

handler = aditof.FrameHandler()
handler.setOutputFilePath("/path/to/output")

# Save frame
handler.saveFrameToFile(frame, "frame_001.raw")

# Read frame
handler.setInputFileName("/path/to/file.raw")
loaded_frame = aditof.Frame()
handler.readNextFrame(loaded_frame)

Return Value Conventions

Methods follow these return patterns:

  • Single return (Status): Returns operation status only

    status = camera.start()

  • Tuple return (Status, value): Returns status and output value

    status, temperature = camera.adsd3500GetSensorTemperature()

  • Dict return (Status, dict): Returns status and parameter dictionary

    status, params = camera.getFrameProcessParams()

  • Multiple output (Status, val1, val2): Returns status and multiple values

    status, chip_status, imager_status = camera.adsd3500GetStatus()

Notes

  • All frame data is exposed as numpy-compatible buffers via the buffer protocol
  • Enumerations can be compared directly: status == aditof.Status.Ok
  • Camera and sensor objects manage their own resources (RAII pattern)
  • Some methods may block waiting for hardware response
  • Frame data pointers are valid until the next frame request

Clone this wiki locally