Docs: add params for postrin/negtrin thresholds

2025-11-26 03:28:43 -04:00
parent 5cce473e01
commit b6c426871e
1 changed files with 152 additions and 0 deletions
@@ -0,0 +1,152 @@
+# Intrinsic Threshold Parameters
+
+## Overview
+
+This document describes quale-iface-api-params that control threshold
+values for constructing stencils and delivering them to SMO via
+postrinInd/negtrinInd with different importance levels. These parameters
+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.
+
+## Interest Threshold Parameters
+
+**Synonyms:**
+- `postrin-interest-threshold`
+- `interest-threshold`
+- `postrin-interest`
+- `negtrin-interest-threshold`
+- `negtrin-interest`
+
+**Description:**
+These parameters denote the value at which the stimbuff API library
+should construct a stencil for the postrin or negtrin that it delivers
+for this DAPSpec's qualeIfaceApi's stimfeat, and present it to SMO via
+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
+- The value is a numeric threshold that determines when stencils are
+  constructed and delivered with INTERESTING importance
+- If multiple synonyms are specified, the lattermost (last encountered)
+  synonym takes precedence
+- Separate thresholds can be specified for postrin and negtrin using the
+  respective prefixes
+
+**Example:**
+```
+idev|my-device|pcloudIntensity(postrin-interest-threshold=50|negtrin-interest-threshold=30)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
+```
+
+This example sets the interest threshold to 50 for postrins and 30 for
+negtrins.
+
+## Distraction Threshold Parameters
+
+**Synonyms:**
+- `postrin-distraction-threshold`
+- `distraction-threshold`
+- `postrin-distraction`
+- `negtrin-distraction-threshold`
+- `negtrin-distraction`
+
+**Description:**
+These parameters denote the value at which the stimbuff API library
+ought to construct a stencil and deliver it to SMO via
+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
+- 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
+```
+
+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`
+
+**Description:**
+These parameters denote the value at which the stimbuff API library
+ought to construct a stencil and deliver it to SMO via postrinInd with
+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
+- 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
+```
+
+This example sets the stupefying threshold to 80 for postrins.
+
+## Intolerable Threshold Parameters (Negtrin)
+
+**Synonyms:**
+- `negtrin-intolerable-threshold`
+- `negtrin-intolerable`
+- `intolerable-threshold`
+- `intolerable`
+
+**Description:**
+These parameters denote the value at which the stimbuff API library
+ought to construct a stencil and deliver it to SMO via negtrinInd with
+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
+- 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
+```
+
+This example sets the intolerable threshold to 90 for negtrins.
+
+## Notes
+
+The way that SMO handles these importance levels is not yet fully worked
+out. For postrins, the distinction between "interesting" vs "stupefying"
+is somewhat reasonably intuitively clear, but how that meaning is given
+in code has not been worked out yet. Similarly, for negtrins, the
+distinctions between "interesting" vs "distracting" vs "intolerable"
+are not entirely clear in terms of how their handling will impose
+meaningful differences that will give meaning to their distinctions.
+
+These parameters provide the mechanism for the stimbuff API library to
+classify and deliver intrinsic stimuli with appropriate importance
+levels, but the downstream processing and behavioral implications of
+these classifications within SMO remain to be fully defined.