Entities, Groups, Instances, and Definitions for a beginner

honoluludesktop

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 by entities.add_... where ... is a Sketchup::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, by model = Sketchup.active_model, and then its entities by entities = model.active_entities. Adding new entities to the collection of entities is as previously stated, entities.add_... where ... is a Sketchup::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.

thomthom

@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 have ComponentDefinitions like ComponentInstances 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 call group.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 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.

@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

honoluludesktop

Thanks, Tom. I've corrected the original post.