Skip to content

Latest commit

 

History

History
528 lines (410 loc) · 19.7 KB

api-osd.md

File metadata and controls

528 lines (410 loc) · 19.7 KB
Raw

On-Screen Display API Reference

The On-Screen Display (OSD) component provides visualization of object detection, classification, and tracking. OSDs display bounding boxes and labels for objects detected in the video stream. Bounding boxes and labels are defined using meta-data added to each frame by the Inference and Tracker components. All RGBA Display Types added upstream from the OSD will be displayed as well.

As with all components, OSDs must be uniquely named from all other components created.

OSD Construction and Destruction

The constructor dsl_osd_new is used to create an OSD with boolean inputs for enabling display of text, clock, bounding boxes, and segmentation mask. Once created, the OSD's clock parameters -- fonts, color and offsets -- can be modified from their default values. OSDs are deleted by calling dsl_component_delete, dsl_component_delete_many, or dsl_component_delete_all

Adding and Removing

A single OSD can be added to Pipeline trunk or individual branch. An OSD 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 an OSD 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, an OSD must be removed before it can be used with another.

On-Screen API

Constructors:

Methods:

Return Values

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

#define DSL_RESULT_OSD_NAME_NOT_UNIQUE                              0x00050001
#define DSL_RESULT_OSD_NAME_NOT_FOUND                               0x00050002
#define DSL_RESULT_OSD_NAME_BAD_FORMAT                              0x00050003
#define DSL_RESULT_OSD_THREW_EXCEPTION                              0x00050004
#define DSL_RESULT_OSD_MAX_DIMENSIONS_INVALID                       0x00050005
#define DSL_RESULT_OSD_IS_IN_USE                                    0x00050006
#define DSL_RESULT_OSD_SET_FAILED                                   0x00050007
#define DSL_RESULT_OSD_HANDLER_ADD_FAILED                           0x00050008
#define DSL_RESULT_OSD_HANDLER_REMOVE_FAILED                        0x00050009
#define DSL_RESULT_OSD_PAD_TYPE_INVALID                             0x0005000A
#define DSL_RESULT_OSD_COMPONENT_IS_NOT_OSD                         0x0005000B
#define DSL_RESULT_OSD_COLOR_PARAM_INVALID                          0x0005000C

Symbolic Constants

OSD process mode constants for CPU and GPU

  • CPU: Jetson & dGPU
  • GPU: dGPU only
  • HW: Jetson only
#define DSL_OSD_PROCESS_MODE_CPU                                    0
#define DSL_OSD_PROCESS_MODE_GPU                                    1
#define DSL_OSD_PROCESS_MODE_HW                                     2

Default Values

The following default property values are used by the On-Screen Display API These values are used to override the nvdsosd plugin defaults.

#define DSL_DEFAULT_OSD_PROCESS_MODE                                DSL_OSD_PROCESS_MODE_CPU
#define DSL_DEFAULT_OSD_CLOCK_FONT_TYPE                             "Serif"
#define DSL_DEFAULT_OSD_CLOCK_FONT_SIZE                             12
#define DSL_DEFAULT_OSD_CLOCK_OFFSET_X                              20
#define DSL_DEFAULT_OSD_CLOCK_OFFSET_Y                              20
#define DSL_DEFAULT_OSD_CLOCK_COLOR                                 {1.0,0.0,0.0,1.0}

Constructors

dsl_osd_new

DslReturnType dsl_osd_new(const wchar_t* name,
    boolean text_enabled, boolean clock_enabled,
    boolean bbox_enabled, boolean mask_enabled);

The constructor creates a uniquely named On-Screen Display. Construction will fail if the name is currently in use.

Parameters

  • name - [in] unique name for the On-Screen Display to create.
  • text_enable - [in] set to true to enable object text display, false otherwise.
  • clock_enable - [in] set to true to enable clock display, false otherwise.
  • bbox_enable - [in] set to true to enable bounding box display, false otherwise.
  • mask_enable - [in] set to true to enable segmentation mask display, false otherwise.

Returns

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

Python Example

retval = dsl_osd_new('my-on-screen-display', True, True, True, False)

Methods

dsl_osd_text_enabled_get

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

This service returns the current text display enabled setting for the named On-Screen Display.

Parameters

  • name - [in] unique name of the On-Screen Display to query.
  • enabled - [out] true if text display is currently enabled, false otherwise.

Returns

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

Python Example

retval, enabled = dsl_osd_text_enabled_get('my-on-screen-display')

dsl_osd_text_enabled_set

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

This service sets the current text display enabled setting for the named On-Screen Display.

IMPORTANT! this service can be called at runtime while the Pipeline is playing.

Parameters

  • name - [in] unique name of the On-Screen Display to update.
  • enable - [in] set to true to enable text display, false otherwise.

Returns

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

Python Example

retval = dsl_osd_text_enabled_set('my-on-screen-display', False)

dsl_osd_clock_enabled_get

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

This service returns the current clock display enabled setting for the named On-Screen Display.

Parameters

  • name - [in] unique name of the On-Screen Display to query.
  • enabled - [out] true if the On-Screen clock is currently enabled, false otherwise.

Returns

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

Python Example

retval, enabled = dsl_osd_clock_enabled_get('my-on-screen-display')

dsl_osd_clock_enabled_set

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

This service sets the current clock display enabled setting for the named On-Screen Display.

IMPORTANT! this service can be called at runtime while the Pipeline is playing.

Parameters

  • name - [in] unique name of the On-Screen Display to update.
  • enabled - [in] set to true to enable the On-Screen clock, false otherwise.

Returns

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

Python Example

retval = dsl_osd_clock_enabled_set('my-on-screen-display', False)

dsl_osd_clock_offsets_get

DslReturnType dsl_osd_clock_offsets_get(const wchar_t* name, uint* x_offset, uint* y_offset);

This service gets the current clock X and Y offsets for the named On-Screen Display. The offsets start from the upper left corner of the frame.

Parameters

  • name - [in] unique name of the On-Screen Display to query.
  • x_offset - [out] On-Screen clock offset in the X direction.
  • y_offset - [out] On-Screen clock offset in the Y direction.

Returns

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

Python Example

retval, x_offset, y_offset = dsl_osd_clock_offsets_get('my-on-screen-display')

dsl_osd_clock_offsets_set

DslReturnType dsl_osd_clock_offsets_set(const wchar_t* name, uint offsetX, uint offsetY);

This service sets the current clock X and Y offsets for the named On-Screen Display. The offsets start from the upper left corner of the frame.

Parameters

  • name - [in] unique name of the On-Screen Display to update.
  • x_offset - [in] On-Screen clock offset in the X direction.
  • y_offset - [in] On-Screen clock offset in the Y direction.

Returns

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

Python Example

retval, x_offset, y_offset = dsl_osd_clock_offsets_get('my-on-screen-display')

dsl_osd_clock_font_get

DslReturnType dsl_osd_clock_font_get(const wchar_t* name, const wchar_t** font, uint size);

This service gets the current clock font name and size for the named On-Screen Display.

Parameters

  • name - [in] unique name of the On-Screen Display to query.
  • font - [out] Name of the clock font type currently in use.
  • size - [out] Size of the On-Screen clock.

Returns

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

Python Example

retval, font, size = dsl_osd_clock_font_get('my-on-screen-display')

dsl_osd_clock_font_set

DslReturnType dsl_osd_clock_font_set(const wchar_t* name, const wchar_t* font, uint size);

This service sets the current clock font type and size for the named On-Screen Display

Parameters

  • name - [in] unique name of the On-Screen Display to update.
  • font - [in] Name of the clock font type currently in use.
  • size - [in] Size of the On-Screen clock.

Returns

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

Python Example

retval = dsl_osd_clock_font_set('my-on-screen-display', 'arial', 12)

dsl_osd_clock_color_get

DslReturnType dsl_osd_clock_color_get(const wchar_t* name,
    double* red, double* green, double* blue, double alpha);

This service gets the current clock color for the named On-Screen Display. The color is represented in RGBA format, each with weights between 0.0 and 1.0.

Parameters

  • name - [in] unique name of the On-Screen Display to query.
  • red - [out] red color weight [0.0...1.0].
  • green - [out] green color weight [0.0...1.0].
  • blue - [out] blue color weight [0.0...1.0].
  • alpha - [out] alpha color weight [0.0...1.0].

Returns

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

Python Example

retval, red, green, blue, alpha = dsl_osd_clock_color_get('my-on-screen-display').

dsl_osd_clock_color_set

DslReturnType dsl_osd_clock_color_set(const wchar_t* name, double red, uint double, uint blue);

This service gets the current clock color for the named On-Screen Display. The color is specified in RGBA format.

Parameters

  • name - [in] unique name of the On-Screen Display to update.
  • red - [in] red color weight [0.0...1.0].
  • green - [in] green color weight [0.0...1.0].
  • blue - [in] blue color weight [0.0...1.0].
  • alpha - [in] alpha color weight [0.0...1.0].

Returns

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

Python Example

retval = dsl_osd_clock_color_set('my-on-screen-display', 0.6, 0.0, 0.6, 1.0)

dsl_osd_bbox_enabled_get

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

This service returns the current bounding box display enabled setting for the named On-Screen Display.

IMPORTANT! this service can be called at runtime while the Pipeline is playing.

Parameters

  • name - [in] unique name of the On-Screen Display to query.
  • enabled - [out] true if bounding box display is currently enabled, false otherwise.

Returns

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

Python Example

retval, enabled = dsl_osd_bbox_enabled_get('my-on-screen-display')

dsl_osd_bbox_enabled_set

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

This service sets the current bounding box display enabled setting for the named On-Screen Display.

Parameters

  • name - [in] unique name of the On-Screen Display to update.
  • enable - [in] set to true to enable bounding box display, false otherwise.

Returns

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

Python Example

retval = dsl_osd_bbox_enabled_set('my-on-screen-display', False)

dsl_osd_mask_enabled_get

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

This service returns the current segmentation mask display enabled setting for the named On-Screen Display.

Parameters

  • name - [in] unique name of the On-Screen Display to query.
  • enabled - [out] true if segmentation mask display is currently enabled, false otherwise.

Returns

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

Python Example

retval, enabled = dsl_osd_mask_enabled_get('my-on-screen-display')

dsl_osd_mask_enabled_set

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

This service sets the current segmentation mask display enabled setting for the named On-Screen Display.

IMPORTANT! this service can be called at runtime while the Pipeline is playing.

Parameters

  • name - [in] unique name of the On-Screen Display to update.
  • enable - [in] set to true to enable segmentation mask display, false otherwise.

Returns

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

Python Example

retval = dsl_osd_mask_enabled_set('my-on-screen-display', False)

dsl_osd_process_mode_get

DslReturnType dsl_osd_process_mode_get(const wchar_t* name, uint* mode);

This service returns the current process-mode setting for the named On-Screen Display Default value -- explicity set by DSL on OSD creation is DSL_OSD_PROCESS_MODE_CPU.

Parameters

  • name - [in] unique name of the On-Screen Display to query.
  • mode - [out] one of the DSL_OSD_PROCESS_MODE constants defined above.

Returns

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

Python Example

retval, mode = dsl_osd_process_mode_get('my-on-screen-display')

dsl_osd_process_mode_set

DslReturnType dsl_osd_process_mode_set(const wchar_t* name, uint mode);

This service sets the process-mode setting for the named On-Screen Display.

Parameters

  • name - [in] unique name of the On-Screen Display to update.
  • mode - [in] one of the DSL_OSD_PROCESS_MODE constants defined above.

Returns

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

Python Example

retval = dsl_osd_process_mode_set('my-on-screen-display', DSL_OSD_PROCESS_MODE_GPU)

dsl_osd_pph_add

DslReturnType dsl_osd_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 On-Screen Display.

Parameters

  • name - [in] unique name of the On-Screen Display 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

  • Example using Nvidia's pyds lib to handle batch-meta data
retval = dsl_osd_pph_add('my-osd', 'my-pph-handler', `DSL_PAD_SINK`)

dsl_osd_pph_remove

DslReturnType dsl_osd_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 On-Screen Display. The service will fail if the named handler is not owned by the Tiler

Parameters

  • name - [in] unique name of the On-Screen Display 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_osd_pph_remove('my-osd', 'my-pph-handler', `DSL_PAD_SINK`)

API Reference