From 7a14b48dadde2bbe640237d4fc933b9a657b090a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Olivier=20Cr=C3=AAte?= Date: Sun, 3 Mar 2024 18:34:41 -0500 Subject: [PATCH] analytics: Add missing documentation Part-of: --- girs/GstAnalytics-1.0.gir | 15 ++++--- .../analytics/gstanalyticsclassificationmtd.c | 16 ++++++++ .../gst-libs/gst/analytics/gstanalyticsmeta.c | 18 +++++++++ .../gst-libs/gst/analytics/gstanalyticsmeta.h | 39 ++++++++++++++++++- .../gstanalyticsobjectdetectionmtd.c | 14 +++++++ .../analytics/gstanalyticsobjecttrackingmtd.c | 16 ++++++++ 6 files changed, 109 insertions(+), 9 deletions(-) diff --git a/girs/GstAnalytics-1.0.gir b/girs/GstAnalytics-1.0.gir index 8b62d06e64..571d6441d5 100644 --- a/girs/GstAnalytics-1.0.gir +++ b/girs/GstAnalytics-1.0.gir @@ -134,6 +134,7 @@ identified by @id is stored. + Get instance id Id of @instance @@ -141,8 +142,7 @@ identified by @id is stored. - Instance of #GstAnalyticsMtd -Get instance id + Instance of #GstAnalyticsMtd @@ -682,13 +682,12 @@ otherwise this method return FALSE and @rlt is invalid. - - - relation description between first and second analysis-meta. - -Get relations between first and second analysis-meta. + Get relations between first and second analysis-meta. Ids (@an_meta_first_id and @an_meta_second_id) must be from a call to @gst_analytics_mtd_get_id (handle). + + + relation description between first and second analysis-meta. @@ -1000,7 +999,7 @@ information about the tracking, for example, it can be used alongside a Number of analysis-meta attached to this -instance. + instance. diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsclassificationmtd.c b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsclassificationmtd.c index 0fc5065389..0748af2b18 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsclassificationmtd.c +++ b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsclassificationmtd.c @@ -24,6 +24,22 @@ #include "gstanalyticsclassificationmtd.h" +/** + * SECTION:gstanalyticsclassificationtd + * @title: GstAnalyticsClsMtd + * @short_description: An analytics metadata for classification inside a #GstAnalyticsRelationMeta + * @symbols: + * - GstAnalyticsClsMtd + * @see_also: #GstAnalyticsMtd, #GstAnalyticsRelationMeta + * + * This type of metadata holds classification, it is generally used in + * relationship with another metadata type to enhance its content. For example, + * it can enhance the classifcation of an object detection held by the + * #GstAnalyticsODMtd metadata type. + * + * Since: 1.24 + */ + static const GstAnalyticsMtdImpl cls_impl = { "classification", NULL diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c index 054caff898..d97bbc3a2d 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c +++ b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.c @@ -26,6 +26,24 @@ #include +/** + * SECTION:gstanalyticsmeta + * @title: GstAnalyticsRelationMeta + * @short_description: A GstMeta for analytics metadata + * @symbols: + * - GstAnalyticsRelationMeta + * - GstAnalyticsMtd + * @see_also: #GstAnalyticsODMtd, #GstAnalyticsClsMtd, #GstAnalyticsTrackingMtd + * + * The #GstAnalyticsRelationMeta is a #GstMeta that can contain a large number + * of results from the analysis of a meta. Each result can be accessed by + * using its id, or more conviently, by using a #GstAnalyticsMtd. A matrix + * of relationships between the various metadata is also defined and can be + * filled by the analysis processes. + * + * Since: 1.24 + */ + GST_DEBUG_CATEGORY_STATIC (an_relation_meta_debug); #define GST_CAT_AN_RELATION an_relation_meta_debug diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.h b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.h index 29147bf202..7da1453c07 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.h +++ b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsmeta.h @@ -30,8 +30,15 @@ #include G_BEGIN_DECLS + +/** + * GST_INF_RELATION_SPAN: + * Passes to functions asking for a relation span when the span is + * infinite. + * + * Since: 1.24 + */ #define GST_INF_RELATION_SPAN -1 -#define GST_AN_RELATION_META_TAG "GST-ANALYSIS-RELATION-META-TAG" typedef struct _GstAnalyticsMtd GstAnalyticsMtd; /** @@ -53,9 +60,25 @@ typedef guintptr GstAnalyticsMtdType; #define GST_ANALYTICS_MTD_TYPE_ANY (0) +/** + * GST_ANALYTICS_MTD_CAST: (skip) + * + * Since: 1.24 + */ #define GST_ANALYTICS_MTD_CAST(mtd) \ ((GstAnalyticsMtd *)(mtd)) +/** + * GstAnalyticsRelationMeta: + * + * An opaque #GstMeta that can be used to hold various types of results + * from analysis processes. + * + * The content should be accessed through the API. + * + * Since: 1.24 + */ + typedef struct _GstAnalyticsRelationMeta GstAnalyticsRelationMeta; /** @@ -75,6 +98,19 @@ struct _GstAnalyticsMtd GstAnalyticsRelationMeta *meta; }; +/** + * GstAnalyticsMtdImpl: + * @name: The name of the metadata type + * @mtd_meta_transform: A pointer to a function that will be called + * when the containing meta is transform to potentially copy the data + * into a new Mtd into the new meta. + * + * This structure must be provided when registering a new type of Mtd. It must + * have a static lifetime (never be freed). + * + * Since: 1.24 + */ + typedef struct { const char *name; @@ -82,6 +118,7 @@ typedef struct { GstBuffer *buffer, GQuark type, gpointer data); + /*< private >*/ gpointer _reserved[GST_PADDING_LARGE]; } GstAnalyticsMtdImpl; diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjectdetectionmtd.c b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjectdetectionmtd.c index 070803b487..f616352fbd 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjectdetectionmtd.c +++ b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjectdetectionmtd.c @@ -26,6 +26,20 @@ #include +/** + * SECTION:gstanalyticsobjectdetectionmtd + * @title: GstAnalyticsODMtd + * @short_description: An analytics metadata for object dection inside a #GstAnalyticsRelationMeta + * @symbols: + * - GstAnalyticsODMtd + * @see_also: #GstAnalyticsMtd, #GstAnalyticsRelationMeta + * + * This type of metadata holds the position of detected object inside the + * image, along with the probabily of each detection. + * + * Since: 1.24 + */ + typedef struct _GstAnalyticsODMtdData GstAnalyticsODMtdData; /** diff --git a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjecttrackingmtd.c b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjecttrackingmtd.c index 40a646f188..78bb327312 100644 --- a/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjecttrackingmtd.c +++ b/subprojects/gst-plugins-bad/gst-libs/gst/analytics/gstanalyticsobjecttrackingmtd.c @@ -24,6 +24,22 @@ #include "gstanalyticsobjecttrackingmtd.h" +/** + * SECTION:gstanalyticsobjecttrackingmtd + * @title: GstAnalyticsTrackingMtd + * @short_description: An analytics metadata for tracking inside a #GstAnalyticsRelationMeta + * @symbols: + * - GstAnalyticsTrackingMtd + * @see_also: #GstAnalyticsMtd, #GstAnalyticsRelationMeta + * + * This type of metadata holds tracking information. In many cases, it is + * desired to track an object across many frames. This type of metadata holds + * information about the tracking, for example, it can be used alongside a + * #GstAnalyticsODMtd to track an object. + * + * Since: 1.24 + */ + typedef struct _GstAnalyticsTrackingMtdData GstAnalyticsTrackingMtdData; /**