Add presentation Extension

[jacobagilbert]

This extension was written to support suggestive input as to how SigMF Recordings and Metadata should be presented visually to users. A basic example of how this could be used is here: miek/inspectrum#195 miek/inspectrum#208 which is just a quick proof of concept for how this might look.

There is no expectation that applications support all features of this, and the "simple" usage where an optional presentation:color field is added to annotations allows for the features in the above link. A much more descriptive set of features, presentation_style objects, are available that can be used to describe recommended presentation of entire classes of annotations or captures segments without requiring individual specification.

I believe this should be in-tree so as to make these field names common across applications and encourage adoption and convention.

The current implementation is blocked by #146 but this can be changed to work without it.

[gmabey]

Did you consider also allowing strings from this well-defined set of color names? https://www.w3.org/TR/SVG11/types.html#ColorKeywords

[jacobagilbert]

I think this would be ver nice overall but I am not sure if this is burdensome on applications implementing this. Interestingly the merge request with inspectrum does support this (thanks to QT's native support for it).

Open to any thoughts here, especially situations this would be a problem.

[gmabey]

Another thought (I'm not strongly advocating this, but I do like it) is to separate the color and the alpha into two separate fields. That would eliminate the RGBA vs ARGB issue, and simultaneously allow for alpha-izing named colors.

Inasmuch as the .sigmf-meta files are supposed to be "human readable", and inasmuch as I still have a hard time visually decoding hex color strings, named colors would be ... more understandable.

[jacobagilbert]

human readability is a strongly beneficial reason to do this. Not sold on separate alpha but i see your use case...will think more. could be an optional that overrides AARRGGBB....

[bhilburn]

I'm in favor of this, and looks good. I'd say get it going, but deprecate your version to something < v1.0.0. Get feedback from @miek and others and target a v1.0.0 release with next SigMF minor release.

[bhilburn]

Deprecate the version

[gmabey]

That would be duplicate information, no? (Having alpha in 2 places) Also, a separate alpha field has a very natural default value of 1.

…

On Mon, Apr 11, 2022 at 12:15 PM Jacob Gilbert ***@***.***> wrote: ***@***.**** commented on this pull request. ------------------------------ In extensions/presentation.sigmf-ext.md <#234 (comment)>: > +application using this extension is not required to implement any particular +feature. It is RECOMMENDED that applications adhering to the `presentation` +extension use default values in this document. It is also RECOMMENDED that +applications implementing this extension describe what fields are implemented. + +## 0 Datatypes + +The `presentation` extension defines the following SigMF datatypes: + +|type|long-form name|description| +|----|--------------|-----------| +|`color`|Hexadecimal Color String|String representing a 24 bit color (with optional alpha value) in hexadecimal form; either "#RRGGBB" or "#AARRGGBB".| + +### 0.1 The `color` datatype + +The `color` datatype is a string which MUST be either 6 or 8 hexadecimal human readability is a strongly beneficial reason to do this. Not sold on separate alpha but i see your use case...will think more. could be an optional that overrides AARRGGBB.... — Reply to this email directly, view it on GitHub <#234 (comment)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABVTOUBC5DRHR3MPGZPAYJTVERT3DANCNFSM5ROCJGIQ> . You are receiving this because you commented.Message ID: ***@***.***>

[miek]

I've thought about this a bunch and, while I really like the idea of being able to encode some visual information, I worry that this implementation will lead to people creating recordings that only work well with their favourite tool/theme/colour-map. For example, I plan to add options for other colour maps to inspectrum at some point and presentation parameters for annotations created now could be unreadable on other colour maps.

I'd much rather see some way to encode intent rather than specific colours/styles, and then visualisation tools can interpret that in a way that works with their theme. Perhaps the naming scheme from standard logging levels could work, with fatal/error/warn/info/etc.? There could also be a way to define extra named groups, to group similar packets together for example.

[777arc]

I'd much rather see some way to encode intent rather than specific colours/styles, and then visualisation tools can interpret that in a way that works with their theme. Perhaps the naming scheme from standard logging levels could work, with fatal/error/warn/info/etc.? There could also be a way to define extra named groups, to group similar packets together for example.

Great point, although I would rather see integers starting at 0 than fatal/error/warn/info, that way we don't have to all agree what each code means, plus the RFML folks will love integers. And it solves the group problem. Would be nice to at least standardize on green and red, e.g. have 0 = green and 1 = red and then past that it's whatever the tooling thinks looks good?

Then there's the question of how do we support both options, because in the end it would seem weird to not allow specifying a specific color...

[jacobagilbert]

@miek Your input here is great, sorry I sat on this for so long. I'll definitely keep this in mind the next time I'm wondering why one of my inspectrum PRs hasn't been merged yet LOL!

I think your proposal makes a ton of sense and I'd like to figure out a way to capture that effectively. I have run into exactly the concern you raise repeatedly in my playing around with colored annotations in just the single default inspectrum colormap. Im wondering if we can identify a small set of features or annotation groups users would want to allow a tool to color. I think it needs to be a small enough set that its reasonable to find a set of annotation styles that coexist with a given colormap and are distinguishable.

I like taking inspiration from log levels, heres my first-pass take on this:

styles = {
  ALERT,    // should be visible immediately, regardless of the view settings of the dataset
  ERROR,    // should quickly draw attention and be styled in such a way to indicate a problem (e.g.: red)
  WARNING,  // upon inspection it should be obvious that this area may require additional inspection
  INFO,     // this is the standard annotation style
  DEBUG,    // this annotation is of lower importance than standard annotations
  USER_A,   //  \
  USER_B,   //  |
  USER_C,   //   > these styles should be visibly distinct but no relative importance is implied
  USER_D,   //  |
  USER_E    //  /
}

A number of questions:

1. Does 10 styles seem like a lot?
2. Should there be more user classes?
3. Should the ability to specify suggestions or explicit colors still be included?

---

Also, as an aside:

For example, I plan to add options for other colour maps to inspectrum

🙌 🙌 I like to hear this, viridis cant come soon enough :) - Tammojan's suggestion in 204 of using tinycolormap seems like a pretty easy way to get Parula, Heat, Jet, Turbo, Hot, Gray, Magma, Inferno, Plasma, Viridis, Cividis, Github, Cubehelix, and HSV for the cost of adding a drop down, removing Jet from that list and adding a little interface glue.