SketchUp Entity Overview
The purpose of this document is to give an overview of SketchUp entities and to better bridge the gap between the technical details from our API docs and the mental model of a SketchUp user.
A SketchUp model consists of a range of different objects, referred to as entities, some easier to understand than others. The names of these entities can differ from what they are called in other programs, and even differ slightly between the API and the user interface.
All Entities
Entities are a diverse bunch, spanning from the model's geometric content to its display settings, but they all share some behaviors.
All entities belong to a SketchUp model. Attributes with custom data, e.g. parametric input, can be saved to entities, and observers can be added to entities to respond to them changing.
DrawingElements
The main group of entities are the drawing elements. These are the "physical" things in the model, such as edges, faces, groups and images. These are the stuff you see in the model view (with some exceptions but we’ll get to that later) and can be selected by the Select tool and moved by the Move tool.
DrawingElements can all be assigned Tags (aka Layers) and Materials. They can be hidden or erased and can cast shadows.
All DrawingElements are parented by either a ComponentDefinition or the Model itself.
In the SketchUp UI, this category is simply referred to as Entities, e.g. in Entity Info.
Edge
The Edge is maybe the simplest and most fundamental Drawingelement. It's a straight line between two points (Vertices).
SketchUp has no concept of truly curved geometry, but edges can approximate curves with help of the Curve and ArcCurve entity described further down.
Face
Faces are slightly more complex. They can have any number of Vertices, but must be planar. Faces can also have any number of interior holes.
What SketchUp calls a Face can be called a polygon in other programs.
A Note on Surfaces
If the edges between faces are marked as soft and hidden, geometry isn't currently displayed in the model, the faces act together as a single entity in the SketchUp UI. Clicking with the Select tool selects them together and in Entity Info the label displays as "Surface". However, no Surface entity actually exists under the hood and surfaces are sometimes referred to as pseudo entities.
Since SketchUp has no concept of truly curved geometry, a series of flat faces combined into a Surface is used as an approximation.
A Note on Stickiness
In SketchUp both Faces and Edges are "sticky". If they overlap they intersect and merge. This is why it is so important to create groups and components to separate objects!
Components
In SketchUp a Component can be thought of as an embedded model within a model. A Component has its own internal axes and coordinate system. Geometry inside Components doesn't stick to geometry outside or in other Components.
To the user a Component typically represents a class of identical objects that are distinct from what's around them, e.g. doors and windows. You can generate reports from your Components to know how many items to purchase or manufacture.
There are two distinct aspects of Components in SketchUp, Component Definition and Component Instance, but in the UI they are often both referred to simply as Components.
ComponentInstance
A Component Instance is the thing that exists in the model viewport. It can be selected, moved, scaled, painted and more, just like any other DrawingElement.
The main properties of the Component Instance are the transformation matrix controlling its position, rotation and size, and the reference to a Component Definition.
A Component Instance can be thought of as the "outside" of the Component.
ComponentDefinition
A Component Definition holds the "inside" of a Component. All geometry within a Component belongs to (is parented by) the definition. When a user double clicks a Component to edit its content, it's the definition that is edited, and all instances of the same Component are changed together.
If you as a user want to change just one instance of a Component to create a variation of its design, e.g. make one window bigger than the others, you can make it unique and a new duplicated definition is created for it.
It can be argued a ComponentDefiniton isn't a true DrawingElement. It can't be selected or moved around in the model, but is rather a support entity for the ComponentInstance, a bit like a Tag or a Material. From the UI it cannot be painted with a material and it cannot be tagged. However it does inherit from the Drawingelement class.
To the end user the ComponentDefinitions are accessed in the In Model view of the Components panel.
ComponentDefinitions are internally also used by Groups and Images, in addition to regular Components. However, these definitions are not directly exposed to the user.
Group
A Group can be thought of as a special case of a Component. Groups have transformations and ComponentDefinition references just like ComponentInstances. Groups share definitions with each other when they are copied, just like Components. However, when you modify the contents of a Group from the UI, SketchUp silently makes it unique. Also Group definitions don't display in the Components panel.
To end users Groups represent unique objects whereas Components represent classes of objects. While Components are used for interchangeable or off the shelf parts like doors and windows, Groups are typically used for locally built or unique parts, like individual slabs or walls.
Note: The SketchUp Ruby API doesn't automatically make Groups unique the way the UI does. As an extension developer it is your responsibility to explicitly make a group unique if you change it.
Historically the Group's definition couldn't be directly accessed in the API. Instead you had to iterate over all the model's definitions to see which one had the Group among its instances. Direct access to the definition was added to the C API in SketchUp version 2014 and Ruby API in SketchUp version 2015.
Image
Images are another case where the user mental model and implementation don't fully match. From a user point of view an Image is an atom object; you can't double click it to edit its content. However, implementation-wise Images are related to Components and Groups, and do rely on a ComponentDefinition, containing a single rectangular face and its edges.
An Image's definition cannot be directly accessed from the Image. However, if you iterate over the ComponentDefinitions in the model, you'll find it there. Similarly the Image Material can be found in the model's internal Materials list but is hidden in the UI Materials list.
You probably don't want to directly interact with these internal objects. They are hidden from the user and according to the mental model of SketchUp they don't really exist. If you for instance are writing an exporter, you typically skip these internal objects and use the API for the Image directly to access the relevant data.
Guides
Guides (ConstructionLine, ConstructionPoint) are helper objects in SketchUp modeling. They can be used to create a modeling grid or to align objects, and don't stick to other entities the way Edges and Faces do.
Dimension
Dimensions are the things drawn around an object to annotate its measurements. The Dimension text is automatically generated from the model measurement but can also be overridden to a custom string.
Text
Texts are typically used as labels with an arrow pointing to something in the model. The text always faces the camera and its size is by default defined in 2D screen space.
A Note on 3D Text
The 3D text that can be created in the SketchUp UI is currently not its own entity. It's merely a normal component, with no parametric ability.
SectionPlane
Section Planes are used to cut a model open to view the inside. The Section Plane is non-destructive and hides part of the model without altering the geometry.
There can only be one active (cutting) section plane in each group or component, as well as in the model root.
Non-DrawingElements
The other, "non-DrawingElement," entities are typically things that aren't "physical" selectable objects in the model, but support such objects. This includes tags that control Drawingelement visibility, materials that can be painted onto DrawingElements, scenes (saved views) and more.
These entities are often not controlled from within the modeling view, but from the side panels.
Vertex
A Vertex, also known as an Endpoint, may seem like a "physical" thing inside the model. It can be moved with the Move tool and it has a more direct presence in the geometry than say a Tag or Material. However Vertices cannot be selected by Select tool, can't have Materials and can't have Tags, and is therefore not a DrawingElement.
Vertices are used by Edges and Faces.
Curve
SketchUp has no concept of truly curved geometry, only straight edges. However, a sequence of straight edges can be used to approximate a curve. The Curve entity denotes such a relation.
ArcCurve
An ArcCurve is a special case of Curve representing an arc. The ArcCurve stores underlying parameters such as center point and radius that can be used to extract a "true" curve. The length in Entity Info is for instance calculated from the "true" curve, not from the length of the straight edges.
Material
How boring would a model be without materials? All materials have a color and can optionally also have a texture.
All Drawingelements can have a material.
Nil denotes default material, or no material.
Similarly to how Groups and Images internally use ComponentDefinitions, Tags and Images internally use Materials. However, these materials are not accessible in the UI and not intended to be directly edited.
A Note on Inheritance
If a SketchUp Drawingelement lacks a Material of its own, it is displayed with the Material of its parent. This means you can draw an object, make it a Group or Component, and paint it as a whole "from the outside" rather than painting each Face individually.
Tag (aka Layer)
Tags can be used to categorize objects in a SketchUp model and control their visibility together, e.g. for walls, slabs, windows, doors, furniture or scale figures.
All SketchUp DrawingElements have a Tag.
Tags used to be called Layers. However, they were never containers parenting DrawingElements but rather attributes applied to DrawingElements. The hierarchical parenting that other programs often call layers better maps to SketchUp's Groups and Components. Also the name clashed with LayOut's existing Layer concept when the SketchUp feature was exposed in LayOut. In SketchUp 2020 this entity was renamed Tag.
Tag Folder (aka Layer Folder)
To make the tag list more manageable in complex models, SketchUp 2021 introduced Tag Folders. In the UI users can collapse or expand folders to visually shorten the list. The visibility of Tag Folders can also be controlled, both from the UI and API. Tag Folders can both contain Tags and nested Tag Folders.
When a Tag Folder is hidden, all of the contained Tags are functionally hidden, although their individual visibility states are preserved. To test if a Tag is "actually" visible, you need to both test its own visibility state and that of all parent Tag Folders (see Traversing the SketchUp model).
Fun fact: In the API the name Layer Folder is used for consistency to the Layer class, although Tag Folders have never been called that in the UI.
Style
A style contains display settings, such as the color of the sky, the thickness of profile edges or how the rest of the model should fade out when a Component is opened.
A common usage is to have one Style representing a realistic look with a gradient sky, materials and textures, and another used for generating drawings with only lines on a solid background color.
Styles can be saved and reused between Scenes. Editing the Style once affects all the Scenes using it.
Scene (aka Page)
Scenes are saved views in a SketchUp model. Scenes can save the camera location, tag visibility, some entity visibility, drawing axes, display options and more.
By default Scenes store all of these properties, but a somewhat common workflow is to set up Scenes that only stores certain properties and use them as a kind of shortcut for e.g. a specific tag visibility setup or a specific drawing axes setup.
Some other programs use the word "Scene" to refer to the whole open document. In SketchUp that is called a model.
At the beginning of time Scenes were called Pages in the SketchUp UI, and the API still uses the old name for compatibility.
Attributes
All SketchUp entities can have attribute dictionaries stored to them. Fun fact: since attribute dictionaries are themselves entities you can also create nested attribute dictionaries.
Attributes can be used to store custom data to a model, such as input values if you create an extension drawing parametric objects.
Honorable Mentions
The Model
This is the open document, the one containing all entities.
The Model is actually not an Entity in SketchUp but sometimes behaves like one. Just like Entities, the Model can store attributes.
Note: In some other programs a "model" is an asset inserted to the open document. In SketchUp that would be called a Component.
And More?
This article serves to give an overview of how a SketchUp model is assembled. There are even more Entity types that we hope to dive deeper into in future articles, such as Loop, EdgeUse, LineStyle and RenderingOptions. For a full list, see our Documentation.