RE: color.el

[Drew Adams]

> Thanks.  I'll start applying some parts of the patch shortly, but here
> are a few points worth discussing:
> 
> 1. Renaming color-rgb->hsv to color-rgb-to-hsv, etc.
> 
>    The latter is a bit more in line with other Emacs Lisp function
>    names, though we do have a few named "X->Y".
> 
>    Any thoughts from Emacs developers?  I am not sure myself.

I applied the renamings for the following reasons, but you can choose whatever
names you like:

a. There is already another function `color-rgb-to-hsv', in `facemenu.el'.  As I
said, I did not send a patch for `facemenu.el'.  Presumably that function as
well as `read-color' would be removed from `facemenu.el' in favor of those
functions in `color.el'.  (You might also consider moving `list-colors-display'
to `color.el'.)

b. There was one of the *->* functions that was not in fact a *-to-* function:
`color-rgb->normalize'.  IOW, it probably should not have followed the same
naming convention.  I renamed it to `color-rgb-normalize', not to
`color-rgb-to-normalize'.  (When the name includes *-to-* it is arguably easier
to see it as a conversion function.)

c. The hexrgb.el functions that were merged follow the *-to-* naming convention.

d. Only two more characters are needed for *-to-* than for *->*, and the former
is more readable, IMO - clear to anyone without wondering what the meaning of ->
might be.

e. There are many, many *-to-* functions in Emacs, and many (most?) of them
represent conversions of some kind.  On the other hand, the only *->* functions
in Emacs are the internal functions `compilation--*->*' and
`completion-pcm--pattern->regex', in all of which I think the `->' represents
essentially field selection, not format or data conversion.

Yes, those are all relatively minor reasons, but they are the reasons behind the
names used. 

> 2. Returning HUE in [0,1], rather than radians, by default.
> 
>    If we do this, I'd rather not add a separate *-radians function; we
>    should just decide on whether Emacs should represent hue 
>    as [0,1], as radians, or as [0,360], and use that everywhere.

The code I sent does not use [0,360] or radians.  It uses decimal [0,1] for hue
just as for all the other color components (red, green, blue, saturation,
value).  It uses the same units and ranges for component inputs and outputs, as
well as for all component types.

In practice, both [0,360] and [0,1] are common representations for hue,
depending somewhat on the emphasis wrt use.  But [0,255] is also common for RGB
- and even for HSV.  [0,360] is not used for any component other than hue,
AFAIK.

I don't see a problem with having two different functions that return these two
kinds of values, for that reason: convenience for different uses.

I have used the `hexrgb.el' version of RGB-to-HSV for a long time and find that
it handles corner cases well.  I can't vouch for the radians version provided.
That function is not used in the rest of the `color.el' code - I don't know if
it has been used in any Emacs code yet.

(Note: I meant to also add a FIXME/TODO? comment for that radians version: the
acceptable input RGB values need to be described.  They are apparently [0,255],
not [0,1].)

In my own use I've found using decimal numbers for all components, and for both
input and output values, to be convenient.  Same kind of number, same range
[0,1], for everything.  Simple.

That is easily interpreted by users (e.g. as percentages), easily incremented
etc. in the same way over and over, and so on.  That's to be contrasted with
sometimes using [0,255] for RGB input; sometimes using [0,1] for RGB input;
using [0,1] for S and V; and using [0,360] for H.

And you will notice that no conversions have yet been provided by the
`color-lab.el' code for radian HSV or HSL to RGB (see the FIXME/TODO? comments I
added for that).  Which RGB units and range would be used for the output of such
functions - [0,1] or [0,255]?

The interpretation of hue as an angle around a color cone or color wheel is fine
for explaining things but is not always so useful in practice (e.g. GUI's).

Look, for instance, at these typical color editors from the Wikipedia page
describing HSV and HSL:
http://en.wikipedia.org/wiki/File:Hsl-hsv-colorpickers.svg.  Even though the
explanation of hue that accompanies that illustration (on the HSV/HSL page)
shows a color cone to introduce the concepts, this illustration indicates that
in practice GUIs often use the same unit and range for all HSV components.

As another commonly used example, see the attached screenshot of the color
editor used in MS Word - it uses [0,255] for each component, for both RGB and
HSL.  (On the other hand, both Gimp and Photoshop use [0,360] for hue.)

>    For what it's worth, the Gimp, the Java color library, and the
>    Eclipse API all use [0,360].  Maybe we should do follow suit.  Any
>    objections?

I would object, but perhaps that doesn't count. ;-)  IMO, Occam's razor argues
for using the same units and ranges for all components and for both input and
output.

Unless a user is really thinking in terms of a color cone or color wheel, there
is little reason to employ 0-360 or radians, IMO.  Percentage is sensible enough
to users.  (That's so even though it is true that 0% hue = 100% hue - just as 0
deg = 360 deg and 0 rad = 2 pi rad.)

And using the same units and ranges for input and output facilitates iteration
and chaining.

> 3. The functions for incrementing color components don't look very
>    useful to me.  Surely it's simple enough for a Lisp program to
>    increment a member of a list.  Is there any real world example of a
>    program using this part of hexrgb?

The input and output are both RGB triplets, so you can apply the functions
iteratively.  Since such string triplets are used directly by Emacs for faces
and frame parameter values, you can iteratively adjust those values directly.
Staying within RGB triplets is quite handy, including wrt wraparound (F->0,
0->F) and wrt feedback for users.

I use those increment functions in `doremi-frm.el' for defining commands that
repeatedly increment various color components of different objects (faces, frame
fg/bg).

For example, command `doremi-face-fg+' lets a user incrementally change the
foreground color of a given face - s?he can switch the color component
(r,g,b,h,s,v) to be incremented at any time, and s?he can change the increment
size at any time.

There are other, similar such Do Re Mi commands.  Those command definitions
build on other `doremi-frm.el' functions, which in turn build on the
`hexrgb-increment-*' functions.
http://www.emacswiki.org/emacs/doremi-frm.el

throw-MS-Word-color-editor.PNG
Description: PNG image