DAPS: Add intrin specs to nontrin specs
We no longer do intrin specs as a separate stimbuff; rather now we do them as a specifier segment within the pipeline spec of a normal nontrin spec.
This commit is contained in:
@@ -9,30 +9,33 @@ 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.
|
||||
**Intrinsic parameters live inside `postrin(...)` / `negtrin(...)`
|
||||
segments attached to a nontrin DAP line.** A DAP line may declare at most
|
||||
one `postrin(...)` segment and at most one `negtrin(...)` segment, and both
|
||||
must precede the qualeIfaceApi segment. Ordering between postrin and
|
||||
negtrin is free.
|
||||
|
||||
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`.
|
||||
Intrinsic threshold params (and the deprecated `from-stimbuff` marker)
|
||||
must not appear on the qualeIfaceApi params themselves — policy
|
||||
validation rejects them there. The nontrin qualeIfaceApi
|
||||
(e.g. `pcloudAmbience`) still owns its own sensory params (such as
|
||||
passband comparators); only the threshold classifications (`interest-*`,
|
||||
`distraction-*`, `stupefaction-*` / `stupefying-*`, `intolerable-*`) live
|
||||
in the postrin/negtrin segments.
|
||||
|
||||
## Dedicated `negtrin` / `postrin` qualeIfaceApi names
|
||||
## `postrin` / `negtrin` segments
|
||||
|
||||
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.
|
||||
On **`postrin(...)`** or **`negtrin(...)`**, the intrinsic family
|
||||
(positive vs negative) is fixed by the segment name, so only the
|
||||
unprefixed short forms **`interest-...`**, **`distraction-...`**,
|
||||
**`stupefaction-` / `stupefying-...`**, and **`intolerable-...`** (with
|
||||
the unit suffix rules below) are accepted.
|
||||
|
||||
Example (negtrin driven by ambience, short interest param, passband comparator):
|
||||
Example (negtrin segment attached to ambience, with passband comparator
|
||||
on the nontrin qualeIfaceApi):
|
||||
|
||||
````
|
||||
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
|
||||
+edev|avia0|negtrin(interest-pc=85)|pcloudAmbience(passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39||
|
||||
````
|
||||
|
||||
## Unit Suffix Rules
|
||||
@@ -59,20 +62,18 @@ 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>`
|
||||
- `<interest|distraction|stupef<action|ying>|intolerable>`
|
||||
|
||||
On dedicated **`postrin(...)`** / **`negtrin(...)`** lines, the short forms
|
||||
Inside **`postrin(...)`** / **`negtrin(...)`** segments, the short forms
|
||||
**`interest-...`**, **`distraction-...`**, etc. still require those unit
|
||||
suffixes.
|
||||
|
||||
## Interest Threshold Parameters
|
||||
|
||||
**Parameter forms (only inside `negtrin(...)` or `postrin(...)`):**
|
||||
**Parameter forms (only inside `postrin(...)` or `negtrin(...)`
|
||||
segments):**
|
||||
|
||||
- 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>`
|
||||
- `interest-<percentage|pc|threshold|thresh|thr>`
|
||||
|
||||
**Description:**
|
||||
These parameters denote the value at which the stimbuff API library
|
||||
@@ -80,32 +81,29 @@ 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):**
|
||||
**Example (negtrin segment attached to ambience):**
|
||||
````
|
||||
+edev|avia0|negtrin(from-stimbuff=pcloudAmbience|interest-pc=85|passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39
|
||||
+edev|avia0|negtrin(interest-pc=85)|pcloudAmbience(passband-count-gt-val=120)|livoxGen1()|livoxProto1(SMO_IP)|3JEDK380010Z39||
|
||||
````
|
||||
|
||||
## Distraction Threshold Parameters
|
||||
|
||||
**Parameter forms (only inside `negtrin(...)` or `postrin(...)`):**
|
||||
**Parameter forms (only inside `postrin(...)` or `negtrin(...)`
|
||||
segments):**
|
||||
|
||||
- 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)
|
||||
- `distraction-<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/postrinInd with the importance argument set to "DISTRACTION".
|
||||
postrinInd/negtrinInd with the importance argument set to "DISTRACTION".
|
||||
|
||||
## Stupefying Threshold Parameters (Postrin)
|
||||
|
||||
**Parameter forms (only inside `postrin(...)`):**
|
||||
**Parameter forms (only inside `postrin(...)` segments):**
|
||||
|
||||
- Prefixed: `[postrin-]stupefaction-<percentage|pc|threshold|thresh|thr>`,
|
||||
`[postrin-]stupefying-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short: `stupefaction-...`, `stupefying-...` with unit suffix
|
||||
- `stupefaction-<percentage|pc|threshold|thresh|thr>`
|
||||
- `stupefying-<percentage|pc|threshold|thresh|thr>`
|
||||
|
||||
**Description:**
|
||||
These parameters denote the value at which the stimbuff API library
|
||||
@@ -114,10 +112,9 @@ the importance argument set to "STUPEFYING".
|
||||
|
||||
## Intolerable Threshold Parameters (Negtrin)
|
||||
|
||||
**Parameter forms (only inside `negtrin(...)`):**
|
||||
**Parameter forms (only inside `negtrin(...)` segments):**
|
||||
|
||||
- Prefixed: `[negtrin-]intolerable-<percentage|pc|threshold|thresh|thr>`
|
||||
- Short: `intolerable-<percentage|pc|threshold|thresh|thr>`
|
||||
- `intolerable-<percentage|pc|threshold|thresh|thr>`
|
||||
|
||||
**Description:**
|
||||
These parameters denote the value at which the stimbuff API library
|
||||
|
||||
+29
-28
@@ -18,16 +18,15 @@ descriptors tell it exactly which body spots are raising it.
|
||||
|
||||
This direct information also assists SMO in narrowing down the scope of its
|
||||
DB searches for methods to handle (increase or decrease) the stimval. For
|
||||
example, for a negtrin whose intrinsic pipeline is declared with a dedicated
|
||||
`negtrin(...)` spec (and whose sensory data may come from intensity or another
|
||||
stimbuff via `from-stimbuff`), we don't search DB by trying to match all
|
||||
possible body spots with their stimvals. Rather, we search for all the body
|
||||
spots that are described in the stencil. This optimizes DB searches
|
||||
and also makes negtrin relieving/postrin satisfying searches more explicit
|
||||
and obviously scoped items of knowledge. The eventual solution is
|
||||
automatically classified as being a method to relieve/satisfy intrins at
|
||||
this point on the body and not just hazily generally for "all over the
|
||||
body". We get to make the new item of knowledge more specific.
|
||||
example, for a negtrin raised from a `negtrin(...)` segment attached to a
|
||||
nontrin DAP line (e.g. `pcloudAmbience`), we don't search DB by trying to
|
||||
match all possible body spots with their stimvals. Rather, we search for
|
||||
all the body spots that are described in the stencil. This optimizes DB
|
||||
searches and also makes negtrin relieving/postrin satisfying searches
|
||||
more explicit and obviously scoped items of knowledge. The eventual
|
||||
solution is automatically classified as being a method to relieve/satisfy
|
||||
intrins at this point on the body and not just hazily generally for "all
|
||||
over the body". We get to make the new item of knowledge more specific.
|
||||
|
||||
## Format and Allocation Model
|
||||
|
||||
@@ -60,15 +59,14 @@ But it's fine because we don't expect the relationship between SMO and
|
||||
stimbuff libraries to be inimical enough for security measures like that to
|
||||
be non-negotiable.
|
||||
|
||||
## n-stencils QualeIfaceApi Parameter
|
||||
## n-stencils Intrin-Segment Parameter
|
||||
|
||||
Where a stim buff supports it, a qualeIfaceApi parameter called `n-stencils`
|
||||
tells the stimbuff how many stencils it can allocate and deliver to SMO
|
||||
simultaneously for **intrinsic** delivery. Intrinsic rate limiting and stencil
|
||||
counts apply to **dedicated** intrinsic qualeIfaceApi specs (`negtrin(...)`,
|
||||
`postrin(...)`) when the implementation attaches them—not to sensory-only
|
||||
lines such as `pcloudIntensity` or `pcloudAmbience` (see
|
||||
`docs/design/intrin-thresholds.md`).
|
||||
Where a stim buff supports it, a parameter called `n-stencils` tells the
|
||||
stimbuff how many stencils it can allocate and deliver to SMO
|
||||
simultaneously for **intrinsic** delivery. `n-stencils` belongs on the
|
||||
`postrin(...)` / `negtrin(...)` segment it rate-limits — **not** on the
|
||||
nontrin qualeIfaceApi params. Postrin and negtrin get independent
|
||||
budgets.
|
||||
|
||||
The stimbuff must wait until SMO returns stencils to it via postrinEventRdy or
|
||||
negtrinEventRdy before delivering new intrin events. Stimbuffs can deliver
|
||||
@@ -77,23 +75,26 @@ have been given to SMO, they must wait until SMO returns a stencil before
|
||||
raising new intrins.
|
||||
|
||||
**Specification:**
|
||||
- The parameter is specified as part of the `quale-iface-api-params` in the
|
||||
DAP specification
|
||||
- The value is an integer representing the maximum number of stencils that
|
||||
can be allocated simultaneously
|
||||
- The parameter is specified inside a `postrin(...)` or `negtrin(...)`
|
||||
segment on a DAP line
|
||||
- The value is an integer representing the maximum number of stencils
|
||||
that can be allocated simultaneously for that segment's intrin path
|
||||
- This parameter controls rate limiting for intrin events
|
||||
- Stimbuffs must respect this limit and wait for stencil returns before
|
||||
allocating new ones
|
||||
|
||||
**Example (generic dedicated intrin line—shape only; names depend on device):**
|
||||
**Example (generic shape — names depend on device):**
|
||||
```
|
||||
+idev|my-device|negtrin(from-stimbuff=someSensoryQuale|n-stencils=4)|someStimBuffApi()|livoxProto1()|SERIAL
|
||||
+idev|my-device
|
||||
|negtrin(interest-pc=85|n-stencils=4)|someSensoryQuale()|someStimBuffApi()
|
||||
|livoxProto1()|SERIAL
|
||||
```
|
||||
|
||||
The Livox Gen1 **`pcloudAmbience`** sensory line does **not** use `n-stencils`;
|
||||
ambience floats are delivered in the stimulus frame buffer. If Livox adds
|
||||
`n-stencils` for intrinsic pipelines, it would appear on **`negtrin(...)`** /
|
||||
**`postrin(...)`** lines (with `from-stimbuff`), not on `pcloudAmbience` itself.
|
||||
The Livox Gen1 **`pcloudAmbience`** sensory line does **not** use
|
||||
`n-stencils`; ambience floats are delivered in the stimulus frame buffer.
|
||||
If Livox adds `n-stencils` for its intrinsic pipelines, it would appear
|
||||
inside the `postrin(...)` / `negtrin(...)` segments attached to
|
||||
`pcloudAmbience`, not on `pcloudAmbience` itself.
|
||||
|
||||
**Invalid (sensory qualeIfaceApi must not carry intrin-oriented params):**
|
||||
```
|
||||
|
||||
@@ -43,9 +43,12 @@ Each stim-buff-api is designed to work with specific stim-iface libraries that u
|
||||
**Stim-Buff-API**: `livoxGen1-pcloud`
|
||||
**Quale-Iface-API**: `pcloudAmbience` - Delivers per-dagram average intensity floats (sensory stream only).
|
||||
|
||||
Intrinsic thresholds, passband comparators, and `from-stimbuff` wiring are **not** configured on
|
||||
`pcloudAmbience`. Use separate DAP lines with qualeIfaceApi **`negtrin(...)`** or **`postrin(...)`**
|
||||
and `from-stimbuff=pcloudAmbience`; see `docs/design/intrin-thresholds.md` and the `PcloudAmbienceIntrinStimulusBuffer` path in the LivoxGen1 stim buff API.
|
||||
Passband comparators (`passband-count-lt-val`, `passband-count-gt-val`) belong on
|
||||
`pcloudAmbience(...)` itself, and both may appear together — `lt` drives the
|
||||
postrin path, `gt` drives the negtrin path. Intrinsic threshold params
|
||||
(`interest-*`, `distraction-*`, `stupefaction-*`/`stupefying-*`, `intolerable-*`)
|
||||
live inside `postrin(...)` / `negtrin(...)` segments attached to the same DAP
|
||||
line. See `docs/design/intrin-thresholds.md`.
|
||||
|
||||
### 3. Point Cloud Coordinate Data Device (Extrospector)
|
||||
|
||||
@@ -155,9 +158,7 @@ The `livoxProto1` provider accepts the following parameters:
|
||||
| Stim Feature | Stim-Buff-API | Quale-Iface-API | Description |
|
||||
|--------------|---------------|----------------|-------------|
|
||||
| Point Cloud Intensity | `livoxGen1-pcloudIntensity` | `pcloudIntensity` | Light intensity/reflectivity data |
|
||||
| Point Cloud Ambience | `livoxGen1-pcloud` | `pcloudAmbience` | Per-dagram average intensity vector (`float` × `n-dgrams-per-frame`) |
|
||||
| Ambience-driven intrinsic (negtrin) | `livoxGen1-pcloud` | `negtrin` | Dedicated intrin pipeline; requires `from-stimbuff=pcloudAmbience` and intrin params per `docs/design/intrin-thresholds.md` |
|
||||
| Ambience-driven intrinsic (postrin) | `livoxGen1-pcloud` | `postrin` | Same as negtrin row, for positive intrinsics |
|
||||
| Point Cloud Ambience | `livoxGen1-pcloud` | `pcloudAmbience` | Per-dagram average intensity vector (`float` × `n-dgrams-per-frame`). Accepts `postrin(...)` / `negtrin(...)` segments on the same DAP line for intrin thresholds; see `docs/design/intrin-thresholds.md`. |
|
||||
| Point Cloud Coordinates | `livoxGen1-pcloud` | `pcloud` | Spatial coordinate data |
|
||||
| Gyroscope | `livoxGen1-gyro` | `gyro` | Angular velocity measurements |
|
||||
| Accelerometer | `livoxGen1-accel` | `accel` | Linear acceleration measurements |
|
||||
|
||||
Reference in New Issue
Block a user