Skip to content

Latest commit

 

History

History
257 lines (201 loc) · 11.4 KB

api-preproc.md

File metadata and controls

257 lines (201 loc) · 11.4 KB
Raw

Preprocessor API Reference

The DeepStream Services Library (DSL) provides services for NVIDIA's Gst-nvdsprerocessor plugin. From the NVIDIA DeepStream Developer's Guide,

"The Gst-nvdspreprocess plugin is a customizable plugin which provides a custom library interface for preprocessing on input streams. Each stream can have its own preprocessing requirements. (e.g., per stream ROIs - Region of Interests processing)." Read more....

Note:​ The Gst-nvdsprerocessor plugin released with DeepStream 6.0 is in an "alpha" state and only the Primary GST Inference component can process input-tensor-meta from the Preprocessor.

IMPORTANT! Raw tensor from the scaled & converted ROIs are passed to the downstream Primary GST Inference Engine (PGIE) via user metadata. You must enable the PGIE's input-tensor-meta setting by calling dsl_infer_gie_tensor_meta_settings_set when adding a Preprocessor to a Pipeline. Refer to the Inference API Reference

Preprocessor Construction and Destruction

The constructor dsl_preproc_new is used to create a Preprocessor with input parameters for the config file and enabled setting. Once created, the Preprocessor's configuration file and enabled setting can be updated. Preprocessors are deleted by calling dsl_component_delete, dsl_component_delete_many, or dsl_component_delete_all

Preprocessor Configuration

Preprocessor components require a configuration file when constructed. Once created, clients can query the Preprocessor for the Config File in-use by calling dsl_preproc_config_file_get or change the Preprocessor's configuration by calling dsl_preproc_config_file_set.

Adding and Removing

A single Preprocessor can be added to Pipeline trunk or individual Branch. A Preprocessor is added to a Pipeline by calling dsl_pipeline_component_add or dsl_pipeline_component_add_many and removed with dsl_pipeline_component_remove, dsl_pipeline_component_remove_many, or dsl_pipeline_component_remove_all.

A similar set of Services are used when adding/removing a Preprocess to/from a branch: dsl_branch_component_add, dsl_branch_component_add_many, dsl_branch_component_remove, dsl_branch_component_remove_many, and dsl_branch_component_remove_all.

Once added to a Pipeline or Branch, a Preprocessor must be removed before it can be used with another.

Adding/Removing Pad-Probe-handlers

Multiple sink and/or source Pad-Probe Handlers can be added to a Preprocessor by calling dsl_preproc_pph_add and removed with dsl_preproc_pph_remove.

Preprocessor API

Constructors:

Methods:

Return Values

The following return codes are used by the On-Screen Display API

#define DSL_RESULT_PREPROC_RESULT                                   0x00B00000
#define DSL_RESULT_PREPROC_NAME_NOT_UNIQUE                          0x00B00001
#define DSL_RESULT_PREPROC_NAME_NOT_FOUND                           0x00B00002
#define DSL_RESULT_PREPROC_CONFIG_FILE_NOT_FOUND                    0x00060003
#define DSL_RESULT_PREPROC_THREW_EXCEPTION                          0x00B00004
#define DSL_RESULT_PREPROC_IN_USE                                   0x00B00005
#define DSL_RESULT_PREPROC_SET_FAILED                               0x00B00006
#define DSL_RESULT_PREPROC_IS_NOT_PREPROC                           0x00B00007
#define DSL_RESULT_PREPROC_HANDLER_ADD_FAILED                       0x00B00008
#define DSL_RESULT_PREPROC_HANDLER_REMOVE_FAILED                    0x00B00009

Constructors

dsl_preproc_new

DslReturnType dsl_preproc_new(const wchar_t* name, const wchar_t* config_file);

The constructor creates a uniquely named Preprocessor. Construction will fail if the name is currently in use. The Preprocessor is enabled by default. It can be disabled by calling dsl_preproc_enabled_set.

Parameters

  • name - [in] unique name for the Preprocessor to create.
  • config_file - [in] absolute or relative path to the Preprocessor configuration file to use.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure

Python Example

retval = dsl_preproc_new('my-preprocessor', './my-config-file.txt')

Methods

dsl_preproc_config_file_get

DslReturnType dsl_preproc_config_file_get(const wchar_t* name,
    const wchar_t** config_file);

This service returns the current configuration file in use by a named Preprocessor.

Parameters

  • name - [in] unique name of the Preprocessor to query.
  • config_file - [out] absolute or relative path to the configuration file in use.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure

Python Example

retval, config_file = dsl_preproc_config_file_get('my-preprocessor')

dsl_preproc_config_file_set

DslReturnType dsl_preproc_config_file_set(const wchar_t* name,
    const wchar_t* config_file);

This service sets the current configuration file for the named Preprocessor to use.

Parameters

  • name - [in] unique name of the Preprocessor to update.
  • config_file - [in] absolute or relative path to the new Preprocessor configuration file to use.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure

Python Example

retval = dsl_preproc_config_file_set('my-on-screen-display', './my-new-config-file.txt)

dsl_preproc_enabled_get

DslReturnType dsl_preproc_enabled_get(const wchar_t* name,
    boolean* enabled);

This service returns the current enabled setting for the named Preprocessor.

Parameters

  • name - [in] unique name of the Preprocessor to query.
  • enable - [out] true if preprocessing in enabled, false otherwise.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure

Python Example

retval, enabled = dsl_preproc_enabled_get('my-preprocessor')

dsl_preproc_enabled_set

DslReturnType dsl_preproc_enabled_set(const wchar_t* name,
    boolean enabled);

This service sets the enabled setting for the named Preprocessor.

Parameters

  • name - [in] unique name of the Preprocessor to update.
  • enabled - [in] set to True to enabled preprocessing, False to disable.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure

Python Example

retval = dsl_preproc_enabled_set('my-preprocessor', False)

dsl_preproc_unique_id_get

DslReturnType dsl_preproc_unique_id_get(const wchar_t* name,
    uint* id);

This service the unique Id assigned to the named Preprocessor when created. The Id is used to identify metadata generated by the Preprocessor. Id's start at 0 and are incremented with each new Preprocessor created. Id's will be reused if the Preprocessor is deleted.

Parameters

  • name - [in] unique name of the Preprocessor to query.
  • id - [out] the unique id assigned to the Preprocessor when created.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure

Python Example

retval, unique_id = dsl_preproc_unique_id_get('my-preprocessor')

dsl_preproc_pph_add

DslReturnType dsl_preproc_pph_add(const wchar_t* name, const wchar_t* handler, uint pad);

This service adds a Pad Probe Handler to either the Sink or Source pad of the named Preprocessor.

Parameters

  • name - [in] unique name of the Preprocessor to update.
  • handler - [in] unique name of Pad Probe Handler to add
  • pad - [in] to which of the two pads to add the handler: DSL_PAD_SIK or DSL_PAD SRC

Returns

  • DSL_RESULT_SUCCESS on successful add. One of the Return Values defined above on failure.

Python Example

retval = dsl_preproc_pph_add('my-preprocessor', 'my-pph-handler', `DSL_PAD_SINK`)

dsl_preproc_pph_remove

DslReturnType dsl_preproc_pph_remove(const wchar_t* name, const wchar_t* handler, uint pad);

This service removes a Pad Probe Handler from either the Sink or Source pad of the named Preprocess. The service will fail if the named handler is not owned by the Preprocessor.

Parameters

  • name - [in] unique name of the Preprocessor to update.
  • handler - [in] unique name of Pad Probe Handler to remove
  • pad - [in] to which of the two pads to remove the handler from: DSL_PAD_SIK or DSL_PAD SRC

Returns

  • DSL_RESULT_SUCCESS on successful remove. One of the Return Values defined above on failure.

Python Example

retval = dsl_preproc_pph_remove('my-preprocessor', 'my-pph-handler', `DSL_PAD_SINK`)

API Reference