hayodea
fc1fcae0b0
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.
141 lines
5.9 KiB
Markdown
141 lines
5.9 KiB
Markdown
# 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.
|
|
|
|
**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.
|
|
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. The following
|
|
forms are invalid because they omit units:
|
|
|
|
- `[<pos|neg>trin-]<interest|distraction|stupef<action|ying>|intolerable>`
|
|
|
|
On dedicated **`postrin(...)`** / **`negtrin(...)`** lines, the short forms
|
|
**`interest-...`**, **`distraction-...`**, etc. still require those unit
|
|
suffixes.
|
|
|
|
## Interest Threshold Parameters
|
|
|
|
**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 intrinsic spec, and present it to SMO via postrinInd/negtrinInd
|
|
with the "importance" argument set to "INTERESTING".
|
|
|
|
**Example (dedicated negtrin line):**
|
|
````
|
|
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
|
|
````
|
|
|
|
## Distraction Threshold Parameters
|
|
|
|
**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".
|
|
|
|
## Stupefying Threshold Parameters (Postrin)
|
|
|
|
**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".
|
|
|
|
## Intolerable Threshold Parameters (Negtrin)
|
|
|
|
**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".
|
|
|
|
## 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.
|