NAME

       clip - Clip an OOGL object against planes or other surfaces

SYNOPSIS

       clip [-v axisx,y,z,...]
           [-g value-or-point] [-l value-or-point]
           [-s nstrips[,fraction]] [-e]
           [-sph centerx,y,z,...] [-cyl centerx,y,z,...]
           [ooglfile]

DESCRIPTION

       Clip,  adapted  from Daeron Meyer's ginsu module, allows clipping an OOGL object against planes, spheres,
       or cylinders from the UNIX command line.  Its input can come from a file or  standard  input;  output  is
       written to standard output.

       Options  specify a function of space position; the output is the portion of the object where the function
       is greater or less than some given value, or the portion lying between  two  values.   Alternatively,  an
       object  can  be  sliced  into  equally-spaced  strips.  Objects may be of any dimension (but see the BUGS
       section).

       Options are:

       -g value-or-point

       -l value-or-point
              Select the portion of the object where the function is greater than (-g) or  less  than  (-l)  the
              given  value.   If  both  are  specified,  the result is the portion of the object satisfying both
              conditions.

              If, rather than a single number, the argument to -l or -g is a point (a series of x,y,z,... values
              separated by commas, with no embedded blanks), then the clipping surface is  one  chosen  to  pass
              through that point.

       -v axisx,y,z,...
              Specifies  a  direction  in  space.   For  planar  clipping  (the  default), it's the plane normal
              direction; the clipping function is the inner product between the direction vector and  the  point
              on  the  object.  For cylindrical clipping, -v specifies the direction of the cylinder's axis; the
              clipping function is the distance from the axis.

       -sph centerx,y,z,...
              Clip against spheres centered on x,y,z,....  The clipping function is the distance from the  given
              center.  Coordinates must be separated by commas without intervening spaces.

       -cyl centerx,y,z,...
              Clip  against cylinders with an axis passing through centerx,y,z,..., with axis direction given by
              the -v option.  The clipping function is the distance from the axis.

       -s nslices[,fraction]
              Clip an object into a series of nslices ribbons  spanning  its  entire  extent  --  the  range  of
              function-values  over  the object.  Part of each ribbon is omitted; the fraction, default .5, sets
              the width of the visible part of a ribbon compared to the ribbon period.  There  are  a  total  of
              (nslices+fraction-1)  ribbon  periods  across  the  object, so e.g. -s 2,.5 slices the object into
              equal thirds, omitting the middle third.  The output OOGL object  is  a  LIST  of  OFFs,  one  per
              ribbon.

       -e     Don't emit a clipped OOGL object, just print two numbers, listing the minimum and maximum function
              values  for  the object.  If -g or -l clipping options are specified, the object is clipped before
              determining the function range.  If none of the object remains, clip prints "0 0".

EXAMPLES

       To extract the portion of an object lying below the x+y+z=1 plane:

         clip -l 1  -v 1,1,1  file.oogl  > portion.oogl

       To extract the portion of an object lying in the positive octant and below the x+y+z=1 plane, we can pipe
       multiple instances of clip together to find the intersection of several half-spaces:

         clip -g 0  -v 1,0,0 file.oogl | \
            clip -g 0 -v 0,1,0 | \
            clip -g 0 -v 0,0,1 | \
            clip -l 1 -v 1,1,1 > portion.oogl

       To find the region lying between two surfaces (either above one and below the other, or below  the  first
       and above the second), say the planes 2x + y -.5z = 1 and y + 2z = 0:

            echo "{ LIST"
            clip -v 2,1,-.5 -g 1  file.oogl | clip -v 0,1,2 -l 0
            clip -v 2,1,-.5 -l 1  file.oogl | clip -v 0,1,2 -g 0
            echo "}"

       We use pipelines to compute intersections, and a LIST to form their union.

SEE ALSO

       ginsu(1)

BUGS

       Uses  anytooff(1)  to  convert  input data to OFF format internally; this can lose information.  The only
       arbitrary-dimensional form accepted at present is nOFF, not nSKEL or nMESH.  However the four-dimensional
       4OFF, 4QUAD, 4MESH, 4VECT, etc. formats should work.

       Clip really only clips edges.  If a curved clipping surface cuts  an  edge  twice,  or  removes  only  an
       interior  portion  of  some polygon, clip misses it entirely.  Clipping against a curved surface yields a
       straight edge (a chord of the ideal curved edge segment).  This latter failing might be fixed someday.

Geometry Center                                 23 November 1994                                       CLIP(1gv)