Architect's Walkthrough
© 2010, Martin Rinehart

OK, you've created the most beautiful house since Falling Water. Now you want to show it to the world with an animated walkthrough. That requires knowing a little SketchTalk in Motion. The bad news is that SketchTalk scripts are really Ruby plugin programs. The good news is that this short document is all you need. I'll explain everything you need to know before the second page is done. Then we get to scripting an actual walkthrough. You'll forget that you are writing Ruby programs.

Let's keep this simple. You could open and close doors with SketchTalk in Motion, but that's an advanced use. Let's just carry a camera as we walk into the house, turn it around as we move and zoom in and out. Hollywood director stuff, but no actors. (Actors are temperamental. Cameras are not.)

About the Camera

We control three things about the camera: The eye is the camera's position. More precisely, the position of the digital sensor within the camera. If you are the cameraman (or camerawoman) the eye is your eye. The target is the thing you are pointing at. The field of view is the inverse of the zoom. Small field of view equals zooming in; large field of view equals zooming out. The field of view ranges from one to 120 degrees. (Field of view: 1 to 120. It's on the exam.)

About Space

SketchUp's 3D space has red, green and blue axes. It also has points and vectors. If you want to place the camera's eye at a point 10 feet away from the origin on both the red and green axes, and 5 feet above the ground, you might use the ce (camera eye) command, this way:

ce Geom::Point3d.new( 120, 120, 60 )

Fortunately, you can use the much simpler, [r,g,b] array notation, this way:

ce [120,120,60]

That places the eye at the position you specify. It does not change the target or field of view.

OK, on to vectors. "Vector" is a 3D geometry term for which you can substitute the word "direction." Suppose you want to move 10 feet away from the origin, parallel to the red axis. You could move the eye with the cem command, this way:

cem Geom::Vector3d.new( 120, 0, 0 )

Again, you can use [r,g,b] notation to do that more easily:

cem [120,0,0]

All of the SketchTalk in Motion camera commands have an optional "m" third letter that means "move" by a vector from the current location (or move by a number of degrees from the current value, for field of view).

About Animation

Each of the SketchTalk in Motion camera commands has a static and an animated flavor. The commands above were static: do it immediately. To animate them, add a start and a stop second. Lets say we want to move 10 feet out parallel to the red axis, but we want to start moving in second 5 and stop when we get to second 10. This will do the trick:

cem [120,0,0], 5, 10
go

All the SketchTalk in Motion Camera Commands

(Hint: Everything in this section is on the exam.) The camera commands start with "c", for camera. They continue with: That gives three base commands: ce, cf and ct. These set the absolute point in space or number of degrees in the field of view. To specify a change from the current position or value, you append an "m" (as in "move"): cem, cfm or ctm. Each is followed by a value. An [r,g,b] array for eye or target, or a number of degrees (such as 35), for field of view. If the value is followed by start and stop seconds, it is animated. (The movement is divided into small parts. For example, a five second move at 24 frames per second, our animation speed, is 120 small moves.)

OK, now you know it all. Time to put it to use.

A Sample Walkthrough

Suppose we have a house to walk through. Here's mine:

Bird

My house has proved invaluable for testing this scripting and, before that for testing my VisMap plugin. I'm quite fond of it, so please don't make fun. You should use your own house or other building and create your own walkthrough of, I'm sure, something much better designed than mine.

Begin with a Plan

First, fold your arms in front of your chest. (That gets your digits away from mouse and keyboard.) Think. What do you want to do? For our sample, here's the plan:
  1. Begin with bird's eye view. 2 seconds.
  2. Drop to ground, 20 feet in front. 1 second.
  3. Walk to front, 5 seconds.
  4. Up step, 1 second.
  5. Into living room, 2 seconds.
  6. Turn 360 degrees, 90 at a time, 3 seconds each.
This plan is simple. A serious walkthrough will have many more steps but at first, use my plan. Follow this example, substituting values appropriate to your own model.

After making a plan, we start adding commands in the Ruby Console Pro. You have installed the Ruby Console Pro plus SketchTalk in Motion bundle haven't you? If you have, skip the next section.

Installing the Plugins

To begin, you need to download the Ruby Console Pro plus SketchTalk in Motion bundle.

Download
Ruby Console Pro and
SketchTalk in Motion

You extract the bundle into your SketchUp Plugins folder. To find your Plugins folder, in SketchUp click Window/Ruby Console. In the Ruby Console, type what you see here in the white input bar:

Finding the Plugins folder.

Your Plugins folder is the one in the second line of the output window. (Ruby is case sensitive: "SketchUp" won't work. It has to be "Sketchup.")

Extract the zip into Plugins and then restart SketchUp. You should now have a "Ruby Console Pro" choice in your Window menu.

Into the Ruby Console Pro

Begin by setting starting values:

Setting initial values.

You could use a calculator, or you could enter 18' the way you see here. How did I know that it was 18'?

Measuring to the center of the doorway.

You click "Exec" to check your work:

Clicking "Exec" checks your work.

Saving, often, is a good habit.

Saving your work.

The file name you save as becomes your working temp file name.

Saving as walkthrough.rb.

Your output window confirms your work:

Output window confirms your commands.

Or, if you make a mistake, it complains:

Output window issues error messages.

On to Animation

Our plan specifies two seconds up in the air, then dropping to the ground 20 feet in front of the door in one second. That's one command:

Add the first animated command.

If you're like me, you enter your animation command, click "Exec" and wonder why nothing happens. Eventually, you remember that you have to give a go command to start the animations. Your animation command is registered with the "conductor." Prior to go, the conductor simply maintains a list of the animations he'll need to execute. Your first command is on his list.

So you add go and realize that cem as specified only moves your camera a little bit. You change that to ce and you try again. This time you find that 20 feet is too close for comfort. This one works:

Corrected version of first animated command.

Note that non-animated commands are all executed prior to go. They are not registered with the conductor. It is a good practice to use the "m" form for all commands registered with the conductor. Sometimes, such as when animation starts, this is a bit extra trouble but it will pay off in the long run. Let's use cem, camera eye move, here:

Using the "cem" command.

You specify where you want to be and subtract where you were, in each dimension. From here on, this gets simpler.

Walking into the House

We'll walk to the door (5 seconds), up the step (1 second) and 10 feet into the living room (2 seconds). This is all you need:

Camera shows blank wall.

Note that I've added comments. From the "#" character on, the computer ignores whatever is there. It's your chance to annotate your script so that you can understand it later.

Now, this worked well until I got to the door. Then the camera flipped out. What's the problem? Simple, the target's green value is zero. (That's the front door.) It should have been set past the far wall. Simple to fix:

Fixing the camera target.

Zoom Out

Now all's good, but our shot is way too close to the back wall. Let's zoom out as we walk into the living room:

Zoom out while walking in.

I've used the exact same seconds for the zoom that were used for walking into the living room. You could experiment with continuing the zoom for a second or two more. How did I know that another 35 degrees was right? I didn't. 20 wasn't enough. 40 was a bit much. Ergo, 35. What works for your walkthrough is probably something different. Try it.

Turn Around

ow we want to turn 90 degrees at a time through a full 360, 3 seconds each turn. You turn by changing the target. Here's my finished turn:

Commands for the finished turn.

If you were sharp-eyed, you noticed that my finished turn is not quite my planned turn. It's four turns, five seconds each with a second pause between them. There's a lot of "try it, change it, try it again" involved in our movie making.

Finishing Touches

I decided to fly back to the bird's eye view and return to the original zoom. (The view is only approximately the same. No one will know if you don't tell.)

Last, being a long-time geek, I added a comment at the top and bottom. Even if you're an architect having nothing to do with geek, this is still a good idea. The top comment identifies the script file and explains what it does. By being there, the bottom tells you that you've got the whole script. This is the final script:

The complete, finished, walkthrough script.

Happy scripting!

Final Exam

  1. What letter do the camera commands start with?
  2. What second letter is used when you (re)position the eye? The target? The field of view?
  3. What third letter is used to indicate a move from the current value?
  4. What is the correct order for the rgb coordinates in a point or vector?
  5. In an animated command, which comes first: start or stop?
  6. What is the minimum and maximum field of view?

Answers

Question 6: 1 and 120. You probably knew the others.

F1, when the Ruby Console Pro has focus, gets you SketchTalk help if you forget. Do a File/New and try the sample "col" command.