New API doc - typos and questions

thomthom · 9 Nov 2009, 11:21

Edge.reversed_in?
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/edge.html#reversed_in?
The reversed_in? method is used to determine if the EdgeUse object is traversed in the corresponding direction as its corresponding edge.

Apart from the EdgeUse typo - what does the method really do. I don't understand at all from the description what it does.

TIG · 10 Nov 2009, 10:12

@thomthom said:

Edge.reversed_in?
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/edge.html#reversed_in?
The reversed_in? method is used to determine if the EdgeUse object is traversed in the corresponding direction as its corresponding edge.

Apart from the EdgeUse typo - what does the method really do. I don't understand at all from the description what it does.

I use it in my 'orient faces' method - although I agree that it all seems pretty arcane and badly explained. If an edge is reversed in a face it is going contrary to that face's logical loop direction. If you test an edge belonging to a selected face and that edge has that face face plus another one that both return as being either reversed or not-reversed then you know that this other face has the same 'orientation' as the selected face: if the other face has the opposite 'reversed-ness' to the selected face then it needs to be flipped over (reversed) so it orients the same way as the selected face...

thomthom · 10 Nov 2009, 11:01

There's a logical orientation of the loops?

TIG · 10 Nov 2009, 11:33

@thomthom said:

There's a logical orientation of the loops?

If you get a set of vertices for a face's loop it's always listed as an ordered array: it will be rotating 'counter-clockwise' to the face's normal if it's an external loop, or 'clockwise' if it's an internal loop... If an edge's start/end vertices break this 'rule' I think it's said to be 'reversed in the face' ? That is the order of the edge's vertices don't follow the loops 'handed-ness' so are flagged thus...

jarl · 10 Nov 2009, 12:06

@unknownuser said:

Your help in finding typos/missing details are very welcome!

On http://code.google.com/intl/da/apis/sketchup/docs/ourdoc/point3d.html#+ it says that the argument is a Point3d, but it should say a Vector3d.

Jarl

thomthom · 10 Nov 2009, 12:28

Geom;;Point3d.new(10,10,10) + Geom;;Point3d.new(20,20,20)
Error; #<ArgumentError; (eval);261;in `+'; Cannot convert argument to Sketchup;;Vector3d>
(eval);261

TIG · 10 Nov 2009, 14:18

@jarl said:

@unknownuser said:

Your help in finding typos/missing details are very welcome!

On http://code.google.com/intl/da/apis/sketchup/docs/ourdoc/point3d.html#+ it says that the argument is a Point3d, but it should say a Vector3d.

Jarl

If you add two pointstogether it returns a vector (or another point if it's taken as an array) ?

thomthom · 18 Nov 2009, 10:12

Color
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/color.html

When creating a Color object you can specify an alpha value. Not mentioned in the examples.

Color.new
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/color.html#new
The way the arguments are presented now it looks like they are all equal, but it's actually wither RGB(A) values or a String. It also takes Hex, array with Integers or Floats.

Oddly enough, you can do: Sketchup::Color.new(128) and get a Red-ish color. But not Sketchup::Color.new(128, 255) - where it will throw an error saying at least 3 values are required. So if you can specify 1, 3 or 4 values for the RGBA combination.

TIG · 18 Nov 2009, 11:08

But the Color's Alpha value is always ignored anyway ?
Whereas Alpha value for the material is used !

thomthom · 18 Nov 2009, 11:22

@tig said:

But the Color's Alpha value is always ignored anyway ?
Whereas Alpha value for the material is used !

Yea, that's what I've noticed as well. Confusing. Should be mentioned in the docs. I had hoped that the alpha channel would be used the the view.draw2d method, but alas - it does not. Wondering if it's by design or if it's a bug.

TIG · 18 Nov 2009, 13:48

I guess it was perhaps an early implementation when perhaps Color and Material were the same thing ?
Also I suppose it allows you to import a RGBA value from elsewhere directly into a Color, but then using the first 3 items in the array is no hardship ???
Seems that the alpha could be removed as it's not needed/useful ?

thomthom · 18 Nov 2009, 13:51

I'd rather see view.drawingcolor= make use of the alpha channel and let us draw transparent objects to the viewport.

thomthom · 18 Nov 2009, 17:00

@tig said:

That would be much more use... unfortunately with drawaren't we limited to the built-in color-set, and that has no transparency setting ?

draw is currently bugged an only draws black fill.
draw2d works, and you can specify any Color object (or hex,int,float,array that equal to a colour) but it ignores the alpha.

TIG · 18 Nov 2009, 17:03

@thomthom said:

I'd rather see view.drawingcolor= make use of the alpha channel and let us draw transparent objects to the viewport.

That would be much more use... unfortunately with draw aren't we limited to the built-in color-set, and that has no transparency setting ?
Transparency ispossible with OpenGL but not as I can seem in it's port to Ruby and SUp ???

Dan Rathbun · 20 Nov 2009, 08:01

COLOR ...by the way...FYI

Another Color Table with much more info then the one on the SU API Color page, is at
MSDN Samples - Dynamic Color Reference

It's a DHTML sample page... takes awhile to load (and I have broadband.) Once loaded you can sort the table by any column, by clicking it.

thomthom · 20 Nov 2009, 08:25

@dan rathbun said:

ANY numeric input is bugged, no matter Fixnum or Hex or Octal.


> c1 = Sketchup;;Color.new( 255 )
> Color(255,   0,   0, 255)
> # You'd expect (0,0,255,255) ...but
>

Why are you expecting a ble value from that? Getting a Red colour is what I'd expect, going left to right in RGB.

@dan rathbun said:


> c2 = Sketchup;;Color.new( 256 )
> Color(  0,   1,   0, 255)
> # that's just plain weird!
>

Ah! They treat a single int as a full colour code. Used to do this stuff in VB apps that used long ints for colours.


c = 256
r = c & 0xFF
g = (c & 0xFF00) / 0x100
b = (c & 0xFF0000) / 0x10000

Results in RGB 0, 1, 0

thomthom · 20 Nov 2009, 08:42

@dan rathbun said:

c3 = Sketchup;;Color.new("darkorchid")
> Color(153,  50, 204, 255)
> # all OK so far, lets get the integer output...
> c3.to_i
> 13382297
> # is that right?
>

c = 13382297
13382297
r = c % 256
153
g = (c / 256) % 256
50
b = (c & 0xFF0000) / 0x10000
204

Seems right.

@dan rathbun said:

Let's see what Ruby says...
"0x9932CC".hex
10040012

You get the int by first extracting the rgb components, then: int = b * 65536 + g * 256 + r
So in this case:
0xCC * 65536 + 0x32 * 256 + 0x99 = 13382297

Dan Rathbun · 21 Nov 2009, 06:43

@thomthom said:

@dan rathbun said:


> > c1 = Sketchup;;Color.new( 255 )
> > Color(255,   0,   0, 255)
> > # You'd expect (0,0,255,255) ...but
> >

Ah! They treat a single int as a full colour code. Used to do this stuff in VB apps that used long ints for colours.
YES.. a single arg is 'read' as either a ColorNameString or a 32bitColorInteger (not read as a 8bitColorComponentByte, unless 3 or 4 args are given.)

@thomthom said:

Why are you expecting a blue value from that? Getting a Red colour is what I'd expect, going left to right in RGB...
Because I was thinking of the 'newer' way of representing colors in binary (in which the blue is the lowest order byte); and you are refering to the 'older' way (in which the red is the lowest order byte.)
So both of us are both wrong and correct at the same time.

@thomthom said:

You get the int by first extracting the rgb components, then:...
Actually I was using bit shifting, it's easier for me to understand, makes for a compact looking method, and is supposed to be much faster on 32 bit architecture.

The truth (after several hours of research,) is that the whole story is more complex. The binary [integer] format AND the array [component] format for colors depends on platform, specification (ie things changed over time,) and what graphics library is in use by the color.

The 'old' way you remember is the RGB format, which was a 24bit integer, and had the red as the low-order byte; the blue as the high (3rd) byte. The math you describe will work for this... see previous post, refering to VB coding days.

Then came Win32. Colors were expressed as 32bit integers, but the industry could not agree on what the extra 4th byte was to be used for. Win32 was released with the 'old' GDI library using the COLOREF structure; it was the same as the 24bit RGB but the 4th byte was labeled 'Reserved' and had to be set to 00 if specified. (I think it defaulted to 00 as well.)

Later, came, the GDI+ library and .NET; and by that time the alpha camp won out, and the 4th byte became the 'aplha channel.' BUT... they changed the format to ARGB format:
[C from WinowsSDK::GdiPlusColor.h:beginline 288]

// Shift count and bit mask for A, R, G, B components
    
    enum
    {
        AlphaShift  = 24,
        RedShift    = 16,
        GreenShift  = 8,
        BlueShift   = 0
    };

    enum
    {
        AlphaMask   = 0xff000000,
        RedMask     = 0x00ff0000,
        GreenMask   = 0x0000ff00,
        BlueMask    = 0x000000ff
    };

// Assemble A, R, G, B values into a 32-bit integer
    
    static ARGB MakeARGB(IN BYTE a,
                         IN BYTE r,
                         IN BYTE g,
                         IN BYTE b)
    {
        return (((ARGB) (b) <<  BlueShift) |
                ((ARGB) (g) << GreenShift) |
                ((ARGB) (r) <<   RedShift) |
                ((ARGB) (a) << AlphaShift));
    }

Also take note, that HTML/CSS colors conform to ARGB.

However... when Microsoft, and the W3C switched to ARGB.. others did not.

OpenGL went with the RGBA format, and did not swap the red and blue, just added the alpha as the 4th byte above the blue, as in the original RGB ( or as in the 'old' GDI 32bit COLORREF with the alpha occuping the 'Reserved' 4th byte.)

So why am I worrying about this?
Well, I was 'mixing-in' the standard ruby library Comparble, so Sketchup::Color class objects could be compared to one another, and other objects, ie: integers and arrays that a coder might create for comparison sake. The simplest comparison is at the integer level, and it seemed to me that there was a math bug in the SU Color class.

So.. it turns out there is NO correct color integer, NOR color array, but instead 4 versions (editions) of each! ( RGB, RGB0, RGBA and ARGB ) The 1st being 24bit/3 element array; the following 3 being 32bit/4 element arrays.


Form  ArrayFmt   HexInteger   Used by;
RGB   [r,g,b]      0xbbggrr   Win16
RGB0  [r,g,b,0]  0x00bbggrr   Win32, GDI
RGBA  [r,g,b,a]  0xaabbggrr   OpenGL
ARGB  [a,r,g,b]  0xaarrggbb   Win32, GDI+,.NET, HTML/CSS
Form  bits  (MSB)--Binary Representation--(LSB)
RGB    24            bbbbbbbb gggggggg rrrrrrrr
RGB0   32   00000000 bbbbbbbb gggggggg rrrrrrrr
RGBA   32   aaaaaaaa bbbbbbbb gggggggg rrrrrrrr
ARGB   32   aaaaaaaa rrrrrrrr gggggggg bbbbbbbb

This greatly complicates implementing comparison, which may be why it was not done in the first place.

Also.. the idea of whether one color is greater or less than another, depends upon your viewpoint. If you like to think of color as having 'frequency magnitude', where red have lower freqs, and blue have higher freqs, than direct comparison of RGBA integers will work for you. On the other hand, most people (scientisits) refer to colors as having 'wavelength magnitude' where the blues have shorter wavelengths, and the colors have longer and longer wavelengths as you appraoch the red. So in the 2nd case you might prefer the ARGB; but a comparison of RGBA integers would give you an opposite result.

Oh.. we might think why not use a to_hash method and then the comparisons would be able to match up the rgba keys, but to complicate things further there are different types for the values: byteinteger, float 0.0-1.0, percent 0-100%.
It's looking like it's more trouble than it's worth.

Dan Rathbun · 21 Nov 2009, 07:07

@jim said:

Sketchup::Color.new

new can accept a hex value (not string) as the parameter: for example 0xFF0000 (undocumented)

But, it reverses the red and blue values. Here is a Console session. (bug)


> Sketchup;;Color.new 0xFF0000
> Color(  0,   0, 255, 255)
> Sketchup;;Color.new 0x0000FF
> Color(255,   0,   0, 255)
>

ANY numeric input is bugged, no matter Fixnum or Hex or Octal. NOT TRUE... see my next post
[Console Sesion]


c1 = Sketchup;;Color.new( 255 )
Color(255,   0,   0, 255)
# You'd expect (0,0,255,255) ...but
c2 = Sketchup;;Color.new( 256 )
Color(  0,   1,   0, 255)
# that's just plain weird!

The color "DarkOrchid" = Hex:#9932CC RGB: 153,50,204
Using the ColorName all seems to go well on "new"
[Console Sesion]


c3 = Sketchup;;Color.new("darkorchid")
Color(153,  50, 204, 255)
# all OK so far, lets get the integer output...
c3.to_i
13382297
# is that right? Let's see what Ruby says...
"0x9932CC".hex
10040012
# so the .to_i ouput is NOT correct.. 
#### UPDATE; Ruby returns the correct integer for an ARGB string, ####
####  but not the correct integer for an RGBA color, which OpenGL uses.  ####
# ... but what is integer 13382297 for?
#### UPDATE; it's for the RGBA color "DarkOrchid"
#### see the next 2 posts.
"0xCC3299".hex
13382297
# it's for RGB;(204, 50, 153) NOT (153, 50, 204)

So.. Sketchup::Color.to_i has the same bug. NOT TRUE... see my next post.
I'm working on aColor Mixin for the SKX project that ... needs more work.

thomthom · 21 Nov 2009, 10:24

sheeeesh! No wonder it was all confusing.