Entities, Groups, Instances, and Definitions for a beginner
-
Can't help it that I'm slow,-) but it took me the last month or so, to come to the following, and would appreciate clarification from those who better understand the subject.
SU entities include basic geometry, like lines (or edges), and faces. A SU group is a unique collection of entities. An instance is a SU component that is one copy of a component definition. Groups have instances, and have ComponentDefinitions like ComponentInstances does.
Images have component definitions as well, like Groups, SU treats them slightly different. You can see when you iterate
model.definitions
that you also get Group and Image definitions. ComponentDefinition has.image?
and.group?
that allows you to identify the type of component definition you are dealing with. This is important to check if you are processing all definitions in a model.The difference between one instance and another, is its transformation; its spatial location, scale, and rotation. Editing the entities in a component instance, edits the entities in all instances of that component. Groups are unique instances. Caveat: when you have multiple group instances of the same group definition and edit one via the ruby API they are not automatically made unique. You must call
group.make_unique
first - otherwise you edit all the group copies. Besides basic geometry (lines, surfaces, circles, arcs, etc.), entities include groups, and instances (component instances).The basic level of "collecting stuff" is an array of
entities
. The next level of collection is a group of entities,group.entities
, and*instance.definition.entitites*
. The final level is a collection of instance definitions,model.definition
. Adding entities to the basic level is byentities.add_...
where...
is aSketchup::Entity
(eg.entities.add_line
).Before adding a
Sketchup::Entity
to entities, groups, instances, and components, one must be created, or identified. Identifying the basic entities in the existing model is first by identifying the current model, bymodel = Sketchup.active_model
, and then its entities byentities = model.active_entities
. Adding new entities to the collection of entities is as previously stated,entities.add_...
where...
is aSketchup::Entity
.Adding entities to a new group, instance, or component, requires creating a new group, instance, or component by,
entities.add_group
, or [ruby:21nafgpj]entities.add_instance[/ruby:21nafgpj]. For example, [ruby:21nafgpj]my_group = entities.add_group[/ruby:21nafgpj] creates a new group, [ruby:21nafgpj]my_group[/ruby:21nafgpj]. Entities added to my_group are by [ruby:21nafgpj]my_group.entities.add_...[/ruby:21nafgpj], as noted above. The same sequence applies when adding entities to new instances.New definitions are created by identifying the current collection of definitions by [ruby:21nafgpj]definitions = model.definitions[/ruby:21nafgpj], then adding a new one by [ruby:21nafgpj]my_definition = definitions.add "Description_of_definition"[/ruby:21nafgpj]. Adding an instance to my_definition is by [ruby:21nafgpj]my_definition.entities.add_instance(my_instance.definition, my_instance.transformation)[/ruby:21nafgpj].
The following code snippet changes a group into an instance, then adds the instance to a definition:
#get current model model = Sketchup.active_model #get current entities array entities = model.active_entities #get model's definitions array definitions = model.definitions #add new empty my_definition my_definition = definitions.add "My Selection" #make my_instance out of group my_instance = my_group.to_component #add my_instance to my_definition my_definition.entities.add_instance(my_instance.definition, my_instance.transformation)
Addenda: Where the previous is italicized, it reflects corrections per the below.
-
@honoluludesktop said:
A SU group is a unique collection of entities. An instance is a SU component that is one copy of a component definition.
Groups
have instances, and they haveComponentDefinitions
likeComponentInstances
does.
Groups are just special components - when you copy a group you make multiple instances of the same group definition. But SU treats them specially when you edit by making them unique. Caveat: when you have multiple group instances of the same group definition and edit one via the ruby API they are not automatically made unique. You must callgroup.make_unique
first - otherwise you edit all the group copies.Images have component definitions as well, like Groups, SU treats them slightly different. You can see when you iterate
model.definitions
that you also getGroup
andImage
definitions. ComponentDefinition has.image?
and.group?
that allows you to identify the type of component definition you are dealing with. This is important to check if you are processing all definitions in a model.@honoluludesktop said:
The next level of collection is a group of entities, group.entities, or an instance of entities, instance.entities.
Not quite correct - there is no ComponentInstance.entities
You must always access the definition, as such:instance.definition.entitites
-
Thanks, Tom. I've corrected the original post.
Advertisement