1 Quick Start

This section is best understood by following along with the examples in DrRacket.

If you get OpenGL errors when using pict3d, try adding (current-pict3d-legacy? #t) to the top of your programs. To make a Pict3D instance containing a single shape, first load the pict3d module, then apply a shape constructor:
> (require pict3d)
> (sphere origin 1/2)


This sphere’s center position is (pos 0 0 0), or the origin, and it has radius 1/2. The red, green and blue bars are not part of the scene. They’re just extra arrows drawn from the origin along the x, y and z axes.

When the mouse hovers over a displayed Pict3D instance, it looks something like this:


If you’re following along in DrRacket, click on it. You can also click and drag to look. “Mouse look” doesn’t work on Mac OS because of reasons. Move the mouse to look around, and use these keys to navigate:
  • W and S (or and ): forwards and backwards

  • A and D (or and ): left and right

  • R and F (or PgUp and PgDn): up and down

If you’re familiar with first-person 3D games, this should feel fairly natural. Click the mouse button again to return control of the keyboard and mouse to DrRacket.

Flying around demonstrates why the axis arrows are necessary. The sphere looks similar from every direction, so it’s easy to get lost. (If you do get lost, press Esc.)

The numbers in the lower right are information about the position and orientation of the closest surface point in space under the mouse cursor. Right-clicking allows you to copy the information to the clipboard.

The image in the upper right shows the scale the Pict3D is rendered at. Clicking on the - and + parts decrease and increase the scale.

The image icon toggles a global grid. The image icon toggles triangle wireframes, which are good for showing tessellations. Clicking the image icon toggles the displayed Pict3D’s default lighting, which is also not part of the scene. Clicking the image icon toggles the origin axes and other indicators. With default lighting off and indicators off, the display looks respectively like

image      image

With both off, the displayed Pict3D looks like this:


The above is the only faithful display, identical to what you get by converting the sphere into a bitmap:
Our Pict3D clearly needs better lighting to communicate its shape. We’ll combine it with a point light source on the x = 0 plane:
> (pict3d->bitmap
   (combine (sphere origin 1/2)
            (light (pos 0 1 1))))


If you evaluate (combine (sphere origin 1/2) (light (pos 0 1 1))) (i.e. without converting to a bitmap) and fly around the scene, you’ll find the point light represented by a glowing octahedron:


If you then click image, the octahedron will disappear, because it’s not part of the scene, either. The light itself is actually invisible.

In general, a Pict3D is comprised of the following kinds of objects.
  • Shapes: visible 2D surfaces in 3D space. Surfaces are visible on only one side.

  • Lights: invisible color emitters.

  • Groups: invisible, named, oriented collections of other objects.

Only one group is special: the one named 'camera. When a Pict3D is renderered, if a group named 'camera exists, that group’s orientation is used as the viewpoint. To look down on our sphere, we can combine it with a downward-oriented camera group:
> (combine (sphere origin 1/2)
           (basis 'camera (point-at (pos 0 0 2) origin)))


The basis function creates an empty group with a given orientation, while (point-at (pos 0 0 2) origin) creates an orientation looking at the origin from the point (pos 0 0 2).

If a 'camera group isn’t in the scene, an orientation is chosen automatically by (current-pict3d-auto-camera).