Well actually … I’ve been pottering with the Snap! color system, and it turns out to be pretty complicated.
This post is yet to be completed - I accidentally posted it prematurely.
As a matter of fact I did read the manual (“when all else fails …” 
)
For clarity: By “Snap! color system” I mean:
- the variety of supported color definition mechanisms: RGB (hex), (fair) HSL, (fair) HSV, X11/W3C, crayons, color numbers, and the Snap! color data type;
- Snap! primitive functions within the Pen palette;
- Snap! libraries: “Crayons”, as well as “Colors and crayons”.
Now for my remark on The Snap! color system being complicated.
I’m aware the subject of color is inherently complicated, as proven by the long history of color theories (Color theory - Wikipedia), and as hinted on in the Snap! reference manual (rainbow vs. the human eye; screen vs. print; transparency; etc.). This isn’t something anyone can repair. One could even argue that many well-intended attempts to systemize this subject have only made it more complicated, as evidenced by the multitude of color definition systems (RGB, HSL, etc.).
Clearly the Snap! team have attempted to provide a rich set of tools for color-savvy advanced users, while not scaring away the rest of us. In my view the team are struggling with this dual goal.
A naive user (which in many respects I am) may easily be confused by the treatment of color in the manual.
-
very few functions within the Colors and crayons library, or even primitives within the Pen palette, come with (adequate) Help texts.
E.g.
Help doesn’t mention no pen trail is left when the sprite is moved manually by the user. The meaning of RGBA (especially the A) in 
is not explained. Blocks such as 
, 
, 
, 
, and 
come without any Help at all. -
even though the color type (apparently a costume of 1x1 pixel) is supposed to be “first class”, it doesn’t have a tick box in the block editor’s long input name dialog, and I haven’t figured out yet how e.g. the coloured input boxes in functions like
actually work, such that I could “build my own blocks” featuring color type input.
Oh dear.
The colors and crayons library is my doing, so all these problems with it are my fault. So is the inadequate help.
The lack of a color-picker input type is beyond the reach of a library. The built-in types haven't kept up with other developments in the language; for example, distinct type indicators for sprites, costumes, and sounds would (imho) be better than lumping them all under the Object type. Meanwhile, right now you can't make your own color-picker input slots; the way the library does it is by editing the XML file by hand. So this isn't a documentation failure; it's a deficiency in Snap! itself, and we'll eventually fix it.
But I think you're expecting too much from help screens. The idea of a help screen is to get you started with an unfamiliar block, not to say everything about it. I think it's especially unrealistic to expect help screens to tell you what a block doesn't do, as in your PEN DOWN example. But your example about RGBA is more plausible. It isn't our fault that out in the world the alpha value is called "tranparency" even though it's really a measure of opacity. That is, a value of 0 (the minimum value) means fully transparent (invisible), while 255 (the maximum value) means fully opaque. Meanwhile, our own scales have a more intuitive maximum value of 100, and when you specify transparency on that scale it really does measure transparency, i.e., 100 means fully transparent. So we need to document all that, and we do, in the manual. But I don't think we can tell that entire story on a help screen; if we try to make them encyclopedic, they won't satisfy their primary purpose of telling the user in 25 words or less what the block is about. The chart on the bottom part of the help screen is an attempt to clarify the different dimensions of color without words.
But the real problem with that particular help screen is that it hasn't been updated since Jens added the RGBA option. I've been reluctant to put a lot of effort into help screens right now because we have Deborah Servilla's implementation of help screens represented as editable text rather than as a single png, to make them more translatable to other (human) languages, almost ready to be deployed, so I'd rather make changes in the new format once it's in place.
But even when we redo the help screens, we'll probably give much less of an explanation of RGBA than you'd prefer. The main point about RGBA is that it's the representation used by modern display hardware, and we expose it to users so that certain operations on colors can be faster. So I don't think a help screen is the place to explain why hardware color representation is what it is. If you want to understand all the bells and whistles of color, you have to read the manual.
A more crucial version of this design issue in help texts is hyperblocks. We could add a dense paragraph to every Operators help screen explaining how the domain of those operarors are extended to include lists, but I'd rather leave that task to the manual, and note in the help screens the few primitive operations that aren't extended as hyperblocks.
CUT FROM and PASTE ON don't have help screens because I don't understand them well enough to write the documentation. :~( I think I'll have to make Jens or Jadga do it.
As you say, color theory is inherently hard. I spent a year trying to understand it before writing that library, but I am by no means an expert. Just this second it occurs to me that I should have made those portmanteaux input menus say "For experts" instead of "3D Color spaces." That would help a lot in terms of user expectations. And maybe put "color number" and "crayon" in boldface. :~)
@bh: thank you for replying. I see what you mean, even though I don’t agree with your limited ambition regarding online Help text (in my view consulting Help should suffice in about 95% of all use cases). I’m also aware that the Colors & Crayons library is a work in progress.
When you replied I was actually still in the process of refining and adding to my writing - which as I mentioned had accidentally been posted prematurely - meanwhile trying to structure my thoughts on the subject, and thinking of solutions to improve the user experience.
Below are few suggestions, I leave it up to you to judge if they are of use:
- Presuming you’re serious about creating a “low floor” for non-geeks you may want to consider promoting to Pen primitives the blocks that are currently in the Crayons library.
- Reversely, you may want to consider moving some of the now-primitive blocks to a library, notably: , , , , and possibly
, , and . - By the same token, move all complexity regarding colors, including discussion of the Colors & Crayons library, from the Reference Manual’s body to Appendix A.
- Reorganize the Colors & Crayons library such that less blocks are immediately visible in the Palette area: the current set of 65 or so blocks appears cluttered and, frankly, intimidating. Below are two implementation strategies:
- I have understood that it’s possible to hide blocks from the Palette area, e.g.
is used by blocks currently in the Crayons library, but is invisible when using only that library. My impression is that many blocks in the Colors & Crayons library are for internal use only; one of those - for some reason I can’t get a script pic - even has a Help text saying “don’t ask, for internal use only” : so why not hide all of those? - To me it looks like too many conversions are supported. Choose one color definition system as the internal standard, and only convert to and from that system from / to other systems (… and I encountered yet another system: CMYK).
- What does a block such as
do? No Help text available, and I don’t remember having read about it in the Reference Manual. - At least in the Reference Manual explain the data structure of the “color type”. In ch. VII par. H an example is presented of manipulating color attributes, which leads me to suspect color is a list of R, G, B and something else (opacity 0-100?), but why keep us guessing? unless you don’t want ordinary users to build their projects on knowledge of the implementation: in that case the aforementioned example should be removed from the manual, I suppose.
Now that you’re probably going to read this post anyway, I have a related question for you. Can you corroborate (or deny) the following suspicions?
- Stage size as specified in the Settings menu understates both width and height (in pixels) by 1. E.g. 480 x 360 means -240 <= x <= +240, so the number of colums is 240 (values: -240 .. 1) + 1 (0) + 240 (1 .. 240) = 481.
- If a position is specified as a non-integer, e.g.
, the pen behaves as if the (x-) position were 
. If so, is this generally the way non-integer position specifications are interpreted by Snap! ? - (not a suspicion really but a question:) Are non-integer pen sizes interpreted as truncated or rounded, or … ?
- (another question:) If e.g. pen size = 2, and x-position = 0, which pixels are going to be affected by a vertical pen movement? (assuming
, of course):
- only those for which x = 0?
- pixels with x ∈ (0, 1) or perhaps (-1, 0)?
- pixels with x = 0, for 100%; pixels with x ∈ ( -1, 1), with 50% opacity?
- or … ?
Thanks in advance!
By the way:
I just did, by copying and modifying an existing library block
i really don't think this is a good idea, these blocks are pretty basic functionality and wouldn't be hard to explain in the help text. even if someone is confused by them, it's nowhere near enough blocks that they should get overwhelmed. i can see some case for all the color blocks, but the 3 last blocks aren't confusing at all, and even if they were, pretty easy to just skip over. people learning snap would be confused by other blocks anyways.
it would get annoying very quickly to have to repeatedly add these blocks from a library, i'm also suspicious with the way snap is structured that would come with a performance impact (although that should be benchmarked)
looking at crayons in their current state, i think they're actually more confusing just because of the wording. what does it mean to "change crayon by 10"? pens don't use crayons, crayons aren't colors (they have them), and crayons aren't numbers.
with better wording i could see the crayons library making sense, but really it would give a similar effect to all the existing pen blocks to add help text.
So, the answer to many of your questions is "Jens decides on primitives; Brian decides what's in the library."
So, yeah, if it were up to me, I'd replace the primitive blocks with the (reimplemented in JS for speed) library blocks. But actually this thread is causing me to rethink that view, since you seem to find the library confusing rather than simplifying. Maybe I'd do some intermediate thing, e.g., in the primitive blocks, only offer color number, crayon, [fair] hue, [fair] saturation, [fair] lightness, opacity. A rule between the first three and the last three. Put the more complicated choices in a new version of the library, including conventional [non-faired] HSL scales. Perhaps even decide that changing the hue when lightness is 0 sets lightness to 50, to keep people out of the Black Hole.
The ability to hide custom blocks was invented just too late for the colors library, and indeed was largely motivated by it. All the blocks with pencils in their names are meant to be hidden. I haven't done it mainly because it's hard to develop code most of which is hidden. I was going to say, "we need a temporarily-unhide-all-hidden-blocks" mode toggle, but I realize that that can be done as a custom block so never mind.
The library is much, much too slow to be practical. I wish I understood why, and what to do about it. I've started working on a data-directed version of the main SET PEN block, and it helps a little, but not enough. If I were energetic instead of depressed, I'd try to rewrite the whole library in JS to see if it's somehow inherently slow, or only because the blocks are interpreted on top of an interpreter. This slowness barrier is really unmotivating; I feel like I've put all this effort into inventing a color system nobody will use.
(And, by the way, that answers the question about the Crayons library. It's the crayons feature of the color library, pulled out because otherwise it's too slow, and people were interested in having just that part as an option.)
That huge COLOR NUMBER IN block with seven inputs is an internal helper (starts with a pencil). It's a bit of a kludge. Mostly if you set the pen color in one coordinate system and want to read it back in an unrelated system (e.g., you set it by RGBA and ask for its crayon number) it errors. (If there is a bijection between the two systems (e.g. HSV and HSL) then you can convert.) But I decided, for some reason, that you should be able to find out the color number closest to the color you set in some different way, e.g., X11 name. But color numbers are only partly ordered, because both hue and lightness contribute to them, so the "algorithm" to convert to color numbers is kinda arbitrary and definitely too complex to explain. But that block is part of its implementation.
Actually I think I do remember the reason; I wanted to encourage people to move their projects into the color number scale by making it easy to find the closest match to some color their project uses.
About the internal representation of a color, I blush to think about it. It involves 21 global variables. Well, not as bad as that sounds, because 13 of them are really constants. But the other eight are part of a somewhat redundant color representation. Oh, sorry, in addition to the library variables there are the four hardware scales, so that's 12 pieces of the representation. The redundancy is partly to try to speed things up, but also because part of the color is what coordinate system it was defined in, and even that isn't straightforward because, e.g., FAIR? is a Boolean value factored out of the coordinate system.
PEN TRAILS, PASTE ON, and CUT FROM are orthogonal to the color scales. The others in the list would indeed be replaced by the Colors library blocks of the same name in my dream Snap!. There would be no need to have them in a library because the Colors blocks can do everything they can do.
Stage size: No, it means [-240, 239]. No extra pixels.
Non-integer values where integers are expected: All numbers are represented by Javascript as floats. So we're perfectly happy to have fractional positions, fractional hues, fractional pen sizes, etc., and only at the last minute, when interfacing to hardware, do we have to round. I'm pretty sure round (as opposed to floor or ceiling) is what we do, but I wouldn't swear to it.
Even pen sizes: I try to avoid them, so as not to have to think about this, but my guess is that it includes the next position up. Certainly 2 looks way thicker than 1.
Yes, but the way to make that be the case is to simplify the blocks so that a short description is adequate. This, I guess, is why the Scratch Team never adopted our ideas about first class functions. There's no 25-words-or-less explanation for grey rings, unless you already know and just need a reminder.
But no, you want to make the help be a complete explanation of the block to people who know... nothing about programming? Nothing about Snap!? Everything about Snap! except for this one block? Your position is pretty close to "nothing about Snap! " I guess if you know nothing about (for example) colors, you shouldn't expect to learn it all from the help screens. After a yearlong deep dive into Wikipedia, I still don't know all about colors! But, to take a more vanilla example, do you expect the help screen for MOVE n STEPS to explain what a sprite is, that they all move independently, unless of course they're nested, and they all have separate pens, and they're completely independent in their behavior, oh unless they're clones... Oh and that a "step" means the distance between pixels on your monitor, unless you have a 4K (Retina) monitor, in which case a step is two pixel spaces. And for that matter to explain the whole idea of turtle geometry, in which motion is relative to the sprite's own position and heading? And why one might prefer that to Cartesian graphics the way the grownups do it? (All the world's problems are due to grownups. Or at least all the problems with teaching and learning, which are due more specifically to kids wanting to do things as the grownups do.)
Yeah, all the "crayon" menu items should be "crayon number," but I didn't do that for two reasons: (1) It would make the menu wider, which is best avoided, and (2) I didn't want people to confuse it with "color number," which has to be called that because there's another option called just "color."
I'm sorry for you, wishing you all the best! Hope my comments didn't make it worse.
To me it sounds like you’ve bitten off more than you could / can chew.
Perhaps you and Jens should have a talk, and plan for an incremental redevelopment-from-scratch of colors etc., based on accumulated knowledge and insights … and why not involve the user community in establishing goals and principles, prioritizing features, and writing code? Meanwhile the existing primitives and libraries will still be available, so there is no time pressure.
As for the Help discussion: what I envision is that each primitive or library block features a Help text at least specifying each input variable and of course the result; and referencing to the manual for background information, where appropriate.
BTW post 34 and up within this topic are not at all about the original subject. Is there a more or less convenient way to move them to a new topic?
We want divergent things. Jens is into media computation and wants to be able to process hundreds of thousands of pixels very quickly, but not especially worried about the color details. For example, what will this picture look like if we exchange the red component and the blue component of each pixel.
Here the fact that it's visual makes it interesting, but the real curriculum is about arrays and (implicit) mapping of functions over pixels.
By contrast, what I'm after is Correct™ colors; I'm not really sure why this is where I've drawn my line in the sand, since I never really do graphics at all, more thinking about functions in the abstract. I suppose I'm intrigued by how absurdly complicated it is. I mean, colors are frequencies of light, right? And each frequency is a color? Should be trivial, right? But one of those frequencies is Yellow, and yet if you take the Red frequency and add the Green frequency, the result doesn't somehow become a single frequency; you can run the two lights through prisms, and one will give you a single spike at Yellow and the other will give you two spikes at Red and Green, but they look the same to our eyes. Isn't that strange? And if you work with beams of light, those two kinds of yellow behave the same when you mix them with other colors, but if it's two kinds of yellow paint they're totally different. Gives me a headache. I'm still not 100% confident that my color model is even slightly correct. And then instead of liking green like a sensible color modeler, I like orange and brown, so I end up tilting at windmills by inventing a hue scale that's different from the rainbow one. I could have gotten away with just spreading out orange and compressing green to make it fit, but deciding to make brown available as a pseudo-spectral color as well as a shade of orange, so the correspondance between regular HSL and fair HSL isn't a bijection, which explains that complicated helper block you asked about...
I really got interested in the Scratch color space because of getting trapped in the Black Hole like a lot of other Scratch newbies, which gave me the insight that it's very misleading using the name "color" to mean hue, and from there, thinking that it'd be good to have a one-dimensional color scale that would include Black and White and all the rainbow colors.
Anyway, the point is, this is the sort of reasoning that Jens really does not want to determine what gets built into Snap!. He's happy for me to build it all into a library, to be used by experts. But it's not experts who need a one-dimensional Color number space with black and white (and greyscale) but no Black Hole. It's newbies who need that, and so they need at least color numbers as primitive. But my color numbers are incompatible with how other people in general, and Scratch in particular, think about colors.
TL;DR: Jens and I think too differently, and who knows how users think, about this. Probably once you teach them how to get a color other than black, most users never think twice about colors. Sigh.
Yeah. That's what we all want. Except that you seemed to be asking for something quite different in the example about how dragging a sprite by hand doesn't leave a pen trail.
Done.
@bh: Thanks for moving the relevant posts to this new topic!
is a command; the result of this command is that any subsequent sprite movements will leave a pen trail ... except when done by user's hand. (I'm not saying this omission is a big deal per se; it was merely one example of not-so-comprehensive Help text in the Pen department. If you're interested I could make a few suggestions for Help text additions).
Returning to the Colors & Crayons library - let's assume for now the primitives remain as they are, all the more since you don't want to argue with Jens about it (BTW I’m impressed with the power and speed of the primitives, including those in the Looks and Sensing palettes, e.g. 200 graphics effects per millisecond on a 480x360 background, on my 5 year old garden variety device ... wow!) (and for something completely different: I'm not sure what you mean by "getting trapped in the Black Hole").
Perhaps the scope of the C&C library is too narrow - how about expanding it to Graphics? The question then is: what would users (students, others) want to do with graphics (including colors) that is not conveniently supported by current primitives?
Here's some ideas (from what I, personally, would like to be supported in doing):
- Apply line patterns (dotted, dashed, stars, etc.) (+ arrowheads?);
- Draw basic figures such as: (of course) line, triangle, rectangle, pentagon, hexagon ... (regular / arbitary polygons), ellipse / circle; with/-out contrasting perimeter;
- Draw freehand;
- Draw with a different tool, like a felt marker (rectangular head / end, and possibly somewhat sketchy), or perhaps aquarel style (implementing time-dependent ink flow: this is just a fantasy of my own
); - Create buttons with icons;
- Draw geometric patterns such as hatching, and project them onto an area;
- Apply graphic effects preferably not as a command (~ Looks palette) but as a reporter;
- Apply perspective (2½-D, or would that easliy become too complicated ? may be a later increment);
- Perhaps some support for AI, especially image analysis, and face recognition: conversions to RG chromaticity space and TSL color space, respectively (source: Wikipedia).
The crayons, in my opinion, are a really neat feature for beginners and experienced users alike; I'm not sure though about the color numbers: being offered both crayons (1-100) AND color numbers (1-100) I find slightly confusing.
Ideally color model conversions are HOF's implemented in Javascript, as they're relatively slow now, at least when applied at a substantial picture (I guess this is what you hinted at). However I suppose not all of the presently supported color model combinations need this level of performance (e.g. I can't think of an application where a user would be in haste to convert tons of HSL-bitmaps to HSV).
Finally I propose a pair of mutual recursive functions to be included in the library, plus a lambda function with undecidable halt condition. Just so as to make it interesting to you.
polygons sounds pretty standard for a library, but so simple that i feel like a library doesn't really need them. i think library features are generally about showing new ideas or complex things, not just getting around a quick puzzle.
the others are just very vague, for example "image analysis" means pretty much anything
different pen tools/brushes and line patterns are great ideas, but they would require in-depth changes to the snap code since the line drawing happens when the sprite moves, not when the pen blocks are used. arrowheads seem too difficult to get right in a way that wouldn't be confusing or limiting, since it's not always clear where a line ends. i think that should be left out if this is done.
Haha, you want me to write Photoshop!
Seriously, even just dealing with color space, this library already has a kind of tail-wagging-the-dog feel to it. If I added all of computer graphics to it, it'd take an hour to load. Given that navigating in color space is a separable chunk, you can put all that other stuff in another library. And anyway, I'm not competent to write all that; I never took a graphics course. I'm already in over my head just with colors.
If I'm going to put a lot of time into the library, it'd be much more productive, imho, to put all my effort into speeding it up. That'll be hard enough.
The problem with this is you don't need to do that, because this is a development environment, so instead of having those native, it should be up to the user to solve that problem themselves, and given the power of snap, that isn't even that hard. I mean it's pretty hard, but it is solvable. (Well....)
That just tails back towards the help section because the problem is always you want to expose the user to a whole heap of things they can do but not outright do it for them.
Which the dev team are acutely aware of, as demonstrated by the conversation about colour.
We want divergent things. Jens is into media computation and wants to be able to process hundreds of thousands of pixels very quickly, but not especially worried about the color details. For example, what will this picture look like if we exchange the red component and the blue component of each pixel.
Here the fact that it's visual makes it interesting, but the real curriculum is about arrays and (implicit) mapping of functions over pixels.
By contrast, what I'm after is Correct™ colors; I'm not really sure why this is where I've drawn my line in the sand, since I never really do graphics at all'
For me, that's not divergent, for me that's the same goal from different starting points.
Jens is teaching arrays using colour theory and you're then going "If you want to explore that more, here are your options" and there are a lot of options.
(and for something completely different: I'm not sure what you mean by "getting trapped in the Black Hole").
What he means by this is that if you aren't careful, no matter what colour you want, you end up with black. Even if you are careful tbh.
Right, I forgot to answer this part. Since black isn't a spectral color, if you choose it in the color picker or you're just starting off and the pen is black by default, you're in the Black Hole. So in HSV you have any hue (probably 0 for red), saturation 100, value/brightness 0. V=0 is what makes it black. Now you say "change hue by 10." (It used to be even worse, because that block was called "change color by.") Nothing happens, because V is still 0. No matter how much you change the hue, the pen stays black. That's the Black Hole: once you fall in, you can't escape. (Of course, since we got settable S and V, you can if you're a color expert and know to say "set brightness to 100." And you have to figure out that "brightness" means V.)
+1
...............
That was not my intention, even if it's probably quite feasible to build a set of functions in Snap! that will do most of what commercial graphics software is used for most of the time. And you're probably right about separating graphics from a colors. Still I believe a graphics library will add value to the Snap!
Besides I did not imply that it had would have to be you doing all the work. I'd be happy to make a start, and others might be interested to join.
Awesome! Go for it.
I want to help a little bit, specifically with different pen styles. I can also help you with getting this built into Snap!
Also, we need to keep the blocks at least a little user-friendly, so the average user can quickly figure out what a block does.