randomVector (un, doc, umen, ted)

November 2, 2001
by Paul Catanese

Ok, I've got a good one for you, but I warn you right now, this article is almost entirely about an undocumented feature. That means that the standard disclaimer applies: this feature could easily disappear in a future release of Director or the Shockwave plug-in or it could cause your computer to act screwy like HAL (maybe not that bad), but in any case, be warned. That said, I have an undocumented goodie that I think you will really like.

Introduction

You've been playing with 3D in Director for a while, and you are starting to get used to the concept of vectors, not to mention the vector data type as implemented in Director 8.5. [Editor's Note: If not, check out Paul's previous article, "Vector Math is Not the Tool of Satan".] You are comfortable with the fact that a normalized vector has a magnitude of 1, and is sometimes referred to as a unit vector. If we were only thinking about 2D vectors and we took all of the possible 2D unit vectors and drew them on a piece of paper radiating from a single point, we would end up with a circle, one unit in radius. If we were to draw out all of the possible 3D unit vectors, we would end up with a sphere known as the unit sphere. The beauty of the unit sphere is this: any location on the surface of the sphere represents a 3D unit vector.

So Far, So Good?

In this article, I am assuming that you have a bit of experience with the randomvector function. On its own, this function spits back a random 3D unit vector. It is already normalized, therefore the magnitude of one of these randomly-generated vectors is exactly 1. To make sure that this concept makes 100% sense for you, I put together a very small demo. When you open up the link below, you should see a small Shockwave movie in which a blue sphere is "jumping all over the place". What you are watching is a blue sphere whose position is constantly being changed to a randomvector value (centered on the world's origin). Note how the position of the blue sphere is always on the surface of a "unit sphere" that I put in there to help you visualize this concept.

View demo 1

Up to this point, the information that I have covered is documented, and most likely if you have been playing with 3D for a few months now, you understand the concepts of unit vectors and random vectors. In any case, I expect and assume that the material that I have just briefly covered is material that you know well. But this is where we depart from the trail.

Up Too Late...

Don't know what made me do it, but I tried to pass the randomvector function an argument. When I did, I got the following: "Script error: four parameters expected". As soon as I saw that dialog box, I thought to myself: really? So I started plugging in all sorts of values, but it got me nowhere, and usually the results that came back were NAN or worse.

What kept me intrigued was an idea that I had. If you think about the good old random function, you know that it requires one argument such as random (10) - which will return a random number between 1 and 10. Less known is that if you pass two arguments such as random (5,10) you will get a random number within the range of 5 and 10. You can even do fun things like random (-10,10) to get random numbers that are both positive and negative. The point is that I remembered that Macromedia built functionality that allows developers to quickly generate constrained ranges of random numbers into the random function, and it made me wonder if they had secretly implemented something similar for the randomvector function.

The thought I had was this: what if we could feed values to the randomvector command and have a constrained range of random vectors returned. Think of it this way: I wanted to know if there was a way to use randomvector to generate random vectors from a section of the unit sphere rather than the whole thing. Long story made short: it is possible, and the four undocumented arguments are the key to making this work.

The Four Undocumented Arguments (of the Apocalypse)

If you think about a globe, you know that you can find locations on the globe by using latitude and longitude. But there are other systems for defining the coordinates on the globe as well. Imagine a two-coordinate system (Q, P) where P represents a point on the Z axis and Q represents an angle around the Z axis. P has the range -1 to 1 and Q has the range of 0 to 360 degrees. Using these coordinates you could describe any specific point on the surface of a sphere. With this coordinate system in mind, think about accessing the randomvector function with the following syntax:

randomvector (0, Q, P, 1)

The easiest argument to understand is the first one: just enter 0 and forget about it. The second argument represents Q in the coordinate system that I described above. The value that you assign to Q is a floating point number between 0 and 1 that represents an angle between 0 and 360 degrees. The third argument, P is a number between 0 and 1 that represents a position between -1 and 1 on the Z axis. The fourth parameter is the radius of the sphere, but since we really want a unit sphere, we will leave the value of the last argument as 1.

Note that when we use the randomVector function with four arguments, Director performs a unit conversion; from (Q, P) coordinates into vector (X,Y,Z) coordinates. Therefore, unlike randomVector without arguments, the randomness is not introduced for you. It is your job to feed the randomvector function random values within a given range in order to get uniformly distributed points over the area of the sphere. For example, take a look at the following code:

-- generate a random float number between 0.00 and 1.00
Q = random (100) / float (100)
-- generate a random float number between 0.00 and 1.00
P = random (100) / float (100)
randomvector (0, Q, P, 1)

I have to generate random numbers and then feed these numbers to the randomvector function. (The above example generates values anywhere on the surface of the sphere) But we can limit that area by doing something like the following:

-- generate a random float number between 0.50 and 1.00
Q = random (50) / float (100)
-- generate a random float number between 0.50 and 1.00
P = random (50) / float (100)
randomvector (0, Q, P, 1)

If you are still with me, great, but I personally think that the implications of the four arguments and the (Q, P) coordinate system are a little hard to grasp without a nifty demonstration. This time, you have a more control over what is happening in terms of the generation of random vectors. Take a look at the following Shockwave movie:

View demo 2

In this demonstration, there are two slider bars, each with two sliders on it. You can use the sliders to isolate a range of numbers to feed to the randomvector command. In addition, you can drag the mouse around in the window to dynamically change your point of view -- you can also use the button at the bottom of the stage to reset the camera view.

As you play with the sliders in this demonstration, I offer the following advice. Start by moving one of the sliders on the Q bar to about the half-way point on the slider. If you look at the random vectors being created, you should see that they are only on one side of the unit sphere. Ok, reset the Q slider and this time, let's play with the P slider. Set the range of P so that it is between 0 and .25; you are going to need to change views, but you should be able to see that random vectors are only being created in the front quarter of the unit sphere.

Now, try setting the range of P so that it is between .4 and .6; you should now see random vectors in a ring around the Z axis! With the P slider set as such, limit the Q slider to a range of .5 and .75; random vectors are only being generated in one quarter of that ring. Ok: Your turn. Before going on, play with the demo for a little while and try to see what sorts of distributions you can get. Remember to wheel your view around as you work to make sure that you understand the distribution of random vectors that you are creating.

Conclusion

I hope that as you fiddle with this demo the immediate relevance and power of this technique are quickly understood. However, as with any demonstration, there are limits to what I can show you in a given amount of time. The direction that I will push you in from here is to think about the ranges of random numbers that we are feeding to the randomvector function.

Try this: play with the Q range of numbers to see if you can get the random vectors generated only in the upper hemisphere. With this demo, you can't do it. (but it can be done). The range that you need to feed to randomvector is 0 to.25 and .75 to 1. See how the range is split in the middle? (a) It was too much of a pain to make sliders that could do that. (b) More importantly, the implication here is that you could devise complicated ranges to generate random vectors in two or more different locations on the surface of the unit sphere - the possibilities are quite broad. I will leave the implementation up to you, but go ahead and download the demo movie in MacOS or Windows format and use the code as a starting point if you want.

The randomvector function has more to offer than you might have originally thought. Even without the undocumented arguments described in this article, randomvector is extremely useful. Personally, I think this functionality could serve as the basis for an amazing custom particle system engine - keep your eyes open because you never know what just might pop up on DOUG!

Acknowledgments

This demo / article / technique would not have been possible without the help of Jerry Charumilind who so kindly answered all of my questions in regards to the randomvector function. I was having trouble deciphering what the four arguments meant, and -- more importantly -- what the expected ranges were. He was amazingly quick and adept at answering my queries and I appreciate his help in making this article possible; Thanks, Jerry.

Paul Catanese is a Chicago-based artist and educator who has been working with Director for several years. Paul's most recent credits include authoring Director's Third Dimension: Fundamentals of 3D Programming in Director 8.5, a Technology Fellowship from Columbia College to develop curriculum for 3D programming and consulting for the Brainbench.com Director 7 and 8 certification tests. Currently, Paul teaches animation and experimental imaging at the School of the Art Institute of Chicago and continues to offer consulting, training and development for all aspects of interactive multimedia through his company, skeletonmoon.com.