Detailed Description

Defines the feature array used by detector and tracker.

Note: SW Release Applicability: These APIs are available in both NVIDIA DriveWorks and NVIDIA DRIVE Software releases.

Data Structures
struct	dwFeatureArray

struct	dwFeatureHistoryArray
	Holds pointers to the data exposed by a feature2d list. More...

Enumerations
enum	dwFeature2DStatus { DW_FEATURE2D_STATUS_INVALID = 0, DW_FEATURE2D_STATUS_DETECTED, DW_FEATURE2D_STATUS_TRACKED, DW_FEATURE2D_STATUS_TYPE_COUNT }
	Defines the possible status of a feature. More...

Functions
DW_API_PUBLIC dwStatus	dwFeature_mergeNewToOldMap (uint32_t d_newToOldMapC2A, const uint32_t d_newToOldMapC2B, const uint32_t d_newToOldMapB2A, const uint32_t d_newToOldMapCount, const uint32_t maxFeatureCount, cudaStream_t stream)
	Merge `newToOldMap` from 2 inputs. More...

DW_API_PUBLIC dwStatus	dwFeatureArray_copyAsync (dwFeatureArray dstFeatures, const dwFeatureArray srcFeatures, cudaStream_t stream)
	Deep copy all contents from `srcFeatures` to `dstFeatures` More...

DW_API_PUBLIC dwStatus	dwFeatureArray_create (dwFeatureArray *featureArray, const uint32_t maxFeatureCount, const dwMemoryType memoryType, dwContextHandle_t context)
	Creates and initializes a feature array. More...

DW_API_PUBLIC dwStatus	dwFeatureArray_destroy (dwFeatureArray featureArray)
	Destroys the featureArray and frees any memory created by dwFeatureArray_create(). More...

DW_API_PUBLIC dwStatus	dwFeatureArray_reset (dwFeatureArray *featureArray)
	Resets the feature array. More...

DW_API_PUBLIC dwStatus	dwFeatureHistoryArray_copyAsync (dwFeatureHistoryArray dstFeatureHistory, const dwFeatureHistoryArray srcFeatureHistory, cudaStream_t stream)
	Deep copy all contents from `srcFeatureHistory` to `dstFeatureHistory` More...

DW_API_PUBLIC dwStatus	dwFeatureHistoryArray_create (dwFeatureHistoryArray *featureHistoryArray, const uint32_t maxFeatureCount, const uint32_t maxHistoryCapacity, const dwMemoryType memoryType, dwContextHandle_t context)
	Creates and initializes a feature history array. More...

DW_API_PUBLIC dwStatus	dwFeatureHistoryArray_destroy (dwFeatureHistoryArray featureHistoryArray)
	Destroys the featureHistoryArray and frees any memory created by dwFeatureHistoryArray_create(). More...

DW_API_PUBLIC dwStatus	dwFeatureHistoryArray_get (dwFeatureArray featureArray, const uint32_t historyIdx, dwFeatureHistoryArray featureHistoryArray)
	Get the feature snapshot(arraySize = maxFeatureCount) historyIdx-th frame earlier. More...

DW_API_PUBLIC dwStatus	dwFeatureHistoryArray_getCurrent (dwFeatureArray featureArray, dwFeatureHistoryArray featureHistoryArray)
	Get the latest feature snapshot(arraySize = maxFeatureCount) from history. More...

DW_API_PUBLIC dwStatus	dwFeatureHistoryArray_getPrevious (dwFeatureArray featureArray, dwFeatureHistoryArray featureHistoryArray)
	Get the feature snapshot(arraySize = maxFeatureCount) 1 frame previous to current time. More...

DW_API_PUBLIC dwStatus	dwFeatureHistoryArray_reset (dwFeatureHistoryArray *featureHistoryArray)
	Resets the feature history array. More...

Data Structure Documentation

◆ dwFeatureArray

struct dwFeatureArray

Data Fields
uint32_t *	ages	Age of each feature. 1D array of size maxFeatures.
uint32_t *	featureCount	Total number of feature points. Single value.
uint32_t *	ids	Id of each feature. 1D array of size maxFeatures.
dwVector2f *	locations	Location of feature points. 2D array of size maxFeatures
uint32_t	maxFeatures	Max number of features.
dwMemoryType	memoryType	Where feature array is located, GPU, CPU or pinned memory.
uint32_t *	newToOldMap	New to old index map, 1D array of size maxFeatures. See more details in `dwFeature2DTracker_trackFeatures`.
float32_t *	scales	Scale change for each feauture. 1D array of size maxFeatures.
dwFeature2DStatus *	statuses	Status of each feature. 1D array of size maxFeatures.
uint32_t	timeIdx	Time index, 0 means latest, N means N frames earlier to latest.

◆ dwFeatureHistoryArray

struct dwFeatureHistoryArray

Data Fields
uint32_t *	ages	Age of each feature. 1D array of size maxFeatures.
size_t	bytes	Bytes of raw data.
uint32_t	currentTimeIdx	Index that points to the latest feature records.
uint8_t *	data	Pointer to the raw data address.
uint32_t *	featureCount	Total number of feature points. Single value.
uint32_t *	ids	Id of each feature. 1D array of size maxFeatures.
dwVector2f *	locationHistory	Location history of feature points. 2D array of size maxFeatures*maxHistory.
uint32_t	maxFeatures	Max number of features in one timeIdx.
uint32_t	maxHistory	Max feature history size.
dwMemoryType	memoryType	Where feature array is located, GPU, CPU or pinned memory.
uint32_t *	newToOldMap	New to old index map, 1D array of size maxFeatures. See more details in `dwFeature2DTracker_trackFeatures`.
float32_t *	scales	Scale change for each feauture. 1D array of size maxFeatures.
dwFeature2DStatus *	statuses	Status of each feature. 1D array of size maxFeatures.

Enumeration Type Documentation

◆ dwFeature2DStatus

enum dwFeature2DStatus

Defines the possible status of a feature.

Enumerator
DW_FEATURE2D_STATUS_INVALID	A feature with this entry is garbage.
DW_FEATURE2D_STATUS_DETECTED	The feature was just detected in the current frame.
DW_FEATURE2D_STATUS_TRACKED	The feature was successfully tracked in the current frame.
DW_FEATURE2D_STATUS_TYPE_COUNT

Definition at line 64 of file FeatureList.h.

Function Documentation

◆ dwFeature_mergeNewToOldMap()

DW_API_PUBLIC dwStatus dwFeature_mergeNewToOldMap	(	uint32_t *	d_newToOldMapC2A,
		const uint32_t *	d_newToOldMapC2B,
		const uint32_t *	d_newToOldMapB2A,
		const uint32_t *	d_newToOldMapCount,
		const uint32_t	maxFeatureCount,
		cudaStream_t	stream
	)

Merge newToOldMap from 2 inputs.

i.e. There're 3 working stages: A->B->C, newToOldMapC2B gives the mapping of C->B, while newToOldMapB2A gives the mapping of B->A. The final C->A mapping will be computed and output to newToOldMapC2A

Parameters

[out]	d_newToOldMapC2A	A GPU pointer to the output merged newToOldMap
[in]	d_newToOldMapC2B	A GPU pointer to newToOldMap from stage C->B
[in]	d_newToOldMapB2A	A GPU pointer to newToOldMap from stage B->A
[in]	d_newToOldMapCount	A GPU pointer to valid number of entries in `newToOldMapC2B`
[in]	maxFeatureCount	max number of features for `newToOldMapC2A`, `newToOldMapC2B` and `newToOldMapB2A`
[in]	stream	Working cuda stream

Returns: DW_INVALID_ARGUMENT if any of the input argument is NULL.
DW_SUCCESS otherwise.

◆ dwFeatureArray_copyAsync()

DW_API_PUBLIC dwStatus dwFeatureArray_copyAsync	(	dwFeatureArray *	dstFeatures,
		const dwFeatureArray *	srcFeatures,
		cudaStream_t	stream
	)

Deep copy all contents from srcFeatures to dstFeatures

Parameters

[out]	dstFeatures	`dwFeatureArray` to copy to
[in]	srcFeatures	`dwFeatureArray` to copy from
[in]	stream	Working cuda stream

Returns: DW_INVALID_ARGUMENT if dstFeatures or srcFeatures is NULL.
if dstFeatures.maxFeatures != srcFeatures.maxFeatures.
A specific CUDA error in case of an underlying cuda failure.
DW_SUCCESS otherwise.

Note: If the copy function is run on a non-zero stream, it's asynchronous calling, need do stream sync or event sync to make sure the copy is done.

◆ dwFeatureArray_create()

DW_API_PUBLIC dwStatus dwFeatureArray_create	(	dwFeatureArray *	featureArray,
		const uint32_t	maxFeatureCount,
		const dwMemoryType	memoryType,
		dwContextHandle_t	context
	)

Creates and initializes a feature array.

Parameters

[out]	featureArray	pointer to the dwFeatureArray is returned here.
[in]	maxFeatureCount	maximum number of features that the feature array can have.
[in]	memoryType	DW_FEATURE2D_MEMORY_TYPE_CUDA for CUDA array, DW_FEATURE2D_MEMORY_TYPE_CPU for CPU array, DW_FEATURE2D_MEMORY_TYPE_PINNED for pinned memory
[in]	context	handle to the context under which it is created.

Returns: DW_INVALID_ARGUMENT if feature arry or context are NULL.
if maxFeatureCount is 0.
if processType is not DW_PROCESSOR_TYPE_CPU or DW_PROCESSOR_TYPE_GPU.
DW_SUCCESS otherwise.

◆ dwFeatureArray_destroy()

DW_API_PUBLIC dwStatus dwFeatureArray_destroy ( dwFeatureArray featureArray )

Destroys the featureArray and frees any memory created by dwFeatureArray_create().

Parameters

[in] featureArray feature array to be destroyed.

Returns: DW_INVALID_ARGUMENT if featureArray contains invalid pointers.
DW_SUCCESS otherwise.

Note: dwFeatureArray got by dwFeatureHistoryArray_get*() API doesn't need to be destroyed by this API, all resource will be freed when calling dwFeatureHistoryArray_destroy().

◆ dwFeatureArray_reset()

DW_API_PUBLIC dwStatus dwFeatureArray_reset ( dwFeatureArray * featureArray )

Resets the feature array.

Sets the feature count back to zero.

Parameters

[in] featureArray feature array to be reset.

Returns: DW_INVALID_ARGUMENT if featureArray.featureCount is NULL.
DW_SUCCESS otherwise.

◆ dwFeatureHistoryArray_copyAsync()

DW_API_PUBLIC dwStatus dwFeatureHistoryArray_copyAsync	(	dwFeatureHistoryArray *	dstFeatureHistory,
		const dwFeatureHistoryArray *	srcFeatureHistory,
		cudaStream_t	stream
	)

Deep copy all contents from srcFeatureHistory to dstFeatureHistory

Parameters

[out]	dstFeatureHistory	`dwFeatureHistoryArray` to copy to
[in]	srcFeatureHistory	`dwFeatureHistoryArray` to copy from
[in]	stream	Working cuda stream

Returns: DW_INVALID_ARGUMENT if dstFeatureHistory or srcFeatureHistory is NULL.
if dstFeatureHistory.bytes != srcFeaturesHistory.bytes.
A specific CUDA error in case of an underlying cuda failure.
DW_SUCCESS otherwise.

Note: If the copy function is run on a non-zero stream, it's asynchronous calling, need do stream sync or event sync to make sure the copy is done.

◆ dwFeatureHistoryArray_create()

DW_API_PUBLIC dwStatus dwFeatureHistoryArray_create	(	dwFeatureHistoryArray *	featureHistoryArray,
		const uint32_t	maxFeatureCount,
		const uint32_t	maxHistoryCapacity,
		const dwMemoryType	memoryType,
		dwContextHandle_t	context
	)

Creates and initializes a feature history array.

Parameters

[out]	featureHistoryArray	pointer to the dwFeatureHistoryArray is returned here.
[in]	maxFeatureCount	maximum number of features that each time slice can have.
[in]	maxHistoryCapacity	maximum length of history in feature history array. There'll be maxFeatureCount*maxHistoryCapacity features totally.
[in]	memoryType	DW_FEATURE2D_MEMORY_TYPE_CUDA for CUDA array, DW_FEATURE2D_MEMORY_TYPE_CPU for CPU array, DW_FEATURE2D_MEMORY_TYPE_PINNED for pinned memory
[in]	context	handle to the context under which it is created.

Returns: DW_INVALID_ARGUMENT if feature arry or context are NULL.
if maxFeatureCount or maxHistoryCapacity is 0.
if processType is not DW_PROCESSOR_TYPE_CPU or DW_PROCESSOR_TYPE_GPU.
DW_SUCCESS otherwise.

◆ dwFeatureHistoryArray_destroy()

DW_API_PUBLIC dwStatus dwFeatureHistoryArray_destroy ( dwFeatureHistoryArray featureHistoryArray )

Destroys the featureHistoryArray and frees any memory created by dwFeatureHistoryArray_create().

Parameters

[in] featureHistoryArray feature history array to be destroyed.

Returns: DW_INVALID_ARGUMENT if featureHistoryArray contains invalid pointers.
DW_SUCCESS otherwise.

◆ dwFeatureHistoryArray_get()

DW_API_PUBLIC dwStatus dwFeatureHistoryArray_get	(	dwFeatureArray *	featureArray,
		const uint32_t	historyIdx,
		dwFeatureHistoryArray *	featureHistoryArray
	)

Get the feature snapshot(arraySize = maxFeatureCount) historyIdx-th frame earlier.

For N valid features in current time T, this API returns the snapshot of those N features in T - historyIdx. For a given feature F, ages(F) <= historyIdx means feature F is invalid in T - historyIdx.

Parameters

[out]	featureArray	Snapshot of the timeIdx that is historyIdx frame previous to current in feature history.
[in]	historyIdx	Time index that need to be backtraced.
[in]	featureHistoryArray	Complete feature history.

Returns: DW_INVALID_ARGUMENT if featureArray or featureHistoryArray is NULL
DW_SUCCESS otherwise

Note: featureArray got by this API DOES NOT need to be freed by dwFeatureArray_destroy().

◆ dwFeatureHistoryArray_getCurrent()

DW_API_PUBLIC dwStatus dwFeatureHistoryArray_getCurrent	(	dwFeatureArray *	featureArray,
		dwFeatureHistoryArray *	featureHistoryArray
	)

Get the latest feature snapshot(arraySize = maxFeatureCount) from history.

Parameters

[out]	featureArray	Snapshot of latest time in feature history.
[in]	featureHistoryArray	Complete feature history.

Returns: DW_INVALID_ARGUMENT if featureArray or featureHistoryArray is NULL.
DW_SUCCESS otherwise.

Note: featureArray got by this API DOES NOT need to be freed by dwFeatureArray_destroy().

◆ dwFeatureHistoryArray_getPrevious()

DW_API_PUBLIC dwStatus dwFeatureHistoryArray_getPrevious	(	dwFeatureArray *	featureArray,
		dwFeatureHistoryArray *	featureHistoryArray
	)

Get the feature snapshot(arraySize = maxFeatureCount) 1 frame previous to current time.

For N valid features in current time T, this API returns the snapshot of those N features in T - 1. For a given feature F, ages(F) <= 1 means feature F is invalid in T - 1.

Parameters

[out]	featureArray	Snapshot of the timeIdx that is 1 frame previous to current in feature history.
[in]	featureHistoryArray	Complete feature history.

Returns: DW_INVALID_ARGUMENT if featureArray or featureHistoryArray is NULL.
DW_SUCCESS otherwise.

Note: featureArray got by this API DOES NOT need to be freed by dwFeatureArray_destroy()

◆ dwFeatureHistoryArray_reset()

DW_API_PUBLIC dwStatus dwFeatureHistoryArray_reset ( dwFeatureHistoryArray * featureHistoryArray )

Resets the feature history array.

Sets the feature count back to zero.

Parameters

[in] featureHistoryArray feature history array to be reset.

Returns: DW_INVALID_ARGUMENT if featureHistoryArray.featureCount is NULL.
DW_SUCCESS otherwise.

Detailed Description

Data Structures

Enumerations

Functions

Data Structure Documentation

◆ dwFeatureArray

◆ dwFeatureHistoryArray

Enumeration Type Documentation

◆ dwFeature2DStatus

Function Documentation

◆ dwFeature_mergeNewToOldMap()

◆ dwFeatureArray_copyAsync()

◆ dwFeatureArray_create()

◆ dwFeatureArray_destroy()

◆ dwFeatureArray_reset()

◆ dwFeatureHistoryArray_copyAsync()

◆ dwFeatureHistoryArray_create()

◆ dwFeatureHistoryArray_destroy()

◆ dwFeatureHistoryArray_get()

◆ dwFeatureHistoryArray_getCurrent()

◆ dwFeatureHistoryArray_getPrevious()

◆ dwFeatureHistoryArray_reset()