New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add better examples for entities.intersect_with
#741
Comments
One of the main reasons why the doc is confusing is the naming of the arguments. For example, It would be better if either the argument names matched ...
... or were more descriptive. ie:
~ |
The documentation is very frustrating. There are three entitites collections and two transformations so the two transformations must embed the connections between all three. I think an example like this would be quite good in the docs: def intersect(cutter_group, mesh_group, result_group)
# transformation from mesh to cutter
tr0 = cutter_group.transformation.inverse * mesh_group.transformation
# transformation from result to cutter
tr1 = cutter_group.transformation.inverse * result_group.transformation
mesh_group.entities.intersect_with(false, tr0, result_group.entities, tr1, true, cutter_group.entities.to_a)
end |
Here's another example: # @example In a model whose top level entities has 2 intersecting groups:
# model = Sketchup.active_model
# groups = model.entities.grep(Sketchup::Group)
# group = groups.first
# group2 = groups[1]
# recurse = false
# hidden = true
# ents = group.entities
# result_group = model.entities.add_group
# ents.intersect_with(
# recurse, group.transformation, result_group.entities,
# result_group.transformation, hidden, group2
# ) |
Interesting example since it works, is more compact then my proposed solution and clearly violates the docs which states that the last parameter is:
It seems that if you send in a container instead of an entities collection Sketchup picks the transformation from the container. It makes perfect sense but there is no mention of it in the documentation. |
Now the documentation actually makes sense - it's just that it is exactly wrong. With |
After a night's sleep I realized that a group is an entity so the documentation isn't exactly wrong, it's just exactly confusing. It should clearly separate the more general case where |
Well I debated stating the obvious. Yes, everything that resides in the model dB's collections are instances of subclasses of * Except
I think this is subjective. It depends upon the readers level of experience with Ruby, OOP (in general) and YARD generated documentation in particular. So it could range from "a little bit confusing" to "somewhat confusing" to "pulling your hair out". ;) (yea, I'm teasin')
Seriously, though, ... I never read the documentation this way. Ie, it didn't seem (to me) to imply that
BUT ... rereading the method description, it does clearly state ... "to intersect an entities, component instance, or group object" ... with the receiver "entities object". However, the parameter list for the last argument ( I just tested using this as the last statement ... ents.intersect_with(
recurse, group.transformation, result_group.entities,
result_group.transformation, hidden, group2.entities
) ... and got this exception:
So, the last argument cannot be an What the doc does not imply is that the last argument can also be a single primitive like an edge. So the description should read:
The term "entity" is this context and many other places in the documentation actually means We who've been using (and helping to improve) the SketchUp API documentation for going on 15 years (in it's several forms) just take for granted that the lower case word "entities" in the text can refer to either an If the context is not clear enough then those new to the concept or in this case this method, can be easily confused if the explanation is too terse. Sometimes a guru (writing) technical descriptions doesn't realize that the "common knowledge" that they take for granted isn't yet understood by novices who will be reading those words. Anyway .. the ~ |
I've always interpreted the last argument as an entities collection and the thrown error as a bug, but when looking closely that's a bug on my part. Nevertheless - for the method to be general and work with three contexts arbitrarily placed in the model hierarchy the last argument has to be an array of raw entities and the transformations have to embed the relation between the three contexts explicitly. For this case (which I until now thought was the only one....) the docs are simply annoyingly unhelpful since they do not state that the context of the intersection is |
Could be why I noticed a difference in the placement of the I think the former put the intersecting edges exactly where they intersected, and the latter had the
Agree. That one-line description doesn't do much for understanding the quirks or power of this method. |
This method is not easy to understand.
Yet another demonstration of that:
https://forums.sketchup.com/t/how-can-i-understand-entities-intersect-with-method/182335
We should add more complete code examples. It might be challenging to do a fully functional example in the Ruby API docs without a lot of setup code to generate the geometry. But we can do better than the current one-liner.
We can add better example/tutorial to the example/tutorial repo and link to it from the docs. (https://github.com/SketchUp/sketchup-ruby-api-tutorials)
The text was updated successfully, but these errors were encountered: