Adding Geometry

In this lesson we'll show the basics of adding geometry to a model. By the end of this tutorial, you should be able to:

  • Access the model object.
  • Access the model's entities collection.
  • Add an edge, face and construction point to the model.

Try it Now!

One of the most basic things you might want to do with Ruby code is to add geometry to a model. Lets dive right into this core feature of the Ruby API. In this snippet we will add an edge into the model.

point1 = [0,0,0] point2 = [100,100,100] model = Sketchup.active_model entities = model.active_entities entities.add_edges(point1, point2)

Lets look at the code. First we define two variables as arrays with 3 values in them. Those arrays are interpereted by SketchUp as points in space. point1 is the model origin at 0,0,0 and point2 is at 100,100,100.

Tip! - In the Ruby API, units are always "inches". Refer to the docs for the Numeric class for information on how to convert between different units.

Then we declare the model variable that references the current, or active SketchUp model. Next we make a variable called entities and assign it a reference to the model's active_entity collection. Entities are things like edges, faces, images, components, construction geometry, etc. and an entity collection is like a Ruby Array, full of those entities. There can be many entity collections in a model. The last step is to add the edge to that entity collection with the Entities.add_edges method.

Use the API Docs

This is the final reminder, I promise. Remember to look things up in the API docs! The more you read through the docs, the more you will understand what the Ruby API is capable of doing. Check out the documentation for these methods we used:

Moving On, Adding a Face!

Lets take the ideas we covered in the first example and keep going with it by adding a face to the model. We add a face to the model in a similar manner to adding an edge. We need three unique points in space. So lets create one additional array, and add a face with edges that go from point1 to point2, point2 to point3, and point3 back to point1. Here's an example.

point1 = [0,0,0] point2 = [100,100,100] point3 = [0,100,100] model = Sketchup.active_model entities = model.active_entities entities.add_face(point1, point2, point3, point1)
Tip! - Faces in SketchUp are made up of 3 or more points or edges and those points or edges must be coplanar. It is up to you as the developer to make sure the edges or points are coplanar, otherwise no face will be created.

Adding a Construction Point

Or adding a few construction points. Lets repurpose the previous example and add construction points to the end of all edges of the face we created. Instead of using the point1, point2, and point3 arrays to add a face, we'll use them to add construction points at each of those positions, one at a time using the Entities.add_cpoint method.

point1 = [0,0,0] point2 = [100,100,100] point3 = [0,100,100] model = Sketchup.active_model entities = model.active_entities entities.add_cpoint(point1) entities.add_cpoint(point2) entities.add_cpoint(point3)

One Step Further

Here's some ideas to help you take the provided examples and take them to the next level. See if you can find a way to do it without looking at the provided solutions.

Add a Circle

Let's start with something that should be pretty straightfoward. Before you get started, delete everything that you have in the model. Now use the Ruby API to add a circle into the model.

How did you add the other geometry into the model? By accessing the active_entities object and calling a method that adds the geometry. Look at the documentation for the Entities class.

centerpoint =,0,0) vector = 0,0,1 model = Sketchup.active_model entities = model.active_entities edges = entities.add_circle( centerpoint, vector, 10 )
Add Construction Points to a Circle

Was the circle task too easy? Lets build on it. Go ahead and delete the circle in the model. Now try to create a circle and add a construction point to each vertex on the perimiter of the circle. Bonus points if you only add one Construction Point per vertex!

Notice that when you create the circle, you get an array of edges returned. Use that array of edges and find all the edges that define the circle. Then find those edges' vertices. Use the position of those vertices to determine where to add the Construction Points.

centerpoint =,0,0) vector = 0,0,1 model = Sketchup.active_model entities = model.active_entities edges = entities.add_circle( centerpoint, vector, 10 ) # This is an empty aray where the vertices will be stored. vertices = [] edges.each do |edge| # Add the start and end vertices for every edge. Think about this, # each vertex will be added twice because it is used by 2 edges. vertices << edge.start vertices << edge.end end # This is where we remove duplicate vertices. vertices.uniq! vertices.each do |vert| # Here we add the construction point to the model, using the # position of the vertex. entities.add_cpoint(vert.position) end
Add 3D Text

Here's another test to try. Delete everything from the model and use the Ruby API to add 3D Text to the model. If you have made it this far, this should be pretty easy. Try playing with all the available parameters when you create the 3D Text.

Still need some help? Look in the Ruby API docs for the add_3d_text method in the Entities class. The example there should give you enogh to get this working.

# Look at the add_3d_text method in the Entities class # in the Ruby API docs for information about all the # available parameters to create 3D Text. entities = Sketchup.active_model.entities string = "Hello World in 3D!" align = TextAlignLeft font = "Arial" is_bold = true is_italic = false height = 12.0 tolerance = 0.0 z_position = 1.0 is_filled = true depth = 5.0 success = entities.add_3d_text(string, align, font, is_bold, is_italic, height, tolerance, z_position, is_filled, depth)