Documentation for Convert*()'s "matrix" parameter

[shae]

The documentation for Convert*() is misleading. Currently it says (among other things):

matrix: Default unspecified. Controls the colour coefficients
and scaling factors used in RGB - YUV conversions.

unspecified : Use Rec.601 coefficients, scaled to TV range [16,235].
"PC.601" : Use Rec.601 coefficients, keep full range [0,255].
"Rec709" : Use Rec.709 coefficients, scaled to TV range.
"PC.709" : Use Rec.709 coefficients, keep full range.

I think the following is clearer:

matrix: Default Rec601. Controls the colour coefficients
and scaling factors used in RGB - YUV conversions.

"Rec601" : Use Rec.601 coefficients in TV range [Y 16-235, UV 16-240].
"PC.601" : Use Rec.601 coefficients in full range [YUV 0-255].
"Rec709" : Use Rec.709 coefficients in TV range.
"PC.709" : Use Rec.709 coefficients in full range.

What do you think?

Edit: Specifying matrix="rec601" isn't currently valid, but the main point was clarifying the YUV range.

[Wilbert]

Specifying matrix="rec601" isn't currently valid
It's valid in v2.57.

but the main point was clarifying the YUV range.
Ok, i will add that.

[shae]

Just noticed what I said might be unclear. :)

By "clarifying the YUV range" I didn't mean -235 vs -240, but the use of the words "scaled to TV range" and "keep full range". I understood exactly the opposite of what it does; usually scaling and PC range suggest to me extending TV YUV to 0-255 and keep suggests the opposite.

It's valid in v2.57.
Oh. I'm still with 2.56. Before writing that I wondered if 2.57 might've changed that, but I wrongly assumed it didn't.

[Wilbert]

By "clarifying the YUV range" I didn't mean -235 vs -240, but the use of the words "scaled to TV range" and "keep full range". I understood exactly the opposite of what it does; usually scaling and PC range suggest to me extending TV YUV to 0-255 and keep suggests the opposite.
If your source is RGB [0,255], you can't extend to YCbCr [0,255].

Scaling means scaling. Thus Rec601 means the following:

RGB [0,255] <-> YCbYCr [16,235].

For PC.601 there is no scaling:

RGB [0,255] <-> YCbYCr [0,255].