From 5811af7cb14224326d4d7865c60ea318e7a461aa Mon Sep 17 00:00:00 2001 From: Hayodea Hekol Date: Fri, 3 Apr 2026 21:57:41 -0400 Subject: [PATCH] Docs: Intrins now require units. --- docs/design/intrin-thresholds.md | 121 +++++++++++++++--------------- docs/livox-gen1-lidar-dap-spec.md | 19 ++--- 2 files changed, 70 insertions(+), 70 deletions(-) diff --git a/docs/design/intrin-thresholds.md b/docs/design/intrin-thresholds.md index 4bc7c9f..43c2c25 100644 --- a/docs/design/intrin-thresholds.md +++ b/docs/design/intrin-thresholds.md @@ -9,20 +9,42 @@ allow the stimbuff API library to determine when to construct a stencil for postrin or negtrin data and present it to SMO with appropriate importance classifications. +## Unit Suffix Rules + +All intrinsic threshold params must include an explicit unit suffix. +These suffix families are not synonyms with each other; they select +different units: + +- `-percentage`/`-pc` +- `-threshold`/`-thresh`/`-thr` + +Parameters with the `-percentage` or `-pc` suffix take a percentage in +the range `0-100`. + +Parameters with the `-threshold`, `-thresh`, or `-thr` suffix take an +absolute number. The interpretation of that number, and the underlying +unit, is defined by the API library itself. + +Users must specify only one unit-suffixed parameter per targeted +intrinsic classification. If multiple unit-suffixed variants targeting +the same classification are supplied anyway, the lattermost supplied +parameter takes precedence. + +Shorthand params without a unit suffix are not permitted anymore. The +following forms are invalid because they all omit units: + +- `[trin-]|intolerable>` + +For stupefying and intolerable thresholds specifically, the `postrin-` +or `negtrin-` prefix may be omitted when the intended intrinsic is +already implied by the classification itself. Even in those cases, a +unit suffix is still mandatory. + ## Interest Threshold Parameters -**Synonyms:** -- `postrin-interest-percentage` -- `postrin-interest-pc` -- `postrin-interest-threshold` -- `postrin-interest-th` (abbreviation for `-threshold`) -- `interest-threshold` -- `postrin-interest` -- `negtrin-interest-percentage` -- `negtrin-interest-pc` -- `negtrin-interest-threshold` -- `negtrin-interest-th` (abbreviation for `-threshold`) -- `negtrin-interest` +**Parameter forms:** +- `postrin-interest-` +- `negtrin-interest-` **Description:** These parameters denote the value at which the stimbuff API library @@ -33,30 +55,23 @@ postrinInd/negtrinInd with the "importance" argument set to "INTERESTING". **Specification:** - The parameter is specified as part of the `quale-iface-api-params` in the DAP specification -- Parameters with the `-percentage` or `-pc` suffix are interpreted as percentages (0-100) -- Parameters with the `-threshold` or `-th` suffix are interpreted as absolute threshold values -- The `-threshold` suffix can be abbreviated as `-th` -- If multiple synonyms are specified, the lattermost (last encountered) - synonym takes precedence +- The unit suffix rules from the top of this document apply here too - Separate thresholds can be specified for postrin and negtrin using the respective prefixes **Example:** -``` -+idev|my-device|pcloudIntensity(postrin-interest-percentage=50|negtrin-interest-threshold=30)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39 -``` +```` ++idev|my-device|pcloudIntensity(postrin-interest-percentage=50|negtrin-interest-thr=30)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39 +```` -This example sets the interest threshold to 50% for postrins (percentage-based) and 30 for -negtrins (absolute threshold value). +This example sets the interest threshold to 50% for postrins +(percentage-based) and 30 for negtrins (absolute threshold value). ## Distraction Threshold Parameters -**Synonyms:** -- `postrin-distraction-threshold` -- `distraction-threshold` -- `postrin-distraction` -- `negtrin-distraction-threshold` -- `negtrin-distraction` +**Parameter forms:** +- `postrin-distraction-` +- `negtrin-distraction-` **Description:** These parameters denote the value at which the stimbuff API library @@ -66,30 +81,23 @@ negtrinInd/postrinInd with the importance argument set to "DISTRACTION". **Specification:** - The parameter is specified as part of the `quale-iface-api-params` in the DAP specification -- The value is a numeric threshold that determines when stencils are - constructed and delivered with DISTRACTION importance -- If multiple synonyms are specified, the lattermost (last encountered) - synonym takes precedence +- The unit suffix rules from the top of this document apply here too - Separate thresholds can be specified for postrin and negtrin using the respective prefixes **Example:** -``` -+idev|my-device|pcloudIntensity(negtrin-distraction-threshold=60|postrin-distraction-threshold=40)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39 -``` +```` ++idev|my-device|pcloudIntensity(negtrin-distraction-thr=60|postrin-distraction-thr=40)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39 +```` This example sets the distraction threshold to 60 for negtrins and 40 for postrins. ## Stupefying Threshold Parameters (Postrin) -**Synonyms:** -- `postrin-stupefaction-threshold` -- `postrin-stupefaction` -- `stupefaction-threshold` -- `postrin-stupefying` -- `stupefaction` -- `stupefying` +**Parameter forms:** +- `[postrin-]stupefaction-` +- `[postrin-]stupefying-` **Description:** These parameters denote the value at which the stimbuff API library @@ -99,27 +107,21 @@ the importance argument set to "STUPEFYING". **Specification:** - The parameter is specified as part of the `quale-iface-api-params` in the DAP specification -- The value is a numeric threshold that determines when stencils are - constructed and delivered with STUPEFYING importance +- The unit suffix rules from the top of this document apply here too - These parameters apply only to postrin data (positive intrinsic stimuli) -- If multiple synonyms are specified, the lattermost (last encountered) - synonym takes precedence **Example:** -``` -+idev|my-device|pcloudIntensity(postrin-stupefying=80)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39 -``` +```` ++idev|my-device|pcloudIntensity(stupefying-thr=80)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39 +```` This example sets the stupefying threshold to 80 for postrins. ## Intolerable Threshold Parameters (Negtrin) -**Synonyms:** -- `negtrin-intolerable-threshold` -- `negtrin-intolerable` -- `intolerable-threshold` -- `intolerable` +**Parameter forms:** +- `[negtrin-]intolerable-` **Description:** These parameters denote the value at which the stimbuff API library @@ -129,17 +131,14 @@ the importance argument set to "INTOLERABLE". **Specification:** - The parameter is specified as part of the `quale-iface-api-params` in the DAP specification -- The value is a numeric threshold that determines when stencils are - constructed and delivered with INTOLERABLE importance +- The unit suffix rules from the top of this document apply here too - These parameters apply only to negtrin data (negative intrinsic stimuli) -- If multiple synonyms are specified, the lattermost (last encountered) - synonym takes precedence **Example:** -``` -+idev|my-device|pcloudIntensity(negtrin-intolerable=90)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39 -``` +```` ++idev|my-device|pcloudIntensity(intolerable-thr=90)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39 +```` This example sets the intolerable threshold to 90 for negtrins. diff --git a/docs/livox-gen1-lidar-dap-spec.md b/docs/livox-gen1-lidar-dap-spec.md index 684ccfb..9f4e48d 100644 --- a/docs/livox-gen1-lidar-dap-spec.md +++ b/docs/livox-gen1-lidar-dap-spec.md @@ -46,15 +46,16 @@ Each stim-buff-api is designed to work with specific stim-iface libraries that u **Intrinsic Stimuli Support** (for pcloudAmbience quale-iface-api): The `pcloudAmbience` quale-iface-api exports both a postrin and a negtrin whose thresholds are configurable via standard quale-iface-api-params: -- **Postrin interest threshold**: Configurable via `postrin-interest-percentage` / `postrin-interest-pc` / `postrin-interest` (default: 90, interpreted as percentage) -- **Negtrin interest threshold**: Configurable via `negtrin-interest-percentage` / `negtrin-interest-pc` / `negtrin-interest-threshold` / `negtrin-interest-th` / `negtrin-interest` (default: 30) +- **Postrin interest threshold**: Configurable via `postrin-interest-[percentage|pc|threshold|thresh|thr]` +- **Negtrin interest threshold**: Configurable via `negtrin-interest-[percentage|pc|threshold|thresh|thr]` -The postrin interest threshold is percentage-based only (0-100) and specifies the -percentage of frames whose average intensity must be <= the ambience intensity low -value threshold. Frames whose average intensity is <= the ambience intensity low -value qualify for postrin, and frames whose average intensity is >= the negtrin -interest threshold qualify for negtrin. The ambience count written to each stimFrame -is the number of frames that qualify for either intrinsic. +The `-percentage` and `-pc` variants take percentages in the range +`0-100`. The `-threshold`, `-thresh`, and `-thr` variants take an +absolute number whose interpretation is defined by the API library +itself. Users should specify only one unit-suffixed variant per targeted +intrinsic threshold; if multiple such variants are supplied, the +lattermost one takes precedence. Shorthand forms without a unit suffix +are not valid. ### 3. Point Cloud Coordinate Data Device (Extrospector) @@ -258,4 +259,4 @@ The specification includes comprehensive error handling for: - Invalid coordinate format requests - IMU data stream interruptions - Device discovery failures -- Connection retry timeouts \ No newline at end of file +- Connection retry timeouts