New API doc - typos and questions

thomthom

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

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

thomthom

@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

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

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

thomthom

@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

@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

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

@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

@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

@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

@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

sheeeesh! No wonder it was all confusing.

Dan Rathbun

A TEMPORARY fix for dealing with the differing formats of color integers.

Adds 4 methods to Integer (and subclasses Bignum and Fixnum.)

Get it in the main Ruby Discussion forum, thread:
[Ruby Extension] for Sketchup color integers

thomthom

PickHelper.path_at
PickHelper.depth_at
PickHelper.path_at
PickHelper.transformation_at
All these are described as index 1 being the root element. But that's not in my experience. I was using PickHelper.path_at and PickHelper.transformation_at for one of my scripts where I was drilling down through groups/components. When using PickHelper.transformation_at(1) to get the global positions I would get nil half the time. PickHelper.transformation_at(0) worked instead.

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

thomthom

PolygonMesh.uv_at
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/polygonmesh.html#uv_at
There are two arguments:
PolygonMesh.uv_at(int_index, bool_front)

PolygonMesh.uvs
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/polygonmesh.html#uvs
This requires a boolean value as argument.
true returns front UV data set.
false returns back data set.

thomthom

PolygonMesh.add_polygon
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/polygonmesh.html#add_polygon

I can't seem to add points like the example does.

Instead, I must first add each point using PolygonMesh.add_point and then provide PolygonMesh.add_polygon with index values that refers to the points.

In general this PolygonMesh seem to have many errors in the description of the methods, arguments and usage. Recommend a closer revising of this section.

thomthom

Entities.fill_from_mesh
http://code.google.com/apis/sketchup/docs/ourdoc/entities.html#fill_from_mesh

smooth_flags does not default to 0. Seems to default to 12 (soft and smooth)
weld_vertices - what does this really do? I can't see any difference in the resulting geometry.

thomthom

Entities.add_faces_from_mesh
http://code.google.com/apis/sketchup/docs/ourdoc/entities.html#add_faces_from_mesh

@unknownuser said:

Returns:
faces
an array of Face objects if successful

In my tests it returns 0 - not an array.

cjthompson

@thomthom said:

PolygonMesh.add_polygon
http://code.google.com/intl/nb/apis/sketchup/docs/ourdoc/polygonmesh.html#add_polygon

I can't seem to add points like the example does.

Instead, I must first add each point using PolygonMesh.add_point and then provide PolygonMesh.add_polygon with index values that refers to the points.

That's weird. It works just fine for me.