yaq-yeps/311


has-mapping

YEP:311
Title:has-mapping
Authors:Blaise Thompson
Status:draft
Tags:trait
Post-History:2020-10-29

Abstract

This YEP defines the concept of "mapping" arrays. These arrays add additional "context" to the channel arrays defined by is-sensor (YEP-302). For example, a mapping might describe which wavelength of light falls upon each pixel of a spectrometer array detector.

Table of Contents

Motivation

Certain sensors contain important information beyond their raw values. Consider an array-sensor within an optical spectrometer. Such an array detector could be implemented according to the is-sensor trait (YEP-302), with a channel for the measured light intensity at each pixel. To use this information, however, clients must also know the relationship between pixel index and light wavelength: the "mapping" of the array detector. This YEP defines a trait which allows daemons to expose mapping information over a consistent interface.

Specification

This trait requires is-sensor (YEP-302).

This trait implements mappings as a collection of arrays completely separate from channels. The principle feature of this trait is the new message get_mappings.

message: get_channel_mappings

response: {"type": "map", "values": {"type": "array", "items": "string"}}

Keys being channel names. Values array of keys from get_mappings. Can be many mappings per channel, or no mappings for a given channel (empty array).

Mappings must have the same dimensionality as their associated channel. Do not need to be the same size. They must broadcast into their associated channel.

message: get_mapping_id

response: int

Mapping ID. This integer increments every time the mapping is updated. Clients can safely check this id to verify that their cached mappings are correct, if desired.

message: get_mapping_units

response: {"type": "map", "values": ["null", "string"]}

Must return units for every mapping. Units can be null.

message: get_mappings

response: {"type": "map", "values": ["double", "ndarray", "int"]}

Keys used in get_channel_mappings

Rejected Ideas

At one point in yaq development, mappings were included simply as additional channels. While elegantly simple, this idea proved insufficient.

Discussion

Discussion can be found on the gitlab issue for this YEP.

Copyright

This document is placed in the public domain or under the CC0-1.0-Universal license, whichever is more permissive.


built 2021-10-21 19:15:50                                      CC0: no copyright