RawImage: document encodings in schemas

[james-rms]

Changelog

Docs

https://github.com/foxglove/docs/pull/628

Description

Documents our supported raw image encodings in (slightly more) detail.

Before	After

Fixes: FG-6974

[linear]

FG-6974 Explain RawImage encodings in docs

[james-rms]

Reviewers should probably start here.

[indirectlylit]

I tend to dislike putting so much formatted text into table cells because it tends to make formatting a bit janky, especially on smaller screens.

I could also imagine putting these in a table on their own rather than a bulleted list. Something like this:

Encoding	Field value	Description	Step size
8-bit YUV	yuv422	U and V values are shared between horizontal pairs of pixels. Each pair of output pixels is encoded as [U, Y1, V, Y2].	>= width * 2
8-bit RGB	rgb8	Each output pixel is encoded as [R, G, B]	>= width * 3
...	...	...	...

Suggested change

	Raw image data.
	Raw image data, encoded using the format specified by the `encoding` field. See below for a description of all supported encodings.

[james-rms]

I agree, but I'm not sure if I can bite that off right now. The original text starts in schemas.ts which goes through a generation step to be inserted into a table in the final markdown. I'd need to add a special case into the generation logic (here and in the schemas docusaurus plugin).

[defunctzombie]

8-bit meaning what?

[defunctzombie]

signed or unsigned?

[defunctzombie]

RGB is backwards here relative to bgr8, what does that mean? Also why does this say "one byte per component" whereas the other ones are 8-bit, is there some difference?

[defunctzombie]

Fascinating. How do we decode the values though? As a 16 bit unsigned number? signed? 16bit float?

[defunctzombie]

👍 seems like an improvement to me. There's a few more "ambiguities" that you could tighten up while you are here that I pointed out.

[james-rms]

heigh

[indirectlylit]

I tend to dislike putting so much formatted text into table cells because it tends to make formatting a bit janky, especially on smaller screens.

I could also imagine putting these in a table on their own rather than a bulleted list. Something like this:

Encoding	Field value	Description	Step size
8-bit YUV	yuv422	U and V values are shared between horizontal pairs of pixels. Each pair of output pixels is encoded as [U, Y1, V, Y2].	>= width * 2
8-bit RGB	rgb8	Each output pixel is encoded as [R, G, B]	>= width * 3
...	...	...	...

Suggested change

	Raw image data.
	Raw image data, encoded using the format specified by the `encoding` field. See below for a description of all supported encodings.

[indirectlylit]

Are these (and other similar pairs) synonyms? It's not clear to me why we have two field values with the same description.

[indirectlylit]

Suggested change

	The requirements for each `encoding` value are:
	The definitions for each `encoding` value are:

[indirectlylit]

nit: remove all unnecessary periods (anywhere you have only a single sentence or a fragment)

Material Design writing guidelines

Suggested change

	- `step` must be greater than or equal to `width` * 2.
	- `step` must be greater than or equal to `width` * 2

[jtbandes]

8UC3 is equivalent to bgr8, not bgra8

[jtbandes]

what order are these in? I'd probably order them either alphabetically, by bit depth/number of channels/etc., or by popularity

[jtbandes]

Suggested change

	- | -
	- + -

[jtbandes]

we don't specify the 0-255 range for other 8-bit formats -- intentional choice?

[jtbandes]

I don't know that we often refer to panel docs/settings inside schema comments, this might be the first time. Maybe we should leave it out and remove the language around "abstract values" / "brightness values"?

[jtbandes]

endianness?