NVIDIA DriveOS Linux NSR SDK API Reference
7.0.3.0 Release
Data Structures | Typedefs | Enumerations | Functions | Variables
Feature 2D Detector Interface
DriveWorks » Image Processing Interface

Detailed Description

Defines 2D-based feature detection.

Data Structures

struct  dwFeature2DDetectorConfig
 Holds configuration parameters for a feature detector. More...
 

Typedefs

typedef struct dwFeature2DDetectorObject * dwFeature2DDetectorHandle_t
 Handle representing a feature detector. More...
 
typedef struct dwFeature2DDetectorObject const * dwConstFeature2DDetectorHandle_t
 Handle representing a const feature detector. More...
 
typedef enum dwFeature2DDetectorType dwFeature2DDetectorType
 Defines different KLT tracking algorithms. More...
 
typedef struct dwFeature2DDetectorConfig dwFeature2DDetectorConfig
 Holds configuration parameters for a feature detector. More...
 

Enumerations

enum  dwFeature2DDetectorType {
  DW_FEATURE2D_DETECTOR_TYPE_STD = 0,
  DW_FEATURE2D_DETECTOR_TYPE_EX,
  DW_FEATURE2D_DETECTOR_TYPE_FAST9,
  DW_FEATURE2D_DETECTOR_TYPE_COUNT
}
 Defines different KLT tracking algorithms. More...
 
enum  dwFeature2DSelectionMaskType {
  DW_FEATURE2D_SELECTION_MASK_TYPE_UNIFORM = 0,
  DW_FEATURE2D_SELECTION_MASK_TYPE_GAUSSIAN,
  DW_FEATURE2D_SELECTION_MASK_TYPE_COUNT
}
 Feature distribution mask for extended detector. More...
 

Functions

DW_API_PUBLIC dwStatus dwFeature2DDetector_initDefaultParams (dwFeature2DDetectorConfig *params)
 Initializes dwFeature2DDetector parameters with default values. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_initDefaultParamsForCamera (dwFeature2DDetectorConfig *params, const dwTransformation3f *cameraToRig, dwConstCameraModelHandle_t cameraHandle)
 Initializes dwFeature2DDetector parameters with values best suited for the given camera using camera extrinsic (dwTransformation3f* cameraToRig) and camera intrinsic (dwConstCameraModelHandle_t cameraHandle) More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_initialize (dwFeature2DDetectorHandle_t *obj, const dwFeature2DDetectorConfig *config, cudaStream_t cudaStream, dwContextHandle_t context)
 Creates and initializes a feature Detector. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_reset (dwFeature2DDetectorHandle_t obj)
 Resets a feature Detector. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_release (dwFeature2DDetectorHandle_t obj)
 Releases the feature Detector. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_setMask (const uint8_t *d_mask, const uint32_t maskStrideBytes, const uint32_t maskWidth, const uint32_t maskHeight, dwFeature2DDetectorHandle_t obj)
 Sets a mask to ignore areas of the image. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_detectFromImage (dwFeatureArray *outputDetections, dwImageHandle_t image, dwFeatureArray *preTrackedFeatures, const float32_t *d_normalizedCrossCorrelation, dwFeature2DDetectorHandle_t obj)
 Detects new features and append them after old tracked features. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_detectFromPyramid (dwFeatureArray *outputDetections, const dwPyramidImage *pyramid, dwFeatureArray *preTrackedFeatures, const float32_t *d_normalizedCrossCorrelation, dwFeature2DDetectorHandle_t obj)
 Detects new features and append them after old tracked features. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_dryrunDetectionImage (dwFeatureArray *outputDetections, dwFeatureArray *preTrackedFeatures, const float32_t *d_normalizedCrossCorrelation, dwFeature2DDetectorHandle_t obj)
 Dryrun the detection to record a CUDA graph. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_dryrunDetectionPyramid (dwFeatureArray *outputDetections, dwFeatureArray *preTrackedFeatures, const float32_t *d_normalizedCrossCorrelation, dwFeature2DDetectorHandle_t obj)
 Dryrun the detection to record a CUDA graph. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_getValidTrackedCount (const uint32_t **d_validTrackedCount, dwFeature2DDetectorHandle_t obj)
 dwFeature2DDetector_getValidTrackedCount More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_setCUDAStream (cudaStream_t stream, dwFeature2DDetectorHandle_t obj)
 Sets the CUDA stream for CUDA related operations. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_getCUDAStream (cudaStream_t *stream, dwFeature2DDetectorHandle_t obj)
 Gets the CUDA stream used by the feature Detector. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_getScoreThreshold (float32_t *scoreThreshold, dwFeature2DDetectorHandle_t obj)
 Get the current score threshold used in Harris detector. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_setScoreThreshold (float32_t scoreThreshold, dwFeature2DDetectorHandle_t obj)
 Set Harris detector's score threshold. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_setPVAStream (cupvaStream_t stream, dwFeature2DDetectorHandle_t obj)
 Sets the CUPVA stream for PVA related operations. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_getPVAStream (cupvaStream_t *stream, dwFeature2DDetectorHandle_t obj)
 Gets the CUPVA stream used by the feature Detector. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_registerInputNccScore (float32_t *nccScore, uint32_t nccScoreArraySize, dwFeature2DDetectorHandle_t obj)
 Binds input ncc Score. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_registerHistoryArray (dwFeatureHistoryArray *historyArray, dwFeature2DDetectorHandle_t obj)
 Binds feature HistoryArray. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_registerFeatureArray (dwFeatureArray *inFeatures, dwFeature2DDetectorHandle_t obj)
 Binds feature Array. More...
 

Variables

const uint32_t DW_FEATURES2D_DETECTOR_MAX_CELL_SIZE = 128
 
enum  dwFeature2DDetectorStage {
  DW_FEATURE2D_DETECTOR_STAGE_GPU_ASYNC = 0,
  DW_FEATURE2D_DETECTOR_STAGE_GPU_ASYNC_DATA_PREPARE = 100,
  DW_FEATURE2D_DETECTOR_STAGE_CPU_SYNC_DATA_PREPARE = 101,
  DW_FEATURE2D_DETECTOR_STAGE_PVA_ASYNC_DETECT_IMAGE = 102,
  DW_FEATURE2D_DETECTOR_STAGE_CPU_SYNC_DATA_POSTPROCESS = 103,
  DW_FEATURE2D_DETECTOR_STAGE_GPU_ASYNC_DATA_POSTPROCESS = 104
}
 Defines 2D-based feature detection. More...
 
typedef enum dwFeature2DDetectorStage dwFeature2DDetectorStage
 Defines 2D-based feature detection. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_bindOutput (dwFeatureArray *outputDetections, dwFeature2DDetectorHandle_t obj)
 Bind output dwFeatureArray to detector object. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_bindInputImage (dwImageHandle_t image, dwFeatureArray *preTrackedFeatures, const float32_t *d_normalizedCrossCorrelation, dwFeature2DDetectorHandle_t obj)
 Bind input parameters to detector object. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_processImage (dwFeature2DDetectorStage stage, dwFeature2DDetectorHandle_t obj)
 Do detections on the image bound by dwFeature2DDetector_bindInputImage, output will be written to dwFeatureArray bound by dwFeature2DDetector_bindOutput. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_bindInputPyramid (const dwPyramidImage *pyramid, dwFeatureArray *preTrackedFeatures, const float32_t *d_normalizedCrossCorrelation, dwFeature2DDetectorHandle_t obj)
 Bind input parameters to detector object. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_processPyramid (dwFeature2DDetectorStage stage, dwFeature2DDetectorHandle_t obj)
 Do detections on the pyramid bound by dwFeature2DDetector_bindInputPyramid, output will be written to dwFeatureArray bound by dwFeature2DDetector_bindOutput. More...
 
enum  dwFeature2DSelectionMaskTypeExtra {
  DW_FEATURE2D_SELECTION_MASK_TYPE_EXTRA_UNIFORM = 0,
  DW_FEATURE2D_SELECTION_MASK_TYPE_EXTRA_GAUSSIAN = 1,
  DW_FEATURE2D_SELECTION_MASK_TYPE_EXTRA_ROAD_SURFACE = 2,
  DW_FEATURE2D_SELECTION_MASK_TYPE_EXTRA_COUNT = 3
}
 Defines internal functions of 2D-based feature detection. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_initDefaultParamsExtra (dwFeature2DDetectorConfigExtra *params)
 Initializes dwFeature2DDetector parameters with default values. More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_initDefaultParamsForCameraExtra (dwFeature2DDetectorConfigExtra *params, const dwTransformation3f *cameraToRig, dwConstCameraModelHandle_t cameraHandle)
 Initializes dwFeature2DDetector parameters with values best suited for the given camera using camera extrinsic (dwTransformation3f* cameraToRig) and camera intrinsic (dwConstCameraModelHandle_t cameraHandle) More...
 
DW_API_PUBLIC dwStatus dwFeature2DDetector_initializeExtra (dwFeature2DDetectorHandle_t *obj, const dwFeature2DDetectorConfigExtra *config, cudaStream_t cudaStream, dwContextHandle_t context)
 Creates and initializes a feature Detector. More...
 

Typedef Documentation

◆ dwConstFeature2DDetectorHandle_t

typedef struct dwFeature2DDetectorObject const* dwConstFeature2DDetectorHandle_t

Handle representing a const feature detector.

Definition at line 49 of file FeatureDetector.h.

◆ dwFeature2DDetectorConfig

typedef struct dwFeature2DDetectorConfig dwFeature2DDetectorConfig

Holds configuration parameters for a feature detector.

◆ dwFeature2DDetectorHandle_t

typedef struct dwFeature2DDetectorObject* dwFeature2DDetectorHandle_t

Handle representing a feature detector.

Definition at line 46 of file FeatureDetector.h.

◆ dwFeature2DDetectorStage

typedef enum dwFeature2DDetectorStage dwFeature2DDetectorStage

Defines 2D-based feature detection.

The stage of feature tracker Pipeline running order is either 0), or 1). 1) 0 which runs feature detector for image on GPU 1) 100->101->102->103->104 which runs feature detector for image on a combination of processors, mainly on PVA.

◆ dwFeature2DDetectorType

typedef enum dwFeature2DDetectorType dwFeature2DDetectorType

Defines different KLT tracking algorithms.

Enumeration Type Documentation

◆ dwFeature2DDetectorStage

enum dwFeature2DDetectorStage

Defines 2D-based feature detection.

The stage of feature tracker Pipeline running order is either 0), or 1). 1) 0 which runs feature detector for image on GPU 1) 100->101->102->103->104 which runs feature detector for image on a combination of processors, mainly on PVA.

Enumerator
DW_FEATURE2D_DETECTOR_STAGE_GPU_ASYNC 

GPU Async stage.

DW_FEATURE2D_DETECTOR_STAGE_GPU_ASYNC_DATA_PREPARE 

Process the preprocessing part of the feature detector pipeline on GPU.

DW_FEATURE2D_DETECTOR_STAGE_CPU_SYNC_DATA_PREPARE 

Process the preprocessing part of the feature detector pipeline on CPU.

DW_FEATURE2D_DETECTOR_STAGE_PVA_ASYNC_DETECT_IMAGE 

Process the tracking part of the feature detector pipeline on PVA.

DW_FEATURE2D_DETECTOR_STAGE_CPU_SYNC_DATA_POSTPROCESS 

Process the postprocess part of the feature detector pipeline on CPU.

DW_FEATURE2D_DETECTOR_STAGE_GPU_ASYNC_DATA_POSTPROCESS 

Process the postprocess part of the feature detector pipeline on GPU.

Definition at line 43 of file FeatureDetector_processpipeline.h.

◆ dwFeature2DDetectorType

enum dwFeature2DDetectorType

Defines different KLT tracking algorithms.

Enumerator
DW_FEATURE2D_DETECTOR_TYPE_STD 

Standard Harris Corner detector with fixed parameters, quicker.

DW_FEATURE2D_DETECTOR_TYPE_EX 

Extended Harris Corner detector with more configurable parameters, more flexible, better quality but slower.

DW_FEATURE2D_DETECTOR_TYPE_FAST9 

Fast corner detector, quicker.

This algorithm was introduced by Edward Rosten and Tom Drummond in their paper "Machine learning for high-speed corner detection" in 2006

DW_FEATURE2D_DETECTOR_TYPE_COUNT 

Definition at line 54 of file FeatureDetector.h.

◆ dwFeature2DSelectionMaskType

enum dwFeature2DSelectionMaskType

Feature distribution mask for extended detector.

Enumerator
DW_FEATURE2D_SELECTION_MASK_TYPE_UNIFORM 

output feature in uniform distribution

DW_FEATURE2D_SELECTION_MASK_TYPE_GAUSSIAN 

output feature in 2D gaussian distribution which has more features in center area and less ones in boundary

DW_FEATURE2D_SELECTION_MASK_TYPE_COUNT 

Definition at line 70 of file FeatureDetector.h.

◆ dwFeature2DSelectionMaskTypeExtra

enum dwFeature2DSelectionMaskTypeExtra

Defines internal functions of 2D-based feature detection.

Feature distribution mask for extended detector

Enumerator
DW_FEATURE2D_SELECTION_MASK_TYPE_EXTRA_UNIFORM 

output feature in uniform distribution

DW_FEATURE2D_SELECTION_MASK_TYPE_EXTRA_GAUSSIAN 

output feature in 2D gaussian distribution which has more features in center area and less ones in boundary

DW_FEATURE2D_SELECTION_MASK_TYPE_EXTRA_ROAD_SURFACE 

output feature focusing on road surface within 30m; it has only been tested on 60fov/120fov front cameras

DW_FEATURE2D_SELECTION_MASK_TYPE_EXTRA_COUNT 

Definition at line 38 of file FeatureDetectorExtra.h.

Function Documentation

◆ dwFeature2DDetector_bindInputImage()

DW_API_PUBLIC dwStatus dwFeature2DDetector_bindInputImage ( dwImageHandle_t  image,
dwFeatureArray *  preTrackedFeatures,
const float32_t *  d_normalizedCrossCorrelation,
dwFeature2DDetectorHandle_t  obj 
)

Bind input parameters to detector object.

Parameters
[in]imageSpecifies the image on which feature detection takes place, must be a CUDA image.
[in,out]preTrackedFeaturesPrevious tracked features, if detector type is DW_FEATURE2D_DETECTOR_TYPE_EX, some of old features will be marked as DW_FEATURE2D_STATUS_INVALID during detection. The dwFeatureArray can either be an empty array allocated by dwFeatureArray_createNew or a slice from feature history by dwFeatureHistoryArray_getXXX
[in]d_normalizedCrossCorrelationGPU pointer to nccScores of each feature, will be ignored if it's NULL. If the feature detector is connected to a tracker, d_normalizedCrossCorrelation can be filled by dwFeature2DTracker_trackFeatures.
[in]objSpecifies the feature detector handle.
Returns
DW_INVALID_ARGUMENT if detector handle, preTrackedFeatures or image are NULL.
DW_INVALID_ARGUMENT if preTrackedFeatures are not allocated on GPU.
DW_CALL_NOT_ALLOWED if target is safety platform and useCudaGraph is on, preTrackedFeatures or d_normalizedCrossCorrelation address changes.
DW_SUCCESS otherwise.
Note
dwFeature2DDetector_bindInputImage must be called at least once before dwFeature2DDetector_processImage.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_bindInputPyramid()

DW_API_PUBLIC dwStatus dwFeature2DDetector_bindInputPyramid ( const dwPyramidImage *  pyramid,
dwFeatureArray *  preTrackedFeatures,
const float32_t *  d_normalizedCrossCorrelation,
dwFeature2DDetectorHandle_t  obj 
)

Bind input parameters to detector object.

Parameters
[in]pyramidSpecifies the pyramid on which feature detection takes place.
[in,out]preTrackedFeaturesPrevious tracked features, if detector type is DW_FEATURE2D_DETECTOR_TYPE_EX, some of old features will be marked as DW_FEATURE2D_STATUS_INVALID during detection. The dwFeatureArray can either be an empty array allocated by dwFeatureArray_createNew or a slice from feature history by dwFeatureHistoryArray_getXXX *
[in]d_normalizedCrossCorrelationGPU pointer to nccScores of each feature, will be ignored if it's NULL. If the feature detector is connected to a tracker, d_normalizedCrossCorrelation can be filled by dwFeature2DTracker_trackFeatures.
[in]objSpecifies the feature detector handle.
Returns
DW_INVALID_ARGUMENT if detector handle, preTrackedFeatures or image are NULL.
DW_INVALID_ARGUMENT if preTrackedFeatures are not allocated on GPU.
DW_CALL_NOT_ALLOWED if target is safety platform and useCudaGraph is on, preTrackedFeatures or d_normalizedCrossCorrelation address changes.
DW_SUCCESS otherwise.
Note
dwFeature2DDetector_bindInputPyramid must be called at least once before dwFeature2DDetector_processPyramid.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_bindOutput()

DW_API_PUBLIC dwStatus dwFeature2DDetector_bindOutput ( dwFeatureArray *  outputDetections,
dwFeature2DDetectorHandle_t  obj 
)

Bind output dwFeatureArray to detector object.

Parameters
[out]outputDetectionsDetected features, composed of old tracked features and new detections, new detections are appended after old features. Must be created by dwFeatureArray_createNew() with DW_PROCESSOR_TYPE_GPU flag and the same maxFeatureCount when initializing detector
[in]objSpecifies the feature detector handle.
Returns
DW_INVALID_ARGUMENT if detector handle or outputDetections are NULL.
DW_INVALID_ARGUMENT if outputDetections is not created with detector compatible parameters.
DW_CALL_NOT_ALLOWED if target is safety platform and useCudaGraph is on, outputDetections address changes.
DW_SUCCESS otherwise.
Note
App must call dwFeature2DDetector_bindOutput to set output feature array.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_detectFromImage()

DW_API_PUBLIC dwStatus dwFeature2DDetector_detectFromImage ( dwFeatureArray *  outputDetections,
dwImageHandle_t  image,
dwFeatureArray *  preTrackedFeatures,
const float32_t *  d_normalizedCrossCorrelation,
dwFeature2DDetectorHandle_t  obj 
)

Detects new features and append them after old tracked features.

Features are added only in areas where the mask == 0xff means valid area, any pixel whose mask value != 0xff will be ignored during tracking.

Parameters
[out]outputDetectionsDetected features, composed of old tracked features and new detections, new detections are appended after old features. Must be created by dwFeatureArray_createNew() with DW_PROCESSOR_TYPE_GPU flag and the same maxFeatureCount when initializing detector
[in]imageSpecifies the image on which feature detection takes place, must be a CUDA image.
[in,out]preTrackedFeaturesPrevious tracked features, if detector type is DW_FEATURE2D_DETECTOR_TYPE_EX, some of old features will be marked as DW_FEATURE2D_STATUS_INVALID during detection. The dwFeatureArray can either be an empty array allocated by dwFeatureArray_createNew or a slice from feature history by dwFeatureHistoryArray_getXXX
[in]d_normalizedCrossCorrelationGPU pointer to nccScores of each feature, will be ignored if it's NULL. If the feature detector is connected to a tracker, d_normalizedCrossCorrelation can be filled by dwFeature2DTracker_trackFeatures.
[in]objSpecifies the feature detector handle.
Returns
DW_INVALID_ARGUMENT if detector handle or preTrackedFeatures are NULL.
DW_INVALID_ARGUMENT if preTrackedFeatures are not allocated on GPU.
DW_CALL_NOT_ALLOWED if target is safety platform and useCudaGraph is on, either outputDetections, preTrackedFeatures or d_normalizedCrossCorrelation's address changes
DW_SUCCESS otherwise.
Note
In safety platform, if useCudaGraph is on, dwFeature2DDetector_dryrunDetectionImage must be called at least one time before any dwFeature2DDetector_detectFromImage in INIT state, elsewise dwFeature2DDetector_detectFromImage may have unexpected behavior.

If there're N features in preTrackedFeatures, for DW_FEATURE2D_DETECTOR_TYPE_STD, the first N features in detectedFeatures are from preTrackedFeaturs, new detections are appended after old ones. for DW_FEATURE2D_DETECTOR_TYPE_EX, the first M(M <= N) features in detectedFeatures are from preTrackedFeaturs new detections are appended after old ones. The reason that M <= N is that some features in preTrackedFeatures will be marked as invalid to meet the restriction of uniform/gaussian distribution.

API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

◆ dwFeature2DDetector_detectFromPyramid()

DW_API_PUBLIC dwStatus dwFeature2DDetector_detectFromPyramid ( dwFeatureArray *  outputDetections,
const dwPyramidImage *  pyramid,
dwFeatureArray *  preTrackedFeatures,
const float32_t *  d_normalizedCrossCorrelation,
dwFeature2DDetectorHandle_t  obj 
)

Detects new features and append them after old tracked features.

Features are added only in areas where the mask == 0xff means valid area, any pixel whose mask value != 0xff will be ignored during tracking.

Parameters
[out]outputDetectionsDetected features, composed of old tracked features and new detections, new detections are appended after old features. Must be created by dwFeatureArray_createNew() with DW_PROCESSOR_TYPE_GPU flag and the same maxFeatureCount when initializing detector
[in]pyramidSpecifies the pyramid on which feature detection takes place.
[in,out]preTrackedFeaturesPrevious tracked features, if detector type is DW_FEATURE2D_DETECTOR_TYPE_EX, some of old features will be marked as DW_FEATURE2D_STATUS_INVALID during detection. The dwFeatureArray can either be an empty array allocated by dwFeatureArray_createNew or a slice from feature history by dwFeatureHistoryArray_getXXX *
[in]d_normalizedCrossCorrelationGPU pointer to nccScores of each feature, will be ignored if it's NULL. If the feature detector is connected to a tracker, d_normalizedCrossCorrelation can be filled by dwFeature2DTracker_trackFeatures.
[in]objSpecifies the feature detector handle.
Returns
DW_INVALID_ARGUMENT if detector handle, preTrackedFeatures or image are NULL.
DW_INVALID_ARGUMENT if preTrackedFeatures are not allocated on GPU.
DW_CALL_NOT_ALLOWED if target is safety platform and useCudaGraph is on, either outputDetections, preTrackedFeatures or d_normalizedCrossCorrelation's address changes.
DW_SUCCESS otherwise.
Note
In safety platform, if useCudaGraph is on, dwFeature2DDetector_dryrunDetectionPyramid must be called at least one time before any dwFeature2DDetector_detectFromPyramid in INIT state, elsewise dwFeature2DDetector_detectFromPyramid may have unexpected behavior.

If there're N features in preTrackedFeatures, for DW_FEATURE2D_DETECTOR_TYPE_STD, the first N features in detectedFeatures are from preTrackedFeaturs, new detections are appended after old ones. for DW_FEATURE2D_DETECTOR_TYPE_EX, the first M(M <= N) features in detectedFeatures are from preTrackedFeaturs new detections are appended after old ones. The reason that M <= N is that some features in preTrackedFeatures will be marked as invalid to meet the restriction of uniform/gaussian distribution.

API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

◆ dwFeature2DDetector_dryrunDetectionImage()

DW_API_PUBLIC dwStatus dwFeature2DDetector_dryrunDetectionImage ( dwFeatureArray *  outputDetections,
dwFeatureArray *  preTrackedFeatures,
const float32_t *  d_normalizedCrossCorrelation,
dwFeature2DDetectorHandle_t  obj 
)

Dryrun the detection to record a CUDA graph.

Parameters
[out]outputDetectionsDetected features, composed of old tracked features and new detections, new detections are appended after old features. Must be created by dwFeatureArray_createNew() with DW_PROCESSOR_TYPE_GPU flag and the same maxFeatureCount when initializing detector
[in,out]preTrackedFeaturesPrevious tracked features, if detector type is DW_FEATURE2D_DETECTOR_TYPE_EX, some of old features will be marked as DW_FEATURE2D_STATUS_INVALID during detection. The dwFeatureArray can either be an empty array allocated by dwFeatureArray_createNew or a slice from feature history by dwFeatureHistoryArray_getXXX
[in]d_normalizedCrossCorrelationGPU pointer to nccScores of each feature, will be ignored if it's NULL. If the feature detector is connected to a tracker, d_normalizedCrossCorrelation can be filled by dwFeature2DTracker_trackFeatures.
[in]objSpecifies the feature detector handle.
Returns
DW_INVALID_ARGUMENT if detector handle, preTrackedFeatures or image are NULL.
DW_INVALID_ARGUMENT if preTrackedFeatures are not allocated on GPU.
DW_INVALID_HANDLE if image is not a CUDA image.
DW_SUCCESS otherwise.
Note
This API MUST be called at least one time in INIT state in safety platform if if useCudaGraph is on, elsewise dwFeature2DDetector_detectFromImage may have unexpected behavior. For PVA detector, there's no such restriction.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_dryrunDetectionPyramid()

DW_API_PUBLIC dwStatus dwFeature2DDetector_dryrunDetectionPyramid ( dwFeatureArray *  outputDetections,
dwFeatureArray *  preTrackedFeatures,
const float32_t *  d_normalizedCrossCorrelation,
dwFeature2DDetectorHandle_t  obj 
)

Dryrun the detection to record a CUDA graph.

Parameters
[out]outputDetectionsDetected features, composed of old tracked features and new detections, new detections are appended after old features. Must be created by dwFeatureArray_createNew() with DW_PROCESSOR_TYPE_GPU flag and the same maxFeatureCount when initializing detector
[in,out]preTrackedFeaturesPrevious tracked features, if detector type is DW_FEATURE2D_DETECTOR_TYPE_EX, some of old features will be marked as DW_FEATURE2D_STATUS_INVALID during detection. The dwFeatureArray can either be an empty array allocated by dwFeatureArray_createNew or a slice from feature history by dwFeatureHistoryArray_getXXX *
[in]d_normalizedCrossCorrelationGPU pointer to nccScores of each feature, will be ignored if it's NULL. If the feature detector is connected to a tracker, d_normalizedCrossCorrelation can be filled by dwFeature2DTracker_trackFeatures.
[in]objSpecifies the feature detector handle.
Returns
DW_INVALID_ARGUMENT if detector handle or preTrackedFeatures.
DW_INVALID_ARGUMENT if preTrackedFeatures are not allocated on GPU.
DW_SUCCESS otherwise.
Note
This API MUST be called at least one time in INIT state in safety platform if useCudaGraph is on, elsewise dwFeature2DDetector_detectFromPyramid may have unexpected behavior. For PVA detector, there's no such restriction.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_getCUDAStream()

DW_API_PUBLIC dwStatus dwFeature2DDetector_getCUDAStream ( cudaStream_t *  stream,
dwFeature2DDetectorHandle_t  obj 
)

Gets the CUDA stream used by the feature Detector.

Parameters
[out]streamThe CUDA stream currently used.
[in]objA handle to the feature Detector module.
Returns
DW_INVALID_ARGUMENT if feature Detector handle or stream are NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_getPVAStream()

DW_API_PUBLIC dwStatus dwFeature2DDetector_getPVAStream ( cupvaStream_t *  stream,
dwFeature2DDetectorHandle_t  obj 
)

Gets the CUPVA stream used by the feature Detector.

Parameters
[out]streamThe CUPVA stream currently used.
[in]objA handle to the feature Detector module.
Returns
DW_INVALID_ARGUMENT if feature Detector handle or stream are NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_getScoreThreshold()

DW_API_PUBLIC dwStatus dwFeature2DDetector_getScoreThreshold ( float32_t *  scoreThreshold,
dwFeature2DDetectorHandle_t  obj 
)

Get the current score threshold used in Harris detector.

Parameters
[out]scoreThresholdCurrent score threshold used
[in]objA handle to the feature Detector module.
Returns
DW_INVALID_ARGUMENT if feature Detector handle or scoreTheshold is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_getValidTrackedCount()

DW_API_PUBLIC dwStatus dwFeature2DDetector_getValidTrackedCount ( const uint32_t **  d_validTrackedCount,
dwFeature2DDetectorHandle_t  obj 
)

dwFeature2DDetector_getValidTrackedCount

Parameters
d_validTrackedCount
obj
Returns
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_initDefaultParams()

DW_API_PUBLIC dwStatus dwFeature2DDetector_initDefaultParams ( dwFeature2DDetectorConfig *  params)

Initializes dwFeature2DDetector parameters with default values.

Parameters
[in,out]paramsdwFeature2DDetector parameters; user can optionally set imageWidth/imageHeight before the API call to obtain the default parameters for the resolution
Returns
DW_INVALID_ARGUMENT if params is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

◆ dwFeature2DDetector_initDefaultParamsExtra()

DW_API_PUBLIC dwStatus dwFeature2DDetector_initDefaultParamsExtra ( dwFeature2DDetectorConfigExtra *  params)

Initializes dwFeature2DDetector parameters with default values.

Parameters
[out]paramsdwFeature2DDetector parameters
Returns
DW_INVALID_ARGUMENT if params is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

◆ dwFeature2DDetector_initDefaultParamsForCamera()

DW_API_PUBLIC dwStatus dwFeature2DDetector_initDefaultParamsForCamera ( dwFeature2DDetectorConfig *  params,
const dwTransformation3f *  cameraToRig,
dwConstCameraModelHandle_t  cameraHandle 
)

Initializes dwFeature2DDetector parameters with values best suited for the given camera using camera extrinsic (dwTransformation3f* cameraToRig) and camera intrinsic (dwConstCameraModelHandle_t cameraHandle)

Parameters
[out]paramsdwFeature2DDetector parameters
[in]cameraToRigtransformed camera extrinsic parameters with respect to rig
[in]cameraHandleholds camera intrinsic information
Returns
DW_INVALID_ARGUMENT if any parameter is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

◆ dwFeature2DDetector_initDefaultParamsForCameraExtra()

DW_API_PUBLIC dwStatus dwFeature2DDetector_initDefaultParamsForCameraExtra ( dwFeature2DDetectorConfigExtra *  params,
const dwTransformation3f *  cameraToRig,
dwConstCameraModelHandle_t  cameraHandle 
)

Initializes dwFeature2DDetector parameters with values best suited for the given camera using camera extrinsic (dwTransformation3f* cameraToRig) and camera intrinsic (dwConstCameraModelHandle_t cameraHandle)

Parameters
[out]paramsdwFeature2DDetector parameters
[in]cameraToRigtransformed camera extrinsic parameters with respect to rig
[in]cameraHandleholds camera intrinsic information
Returns
DW_INVALID_ARGUMENT if any parameter is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

◆ dwFeature2DDetector_initialize()

DW_API_PUBLIC dwStatus dwFeature2DDetector_initialize ( dwFeature2DDetectorHandle_t *  obj,
const dwFeature2DDetectorConfig *  config,
cudaStream_t  cudaStream,
dwContextHandle_t  context 
)

Creates and initializes a feature Detector.

Parameters
[out]objA pointer to the feature Detector handle is returned here.
[in]configSpecifies the configuration parameters.
[in]cudaStreamSpecifies the CUDA stream to use for Detector operations.
[in]contextSpecifies the handle to the context under which it is created.
Returns
DW_INVALID_ARGUMENT if feature Detector handle or context are NULL or config is invalid.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

◆ dwFeature2DDetector_initializeExtra()

DW_API_PUBLIC dwStatus dwFeature2DDetector_initializeExtra ( dwFeature2DDetectorHandle_t *  obj,
const dwFeature2DDetectorConfigExtra *  config,
cudaStream_t  cudaStream,
dwContextHandle_t  context 
)

Creates and initializes a feature Detector.

Parameters
[out]objA pointer to the feature Detector handle is returned here.
[in]configSpecifies the configuration parameters.
[in]cudaStreamSpecifies the CUDA stream to use for Detector operations.
[in]contextSpecifies the handle to the context under which it is created.
Returns
DW_INVALID_ARGUMENT if feature Detector handle or context are NULL or config is invalid.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: No
  • De-Init: No

◆ dwFeature2DDetector_processImage()

DW_API_PUBLIC dwStatus dwFeature2DDetector_processImage ( dwFeature2DDetectorStage  stage,
dwFeature2DDetectorHandle_t  obj 
)

Do detections on the image bound by dwFeature2DDetector_bindInputImage, output will be written to dwFeatureArray bound by dwFeature2DDetector_bindOutput.

Features are added only in areas where the mask == 0xff means valid area, any pixel whose mask value != 0xff will be ignored during tracking.

Parameters
[in]stageSpeicifies the detecting stage
[in]objSpecifies the feature detector handle.
Returns
DW_CALL_NOT_ALLOWED if there's no output dwFeatureArray bound to detector.
if there's no input image or preTrackedFeatures bound to detector.
DW_SUCCESS otherwise.
Note
In safety platform while useCudaGraph is on, dwFeature2DDetector_dryrunDetectionImage must be called at least one time before any dwFeature2DDetector_processImage in INIT state, elsewise dwFeature2DDetector_processPyramid may have unexpected behavior

If there're N features in preTrackedFeatures, for DW_FEATURE2D_DETECTOR_TYPE_STD, the first N features in detectedFeatures are from preTrackedFeaturs, new detections are appended after old ones. for DW_FEATURE2D_DETECTOR_TYPE_EX, the first M(M <= N) features in detectedFeatures are from preTrackedFeaturs new detections are appended after old ones. The reason that M <= N is that some features in preTrackedFeatures will be marked as invalid to meet the restriction of uniform/gaussian distribution.

API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_processPyramid()

DW_API_PUBLIC dwStatus dwFeature2DDetector_processPyramid ( dwFeature2DDetectorStage  stage,
dwFeature2DDetectorHandle_t  obj 
)

Do detections on the pyramid bound by dwFeature2DDetector_bindInputPyramid, output will be written to dwFeatureArray bound by dwFeature2DDetector_bindOutput.

Features are added only in areas where the mask == 0xff means valid area, any pixel whose mask value != 0xff will be ignored during tracking.

Parameters
[in]stageSpeicifies the detecting stage
[in]objSpecifies the feature detector handle.
Returns
DW_CALL_NOT_ALLOWED if there's no output dwFeatureArray bound to detector.
if there's no input pyramid or preTrackedFeatures bound to detector.
DW_SUCCESS otherwise.
Note
In safety platform while useCudaGraph is on, dwFeature2DDetector_dryrunDetectionPyramid must be called at least one time before any dwFeature2DDetector_processPyramid in INIT state, elsewise dwFeature2DDetector_processPyramid may have unexpected behavior

If there're N features in preTrackedFeatures, for DW_FEATURE2D_DETECTOR_TYPE_STD, the first N features in detectedFeatures are from preTrackedFeaturs, new detections are appended after old ones. for DW_FEATURE2D_DETECTOR_TYPE_EX, the first M(M <= N) features in detectedFeatures are from preTrackedFeaturs new detections are appended after old ones. The reason that M <= N is that some features in preTrackedFeatures will be marked as invalid to meet the restriction of uniform/gaussian distribution.

API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_registerFeatureArray()

DW_API_PUBLIC dwStatus dwFeature2DDetector_registerFeatureArray ( dwFeatureArray *  inFeatures,
dwFeature2DDetectorHandle_t  obj 
)

Binds feature Array.

Internally the cuda pointer to featureArray is mapped to pva address space using the cupva cuda interop api

Parameters
[in]inFeaturescuda pointer to Feature Array
[in]objA handle to the feature detector module.
Returns
DW_NOT_SUPPORTED if the api is called for non pva platform. DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_registerHistoryArray()

DW_API_PUBLIC dwStatus dwFeature2DDetector_registerHistoryArray ( dwFeatureHistoryArray *  historyArray,
dwFeature2DDetectorHandle_t  obj 
)

Binds feature HistoryArray.

Internally, this function maps the feature history array to the PVA address space using the cupva cuda interop API.

Parameters
[in]historyArraycuda pointer to Complete feature History Array
[in]objA handle to the feature tracker module.
Returns
DW_NOT_SUPPORTED if the api is called for non pva platform. DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_registerInputNccScore()

DW_API_PUBLIC dwStatus dwFeature2DDetector_registerInputNccScore ( float32_t *  nccScore,
uint32_t  nccScoreArraySize,
dwFeature2DDetectorHandle_t  obj 
)

Binds input ncc Score.

Internally the cuda pointer to nccScore is mapped to pva address space using the cupva cuda interop api

Parameters
[in]nccScorecuda pointer to Input NccScore
[in]objA handle to the feature detector module.
[in]nccScoreArraySizeNumber of elements in the ncc Score Array.
Returns
DW_NOT_SUPPORTED if the api is called for non pva platform. DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_release()

DW_API_PUBLIC dwStatus dwFeature2DDetector_release ( dwFeature2DDetectorHandle_t  obj)

Releases the feature Detector.

This method releases all resources associated with a feature Detector.

Note
This method renders the handle unusable.
Parameters
[in]objThe feature detector handle to be released.
Returns
DW_INVALID_ARGUMENT if feature Detector handle is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: No
  • De-Init: Yes

◆ dwFeature2DDetector_reset()

DW_API_PUBLIC dwStatus dwFeature2DDetector_reset ( dwFeature2DDetectorHandle_t  obj)

Resets a feature Detector.

Parameters
[in]objSpecifies the feature Detector handle to be reset.
Returns
DW_INVALID_ARGUMENT if feature Detector handle is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_setCUDAStream()

DW_API_PUBLIC dwStatus dwFeature2DDetector_setCUDAStream ( cudaStream_t  stream,
dwFeature2DDetectorHandle_t  obj 
)

Sets the CUDA stream for CUDA related operations.

Note
The ownership of the stream remains by the callee.
Parameters
[in]streamThe CUDA stream to be used. Default is the one passed during dwFeature2DDetector_initialize.
[in]objA handle to the feature Detector module to set CUDA stream for.
Returns
DW_INVALID_ARGUMENT if feature Detector handle is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_setMask()

DW_API_PUBLIC dwStatus dwFeature2DDetector_setMask ( const uint8_t *  d_mask,
const uint32_t  maskStrideBytes,
const uint32_t  maskWidth,
const uint32_t  maskHeight,
dwFeature2DDetectorHandle_t  obj 
)

Sets a mask to ignore areas of the image.

Areas where mask != 0xff will not produce new features when detectNewFeatures() is called. The size of the mask must be the same as the image.

Note
If this function is called after dwFeature2DDetector_initialize(), it must be called with the same input parameters after dwFeature2DDetector_reset because reset() function will clear the existing mask.
Parameters
[in]d_maskA GPU pointer to the mask data. The data is copied.
[in]maskStrideBytesSpecifies the stride, in bytes, for each row of the mask.
[in]maskWidthSpecifies the width of the mask.
[in]maskHeightSpecifies the height of the mask.
[in]objSpecifies the feature detector handle.
Returns
DW_INVALID_ARGUMENT if feature Detector handle or d_mask are NULL or maskWidth or maskHeight are invalid.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_setPVAStream()

DW_API_PUBLIC dwStatus dwFeature2DDetector_setPVAStream ( cupvaStream_t  stream,
dwFeature2DDetectorHandle_t  obj 
)

Sets the CUPVA stream for PVA related operations.

Note
The ownership of the stream remains by the callee.
Parameters
[in]streamThe CUPVA stream to be used. Default is the one passed during dwFeature2DDetector_initialize.
[in]objA handle to the feature Detector module to set CUPVA stream for.
Returns
DW_INVALID_ARGUMENT if feature Detector handle is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

◆ dwFeature2DDetector_setScoreThreshold()

DW_API_PUBLIC dwStatus dwFeature2DDetector_setScoreThreshold ( float32_t  scoreThreshold,
dwFeature2DDetectorHandle_t  obj 
)

Set Harris detector's score threshold.

It's similar to dwFeature2DDetectorConfig::scoreThreshold, but this API allows setting the values in runtime.

Parameters
[in]scoreThresholdThreshold to filter out low frequency points. All points whose scores are less than scoreThreshold will be considered as a non-feature point. Lower value will output more features, higher value will only keep the high frequency points.
[in]objA handle to the feature Detector module.
Returns
DW_INVALID_ARGUMENT if feature Detector handle is NULL.
DW_SUCCESS otherwise.
API Group
  • Init: Yes
  • Runtime: Yes
  • De-Init: Yes

Variable Documentation

◆ DW_FEATURES2D_DETECTOR_MAX_CELL_SIZE

const uint32_t DW_FEATURES2D_DETECTOR_MAX_CELL_SIZE = 128

Definition at line 231 of file FeatureDetector.h.