Geomview Manual - INST

Go to the first, previous, next, last section, table of contents.

### INST Files

The conventional suffix for a `INST` file is ``.inst'`.

There is no INST BINARY format.

An `INST` applies a 4x4 transformation to another OOGL object. It begins with `INST` followed by these sections which may appear in any order:

    geom oogl-object

specifies the OOGL object to be instantiated. See section Embedded objects and external-object references, for the syntax of an oogl-object. The keyword `unit` is a synonym for `geom`.

    transform   ["{"] 4x4 transform ["}"]

specifies a single transformation matrix. Either the matrix may appear literally as 16 numbers, or there may be a reference to a "transform" object, i.e.

        "<" file-containing-4x4-matrix

or

        ":" symbol-representing-transform-object>

Another way to specify the transformation is

    transforms
        oogl-object

The oogl-object must be a `TLIST` object (list of transformations) object, or a `LIST` whose members are ultimately `TLIST` objects. In effect, the `transforms` keyword takes a collection of 4x4 matrices and replicates the `geom` object, making one copy for each 4x4 matrix.

If no `transform` nor `transforms` keyword appears, no transformation is applied (actually the identity is applied). You could use this for, e.g., wrapping an appearance around an externally-supplied object, though a single-membered LIST would do this more efficiently.

See section Transformation matrices, for the matrix format.

Two more INST fields are accepted: `location` and `origin`.

    location [global or camera or ndc or screen or local]

Normally an INST specifies a position relative to its parent object; the `location` field allows putting an object elsewhere.

- `location global` attaches the object to the global (a.k.a. universe) coordinate system -- the same as that in which geomview's World objects, alien geometry, and cameras are placed.
- `location camera` places the object relative to the camera. (Thus if there are multiple views, it may appear in a different spatial position in each view.) The center of the camera's view is along its negative Z axis; positive X is rightward, positive Y upward. Normally the units of camera space are the same as global coordinates. When a camera is reset, the global origin is at (0,0,-3.0).
- `location ndc` places the object relative to the normalized unit cube into which the camera's projection (perspective or orthographic) maps the visible world. X, Y, and Z are each in the range from -1 to +1, with Z = -1 the near and Z = +1 the far clipping plane, and X and Y increasing rightward and upward respectively. Thus something like

      INST  transform  1 0 0 0  0 1 0 0  0 0 1 0  -.9 -.9 -.999 1
            location ndc
            geom < label.vect

  pastes `label.vect` onto the lower left corner of each window, and in front of nearly everything else, assuming `label.vect`'s contents lie in the positive quadrant of the X-Y plane. It's tempting to use -1 rather than -.999 as the Z component of the position, but that may put the object just nearer than the near clipping plane and make it (partially) invisible, due to floating-point error.
- `location screen` places the object in screen coordinates. The range of Z is still -1 through +1 as for ndc coordinates; X and Y are measured in pixels, and range from (0,0) at the lower left corner of the window, increasing rightward and upward.

`location local` is the default; the object is positioned relative to its parent.

    origin [global or camera or ndc or screen or local] x y z

The `origin` field translates the contents of the INST to place the origin at the specified point of the given coordinate system. Unlike `location`, it doesn't change the orientation, only the choice of origin. Both `location` and `origin` can be used together.

So for example

    { INST
      location screen
      origin ndc 0 0 -.99
      geom { < xyz.vect }
      transform { 100 0 0 0  0 100 0 0  0 0 -.009 0   0 0 0 1 }
    }

places xyz.vect's origin in the center of the window, just beyond the near clipping plane. The unit-length X and Y edges are scaled to be just 100 screen units -- pixels -- long, regardless of the size of the window.

- INST Examples: Some example of `INST` Files.

Go to the first, previous, next, last section, table of contents.