DriveWorks SDK Reference

| 0.6.67 Release

Feature List

Detailed Description

Defines the feature list used by the tracker.

Data Structures

struct  dwFeatureListPointers
 Holds pointers to the data exposed by a feature list. More...
 

Enumerations

enum  dwFeatureStatus {
  DW_FEATURE_STATUS_INVALID = 0,
  DW_FEATURE_STATUS_DETECTED,
  DW_FEATURE_STATUS_TRACKED,
  DW_FEATURE_STATUS_TYPE_COUNT
}
 Defines the possible status of a feature. More...
 

Functions

DW_API_PUBLIC dwStatus dwFeatureList_compact (dwFeatureListHandle_t featureList, const uint32_t *d_validIndexCount, const uint32_t *d_validIndexes, const uint32_t *d_invalidIndexCount, const uint32_t *d_invalidIndexes)
 Removes features from the list. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_getCUDAStream (cudaStream_t *stream, dwFeatureListHandle_t obj)
 Gets the CUDA stream used by the feature list. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_getCurrentTimeIdx (uint32_t *currentTimeIdx, dwFeatureListHandle_t obj)
 Returns the current time index of feature-history circular buffer. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_getDataBasePointer (void **d_basePointer, size_t *size, dwFeatureListHandle_t obj)
 Returns the start position of the data buffer that stores all of the feature list information (in GPU memory). More...
 
DW_API_PUBLIC dwStatus dwFeatureList_getDataPointers (dwFeatureListPointers *pointers, void *basePointer, dwFeatureListHandle_t obj)
 Returns the pointers to the actual data of a feature list given the base pointer. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_getFeatureListSize (uint32_t *maxFeatureCount, uint32_t *historyCapacity, dwFeatureListHandle_t obj)
 Returns the maximum feature count and history capacity of the feature list. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_initialize (dwFeatureListHandle_t *obj, dwContextHandle_t context, cudaStream_t stream, const uint32_t maxFeatureCount, const uint32_t historyCapacity, const uint32_t imageWidth, uint32_t imageHeight)
 Creates and initializes a feature list. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_proximityFilter (dwFeatureListHandle_t list)
 Invalidates features that are too close to each other. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_release (dwFeatureListHandle_t *obj)
 Releases the feature list. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_reset (dwFeatureListHandle_t obj)
 Resets the feature list. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_selectValid (uint32_t *d_validIndexCount, uint32_t *d_validIndexes, uint32_t *d_invalidIndexCount, uint32_t *d_invalidIndexes, dwConstFeatureListHandle_t obj)
 Creates a list of indexes of those features with a status of detected or tracked, and list of indexes of those features with a status of invalid. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_setCUDAStream (cudaStream_t stream, dwFeatureListHandle_t obj)
 Sets the CUDA stream for CUDA related operations. More...
 
DW_API_PUBLIC dwStatus dwFeatureList_setCurrentTimeIdx (uint32_t currentTimeIdx, dwFeatureListHandle_t obj)
 Sets the current time index of the feature-history circular buffer. More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_addEmptyFeature (uint32_t nFeatures, dwScalingFeatureListHandle_t obj)
 Insert nFeatures empty feature into the feature list. More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_applySizeFilter (float32_t maxWidth, float32_t maxHeight, dwScalingFeatureListHandle_t obj)
 Mark the features in the list as DW_FEATURE_STATUS_INVALID with size larger than (maxWidth, maxHeight) More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_compact (dwScalingFeatureListHandle_t list, const uint32_t *d_validIndexCount, const uint32_t *d_validIndexes, const uint32_t *d_invalidIndexCount, const uint32_t *d_invalidIndexes)
 Removes scaling features from the list. More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_getCUDAStream (cudaStream_t *stream, dwScalingFeatureListHandle_t obj)
 Gets the CUDA stream used by the scaling feature list. More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_getDataBasePointer (void **d_basePointer, size_t *size, dwScalingFeatureListHandle_t obj)
 Returns the start position of the data buffer that stores all of the scaling feature list information (in GPU memory). More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_getDataPointers (dwScalingFeatureListPointers *pointers, void *basePointer, dwScalingFeatureListHandle_t obj)
 Returns the pointers to the actual data of a scaling feature list given the base pointer. More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_initialize (dwScalingFeatureListHandle_t *obj, dwContextHandle_t context, cudaStream_t stream, const uint32_t maxFeatureCount, const dwTrivialDataType pxlType)
 Creates and initializes a scaling feature list. More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_release (dwScalingFeatureListHandle_t *obj)
 Releases the scaling feature list. More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_reset (dwScalingFeatureListHandle_t obj)
 Resets the scaling feature list. More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_selectValid (uint32_t *d_validIndexCount, uint32_t *d_validIndexes, uint32_t *d_invalidIndexCount, uint32_t *d_invalidIndexes, dwConstScalingFeatureListHandle_t obj)
 Creates a list of indexes of those scaling features with a status of detected or tracked, and list of indexes of those scaling features with a status of invalid. More...
 
DW_API_PUBLIC dwStatus dwScalingFeatureList_setCUDAStream (cudaStream_t stream, dwScalingFeatureListHandle_t obj)
 Sets the CUDA stream for CUDA related operations. More...
 

Data Structure Documentation

◆ dwFeatureListPointers

struct dwFeatureListPointers
Data Fields
uint32_t * ages Age of each feature.

1D array of size N.

uint32_t * featureCount Total number of feature points.

Single value.

dwVector2f * locationHistory Location history of feature points.

2D array of size N*H.

dwFeatureStatus * statuses Status of each feature.

1D array of size N.

Enumeration Type Documentation

◆ dwFeatureStatus

Defines the possible status of a feature.

Enumerator
DW_FEATURE_STATUS_INVALID 

A feature with this entry is garbage.

DW_FEATURE_STATUS_DETECTED 

The feature was just detected in the current frame.

DW_FEATURE_STATUS_TRACKED 

The feature was succesfully tracked in the current frame.

DW_FEATURE_STATUS_TYPE_COUNT 

Definition at line 88 of file Features.h.

Function Documentation

◆ dwFeatureList_compact()

DW_API_PUBLIC dwStatus dwFeatureList_compact ( dwFeatureListHandle_t  featureList,
const uint32_t *  d_validIndexCount,
const uint32_t *  d_validIndexes,
const uint32_t *  d_invalidIndexCount,
const uint32_t *  d_invalidIndexes 
)

Removes features from the list.

It doesn't work in place; instead, it copies the valid features onto a new list.

Parameters
[in,out]featureListSpecifies the list where the compact operation will be performed.
[in]d_validIndexCountA GPU pointer to the number of entries in the d_validIndexes array.
[in]d_validIndexesA GPU array that holds the indexes of the features that will be copied to the new list.
[in]d_invalidIndexCountA GPU pointer to the number of entries in the d_invalidIndexes array.
[in]d_invalidIndexesA GPU array that holds the indexes of the features that shouldn't be copied to the new list.
Returns
DW_INVALID_ARGUMENT if featureList, d_validIndexCount, d_validIndexes, d_invalidIndexCount, or d_invalidIndexes are NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_getCUDAStream()

DW_API_PUBLIC dwStatus dwFeatureList_getCUDAStream ( cudaStream_t *  stream,
dwFeatureListHandle_t  obj 
)

Gets the CUDA stream used by the feature list.

Parameters
[out]streamThe CUDA stream currently used.
[in]objA handle to the feature list module.
Returns
DW_INVALID_ARGUMENT if feature list handle or stream are NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_getCurrentTimeIdx()

DW_API_PUBLIC dwStatus dwFeatureList_getCurrentTimeIdx ( uint32_t *  currentTimeIdx,
dwFeatureListHandle_t  obj 
)

Returns the current time index of feature-history circular buffer.

Using this function one can find where the most recent measured position is:

dwVector2f currentLocation = locationHistory[currentTimeIdx * maxFeatureCount + featureIdx];
Parameters
[out]currentTimeIdxCurrent time index.
[in]objFeature list handle.
Returns
DW_INVALID_ARGUMENT if feature list handle is NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_getDataBasePointer()

DW_API_PUBLIC dwStatus dwFeatureList_getDataBasePointer ( void **  d_basePointer,
size_t *  size,
dwFeatureListHandle_t  obj 
)

Returns the start position of the data buffer that stores all of the feature list information (in GPU memory).

Use this base pointer to allocate a CPU buffer and copy the feature list into it.

Parameters
[out]sizeThe size of the feature list data structure.
[out]d_basePointerA pointer to a GPU pointer to the feature data.
[in]objSpecifies the feature list handle.
Returns
DW_INVALID_ARGUMENT if feature list handle, d_basePointer or size are NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_getDataPointers()

DW_API_PUBLIC dwStatus dwFeatureList_getDataPointers ( dwFeatureListPointers pointers,
void *  basePointer,
dwFeatureListHandle_t  obj 
)

Returns the pointers to the actual data of a feature list given the base pointer.

basePointer can be either CPU or GPU, and the resulting pointers will be in the same memory space.

Parameters
[out]pointersList of pointers into the data.
[in]basePointerStart of the data structure. Can be GPU or CPU pointer.
[in]objSpecifies the feature list handle.
Returns
DW_INVALID_ARGUMENT if feature list handle, pointers or basePointer are NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_getFeatureListSize()

DW_API_PUBLIC dwStatus dwFeatureList_getFeatureListSize ( uint32_t *  maxFeatureCount,
uint32_t *  historyCapacity,
dwFeatureListHandle_t  obj 
)

Returns the maximum feature count and history capacity of the feature list.

Parameters
[out]maxFeatureCountMaximum number of features can be stored in the list.
[out]historyCapacityCapacity of location history circular buffer.
[in]objFeature list handle.
Returns
DW_INVALID_ARGUMENT if feature list handle is NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_initialize()

DW_API_PUBLIC dwStatus dwFeatureList_initialize ( dwFeatureListHandle_t obj,
dwContextHandle_t  context,
cudaStream_t  stream,
const uint32_t  maxFeatureCount,
const uint32_t  historyCapacity,
const uint32_t  imageWidth,
uint32_t  imageHeight 
)

Creates and initializes a feature list.

The list allocates space for maxFeatureCount features and is initialized to zero features.

Parameters
[out]objA pointer to the feature list handle is returned here.
[in]contextSpecifies the handle to the context under which it is created.
[in]streamSpecifies the CUDA stream to use for list operations.
[in]maxFeatureCountSpecifies the maximum number of features that the list can have.
[in]historyCapacitySpecifies capacity of feature history circular buffer.
[in]imageWidthSpecifies the width of the source images.
[in]imageHeightSpecifies the height of the source images.
Returns
DW_INVALID_ARGUMENT if feature list handle or context are NULL or maxFeatureCount is 0.
DW_SUCCESS otherwise.

◆ dwFeatureList_proximityFilter()

DW_API_PUBLIC dwStatus dwFeatureList_proximityFilter ( dwFeatureListHandle_t  list)

Invalidates features that are too close to each other.

Parameters
[in]listSpecifies the list handle.
Returns
DW_INVALID_ARGUMENT if feature list handle is NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_release()

DW_API_PUBLIC dwStatus dwFeatureList_release ( dwFeatureListHandle_t obj)

Releases the feature list.

This method releases all resources associated with a feature list.

Note
This method renders the handle unusable.
Parameters
[in]objA pointer to the object handle to be released.
Returns
DW_INVALID_ARGUMENT if feature list handle is NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_reset()

DW_API_PUBLIC dwStatus dwFeatureList_reset ( dwFeatureListHandle_t  obj)

Resets the feature list.

Sets the feature count back to zero.

Parameters
[in]objSpecifies the feature list handle to reset.
Returns
DW_INVALID_ARGUMENT if feature list handle is NULL.
A specific CUDA error in case of an underlying cuda failure.
DW_SUCCESS otherwise.

◆ dwFeatureList_selectValid()

DW_API_PUBLIC dwStatus dwFeatureList_selectValid ( uint32_t *  d_validIndexCount,
uint32_t *  d_validIndexes,
uint32_t *  d_invalidIndexCount,
uint32_t *  d_invalidIndexes,
dwConstFeatureListHandle_t  obj 
)

Creates a list of indexes of those features with a status of detected or tracked, and list of indexes of those features with a status of invalid.

Parameters
[out]d_validIndexCountA GPU pointer to the number of entries in the d_validIndexes array.
[out]d_validIndexesA GPU array to hold the indexes of the features with a valid status. Must be at least of size featureCount.
[out]d_invalidIndexCountA GPU pointer to the number of entries in the d_invalidIndexes array.
[out]d_invalidIndexesA GPU array to hold the indexes of the features with a invalid status. Must be at least of size featureCount.
[in]objSpecifies the feature list handle.
Returns
DW_INVALID_ARGUMENT if feature list handle, d_indexCount or d_validIndexes are NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_setCUDAStream()

DW_API_PUBLIC dwStatus dwFeatureList_setCUDAStream ( cudaStream_t  stream,
dwFeatureListHandle_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 dwFeatureList_initialize.
[in]objA handle to the feature list module to set CUDA stream for.
Returns
DW_INVALID_ARGUMENT if feature list handle is NULL.
DW_SUCCESS otherwise.

◆ dwFeatureList_setCurrentTimeIdx()

DW_API_PUBLIC dwStatus dwFeatureList_setCurrentTimeIdx ( uint32_t  currentTimeIdx,
dwFeatureListHandle_t  obj 
)

Sets the current time index of the feature-history circular buffer.

When you call dwFeatureTracker_trackFeatures(), the current time index is decremented automatically. Use this function only when you want to manually change the current time index to provide your own feature list.

Parameters
[in]currentTimeIdxCurrent time index.
[in]objFeature list handle.
Returns
DW_INVALID_ARGUMENT if feature list handle is NULL.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_addEmptyFeature()

DW_API_PUBLIC dwStatus dwScalingFeatureList_addEmptyFeature ( uint32_t  nFeatures,
dwScalingFeatureListHandle_t  obj 
)

Insert nFeatures empty feature into the feature list.

Parameters
[in]nFeaturesNumber of features to be added
[in,out]objSpecifies the scaling feature list handle.
Returns
DW_INVALID_ARGUMENT if scaling feature list handle is NULL.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_applySizeFilter()

DW_API_PUBLIC dwStatus dwScalingFeatureList_applySizeFilter ( float32_t  maxWidth,
float32_t  maxHeight,
dwScalingFeatureListHandle_t  obj 
)

Mark the features in the list as DW_FEATURE_STATUS_INVALID with size larger than (maxWidth, maxHeight)

Parameters
[in]maxWidthIf width of the feature > maxWidth, it will be marked as DW_FEATURE_STATUS_INVALID
[in]maxHeightIf height of the feature > maxHeight, it will be marked as DW_FEATURE_STATUS_INVALID
[in,out]objSpecifies the scaling eature list handle.
Returns
DW_INVALID_ARGUMENT if scaling feature list handle is NULL.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_compact()

DW_API_PUBLIC dwStatus dwScalingFeatureList_compact ( dwScalingFeatureListHandle_t  list,
const uint32_t *  d_validIndexCount,
const uint32_t *  d_validIndexes,
const uint32_t *  d_invalidIndexCount,
const uint32_t *  d_invalidIndexes 
)

Removes scaling features from the list.

It doesn't work in place; instead, it copies the valid features onto a new list.

Parameters
[in,out]listSpecifies the list where the compact operation will be performed.
[in]d_validIndexCountA GPU pointer to the number of entries in the d_validIndexes array.
[in]d_validIndexesA GPU array that holds the indexes of the features that will be copied to the new list.
[in]d_invalidIndexCountA GPU pointer to the number of entries in the d_invalidIndexes array.
[in]d_invalidIndexesA GPU array that holds the indexes of the features that shouldn't be copied to the new list.
Returns
DW_INVALID_ARGUMENT if list, d_validIndexCount, d_validIndexes, d_invalidIndexCount, or d_invalidIndexes are NULL.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_getCUDAStream()

DW_API_PUBLIC dwStatus dwScalingFeatureList_getCUDAStream ( cudaStream_t *  stream,
dwScalingFeatureListHandle_t  obj 
)

Gets the CUDA stream used by the scaling feature list.

Parameters
[out]streamThe CUDA stream currently used.
[in]objA handle to the scaling feature list module.
Returns
DW_INVALID_ARGUMENT if scaling feature list handle or stream are NULL.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_getDataBasePointer()

DW_API_PUBLIC dwStatus dwScalingFeatureList_getDataBasePointer ( void **  d_basePointer,
size_t *  size,
dwScalingFeatureListHandle_t  obj 
)

Returns the start position of the data buffer that stores all of the scaling feature list information (in GPU memory).

Use this base pointer to allocate a CPU buffer and copy the scaling feature list into it.

Parameters
[out]sizeThe size of the scaling feature list data structure.
[out]d_basePointerA pointer to a GPU pointer to the scaling feature data.
[in]objSpecifies the scaling feature list handle.
Returns
DW_INVALID_ARGUMENT if scaling feature list handle, d_basePointer or size are NULL.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_getDataPointers()

DW_API_PUBLIC dwStatus dwScalingFeatureList_getDataPointers ( dwScalingFeatureListPointers pointers,
void *  basePointer,
dwScalingFeatureListHandle_t  obj 
)

Returns the pointers to the actual data of a scaling feature list given the base pointer.

basePointer can be either CPU or GPU, and the resulting pointers will be in the same memory space.

Parameters
[out]pointersList of pointers into the data.
[in]basePointerStart of the data structure. Can be GPU or CPU pointer.
[in]objSpecifies the scaling feature list handle.
Returns
DW_INVALID_ARGUMENT if scaling feature list handle, pointers or basePointer are NULL.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_initialize()

DW_API_PUBLIC dwStatus dwScalingFeatureList_initialize ( dwScalingFeatureListHandle_t obj,
dwContextHandle_t  context,
cudaStream_t  stream,
const uint32_t  maxFeatureCount,
const dwTrivialDataType  pxlType 
)

Creates and initializes a scaling feature list.

The list allocates space for maxFeatureCount features and is initialized to zero features.

Parameters
[out]objA pointer to the feature list handle is returned here.
[in]contextSpecifies the handle to the context under which it is created.
[in]streamSpecifies the CUDA stream to use for list operations.
[in]maxFeatureCountSpecifies the maximum number of features that the list can have.
[in]pxlType
Returns
DW_INVALID_ARGUMENT if scaling feature list handle or context are NULL or maxFeatureCount is 0.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_release()

DW_API_PUBLIC dwStatus dwScalingFeatureList_release ( dwScalingFeatureListHandle_t obj)

Releases the scaling feature list.

This method releases all resources associated with a scaling feature list.

Note
This method renders the handle unusable.
Parameters
[in]objA pointer to the object handle to be released.
Returns
DW_INVALID_ARGUMENT if scaling feature list handle is NULL.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_reset()

DW_API_PUBLIC dwStatus dwScalingFeatureList_reset ( dwScalingFeatureListHandle_t  obj)

Resets the scaling feature list.

Sets the feature count back to zero.

Parameters
[in]objSpecifies the scaling feature list handle to reset.
Returns
DW_INVALID_ARGUMENT if scaling feature list handle is NULL.
A specific CUDA error in case of an underlying cuda failure.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_selectValid()

DW_API_PUBLIC dwStatus dwScalingFeatureList_selectValid ( uint32_t *  d_validIndexCount,
uint32_t *  d_validIndexes,
uint32_t *  d_invalidIndexCount,
uint32_t *  d_invalidIndexes,
dwConstScalingFeatureListHandle_t  obj 
)

Creates a list of indexes of those scaling features with a status of detected or tracked, and list of indexes of those scaling features with a status of invalid.

Parameters
[out]d_validIndexCountA GPU pointer to the number of entries in the d_validIndexes array.
[out]d_validIndexesA GPU array to hold the indexes of the features with a valid status. Must be at least of size featureCount.
[out]d_invalidIndexCountA GPU pointer to the number of entries in the d_invalidIndexes array.
[out]d_invalidIndexesA GPU array to hold the indexes of the features with a invalid status. Must be at least of size featureCount.
[in]objSpecifies the scaling feature list handle.
Returns
DW_INVALID_ARGUMENT if scaling feature list handle, d_indexCount or d_validIndexes are NULL.
DW_SUCCESS otherwise.

◆ dwScalingFeatureList_setCUDAStream()

DW_API_PUBLIC dwStatus dwScalingFeatureList_setCUDAStream ( cudaStream_t  stream,
dwScalingFeatureListHandle_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 dwScalingFeatureList_initialize.
[in]objA handle to the scaling feature list module to set CUDA stream for.
Returns
DW_INVALID_ARGUMENT if scaling feature list handle is NULL.
DW_SUCCESS otherwise.