New API doc - typos and questions

Dan Rathbun

@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.

Error 404 (Not Found)!!1

(code.google.com)

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.

thomthom

Can you post a quick example?

thomthom

Ah! That's what I tried. Using a normal Array as substitute of Point3D. How odd that this method suddenly don't let you interchange arrays and Point3Ds...

cjthompson

now I see why it doesn't work with arrays:


mesh = Geom;;PolygonMesh.new
mesh.add_point([0,0,0])
mesh.add_point([1,0,0])
mesh.add_point([1,1,0])
mesh.add_point([0,1,0])
mesh.add_polygon([1,2,3,4])
Sketchup.active_model.entities.add_faces_from_mesh(mesh)

you can use an array to index the points directly (for some reason, starting at 1)!

Can you test whether this is faster than point_at?

thomthom

I will see over the weekend. I found some slowness by having to use .add_point and then later use .point_index to build the polygons. building my own hash of Point3Ds and the index I got from add_point was faster.

Hopefully adding points in the add_polygon methods directly will be faster.

Oh yea - the index start at 1 is annoying as well.

cjthompson

I think I found what your problem is.

This works:


mesh = Geom;;PolygonMesh.new
mesh.add_polygon(Geom;;Point3d.new(0,0,0),Geom;;Point3d.new(1,0,0),Geom;;Point3d.new(1,1,0),Geom;;Point3d.new(0,1,0))
Sketchup.active_model.entities.add_faces_from_mesh(mesh)

This doesn't:


mesh = Geom;;PolygonMesh.new
mesh.add_polygon([0,0,0],[1,0,0],[1,1,0],[0,1,0])
Sketchup.active_model.entities.add_faces_from_mesh(mesh)

EDIT:
You can put the arrays inside of another array to get it to work:


mesh = Geom;;PolygonMesh.new
mesh.add_polygon([[0,0,0],[1,0,0],[1,1,0],[0,1,0]]) #this works
Sketchup.active_model.entities.add_faces_from_mesh(mesh)

thomthom

Using .add_points first and using index references for .add_polygon seems faster than using Point3d's.

RichMorin

General

Class and method names could be turned into links
to the appropriate API page, for ease of navigation.

Sentences should begin with a capital letter and end with
a period (etc). Phrases should not.

If a modifying phrase is used at the end of a sentence,
a comma should be added for clarity:


  the name of the attribute dictionary  if successful
                            dictionary,

Specific

http://code.google.com/apis/sketchup/docs/ourdoc/animation.html


animation -> animation
ruby      -> Ruby

... to pause, only certain ...
       pause;

http://code.google.com/apis/sketchup/docs/ourdoc/appobserver.html


... a 2nd    model ...
      second

Useful for if you need ...
---
This is useful if you need ...

http://code.google.com/apis/sketchup/docs/ourdoc/array.html


The SketchUp Array class adds ...
---
SketchUp adds ...

Specifically, it contains methods ...
---
Specifically, it adds methods ...

... arrays of 3     coordinate ...
              three

... vector. it returns ...
            It

http://code.google.com/apis/sketchup/docs/ourdoc/attributedictionaries.html


... all of the attributes dictionaries.
               attribute

http://code.google.com/apis/sketchup/docs/ourdoc/attributedictionary.html

Although the page does not discuss this, setting a
custom attribute with a key that contains upper-case
letters does not work.

The page does not indicate how to set an attribute
(eg, '=LenX+20') to be used as an expression.

In the entry for AttributeDictionary.each, the "value"
argument is being formatted as part of the description
for the "key" argument.

Ditto for AttributeDictionary.each_pair.

Dan Rathbun

On the API docs pages, in the left nav column, whenever you have made a link bold, the cursor changes to a caret instead of the hand cursor. I suspect it's the <b> and </b> tags doing this.
example from the API HTML source:

<li><a href="/apis/..../model.html"><b>Model</b></a></li>

Perhaps if the bold tags were outside the anchor tags?

<li><b><a href="/apis/..../model.html">Model</a></b></li>

If the css specifically set a tags such: a {cursor:hand} the nested bold tags should inherit their parent's cursor setting (according to the css reference.)

thomthom

The bold tag should not interfere with the cursor regardless if it's inside or outside the link element. It's default cursor property is inherit. It's either some override or other quirk. Could be a browser quirk.
In FF3.5 I don't see this behaviour. What browser do you use?

Dan Rathbun

@thomthom said:

In FF3.5 I don't see this behaviour. What browser do you use?

Currently still using MSIE 7

P.S.: at MSDN it indicates if the cursor is not explicitly set, the browser decides; so it may indeed be a MSIE quirk. (I have MSIE 8 and FF on the computer in another room, I'll check and see how the site looks on that machine later today.)