Ruby API Documentation - Errors & Suggestions

I believe that what the API docs intended was that these three methods always return unit vectors as if the transformation was rigid. You have to check the (undocumented) methods #xscale, #yscale, and #zscale to see whether the transformation included scaling, which would make it non-rigid. (The methods #rotx, #roty, and #rotz are also undocumented, but are ok with rigid transformations).

It is also possible, though unusual, to create a skewed transformation in which the axes are not orthogonal. You would have to use Vector3d#perpendicular? to test them.

As an example of how you might use these, if you wanted to offset a Point3d in the x axis direction of a Group, you could use

trans = group.transformation
offsetvect = trans.xaxis
offsetvect.length=distance
point.offset(offsetvect)

Entity # valid?


The return conditions are empty.

The statement that it is functionality identical to the deleted? method, is wrong, … it is the functional (logical) inverse.

:warning:


EDIT (2019-02019) : Added issue to the official API issue tracker …

Drawingelement # visible=


The arguments and return description is the logical inverse of reality. (Appears that the documentation was copied from the #hidden= method but not changed to be correct for #visible=.)

:white_check_mark: This issue has been FIXED since posting.

Model # options()


The code example does not work because it is iterating an array of keyname strings.
The String class does not have name() method, and the old Ruby 1.8 each() method has been removed. (The current example raises NoMethodError for both these.)

Here is a better working example:

manager = Sketchup.active_model.options
manager.keys.each {|provider|
  puts provider.to_s
  if manager[provider].size != 0
    manager[provider].each {|key, value|
      puts "> #{key} - #{value}"
    }
  else
    puts "- (no options for this provider)"
  end
  puts
}

If you wish not to use subscripting, then remove the chained call to .keys, viz:

manager = Sketchup.active_model.options
manager.each {|provider|
  puts provider.name
  if provider.size != 0
    provider.each {|key, value|
      puts "> #{key} - #{value}"
    }
  else
    puts "- (no options for this provider)"
  end
  puts
}

And the “no options” clause is needed because there is actually one provider that has no options, and allows options to be added, (but SketchUp has a bug in handling them on the PC at least.)


EDIT (2019-02-19) : Added issue to official issue tracker at GitHub …

ComponentDefinition # set_classification_value()


The API says:

But when actually trying to set a choice attribute:

path = ["IFC 2x3", "IfcBuilding", "CompositionType", "IfcElementCompositionEnum"]
success = definition.set_classification_value(path, "element")

Error: #<RuntimeError: Unexpected attribute type>
<main>:in `set_classification_value'

We get a RuntimeError instead of a NotImplementedError.

:warning:

Note: When trying an integer argument, the same exception occurs.


EDIT (2019–2-19) : Added an issue to the official API issue tracker …

Group#move!: and Componentinstance#move!

API:
Homepage | SketchUp Developer!
Homepage | SketchUp Developer!

Group#move! includes the text “The move! method is used to apply a transformation to the group.”.
Componentinstance#move! includes: “The move! method is the same as the transform! method…”

Those descriptions are appropriate for the “transform!” method, which applies an affine. Method “move!” is similar to “transformation=”, replacing the existing transformation. Unlike, “transformation=”, “move!” does not affect the undo stack and is quicker for animation.

Suggest for both group and component instance: “The move! method is used to assign the transformation for the group, similar to the transformation= method, except that it does not record the move as an undo operation”.

Geom::Transformation#interpolate

:white_check_mark: FIXED

API:
http://www.sketchup.com/intl/en/developer/docs/ourdoc/transformation#interpolate

The interpolate method requires three arguments, and the third is labeled “parameter”. A better name would be “ratio”.

The description for that method says that the parameter is a value from 0 to 1, but the example code statements have a value of 25:

    t3 = Geom::Transformation.interpolate t1, t2, 25

Testing has shown that 1.0 returns transform2 “t2” argument, indicating that a value of “1.0” is a interpolation ratio of 100%. Recommend changing the 25 to 0.25. A value of “25” is 25 times beyond the the second argument, and can be confused with 25%, which it is not.

Occurs in too many examples to list here:

Please get rid of all the inane “I just happen to know” comments in the examples. These are useless to both novices (who have no clue how you happen to know that) and to experts (who most likely have some other reason for knowing). They reveal a lack of effort in creating examples that can stand on their own two feet!

2 Likes

Drawingelement # bounds()


For a group, there is a wrapper method named local_bounds, whose description notes the difference in the bounds method between a component instance and definition. (When it really should also be noted in the bounds method description proper.)

So the description needs to explain when it returns transformed and untransformed bounding boxes, and should include a link to Group # local_bounds().


EDIT (2019-02-19) : Added to official API issue tracker …

https://github.com/SketchUp/api-issue-tracker/issues/202

in the Sketchup Selection class

in the Selection.remove() method, it says selection.add() in the example box. Just thought i’d throw that out there

Because they are really aliases for one another. They don’t do exactly what their name implies. (Which I do not like myself.) If the object is not in the selection set, the remove method will add it.

So, they actually are a toggle.

1 Like

Ok that makes sense. just wondered if it was a typo.

Sketchup::Camera#fov=

The “fov=” setter is documented in the API as taking an argument in millimeters. That is inconsistent with the “fov” getter method which returns a value in degrees. The “focal_length” getter and setters are in millimeters. A field of view should be expressed in angular measurements, and testing with it shows that it is working in degrees.

A simple test at the command line of:

Sketchup.active_model.active_view.camera.fov= 50.mm

results in a significant amount of magnification. A length of 50.mm, converts to a simple floating point value of 1.98, or almost 2 inches. The “fov=” is accepting that as 1.98 degrees.
One might try to say that 50.mm is a FOV for some sort of camera, but increasing focal lengths always zooms in more, while increasing FOV in degrees zooms out.

The API documentation for #fov= should be units of degrees.

When Sketchup’s built-in zoom tool is in use, the VCB (Value Control Box) can accept text in both degrees and mm, but the fov= is not working that way.

API:
http://www.sketchup.com/intl/en/developer/docs/ourdoc/camera#fov=

I’ve been away from Sketchup for a while and find the current Ruby API documentation to be lacking. To start, I’m trying to create an Extension with a menu. But the documentation for menu is incorrect, it should include add_item not add_menu. And if I get a menu item id how do I access its methods and properties? What are its methods and properties?

You are right. The headers say add_menu, but the documentation text and examples say add_item! This is a documentation error.

The Ruby API is lacking in useful support for menu items. There isn’t much you can do with the id. If you created a UI::Command object for use as the menu item, you can retain a reference to it yourself and try invoking its methods. I’ve had no luck with this, however. It appears that most of the Command’s attributes are copied into some inaccessible structure as the item is added to a menu and changing them later has no effect.

We’ve had these issues for 8 years or more.

Recently the switch was made to use YARD, and a small group of us are in the process of an overhaul. It’ll take some time.

Thanks Steve. I thought there was a way to disable and enable a menu option
but don’t remember how. I seem to have lost all of my old code. That’s
where the Ruby API documentation is really lacking. The old documentation
was much better.

You use the beforementioned id: Sketchup::Menu#set_validation_proc

It is the old documentation. That’s the main problem. :wink:
(It is just being output by a different webpage building engine.)

Not what I remember. A menu item is an object, but what are the methods and what are the properties?