Ruby API Documentation - Errors & Suggestions


#1

Ruby API Documentation - Errors & Suggestions

The SketchUp Ruby API Documentation are located here:

This topic will serve as a thread to post suggestions for content, style & functionality, as well as notice of errors to be fixed, for the Ruby API Documentation.

If you have a GitHub account, you can also create issues in the SketchUp Ruby API Issue Tracker:


#2

Model # import()


a) The 1st argument should be “filepath” not “filename”.

  • The description of the 1st argument should explicitly indicate that the file’s path be included (if not in the current working directory.)

b) Example should parenthesize arguments.


#3

Layer#visible=

The documentation does not state that the method returns true if the assignment succeeded and false if not (for example when the layer is the current active layer).


#4

Entities#intersect_with

This method has tremendous power but what may be the weakest documentation in the API! The docs do not really tell what the method does (create Edges where Faces intersect), uses confusing names for the arguments, doesn’t clearly explain the significance of the arguments (especially the Transformations), and mis-states the return value (it is actually an Array containing the Edges that were created).


#5

as this thread includes suggestions…

all ‘snippets’ should be copy paste-able into Ruby console and work…

i.e. if a method only works inside a tool, the tool code should be included…

this catches out so many people…


#6

EDIT (2017-10-13): This suggestion predated the reimplementation of the API docs using YARD.

  • Since then, these suggestions apply to the YARD template used to generate the pages, and all these are now marked with a green checkmark have been realised as they are features of the standard YARD template for Ruby document pages.

For styling of how each method page should work, see the MSDN pages:
https://msdn.microsoft.com/en-us/library/windows/desktop/ms633573(v=vs.85).aspx

See how the left navigation column is:

  • Sizable
    • (by grabbing the margin separator with the mouse.) :white_check_mark:
  • Collapsible / Expanable :white_check_mark:
    • (by double-clicking margin > button with the mouse.)
      • Perhaps no longer needed, as with YARD, the class nav list automatically collapses to a “hamburger menu” when the content width is reduced too much (such as on mobile platforms.)
  • Never scrolls off the top of the screen :white_check_mark:

It was a major PITB to have to go way back to the top of the page top get at the links in the left navigation column!

:white_check_mark: - FIXED


#7

Entities#add_note creates a restricted kind of Text Entity. It does not have a Point3d position or a leader and can not have these properties set despite responding to the methods for them. It also has useless values of the other attributes of a Text related to leaders. These methods return default values that have no impact on the display. This kind of Text should be a separate class of Entity or at least provide a method to determine it is a note (Text#is_note?) instead of requiring users to know the workaround of testing for point.nil? && !has_leader.


Is there a screen text method?
#8

from the API: Camera.aspect_ratio=

If you set the value to 0.0, then the aspect ratio of the Camera will match the aspect ratio of its View.

this is just wrong in so many ways…
If you set the value to 0.0, then the aspect ratio of the Camera will returns 0.0, not the “relation” between width and height of it’s View…
as a ratio the view can never be 0.0:1, all 0.0 achieves is the clearing any camera ratio bars and ruining any export code that needs to know the true aspect ratio of the current cameras real view…

to further compound this issue, 0.0 is the default camera.aspect_ratio and when changed in code can also affect other camera parameters, why?

john


#9

Agreed.

I’d like to see view locked notes as a subclass of Sketchup::Text with the added methods it needs, and the useless ones from the superclass undefined for the subclass.

Names for the class could be ViewNote or TextNote.

(I prefer the former as it indicates the anchoring to the viewport.)

Additional methods needed might contain:

#anchor : Return an array of the position scales [ x_scale, y_scale ] from the upper left corner of the viewport. (The scales being a Float between 0.0 and 1.0.)

#anchor= : Accepts an array of the position scales [ x_scale, y_scale ] from the upper left corner of the viewport. (The scales being a Float between 0.0 and 1.0.) Cause an undo entry.

#set_anchor : Accepts an array or a list of two values, of the position scales [ x_scale, y_scale ] from the upper left corner of the viewport. (The scales being a Float between 0.0 and 1.0.) Should not cause an undo entry.

(Currently in order to move a note, we have to save it’s text, erase it, and recreate it. This causes an undo entry.)

#outline
#outline= : thickness of outline (0 if none), unit (:em,:px, etc.)

#padding
#padding= : thickness of padding (use nil for default in setter.), unit (:em,:px, etc.)

#background
#background= : Sketchup::Material object (nil if none.) Would allow transparency.

#color
#color= : Sketchup::Color object (nil if default.)

#font : reference to font object to get & set face, style & size (and choose between pts & %, or assume % if value is Float between 0.0 and 1.0 ?)

~


Is there a screen text method?
#10

API Array class documentation


The docs are misleading when it says “The SketchUp Array class …”

There is only one Array class. The SketchUp API just modifies the Ruby Array base class.

:white_check_mark: - FIXED : Will accept …

The SketchUp Array class adds additional methods to the standard Ruby Array class.

… even though I’d have preferred the term “The SketchUp API adds methods…


#11

Geom::Transformation # xaxis()

Geom::Transformation # yaxis()

Geom::Transformation # zaxis()


Was wrong return type. Said Point3d, instead of Vector3d.

:white_check_mark: - FIXED


#12

Dan,
Can you give me an example of how to use the results of these axis transformations?
The API it says it returns the axis of a “rigid” transformation.
If I want to query the xaxis of a group’s transformation, how would I know the user has not previously applied a nonrigid transform to it? And what would be the result?


#13

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.length=distance
point.offset(offsetvect)

#14

Entity # valid?


The return conditions are reversed.

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

:warning:


#15

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=.)

:warning:


#16

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


#17

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.


#18

Group#move!: and Componentinstance#move!

API:
http://www.sketchup.com/intl/en/developer/docs/ourdoc/group#move!
http://www.sketchup.com/intl/en/developer/docs/ourdoc/componentinstance#move!

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


Move! relative vs absolute positioning
Recommendations for animation code?
#19

Geom::Transformation#interpolate

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.


#20

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!