StdDraw3D Tutorial

StdDraw3D is a Java library that makes it easy to create three-dimensional models, simulations, and games. This tutorial covers basic features—it is aimed at a beginner, with no experience in computer graphics. Here is the complete StdDraw3D reference manual.

This tutorial is oriented toward those familiar with this library's two-dimensional counterpart StdDraw. StdDraw3D strives to match the syntax of StdDraw, but it has a much larger API and many more features.

Installing StdDraw3D.

To ensure that you have the necessary environment for StdDraw3D, run our automatic Java installer for your operating system [ Mac OS X · Windows ]. We do not recommend a manual installation because there are numerous dependencies. Since StdDraw3D is under development so we recommend downloading the latest version of stdlib.jar unless you just ran our automatic installer. For Windows, overwrite the version in

C:\Users\username\introcs\stdlib.jar

For Mac OS X, overwrite the version in

~/Library/Extensions/stdlib.jar

To test that StdDraw3D is installed correctly, type the following from the command line:

% java StdDraw3D

You should see rotating text within two red concentric circles. StdDraw3D is graphics intensive, and may be slow on older computers.

Hello 3D.

Compile and run the program Hello3D.java.

public class Hello3D {
    public static void main(String[] args) {

        // set the scale of the drawing window
        StdDraw3D.setScale(-1,1);

        // draw a sphere of radius 1 centered at (0,0,0)
        StdDraw3D.sphere(0, 0, 0, 1);

        // render to the drawing window
        StdDraw3D.finished();
    }
}

The first command sets the viewable coordinates of the drawing window to between -1 and 1 in all directions. The second command draws a sphere at three-dimensional coordinates (0, 0, 0) with a radius of 1. The third command says that you are done drawing (more on this later). It's that easy—if you run this program, you will see a white sphere in the drawing window.

If you do not, troubleshoot using the Q & A below.

Basic commands.

StdDraw3D supports a wide range of interactive navigation controls and camera modes. Try some basic navigation in the drawing window:

Left-click and drag to orbit around the sphere.
Right-click and drag to pan the view.
Scroll the mouse wheel (or alt-click and drag) to zoom.

StdDraw3D has a black background by default, rather than the white of StdDraw. This is because 3D shading looks much nicer with a black background. You can change the background color the same way as in StdDraw. For example, the command StdDraw3D.clear(StdDraw3D.BLUE) sets the background color to blue before drawing. There are also commands for setting background images and 3D background panoramas.

There are many types of 3D shapes available for drawing in StdDraw3D. Play around with these basic functions—they all take double values as arguments.

StdDraw3D.sphere(x, y, z, radius);
StdDraw3D.cube(x, y, z, radius);
StdDraw3D.box(x, y, z, width, height, depth);
StdDraw3D.cylinder(x, y, z, radius, height);
StdDraw3D.cone(x, y, z, radius, height);
StdDraw3D.ellipsoid(x, y, z, width, height, depth);

All of your shapes so far have been white (the default pen color), but you can change colors with the command StdDraw3D.setPenColor().

StdDraw3D.setPenColor(StdDraw3D.GREEN); // Predefined green color
StdDraw3D.setPenColor(StdDraw3D.RED, int alpha); // Red with transparency (0-255)
StdDraw3D.setPenColor(int r, int g, int b); // RGB values (0-255)
StdDraw3D.setPenColor(Color col); // Color object

The default coordinate scale for the drawing window is from 0 to 1 in all directions. You can set the scale with the command StdDraw3D.setScale(). For example, StdDraw3D.setScale(-100, 100) sets the x-, y-, and z-scale of the window such that you can comfortably view a sphere of radius 100. It is important to define a good scale for your project, because many parameters depend on it. We use the scale (-1, +1) for most of our example programs.

BlueCone.java demonstrates some of these features. It draws a blue cone of radius 0.5 and height 1 at the location (0, 0, 0), on an orange background.

The camera.

So far, the example shapes have been at the location (0, 0, 0), which is the origin of the 3D space you are working with. The three values correspond to the x-, y-, and z-coordinates along the standard Cartesian axes. By drawing shapes in different locations, you will observe that by default positive x is to the right, positive y is upward, and positive z is out of the screen.

In the upper left corner of the drawing window, you will see some text that looks like this:

Position: ( 0.000, 0.000, 2.414 )
Rotation: ( 0,000, 0.000, 0.000 )
Camera: ORBIT_MODE

Imagine that the view you see in the drawing window is the result of a picture taken by a camera. This camera is an abstraction used to control the viewpoint of your project. The listed numbers are the position and rotation of this camera.

The camera position is specified by (x, y, z) coordinates. The rotation is specified by three Euler angles (xAngle, yAngle, zAngle), which are essentially successive angles of rotation about the x-, y-, and z-axes.

When you move around with the interactive controls, you are changing the position and rotation of the camera. You can gain a better understanding by looking at how the numbers change as you play around with the controls.

By default, the camera is centered on the origin and zoomed out on the z-axis enough to have a proper view of the scale you defined. It is easy to change the camera properties.

The easiest way to set the camera position is with the command StdDraw3D.setCameraPosition(x, y, z). It sets the camera position to the three coordinates you specify. To set the rotation of the camera, use the command StdDraw3D.setCameraOrientation(xAngle, yAngle, zAngle). One useful trick is to find a camera angle you like using the interactive controls, and then plug in the displayed numbers into these functions to programatically set that viewpoint.

CameraTest.java is a simple example of setting a custom camera viewpoint. It draws six simple shapes and sets the camera properties.

The camera has numerous advanced features, including multiple modes, animation capabilities, and object-oriented control. For example, setting the camera to First-Person Mode will allow you to use the WASD keys and mouse, as in most computer games. 3D rotations are a very complicated topic, and there are many options included in StdDraw3D. However, what you have just learned is sufficient for most common applications.

Animation.

So far, we have discussed drawing a single scene and showing it by calling StdDraw3D.finished(). StdDraw3D also suppports animations and and user interactions.

If you have used StdDraw, you are familiar with the StdDraw.clear() and StdDraw.show()—StdDraw3D takes a similar approach for producing simple animations.

The function StdDraw3D.show(int milliseconds) displays everything you have drawn to the drawing window, and pauses for a given number of milliseconds.
The function StdDraw3D.clear() erases everything in the drawing window upon the next call of StdDraw3D.show(). Clearing with a color argument sets the background color.
The function StdDraw3D.finished() is equivalent to calling StdDraw3D.show() an infinite number of times. The reason it exists is that because StdDraw3D has interactive controls—we always want the program to be in an infinite loop and never exit. If the program were to exit, then the interactive features would no longer be responsive.

To create animations, you need a loop that uses the pattern of clearing the screen, drawing something, and then showing for a specified amount of time. The standard frame rate of videos is approximately 30 milliseconds per frame.

AnimationTest.java demonstrates the process described above by animating a red sphere to move in a circle.

A more powerful and efficient method of animation is available in StdDraw3D, but that is deferred for the advanced tutorial.

Wireframe shapes.

All of the shape functions you have seen so far have wireframe equivalents—just add the prefix wire. For example, call StdDraw3D.wireSphere(0, 0, 0, 1) instead of StdDraw3D.sphere(0, 0, 0, 1). WireSphere.java draws a wireframe sphere.

Rotated Shapes.

You know how to set the position of drawn shapes, but you can also specify their three dimensional rotation. Just like the camera has three Euler angles to specify it's successive rotation about the x, y, and z axes, so does each shape.

Every shape you have seen so far has overloaded drawing functions that you can use to specify the three rotation angles. For example, use StdDraw3D.cube(x, y, z, radius, xAngle, yAngle, zAngle) to draw a rotated cube. RotationTest.java draws a cone inside a wireframe sphere, and animates them rotating in different directions.

Points, lines, and surfaces.

In addition to 3D solids, you can draw points, lines, and surfaces in 3D space.

StdDraw3D.point(x, y, z) draws a point at the coordinates (x, y, z).
StdDraw3D.line(x1, y1, z1, x2, y2, z2) draws a line from (x1, y1, z1) to (x2, y2, z2).
StdDraw3D.polygon(double[] x, double[] y, double[] z) takes arrays of vertices as input and draws their containing surface.
StdDraw3D.tube(x1, y1, z1, x2, y2, z2, radius) draws a 3D cylindrical tube between the points (x1, y1, z1) and (x2, y2, z2).

In addition, the functions StdDraw3D.points(), StdDraw3D.lines(), and StdDraw3D.triangles() take arrays of points, lines, and mesh surfaces. These methods are much more efficient than individually drawing a large number of individual shapes. Hilbert3D.java draws the following image:

3D text. The command StdDraw3D.text3D(x, y, z, String text) creates 3D text shapes from a given string. For example, Text3D.java produces the following image:

2D overlays.

You can draw 2D overlays on top of the 3D drawing window, to act as an HUD or present informational text. All functions of StdDraw are available under the prefix of StdDraw3D.overlay. For example, to draw an overlaid circle of radius 0.5, use StdDraw3D.overlayCircle(0, 0, 0.5). Overlays do follow the scale set by StdDraw3D.setScale() but do not depend on the camera position or rotation. OverlayText.java provides an example.

The advanced tutorial.

This tutorial covers the basics of StdDraw3D. For interactive animations, large-scale simulations, and games, we recommend the advanced tutorial (under development). The advanced tutorial reintroduces StdDraw3D under these premises:

Every Shape is an object that you can move and rotate without having to redraw.
The Camera is an object that behaves just like a Shape.
Coordinates can be controlled using a Vector3D class rather than scalars.
You do not need to redraw or clear anything to create animations.

The advanced tutorial also covers advanced features, including the following:

Support for easy custom keyboard and mouse controls.
Control of lighting, colored lighting, animated lighting.
Importing 3D models as shapes and animating them.
Combining Shapes to create cascading kinematic transformations.
Camera modes and projection modes.
Easy sound effects.
Creation of custom 3D shapes.

The StdDraw3D reference manual documents and explains every method in StdDraw3D.

Q + A

Q. Whom should I contact if I find a bug or have a question?

A. This tutorial and StdDraw3D were written by Hayk Martirosyan. Feel free to email him at hmartiro@princeton.edu.

Q. Where can I find obj model files?

A. TurboSquid has many free obj models. Note that many of these OBJ files won't show their materials properly because the file format is variable and the Java loader is not very good - they may need tweaking of the "find and replace" style for some commands. Summary: For one color models, everything will work. For models with custom materials and textures, it may take some work.

Q. Why aren't there more questions and answers?

A. This Q + A section is under development.