DAP: Add intrin DAPSpecs
We now specify intrins as separate DAPS lines. This syntax is much nicer and well-grouped than the previous negtrin-*/postrin-* param names. Alas, we're about to replace it in the next few commits already though.
This commit is contained in:
@@ -9,6 +9,32 @@ 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.
|
||||
|
||||
**Intrinsic parameters may appear only on dedicated intrinsic qualeIfaceApi
|
||||
specs.** The only supported forms are **`negtrin(...)`** and **`postrin(...)`**.
|
||||
You cannot attach intrinsic threshold params to a sensory or other
|
||||
non-intrinsic qualeIfaceApi (for example `pcloudIntensity`, `pcloudAmbience`,
|
||||
`mesh`, `pcloud`, and so on). Those lines are for sensory streams only.
|
||||
|
||||
A dedicated intrinsic line must name the sensory stimbuff it derives from via
|
||||
**`from-stimbuff=<qualeIfaceApi>`** (non-empty). Policy validation rejects
|
||||
intrinsic params and passband-style comparators on sensory lines, and rejects
|
||||
dedicated lines that omit `from-stimbuff`.
|
||||
|
||||
## Dedicated `negtrin` / `postrin` qualeIfaceApi names
|
||||
|
||||
On **`negtrin(...)`** or **`postrin(...)`**, the intrinsic family (negative vs
|
||||
positive) is fixed by the API name. The **`negtrin-`** and **`postrin-`**
|
||||
prefixes on parameter names are **optional**: you may use short forms
|
||||
**`interest-...`**, **`distraction-...`**, **`stupefaction-` / `stupefying-...`**,
|
||||
and **`intolerable-...`** with the unit suffix rules below. Prefixed names such
|
||||
as **`negtrin-interest-pc`** remain valid when you prefer explicit spelling.
|
||||
|
||||
Example (negtrin driven by ambience, short interest param, passband comparator):
|
||||
|
||||
````
|
||||
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
|
||||
````
|
||||
|
||||
## Unit Suffix Rules
|
||||
|
||||
All intrinsic threshold params must include an explicit unit suffix.
|
||||
@@ -30,118 +56,74 @@ 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:
|
||||
Shorthand params without a unit suffix are not permitted. The following
|
||||
forms are invalid because they omit units:
|
||||
|
||||
- `[<pos|neg>trin-]<interest|distraction|stupef<action|ying>|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.
|
||||
On dedicated **`postrin(...)`** / **`negtrin(...)`** lines, the short forms
|
||||
**`interest-...`**, **`distraction-...`**, etc. still require those unit
|
||||
suffixes.
|
||||
|
||||
## Interest Threshold Parameters
|
||||
|
||||
**Parameter forms:**
|
||||
- `postrin-interest-<percentage|pc|threshold|thresh|thr>`
|
||||
- `negtrin-interest-<percentage|pc|threshold|thresh|thr>`
|
||||
**Parameter forms (only inside `negtrin(...)` or `postrin(...)`):**
|
||||
|
||||
- Prefixed: `postrin-interest-<percentage|pc|threshold|thresh|thr>`,
|
||||
`negtrin-interest-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short (prefix optional because the line is already negtrin or postrin):
|
||||
`interest-<percentage|pc|threshold|thresh|thr>`
|
||||
|
||||
**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".
|
||||
for this intrinsic spec, 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 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:**
|
||||
**Example (dedicated negtrin line):**
|
||||
````
|
||||
+idev|my-device|pcloudIntensity(postrin-interest-percentage=50|negtrin-interest-thr=30)|livoxGen1-pcloudIntensity()|livoxProto1()|3JEDK380010Z39
|
||||
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
|
||||
````
|
||||
|
||||
This example sets the interest threshold to 50% for postrins
|
||||
(percentage-based) and 30 for negtrins (absolute threshold value).
|
||||
|
||||
## Distraction Threshold Parameters
|
||||
|
||||
**Parameter forms:**
|
||||
- `postrin-distraction-<percentage|pc|threshold|thresh|thr>`
|
||||
- `negtrin-distraction-<percentage|pc|threshold|thresh|thr>`
|
||||
**Parameter forms (only inside `negtrin(...)` or `postrin(...)`):**
|
||||
|
||||
- Prefixed: `postrin-distraction-<percentage|pc|threshold|thresh|thr>`,
|
||||
`negtrin-distraction-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short: `distraction-<percentage|pc|threshold|thresh|thr>` (family is
|
||||
fixed by the `negtrin` / `postrin` API name)
|
||||
|
||||
**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 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-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)
|
||||
|
||||
**Parameter forms:**
|
||||
- `[postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>`
|
||||
- `[postrin-]stupefying-<percentage|pc|threshold|thresh|thr>`
|
||||
**Parameter forms (only inside `postrin(...)`):**
|
||||
|
||||
- Prefixed: `[postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>`,
|
||||
`[postrin-]stupefying-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short: `stupefaction-...`, `stupefying-...` with unit suffix
|
||||
|
||||
**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 unit suffix rules from the top of this document apply here too
|
||||
- These parameters apply only to postrin data (positive intrinsic
|
||||
stimuli)
|
||||
|
||||
**Example:**
|
||||
````
|
||||
+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)
|
||||
|
||||
**Parameter forms:**
|
||||
- `[negtrin-]intolerable-<percentage|pc|threshold|thresh|thr>`
|
||||
**Parameter forms (only inside `negtrin(...)`):**
|
||||
|
||||
- Prefixed: `[negtrin-]intolerable-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short: `intolerable-<percentage|pc|threshold|thresh|thr>`
|
||||
|
||||
**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 unit suffix rules from the top of this document apply here too
|
||||
- These parameters apply only to negtrin data (negative intrinsic
|
||||
stimuli)
|
||||
|
||||
**Example:**
|
||||
````
|
||||
+idev|my-device|pcloudIntensity(intolerable-thr=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
|
||||
|
||||
Reference in New Issue
Block a user