#ifndef SCEPTER_API_H #define SCEPTER_API_H /** * @file Scepter_api.h * @brief Scepter API header file. * Copyright (c) 2024 Goermicro Inc. */ /*! \mainpage Scepter API Documentation * * \section intro_sec Introduction * * Welcome to the Scepter API documentation. This documentation enables you to quickly get started in your * development efforts to programmatically interact with the Scepter CW ToF Camera. */ #include "Scepter_define.h" /** * @brief Initializes the API on the device. This function must be invoked before any other Scepter APIs. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scInitialize(); /** * @brief Shuts down the API on the device and clears all resources allocated by the API. After * invoking this function, no other Scepter APIs can be invoked. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scShutdown(); /** * @brief Get the version of SDK. * @return Returns sdk version. */ SCEPTER_C_API_EXPORT ScStatus scGetSDKVersion(char* pSDKVersion, int32_t length); /** * @brief Returns the number of camera devices currently connected. * @param[out] pDeviceCount Pointer to a 32-bit integer variable in which to return the device count. * @param[in] scanTime Scans time, the unit is millisecond. This function scans devices for scanTime(ms) and then returns the count of devices. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetDeviceCount(uint32_t* pDeviceCount, uint32_t scanTime); /** * @brief Returns the info lists of the deviceCount camera devices. * @param[in] deviceCount The number of camera devices. * @param[out] pDevicesInfoList Pointer to a buffer in which to store the devices list infos. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetDeviceInfoList(uint32_t deviceCount, ScDeviceInfo* pDevicesInfoList); /** * @brief Opens the device specified by serialNumber. The device must be subsequently closed using scCloseDevice(). * @param[in] pSN The uri of the device. See ::ScDeviceInfo for more information. * @param[out] pDevice The handle of the device on which to open. * @return: ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scOpenDeviceBySN(const char* pSN, ScDeviceHandle* pDevice); /** * @brief Opens the device specified by ip. The device must be subsequently closed using scCloseDevice(). * @param[in] pIP The ip of the device. See ::ScDeviceInfo for more information. * @param[out] pDevice The handle of the device on which to open. * @return: ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scOpenDeviceByIP(const char* pIP, ScDeviceHandle* pDevice); /** * @brief Closes the device specified by device that was opened using scOpenDevice. * @param[in] pDevice The handle of the device to close. * @return: ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scCloseDevice(ScDeviceHandle* pDevice); /** * @brief Starts capturing the image stream indicated by device. Invoke scStopStream() to stop capturing the image stream. * @param[in] device The handle of the device on which to start capturing the image stream. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scStartStream(ScDeviceHandle device); /** * @brief Stops capturing the image stream on the device specified by device. that was started using scStartStream. * @param[in] device The handle of the device on which to stop capturing the image stream. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scStopStream(ScDeviceHandle device); /** * @brief Captures the next image frame from the device specified by device. This API must be invoked before capturing frame data using scGetFrame(). * @param[in] device The handle of the device on which to read the next frame. * @param[in] waitTime The unit is millisecond, the value is in the range (0,65535). * You can change the value according to the frame rate. For example,the frame rate is 30, so the theoretical waittime interval is 33ms, * but if set the time value is 20ms, it means the maximum wait time is 20 ms when capturing next frame, so when call the scGetFrameReady, * it may return SC_GET_FRAME_READY_TIME_OUT(-11). * So the recommended value is 2 * 1000/ FPS. * @param[out] pFrameReady Pointer to a buffer in which to store the signal on which image is ready to be get. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetFrameReady(ScDeviceHandle device, uint16_t waitTime, ScFrameReady* pFrameReady); /** * @brief Returns the image data for the current frame from the device specified by device. * Before invoking this API, invoke scGetFrameReady() to capture one image frame from the device. * @param[in] device The handle of the device to capture an image frame from. * @param[in] frameType The image frame type. * @param[out] pScFrame Pointer to a buffer in which to store the returned image data. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetFrame(ScDeviceHandle device, ScFrameType frameType, ScFrame* pScFrame); /** * @brief Get the depth range in the current working mode of the device. * @param[in] device The handle of the device. * @param[out] minValue The min value of the depth * @param[out] maxValue The ax value of the depth * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetDepthRangeValue(ScDeviceHandle device, int16_t* minValue, int16_t* maxValue); /** * @brief Returns the internal intrinsic and distortion coefficient parameters from the device specified by device. * @param[in] device The handle of the device from which to get the internal parameters. * @param[in] sensorType The type of sensor (depth or color) from which to get parameter information. Pass in the applicable value defined by ::ScSensorType. * @param[out] pSensorIntrinsicParameters Pointer to a ScSensorIntrinsicParameters variable in which to store the parameter values. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetSensorIntrinsicParameters(ScDeviceHandle device, ScSensorType sensorType, ScSensorIntrinsicParameters* pSensorIntrinsicParameters); /** * @brief Returns the camera rotation and translation coefficient parameters from the device specified by device. * @param[in] device The handle of the device from which to get the extrinsic parameters. * @param[out] pSensorExtrinsicParameters Pointer to a ::ScSensorExtrinsicParameters variable in which to store the parameters. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetSensorExtrinsicParameters(ScDeviceHandle device, ScSensorExtrinsicParameters* pSensorExtrinsicParameters); /** * @brief Get the firmware version number. * @param[in] device The handle of the device on which to set the pulse count. * @param[out] pFirmwareVersion Pointer to a variable in which to store the returned fw value. * @param[in] length The maximum length is 64 bytes. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetFirmwareVersion(ScDeviceHandle device, char* pFirmwareVersion, int32_t length); /** * @brief Get the MAC from the device specified by device. * @param[in] device The handle of the device. * @param[out] pMACAddress Pointer to a buffer in which to store the device MAC address. the buffer default size is 18, and the last buffer set '\0'. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetDeviceMACAddress(ScDeviceHandle device, char* pMACAddress); /** * @brief Enables or disables DHCP. Default disabled * @param[in] device The handle of the device on which to enable or disable the feature. * @param[in] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetDeviceDHCPEnabled(ScDeviceHandle device, bool bEnabled); /** * @brief Returns the Boolean value of whether the device is in DHCP or not. * @param[in] device The handle of the device on which to enable or disable the feature. * @param[out] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetDeviceDHCPEnabled(ScDeviceHandle device, bool* bEnabled); /** * @brief Set the IP address of the device in non-DHCP mode. The call takes effect after the device is restarted. * @param[in] device The handle of the device. * @param[in] ipAddr Pointer to a buffer in which to store the device IP address. the buffer default size is 16, and the last buffer set '\0'. * @param[in] length The length of the buffer. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetDeviceIPAddr(ScDeviceHandle device, const char* ipAddr, int32_t length); /** * @brief Get the IP address of the device in non-DHCP mode. * @param[in] device The handle of the device. * @param[out] ipAddr Pointer to a buffer in which to store the device IP address. the buffer default size is 16, and the last buffer set '\0'. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetDeviceIPAddr(ScDeviceHandle device, char* ipAddr); /** * @brief Set the subnet mask of the device in non-DHCP mode. The call takes effect after the device is restarted. * @param[in] device The handle of the device. * @param[in] pMask Pointer to a buffer in which to store the subnet mask address. the buffer default size is 16, and the last buffer set '\0'. * @param[in] length The length of the buffer. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetDeviceSubnetMask(ScDeviceHandle device, const char* pMask, int32_t length); /** * @brief Get the subnet mask of the device in non-DHCP mode. * @param[in] device The handle of the device. * @param[out] pMask Pointer to a buffer in which to store the device subnet mask address. the buffer default size is 16, and the last buffer set '\0'. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetDeviceSubnetMask(ScDeviceHandle device, char* pMask); /** * @brief Set the parameters for time sync, such as enable the NTP/PTP * @param[in] device The handle of the device on which to enable or disable the feature. * @param[in] params The parameters defined by ::ScTimeSyncConfig. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetRealTimeSyncConfig(ScDeviceHandle device, ScTimeSyncConfig params); /** * @brief Get the parameters for time sync,such as the status of the NTP/PTP * @param[in] device The handle of the device on which to enable or disable the feature. * @param[out] pParams Pointer to a variable in which to store the returned value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetRealTimeSyncConfig(ScDeviceHandle device, ScTimeSyncConfig* pParams); /** * @brief Set the ToF frame rate.The interface takes a long time, about 500 ms. * @param[in] device The handle of the device on which to set the framerate. * @param[in] value The rate value. Different products have different maximum values. Please refer to the product specification. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetFrameRate(ScDeviceHandle device, int32_t value); /** * @brief Get the ToF frame rate. * @param[in] device The handle of the device on which to get the framerate. * @param[out] pValue The rate value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetFrameRate(ScDeviceHandle device, int32_t* pValue); /** * @brief Set the working mode of the camera. * @param[in] device The handle of the device. * @param[in] mode The work mode of camera. For ActiveMode, set the Time filter default true, for SlaveMode, set the Time filter default false. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetWorkMode(ScDeviceHandle device, ScWorkMode mode); /** * @brief Get the working mode of the camera. * @param[in] device The handle of the device. * @param[out] pMode The work mode of camera. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetWorkMode(ScDeviceHandle device, ScWorkMode* pMode); /** * @brief Set the count of frame in SC_SOFTWARE_TRIGGER_MODE. * The more frames there are, the better frame's quality after algorithm processing * @param[in] device The handle of the device on which to set the parameter * @param[in] frameCount The count of frame, in range [1,10]. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetSoftwareTriggerParameter(ScDeviceHandle device, uint8_t frameCount); /** * @brief Get the count of framer in SC_SOFTWARE_TRIGGER_MODE. * @param[in] device The handle of the device from which to get the parameter * @param[out] pframeCount Pointer to a variable in which to store the count of frame, in range [1,10]. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetSoftwareTriggerParameter(ScDeviceHandle device, uint8_t* pframeCount); /** * @brief Get a frame in SC_SOFTWARE_TRIGGER_MODE. * Call the scSetSoftwareTriggerParameter API to improve the quality of depth frame. * @param[in] device The handle of the device. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSoftwareTriggerOnce(ScDeviceHandle device); /** * @brief Set the input signal parameters for Hardware Trigger. * @param[in] device The handle of the device * @param[in] params Pointer to a variable in which to store the parameters. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetInputSignalParamsForHWTrigger(ScDeviceHandle device, ScInputSignalParamsForHWTrigger params); /** * @brief Get the Input signal parameters for Hardware Trigger. * @param[in] device The handle of the device * @param[out] pParams Pointer to a variable in which to store the returned value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetInputSignalParamsForHWTrigger(ScDeviceHandle device, ScInputSignalParamsForHWTrigger* pParams); /** * @brief Set the device GMM gain on a device. * @param[in] device The handle of the device on which to set the GMM gain. * @param[in] gmmgain The value of IRGMM Gain. Different products have different maximum value. Please refer to the product specification. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetIRGMMGain(ScDeviceHandle device, uint8_t gmmgain); /** * @brief Returns the the device's GMM gain. * @param[in] device The handle of the device from which to get the GMM gain. * @param[out] pGmmgain Pointer to a variable in which to store the returned GMM gain. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetIRGMMGain(ScDeviceHandle device, uint8_t* pGmmgain); /** * @brief Set the device IR GMM Correction on a device. * @param[in] device The handle of the device. * @param[in] params The value of IR GMM Correction. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetIRGMMCorrection(ScDeviceHandle device, const ScIRGMMCorrectionParams params); /** * @brief Return the device IR GMM Correction on a device. * @param[in] device The handle of the device. * @param[out] params The value of IR GMM Correction. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetIRGMMCorrection(ScDeviceHandle device, ScIRGMMCorrectionParams* pParams); /** * @brief Set the color image pixel format on the device specified by device. Currently only RGB and BGR formats are supported. * @param[in] device The handle of the device to set the pixel format. * @param[in] pixelFormat The color pixel format to use. Pass in one of the values defined by ::ScPixelFormat. Others cameras support only * SC_PIXEL_FORMAT_RGB_888_JPEG and SC_PIXEL_FORMAT_BGR_888_JPEG. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetColorPixelFormat(ScDeviceHandle device, ScPixelFormat pixelFormat); /** * @brief Set the color Gain with the exposure mode of Color sensor in SC_EXPOSURE_CONTROL_MODE_MANUAL. * @param[in] device The handle of the device. * @param[in] params The value of color Gain.Different products have different maximum value. Please refer to the product specification. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetColorGain(ScDeviceHandle device, float params); /** * @brief Get the color Gain. * @param[in] device The handle of the device. * @param[out] params The value of color Gain. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetColorGain(ScDeviceHandle device, float* pParams); /** * @brief Get a list of image resolutions supported by Sensor * @param[in] device The handle of the device. * @param[in] type The sensor type * @param[out] pList List of supported resolutions * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetSupportedResolutionList(ScDeviceHandle device, ScSensorType type, ScResolutionList* pList); /** * @brief Set the ToF frame Resolution. * @param[in] device The handle of the device. * @param[in] w The width of ToF image * @param[in] h The height of ToF image * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetToFResolution(ScDeviceHandle device, int32_t w, int32_t h); /** * @brief Returns the the ToF frame Resolution. * @param[in] device The handle of the device. * @param[out] pW The width of ToF image * @param[out] pH The height of ToF image * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetToFResolution(ScDeviceHandle device, int32_t* pW, int32_t* pH); /** * @brief Set the color frame Resolution. * @param[in] device The handle of the device. * @param[in] w The width of color image * @param[in] h The height of color image * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetColorResolution(ScDeviceHandle device, int32_t w, int32_t h); /** * @brief Returns the the color frame Resolution. * @param[in] device The handle of the device. * @param[out] pW The width of color image * @param[out] pH The height of color image * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetColorResolution(ScDeviceHandle device, int32_t* pW, int32_t* pH); /** * @brief Set the exposure mode of sensor. * @param[in] device The handle of the device on which to set the exposure control mode. * @param[in] sensorType The type of sensor (depth or color) from which to get parameter information. Pass in the applicable value defined by ::ScSensorType. * @param[in] exposureType The exposure control mode. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetExposureControlMode(ScDeviceHandle device, ScSensorType sensorType, ScExposureControlMode controlMode); /** * @brief Get the exposure mode of sensor. * @param[in] device The handle of the device on which to get the exposure control mode. * @param[in] sensorType The type of sensor (depth or color) from which to get parameter information. Pass in the applicable value defined by ::ScSensorType. * @param[out] pControlMode The exposure control mode. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetExposureControlMode(ScDeviceHandle device, ScSensorType sensorType, ScExposureControlMode* pControlMode); /** * @brief Set the exposure time of sensor. * @param[in] device The handle of the device on which to set the exposure time in microseconds. * @param[in] sensorType The type of sensor (depth or color) from which to get parameter information. Pass in the applicable value defined by ::ScSensorType. * @param[in] exposureTime The exposure time. The value must be within the maximum exposure time of sensor. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetExposureTime(ScDeviceHandle device, ScSensorType sensorType, int32_t exposureTime); /** * @brief Get the exposure time of sensor. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[in] sensorType The type of sensor (depth or color) from which to get parameter information. Pass in the applicable value defined by ::ScSensorType. * @param[out] pExposureTime The exposure time. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetExposureTime(ScDeviceHandle device, ScSensorType sensorType, int32_t* pExposureTime); /** * @brief Set the maximum exposure time of color sensor in automatic mode. The interface is used in automatic mode. * @param[in] device The handle of the device on which to set the exposure time in microseconds. * @param[in] exposureTime The exposure time. The value must be within the maximum exposure time of sensor. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetColorAECMaxExposureTime(ScDeviceHandle device, int32_t exposureTime); /** * @brief Get the maximum exposure time of color sensor in automatic mode. The interface is used in automatic mode. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[out] pExposureTime The exposure time. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetColorAECMaxExposureTime(ScDeviceHandle device, int32_t* pExposureTime); /** * @brief Set the ROI of color sensor in automatic mode. The interface is used in automatic mode. * @param[in] device The handle of the device on which to set the exposure time in microseconds. * @param[in] x The x point of the ROI. The value must be within the color's resolution. * @param[in] y The y point of the ROI. The value must be within the color's resolution. * @param[in] width The width of the ROI. The value must be within the color's resolution. * @param[in] height The height of the ROI. The value must be within the color's resolution. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetColorAECROI(ScDeviceHandle device, uint16_t x, uint16_t y, uint16_t width, uint16_t height); /** * @brief Get the ROI of color sensor in automatic mode. The interface is used in automatic mode. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[out] x The x point of the ROI. The value must be within the color's resolution. * @param[out] y The y point of the ROI. The value must be within the color's resolution. * @param[out] width The width of the ROI. The value must be within the color's resolution. * @param[out] height The height of the ROI. The value must be within the color's resolution. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetColorAECROI(ScDeviceHandle device, uint16_t* x, uint16_t* y, uint16_t* width, uint16_t* height); /** * @brief Get the maximum exposure time of sensor. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[in] sensorType The type of sensor (depth or color) from which to get parameter information. Pass in the applicable value defined by ::ScSensorType. * @param[out] pMaxExposureTime The maximum exposure time. The maximum exposure time is different at different frame rates. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetMaxExposureTime(ScDeviceHandle device, ScSensorType sensorType, int32_t* pMaxExposureTime); /** * @brief Enables or disables the HDR Mode of the ToF sensor with SC_EXPOSURE_CONTROL_MODE_MANUAL. Default enabled, * so if you want switch to the SC_EXPOSURE_CONTROL_MODE_AUTO, set HDR Mode disable firstly. * @param[in] device The handle of the device on which to enable or disable the feature. * @param[in] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetHDRModeEnabled(ScDeviceHandle device, bool bEnabled); /** * @brief Returns the Boolean value of whether the HDR Mode of ToF sensor feature is enabled or disabled. * @param[in] device The handle of the device on which to enable or disable the feature. * @param[out] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetHDRModeEnabled(ScDeviceHandle device, bool* bEnabled); /** * @brief Get the count of frame in HDR mode. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[out] pCount The frame count. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetFrameCountOfHDRMode(ScDeviceHandle device, int32_t* pCount); /** * @brief Set the exposure time of depth sensor with the frameIndex in HDR mode. * @param[in] device The handle of the device on which to set the exposure time in microseconds. * @param[in] frameIndex The frameIndex from 0 to the count (get by scGetFrameCountOfHDRMode). * @param[in] exposureTime The exposure time. The value must be within the maximum exposure time of sensor. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetExposureTimeOfHDR(ScDeviceHandle device, uint8_t frameIndex, int32_t exposureTime); /** * @brief Get the exposure time of depth sensor with the frameIndex in HDR mode. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[in] frameIndex The frameIndex from 0 to the count (get by scGetFrameCountOfHDRMode). * @param[out] pExposureTime The exposure time. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetExposureTimeOfHDR(ScDeviceHandle device, uint8_t frameIndex, int32_t* pExposureTime); /** * @brief Get the maximum exposure time of depth sensor with the frameIndex in HDR mode. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[in] frameIndex The frameIndex from 0 to the count (get by scGetFrameCountOfHDRMode). * @param[out] pMaxExposureTime The maximum exposure time. The maximum exposure time is different at different frame rates. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetMaxExposureTimeOfHDR(ScDeviceHandle device, uint8_t frameIndex, int32_t* pMaxExposureTime); /** * @brief Enables or disables the WDR Mode of the ToF sensor. Default enabled * @param[in] device The handle of the device on which to enable or disable the feature. * @param[in] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetWDRModeEnabled(ScDeviceHandle device, bool bEnabled); /** * @brief Returns the Boolean value of whether the WDRMode of ToF sensor feature is enabled or disabled. * @param[in] device The handle of the device on which to enable or disable the feature. * @param[out] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetWDRModeEnabled(ScDeviceHandle device, bool* bEnabled); /** * @brief Get the count of frame in WDR mode. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[out] pCount The frame count. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetFrameCountOfWDRMode(ScDeviceHandle device, int32_t* pCount); /** * @brief Set the exposure time of depth sensor with the frameIndex in WDR mode. * @param[in] device The handle of the device on which to set the exposure time in microseconds. * @param[in] frameIndex The frameIndex from 0 to the count (get by scGetFrameCountOfWDRMode). * @param[in] exposureTime The exposure time. The value must be within the maximum exposure time of sensor. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetExposureTimeOfWDR(ScDeviceHandle device, uint8_t frameIndex, int32_t exposureTime); /** * @brief Get the exposure time of depth sensor with the frameIndex in WDR mode. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[in] frameIndex The frameIndex from 0 to the count (get by scGetFrameCountOfWDRMode). * @param[out] pExposureTime The exposure time. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetExposureTimeOfWDR(ScDeviceHandle device, uint8_t frameIndex, int32_t* pExposureTime); /** * @brief Get the maximum exposure time of depth sensor with the frameIndex in WDR mode. * @param[in] device The handle of the device on which to get the exposure time in microseconds. * @param[in] frameIndex The frameIndex from 0 to the count (get by scGetFrameCountOfWDRMode). * @param[out] pMaxExposureTime The maximum exposure time. The maximum exposure time is different at different frame rates. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetMaxExposureTimeOfWDR(ScDeviceHandle device, uint8_t frameIndex, int32_t* pMaxExposureTime); /** * @brief Set the parameters of the Time filter. * @param[in] device The handle of the device * @param[in] params Pointer to a variable in which to store the parameters. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetTimeFilterParams(ScDeviceHandle device, ScTimeFilterParams params); /** * @brief Get the parameters of the Time Filter feature. * @param[in] device The handle of the device * @param[out] pParams Pointer to a variable in which to store the returned value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetTimeFilterParams(ScDeviceHandle device, ScTimeFilterParams* pParams); /** * @brief Set the parameters of the Confidence filter. * @param[in] device The handle of the device * @param[in] params Pointer to a variable in which to store the parameters. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetConfidenceFilterParams(ScDeviceHandle device, ScConfidenceFilterParams params); /** * @brief Get the parameters of the ConfidenceFilter feature. * @param[in] device The handle of the device * @param[out] pParams Pointer to a variable in which to store the returned value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetConfidenceFilterParams(ScDeviceHandle device, ScConfidenceFilterParams* pParams); /** * @brief Set the parameters of the FlyingPixel filter. * @param[in] device The handle of the device. * @param[in] params Pointer to a variable in which to store the parameters. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetFlyingPixelFilterParams(ScDeviceHandle device, const ScFlyingPixelFilterParams params); /** * @brief Get the parameters of the FlyingPixel filter. * @param[in] device The handle of the device * @param[out] pParams Pointer to a variable in which to store the returned value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetFlyingPixelFilterParams(ScDeviceHandle device, ScFlyingPixelFilterParams* params); /** * @brief Enables or disables the FillHole filter * @param[in] device The handle of the device. * @param[in] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetFillHoleFilterEnabled(ScDeviceHandle device, bool bEnabled); /** * @brief Returns the Boolean value of whether the FillHole Filter feature is enabled or disabled. * @param[in] device The handle of the device * @param[out] pEnabled Pointer to a variable in which to store the returned Boolean value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetFillHoleFilterEnabled(ScDeviceHandle device, bool* pEnabled); /** * @brief Enables or disables the Spatial filter * @param[in] device The handle of the device. * @param[in] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetSpatialFilterEnabled(ScDeviceHandle device, bool bEnabled); /** * @brief Returns the Boolean value of whether the Spatial Filter feature is enabled or disabled. * @param[in] device The handle of the device * @param[out] pEnabled Pointer to a variable in which to store the returned Boolean value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetSpatialFilterEnabled(ScDeviceHandle device, bool* pEnabled); /** * @brief Enables or disables transforms a color image into the geometry of the depth sensor. When enabled, scGetFrame() can\n * be invoked passing ::ScTransformedColorFrame as the frame type for get a color image which each pixel matches the \n * corresponding pixel coordinates of the depth sensor. The resolution of the transformed color frame is the same as that\n * of the depth image. * @param[in] device The handle of the device on which to enable or disable mapping. * @param[in] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetTransformColorImgToDepthSensorEnabled(ScDeviceHandle device, bool bEnabled); /** * @brief Returns the Boolean value of whether the transformed of the color image to depth sensor space feature is enabled or disabled. * @param[in] device The handle of the device on which to enable or disable the feature. * @param[out] bEnabled Pointer to a variable in which to store the returned Boolean value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetTransformColorImgToDepthSensorEnabled(ScDeviceHandle device, bool* bEnabled); /** * @brief Enables or disables transforms the depth map into the geometry of the color sensor. When enabled, scGetFrame() can\n * be invoked passing ::ScTransformedDepthFrame as the frame type for get a depth image which each pixel matches the \n * corresponding pixel coordinates of the color sensor. The resolution of the transformed depth frame is the same as that\n * of the color image. * @param[in] device The handle of the device on which to enable or disable mapping. * @param[in] bEnabled Set to true to enable the feature or false to disable the feature. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetTransformDepthImgToColorSensorEnabled(ScDeviceHandle device, bool bEnabled); /** * @brief Returns the Boolean value of whether the transformed of the depth image to color space feature is enabled or disabled. * @param[in] device The handle of the device on which to enable or disable the feature. * @param[out] bEnabled Pointer to a variable in which to store the returned Boolean value. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetTransformDepthImgToColorSensorEnabled(ScDeviceHandle device, bool* bEnabled); /** * @brief Returns the point value of the frame that the mapping of the depth image to Color space. * @param[in] device The handle of the device on which to enable or disable the feature. * @param[in] depthPoint The point in depth frame. * @param[in] colorSize The size(x = w,y = h) of color frame. * @param[out] pPointInColor The point in the color frame. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scTransformDepthPointToColorPoint(const ScDeviceHandle device, const ScDepthVector3 depthPoint, const ScVector2u16 colorSize, ScVector2u16* pPointInColor); /** * @brief Converts the input points from depth coordinate space to world coordinate space. * @param[in] device The handle of the device on which to perform the operation. * @param[in] pDepthVector Pointer to a buffer containing the x, y, and z values of the depth coordinates to be converted. \n * x and y are measured in pixels, where 0, 0 is located at the top left corner of the image. \n * z is measured in millimeters, based on the ::ScPixelFormat depth frame. * @param[out] pWorldVector Pointer to a buffer in which to output the converted x, y, and z values of the world coordinates, measured in millimeters. * @param[in] pointCount The number of points to convert. * @param[in] pSensorParam The intrinsic parameters for the depth sensor. See ::ScSensorIntrinsicParameters. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scConvertDepthToPointCloud(ScDeviceHandle device, ScDepthVector3* pDepthVector, ScVector3f* pWorldVector, int32_t pointCount, ScSensorIntrinsicParameters* pSensorParam); /** * @brief Converts the input Depth frame from depth coordinate space to world coordinate space on the device. Currently supported depth * image types are SC_DEPTH_FRAME and SC_TRANSFORM_DEPTH_IMG_TO_COLOR_SENSOR_FRAME. * @param[in] device The handle of the device on which to perform the operation. * @param[in] pDepthFrame The depth frame. * @param[out] pWorldVector Pointer to a buffer in which to output the converted x, y, and z values of the world coordinates, * measured in millimeters. The length of pWorldVector must is (ScFrame.width * ScFrame.height). * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scConvertDepthFrameToPointCloudVector(ScDeviceHandle device, const ScFrame* pDepthFrame, ScVector3f* pWorldVector); /** * @brief Set the parameters by Json file that can be saved by ScepterGUITool. * @param[in] device The handle of the device. * @param[in] pfilePath Pointer to the path of Json file. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetParamsByJson(ScDeviceHandle device, char* pfilePath); /** * @brief Export the parameter initialization file from the device. * @param[in] device The handle of the device. * @param[in] pfilePath Pointer to the path of parameter initialization file. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scExportParamInitFile(ScDeviceHandle device, char* pfilePath); /** * @brief Import the parameter initialization file into the device and take effect after reboot the device. * @param[in] device The handle of the device. * @param[in] pfilePath Pointer to the path of parameter initialization file. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scImportParamInitFile(ScDeviceHandle device, char* pfilePath); /** * @brief Restore the parameter initialization file of the device. * @param[in] device The handle of the device. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scRestoreParamInitFile(ScDeviceHandle device); /** * @brief Reboot the camera. * @param[in] device The handle of the device * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scRebootDevie(ScDeviceHandle device); /** * @brief Set hotplug status callback function. * @param[in] pCallback Pointer to the callback function. See ::PtrHotPlugStatusCallback * @param[in] pUserData Pointer to the user data. See ::PtrHotPlugStatusCallback * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scSetHotPlugStatusCallback(PtrHotPlugStatusCallback pCallback, const void* pUserData); /** * @brief Input the firmware file path and start upgrading device firmware. * @param[in] device The handle of the device. * @param[in] pImgPath Pointer to the path of firmware file. The firmware upgrade file is in .img format. * @return ::SC_OK If the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scStartUpgradeFirmWare(ScDeviceHandle device, char* pImgPath); /** * @brief Get firmware upgrade status and progress. * @param[in] device The handle of the device. * @param[out] pStatus Pointer to the status of firmware upgrade. 0 indicates normal, other values indicate anomalies. * @param[out] pProcess Pointer to the process of firmware upgrade, in range [0, 100]. Under normal circumstances, 100 indicates a successful upgrade. * @return ::SC_OK if the function succeeded, or one of the error values defined by ::ScStatus. */ SCEPTER_C_API_EXPORT ScStatus scGetUpgradeStatus(ScDeviceHandle device, int32_t* pStatus, int32_t* pProcess); #endif /* SCEPTER_API_H */