Skip to content

SDK API & Usage Documentation

Jump to bottom
andrestraker edited this page Dec 18, 2025 · 3 revisions

GENERATED BY COPILOT - REVIEW IS NEEDED.

libaditof SDK – Public API Overview

This page documents the public API of the libaditof SDK as exposed through the headers in:

  • sdk/include/aditof/

The focus is on what an SDK consumer needs to know: key types, responsibilities, and how they fit together.

1. Header Map

Public headers under sdk/include/aditof/:

  • Entry point & high‑level objects

    • aditof.h – Convenience umbrella header.
    • system.h – aditof::System
    • camera.h – aditof::Camera
    • frame.h – aditof::Frame
    • frame_handler.h – aditof::FrameHandler

  • Definitions and enums

    • camera_definitions.h – CameraDetails, camera‑related enums.
    • frame_definitions.h – FrameDetails, FrameDataDetails, Metadata, etc.
    • sensor_definitions.h – ImagerType, sensor‑related enums and structures.
    • status_definitions.h – aditof::Status and status utilities.
    • adsd_errs.h – ADSD‑specific error definitions.

  • Sensors, enumeration, connections

    • depth_sensor_interface.h – aditof::DepthSensorInterface (low‑level sensor control).
    • sensor_enumerator_interface.h – aditof::SensorEnumeratorInterface.
    • sensor_enumerator_factory.h – aditof::SensorEnumeratorFactory.
    • connections.h – connection abstractions (interfaces for USB/Ethernet/etc).

  • Utilities and support

    • frame_operations.h – operations on Frame data.
    • utils.h – general SDK utilities.
    • log.h – logging helpers.
    • sdk_exports.h – export macros (e.g., SDK_API).
    • stb_image_write.h – embedded copy of stb image writing (used by helpers).
    • version-kit.h – version info for the SDK.

For most applications, including aditof/aditof.h should be enough; the other headers are available for more control and integration.

2. Core Classes

2.1 aditof::System

Header: system.h

Purpose:
Entry point of the SDK; discovers cameras and exposes them as std::shared_ptr<aditof::Camera>.

Key API:

  • Construction

    • System();
    • ~System();
    • System(System &&) noexcept;
    • System &operator=(System &&) noexcept;

  • Camera discovery

    • Status getCameraList(std::vector<std::shared_ptr<Camera>> &cameraList, const std::string &uri = "") const;
      • Fills cameraList with available cameras.
      • uri for remote/other connection modes (e.g. ip:10.43.0.1).

Typical usage:

aditof::System system;
std::vector<std::shared_ptr<aditof::Camera>> cameras;

aditof::Status status = system.getCameraList(cameras);
if (status != aditof::Status::OK || cameras.empty()) {
    // handle error
}

std::shared_ptr<aditof::Camera> cam = cameras.front();

2.2 aditof::Camera

Header: camera.h

Purpose:
Abstract interface to a single ToF camera module: initialization, streaming, controls, and sensor‑specific operations.

Type:

class SDK_API Camera {
public:
    virtual ~Camera() = default;
    // all methods below are pure virtual
};

Main responsibilities:

  1. Initialization and streaming

    • virtual Status initialize(const std::string &configFilepath = {}) = 0;
    • virtual Status start() = 0;
    • virtual Status stop() = 0;
    • virtual Status setMode(const uint8_t &mode) = 0;
    • virtual Status getAvailableModes(std::vector<uint8_t> &availableModes) const = 0;

  2. Frame acquisition

    • virtual Status requestFrame(Frame *frame, uint32_t index = 0) = 0;
      • Fills the provided Frame with the latest data (or the frame at index when in playback mode).

  3. Depth / processing parameters

    • virtual Status getFrameProcessParams(std::map<std::string, std::string> &params) = 0;
    • virtual Status setFrameProcessParams(std::map<std::string, std::string> &params, int32_t mode) = 0;
    • virtual Status enableDepthCompute(bool enable) = 0;
    • virtual Status resetDepthProcessParams() = 0;
    • virtual Status getDepthParamtersMap(uint16_t mode, std::map<std::string, std::string> &params) = 0;
    • JSON‑based parameter I/O:
      • virtual Status saveDepthParamsToJsonFile(const std::string &savePathFile) = 0;
      • virtual Status loadDepthParamsFromJsonFile(const std::string &path, const int16_t mode_in_use = -1) = 0;

  4. AB (amplitude) normalization

    • virtual void normalizeABBuffer(uint16_t *abBuffer, uint16_t abWidth, uint16_t abHeight, bool advanceScaling, bool useLogScaling) = 0;
    • virtual Status normalizeABFrame(Frame *frame, bool advanceScaling, bool useLogScaling) = 0;

  5. Camera metadata & controls

    • virtual Status getDetails(CameraDetails &details) const = 0;
    • virtual Status getAvailableControls(std::vector<std::string> &controls) const = 0;
    • virtual Status setControl(const std::string &control, const std::string &value) = 0;
    • virtual Status getControl(const std::string &control, std::string &value) const = 0;

  6. Low‑level sensor access

    • virtual std::shared_ptr<DepthSensorInterface> getSensor() = 0;
    • virtual Status readSerialNumber(std::string &serialNumber, bool useCacheValue = false) = 0;
    • virtual Status getImagerType(ImagerType &imagerType) const = 0;
    • virtual Status setSensorConfiguration(const std::string &sensorConf) = 0;

  7. XYZ / metadata options

    • virtual Status enableXYZframe(bool enable) = 0;
    • virtual Status adsd3500SetEnableMetadatainAB(uint16_t value) = 0;
    • virtual Status adsd3500GetEnableMetadatainAB(uint16_t &value) = 0;

  8. Module configuration and firmware (ADSD3500‑specific)

    • virtual Status saveModuleCFG(const std::string &filepath) const = 0;
    • virtual Status saveModuleCCB(const std::string &filepath) = 0;
    • virtual Status adsd3500UpdateFirmware(const std::string &fwFilePath) = 0;
    • Many additional ADSD3500 control methods:
      • FSYNC, AB/Confidence thresholds, JBLF filter, radial thresholds, temperatures, frame rate, deskew, generic register access, status, CCBM, dynamic mode switching, VCSEL delay, etc.

  9. Recording and playback

    • virtual void dropFirstFrame(bool dropFrame) = 0;
    • virtual Status startRecording(std::string &filePath) = 0;
    • virtual Status stopRecording() = 0;
    • virtual Status setPlaybackFile(std::string &filePath) = 0;

Typical usage (simplified):

// Acquire a camera from System
aditof::System system;
std::vector<std::shared_ptr<aditof::Camera>> cameras;
system.getCameraList(cameras);
auto camera = cameras.front();

// Init and start
camera->initialize();
camera->setMode(0);   // mode depends on the module
camera->start();

// Acquire a frame
aditof::Frame frame;
camera->requestFrame(&frame);

// Clean up
camera->stop();

2.3 aditof::Frame

Header: frame.h

Purpose:
Encapsulates image buffers and metadata for a single frame (depth, AB, XYZ, confidence, etc.).

Type:

class Frame {
public:
    Frame();
    ~Frame();
    Frame(const Frame &);
    Frame &operator=(const Frame &);
    Frame(Frame &&) noexcept;
    Frame &operator=(Frame &&) noexcept;
    // methods below
};

Key methods:

  • Configuration

    • Status setDetails(const FrameDetails &details, const uint8_t &m_bitsInConf, const uint8_t &m_bitsInAB);

  • Global frame info

    • Status getDetails(FrameDetails &details) const;

  • Per‑data‑type info

    • Status getDataDetails(const std::string &dataType, FrameDataDetails &details) const;

  • Data access

    • Status getData(const std::string &dataType, uint16_t **dataPtr);
      • Typical dataType values:
        • "depth", "ab", "xyz", "conf" (depending on mode and configuration).

  • Metadata

    • virtual Status getMetadataStruct(Metadata &metadata) const;

  • Capability querying

    • virtual bool haveDataType(const std::string &dataType);

Typical usage:

aditof::Frame frame;
camera->requestFrame(&frame);

// Access depth data
uint16_t *depthData = nullptr;
frame.getData("depth", &depthData);

// Access AB data
uint16_t *abData = nullptr;
frame.getData("ab", &abData);

// Metadata
aditof::Metadata md;
frame.getMetadataStruct(md);

2.4 aditof::FrameHandler

Header: frame_handler.h

Purpose:
Utility class for saving and loading frames to/from files, optionally in a custom or single‑file format; independent of live camera hardware.

Key methods:

  • Construction

    • FrameHandler();
    • ~FrameHandler();
    • FrameHandler(FrameHandler &&) noexcept;
    • FrameHandler &operator=(FrameHandler &&) noexcept;

  • I/O configuration

    • Status setOutputFilePath(const std::string &filePath);
    • Status setInputFileName(const std::string &fullFileName);
    • Status setCustomFormat(const std::string &format);
    • Status storeFramesToSingleFile(bool enable);
    • Status setFrameContent(const std::string &frameContent);
      • e.g. "depth,ab,conf".

  • Frame persistence

    • Status saveFrameToFile(Frame &frame, const std::string &fileName = "");
    • Status saveFrameToFileMultithread(Frame &frame, const std::string &fileName = "");
    • Status readNextFrame(Frame &frame, const std::string &fullFileName = "");

  • Snapshot helper

    • Status SnapShotFrames(const char *baseFileName, Frame *frame, const uint8_t *ab, const uint8_t *depth);

Usage patterns:

  • Record during streaming
aditof::FrameHandler recorder;
recorder.setOutputFilePath("/tmp/frames");
recorder.setFrameContent("depth,ab");
recorder.storeFramesToSingleFile(true);

aditof::Frame frame;

for (...) {
    camera->requestFrame(&frame);
    recorder.saveFrameToFile(frame);
}
  • Offline playback
aditof::FrameHandler player;
player.setInputFileName("/tmp/frames/session.dat");

aditof::Frame frame;

while (player.readNextFrame(frame) == aditof::Status::OK) {
    uint16_t *depth = nullptr;
    frame.getData("depth", &depth);
    // process depth...
}

2.5 aditof::DepthSensorInterface

Header: depth_sensor_interface.h

Purpose:
Abstract low‑level interface to the depth sensor itself (register‑level configuration, calibration functions, etc.). Used when an application needs more direct sensor access than Camera provides.

Access:

  • std::shared_ptr<DepthSensorInterface> aditof::Camera::getSensor();

API (high‑level view):

  • Methods for:
    • Reading/writing sensor registers or memory regions.
    • Configuring sensor timings or modes.
    • Accessing calibration or sensor‑specific features.

(Refer to depth_sensor_interface.h for the full, detailed function list.)

2.6 Sensor Enumeration Interfaces

Headers:

  • sensor_enumerator_interface.h – introduces aditof::SensorEnumeratorInterface.
  • sensor_enumerator_factory.h – aditof::SensorEnumeratorFactory.

Purpose:
Internal extension points for how sensors/cameras are discovered, but exposed publicly for advanced integrations.

Common pattern:

  • SensorEnumeratorInterface defines a virtual interface for enumerating available sensors/cameras.
  • SensorEnumeratorFactory defines a method to obtain appropriate enumerators (depending on platform/connection).

Most applications use aditof::System instead of touching these directly.

2.7 Status, Errors, and Utilities

2.7.1 aditof::Status

Header: status_definitions.h
Purpose:
Represents the result of most SDK operations.

Typical values (names may vary; see header):

  • Status::OK
  • Status::GENERIC_ERROR
  • Status::INVALID_ARGUMENT
  • Status::UNAVAILABLE
  • etc.

Almost all API methods return aditof::Status; callers must check it.

2.7.2 adsd_errs.h

Contains ADSD‑specific error codes and helpers. Used in combination with ADSD3500‑related API in Camera.

2.7.3 utils.h

Miscellaneous helpers and utilities that are safe to use from application code (e.g., conversions, small helpers). See the header for the exact API surface.

2.7.4 log.h

Logging configuration and macros, allowing the SDK and applications to log messages in a consistent way.

3. Typical Usage Flows

3.1 Live Streaming (Depth Only)

#include <aditof/aditof.h>   // umbrella header

int main() {
    aditof::System system;
    std::vector<std::shared_ptr<aditof::Camera>> cameras;
    if (system.getCameraList(cameras) != aditof::Status::OK || cameras.empty()) {
        return -1;
    }

    auto camera = cameras.front();
    camera->initialize();
    camera->setMode(0);
    camera->start();

    aditof::Frame frame;
    for (int i = 0; i < 100; ++i) {
        camera->requestFrame(&frame);

        uint16_t *depth = nullptr;
        frame.getData("depth", &depth);
        // Process depth ...
    }

    camera->stop();
}

3.2 Recording and Playback

// Recording
aditof::FrameHandler recorder;
recorder.setOutputFilePath("./recordings");
recorder.setFrameContent("depth,ab");

aditof::Frame frame;
camera->start();
for (int i = 0; i < 50; ++i) {
    camera->requestFrame(&frame);
    recorder.saveFrameToFile(frame);
}
camera->stop();

// Playback
aditof::FrameHandler player;
player.setInputFileName("./recordings/session.dat");

while (player.readNextFrame(frame) == aditof::Status::OK) {
    uint16_t *depth = nullptr;
    frame.getData("depth", &depth);
    // Process offline depth frame...
}

4. Public vs Internal

The public API is defined solely by the headers under:

  • sdk/include/aditof/

Implementation details (such as SystemImpl, FrameImpl, FrameHandlerImpl, connection types, and concrete camera classes) live under:

  • sdk/src/
  • sdk/common/

These internal types are not part of the public API and may change without notice; applications should depend only on the interfaces documented above.

5. Summary

  • System – Discover cameras.
  • Camera – Configure and operate a ToF module.
  • Frame – Container for depth/AB/XYZ/conf + metadata.
  • FrameHandler – Record and replay frames.
  • DepthSensorInterface – Advanced, low‑level sensor access.
  • Definitions & utilities – *_definitions.h, status_definitions.h, adsd_errs.h, utils.h, log.h.

These headers together define the public contract of the libaditof SDK; all other code in sdk/src and sdk/common can be treated as implementation detail.

Clone this wiki locally