This document is a very brief introduction to some of the simpler modeling ideas in the Jabka 3D computer graphics system, and gives brief instructions on getting started with Jabka in a Unix/X-Windows environment. If you are working in a Macintosh environment click here to get the appropriate documentation.

Customizing your Unix Environment

Programming and Running Jabka

Predefined Geometric Objects

Predefined Materials and Colors

Describing a Geometric Model

Geometric Transformations

Specifying the Scene to be Viewed

Viewing the Model

Customizing Your Unix Environment

Before using Jabka, the environment variables JABKAPATH, PATH, and SAVEPATH should be defined. These determine where Jabka will search to find files, and where it will write them when a write request is made. For example, an entry in your .login file

will cause jabka to search in the directorys /u/yourname/jabka, and /u/yourname/jabka/models to satisfy a file read request. The order in which directories are searched is indicated below. The search proceeds until either the file is found, or all directories have been examined, and no such file is found.

1. look in current working directory
2. look in directory in which last requested file was found (if any)
3. look in directories in JABKAPATH, in order
4. look in directories in PATH, in order

When you request a save to a file, the environment variable SAVEPATH is used, if defined. The logic followed when saving a file for which a full pathname is not given is

1. try the directory pointed to by SAVEPATH (if defined)
2. try directory from which last requested file access was done (if any).

Your PATH variable should contain an entry pointing to the location of the jabka executable binary, which in a typical installation will also contain Jabka's startup file jabkadefs.scm. Ask your system administrator for the necessary paths if you do not know them.

There are two ways to run Jabka: directly under a unix shell, or as a subprocess under emacs. If you are an emacs user, you will find the emacs environment very convenient. In order to get access to Jabka under emacs, your .emacs file must be modified to tell emacs to configure itself to run jabka.

Once your environment is properly configured, you need only type jabka to start up Jabka under a shell, or M-x run-jabka to start up Jabka under emacs. Jabka looks to the user like an interpreter for the scheme programming language (a dialect of the language Lisp). If you are used to running Lisp or scheme under emacs, the emacs interface will seem quite natural, although there are no fancy debugging facilites.

Programming and Running Jabka

What you do when you run Jabka is to simply write a list of commands (i.e. a program), in Jabka's dialect of the Scheme programming language, that describe a geometric model and provide other information on how images of the model should be rendered. You can enter and execute the commands in the program interactively, but for anything complex you will want to type the program into a file, and then tell Jabka to execute the commands in the file. Within emacs, you simply split the screen and use a second buffer to enter and edit the program, and then use the command M-o to send the program buffer to Jabka. If you are running Jabka under a Unix shell, you edit and save the file, and then issue the command

to Jabka to cause it to read the file and execute its contents. Look at the following example Jabka program, which makes a cone-shaped tree on a circular base.

;----------------- Jabka Scheme Program to Create a -----------------

;---------------- Cone Shaped Tree on Circular Base -----------------

;------------------------ Donald H. House ---------------------------


(object branches part
        (addchild cone)
        (setmaterial green-plaster))

(object trunk part
        (addchild cylinder (scale 0.1 0.3 0.1))
        (setmaterial yellow-plaster))

(object tree part
        (addchild branches)
        (addchild trunk (translate 0 -110 0)))

(object base part
        (addchild cylinder (scale 3 0.05 3))
        (setmaterial red-plaster))

(object scene part
       (addchild tree)
       (addchild base (translate 0 -135 0)))

You should try entering and executing this program to make sure that you know how to use Jabka. Aspects of this example are elaborated in the discussion below. Once you have successfully run this program, the command

should cause Jabka to display a wireframe version of the tree.

Predefined Geometric Objects

Jabka knows about a small collection of geometric objects. These are predefined as either polygonal surfaces, or quadrics. All of these objects are sized so that they fit exactly within a 200 x 200 x 200 cubic volume centered at the origin. In other words, their maximum extents along each of the three coordinate axes are +100 and -100.

• cube A 200 x 200 x 200 cube.
• cylinder A cylinder with height 200, and radius 100, and aligned along the y axis.
• pyramid A pyramid with a 200 x 200 square base whose diagonals are aligned along the x and z axes, height 200, and whose apex is at (0, 100, 0).
• cone A cone with a base of radius 100, height 200, and aligned along the y axis so that its apex is at (0, 100, 0).
• sphere A sphere of radius 100.
• paraboloid A nosecone shaped object oriented and sized like the cone.

Predefined Materials and Colors

All geometric objects have surface properties, like color, that are determined by the material from which the object is made. Later, you will learn how to make virtually any color and/or material you want, but for now we will stick with materials of a few predefined colors and whose surface properties are like plaster (i.e. a matte finish). The predefined colors are red, yellow, green, cyan, blue, magenta, and the greys black, dkgrey, grey, ltgrey, and white. For each of these colors, there is a corresponding plaster-like material named, respectively, red-plaster, yellow-plaster, green-plaster, cyan-plaster, blue-plaster, magenta-plaster, black-plaster, dkgrey-plaster, grey-plaster, ltgrey-plaster, and white-plaster.

Describing a Geometric Model

A geometric model is made from part and primitive objects, attached to each other in a heirarchy. The primitive objects actually describe surfaces, whereas the part objects are simply internal nodes in the heirarchy. The only kinds of primitives we will deal with for a while are polysurface, and quadric. A part object is created by the command:

where name is a unique name you supply for the part, and messages is a group of methods (or commands) you use to further specify the part. For example, one method is setmaterial, as used in the message (setmaterial mat), where mat is a material. Another important method for a part is addchild, as used in (addchild child transform), where child is the name of a part or primitive object that is to be added to the part, and transform (which is optional) is a geometric transform that determines the spatial orientation and scaling of the child within the part. Addchild automatically connects the child to the part. For example:

(object trunk part
        (addchild cylinder (scale 0.1 0.3 0.1))
        (setmaterial yellow-plaster))

creates a part named trunk that consists of a cylinder. The method setmaterial in the example is used to define the material from which the object is made. In the example, the material for trunk is the predefined material yellow-plaster.

Geometric Transformations

The standard geometric transformations of translate, rotate, and scale, as well as the identity transform, are available. These transforms are created by the functions:

• (translate x y z) A transformation-function that moves an object in 3-space by the offsets specified by x, y, and z. This is the basic function for changing the position or placement of objects. example: (translate 100 0 0)
  
• (x-rot angle)
• (y-rot angle)
• (z-rot angle) These are transformation-functions that specify a rotation of angle degrees around the indicated axis . The left-hand rule determines the direction of positive rotation. example: (y-rot 180)
  
• (scale x y z) A transformation-function which specifies that an object is to be scaled by the multipliers x, y, and z. example: (scale 0.5 0.5 0.5 ) would shrink an object by half equally along all axes. example: (scale 2 1 1) would stretch an object to double its size in the x dimension only, leaving the other dimensions unchanged.
  
• (identity) The identity transform. The identity transform is handy in a few cases when you are required to provide a transform, but you don't want the transform to do anything.

Specifying the Scene to be Viewed

Jabka's predefined (or default) camera expects to find a part named scene at which it is directed. In order to create an object named scene and add objects to it to be viewed, simply create the part, and use the addchild method as in the example:

(object scene part
       (addchild tree)
       (addchild base (translate 0 -135 0)))

Viewing the Model

The program you write to define a model is only a description. As explained above, you must tell Jabka to "evaluate" your program, so that it will actually build the model that you have described. You do this using the load command under a shell, or M-o under emacs. Either of these commands tells Jabka to read your entire program and evalute it. If the evaluation proceeds without errors, your model will have been been created. To display the model, you can ``tell'' Jabka's default camera to give you a wireframe preview with the command

or to make a color shaded image with

The camera's position can be adjusted using the camera's raise, pan, and approach methods. These methods use an orbital model of camera control, with the camera fixed to aim at its center of interest. The COI is at the origin by default. Raise and pan accept a single angular parameter in degrees, and approach accepts a percent zoom. Raise causes the camera to orbit around the COI in its ``up'' direction. Pan causes it to orbit to its right, and approach causes it to translate towards the COI. For example,

will cause the camera to orbit up by 30 degrees, and then counter-clockwise by 15 degrees.

An alternative to the approach method is zoom. Zoom simulates a zoom lens on a real camera by adjusting the size of the camera's virtual screen. Zoom accepts a single parameter which is a percentage, similar to approach. A positive percentage makes the screen smaller, thus zooming in, and a negative percentage does the opposite.